Home/Flow Go SDK
Updated: 2022/8/10 byjoekrilljoekrill
23 min read

Overview

This reference documents all the methods available in the SDK, and explains in detail how these methods work. SDKs are open source, and you can use them according to the licence.

The library client specifications can be found here:

Getting Started

Installing

The recommended way to install Go Flow SDK is by using Go modules.

If you already initialized your Go project, you can run the following command in your terminal:

1
go get github.com/onflow/flow-go-sdk

It's usually good practice to pin your dependencies to a specific version. Refer to the SDK releases page to identify the latest version.

Importing the Library

After the library has been installed you can import it.

1
import "github.com/onflow/flow-go-sdk"

Connect

The Go SDK library uses HTTP or gRPC APIs to communicate with the access nodes and it must be configured with correct access node API URL. The library provides default factories for connecting to Flow AN APIs and you can easily switch between HTTP or gRPC if you use the provided client interface.

You can check more examples for creating clients in the examples:

Basic Example:

1
// common client interface
2
var flowClient client.Client
3


4
// initialize an http emulator client
5
flowClient, err := http.NewClient(http.EmulatorHost)
6


7
// initialize a gPRC emulator client
8
flowClient, err = grpc.NewClient(grpc.EmulatorHost)

You can also initialize an HTTP client or gRPC client directly which will offer you access to network specific options, but be aware you won't be able to easily switch between those since they don't implement a common interface. This is only advisable if the implementation needs the access to those advanced options. Advanced Example:

1
// initialize http specific client
2
httpClient, err := http.NewHTTPClient(http.EMULATOR_URL)
3


4
// initialize grpc specific client
5
grpcClient, err := grpc.NewGRPCClient(
6
    grpc.EMULATOR_URL,
7
    grpcOpts.WithTransportCredentials(insecure.NewCredentials()),
8
)

Querying the Flow Network

After you have established a connection with an access node, you can query the Flow network to retrieve data about blocks, accounts, events and transactions. We will explore how to retrieve each of these entities in the sections below.

Get Blocks

Query the network for block by id, height or get the latest block.

📖 Block ID is SHA3-256 hash of the entire block payload. This hash is stored as an ID field on any block response object (ie. response from GetLatestBlock).

📖 Block height expresses the height of the block on the chain. The latest block height increases by one for every valid block produced.

Examples

This example depicts ways to get the latest block as well as any other block by height or ID:

1
func demo() {
2
    ctx := context.Background()
3
    flowClient := examples.NewFlowClient()
4


5
    // get the latest sealed block
6
    isSealed := true
7
    latestBlock, err := flowClient.GetLatestBlock(ctx, isSealed)
8
    printBlock(latestBlock, err)
9


10
    // get the block by ID
11
    blockID := latestBlock.ID.String()
12
    blockByID, err := flowClient.GetBlockByID(ctx, flow.HexToID(blockID))
13
    printBlock(blockByID, err)
14


15
    // get block by height
16
    blockByHeight, err := flowClient.GetBlockByHeight(ctx, 0)
17
    printBlock(blockByHeight, err)
18
}
19


20
func printBlock(block *flow.Block, err error) {
21
    examples.Handle(err)
22


23
    fmt.Printf("\nID: %s\n", block.ID)
24
    fmt.Printf("height: %d\n", block.Height)
25
    fmt.Printf("timestamp: %s\n\n", block.Timestamp)
26
}

Result output:

1
ID: 835dc83939141097aa4297aa6cf69fc600863e3b5f9241a0d7feac1868adfa4f
2
height: 10
3
timestamp: 2021-10-06 15:06:07.105382 +0000 UTC
4


5


6
ID: 835dc83939141097aa4297aa6cf69fc600863e3b5f9241a0d7feac1868adfa4f
7
height: 10
8
timestamp: 2021-10-06 15:06:07.105382 +0000 UTC
9


10


11
ID: 7bc42fe85d32ca513769a74f97f7e1a7bad6c9407f0d934c2aa645ef9cf613c7
12
height: 0
13
timestamp: 2018-12-19 22:32:30.000000042 +0000 UTC

Get Account

Retrieve any account from Flow network's latest block or from a specified block height. The GetAccount method is actually an alias for the get account at latest block method.

📖 Account address is a unique account identifier. Be mindful about the 0x prefix, you should use the prefix as a default representation but be careful and safely handle user inputs without the prefix.

An account includes the following data:

  • Address: the account address.
  • Balance: balance of the account.
  • Contracts: list of contracts deployed to the account.
  • Keys: list of keys associated with the account.

