Categorygithub.com/onflow/flow-go-sdk
modulepackage
1.4.0
Repository: https://github.com/onflow/flow-go-sdk.git
Documentation: pkg.go.dev

# README

Flow Go SDK

GoDoc

The Flow Go SDK provides a set of packages for Go developers to build applications that interact with the Flow network.

Note: This SDK is also fully compatible with the Flow Emulator and can be used for local development.

English | Chinese

What is Flow?

Flow is a new blockchain for open worlds. Read more about it here.

Table of Contents

Getting Started

Installing

To start using the SDK, install Go 1.13 or above and run go get:

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

Building and testing Go commands with the SDK require enabling cgo CGO_ENABLED=1 because of the underlying cryptography library. Refer to the crypto repository build for more details.

Note that it is possible to build with cgo disabled CGO_ENABLED=0, but this requires confirming the choice by using the Go build tag no-cgo. This would disable the crypto BLS signature features of the SDK. Any call of a BLS tool would result in a panic.

Generating Keys

Flow uses ECDSA 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:

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

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

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

The private key can then be encoded as bytes (i.e. for storage):

encPrivateKey := privateKey.Encode()

A private key has an accompanying public key:

publicKey := privateKey.PublicKey()

Supported Curves

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.

Here's how to generate an ECDSA private key for the secp256k1 curve:

privateKey, err := crypto.GeneratePrivateKey(crypto.ECDSA_secp256k1, seed)

Here's a full list of the supported signature and hash algorithms: Flow Signature & Hash Algorithms

Accessing The Flow Network

You can communicate with any Flow Access Node using the Flow Go SDK. This includes official Access Nodes, nodes you run yourself, and hosted nodes. Flow Go SDK supports both gRPC and HTTP methods of communication with Access Nodes.

It's strongly recommended to use gRPC with Go SDK since it's more efficient and faster.

Here's how to create a new gRPC client for any network:

// You can also use grpc.TestnetHost and grpc.EmulatorHost
flowClient, _ := grpc.NewClient(grpc.MainnetHost)

Check out the http_grpc_clients example to learn more.

Creating an Account

Once you have generated a key pair, you can create a new account using its public key.

import (
    "github.com/onflow/flow-go-sdk"
    "github.com/onflow/flow-go-sdk/crypto"
    "github.com/onflow/flow-go-sdk/templates"
)

ctx := context.Background()

// generate a new private key for the account
// note: this is only an example, please use a secure random generator for the key seed
seed := []byte("elephant ears space cowboy octopus rodeo potato cannon pineapple")
privateKey, _ := crypto.GeneratePrivateKey(crypto.ECDSA_P256, seed)

// get the public key
publicKey := privateKey.PublicKey()

// construct an account key from the public key
accountKey := flow.NewAccountKey().
    SetPublicKey(publicKey).
    SetHashAlgo(crypto.SHA3_256).             // pair this key with the SHA3_256 hashing algorithm
    SetWeight(flow.AccountKeyWeightThreshold) // give this key full signing weight

// generate an account creation script
// this creates an account with a single public key and no code
script, _ := templates.CreateAccount([]*flow.AccountKey{accountKey}, nil)

// connect to an emulator running locally
c, err := client.New("localhost:3569")
if err != nil {
    panic("failed to connect to emulator")
}

payer, payerKey, payerSigner := examples.ServiceAccount(c)

tx := flow.NewTransaction().
    SetScript(script).
    SetGasLimit(100).
    SetProposalKey(payer, payerKey.Index, payerKey.SequenceNumber).
    SetPayer(payer)

err = tx.SignEnvelope(payer, payerKey.Index, payerSigner)
if err != nil {
    panic("failed to sign transaction")
}

err = c.SendTransaction(ctx, *tx)
if err != nil {
    panic("failed to send transaction")
}

result, err := c.GetTransactionResult(ctx, tx.ID())
if err != nil {
    panic("failed to get transaction result")
}

var myAddress flow.Address

