LogoLogo
  • INTRODUCTION
  • LEARN
    • Espresso in the Modular Stack
    • The Espresso Network
      • System Overview
      • Properties of HotShot
        • EspressoDA
          • How It Works
      • Interfaces
        • Espresso ↔ Rollup
        • Espresso ↔ L1
        • Rollup ↔ L1
      • Internal Functionality
        • Espresso Node
        • Light Client Contract
        • Fee Token Contract
        • Stake Table
          • How the Stake Table Contract Works
        • Smart Contract Upgradeability
    • Rollup Stacks
      • Integrating a ZK Rollup
        • ZK Rollup Architecture
        • Using Espresso
        • Summary of Changes
      • Integrating an Optimistic Rollup
        • Optimistic Rollup Architecture
        • Using Espresso
        • Summary of Changes
  • Guides
    • Using the Espresso Network
      • Integrating Arbitrum Orbit Chain
        • Quickstart with Arbitrum Nitro Rollups
        • Reading Confirmations from the Espresso Network
        • Arbitrum Nitro Integration Overview
          • Using TEE with Nitro
          • Arbitrum Nitro Trust & Liveness Dependencies
        • Migrating Arbitrum Orbit Chains to Espresso
          • Arbitrum Testnet
            • Nitro Testnet
            • Local Deployment (`docker compose`)
      • Using the Espresso Network as a Cartesi application
    • Running an Espresso Node
    • Running a Builder
    • Bridging with the Espresso Network
  • API Reference
    • Espresso API
      • Status API
      • Catchup API
      • Availability API
      • Node API
      • State API
      • Events API
      • Submit API
      • Earlier Versions
        • v0
          • Status API
          • Catchup API
          • Availability API
          • Node API
          • State API
          • Events API
          • Submit API
    • Builder API
  • Releases
    • Mainnet 1
      • Running a Mainnet 1 Node
      • Contracts
      • Rollup Migration Guide
    • Mainnet 0
      • Running a Mainnet 0 Node
      • Contracts
    • Testnets
      • Decaf Testnet Release
        • Running a Node
        • Contracts
      • Cappuccino Testnet Release
        • Running a Node
        • Deploying a Rollup on Cappuccino
        • Benchmarks
      • Gibraltar Testnet Release
        • Interacting with Gibraltar
        • Arbitrum Nitro integration
        • Deploying a Rollup on Gibraltar
      • Cortado Testnet Release
        • Interacting with Cortado
        • OP Stack Integration
          • Optimism Leader Election RFP
      • Doppio Testnet Release
        • Interacting with Doppio
        • Polygon zkEVM Stack Integration
        • Minimal Rollup Example
        • Benchmarks
      • Americano Testnet Release
  • Appendix
    • Interacting with L1
      • Trustless Sync
      • Fork Recovery
      • Bridging
    • Glossary of Key Terms
Powered by GitBook
On this page
  • Types
  • Account
  • Endpoints
  • GET /catchup/:height/:view/account/:address
  • POST /catchup/:height/:view/accounts
  • GET /catchup/:height/:view/blocks
  • GET /catchup/chain-config/:commitment
  • GET /catchup/:height/leafchain
  • GET /catchup/:height/:view/reward-account/:address
  • POST /catchup/:height/:view/reward-accounts
  1. API Reference
  2. Espresso API

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 balance in WEI. Serialized as a hex string so as not to exceed the
    // range of JSON integers.
    "balance": hex,
    // Merkle proof justifying "balance" relative to the state commitment.
    "proof": {
        "account": hex,
        "proof":
            { "Presence": MerkleProof },
          | { "Absence": MerkleProof }
        }
    }       
}

Endpoints

GET /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

Name
Type
Description

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

POST /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

Name
Type
Description

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

GET /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

Name
Type
Description

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

GET /catchup/chain-config/:commitment

Get the chain config with the given hash.

Parameters

Name
Type
Description

commitment

tagged<CHAIN_CONFIG>

The hash of the chain config to look up

Returns ChainConfig

GET /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

Name
Type
Description

height

integer

The block height decided by the desired leaf chain

Returns [Leaf]

GET /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

Name
Type
Description

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

POST /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

Name
Type
Description

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

PreviousStatus APINextAvailability API

Last updated 1 month ago