Examples

Example depicts ways to get an account at the latest block and at a specific block height:

1
func demo() {
2
    ctx := context.Background()
3
    flowClient := examples.NewFlowClient()
4


5
    // get account from the latest block
6
    address := flow.HexToAddress("f8d6e0586b0a20c7")
7
    account, err := flowClient.GetAccount(ctx, address)
8
    printAccount(account, err)
9


10
    // get account from the block by height 0
11
    account, err = flowClient.GetAccountAtBlockHeight(ctx, address, 0)
12
    printAccount(account, err)
13
}
14


15
func printAccount(account *flow.Account, err error) {
16
    examples.Handle(err)
17


18
    fmt.Printf("\nAddress: %s", account.Address.String())
19
    fmt.Printf("\nBalance: %d", account.Balance)
20
    fmt.Printf("\nContracts: %d", len(account.Contracts))
21
    fmt.Printf("\nKeys: %d\n", len(account.Keys))
22
}

Result output:

1
Address: f8d6e0586b0a20c7
2
Balance: 999999999999600000
3
Contracts: 2
4
Keys: 1
5


6
Address: f8d6e0586b0a20c7
7
Balance: 999999999999600000
8
Contracts: 2
9
Keys: 1

Get Transactions

Retrieve transactions from the network by providing a transaction ID. After a transaction has been submitted, you can also get the transaction result to check the status.

📖 Transaction ID is a hash of the encoded transaction payload and can be calculated before submitting the transaction to the network.

⚠️ The transaction ID provided must be from the current spork.

📖 Transaction status represents the state of transaction in the blockchain. Status can change until is finalized.

StatusFinalDescription
UNKNOWN❌The transaction has not yet been seen by the network
PENDING❌The transaction has not yet been included in a block
FINALIZED❌The transaction has been included in a block
EXECUTED❌The transaction has been executed but the result has not yet been sealed
SEALED✅The transaction has been executed and the result is sealed in a block
EXPIRED✅The transaction reference block is outdated before being executed

1
func demo(txID flow.Identifier) {
2
    ctx := context.Background()
3
    flowClient := examples.NewFlowClient()
4


5
    tx, err := flowClient.GetTransaction(ctx, txID)
6
    printTransaction(tx, err)
7


8
    txr, err := flowClient.GetTransactionResult(ctx, txID)
9
    printTransactionResult(txr, err)
10
}
11


12
func printTransaction(tx *flow.Transaction, err error) {
13
    examples.Handle(err)
14


15
    fmt.Printf("\nID: %s", tx.ID().String())
16
    fmt.Printf("\nPayer: %s", tx.Payer.String())
17
    fmt.Printf("\nProposer: %s", tx.ProposalKey.Address.String())
18
    fmt.Printf("\nAuthorizers: %s", tx.Authorizers)
19
}
20


21
func printTransactionResult(txr *flow.TransactionResult, err error) {
22
    examples.Handle(err)
23


24
    fmt.Printf("\nStatus: %s", txr.Status.String())
25
    fmt.Printf("\nError: %v", txr.Error)
26
}

Example output:

1
ID: fb1272c57cdad79acf2fcf37576d82bf760e3008de66aa32a900c8cd16174e1c
2
Payer: f8d6e0586b0a20c7
3
Proposer: f8d6e0586b0a20c7
4
Authorizers: []
5
Status: SEALED
6
Error: <nil>

Get Events

Retrieve events by a given type in a specified block height range or through a list of block IDs.

📖 Event type is a string that follow a standard format:

1
A.{contract address}.{contract name}.{event name}

Please read more about events in the documentation. The exception to this standard are core events, and you should read more about them in this document.

📖 Block height range expresses the height of the start and end block in the chain.

Examples

Example depicts ways to get events within block range or by block IDs:

1
func demo(deployedContract *flow.Account, runScriptTx *flow.Transaction) {
2
    ctx := context.Background()
3
    flowClient := examples.NewFlowClient()
4


5
    // Query for account creation events by type
6
    result, err := flowClient.GetEventsForHeightRange(ctx, "flow.AccountCreated", 0, 30)
7
    printEvents(result, err)
8


9
    // Query for our custom event by type
10
    customType := fmt.Sprintf("AC.%s.EventDemo.EventDemo.Add", deployedContract.Address.Hex())
11
    result, err = flowClient.GetEventsForHeightRange(ctx, customType, 0, 10)
12
    printEvents(result, err)
13


14
    // Get events directly from transaction result
15
    txResult, err := flowClient.GetTransactionResult(ctx, runScriptTx.ID())
16
    examples.Handle(err)
17
    printEvent(txResult.Events)
18
}
19