if result.Status == flow.TransactionStatusSealed {
    for _, event := range result.Events {
        if event.Type == flow.EventAccountCreated {
            accountCreatedEvent := flow.AccountCreatedEvent(event)
            myAddress = accountCreatedEvent.Address()
        }
	}
}

Signing a Transaction

Below is a simple example of how to sign a transaction using a crypto.PrivateKey.

import (
    "github.com/onflow/flow-go-sdk"
    "github.com/onflow/flow-go-sdk/crypto"
)

var (
    myAddress    flow.Address
    myAccountKey flow.AccountKey
    myPrivateKey crypto.PrivateKey
)

tx := flow.NewTransaction().
    SetScript([]byte("transaction { execute { log(\"Hello, World!\") } }")).
    SetGasLimit(100).
    SetProposalKey(myAddress, myAccountKey.Index, myAccountKey.SequenceNumber).
    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.

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

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

How Signatures Work in Flow

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.


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
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))

key1 := account1.Keys[0]

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

tx := flow.NewTransaction().
    SetScript([]byte(`
        transaction {
            prepare(signer: AuthAccount) { log(signer.address) }
        }
    `)).
    SetGasLimit(100).
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
    SetPayer(account1.Address).
    AddAuthorizer(account1.Address)

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

Full Runnable Example


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
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))

key1 := account1.Keys[0]
key2 := account1.Keys[1]

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

tx := flow.NewTransaction().
    SetScript([]byte(`
        transaction {
            prepare(signer: AuthAccount) { log(signer.address) }
        }
    `)).
    SetGasLimit(100).
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
    SetPayer(account1.Address).
    AddAuthorizer(account1.Address)

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

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

Full Runnable Example


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
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
account2, _ := c.GetAccount(ctx, flow.HexToAddress("02"))

key1 := account1.Keys[0]
key3 := account2.Keys[0]

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

tx := flow.NewTransaction().
    SetScript([]byte(`
        transaction {
            prepare(signer: AuthAccount) { log(signer.address) }
        }
    `)).
    SetGasLimit(100).
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
    SetPayer(account2.Address).
    AddAuthorizer(account1.Address)

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

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

Full Runnable Example


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
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
account2, _ := c.GetAccount(ctx, flow.HexToAddress("02"))

key1 := account1.Keys[0]
key3 := account2.Keys[0]

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

tx := flow.NewTransaction().
    SetScript([]byte(`
        transaction {
            prepare(signer1: AuthAccount, signer2: AuthAccount) {
              log(signer.address)
              log(signer2.address)
          }
        }
    `)).
    SetGasLimit(100).
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
    SetPayer(account2.Address).
    AddAuthorizer(account1.Address).
    AddAuthorizer(account2.Address)

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

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

Full Runnable Example


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
account1, _ := c.GetAccount(ctx, flow.HexToAddress("01"))
account2, _ := c.GetAccount(ctx, flow.HexToAddress("02"))

key1 := account1.Keys[0]
key2 := account1.Keys[1]
key3 := account2.Keys[0]
key4 := account2.Keys[1]

// create signers from securely-stored private keys
key1Signer := getSignerForKey1()
key2Signer := getSignerForKey1()
key3Signer := getSignerForKey3()
key4Signer := getSignerForKey4()

tx := flow.NewTransaction().
    SetScript([]byte(`
        transaction {
            prepare(signer: AuthAccount) { log(signer.address) }
        }
    `)).
    SetGasLimit(100).
    SetProposalKey(account1.Address, key1.Index, key1.SequenceNumber).
    SetPayer(account2.Address).
    AddAuthorizer(account1.Address)

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

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

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

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

Full Runnable Example

Sending a Transaction

You can submit a transaction to the network using the Access API client.

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

// connect to an emulator running locally
c, err := client.New("localhost:3569")
if err != nil {
    panic("failed to connect to emulator")
}

ctx := context.Background()

err = c.SendTransaction(ctx, tx)
if err != nil {
    panic("failed to send transaction")
}

Querying Transaction Results

After you have submitted a transaction, you can query its status by ID:

