> ## Documentation Index
> Fetch the complete documentation index at: https://cosmos-docs-sync-security-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Step 1: Start the Chains

> Start the Cosmos sandbox chain and Besu EVM node used in the IBC demo

Before running through the walkthrough, make sure you have completed the prerequisites in the [quickstart](/ibc/next/cosmos-evm/tutorial/quickstart).

This page covers the setup of the two chains used in the demo. It walks you through what each one is, which modules the Cosmos chain needs for IBC v2 and IFT support, and what happens when you run the following command in the demo:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
./setup.sh chains
```

The logic for this command is in [`lib/chains.sh`](https://github.com/cosmos/ibc-e2e-docs-example/blob/main/demo/cosmos-evm/lib/chains.sh).

Everything else in the [tutorial](/ibc/next/cosmos-evm/tutorial/introduction) depends on both chains being up and producing blocks before it runs.

## Cosmos: sandbox-ledger

The Cosmos chain in this demo is [sandbox-ledger](https://github.com/cosmos/sandbox-ledger), a Cosmos SDK chain built specifically for IBC v2 interoperability. It runs as a single-validator proof-of-authority (POA) chain using CometBFT consensus.

## EVM: Hyperledger Besu

The EVM chain is a single-validator [Hyperledger Besu](https://github.com/hyperledger/besu) node running QBFT consensus. Unlike the Cosmos side, the EVM chain requires no custom chain-level modules: the IBC stack is deployed as Solidity contracts on top of a standard EVM node.

The demo uses:

* Chain ID: `32382`
* Block period: 2 seconds
* Consensus: QBFT (single-validator, no peer discovery)
* Funded account: `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` (this is a test key; do not use it with real funds).

Besu is configured via [`evm/besu.toml`](https://github.com/cosmos/ibc-e2e-docs-example/blob/main/demo/cosmos-evm/evm/besu.toml) and [`evm/el-genesis.json`](https://github.com/cosmos/ibc-e2e-docs-example/blob/main/demo/cosmos-evm/evm/el-genesis.json).

## What `./setup.sh chains` does

### Cosmos initialization

The [`lib/chains.sh`](https://github.com/cosmos/ibc-e2e-docs-example/blob/main/demo/cosmos-evm/lib/chains.sh) script runs inside the sandbox-ledger container to initialize the chain, then patches the genesis before starting:

1. Creates the host config directories (`cosmos/local/config/`, `cosmos/local/keyring-test/`) so the bind mounts in `docker-compose.yml` resolve correctly.
2. Runs `sandboxd init` to generate the initial genesis and key files.
3. Adds a `validator` key.
4. Adds a `relayer` key and funds it in genesis.
5. Reads the CometBFT consensus pubkey from `priv_validator_key.json` and injects it into the POA validator set in genesis via [`patch-genesis.jq`](https://github.com/cosmos/ibc-e2e-docs-example/blob/main/demo/cosmos-evm/cosmos/patch-genesis.jq). POA requires at least one validator in genesis or it rejects on startup.
6. Patches genesis denoms and sets the IFT module authority to the validator address.
7. Copies the customized [`app.toml`](https://github.com/cosmos/ibc-e2e-docs-example/blob/main/demo/cosmos-evm/cosmos/app.toml) and [`config.toml`](https://github.com/cosmos/ibc-e2e-docs-example/blob/main/demo/cosmos-evm/cosmos/config.toml) from `cosmos/` into the config directory, overwriting the defaults written by `init`.
8. Starts the `cosmos` container.

### Besu initialization

1. Starts the `besu` container with the pre-existing `evm/el-genesis.json` and `evm/key` files.

2. Polls `http://localhost:8545` until the JSON-RPC endpoint is reachable.

### Readiness check

After both containers start, the script polls each chain until it confirms blocks are being produced, then prints the endpoints and current block heights.

```
Cosmos (sandbox)
  CometBFT RPC : http://localhost:26657
  REST API      : http://localhost:1317
  gRPC          : localhost:9090

Besu (Ethereum EL)
  JSON-RPC HTTP : http://localhost:8545
  WebSocket     : ws://localhost:8546
```

## Applying this to your own chains

<Tip>
  The chain used in this demo illustrates how to use IBC modules on the Cosmos side, but you can also use the Solidity deployment on Cosmos chains with EVM capabilities.

  If you are operating a Cosmos EVM chain and need to access IBC through the EVM, you can skip the Cosmos-side wiring and use [Solidity contract deployments](/ibc/next/cosmos-evm/tutorial/walkthrough/02-deploy) for your chain.
</Tip>

For native Cosmos IBC module deployments, the Cosmos chain should have the IBC modules listed in the table below installed and wired.

| Module                                                                                                                  | Package      | Purpose                                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [`ibc`](https://github.com/cosmos/ibc-go/tree/main/modules/core) (core)                                                 | `ibc-go/v11` | Core IBC packet routing                                                                                                                   |
| [`callbacks`](https://github.com/cosmos/ibc-go/tree/main/modules/apps/callbacks) (v1 + v2)                              | `ibc-go/v11` | Ack and timeout callbacks for GMP packets                                                                                                 |
| [`27-gmp`](https://github.com/cosmos/ibc-go/tree/main/modules/apps/27-gmp)                                              | `ibc-go/v11` | ICS-27 General Message Passing: carries cross-chain mint and burn instructions                                                            |
| [`attestations`](https://github.com/cosmos/ibc-go/tree/main/modules/light-clients/attestations) light client            | `ibc-go/v11` | The only light client type registered on this chain: verifies packets via quorum-signed ECDSA attestations rather than Tendermint headers |
| [`tokenfactory`](https://github.com/cosmos/ibc-go/tree/prototype-ift-tokenfactory/modules/apps/prototypes/tokenfactory) | `ibc-go/v11` | Permissionless `factory/<creator>/<subdenom>` token creation with admin-gated mint and burn                                               |
| [`ift`](https://github.com/cosmos/ibc-go/tree/prototype-ift-tokenfactory/modules/apps/prototypes/ift)                   | `ibc-go/v11` | The IFT bridge module: pairs a tokenfactory denom with a counterparty IFT contract and handles cross-chain burn/mint                      |

<Warning>
  The `tokenfactory` and `ift` Cosmos modules used in this demo are provided as reference implementations only and are not intended for use in production as-is.
</Warning>

The IBC v2 port routing is set in [`app/app.go`](https://github.com/cosmos/sandbox-ledger/blob/1f8ad2ea5b285be5a1b9fa36d5b4db585e1e56fb/app/app.go#L492). The [`gmpport`](https://github.com/cosmos/sandbox-ledger/blob/1f8ad2ea5b285be5a1b9fa36d5b4db585e1e56fb/app/app.go#L537) routes to the GMP module, wrapped in callbacks-v2 middleware so the IFT keeper receives ack and timeout callbacks.

You can refer to [PR #1](https://github.com/cosmos/sandbox-ledger/pull/1/files#diff-d1a13e056897040ff4a79d865527c9964974cd376af3293d25ac045df8c6fa50) in the sandbox-ledger repo as a reference of the changes needed to add IBC v2 and IFT support to an existing Cosmos SDK chain.

The full wiring, including keeper initialization, module manager registration, and begin/end blocker ordering, is in [`app/app.go`](https://github.com/cosmos/sandbox-ledger/blob/main/app/app.go).

On the EVM side, no chain modifications are needed. The IBC stack for EVM is entirely at the contract layer, which is covered in the [next step](/ibc/next/cosmos-evm/tutorial/walkthrough/02-deploy).