Flow Access API Specification

Updated: 2023/3/21 bypeterargue

17 min read

The Access API is implemented as a gRPC service.

A language-agnostic specification for this API is defined using Protocol Buffers, which can be used to generate client libraries in a variety of programming languages.

• Flow Access API protobuf source files

Flow access node endpoints

The Access Nodes hosted by DapperLabs are accessible at:

Mainnet

We are still in the process of aggregating the past chain data but mainnet 5 to mainnet 1 spork data can be retrieved from the Access nodes mentioned here

Production network where the Flow blockchain is running. Funds are at risk.

Sandboxnet

Sandboxnet mirrors mainnet and is sporked a day after the mainnet spork. It is used for testing and development.

Testnet

Our test environment. Funds can be fauceted freely. It is sporked 2 weeks prior to mainnet.

Rate limits for Dapper Labs access nodes

Access nodes operated by Dapper Labs are rate limited.

Ping

Ping will return a successful response if the Access API is ready and available.

1
rpc Ping(PingRequest) returns (PingResponse)

If a ping request returns an error or times out, it can be assumed that the Access API is unavailable.

Request

1
message PingRequest {}

Response

1
message PingResponse {}

Block Headers

The following methods query information about block headers.

GetLatestBlockHeader

GetLatestBlockHeader gets the latest sealed or unsealed block header.

1
rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderResponse)

Request

1
message GetLatestBlockHeaderRequest {
2
  bool is_sealed
3
}

Response

1
message BlockHeaderResponse {
2
  flow.BlockHeader block
3
  flow.BlockStatus block_status
4
}

GetBlockHeaderByID

GetBlockHeaderByID gets a block header by ID.

1
rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)

Request

1
message GetBlockHeaderByIDRequest {
2
  bytes id
3
}

Response

1
message BlockHeaderResponse {
2
  flow.BlockHeader block
3
  flow.BlockStatus block_status
4
}

GetBlockHeaderByHeight

GetBlockHeaderByHeight gets a block header by height.

1
rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderResponse)

Request

1
message GetBlockHeaderByHeightRequest {
2
  uint64 height
3
}

Response

1
message BlockHeaderResponse {
2
  flow.BlockHeader block
3
  flow.BlockStatus block_status
4
}

Blocks

The following methods query information about full blocks.

GetLatestBlock

GetLatestBlock gets the full payload of the latest sealed or unsealed block.

1
rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse)

Request

1
message GetLatestBlockRequest {
2
  bool is_sealed
3
}

Response

1
message BlockResponse {
2
  flow.Block block
3
  flow.BlockStatus block_status
4
}

GetBlockByID

GetBlockByID gets a full block by ID.

1
rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)

Request

1
message GetBlockByIDRequest {
2
  bytes id
3
}

Response

1
message BlockResponse {
2
  flow.Block block
3
  flow.BlockStatus block_status
4
}

GetBlockByHeight

GetBlockByHeight gets a full block by height.

1
rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)

Request

1
message GetBlockByHeightRequest {
2
  uint64 height
3
}

Response

1
message BlockResponse {
2
  flow.Block block
3
  flow.BlockStatus block_status
4
}

Collections

The following methods query information about collections.

GetCollectionByID

GetCollectionByID gets a collection by ID.

1
rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse)

Request

1
message GetCollectionByIDRequest {
2
  bytes id
3
}

Response

1
message CollectionResponse {
2
  flow.Collection collection
3
}

Transactions

The following methods can be used to submit transactions and fetch their results.

SendTransaction

SendTransaction submits a transaction to the network.

1
rpc SendTransaction (SendTransactionRequest) returns (SendTransactionResponse)

SendTransaction determines the correct cluster of collection nodes that is responsible for collecting the transaction based on the hash of the transaction and forwards the transaction to that cluster.

Request

SendTransactionRequest message contains the transaction that is being request to be executed.

1
message SendTransactionRequest {
2
  flow.Transaction transaction
3
}