result, err := c.GetTransactionResult(ctx, tx.ID())
if err != nil {
    panic("failed to fetch transaction result")
}

The result includes a Status field that will be one of the following values:

  • 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.
if result.Status == flow.TransactionStatusSealed {
  fmt.Println("Transaction is sealed!")
}

The result also contains an Error that holds the error information for a failed transaction.

if result.Error != nil {
    fmt.Printf("Transaction failed with error: %v\n", result.Error)
}

Querying Blocks

You can use the GetLatestBlock method to fetch the latest sealed or unsealed block:

// fetch the latest sealed block
isSealed := true
latestBlock, err := c.GetLatestBlock(ctx, isSealed)
if err != nil {
    panic("failed to fetch latest sealed block")
}

// fetch the latest unsealed block
isSealed := false
latestBlock, err := c.GetLatestBlock(ctx, isSealed)
if err != nil {
    panic("failed to fetch latest unsealed block")
}

A block contains the following fields:

  • ID - The ID (hash) of the block.
  • ParentBlockID - The ID of the previous block in the chain.
  • Height - The height of the block in the chain.
  • CollectionGuarantees - The list of collections included in the block.

Executing a Script

You can use the ExecuteScriptAtLatestBlock method to execute a read-only script against the latest sealed execution state.

This functionality can be used to read state from the blockchain.

Scripts must be in the following form:

  • A single main function with a single return value

This is an example of a valid script:

fun main(): Int { return 1 }
import "github.com/onflow/cadence"

script := []byte("fun main(): Int { return 1 }")

value, err := c.ExecuteScriptAtLatestBlock(ctx, script, nil)
if err != nil {
    panic("failed to execute script")
}

ID := value.(cadence.Int)

// convert to Go int type
myID := ID.Int()

Querying Events

You can query events with the GetEventsForHeightRange function:

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

blocks, err := c.GetEventsForHeightRange(ctx, client.EventRangeQuery{
    Type:       "flow.AccountCreated",
    StartHeight: 10,
    EndHeight:   15,
})
if err != nil {
    panic("failed to query events")
}

Event Query Format

An event query includes the following fields:

Type

The event type to filter by. Event types are namespaced by the account and contract in which they are declared.

For example, a Transfer event that was defined in the Token contract deployed at account 0x55555555555555555555 will have a type of A.0x55555555555555555555.Token.Transfer.

Read the language documentation for more information on how to define and emit events in Cadence.

StartHeight, EndHeight

The blocks to filter by. Events will be returned from blocks in the range StartHeight to EndHeight, inclusive.

Event Results

The GetEventsForHeightRange function returns events grouped by block. Each block contains a list of events matching the query in order of execution.

for _, block := range blocks {
    fmt.Printf("Events for block %s:\n", block.BlockID)
    for _, event := range block.Events {
        fmt.Printf(" - %s", event)
    }
}

Querying Accounts

You can query the state of an account with the GetAccount function:

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

address := flow.HexToAddress("01")

account, err := c.GetAccount(ctx, address)
if err != nil {
    panic("failed to fetch account")
}

A flow.Account contains the following fields:

  • Address: flow.Address - The account address.
  • Balance: uint64 - The account balance.
  • Code: []byte - The code deployed at this account.
  • Keys: []flow.AccountKey - A list of the public keys associated with this account.

Examples

The examples directory contains code samples that use the SDK to interact with the Flow Emulator.

# Packages

Package access contains an interface defining functions for the API clients.
Package client provides grpc API implementation.
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

