availability API 0.0.1 Reference

HotShot chain state

The availability API provides an objective view of the HotShot blockchain. It provides access only to normative data: that is, data which is agreed upon by all honest consensus nodes and which is immutable. This means access to core consensus data structures including leaves, blocks, and headers, where each query is pure and idempotent. This also means that it is possible for a client to verify all of the information provided by this API, by running a HotShot light client and downloading the appropriate evidence with each query.

This API does not provide any queries which represent only the current state of the chain or may change over time, and it does not provide information for which there is not (yet) agreement of a supermajority of consensus nodes. For information about the current dynamic state of consensus and uncommitted state, try the status API. For information about the chain which is tabulated by this specific node and not subject to full consensus agreement, try the node API.

GET get_block_summary

Routes

/hotshot-availability/block/summary/:height

Parameters

height

Integer

Description

Get the Block Summary for a block based on its position in the ledger.

GET get_leaf

Routes

/hotshot-availability/leaf/:height

/hotshot-availability/leaf/hash/:hash

Parameters

hash	TaggedBase64
height	Integer

Description

Get a leaf by its position in the ledger (0 is the genesis leaf) or its hash.

Returns

{
    "leaf": {
        "view_number": integer,
        "justify_qc": QC,
        "parent_commitment": TaggedBase64,
        "block_header": app-specific header type,
        "proposer_id": TaggedBase64,
    },
    "qc": QC,
}

Note that leaf.justify_qc is the quorum certificate linking this leaf to its parent, while qc is the quorum certificate signing this leaf. Both QCs have the schema

{
    "block_commitment": TaggedBase64,
    "leaf_commitment": TaggedBase64,
    "view_number": integer,
    // Map from signing keys to (signature, vote) pairs
    "signatures": {TaggedBase64: [TaggedBase64, TaggedBase64]},
    genesis: boolean,
}

SOCKET stream_payloads

Routes

/hotshot-availability/stream/payloads/:height

Parameters

height

Integer

Description

Subscribe to a stream of block payloads in the order they are sequenced, starting at :height.

Opens a WebSockets connection and sends a stream of the same data type returned by payload/:height.

SOCKET stream_blocks

Routes

/hotshot-availability/stream/blocks/:height

Parameters

height

Integer

Description

Subscribe to a stream of blocks in the order they are sequenced, starting at :height.

Opens a WebSockets connection and sends a stream of the same data type returned by block/:height.

GET get_header_range

Routes

/hotshot-availability/header/:from/:until

Parameters

from	Integer
until	Integer

Description

Get the headers based on their position in the ledger, the headers are taken starting from the given :from up until the given :until.

The allowable length of the requested range may be restricted by an implementation-defined limit (see /limits). Requests for ranges exceeding these limits will fail with a 400 status code.

GET get_payload_range

Routes

/hotshot-availability/payload/:from/:until

Parameters

until	Integer
from	Integer

Description

Get the payloads of blocks based on their position in the ledger, the payloads are taken starting from the given :from up until the given :until.

The allowable length of the requested range may be restricted by an implementation-defined limit (see /limits). Requests for ranges exceeding these limits will fail with a 400 status code.

GET get_stake_table

Routes

/hotshot-availability/stake-table/:height

/hotshot-availability/stake-table/view/:view_number

Parameters

view_number	Integer
height	Integer

Description

Get the stake table after :height leaves or after :view_number.

Returns a map from staking public keys to amounts.

GET get_vid_common

Routes

/hotshot-availability/vid/common/:height

/hotshot-availability/vid/common/hash/:hash

/hotshot-availability/vid/common/payload-hash/:payload-hash

Parameters

payload-hash	TaggedBase64
height	Integer
hash	TaggedBase64

Description

Get common VID data.

Only data common to all storage nodes is provided. This is not a VID share and does not help in the reconstruction of a block. It is only useful to aid in the interpretation of other VID-related data, such as VID range proofs.

To recover the VID share belonging to this node, see the node API endpoint /node/vid/share.

GET get_payload

Routes

/hotshot-availability/payload/:height

/hotshot-availability/payload/hash/:hash

/hotshot-availability/payload/block-hash/:block-hash

Parameters

height	Integer
hash	TaggedBase64
block-hash	TaggedBase64

Description

Get the payload of a block by its position in the ledger (0 is the genesis block) or its hash.

GET get_header

Routes

/hotshot-availability/header/:height

/hotshot-availability/header/hash/:hash

/hotshot-availability/header/payload-hash/:payload-hash

Parameters

height	Integer
hash	TaggedBase64
payload-hash	TaggedBase64

Description

Get a header by its position in the ledger (0 is the genesis block) or its hash.

Returns an application-specific header type.

GET get_leaf_range

Routes

/hotshot-availability/leaf/:from/:until

Parameters

until	Integer
from	Integer

Description

Get the leaves based on their position in the ledger, the leaves are taken starting from the given :from up until the given :until.