Response

SendTransactionResponse message contains the ID of the submitted transaction.

1
message SendTransactionResponse {
2
  bytes id
3
}

GetTransaction

GetTransaction gets a transaction by ID.

If the transaction is not found in the access node cache, the request is forwarded to a collection node.

Currently, only transactions within the current epoch can be queried.

1
rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse)

Request

GetTransactionRequest contains the ID of the transaction that is being queried.

1
message GetTransactionRequest {
2
  bytes id
3
}

Response

TransactionResponse contains the basic information about a transaction, but does not include post-execution results.

1
message TransactionResponse {
2
  flow.Transaction transaction
3
}

GetTransactionResult

GetTransactionResult gets the execution result of a transaction.

1
rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultResponse)

Request

1
message GetTransactionRequest {
2
  bytes id
3
}

Response

1
message TransactionResultResponse {
2
  flow.TransactionStatus status
3
  uint32 status_code
4
  string error_message
5
  repeated flow.Event events
6
}

Accounts

GetAccount

GetAccount gets an account by address at the latest sealed block.

⚠️ Warning: this function is deprecated. It behaves identically to GetAccountAtLatestBlock and will be removed in a future version.

1
rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)

Request

1
message GetAccountRequest {
2
  bytes address
3
}

Response

1
message GetAccountResponse {
2
  Account account
3
}

GetAccountAtLatestBlock

GetAccountAtLatestBlock gets an account by address.

The access node queries an execution node for the account details, which are stored as part of the sealed execution state.

1
rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)

Request

1
message GetAccountAtLatestBlockRequest {
2
  bytes address
3
}

Response

1
message AccountResponse {
2
  Account account
3
}

GetAccountAtBlockHeight

GetAccountAtBlockHeight gets an account by address at the given block height.

The access node queries an execution node for the account details, which are stored as part of the execution state.

1
rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResponse)

Request

1
message GetAccountAtBlockHeightRequest {
2
  bytes address
3
  uint64 block_height
4
}

Response

1
message AccountResponse {
2
  Account account
3
}

Scripts

ExecuteScriptAtLatestBlock

ExecuteScriptAtLatestBlock executes a read-only Cadence script against the latest sealed execution state.

This method can be used to read execution state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.

1
rpc ExecuteScriptAtLatestBlock (ExecuteScriptAtLatestBlockRequest) returns (ExecuteScriptResponse)

This method is a shortcut for the following:

1
header = GetLatestBlockHeader()
2
value = ExecuteScriptAtBlockID(header.ID, script)

Request

1
message ExecuteScriptAtLatestBlockRequest {
2
  bytes script
3
}

Response

1
message ExecuteScriptResponse {
2
  bytes value
3
}

ExecuteScriptAtBlockID

ExecuteScriptAtBlockID executes a ready-only Cadence script against the execution state at the block with the given ID.

This method can be used to read account state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.

1
rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScriptResponse)

Request

1
message ExecuteScriptAtBlockIDRequest {
2
  bytes block_id
3
  bytes script
4
}

Response

1
message ExecuteScriptResponse {
2
  bytes value
3
}

ExecuteScriptAtBlockHeight

ExecuteScriptAtBlockHeight executes a ready-only Cadence script against the execution state at the given block height.

This method can be used to read account state from the blockchain. The script is executed on an execution node and the return value is encoded using the JSON-Cadence data interchange format.

1
rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (ExecuteScriptResponse)

Request

1
message ExecuteScriptAtBlockHeightRequest {
2
  uint64 block_height
3
  bytes script
4
}

Response

1
message ExecuteScriptResponse {
2
  bytes value
3
}

Events

The following methods can be used to query for on-chain events.

GetEventsForHeightRange

GetEventsForHeightRange retrieves events emitted within the specified block range.

1
rpc GetEventsForHeightRange(GetEventsForHeightRangeRequest) returns (GetEventsForHeightRangeResponse)