20
func printEvents(result []client.BlockEvents, err error) {
21
    examples.Handle(err)
22


23
    for _, block := range result {
24
        printEvent(block.Events)
25
    }
26
}
27


28
func printEvent(events []flow.Event) {
29
    for _, event := range events {
30
        fmt.Printf("\n\nType: %s", event.Type)
31
        fmt.Printf("\nValues: %v", event.Value)
32
        fmt.Printf("\nTransaction ID: %s", event.TransactionID)
33
    }
34
}

Example output:

1
Type: flow.AccountCreated
2
Values: flow.AccountCreated(address: 0xfd43f9148d4b725d)
3
Transaction ID: ba9d53c8dcb0f9c2f854f93da8467a22d053eab0c540bde0b9ca2f7ad95eb78e
4


5
Type: flow.AccountCreated
6
Values: flow.AccountCreated(address: 0xeb179c27144f783c)
7
Transaction ID: 8ab7bfef3de1cf8b2ffb36559446100bf4129a9aa88d6bc59f72a467acf0c801
8


9
...
10


11
Type: A.eb179c27144f783c.EventDemo.Add
12
Values: A.eb179c27144f783c.EventDemo.Add(x: 2, y: 3, sum: 5)
13
Transaction ID: f3a2e33687ad23b0e02644ebbdcd74a7cd8ea7214065410a8007811d0bcbd353

Get Collections

Retrieve a batch of transactions that have been included in the same block, known as collections. Collections are used to improve consensus throughput by increasing the number of transactions per block and they act as a link between a block and a transaction.

📖 Collection ID is SHA3-256 hash of the collection payload.

Example retrieving a collection:

1
func demo(exampleCollectionID flow.Identifier) {
2
    ctx := context.Background()
3
    flowClient := examples.NewFlowClient()
4


5
    // get collection by ID
6
    collection, err := flowClient.GetCollection(ctx, exampleCollectionID)
7
    printCollection(collection, err)
8
}
9


10
func printCollection(collection *flow.Collection, err error) {
11
    examples.Handle(err)
12


13
    fmt.Printf("\nID: %s", collection.ID().String())
14
    fmt.Printf("\nTransactions: %s", collection.TransactionIDs)
15
}

Example output:

1
ID: 3d7b8037381f2497d83f2f9e09422c036aae2a59d01a7693fb6003b4d0bc3595
2
Transactions: [cf1184e3de4bd9a7232ca3d0b9dd2cfbf96c97888298b81a05c086451fa52ec1]

Execute Scripts

Scripts allow you to write arbitrary non-mutating Cadence code on the Flow blockchain and return data. You can learn more about Cadence and scripts here, but we are now only interested in executing the script code and getting back the data.

We can execute a script using the latest state of the Flow blockchain or we can choose to execute the script at a specific time in history defined by a block height or block ID.

📖 Block ID is SHA3-256 hash of the entire block payload, but you can get that value from the block response properties.

📖 Block height expresses the height of the block in the chain.

1
func demo() {
2
    ctx := context.Background()
3
    flowClient := examples.NewFlowClient()
4


5
    script := []byte(`
6
        pub fun main(a: Int): Int {
7
            return a + 10
8
        }
9
    `)
10
    args := []cadence.Value{ cadence.NewInt(5) }
11
    value, err := flowClient.ExecuteScriptAtLatestBlock(ctx, script, args)
12


13
    examples.Handle(err)
14
    fmt.Printf("\nValue: %s", value.String())
15


16
    complexScript := []byte(`
17
        pub struct User {
18
            pub var balance: UFix64
19
            pub var address: Address
20
            pub var name: String
21


22
            init(name: String, address: Address, balance: UFix64) {
23
                self.name = name
24
                self.address = address
25
                self.balance = balance
26
            }
27
        }
28


29
        pub fun main(name: String): User {
30
            return User(
31
                name: name,
32
                address: 0x1,
33
                balance: 10.0
34
            )
35
        }
36
    `)
37
    args = []cadence.Value{ cadence.NewString("Dete") }
38
    value, err = flowClient.ExecuteScriptAtLatestBlock(ctx, complexScript, args)
39
    printComplexScript(value, err)
40
}
41


