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.
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 | access.sandboxnet.nodes.onflow.org:9000 | sandboxnet.onflow.org | sandboxnet.onflow.org |
Testnet | access.devnet.nodes.onflow.org:9000 | testnet.onflow.org | testnet.onflow.org |
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 mirrors mainnet and is sporked a day after the mainnet spork. It is used for testing and development.
Our test environment. Funds can be fauceted freely. It is sporked 2 weeks prior to mainnet.
Access nodes operated by Dapper Labs are rate limited.
Ping
will return a successful response if the Access API is ready and available.
1rpc Ping(PingRequest) returns (PingResponse)
If a ping request returns an error or times out, it can be assumed that the Access API is unavailable.
1message PingRequest {}
1message PingResponse {}
The following methods query information about block headers.
GetLatestBlockHeader
gets the latest sealed or unsealed block header.
1rpc GetLatestBlockHeader (GetLatestBlockHeaderRequest) returns (BlockHeaderResponse)
1message GetLatestBlockHeaderRequest {2bool is_sealed3}
1message BlockHeaderResponse {2flow.BlockHeader block3flow.BlockStatus block_status4}
GetBlockHeaderByID
gets a block header by ID.
1rpc GetBlockHeaderByID (GetBlockHeaderByIDRequest) returns (BlockHeaderResponse)
1message GetBlockHeaderByIDRequest {2bytes id3}
1message BlockHeaderResponse {2flow.BlockHeader block3flow.BlockStatus block_status4}
GetBlockHeaderByHeight
gets a block header by height.
1rpc GetBlockHeaderByHeight (GetBlockHeaderByHeightRequest) returns (BlockHeaderResponse)
1message GetBlockHeaderByHeightRequest {2uint64 height3}
1message BlockHeaderResponse {2flow.BlockHeader block3flow.BlockStatus block_status4}
The following methods query information about full blocks.
GetLatestBlock
gets the full payload of the latest sealed or unsealed block.
1rpc GetLatestBlock (GetLatestBlockRequest) returns (BlockResponse)
1message GetLatestBlockRequest {2bool is_sealed3}
1message BlockResponse {2flow.Block block3flow.BlockStatus block_status4}
GetBlockByID
gets a full block by ID.
1rpc GetBlockByID (GetBlockByIDRequest) returns (BlockResponse)
1message GetBlockByIDRequest {2bytes id3}
1message BlockResponse {2flow.Block block3flow.BlockStatus block_status4}
GetBlockByHeight
gets a full block by height.
1rpc GetBlockByHeight (GetBlockByHeightRequest) returns (BlockResponse)
1message GetBlockByHeightRequest {2uint64 height3}
1message BlockResponse {2flow.Block block3flow.BlockStatus block_status4}
The following methods query information about collections.
GetCollectionByID
gets a collection by ID.
1rpc GetCollectionByID (GetCollectionByIDRequest) returns (CollectionResponse)
1message GetCollectionByIDRequest {2bytes id3}
1message CollectionResponse {2flow.Collection collection3}
The following methods can be used to submit transactions and fetch their results.
SendTransaction
submits a transaction to the network.
1rpc 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.
SendTransactionRequest
message contains the transaction that is being request to be executed.
1message SendTransactionRequest {2flow.Transaction transaction3}
SendTransactionResponse
message contains the ID of the submitted transaction.
1message SendTransactionResponse {2bytes id3}
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.
1rpc GetTransaction (GetTransactionRequest) returns (TransactionResponse)
GetTransactionRequest
contains the ID of the transaction that is being queried.
1message GetTransactionRequest {2bytes id3}
TransactionResponse
contains the basic information about a transaction, but does not include post-execution results.
1message TransactionResponse {2flow.Transaction transaction3}
GetTransactionResult
gets the execution result of a transaction.
1rpc GetTransactionResult (GetTransactionRequest) returns (TransactionResultResponse)
1message GetTransactionRequest {2bytes id3}
1message TransactionResultResponse {2flow.TransactionStatus status3uint32 status_code4string error_message5repeated flow.Event events6}
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.
1rpc GetAccount(GetAccountRequest) returns (GetAccountResponse)
1message GetAccountRequest {2bytes address3}
1message GetAccountResponse {2Account account3}
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.
1rpc GetAccountAtLatestBlock(GetAccountAtLatestBlockRequest) returns (AccountResponse)
1message GetAccountAtLatestBlockRequest {2bytes address3}
1message AccountResponse {2Account account3}
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.
1rpc GetAccountAtBlockHeight(GetAccountAtBlockHeightRequest) returns (AccountResponse)
1message GetAccountAtBlockHeightRequest {2bytes address3uint64 block_height4}
1message AccountResponse {2Account account3}
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.
1rpc ExecuteScriptAtLatestBlock (ExecuteScriptAtLatestBlockRequest) returns (ExecuteScriptResponse)
This method is a shortcut for the following:
1header = GetLatestBlockHeader()2value = ExecuteScriptAtBlockID(header.ID, script)
1message ExecuteScriptAtLatestBlockRequest {2bytes script3}
1message ExecuteScriptResponse {2bytes value3}
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.
1rpc ExecuteScriptAtBlockID (ExecuteScriptAtBlockIDRequest) returns (ExecuteScriptResponse)
1message ExecuteScriptAtBlockIDRequest {2bytes block_id3bytes script4}
1message ExecuteScriptResponse {2bytes value3}
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.
1rpc ExecuteScriptAtBlockHeight (ExecuteScriptAtBlockHeightRequest) returns (ExecuteScriptResponse)
1message ExecuteScriptAtBlockHeightRequest {2uint64 block_height3bytes script4}
1message ExecuteScriptResponse {2bytes value3}
The following methods can be used to query for on-chain events.
GetEventsForHeightRange
retrieves events emitted within the specified block range.
1rpc 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.
1message GetEventsForHeightRangeRequest {2string type3uint64 start_height = 2;4uint64 end_height = 3;5}
1message EventsResponse {2message Result {3bytes block_id = 1;4uint64 block_height = 2;5repeated entities.Event events = 3;6google.protobuf.Timestamp block_timestamp = 4;7}8repeated Result results = 1;9}
GetEventsForBlockIDs
retrieves events for the specified block IDs and event type.
1rpc 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.
1message GetEventsForBlockIDsRequest {2string type = 1;3repeated bytes block_ids = 2;4}
1message EventsResponse {2message Result {3bytes block_id = 1;4uint64 block_height = 2;5repeated entities.Event events = 3;6google.protobuf.Timestamp block_timestamp = 4;7}8repeated Result results = 1;9}
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
retrieves the network parameters.
1rpc GetNetworkParameters (GetNetworkParametersRequest) returns (GetNetworkParametersResponse)
1message GetNetworkParametersRequest {}
1message GetNetworkParametersResponse {2string chain_id = 1;3}
Field | Description |
---|---|
chain_id | Chain ID helps identify the Flow network. It can be one of flow-mainnet , flow-testnet or flow-emulator |
The following method can be used to query the latest protocol state snapshot.
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.
1rpc GetLatestProtocolStateSnapshot (GetLatestProtocolStateSnapshotRequest) returns (ProtocolStateSnapshotResponse);
1message GetLatestProtocolStateSnapshotRequest {}
1message ProtocolStateSnapshotResponse {2bytes serializedSnapshot = 1;3}
The following method can be used to query the for execution results for a given block.
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.
1rpc GetExecutionResultForBlockID(GetExecutionResultForBlockIDRequest) returns (ExecutionResultForBlockIDResponse);
1message GetExecutionResultForBlockIDRequest {2bytes block_id = 1;3}
1message ExecutionResultForBlockIDResponse {2flow.ExecutionResult execution_result = 1;3}
Below are in-depth descriptions of each of the data entities returned or accepted by the Access API.
1message Block {2bytes id3bytes parent_id4uint64 height5google.protobuf.Timestamp timestamp6repeated CollectionGuarantee collection_guarantees7repeated BlockSeal block_seals8repeated bytes signatures9}
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.
A block header is a summary of a block and contains only the block ID, height, and parent block ID.
1message BlockHeader {2bytes id3bytes parent_id4uint64 height5}
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 |
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.
1message BlockSeal {2bytes block_id3bytes execution_receipt_id4repeated bytes execution_receipt_signatures5repeated bytes result_approval_signatures6}
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 |
1enum BlockStatus {2UNKNOWN = 0;3FINALIZED = 1;4SEALED = 2;5}
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 |
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.
1message Collection {2bytes id3repeated bytes transaction_ids4}
Field | Description |
---|---|
id | SHA3-256 hash of the collection contents |
transaction_ids | Ordered list of transaction IDs in the collection |
A collection guarantee is a signed attestation that specifies the collection nodes that have guaranteed to store and respond to queries about a collection.
1message CollectionGuarantee {2bytes collection_id3repeated bytes signatures4}
Field | Description |
---|---|
collection_id | SHA3-256 hash of the collection contents |
signatures | BLS signatures of the collection nodes guaranteeing the collection |
A transaction represents a unit of computation that is submitted to the Flow network.
1message Transaction {2bytes script3repeated bytes arguments4bytes reference_block_id5uint64 gas_limit6TransactionProposalKey proposal_key7bytes payer8repeated bytes authorizers9repeated TransactionSignature payload_signatures10repeated TransactionSignature envelope_signatures11}1213message TransactionProposalKey {14bytes address15uint32 key_id16uint64 sequence_number17}1819message TransactionSignature {20bytes address21uint32 key_id22bytes signature23}
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.
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 |
Field | Description |
---|---|
address | Address of the account for this signature |
key_id | ID of the account key |
signature | Raw signature byte data |
1enum TransactionStatus {2UNKNOWN = 0;3PENDING = 1;4FINALIZED = 2;5EXECUTED = 3;6SEALED = 4;7EXPIRED = 5;8}
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. |
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.
1message Account {2bytes address3uint64 balance4bytes code5repeated AccountKey keys6map<string, bytes> contracts7}
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.
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.
1message AccountKey {2uint32 id3bytes public_key4uint32 sign_algo5uint32 hash_algo6uint32 weight7uint32 sequence_number8bool revoked9}
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.
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.
1message Event {2string type3bytes transaction_id4uint32 transaction_index5uint32 event_index6bytes payload7}
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 for a particular block.
1message ExecutionResult {2bytes previous_result_id3bytes block_id4repeated Chunk chunks5repeated ServiceEvent service_events6}
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 described execution information for given collection in a block
1message Chunk {2bytes start_state3bytes event_collection4bytes block_id5uint64 total_computation_used6uint64 number_of_transactions7uint64 index8bytes end_state9}
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 |
Special type of events emitted in system chunk used for controlling Flow system.
1message ServiceEvent {2string type;3bytes payload;4}
Field | Description |
---|---|
type | Type of an event |
payload | JSON-serialized content of an event |