Events can be requested for a specific sealed block range via the start_height and end_height (inclusive) fields and further filtered by event type via the type field.

If start_height is greater than the current sealed chain height, then this method will return an error.

If end_height is greater than the current sealed chain height, then this method will return events up to and including the latest sealed block.

The event results are grouped by block, with each group specifying a block ID, height and block timestamp.

Event types are name-spaced with the address of the account and contract in which they are declared.

Request

1
message GetEventsForHeightRangeRequest {
2
  string type
3
  uint64 start_height = 2;
4
  uint64 end_height = 3;
5
}

Response

1
message EventsResponse {
2
  message Result {
3
    bytes block_id = 1;
4
    uint64 block_height = 2;
5
    repeated entities.Event events = 3;
6
    google.protobuf.Timestamp block_timestamp = 4;
7
  }
8
  repeated Result results = 1;
9
}

GetEventsForBlockIDs

GetEventsForBlockIDs retrieves events for the specified block IDs and event type.

1
rpc GetEventsForBlockIDs(GetEventsForBlockIDsRequest) returns (GetEventsForBlockIDsResponse)

Events can be requested for a list of block IDs via the block_ids field and further filtered by event type via the type field.

The event results are grouped by block, with each group specifying a block ID, height and block timestamp.

Request

1
message GetEventsForBlockIDsRequest {
2
  string type = 1;
3
  repeated bytes block_ids = 2;
4
}

Response

1
message EventsResponse {
2
  message Result {
3
    bytes block_id = 1;
4
    uint64 block_height = 2;
5
    repeated entities.Event events = 3;
6
    google.protobuf.Timestamp block_timestamp = 4;
7
  }
8
  repeated Result results = 1;
9
}

Network Parameters

Network parameters provide information about the Flow network. Currently, it only includes the chain ID. The following method can be used to query for network parameters.

GetNetworkParameters

GetNetworkParameters retrieves the network parameters.

1
rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)

Request

1
message GetNetworkParametersRequest {}

Response

1
message GetNetworkParametersResponse {
2
  string chain_id = 1;
3
}

Protocol state snapshot

The following method can be used to query the latest protocol state snapshot.

GetLatestProtocolStateSnapshotRequest

GetLatestProtocolStateSnapshotRequest retrieves the latest Protocol state snapshot serialized as a byte array. It is used by Flow nodes joining the network to bootstrap a space-efficient local state.

1
rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);

Request

1
message GetLatestProtocolStateSnapshotRequest {}

Response

1
message ProtocolStateSnapshotResponse {
2
  bytes serializedSnapshot = 1;
3
}

Execution results

The following method can be used to query the for execution results for a given block.

GetExecutionResultForBlockID

GetExecutionResultForBlockID retrieves execution result for given block. It is different from Transaction Results, and contain data about chunks/collection level execution results rather than particular transactions. Particularly, it contains EventsCollection hash for every chunk which can be used to verify the events for a block.

1
rpc GetExecutionResultForBlockID(GetExecutionResultForBlockIDRequest) returns (ExecutionResultForBlockIDResponse);

Request

1
message GetExecutionResultForBlockIDRequest {
2
  bytes block_id = 1;
3
}

Response

1
message ExecutionResultForBlockIDResponse {
2
  flow.ExecutionResult execution_result = 1;
3
}

Entities

Below are in-depth descriptions of each of the data entities returned or accepted by the Access API.

Block

1
message Block {
2
  bytes id
3
  bytes parent_id
4
  uint64 height
5
  google.protobuf.Timestamp timestamp
6
  repeated CollectionGuarantee collection_guarantees
7
  repeated BlockSeal block_seals
8
  repeated bytes signatures
9
}

The detailed semantics of block formation are covered in the block formation guide.

Block Header

A block header is a summary of a block and contains only the block ID, height, and parent block ID.

1
message BlockHeader {
2
  bytes id
3
  bytes parent_id
4
  uint64 height
5
}