42
type User struct {
43
	balance uint64
44
	address flow.Address
45
	name string
46
}
47


48
func printComplexScript(value cadence.Value, err error) {
49
    examples.Handle(err)
50
    fmt.Printf("\nString value: %s", value.String())
51


52
    s := value.(cadence.Struct)
53
    u := User{
54
        balance: s.Fields[0].ToGoValue().(uint64),
55
        address: s.Fields[1].ToGoValue().([flow.AddressLength]byte),
56
        name:    s.Fields[2].ToGoValue().(string),
57
    }
58


59
    fmt.Printf("\nName: %s", u.name)
60
    fmt.Printf("\nAddress: %s", u.address.String())
61
    fmt.Printf("\nBalance: %d", u.balance)
62
}

Example output:

1
Value: 15
2
String value: s.34a17571e1505cf6770e6ef16ca387e345e9d54d71909f23a7ec0d671cd2faf5.User(balance: 10.00000000, address: 0x1, name: "Dete")
3
Name: Dete
4
Address: 0000000000000001
5
Balance: 1000000000

Mutate Flow Network

Flow, like most blockchains, allows anybody to submit a transaction that mutates the shared global chain state. A transaction is an object that holds a payload, which describes the state mutation, and one or more authorizations that permit the transaction to mutate the state owned by specific accounts.

Transaction data is composed and signed with help of the SDK. The signed payload of transaction then gets submitted to the access node API. If a transaction is invalid or the correct number of authorizing signatures are not provided, it gets rejected.

Executing a transaction requires couple of steps:

Transactions

A transaction is nothing more than a signed set of data that includes script code which are instructions on how to mutate the network state and properties that define and limit it's execution. All these properties are explained bellow.

📖 Script field is the portion of the transaction that describes the state mutation logic. On Flow, transaction logic is written in Cadence. Here is an example transaction script:

1
transaction(greeting: String) {
2
  execute {
3
    log(greeting.concat(", World!"))
4
  }
5
}

📖 Arguments. A transaction can accept zero or more arguments that are passed into the Cadence script. The arguments on the transaction must match the number and order declared in the Cadence script. Sample script from above accepts a single String argument.

📖 Proposal key must be provided to act as a sequence number and prevent reply and other potential attacks.

Each account key maintains a separate transaction sequence counter; the key that lends its sequence number to a transaction is called the proposal key.

A proposal key contains three fields:

  • Account address
  • Key index
  • Sequence number

A transaction is only valid if its declared sequence number matches the current on-chain sequence number for that key. The sequence number increments by one after the transaction is executed.

📖 Payer is the account that pays the fees for the transaction. A transaction must specify exactly one payer. The payer is only responsible for paying the network and gas fees; the transaction is not authorized to access resources or code stored in the payer account.

📖 Authorizers are accounts that authorize a transaction to read and mutate their resources. A transaction can specify zero or more authorizers, depending on how many accounts the transaction needs to access.

The number of authorizers on the transaction must match the number of AuthAccount parameters declared in the prepare statement of the Cadence script.

Example transaction with multiple authorizers:

1
transaction {
2
  prepare(authorizer1: AuthAccount, authorizer2: AuthAccount) { }
3
}

📖 Gas limit is the limit on the amount of computation a transaction requires, and it will abort if it exceeds its gas limit. Cadence uses metering to measure the number of operations per transaction. You can read more about it in the Cadence documentation.

The gas limit depends on the complexity of the transaction script. Until dedicated gas estimation tooling exists, it's best to use the emulator to test complex transactions and determine a safe limit.

📖 Reference block specifies an expiration window (measured in blocks) during which a transaction is considered valid by the network. A transaction will be rejected if it is submitted past its expiry block. Flow calculates transaction expiry using the reference block field on a transaction. A transaction expires after 600 blocks are committed on top of the reference block, which takes about 10 minutes at average Mainnet block rates.

Build Transactions

Building a transaction involves setting the required properties explained above and producing a transaction object.

Here we define a simple transaction script that will be used to execute on the network and serve as a good learning example.

1
transaction(greeting: String) {
2


3
  let guest: Address
4


5
  prepare(authorizer: AuthAccount) {
6
    self.guest = authorizer.address
7
  }
8


9
  execute {
10
    log(greeting.concat(",").concat(self.guest.toString()))
11
  }
12
}

1
import (
2
  "context"
3
  "ioutil"
4
  "github.com/onflow/flow-go-sdk"
5
  "github.com/onflow/flow-go-sdk/client"
6
)
7