No description provided by the author
BytesToAddress returns Address with value b.
BytesToHash constructs a crypto hash from byte slice.
BytesToID constructs an identifier from a byte slice.
BytesToStateCommitment constructs a state commitment from a byte slice.
CalculateEventsHash calculates hash of the events, in a way compatible with the events hash propagated in Chunk.
DecodeAccountKey decodes the RLP byte representation of an account key.
DecodeTransaction decodes the input bytes into a Transaction struct able to decode outputs from PayloadMessage(), EnvelopeMessage() and Encode() functions.
EncodeAccountProofMessage creates a new account proof message for singing.
HashToID constructs an identifier from a 32-byte hash.
HashToStateCommitment constructs a state commitment from a 32-byte hash.
HexToAddress converts a hex string to an Address.
HexToID constructs an identifier from a hexadecimal string.
HexToStateCommitment constructs a state commitment from a hexadecimal string.
NewAccountKey returns an empty account key.
NewAddressGenerator creates a new address generator for the given chain ID, starting from the zero address state.
NewEventTypeFactory helper function for constructing event names.
NewTransaction initializes and returns an empty transaction.
ServiceAddress is the first generated account address.
SignUserMessage signs a message in the user domain.

# Constants

AccountKeyWeightThreshold is the total key weight required to authorize access to an account.
AccountProofNonceMinLenBytes is the minimum length of account proof nonces in bytes.
AddressLength is the size of an account address in bytes.
Benchnet is the chain ID for the transient benchmarking chain.
BftTestnet is the chain ID for testing attack vector scenarios.
BlockStatusFinalized is the status of a finalized block.
BlockStatusSealed is the status of a sealed block.
BlockStatusUnknown indicates that the block status is not known.
DefaultTransactionGasLimit should be high enough for small transactions.
Emulator is the chain ID for the emulated chain.
List of built-in account event types.
List of built-in account event types.
List of built-in account event types.
List of built-in account event types.
List of built-in account event types.
List of built-in account event types.
No description provided by the author
No description provided by the author
Localnet is the chain ID for the local development chain.
Mainnet is the chain ID for the mainnet chain.
MonotonicEmulator is the chain ID for the emulated node chain with monotonic address generation.
Testnet is the chain ID for the testnet chain.
TransactionStatusExecuted is the status of an executed transaction.
TransactionStatusExpired is the status of an expired transaction.
TransactionStatusFinalized is the status of a finalized transaction.
TransactionStatusPending is the status of a pending transaction.
TransactionStatusSealed is the status of a sealed transaction.
TransactionStatusUnknown indicates that the transaction status is not known.

# Variables

EmptyAddress is the empty address (0x0000000000000000).
EmptyID is the empty identifier.
ErrInvalidAppID is returned when the account proof app ID passed to a function is invalid.
ErrInvalidNonce is returned when the account proof nonce passed to a function is invalid.
TransactionDomainTag is the prefix of all signed transaction payloads.
UserDomainTag is the prefix of all signed user space payloads.

# Structs

An Account is an account on the Flow network.
An AccountKey is a public key associated with an account.
No description provided by the author
No description provided by the author
No description provided by the author
An AddressGenerator uses a deterministic algorithm to generate Flow addresses.
No description provided by the author
Block is a set of state mutations applied to the Flow blockchain.
BlockDigest holds lightweight block information which includes only block id, block height and block timestamp.
BlockEvents are the events that occurred in a specific block.
BlockHeader is a summary of a full block.
BlockPayload is the full contents of a block.
BlockSeal is the attestation by verification nodes that the transactions in a previously executed block have been verified.
No description provided by the author
No description provided by the author
A Collection is a list of transactions bundled together for inclusion in a block.
A CollectionGuarantee is an attestation signed by the nodes that have guaranteed a collection.
No description provided by the author
No description provided by the author
EventFilter is used to filter events based on given parameters.
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author
A ProposalKey is the key that specifies the proposal key and sequence number for a transaction.
No description provided by the author
No description provided by the author
No description provided by the author
A Transaction is a full transaction object containing a payload and signatures.
No description provided by the author
A TransactionSignature is a signature associated with a specific account key.
No description provided by the author

# Type aliases

An AccountCreatedEvent is emitted when a transaction creates a new Flow account.
Address represents the 8 byte address of an account.
BlockStatus represents the status of a block.
A ChainID is a unique identifier for a specific Flow network instance.
No description provided by the author
An Identifier is a 32-byte unique identifier for an entity.
No description provided by the author
TransactionStatus represents the status of a transaction.