Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Proof API is a gRPC service that sits between the relayer and the attestors. The relayer does not build relay transactions itself; it calls the Proof API with a source transaction hash, and the Proof API returns a fully constructed, ready-to-submit transaction for the destination chain. Image: ghcr.io/cosmos/proof-api, see releases for available tags
To see the Proof API running as part of a full IBC setup, follow the Cosmos ↔ EVM Interoperability Tutorial.

​
What it does

When the relayer identifies a packet that needs relaying, it calls the Proof API’s RelayByTx RPC with the source transaction hash, source and destination chain IDs, and the relevant IBC client IDs. The following example illustrates the flow for attestor-based light clients, but the proof API also constructs transactions for the relayer for transfers involving other light client types. The Proof API:
  1. Queries the source chain RPC for the transaction and parses its IBC events
  2. Calls each configured attestor’s gRPC endpoint to collect cryptographic attestations of the source chain state
  3. Aggregates attestor signatures until the quorum threshold is met
  4. Constructs the full relay transaction: updateClient + RecvPacket (or AckPacket / Timeout) with proofs embedded
  5. Returns the serialized transaction bytes to the relayer, which signs and submits them
The Proof API constructs but does not sign or submit transactions. The relayer handles submission.

​
Module system

The Proof API is configured with a list of modules. Each module handles one transfer direction as a single (src_chain, dst_chain) pair. When RelayByTx is called, the Proof API routes the request to the module whose src_chain and dst_chain match. Each module needs access to both chain RPC endpoints regardless of direction, because it reads source chain state and submits to the destination chain.

​
Configuration

The Proof API is configured via a JSON file (conventionally named relayer.json), passed via --config.

​
Full configuration reference

The following is the example config template used in the IBC demo (ibc/proof-api.json.tmpl): 
{
  "server": {"log_level": "info", "address": "0.0.0.0", "port": 9090},
  "modules": [
    {
      "name": "cosmos_to_eth",
      "src_chain": "cosmos-1",
      "dst_chain": "32382",
      "config": {
        "tm_rpc_url": "http://cosmos:26657",
        "ics26_address": "0x9fe46736679d2d9a65f0992f2272de9f3c7fa6e0",
        "eth_rpc_url": "http://besu:8545",
        "signer_address": "cosmos1zj8jljx8rwyhfp36cmp0u5jqa98af8ehnv8463",
        "mode": {"attested": {
          "attestor": {
            "quorum_threshold": 1,
            "attestor_endpoints": ["http://attestor-cosmos:9101"],
            "attestor_query_timeout_ms": 10000
          }
        }}
      }
    },
    {
      "name": "eth_to_cosmos",
      "src_chain": "32382",
      "dst_chain": "cosmos-1",
      "config": {
        "tm_rpc_url": "http://cosmos:26657",
        "ics26_address": "0x9fe46736679d2d9a65f0992f2272de9f3c7fa6e0",
        "eth_rpc_url": "http://besu:8545",
        "signer_address": "cosmos1zj8jljx8rwyhfp36cmp0u5jqa98af8ehnv8463",
        "mode": {"attested": {
          "attestor": {
            "quorum_threshold": 1,
            "attestor_endpoints": ["http://attestor:9101"],
            "attestor_query_timeout_ms": 10000
          }
        }}
      }
    }
  ]
}

​
server

FieldDescription
log_levelLog verbosity: "info", "debug", or "warn"
addressBind address for the gRPC server
portgRPC port the relayer connects to

​
modules[]

FieldDescription
nameModule identifier — used in logs and metrics
src_chainChain ID of the source chain (where the packet originates)
dst_chainChain ID of the destination chain (where the relay transaction is submitted)
configDirection-specific configuration

​
config (per module)

FieldRequiredDescription
tm_rpc_urlYesTendermint RPC endpoint of the Cosmos chain
eth_rpc_urlYesJSON-RPC endpoint of the EVM chain
ics26_addressYesAddress of the deployed ICS26Router contract on the EVM chain
signer_addressYesBech32 address of the Cosmos account that will sign relay transactions. Used when building Cosmos-destination transactions.
modeYesProof construction mode

​
mode

Modes are defined per module and determine how proofs are generated. For use with the attestation light client, the attested mode is used. It instructs the Proof API to collect attestor signatures rather than generate cryptographic proofs.
FieldDescription
quorum_thresholdMinimum number of attestors that must return valid signatures. Must match min_required_sigs in the light client.
attestor_endpointsList of attestor gRPC endpoints to query. Each entry should point to the attestor watching the source chain for that module.
attestor_query_timeout_msMaximum time in milliseconds to wait for each attestor response
Other modes exist for different proof systems. For example, sp1 (ZK proofs via the SP1 zkVM) in cosmos-to-eth and real (Ethereum beacon chain proofs) in eth-to-cosmos.

​
Running the Proof API

​
Startup order

The Proof API depends on the attestors being available (it queries them on every request). The relayer depends on the Proof API. The required startup order is: 
attestors → Proof API → relayer

​
Deployment

The Proof API is generally run with the relayer. The proof-api binary is distributed as a Docker image (ghcr.io/cosmos/proof-api). The following is the service definition from the IBC demo’s docker-compose.yml: 
proof-api:
  image: ghcr.io/cosmos/proof-api:latest
  volumes:
    - ./ibc/local/relayer.json:/usr/local/relayer/relayer.json:ro
  depends_on:
    attestor:
      condition: service_started
    attestor-cosmos:
      condition: service_started
  restart: on-failure
The config file is mounted at /usr/local/relayer/relayer.json inside the container. For a full walkthrough of how the Proof API is deployed alongside the relayer, see the Configure and Start the Relayer and Proof API step of the IBC demo.

​
Relationship to the relayer and attestors

relayer
  └─► Proof API (gRPC RelayByTx)
        └─► attestors (one per source chain)
              └─► chain RPC nodes
The relayer calls RelayByTx on the Proof API. The Proof API calls attestors over gRPC to collect signatures. Attestors read chain state directly from the chain RPC nodes. The relayer points to the Proof API via ibcv2_proof_api.grpc_address in its config. See the relayer configuration reference for details.

​
Applying this to your own setup

​
Quorum threshold

quorum_threshold must match the min_required_sigs value configured in the light client. If the light client requires 2 signatures but the Proof API only collects 1, the relay transaction will be rejected on-chain.

​
Attestor endpoints per module

Each module’s attestor_endpoints should list all attestors watching that module’s source chain. For a 3-of-5 quorum, list all 5 endpoints. The Proof API queries all of them and uses the first quorum_threshold valid responses.

​
signer_address

This is the bech32 address of the Cosmos account the relayer will use to sign and submit Cosmos-destination transactions.