8
func main() {
9


10
  greeting, err := outil.ReadFile("Greeting2.cdc")
11
  if err != nil {
12
    panic("failed to load Cadence script")
13
  }
14


15
  proposerAddress := flow.HexToAddress("9a0766d93b6608b7")
16
  proposerKeyIndex := 3
17


18
  payerAddress := flow.HexToAddress("631e88ae7f1d7c20")
19
  authorizerAddress := flow.HexToAddress("7aad92e5a0715d21")
20


21
  var accessAPIHost string
22


23
  // Establish a connection with an access node
24
  flowClient := examples.NewFlowClient()
25


26
  // Get the latest sealed block to use as a reference block
27
  latestBlock, err := flowClient.GetLatestBlockHeader(context.Background(), true)
28
  if err != nil {
29
    panic("failed to fetch latest block")
30
  }
31


32
  // Get the latest account info for this address
33
  proposerAccount, err := flowClient.GetAccountAtLatestBlock(context.Background(), proposerAddress)
34
  if err != nil {
35
    panic("failed to fetch proposer account")
36
  }
37


38
  // Get the latest sequence number for this key
39
  sequenceNumber := proposerAccount.Keys[proposerKeyIndex].SequenceNumber
40


41
  tx := flow.NewTransaction().
42
    SetScript(greeting).
43
    SetGasLimit(100).
44
    SetReferenceBlockID(latestBlock.ID).
45
    SetProposalKey(proposerAddress, proposerKeyIndex, sequenceNumber).
46
    SetPayer(payerAddress).
47
    AddAuthorizer(authorizerAddress)
48


49
  // Add arguments last
50


51
  hello := cadence.NewString("Hello")
52


53
  err = tx.AddArgument(hello)
54
  if err != nil {
55
    panic("invalid argument")
56
  }
57
}

After you have successfully built a transaction the next step in the process is to sign it.

Sign Transactions

Flow introduces new concepts that allow for more flexibility when creating and signing transactions. Before trying the examples below, we recommend that you read through the transaction signature documentation.

After you have successfully built a transaction the next step in the process is to sign it. Flow transactions have envelope and payload signatures, and you should learn about each in the signature documentation.

Quick example of building a transaction:

1
import (
2
    "github.com/onflow/flow-go-sdk"
3
    "github.com/onflow/flow-go-sdk/crypto"
4
)
5


6
var (
7
    myAddress    flow.Address
8
    myAccountKey flow.AccountKey
9
    myPrivateKey crypto.PrivateKey
10
)
11


12
tx := flow.NewTransaction().
13
    SetScript([]byte("transaction { execute { log(\"Hello, World!\") } }")).
14
    SetGasLimit(100).
15
    SetProposalKey(myAddress, myAccountKey.Index, myAccountKey.SequenceNumber).
16
    SetPayer(myAddress)

Transaction signing is done through the crypto.Signer interface. The simplest (and least secure) implementation of crypto.Signer is crypto.InMemorySigner.

Signatures can be generated more securely using keys stored in a hardware device such as an HSM. The crypto.Signer interface is intended to be flexible enough to support a variety of signer implementations and is not limited to in-memory implementations.

Simple signature example:

1
// construct a signer from your private key and configured hash algorithm
2
mySigner, err := crypto.NewInMemorySigner(myPrivateKey, myAccountKey.HashAlgo)
3
if err != nil {
4
    panic("failed to create a signer")
5
}
6


7
err = tx.SignEnvelope(myAddress, myAccountKey.Index, mySigner)
8
if err != nil {
9
    panic("failed to sign transaction")
10
}

Flow supports great flexibility when it comes to transaction signing, we can define multiple authorizers (multi-sig transactions) and have different payer account than proposer. We will explore advanced signing scenarios bellow.

Single party, single signature

  • Proposer, payer and authorizer are the same account (0x01).
  • Only the envelope must be signed.
  • Proposal key must have full signing weight.
AccountKey IDWeight
0x0111000

1
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
2


3
key1 := account1.Keys[0]
4


5
// create signer from securely-stored private key
6
key1Signer := getSignerForKey1()
7


8
referenceBlock, _ := flow.GetLatestBlock(ctx, true)
9
tx := flow.NewTransaction().
10
    SetScript([]byte(`
11
        transaction {
12
            prepare(signer: AuthAccount) { log(signer.address) }
13
        }
14
    `)).
15
    SetGasLimit(100).
16
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
17
    SetReferenceBlockID(referenceBlock.ID).
