Availability API
Serves data recorded by the Tiramisu DA layer, such as committed blocks
The availability API is the place to get onchain data, like blocks and transactions. It is the primary interface for downstream components like rollups and end users.
The API is designed to be robust and pure. Robust means that if the node hosting the API misses some data, for example from being offline when a certain block was finalized, it will automatically fetch the missing data from a peer, and will eventually fetch and store all finalized data. Pure means that each endpoint is a pure function -- with the exception of occasionally returning 404 for missing data, each endpoint will always give the same response given the same parameters.
Due to purity, this API provides no aggregate queries, like block or transaction counts, which might change as missing data is fetched. Likewise, every endpoint takes some specification of the exact point in the chain the client is looking for, like a block height or hash. There is no "latest block" query. Thus, most real-world use cases will need to complement the availability API with use of the node API.
Organization
While this API has many endpoints, don't be intimidated -- there is a method to the madness. The API is organized around collections of different resources, each of which corresponds to blocks and can be indexed by block height or hash.
Resources
Leaves
Headers
Blocks
Block summaries
Payloads
VID common
Indices
Each of these resources can be addressed in the following ways:
<resource>/:height
<resource>/hash/:hash
<resource>/payload-hash/:payload-hash
Not all of the indices are implemented for all resources, although in principle they can be. The supported indices are documented below for each endpoint. Future releases will fill in the missing functionality.
Leaves are currently indexed slightly differently from other resources. See documentation on leaf endpoints. Future versions of this API will merge the concept of a leaf and a header, resolving this discrepancy.
In addition, there are endpoints to fetch a range of each resource (<resource>/:form/:until
) and to subscribe to a WebSockets stream (/stream/<resource>/:from
).
Types
BlockSummary
BlockSummary
BlockResponse
BlockResponse
LeafResponse
LeafResponse
PayloadResponse
PayloadResponse
VidCommonResponse
VidCommonResponse
Endpoints
GET /availability/leaf
/availability/leaf
Paths
/availability/leaf/:height
/availability/leaf/hash/:hash
Parameters
Returns LeafResponse
LeafResponse
GET /availability/leaf/:from/:until
/availability/leaf/:from/:until
Retrieve a range of consecutive leaves.
Parameters
Returns [LeafResponse]
[LeafResponse]
GET /availability/stream/leaves/:height
/availability/stream/leaves/:height
This is a WebSockets endpoint. The client must be prepared to upgrade the connection to a WebSockets connection, including the proper headers.
Subscribe to a stream of leaves, in order, starting from the given height.
Parameters
Yields LeafResponse
LeafResponse
GET /availability/header
/availability/header
Paths
/availability/header/:height
/availability/header/hash/:hash
/availability/header/payload-hash/:payload-hash
Parameters
Returns Header
Header
GET /availability/header/:from/:until
/availability/header/:from/:until
Retrieve a range of consecutive headers.
Parameters
Returns [Header]
[Header]
GET /availability/stream/headers/:height
/availability/stream/headers/:height
This is a WebSockets endpoint. The client must be prepared to upgrade the connection to a WebSockets connection, including the proper headers.
Subscribe to a stream of headers, in order, starting from the given height.
Parameters
Yields Header
Header
GET /availability/block
/availability/block
Paths
/availability/block/:height
/availability/block/hash/:hash
/availability/block/payload-hash/:payload-hash
Parameters
Returns BlockResponse
BlockResponse
GET /availability/block/:from/:until
/availability/block/:from/:until
Retrieve a range of consecutive blocks.
Parameters
Returns [BlockResponse]
[BlockResponse]
GET /availability/stream/blocks/:height
/availability/stream/blocks/:height
This is a WebSockets endpoint. The client must be prepared to upgrade the connection to a WebSockets connection, including the proper headers.
Subscribe to a stream of blocks, in order, starting from the given height.
Parameters
Yields BlockResponse
BlockResponse
GET /availability/block/summary
/availability/block/summary
Paths
/availability/block/summary/:height
Parameters
Returns BlockSummary
BlockSummary
GET /availability/block/summaries/:from/:until
/availability/block/summaries/:from/:until
Retrieve a range of consecutive block summaries.
Parameters
Returns [BlockSummary]
[BlockSummary]
GET /availability/payload
/availability/payload
Paths
/availability/payload/:height
/availability/payload/block-hash/:block-hash
/availability/payload/hash/:hash
Parameters
Returns PayloadResponse
PayloadResponse
GET /availability/payload/:from/:until
/availability/payload/:from/:until
Retrieve a range of consecutive payloads.
Parameters
Returns [PayloadResponse]
[PayloadResponse]
GET /availability/stream/payloads/:height
/availability/stream/payloads/:height
This is a WebSockets endpoint. The client must be prepared to upgrade the connection to a WebSockets connection, including the proper headers.
Subscribe to a stream of payloads, in order, starting from the given height.
Parameters
Yields PayloadResponse
PayloadResponse
GET /availability/vid/common
/availability/vid/common
Paths
/availability/vid/common/:height
/availability/vid/common/hash/:hash
/availability/vid/common/payload-hash/:payload-hash
Parameters
Returns VidCommonResponse
VidCommonResponse
GET /availability/stream/vid/common/:height
/availability/stream/vid/common/:height
This is a WebSockets endpoint. The client must be prepared to upgrade the connection to a WebSockets connection, including the proper headers.
Subscribe to a stream of VID common objects, in order, starting from the given height.
Parameters
Yields VidCommonResponse
VidCommonResponse
GET /availability/block/:height/namespace/:namespace
/availability/block/:height/namespace/:namespace
Get the list of transactions in a block from a given namespace, along with a proof that these are only and all such transactions from that block. Note that the proof may be null
if transactions
is empty, in which case the caller should check the namespace table for the specified block to confirm that :namespace
is not present.
Parameters
Returns
GET /availability/transaction
/availability/transaction
Paths
/availability/transaction/:height/:index
/availability/transaction/hash/:hash
Parameters
Returns
The response contains the hash of the transaction, the hash and height of the block that contains it, and its index within that block. It also contains a TransactionInclusionProof
, which proves inclusion of this transaction in the block with block_hash
. The specific format of this type is not currently specified, but it can be deserialized and interpreted in Rust using the TxInclusionProof
type.
Last updated