State API

Serves consensus state derived from finalized blocks

All state derived from block data 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 (part of each block header).

Endpoints

GET /fee-state

Get a Merkle proof proving the balance of a certain fee account in a given snapshot of the state. The element in the returned Merkle proof contains the balance of the requested account, or null if the account has no balance.

Paths

• /fee-state/:height/:account

• /fee-state/commit/:commit/:account

Parameters

Name	Type	Description
height	integer	Block height of the state snapshot to read from
commit	tagged<MERKLE_COMM>	Commitment of the state snapshot to read from
account	hex	Fee account to look up

Returns MerkleProof

GET /fee-state/block-height

The latest block height for which fee state is available.

Note that this may be less than the block height indicated by other APIs, such as status or node, since the fee state storage is updated asynchronously.

Returns integer

GET /fee-state/fee-balance/latest/:account

Convenience endpoint to get the current balance of an account from a trusted node.

Name	Type	Description
account	hex	Fee account to look up

Returns the balance as a plain integer, without proof.

GET /block-state

Get a Merkle proof proving the inclusion of a certain block at a position in the history. The element in the returned Merkle proof contains the commitment of the block at the requested position in history.

Paths

• /block-state/:height/:index

• /block-state/commit/:commit/:index

Parameters

Name	Type	Description
height	integer	Block height of the state snapshot to read from
commit	tagged<MERKLE_COMM>	Commitment of the state snapshot to read from
index	integer	Height of the block to look up

Returns MerkleProof

GET /block-state/block-height

The latest block height for which block state is available.

Note that this may be less than the block height indicated by other APIs, such as status or node, since the block state storage is updated asynchronously.

Returns integer

Reward State

The reward state API has two versions:

• Protocol V3: Uses reward state v1 with SHA3 hashing (RewardMerkleTreeV1)

• Protocol V4+: Uses reward state v2 with Keccak256 hashing (RewardMerkleTreeV2)

GET /reward-state

Get a Merkle proof proving the balance of a certain reward account in a given snapshot of the state. The element in the returned Merkle proof contains the balance of the requested account, or null if the account has no balance.

This endpoint returns a V1 Merkle tree proof.

Paths

• /reward-state/:height/:account

• /reward-state/commit/:commit/:account

Parameters

Name	Type	Description
height	integer	Block height of the state snapshot to read from
commit	tagged<MERKLE_COMM>	Commitment of the state snapshot to read from
account	hex	Reward account to look up

Returns MerkleProof

GET /reward-state/block-height

The latest block height for which reward state is available.

Note that this may be less than the block height indicated by other APIs, such as status or node, since the reward state storage is updated asynchronously.

Returns integer

GET /reward-state/proof/:height/:address

Get the Merkle proof for a reward account at a given block height. Returns a RewardAccountQueryDataV1 type, containing the balance and a RewardAccountProofV1. This proof is based on RewardMerkleTreeV1, which uses the SHA3 hashing algorithm.

Parameters

Name	Type	Description
height	integer	Block height to get proof for
address	hex	Account address to get proof for

Returns RewardAccountQueryDataV1

{
  "balance": "0x...",
  "proof": {
    "account": "0x...",
    "proof": { /* merkle proof */ }
  }
}

RewardAccountQueryDataV1 fields:

Field	Type	Description
balance	U256	The reward account balance
proof	RewardAccountProofV1	Merkle proof for the account

RewardAccountProofV1 fields:

Field	Type	Description
account	Address	The reward account address
proof	RewardMerkleProofV1	Merkle proof using SHA3 hashing

Reward State V2

Reward state v2 is used by consensus protocol V4 and above which uses Keccak256 based Merkle proofs for improved compatibility with Ethereum smart contracts.

GET /reward-state-v2

Get a Merkle proof proving the balance of a certain reward account in a given snapshot of the state. The element in the returned Merkle proof contains the balance of the requested account, or null if the account has no balance.

Paths

• /reward-state-v2/:height/:account

• /reward-state-v2/commit/:commit/:account

Parameters

Name	Type	Description
height	integer	Block height of the state snapshot to read from
commit	tagged<MERKLE_COMM>	Commitment of the state snapshot to read from
account	hex	Reward account to look up

Returns MerkleProof

GET /reward-state-v2/block-height

The latest block height for which reward state v2 is available.

Note that this may be less than the block height indicated by other APIs, such as status or node, since the reward state storage is updated asynchronously.

Returns integer

GET /reward-state-v2/reward-balance/latest/:address

Get current balance in reward state.

Parameters

Name	Type	Description
address	hex	Ethereum address in hex format

Returns

The current reward balance as an integer.

GET /reward-state-v2/reward-balance/:height/:address

Get balance in reward state at a specific height.

Parameters

Name	Type	Description
height	integer	Block height to query
address	hex	Ethereum address in hex format

Returns

The reward balance at the specified height as an integer.

GET /reward-state-v2/proof/:height/:address

Get the Merkle proof for a reward account at a given block height. Returns a RewardAccountQueryDataV2 type, containing the balance and a RewardAccountProofV2. This proof is based on RewardMerkleTreeV2, which uses the Keccak256 hashing algorithm.

Parameters

Name	Type	Description
height	integer	Block height of proof for
address	hex	Account address to get proof for

Returns RewardAccountQueryDataV2

{
  "balance": "0x...",
  "proof": {
    "account": "0x...",
    "proof": {
      "Presence": { /* membership proof */ }
    }
  }
}

RewardAccountQueryDataV2 fields:

Field	Type	Description
balance	U256	The reward account balance
proof	RewardAccountProofV2	Merkle proof for the account

RewardAccountProofV2 fields:

Field	Type	Description
account	Address	The reward account address
proof	RewardMerkleProofV2	Merkle proof

RewardMerkleProofV2 is an enum with two variants:

• Presence: Merkle proof demonstrating account membership in the tree

• Absence: Merkle proof demonstrating account non-membership in the tree

GET /reward-state-v2/reward-claim-input/:height/:address

Get the reward claim input data formatted for use with Solidity reward claim contracts. This endpoint is only available for consensus protocol V4+.

Parameters

Name	Type	Description
height	integer	Espresso block height (must match Light Client finalized height)
address	hex	Account address to generate claim input for

Returns RewardClaimInput

{
  "lifetime_rewards": "0x...",
  "auth_data": {
    // Authentication data including Merkle proof
  }
}

Field	Type	Description
lifetime_rewards	U256	Total lifetime rewards for the account
auth_data	RewardAuthData	Merkle proof and authentication data for on-chain verification

• The height parameter must match the finalized block height in the Light Client contract

• Returns error if the account has zero rewards

• The returned data is formatted to be passed directly to reward claim contract functions

Error

• ZeroRewardError: Account has no rewards to claim

• Conversion Error: Failed to convert proof to claim input format