18
    SetPayer(account1.Address).
19
    AddAuthorizer(account1.Address)
20


21
// account 1 signs the envelope with key 1
22
err := tx.SignEnvelope(account1.Address, key1.Index, key1Signer)

Single party, multiple signatures

  • Proposer, payer and authorizer are the same account (0x01).
  • Only the envelope must be signed.
  • Each key has weight 500, so two signatures are required.
AccountKey IDWeight
0x011500
0x012500

1
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
2


3
key1 := account1.Keys[0]
4
key2 := account1.Keys[1]
5


6
// create signers from securely-stored private keys
7
key1Signer := getSignerForKey1()
8
key2Signer := getSignerForKey2()
9


10
referenceBlock, _ := flow.GetLatestBlock(ctx, true)
11
tx := flow.NewTransaction().
12
    SetScript([]byte(`
13
        transaction {
14
            prepare(signer: AuthAccount) { log(signer.address) }
15
        }
16
    `)).
17
    SetGasLimit(100).
18
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
19
    SetReferenceBlockID(referenceBlock.ID).
20
    SetPayer(account1.Address).
21
    AddAuthorizer(account1.Address)
22


23
// account 1 signs the envelope with key 1
24
err := tx.SignEnvelope(account1.Address, key1.Index, key1Signer)
25


26
// account 1 signs the envelope with key 2
27
err = tx.SignEnvelope(account1.Address, key2.Index, key2Signer)

Multiple parties

  • Proposer and authorizer are the same account (0x01).
  • Payer is a separate account (0x02).
  • Account 0x01 signs the payload.
  • Account 0x02 signs the envelope.
    • Account 0x02 must sign last since it is the payer.
AccountKey IDWeight
0x0111000
0x0231000

1
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
2
account2, _ := c.GetAccount(ctx, flow.HexToAddress("02"))
3


4
key1 := account1.Keys[0]
5
key3 := account2.Keys[0]
6


7
// create signers from securely-stored private keys
8
key1Signer := getSignerForKey1()
9
key3Signer := getSignerForKey3()
10


11
referenceBlock, _ := flow.GetLatestBlock(ctx, true)
12
tx := flow.NewTransaction().
13
    SetScript([]byte(`
14
        transaction {
15
            prepare(signer: AuthAccount) { log(signer.address) }
16
        }
17
    `)).
18
    SetGasLimit(100).
19
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
20
    SetReferenceBlockID(referenceBlock.ID).
21
    SetPayer(account2.Address).
22
    AddAuthorizer(account1.Address)
23


24
// account 1 signs the payload with key 1
25
err := tx.SignPayload(account1.Address, key1.Index, key1Signer)
26


27
// account 2 signs the envelope with key 3
28
// note: payer always signs last
29
err = tx.SignEnvelope(account2.Address, key3.Index, key3Signer)

Multiple parties, two authorizers

  • Proposer and authorizer are the same account (0x01).
  • Payer is a separate account (0x02).
  • Account 0x01 signs the payload.
  • Account 0x02 signs the envelope.
    • Account 0x02 must sign last since it is the payer.
  • Account 0x02 is also an authorizer to show how to include two AuthAccounts into an transaction
AccountKey IDWeight
0x0111000
0x0231000

1
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
2
account2, _ := c.GetAccount(ctx, flow.HexToAddress("02"))
3


4
key1 := account1.Keys[0]
5
key3 := account2.Keys[0]
6


7
// create signers from securely-stored private keys
8
key1Signer := getSignerForKey1()
9
key3Signer := getSignerForKey3()
10


11
referenceBlock, _ := flow.GetLatestBlock(ctx, true)
12
tx := flow.NewTransaction().
13
    SetScript([]byte(`
14
        transaction {
15
            prepare(signer1: AuthAccount, signer2: AuthAccount) {
16
              log(signer.address)
17
              log(signer2.address)
18
          }
19
        }
20
    `)).
21
    SetGasLimit(100).
22
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
23
    SetReferenceBlockID(referenceBlock.ID).
24
    SetPayer(account2.Address).
25
    AddAuthorizer(account1.Address).
26
    AddAuthorizer(account2.Address)
27


28
// account 1 signs the payload with key 1
29
err := tx.SignPayload(account1.Address, key1.Index, key1Signer)
30


31
// account 2 signs the envelope with key 3
32
// note: payer always signs last
33
err = tx.SignEnvelope(account2.Address, key3.Index, key3Signer)

