Catchup API
Serves recent consensus state to allow peers to catch up with the network
The primary customer of this API is peer consensus nodes who may have recently joined the network or were temporarily disconnected. These nodes need the very latest state, one which hasn't even been finalized yet, in order to start voting and proposing in consensus.
In HotShot, all state required to participate is represented in the form of Merkle trees or Merkle tries, so this API is able to provide select segments of the state with a proof that will convince the client that the returned segment is accurate, as long as they know the corresponding state commitment.
Types
Account
Account
Endpoints
GET /catchup/:height/:view/account/:address
/catchup/:height/:view/account/:address
Get the balance of the requested fee account in the state from the requested consensus height and view. This is used to fetch the state for unfinalized views, to facilitate rapid catchup. If :view
has already been finalized, this endpoint may fail with error 404.
:height
and :view
must correspond! :height
is provided to simplify lookups for backends where data is not indexed by view.
Parameters
height
integer
The block height at which to look up the account balance
view
integer
The view from which to look up the account balance
address
hex
The account (Ethereum address) to look up
Returns Account
Account
POST /catchup/:height/:view/accounts
/catchup/:height/:view/accounts
Bulk version of /catchup/:height/:view/account
. The request body should be a JSON array consisting of TaggedBase64
-encoded fee accounts.
The response is a FeeMerkleTree
containing sub-trees for each of the requested accounts, which is
a more condensed way to represent the union of account proofs for each requested account. Individual
Merkle proofs for each account can be extracted from this tree.
:height
and :view
must correspond! :height
is provided to simplify lookups for backends where data is not indexed by view.
Parameters
height
integer
The block height at which to look up the account balance
view
integer
The view from which to look up the account balance
Returns FeeMerkleTree
FeeMerkleTree
GET /catchup/:height/:view/blocks
/catchup/:height/:view/blocks
Get the Merkle frontier (path to most recently inserted element) of the accumulator of blocks, from the requested consensus view. This is used to fetch the state for unfinalized views, to facilitate rapid catchup. If :view
has already been finalized, this endpoint may fail with error 404.
:height
and :view
must correspond! :height
is provided to simplify lookups for backends where data is not indexed by view.
Parameters
height
integer
The block height at which to look up the frontier
view
integer
The view from which to look up the frontier
Returns MerkleProof
MerkleProof
GET /catchup/chain-config/:commitment
/catchup/chain-config/:commitment
Get the chain config with the given hash.
Parameters
commitment
tagged<CHAIN_CONFIG>
The hash of the chain config to look up
Returns ChainConfig
GET /catchup/:height/leafchain
/catchup/:height/leafchain
Get a leaf chain which decides a specified block height. This endpoint can be used for catching up the stake table, where :height
is the block height of the epoch root you want to catch up to.
Parameters
height
integer
The block height decided by the desired leaf chain
Returns [Leaf]
GET /catchup/:height/:view/reward-account/:address
/catchup/:height/:view/reward-account/:address
Get the balance of the requested reward account in the state from the requested consensus height and view. This is used to fetch the state for unfinalized views, to facilitate rapid catchup. If :view
has already been finalized, this endpoint may fail with error 404.
:height
and :view
must correspond! :height
is provided to simplify lookups for backends where data is not indexed by view.
Parameters
height
integer
The block height at which to look up the account balance
view
integer
The view from which to look up the account balance
address
hex
The account (Ethereum address) to look up
Returns Account
Account
POST /catchup/:height/:view/reward-accounts
/catchup/:height/:view/reward-accounts
Bulk version of /catchup/:height/:view/reward-account
. The request body should be a JSON array consisting of TaggedBase64
-encoded fee accounts.
The response is a RewardsMerkleTree
containing sub-trees for each of the requested accounts, which is a more condensed way to represent the union of account proofs for each requested account. Individual Merkle proofs for each account can be extracted from this tree.
:height
and :view
must correspond! :height
is provided to simplify lookups for backends where data is not indexed by view.
Parameters
height
integer
The block height at which to look up the account balance
view
integer
The view from which to look up the account balance
Returns RewardsMerkleTree
RewardsMerkleTree
Last updated