Quickstart

Run the full Cosmos ↔ EVM IBC demo end-to-end with a single command

This page gets the IBC demo running end-to-end with a single command. It starts a Cosmos sandbox chain and a Besu EVM node, deploys the IBC contracts, creates attestation light clients on both chains, wires the IFT bridge, configures and starts the attestors, and runs the relayer and Proof API. For a step-by-step breakdown of what each phase does, see the walkthrough.

Prerequisites

• Docker and Docker Compose
• Foundry (forge and cast) and bun
• jq

Run the demo

Clone the repository and navigate to the demo directory:

git clone https://github.com/cosmos/ibc-e2e-docs-example
cd demo/cosmos-evm

Run the full setup:

./setup.sh

This starts the Cosmos and Besu chains, deploys the IBC contracts, creates attestation light clients on both chains, wires the IFT bridge, configures and starts the attestors, relayer, and Proof API. Once setup is complete, it runs the full demo suite:

• Cosmos to EVM transfer: burns IFT tokens on the Cosmos chain and mints the equivalent ERC20 balance on Besu.
• EVM to Cosmos transfer: burns the ERC20 on Besu and mints IFT tokens back on the Cosmos chain.
• Packet tracking: polls the relayer API by transaction hash and prints the transfer state as it progresses.
• Timeout path: sends a packet with a short timeout, pauses the relayer to let it expire, then resumes so the relayer can submit a MsgTimeout. The source chain refunds the sender.
• Observability: samples live Prometheus metrics from the relayer and prints recent log output from the relayer and attestors.

The full setup takes a few minutes. Progress is printed to the terminal and logged to logs/.

What runs

Once complete, these containers are running:

Container	Role
cosmos	Cosmos sandbox chain (CometBFT RPC on port 26657)
besu	Hyperledger Besu EVM node (JSON-RPC on port 8545)
attestor	Watches Besu, signs EVM state for the Cosmos light client
attestor-cosmos	Watches Cosmos, signs Cosmos state for the EVM light client
proof-api	Aggregates attestor signatures into relay-ready proofs
relayer	Submits RecvPacket and MsgTimeout transactions on both chains
postgres	Relayer packet state persistence

All Commands

The command you ran earlier shows the full end-to-end flow of the demo. However, you can also run individual commands that break up the flow so you can see how each step works.

# Full demo
./setup.sh            # full setup: chains + IBC + demos (runs through steps below)

# Set up chains
./setup.sh chains     # start Cosmos and Besu only (skip IBC setup)

# Run all IBC setup steps
./setup.sh ibc        # run all IBC setup steps below on already-running chains

# Run each IBC setup step individually
./setup.sh deploy           # Step 1/5: fetch source + deploy IBC/IFT contracts on Besu
./setup.sh create-clients   # Step 2/5: create attestation light clients on both chains + register counterparties
./setup.sh wire             # Step 3/5: register IFT bridges
./setup.sh attestors        # Step 4/5: generate keystores/configs + start attestor services
./setup.sh relayer          # Step 5/5: copy keys, render configs (client IDs now known), run DB migrations, start relayer + proof-api

# Run the transfers
./setup.sh transfer          # Cosmos ↔ EVM transfers in both directions
./setup.sh demo all          # all demos in sequence
./setup.sh demo cosmos-evm   # Cosmos → EVM transfer
./setup.sh demo evm-cosmos   # EVM → Cosmos transfer
./setup.sh demo track        # packet status tracking
./setup.sh demo failure      # timeout and refund path
./setup.sh demo observe      # Prometheus metrics and logs

./setup.sh status     # print RPC endpoints and current block heights
./setup.sh clean      # stop all containers and wipe state
./setup.sh help       # list all commands and configurable environment variables

Walkthrough

The next sections of this tutorial are a walkthrough that breaks up each step of the demo and shows you how chains are set up, what each service does, and what to look for at each stage.

The walkthrough covers the following setup commands in order:

./setup.sh chains           # 1. start Cosmos and Besu only (skip IBC setup)

./setup.sh deploy           # 2. Fetch source + deploy IBC/IFT contracts on Besu
./setup.sh create-clients   # 3. Create attestation light clients on both chains + register counterparties
./setup.sh wire             # 4. Register IFT bridges
./setup.sh attestors        # 5. Generate keystores/configs + start attestor services
./setup.sh relayer          # 6. Copy keys, render configs (client IDs now known), run DB migrations, start relayer + proof-api

./setup.sh transfer         # 7. Cosmos ↔ EVM transfers in both directions

Before continuing through the walkthrough, make sure to run the following to stop all containers and start fresh:

./setup.sh clean      # stop all containers and wipe state