Multiple parties, multiple signatures

  • Proposer and authorizer are the same account (0x01).
  • Payer is a separate account (0x02).
  • Account 0x01 signs the payload.
  • Account 0x02 signs the envelope.
    • Account 0x02 must sign last since it is the payer.
  • Both accounts must sign twice (once with each of their keys).
AccountKey IDWeight
0x011500
0x012500
0x023500
0x024500

1
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
2
account2, _ := c.GetAccount(ctx, flow.HexToAddress("02"))
3


4
key1 := account1.Keys[0]
5
key2 := account1.Keys[1]
6
key3 := account2.Keys[0]
7
key4 := account2.Keys[1]
8


9
// create signers from securely-stored private keys
10
key1Signer := getSignerForKey1()
11
key2Signer := getSignerForKey1()
12
key3Signer := getSignerForKey3()
13
key4Signer := getSignerForKey4()
14


15
referenceBlock, _ := flow.GetLatestBlock(ctx, true)
16
tx := flow.NewTransaction().
17
    SetScript([]byte(`
18
        transaction {
19
            prepare(signer: AuthAccount) { log(signer.address) }
20
        }
21
    `)).
22
    SetGasLimit(100).
23
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
24
    SetReferenceBlockID(referenceBlock.ID).
25
    SetPayer(account2.Address).
26
    AddAuthorizer(account1.Address)
27


28
// account 1 signs the payload with key 1
29
err := tx.SignPayload(account1.Address, key1.Index, key1Signer)
30


31
// account 1 signs the payload with key 2
32
err = tx.SignPayload(account1.Address, key2.Index, key2Signer)
33


34
// account 2 signs the envelope with key 3
35
// note: payer always signs last
36
err = tx.SignEnvelope(account2.Address, key3.Index, key3Signer)
37


38
// account 2 signs the envelope with key 4
39
// note: payer always signs last
40
err = tx.SignEnvelope(account2.Address, key4.Index, key4Signer)

Send Transactions

After a transaction has been built and signed, it can be sent to the Flow blockchain where it will be executed. If sending was successful you can then retrieve the transaction result.

1
func demo(tx *flow.Transaction) {
2
    ctx := context.Background()
3
    flowClient := examples.NewFlowClient()
4


5
    err := flowClient.SendTransaction(ctx, *tx)
6
    if err != nil {
7
        fmt.Println("error sending transaction", err)
8
    }
9
}

Create Accounts

On Flow, account creation happens inside a transaction. Because the network allows for a many-to-many relationship between public keys and accounts, it's not possible to derive a new account address from a public key offline.

The Flow VM uses a deterministic address generation algorithm to assign account addresses on chain. You can find more details about address generation in the accounts & keys documentation.

Public Key

Flow uses ECDSA key pairs to control access to user accounts. Each key pair can be used in combination with the SHA2-256 or SHA3-256 hashing algorithms.

⚠️ You'll need to authorize at least one public key to control your new account.

Flow represents ECDSA public keys in raw form without additional metadata. Each key is a single byte slice containing a concatenation of its X and Y components in big-endian byte form.

A Flow account can contain zero (not possible to control) or more public keys, referred to as account keys. Read more about accounts in the documentation.

An account key contains the following data:

  • Raw public key (described above)
  • Signature algorithm
  • Hash algorithm
  • Weight (integer between 0-1000)

Account creation happens inside a transaction, which means that somebody must pay to submit that transaction to the network. We'll call this person the account creator. Make sure you have read sending a transaction section first.

1
var (
2
  creatorAddress    flow.Address
3
  creatorAccountKey *flow.AccountKey
4
  creatorSigner     crypto.Signer
5
)
6


7
var accessAPIHost string
8


9
// Establish a connection with an access node
10
flowClient := examples.NewFlowClient()
11


12
// Use the templates package to create a new account creation transaction
13
tx := templates.CreateAccount([]*flow.AccountKey{accountKey}, nil, creatorAddress)
14


15
// Set the transaction payer and proposal key
16
tx.SetPayer(creatorAddress)
17
tx.SetProposalKey(
18
    creatorAddress,
19
    creatorAccountKey.Index,
20
    creatorAccountKey.SequenceNumber,
21
)
22


23
// Get the latest sealed block to use as a reference block
24
latestBlock, err := flowClient.GetLatestBlockHeader(context.Background(), true)
25
if err != nil {
26
    panic("failed to fetch latest block")
27
}
28


29
tx.SetReferenceBlockID(latestBlock.ID)
30