The allowable length of the requested range may be restricted by an implementation-defined limit (see /limits). Requests for ranges exceeding these limits will fail with a 400 status code.

GET get_block

Routes

/hotshot-availability/block/:height

/hotshot-availability/block/hash/:hash

/hotshot-availability/block/payload-hash/:payload-hash

Parameters

hash	TaggedBase64
height	Integer
payload-hash	TaggedBase64

Description

Get a block by its position in the ledger (0 is the genesis block) or its hash.

Note that block data in HotShot disseminates asynchronously. That means that the full data for a block may not be available immediately after that block is committed. In this situation, leaf/i may succeed but block/i may fail. However, once leaf/i succeeds, it is guaranteed that block/i will eventually succeed, and return a block whose hash is the same as the block_hash from the corresponding leaf.

Returns

{
    "header": application-specific header type,
    "payload": application-specific payload type,
    "hash": TaggedBase64,
    "size": integer,
}

SOCKET stream_leaves

Routes

/hotshot-availability/stream/leaves/:height

Parameters

height

Integer

Description

Subscribe to a stream of leaves in the order they are sequenced, starting at :height.

Opens a WebSockets connection and sends a stream of the same data type returned by leaf/:height.

GET get_block_summary_range

Routes

/hotshot-availability/block/summaries/:from/:until

Parameters

until	Integer
from	Integer

Description

Get the Block Summary entries for blocks based on their position in the ledger, the blocks are taken starting from the given :from up until the given :until.

The allowable length of the requested range may be restricted by an implementation-defined limit (see /limits). Requests for ranges exceeding these limits will fail with a 400 status code.

SOCKET stream_headers

Routes

/hotshot-availability/stream/headers/:height

Parameters

height

Integer

Description

Subscribe to a stream that returns the metadata of available blocks, starting at :height. Useful for applications like rollups that do not need to fetch the entire block.

Opens a WebSocket connection and sends a stream of application-specific headers.

GET get_block_range

Routes

/hotshot-availability/block/:from/:until

Parameters

until	Integer
from	Integer

Description

Get the blocks based on their position in the ledger, the blocks are taken starting from the given :from up until the given :until.

The allowable length of the requested range may be restricted by an implementation-defined limit (see /limits). Requests for ranges exceeding these limits will fail with a 400 status code.

GET get_limits

Routes

/hotshot-availability/limits

Parameters

None

Description

Get implementation-defined limits restricting certain requests.

small_object_range_limit: the maximum number of small objects which can be loaded in a single range query.

Currently small objects include leaves only. In the future this limit will also apply to headers, block summaries, and VID common, however
- loading of headers and block summaries is currently implemented by loading the entire block
- imperfect VID parameter tuning means that VID common can be much larger than it should
large_object_range_limit: the maximum number of large objects which can be loaded in a single range query.

Large objects include anything that might contain a full payload or an object proportional in size to a payload. Note that this limit applies to the entire class of objects: we do not check the size of objects while loading to determine which limit to apply. If an object belongs to a class which might contain a large payload, the large object limit always applies.

Returns

{
    "large_object_range_limit": integer,
    "small_object_range_limit": integer
}

GET get_transaction

Routes

/hotshot-availability/transaction/:height/:index

/hotshot-availability/transaction/hash/:hash

Parameters

height	Integer
index	Integer
hash	TaggedBase64

Description

Get a transaction by its index in the block at height or by its hash.

If specified, :height and :index represent the block containing the transaction and the index of the transaction within the block, respectively. Otherwise, :hash is the hash of the transaction.

HotShot consensus does not validate the transactions it sequences, and in particular it does not prohibit duplicate transactions. While each transaction has a unique position in the log (indicated by its height and index) there may be multiple transactions at different positions with the same hash. In such cases, this endpoint will return the earliest transaction with the requested hash.

The response includes the hash of the block containing this transaction as well as an application- defined inclusion proof relative to the block hash. Applications may use proof to prove that the returned transaction is actually a member of its block, but note that the proof system used here will vary by application. Some may prove more (for example, a shared sequencer proving that the transaction belongs not only to the block but to a section of the block dedicated to a specific rollup), some may prove less (for example, a trusted query service may return null for the proof).

Returns

{
    "transaction": application-specific transaction type,
    "index": integer,
    "hash": TaggedBase64,
    "proof": application-specific proof type,
    "block_hash": TaggedBase64,
    "block_height": integer,
}

GET getnamespaceproof

Routes

/hotshot-availability/block/:height/namespace/:namespace

Parameters

namespace	Integer
height	Integer

Description

Get the transactions in a namespace of the given block, along with a proof.

SOCKET stream_vid_common

Routes

/hotshot-availability/stream/vid/common/:height

Parameters

height

Integer

Description

Subscribe to a stream of VID common data in the order they are sequenced, starting at :height.

Opens a WebSockets connection and sends a stream of the same data type returned by vid/common/:height.