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
  • Modularity
  • Content Types
  • Server-Hosted Documentation
  • Versioning and Stability
  • Version Support
  • Types
  • Primitives
  • NamespaceTable
  • ChainConfig
  • Header
  • Payload
  • VidCommon
  • Leaf
  • Transaction
  • MerkleProof
  • NsIndex
  • NsProof
  1. API Reference

Espresso API

Reference for REST APIs served by Espresso nodes and query services

PreviousBridging with the Espresso NetworkNextStatus API

Last updated 1 month ago

Modularity

The Espresso API comprises several independent modules serving different purposes and requiring different resources. A given node may serve one, or all, or any combination of these modules, depending on its role in the system and the resources available to it. To see a list of the modules available from a particular node, navigate to the root URL of that node's API.

In brief, the available API modules are:

  • Status API: node-specific state and consensus metrics

  • Catchup API: serves recent consensus state to allow peers to catch up with the network

  • Availability API: serves data recorded by the , such as committed blocks

  • Node API: complements the availability API by serving eventually consistent data that is not (yet) necessarily agreed upon by all nodes

  • State API: serves consensus state derived from finalized blocks

  • Events API: streams events from HotShot

  • Submit API: allows users to submit transactions to the public mempool

Content Types

All APIs support JSON and binary formats in both request and response bodies.

  • The JSON format is a straightforward serialization of the data types used internally by consensus nodes. In the future, a formal specification will be published, and the API will conform to that specification.

  • The binary format is the serialization of consensus data types, prefixed with an 8-byte version header. In the future, this will be replaced with a binary format with better cross-language support, and the data types will be defined by a published schema, rather than generated from code.

In requests and responses, the JSON format is denoted by the MIME type application/json, and the binary format by application/octet-stream. For requests with a body, the content type of the body must be set via the Content-Type header. The desired content type of the response can be controlled via the Accept header of the request. If the Accept header does not preference either format, JSON will be used by default.

Server-Hosted Documentation

All Espresso API servers provide self-hosted API documentation, which makes it easy to see exactly what APIs the server supports, and can be easier to browse than these docs. The root URL of an application, e.g. my-server.xyz, lists the supported API modules and versions. Clicking on any API module, or navigating to the root of that API, e.g. my-server.xyz/status, documents the endpoints available in that module.

Versioning and Stability

A node may serve multiple major versions of a given API at the same time. The desired version can be selected via a URL prefix. For example, my-server.xyz/v0/status/metrics and my-server.xyz/v1/status/metrics both hit the same endpoint, but in different API versions. A URL with no version segment will get a permanent redirect response to the latest supported version. In this case, /status/metrics would redirect to /v1/status/metrics.

Whenever a breaking change is made to an API, a new major version will be created, and the old version will continue to be served for some time, giving clients time to upgrade to the new version whenever it is convenient for them. Note that non-breaking changes, such as adding new endpoints, may be made in place to existing versions.

To see a list of versions of an API supported by a server, visit the root URL of that server.

Version Support

Version
Status
Comment

v1

available on testnet April 15, 2025

Some APIs are changed and some endpoints added to support proof of stake

v0

latest version

Types

These types are used in requests and responses across many of the API modules.

Primitives

Integer

We use integer to represent any JSON integer, with a maximum size of at least 2^63 - 1. Of special note, byte arrays are sometimes represented as arrays of integers ([integer]). When the type [integer] is used as a byte array, each integer therein is restricted to the range [0, 255].

Hex

In the following, we use the type hex to indicate a hex-encoded binary string, with 0x prefix.

Base 64

In the following, we use the type base64 to indicate a base64-encoded binary string, using the standard base 64 alphabet with padding.

Tagged Base 64

For example, a transaction hash might be encoded like TX~QDuwVkmexu1fWgJbjxshXcGqXku838Pa9cTn0d-v3hZ-, while a block hash could look like BLOCK~00ISpu2jHbXD6z-BwMkwR4ijGdgUSoXLp_2jIStmqBrD.

We use the type tagged<TAG> to indicate a tagged base 64 object with the given tag, as in tagged<TX> or tagged<BLOCK>.

NamespaceTable

{
    "bytes": base64
}