31
// Sign and submit the transaction
32
err = tx.SignEnvelope(creatorAddress, creatorAccountKey.Index, creatorSigner)
33
if err != nil {
34
    panic("failed to sign transaction envelope")
35
}
36


37
err = flowClient.SendTransaction(context.Background(), *tx)
38
if err != nil {
39
    panic("failed to send transaction to network")
40
}

After the account creation transaction has been submitted you can retrieve the new account address by getting the transaction result.

The new account address will be emitted in a system-level flow.AccountCreated event.

1
result, err := flowClient.GetTransactionResult(ctx, tx.ID())
2
if err != nil {
3
    panic("failed to get transaction result")
4
}
5


6
var newAddress flow.Address
7


8
if result.Status != flow.TransactionStatusSealed {
9
    panic("address not known until transaction is sealed")
10
}
11


12
for _, event := range result.Events {
13
    if event.Type == flow.EventAccountCreated {
14
        newAddress = flow.AccountCreatedEvent(event).Address()
15
        break
16
    }
17
}

Generate Keys

Flow uses ECDSA signatures to control access to user accounts. Each key pair can be used in combination with the SHA2-256 or SHA3-256 hashing algorithms.

Here's how to generate an ECDSA private key for the P-256 (secp256r1) curve.

1
import "github.com/onflow/flow-go-sdk/crypto"
2


3
// deterministic seed phrase
4
// note: this is only an example, please use a secure random generator for the key seed
5
seed := []byte("elephant ears space cowboy octopus rodeo potato cannon pineapple")
6


7
privateKey, err := crypto.GeneratePrivateKey(crypto.ECDSA_P256, seed)
8


9
// the private key can then be encoded as bytes (i.e. for storage)
10
encPrivateKey := privateKey.Encode()
11
// the private key has an accompanying public key
12
publicKey := privateKey.PublicKey()

The example above uses an ECDSA key pair on the P-256 (secp256r1) elliptic curve. Flow also supports the secp256k1 curve used by Bitcoin and Ethereum. Read more about supported algorithms here.

Transfering Flow

This is an example of how to construct a FLOW token transfer transaction with the Flow Go SDK.

Before using this example, read the Build a Transaction guide for a general overview of how Flow transactions are constructed.

Cadence Script

The following Cadence script will transfer FLOW tokens from a sender to a recipient.

Note: this transaction is only compatible with Flow Mainnet.

1
import FungibleToken from 0xf233dcee88fe0abe
2
import FlowToken from 0x1654653399040a61
3


4
transaction(amount: UFix64, recipient: Address) {
5
  let sentVault: @FungibleToken.Vault
6
  prepare(signer: AuthAccount) {
7
    let vaultRef = signer.borrow<&FlowToken.Vault>(from: /storage/flowTokenVault)
8
      ?? panic("failed to borrow reference to sender vault")
9


10
    self.sentVault <- vaultRef.withdraw(amount: amount)
11
  }
12


13
  execute {
14
    let receiverRef =  getAccount(recipient)
15
      .getCapability(/public/flowTokenReceiver)
16
      .borrow<&{FungibleToken.Receiver}>()
17
        ?? panic("failed to borrow reference to recipient vault")
18


19
    receiverRef.deposit(from: <-self.sentVault)
20
  }
21
}

Build the Transaction

1
import (
2
    "github.com/onflow/cadence"
3
    "github.com/onflow/flow-go-sdk"
4
)
5


6
// Replace with script above
7
const transferScript string = TOKEN_TRANSFER_CADENCE_SCRIPT
8


9
var (
10
    senderAddress    flow.Address
11
    senderAccountKey flow.AccountKey
12
    senderPrivateKey crypto.PrivateKey
13
)
14


15
func main() {
16
    tx := flow.NewTransaction().
17
        SetScript([]byte(transferScript)).
18
        SetGasLimit(100).
19
        SetPayer(senderAddress).
20
        SetAuthorizer(senderAddress).
21
        SetProposalKey(senderAddress, senderAccountKey.Index, senderAccountKey.SequenceNumber)
22


23
    amount, err := cadence.NewUFix64("123.4")
24
    if err != nil {
25
        panic(err)
26
    }
27


28
    recipient := cadence.NewAddress(flow.HexToAddress("0xabc..."))
29


30
    err = tx.AddArgument(amount)
31
    if err != nil {
32
        panic(err)
33
    }
34


35
    err = tx.AddArgument(recipient)
36
    if err != nil {
37
        panic(err)
38
    }
39
}