node API 0.0.1 Reference

A node’s view of a HotShot chain

The node API provides a subjective view of the HotShot blockchain, from the perspective of one particular node. It provides access to information that the availability API does not, because this information depends on the perspective of the node observing it, and may be subject to eventual consistency. For example, /node/block-height may return smaller counts than expected, if the node being queried is not fully synced with the entire history of the chain. However, the node will eventually sync and return the expected counts. See /node/sync-status for information on how in or out of sync the node currently is.

GET sync_status

Routes

/hotshot-node/sync-status

Parameters

None

Description

Get the node’s progress in syncing with the latest state of the blockchain.

Returns

{
    "missing_blocks": integer,
    "missing_leaves": integer,
    "missing_vid_common": integer,
    "missing_vid_shares": integer,
    "pruned_height": null | integer,
}

GET get_vid_share

Routes

/hotshot-node/vid/share/:height

/hotshot-node/vid/share/hash/:hash

/hotshot-node/vid/share/payload-hash/:payload-hash

Parameters

hash	TaggedBase64
payload-hash	TaggedBase64
height	Integer

Description

Get information needed to run the VID reconstruction protocol for a block.

Returns this node’s VID share, if available.

GET get_limits

Routes

/hotshot-node/limits

Parameters

None

Description

Get implementation-defined limits restricting certain requests.

window_limit: the maximum number of headers which can be loaded in a single header/window query.

Returns

{
    "window_limit": integer
}

GET payload_size

Routes

/hotshot-node/payloads/size

/hotshot-node/payloads/size/:to

/hotshot-node/payloads/size/:from/:to

/hotshot-node/payloads/total-size

Parameters

from	Integer
to	Integer

Description

Get the size (in bytes) of all payload data in the chain.

If :from or :to is specified, they restrict the range of blocks considered. payloads/size/:to will return the cumulative size of all payloads in blocks up to and including block number :to, while payloads/size/:from/:to will return the cumulative size in all blocks between :from (inclusive) and :to (inclusive).

payloads/total-size is a deprecated alias for payloads/size.

Returns an integer.

GET get_header_window

Routes

/hotshot-node/header/window/:start/:end

/hotshot-node/header/window/from/:height/:end

/hotshot-node/header/window/from/hash/:hash/:end

Parameters

start	Integer
height	Integer
end	Integer
hash	TaggedBase64

Description

Get block headers in a time window.

Returns all available headers, in order, whose timestamps fall between :start (inclusive) and :end (exclusive), or between the block indicated by :height or :hash (inclusive) and :end (exclusive). The response also includes one block before the desired window (unless the window includes the genesis block) and one block after the window. This proves to the client that the server has not omitted any blocks whose timestamps fall within the desired window.

It is possible that not all blocks in the desired window are available when this endpoint is called. In that case, whichever blocks are available are included in the response, and next is null to indicate that the response is not complete. The client can then use one of the /from/ forms of this endpoint to fetch the remaining blocks from where the first response left off, once they become available. If no blocks are available, not even prev, this endpoint will return an error.

It is also possible that the number of blocks returned may be restricted by an implementation- defined limit (see /limits), even if subsequent blocks within the window are currently available. In this case, next will be null and the client should call again using one of the /from/ forms to get the next page of results, exactly as in the case where some blocks in the window have yet to be produced.

Returns

{
    "window": ["Header"],
    "prev": "Header", // nullable
    "next": "Header"  // nullable
}

All timestamps are denominated in an integer number of seconds.

GET count_transactions

Routes

/hotshot-node/transactions/count

/hotshot-node/transactions/count/:to

/hotshot-node/transactions/count/:from/:to

Parameters

from	Integer
to	Integer

Description

Get the number of transactions in the chain.

If :from or :to is specified, they restrict the range of blocks considered. transactions/count/:to will return the number of transactions in all blocks up to and including block number :to, while transactions/count/:from/:to will count the transactions in all blocks between :from (inclusive) and :to (inclusive).

Returns an integer.

GET block_height

Routes

/hotshot-node/block-height

Parameters

None

Description

The current height of the chain, as observed by this node.

Returns an integer.