ChainConfig

A chain config determines properties of consensus, such as the base fee for sequencing and the chain ID. To save space, it can be represented either as the full config object (Left variant below) or as a commitment to the chain config (Right variant). The genesis header will always contain the full config, so clients can fetch the full config from genesis and then compare its commitment against any other header.

{
    "chain_config": 
        { "Left": { "chain_id": hex, "max_block_size": integer, "base_fee": hex } }
        | { "Right": tagged<CHAIN_CONFIG> }
}

Header

{
    "version": {
        "Version": {
            "major": integer,
            "minor": integer
        }
    },
    "fields": {
        "height": integer,
        "timestamp": integer,
        "l1_head": integer,
        "l1_finalized": null | {
            "number": integer,
            "timestamp": hex,
            "hash": hex
        },
        "payload_commitment": tagged<HASH>,
        "builder_commitment": tagged<BUILDER_COMMITMENT>,
        "ns_table": NamespaceTable,
        "block_merkle_tree_root": tagged<MERKLE_COMM>,
        "fee_merkle_tree_root": tagged<MERKLE_COMM>,
        "reward_merkle_tree_root": tagged<MERKLE_COMM>,
        "fee_info": { "account": hex, "amount": hex },
        "chain_config": ChainConfig
    }
}

Payload

{
    "raw_payload": base64,
    "ns_table": NamespaceTable
}

VidCommon

{
    "V0": {
        "poly_commits": tagged<FIELD>,
        "all_evals_digest": tagged<FIELD>,
        "payload_byte_len": integer,
        "num_storage_nodes": integer,
        "multiplicity": integer
    }
} | {
    "V1": {
        "total_weights": integer,
        "recovery_threshold": integer
    }  
}

Leaf

{
    "view_number": integer,
    "justify_qc": QC,
    "next_epoch_justify_qc": null | NextEpochQC,
    "parent_commitment": string,
    "block_header": Header,
    "upgrade_certificate": null | UpgradeCertificate,
    "view_change_evidence": null | ViewChangeEvidence,
    "next_drb_result": null | DrbResult,
    "with_epoch": bool
}

Transaction

{
    "namespace": integer,
    "payload": base64
}

MerkleProof

NsIndex

NsProof

A proof that a certain list of transactions corresponds to a certain namespace in a block.

{
    "V0": {
        "ns_index": NsIndex,
        "ns_payload": base64, // binary encoding of the namespace data
        "ns_proof": {
            "prefix_elems": tagged<FIELD>,
            "suffix_elems": tagged<FIELD>,
            "prefix_bytes": [integer],
            "suffix_bytes": [integer]
        }
    }
} | {
    "V1": {
        "ns_index": NsIndex,
        "ns_payload": [integer],
        "ns_proof": MerkleProof
    }   
}

This guide documents the most recent version v1, but archive API references are available for .

Some types use an enhanced encoding, which consists of a prefix identifying the type of the encoded object, a ~, and then a base 64 string using the URL-safe base 64 alphabet without padding. The base 64 string encodes the binary representation of a typed object, plus a checksum. Because the encoding is URL-safe, these strings can be used not only in request and response bodies, but also in URL paths. The checksum allows the server to provide useful errors if a tagged base 64 string is mistyped or corrupted. The tag makes it easy for a human to tell different types of objects apart.

If using the Rust API, you may notice that is represented by a u64. However, some internal sub-protocols represent the namespace as a u32, and thus the maximum allowable namespace ID is 4294967295 (2^32 - 1). Larger namespace IDs will be rejected on transaction submission.

The low-level proof type for a Merklized data structure. The specific format of this type is not currently specified, but it can be deserialized and interpreted in Rust using the type.

The 0-based position of a namespace in a . The index is a little-endian byte-encoded 4-byte integer, as in [3, 2, 1, 255] (0xff010203).

V0.ns_proof is a low-level range proof in the Espresso ADVZ VID scheme. The details of this proof are out of scope of this document, but this JSON object corresponds to the , and can be manipulated in Rust using that type.

Tiramisu DA layer
bincode
earlier supported versions
tagged base 64
namespace
MerkleProof
LargeRangeProofType
NamespaceTable