Block Seal

A block seal is an attestation that the execution result of a specific block has been verified and approved by a quorum of verification nodes.

1
message BlockSeal {
2
  bytes block_id
3
  bytes execution_receipt_id
4
  repeated bytes execution_receipt_signatures
5
  repeated bytes result_approval_signatures
6
}

Block Status

1
enum BlockStatus {
2
  UNKNOWN = 0;
3
  FINALIZED = 1;
4
  SEALED = 2;
5
}

Collection

A collection is a batch of transactions that have been included in a block. Collections are used to improve consensus throughput by increasing the number of transactions per block.

1
message Collection {
2
  bytes id
3
  repeated bytes transaction_ids
4
}

Collection Guarantee

A collection guarantee is a signed attestation that specifies the collection nodes that have guaranteed to store and respond to queries about a collection.

1
message CollectionGuarantee {
2
  bytes collection_id
3
  repeated bytes signatures
4
}

Transaction

A transaction represents a unit of computation that is submitted to the Flow network.

1
message Transaction {
2
  bytes script
3
  repeated bytes arguments
4
  bytes reference_block_id
5
  uint64 gas_limit
6
  TransactionProposalKey proposal_key
7
  bytes payer
8
  repeated bytes authorizers
9
  repeated TransactionSignature payload_signatures
10
  repeated TransactionSignature envelope_signatures
11
}
12

13
message TransactionProposalKey {
14
  bytes address
15
  uint32 key_id
16
  uint64 sequence_number
17
}
18

19
message TransactionSignature {
20
  bytes address
21
  uint32 key_id
22
  bytes signature
23
}

The detailed semantics of transaction creation, signing and submission are covered in the transaction submission guide.

Proposal Key

The proposal key is used to specify a sequence number for the transaction. Sequence numbers are covered in more detail here.

Transaction Signature

Transaction Status

1
enum TransactionStatus {
2
  UNKNOWN = 0;
3
  PENDING = 1;
4
  FINALIZED = 2;
5
  EXECUTED = 3;
6
  SEALED = 4;
7
  EXPIRED = 5;
8
}

Account

An account is a user's identity on Flow. It contains a unique address, a balance, a list of public keys and the code that has been deployed to the account.

1
message Account {
2
  bytes address
3
  uint64 balance
4
  bytes code
5
  repeated AccountKey keys
6
  map<string, bytes> contracts
7
}

The code and contracts fields contain the raw Cadence source code, encoded as UTF-8 bytes.

More information on accounts can be found here.

Account Key

An account key is a reference to a public key associated with a Flow account. Accounts can be configured with zero or more public keys, each of which can be used for signature verification when authorizing a transaction.

1
message AccountKey {
2
  uint32 id
3
  bytes public_key
4
  uint32 sign_algo
5
  uint32 hash_algo
6
  uint32 weight
7
  uint32 sequence_number
8
  bool revoked
9
}

More information on account keys, key weights and sequence numbers can be found here.

Event

An event is emitted as the result of a transaction execution. Events are either user-defined events originating from a Cadence smart contract, or built-in Flow system events.

1
message Event {
2
  string type
3
  bytes transaction_id
4
  uint32 transaction_index
5
  uint32 event_index
6
  bytes payload
7
}

Execution Result

Execution result for a particular block.

1
message ExecutionResult {
2
  bytes previous_result_id
3
  bytes block_id
4
  repeated Chunk chunks
5
  repeated ServiceEvent service_events
6
}

Chunk

Chunk described execution information for given collection in a block

1
message Chunk {
2
  bytes start_state
3
  bytes event_collection
4
  bytes block_id
5
  uint64 total_computation_used
6
  uint64 number_of_transactions
7
  uint64 index
8
  bytes end_state
9
}

Service Event

Special type of events emitted in system chunk used for controlling Flow system.

1
message ServiceEvent {
2
  string type;
3
  bytes payload;
4
}