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.

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

​
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:
ContainerRole
cosmosCosmos sandbox chain (CometBFT RPC on port 26657)
besuHyperledger Besu EVM node (JSON-RPC on port 8545)
attestorWatches Besu, signs EVM state for the Cosmos light client
attestor-cosmosWatches Cosmos, signs Cosmos state for the EVM light client
proof-apiAggregates attestor signatures into relay-ready proofs
relayerSubmits RecvPacket and MsgTimeout transactions on both chains
postgresRelayer 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