Flow Access API Specification
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 Node Endpoints
The Access Nodes hosted by DapperLabs are accessible at:
Network | GRPC | Web GRPC | REST |
---|---|---|---|
Mainnet | access.mainnet.nodes.onflow.org:9000 | mainnet.onflow.org | mainnet.onflow.org |
Sandboxnet (deprecated) | |||
Testnet | access.devnet.nodes.onflow.org:9000 | testnet.onflow.org | testnet.onflow.org |
Previewnet | access.previewnet.nodes.onflow.org:9000 | previewnet.onflow.org | previewnet.onflow.org |
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.
Testnet
Our test environment. Funds can be fauceted freely. It is sporked 2 weeks prior to mainnet.
Ping
Ping
will return a successful response if the Access API is ready and available.
If a ping request returns an error or times out, it can be assumed that the Access API is unavailable.
Request
Response
Block Headers
The following methods query information about block headers.
GetLatestBlockHeader
GetLatestBlockHeader
gets the latest sealed or unsealed block header.
Request
Response
GetBlockHeaderByID
GetBlockHeaderByID
gets a block header by ID.
Request
Response
GetBlockHeaderByHeight
GetBlockHeaderByHeight
gets a block header by height.
Request
Response
Blocks
The following methods query information about full blocks.
GetLatestBlock
GetLatestBlock
gets the full payload of the latest sealed or unsealed block.
Request
Response
GetBlockByID
GetBlockByID
gets a full block by ID.
Request
Response
GetBlockByHeight
GetBlockByHeight
gets a full block by height.
Request
Response
Collections
The following methods query information about collections.
GetCollectionByID
GetCollectionByID
gets a collection by ID.
Request
Response
Transactions
The following methods can be used to submit transactions and fetch their results.
SendTransaction
SendTransaction
submits a transaction to the network.
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.
Response
SendTransactionResponse
message contains the ID of the submitted transaction.
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.
Request
GetTransactionRequest
contains the ID of the transaction that is being queried.
Response
TransactionResponse
contains the basic information about a transaction, but does not include post-execution results.
GetTransactionResult
GetTransactionResult
gets the execution result of a transaction.
Request
Response
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.
Request
Response
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.
Request
Response
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.
Request
Response
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.
This method is a shortcut for the following:
Request
Response
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.
Request
Response
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.
Request
Response
Events
The following methods can be used to query for on-chain events.
GetEventsForHeightRange
GetEventsForHeightRange
retrieves events emitted within the specified block range.
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
Response
GetEventsForBlockIDs
GetEventsForBlockIDs
retrieves events for the specified block IDs and event type.
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
Response
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.
Request
Response
Field | Description |
---|---|
chain_id | Chain ID helps identify the Flow network. It can be one of flow-mainnet , flow-testnet or flow-emulator |
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.
Request
Response
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.
Request
Response
Entities
Below are in-depth descriptions of each of the data entities returned or accepted by the Access API.
Block
Field | Description |
---|---|
id | SHA3-256 hash of the entire block payload |
height | Height of the block in the chain |
parent_id | ID of the previous block in the chain |
timestamp | Timestamp of when the proposer claims it constructed the block. NOTE: It is included by the proposer, there are no guarantees on how much the time stamp can deviate from the true time the block was published. Consider observing blocks' status changes yourself to get a more reliable value. |
collection_guarantees | List of collection guarantees |
block_seals | List of block seals |
signatures | BLS signatures of consensus nodes |
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.
Field | Description |
---|---|
id | SHA3-256 hash of the entire block payload |
parent_id | ID of the previous block in the chain |
height | Height of the block in the chain |
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.
Field | Description |
---|---|
block_id | ID of the block being sealed |
execution_receipt_id | ID execution receipt being sealed |
execution_receipt_signatures | BLS signatures of verification nodes on the execution receipt contents |
result_approval_signatures | BLS signatures of verification nodes on the result approval contents |
Block Status
Value | Description |
---|---|
UNKNOWN | The block status is not known. |
FINALIZED | The consensus nodes have finalized the block |
SEALED | The verification nodes have verified the block |
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.
Field | Description |
---|---|
id | SHA3-256 hash of the collection contents |
transaction_ids | Ordered list of transaction IDs in the collection |
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.
Field | Description |
---|---|
collection_id | SHA3-256 hash of the collection contents |
signatures | BLS signatures of the collection nodes guaranteeing the collection |
Transaction
A transaction represents a unit of computation that is submitted to the Flow network.
Field | Description |
---|---|
script | Raw source code for a Cadence script, encoded as UTF-8 bytes |
arguments | Arguments passed to the Cadence script, encoded as JSON-Cadence bytes |
reference_block_id | Block ID used to determine transaction expiry |
proposal_key | Account key used to propose the transaction |
payer | Address of the payer account |
authorizers | Addresses of the transaction authorizers |
signatures | Signatures from all signer accounts |
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.
Field | Description |
---|---|
address | Address of proposer account |
key_id | ID of proposal key on the proposal account |
sequence_number | Sequence number for the proposal key |
Transaction Signature
Field | Description |
---|---|
address | Address of the account for this signature |
key_id | ID of the account key |
signature | Raw signature byte data |
Transaction Status
Value | Description |
---|---|
UNKNOWN | The transaction status is not known. |
PENDING | The transaction has been received by a collector but not yet finalized in a block. |
FINALIZED | The consensus nodes have finalized the block that the transaction is included in |
EXECUTED | The execution nodes have produced a result for the transaction |
SEALED | The verification nodes have verified the transaction (the block in which the transaction is) and the seal is included in the latest block |
EXPIRED | The transaction was submitted past its expiration block height. |
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.
Field | Description |
---|---|
address | A unique account identifier |
balance | The account balance |
code | The code deployed to this account (deprecated, use contracts instead) |
keys | A list of keys configured on this account |
contracts | A map of contracts or contract interfaces deployed on this account |
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.
Field | Description |
---|---|
id | Index of the key within the account, used as a unique identifier |
public_key | Public key encoded as bytes |
sign_algo | Signature algorithm |
hash_algo | Hash algorithm |
weight | Weight assigned to the key |
sequence_number | Sequence number for the key |
revoked | Flag indicating whether or not the key has been revoked |
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.
Field | Description |
---|---|
type | Fully-qualified unique type identifier for the event |
transaction_id | ID of the transaction the event was emitted from |
transaction_index | Zero-based index of the transaction within the block |
event_index | Zero-based index of the event within the transaction |
payload | Event fields encoded as JSON-Cadence values |
Execution Result
Execution result for a particular block.
Field | Description |
---|---|
previous_result_id | Identifier of parent block execution result |
block_id | ID of the block this execution result corresponds to |
chunks | Zero or more chunks |
service_events | Zero or more service events |
Chunk
Chunk described execution information for given collection in a block
Field | Description |
---|---|
start_state | State commitment at start of the chunk |
event_collection | Hash of events emitted by transactions in this chunk |
block_id | Identifier of a block |
total_computation_used | Total computation used by transactions in this chunk |
number_of_transactions | Number of transactions in a chunk |
index | Index of chunk inside a block (zero-based) |
end_state | State commitment after executing chunk |
Service Event
Special type of events emitted in system chunk used for controlling Flow system.
Field | Description |
---|---|
type | Type of an event |
payload | JSON-serialized content of an event |
Subscriptions
SubscribeEvents
SubscribeEvents
streams events for all blocks starting at the requested start block, up until the latest available block. Once the latest is
reached, the stream will remain open and responses are sent for each new block as it becomes available.
Events within each block are filtered by the provided EventFilter, and only those events that match the filter are returned. If no filter is provided, all events are returned.
Responses are returned for each block containing at least one event that matches the filter. Additionally, heatbeat responses (SubscribeEventsResponse with no events) are returned periodically to allow clients to track which blocks were searched. Clients can use this information to determine which block to start from when reconnecting.
Request
Field | Description |
---|---|
start_block_id | The first block to search for events. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
start_block_height | Block height of the first block to search for events. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
filter | Filter to apply to events for each block searched. If no filter is provided, all events are returned |
heartbeat_interval | Interval in block heights at which the server should return a heartbeat message to the client |
event_encoding_version | Preferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC |
Response
SubscribeExecutionData
SubscribeExecutionData
streams execution data for all blocks starting at the requested start block, up until the latest available block. Once the latest is reached, the stream will remain open and responses are sent for each new execution data as it becomes available.
Request
Field | Description |
---|---|
start_block_id | The first block to get execution data for. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
start_block_height | Block height of the first block to get execution data for. Only one of start_block_id and start_block_height may be provided, otherwise an InvalidArgument error is returned. If neither are provided, the latest sealed block is used |
event_encoding_version | Preferred event encoding version of the block events payload. Possible variants: CCF, JSON-CDC |
Response
Execution data
EventFilter
EventFilter
defines the filter to apply to block events. Filters are applied as an OR operation, i.e. any event matching any of the filters is returned.
If no filters are provided, all events are returned. If there are any invalid filters, the API will return an InvalidArgument error.
Field | Description |
---|---|
event_type | A list of full event types to include. Event types have 2 formats: * Protocol events: flow.[event name] * Smart contract events: A.[contract address].[contract name].[event name] |
contract | A list of contracts who's events should be included. Contracts have the following name formats: * Protocol events: flow * Smart contract events: A.[contract address].[contract name] This filter matches on the full contract including its address, not just the contract's name |
address | A list of addresses who's events should be included. Addresses must be Flow account addresses in hex format and valid for the network the node is connected to. i.e. only a mainnet address is valid for a mainnet node. Addresses may optionally include the 0x prefix |