Cosmos IBC Tutorial: 8 Proven Steps to Master IBC Eureka Migration

Every cosmos ibc tutorial you find in the top ten search results was written for ibc-go v8. They explain the four-step channel handshake, the connection negotiation process, the ICS-29 fee middleware configuration. None of them mention IBC Eureka, ibc-go v10, or the v9 retraction. The release lines currently supported are v8 and v10. v9 has been retracted and replaced by v10. ibc-go v10 release

This is the largest change to IBC since its launch and every team running a Cosmos chain right now is either migrating to v10 or planning to. The channels and connections they have been managing for years are not going away overnight, but the protocol has fundamentally changed under them.

IBC Eureka, released in ibc-go v10, includes Ethereum connectivity for token transfers backed by ZK light client security, a simplified protocol design that eliminates the 4-step channel handshake, simplified timeouts using timestamps instead of block heights, encoding flexibility beyond Protobuf, and enhanced upgradability with application versions specified in the packet instead of the connection. IBC v2 announcement

This cosmos ibc tutorial covers the migration from v8 to v10 end to end: why v9 was retracted, what IBC v2 actually changes in the protocol, how to upgrade your chain, the new relayer configuration that IBC v2 requires, Ethereum connectivity via IBC Eureka, and the production monitoring setup that keeps cross-chain operations observable.

Why This Cosmos IBC Tutorial Focuses on ibc-go v10 (and Not v8)

The short answer: ibc-go v9 was retracted and replaced by v10, which is the first Eureka-compatible release. The fee middleware module (ICS-29) was also removed in ibc-go v10 due to poor usability. ibc-go v10 changelog

The slightly longer answer requires understanding what Eureka is and why it required skipping a major version.

ibc-go v10 and IBC v2 released a significant improvement of the IBC protocol itself: IBC v2, which simplifies the protocol by removing channel and connection handshakes, reducing complexity and enabling easier implementation in other ecosystems and VMs. In this release, the first stable release of 08-wasm and the callbacks middleware were also included. IBC v2 announcement

IBC v2 is not a replacement for IBC Classic. Since ibc-go v10, there are two versions of the protocol in the same release: IBC classic and IBC v2. The protocols are separate, a connection uses either IBC classic or IBC v2. IBC-Go documentation

What this means practically for a team running a Cosmos chain:

Your existing IBC Classic channels and connections continue to work exactly as they did. No emergency migration is required on day one. But when you upgrade to ibc-go v10, you gain access to IBC v2 connections, which you create independently of your existing Classic channels. Over time, both the Cosmos ecosystem and external chains like Ethereum will migrate toward IBC v2, and the Classic channels will be used less frequently.

The operational implication: after upgrading to v10, you run both protocol versions simultaneously. Your relayers must be configured to handle both.

What IBC v2 Changes and What It Does Not

Before the cosmos ibc tutorial setup steps, understand what fundamentally changed in the protocol. This is the knowledge that makes the rest of this tutorial make sense.

What IBC Classic required:

To connect two Cosmos chains using IBC Classic, the process was:

1. Create a light client on Chain A tracking Chain B’s consensus state.
2. Create a light client on Chain B tracking Chain A’s consensus state.
3. Connection handshake (4 messages: ConnOpenInit, ConnOpenTry, ConnOpenAck, ConnOpenConfirm).
4. Channel handshake (4 messages: ChanOpenInit, ChanOpenTry, ChanOpenAck, ChanOpenConfirm).

This 10-step process created the social consensus problem: between the Cosmos Hub and Osmosis there are 40 channels, but only channel-141 is the canonical one, a fact determined by community agreement, not protocol. New channels could be created by anyone, leading to confusion about which channel to use for transfers.

What IBC v2 removes:

IBC v2 organizes around three components. Clients track the consensus state of a counterparty chain and serve as the primary identifier for a connection. A packet in IBC v2 references a source client and a destination client, not a channel, and is verified by proving the packet commitment against the counterparty’s stored consensus state. The Router directs packets to the correct application module by port ID, consolidating the routing logic that was previously spread across connections, channels, and the port router in IBC Classic into a single abstraction. IBC v2 announcement

Flexible client types: clients are not restricted to light clients. Any verification model can be implemented: light clients, multi-sig, ZK-proof verifiers, or conditional clients. This enables cost-efficient light client verification on chains like Ethereum. Timestamp-only timeout: IBC v2 packets carry a single Unix timestamp timeout in seconds. Block heights are chain-specific and do not translate across heterogeneous chains like Ethereum, so timestamps are used instead as a universal primitive. IBC v2 announcement

The IBC Eureka addition on top of IBC v2:

IBC Eureka is composed of three elements: IBC v2, Skip Go, and the Cosmos Hub. IBC Eureka provides Cosmos blockchains with an onboarding and interoperability solution that removes the limitations of the pre-Eureka era. It reduces infrastructure overhead and the complex usability of knowing which channel takes you to which chain or dropped packets. IBC v2 announcement

The connection is underpinned by light clients. An Ethereum light client as a CosmWasm contract is deployed on the Cosmos Hub using the 08-wasm client, and Succinct’s SP1 zkVM is used to run a tendermint-rs light client of the Cosmos Hub with proofs posted to Ethereum, enabling cost-effective light client verification. solidity-ibc-eureka

Cosmos IBC Tutorial Prerequisites

Before the migration steps, verify your environment:

# Check current ibc-go version
grep "github.com/cosmos/ibc-go" go.mod
# Example output: github.com/cosmos/ibc-go/v8 v8.5.2

# Check Cosmos SDK version
grep "github.com/cosmos/cosmos-sdk" go.mod
# ibc-go v10 requires Cosmos SDK v0.50+ or v0.53+

# Check CometBFT version
grep "github.com/cometbft/cometbft" go.mod
# ibc-go v10 is compatible with CometBFT v0.38

# Verify your Go version
go version
# Requires Go 1.21+

# List existing IBC channels (know what you have before migrating)
gaiad query ibc channel channels --chain-id cosmoshub-4 | jq '.channels | length'

ibc-go v10 is compatible with Cosmos SDK v0.50 and CometBFT v0.38, so chains can connect to Ethereum without a massive chain upgrade. This is the key operational advantage of the v10 release: you do not need to upgrade to Cosmos SDK v0.52 or v0.53 to gain Ethereum connectivity. SDK v0.50 is sufficient. ibc-go v10 changelog

Step 1: Upgrade ibc-go from v8 to v10

The upgrade from v8 to v10 requires a coordinated chain upgrade. This is not an in-place module swap, it requires a governance proposal and a chain halt.

Update go.mod:

# Remove v8 dependency
go mod edit -droprequire github.com/cosmos/ibc-go/v8

# Add v10 (latest stable as of 2026)
go get github.com/cosmos/ibc-go/v10@latest

# Verify
grep "ibc-go" go.mod
# Should show: github.com/cosmos/ibc-go/v10 v10.3.0

Update import paths across your codebase:

# Find and replace all v8 imports
find . -name "*.go" -exec sed -i 's|github.com/cosmos/ibc-go/v8|github.com/cosmos/ibc-go/v10|g' {} \;

# Verify no v8 imports remain
grep -r "ibc-go/v8" . --include="*.go"
# Should return empty

Remove ICS-29 fee middleware references:

The fee middleware module (ICS-29) was removed in ibc-go v10 due to poor usability. Any code referencing the fee middleware must be removed or migrated: ibc-go v10 changelog

# Find all fee middleware references
grep -r "fee_middleware\|ICS29\|ibcfee\|feetypes" . --include="*.go"

# Remove from app.go:
# - ibcfeekeeper
# - ibcfeetypes
# - IBCFeeKeeper
# - MsgServer fee registrations

# Remove from app_wiring.go if using depinject

# Update module manager if fee module was registered

Update the migration handler:

// app/upgrades/v10/upgrade.go
package v10

import (
    sdk "github.com/cosmos/cosmos-sdk/types"
    "github.com/cosmos/cosmos-sdk/types/module"
    upgradetypes "github.com/cosmos/cosmos-sdk/x/upgrade/types"
    ibctm "github.com/cosmos/ibc-go/v10/modules/light-clients/07-tendermint"
)

const UpgradeName = "v10-ibc-eureka"

func CreateUpgradeHandler(
    mm *module.Manager,
    configurator module.Configurator,
) upgradetypes.UpgradeHandler {
    return func(ctx sdk.Context, plan upgradetypes.Plan, vm module.VersionMap) (module.VersionMap, error) {
        // Run module migrations — this migrates IBC store to v10 format
        return mm.RunMigrations(ctx, configurator, vm)
    }
}

Submit the governance upgrade proposal:

# Create upgrade proposal
gaiad tx gov submit-proposal \
  --type software-upgrade \
  --title "Upgrade to ibc-go v10 (IBC Eureka)" \
  --description "Upgrades IBC to v10, enabling IBC v2 protocol and Ethereum connectivity via IBC Eureka. Removes fee middleware (ICS-29). Retains full IBC Classic compatibility." \
  --upgrade-name "v10-ibc-eureka" \
  --upgrade-height [PLANNED_HEIGHT] \
  --deposit 1000000uatom \
  --from validator \
  --chain-id cosmoshub-4

# Monitor proposal
gaiad query gov proposals --status voting_period

Existing IBC channels remain functional. There is no migration to the v2 protocol in this release. Your existing Classic channels and their connections continue to work after the upgrade. The upgrade only adds IBC v2 capability alongside Classic, it does not require or trigger any channel migrations. IBC-Go documentation

Step 2: Configure the 08-wasm Light Client

IBC v2’s Ethereum connectivity requires the 08-wasm light client module, which allows any consensus verification algorithm to be implemented as a CosmWasm contract. This enables Ethereum’s Tendermint light client to be deployed on a Cosmos chain.

// app/app.go - register 08-wasm client
import (
    wasmkeeper "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/keeper"
    wasmtypes "github.com/cosmos/ibc-go/modules/light-clients/08-wasm/types"
)

// Add to app struct
WasmClientKeeper wasmkeeper.Keeper

// Initialize in NewApp
app.WasmClientKeeper = wasmkeeper.NewKeeper(
    appCodec,
    runtime.NewKVStoreService(keys[wasmtypes.StoreKey]),
    app.IBCKeeper.ClientKeeper,
    authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

// Register in IBCKeeper
app.IBCKeeper = ibckeeper.NewKeeper(
    appCodec,
    runtime.NewKVStoreService(keys[ibcexported.StoreKey]),
    app.GetSubspace(ibcexported.ModuleName),
    app.UpgradeKeeper,
    scopedIBCKeeper,
    authtypes.NewModuleAddress(govtypes.ModuleName).String(),
    ibckeeper.WithClientModule(wasmtypes.ModuleName, app.WasmClientKeeper),
)

Allowlist the Ethereum light client contract:

# After upgrade, upload and instantiate the Ethereum light client
# (official contract from Interchain Labs)
gaiad tx wasm store ethereum-light-client.wasm \
  --from validator \
  --gas 5000000 \
  --chain-id cosmoshub-4

# Allowlist via governance (required for 08-wasm client instantiation)
gaiad tx gov submit-proposal \
  --type wasm-store \
  --title "Allowlist Ethereum SP1 Light Client" \
  --description "Allowlists the SP1 Tendermint-rs Ethereum light client contract for IBC v2 Eureka connectivity" \
  --deposit 1000000uatom \
  --from validator

Step 3: IBC Relayer Setup for v10

This is the section most cosmos ibc tutorial guides skip entirely, and where most production issues originate post-migration.

ibc-go v10 runs both IBC Classic and IBC v2 simultaneously. Your relayer must handle both protocol versions. Hermes (by Informal Systems) is the reference relayer with the most mature v10 support.

Install the latest Hermes:

# Install Hermes (Rust-based, recommended for production)
cargo install ibc-relayer-cli --bin hermes --locked

# Verify version
hermes version
# hermes 1.10.x (supports IBC v2)

# Or download binary
curl -L https://github.com/informalsystems/hermes/releases/latest/download/hermes-linux-amd64.tar.gz | tar xz

Hermes config for IBC Classic channels (v8 compatibility):

# ~/.hermes/config.toml
[global]
log_level = 'info'

[mode]
[mode.clients]
enabled = true
refresh = true
misbehaviour = true

[mode.connections]
enabled = false  # Connections pre-exist — no need to create new Classic ones

[mode.channels]
enabled = false  # Existing channels — no new Classic channels needed

[mode.packets]
enabled = true
clear_interval = 100
clear_on_start = true
tx_confirmation = true

[[chains]]
id = 'cosmoshub-4'
type = 'CosmosSdk'
rpc_addr = 'https://rpc.cosmos.network:443'
grpc_addr = 'https://grpc.cosmos.network:9090'
websocket_addr = 'wss://rpc.cosmos.network:443/websocket'
rpc_timeout = '10s'
account_prefix = 'cosmos'
key_name = 'relayer-key-hub'
store_prefix = 'ibc'
default_gas = 100000
max_gas = 3000000
gas_multiplier = 1.1
max_msg_num = 30
max_tx_size = 2097152
clock_drift = '5s'
max_block_time = '30s'
trusting_period = '14days'
trust_threshold = { numerator = '1', denominator = '3' }

[chains.packet_filter]
policy = 'allow'
list = [
  ['transfer', 'channel-141'],  # Hub <> Osmosis canonical channel
  ['transfer', 'channel-0'],    # Hub <> Cosmos Hub ICS
]

[[chains]]
id = 'osmosis-1'
type = 'CosmosSdk'
rpc_addr = 'https://rpc.osmosis.zone:443'
grpc_addr = 'https://grpc.osmosis.zone:9090'
websocket_addr = 'wss://rpc.osmosis.zone:443/websocket'
rpc_timeout = '10s'
account_prefix = 'osmo'
key_name = 'relayer-key-osmosis'
store_prefix = 'ibc'
default_gas = 300000
max_gas = 6000000
gas_multiplier = 1.2

Add IBC v2 relay configuration:

IBC v2 packets reference clients directly, not channels. The relayer configuration reflects this:

# Add to config.toml for IBC v2 packet relay
# IBC v2 uses client IDs instead of channel IDs for routing
[mode.v2_packets]
enabled = true

# In the chain config, reference the IBC v2 client
[[chains]]
id = 'cosmoshub-4'
# ... existing config ...

# IBC v2 client tracking (for Ethereum Eureka connection)
[chains.ibc_v2]
client_id = '08-wasm-0'  # The Ethereum light client ID after deployment

Key management for the relayer:

# Add relayer keys
hermes keys add \
  --chain cosmoshub-4 \
  --key-file ~/.hermes/keys/hub-relayer.json \
  --key-name relayer-key-hub

hermes keys add \
  --chain osmosis-1 \
  --key-file ~/.hermes/keys/osmosis-relayer.json \
  --key-name relayer-key-osmosis

# Verify keys are loaded
hermes keys list --chain cosmoshub-4

# Check chain health before starting
hermes health-check

Step 4: ibc-go v10 Migration Pitfalls

Pitfall 1: ICS-29 fee middleware removal breaks existing tooling

If your chain was using ICS-29 for relayer incentivization, the removal in v10 requires updating all front-end tooling, relayer configurations, and any scripts that referenced fee packets. Relayers previously registering fee addresses must be updated. Monitor for transaction failures from relayers trying to submit fee-related messages post-upgrade.

# Check for any pending fee packets before upgrading
gaiad query ibc-fee incentivized-packets \
  --port-id transfer \
  --channel-id channel-141 \
  --chain-id cosmoshub-4

# Clear all pending fee packets before the upgrade height
# to avoid stranded packets

Pitfall 2: Timeout format change in IBC v2

IBC Classic uses both height and timestamp timeouts. IBC v2 uses only timestamp. If you are building applications that send IBC v2 packets, the timeout field format is different:

// IBC Classic timeout (both height and timestamp)
timeout := clienttypes.NewHeight(0, revisionHeight)

// IBC v2 timeout (timestamp only, in nanoseconds Unix time)
// 10 minutes from now
timeout := uint64(time.Now().Add(10 * time.Minute).UnixNano())

Any application code that generates IBC packets for v2 connections must use the timestamp-only format. Classic packets on v1 channels continue to use the height-based format.

Pitfall 3: Channel IDs no longer apply to IBC v2 connections

Tooling built around channel IDs will not find IBC v2 transactions when querying by channel. IBC v2 references client IDs. Update any monitoring, analytics, or indexing that queries by channel ID to also query by client ID for v2 packets.

Pitfall 4: Running relayers without v2 support on a v10 chain

Old relayer versions that do not support IBC v2 will still relay Classic packets correctly. They will not relay v2 packets. If your chain is sending or receiving IBC v2 packets, you need a v2-compatible relayer (Hermes 1.10+, or Go relayer with v2 support) even if you have no plans to use Ethereum connectivity.

Step 5: Connecting to Cosmos Hub via IBC Eureka

The Cosmos Hub is the canonical entry point for IBC Eureka connectivity. The Cosmos Hub acts as a powerful entry point into the interchain ecosystem. It offers benefits like reduced maintenance, lower costs via batching, and compatibility with existing IBC infrastructure, though it is not mandatory for integration. IBC v2 announcement

Create an IBC v2 client connection to Cosmos Hub:

# Create a Tendermint light client for Cosmos Hub (IBC v2 style)
gaiad tx ibc client create \
  07-tendermint \
  --chain-id cosmoshub-4 \
  --trust-level "1/3" \
  --trusting-period "336h" \  # 14 days
  --max-clock-drift "10s" \
  --from validator \
  --chain-id yourchain-1

# The response includes the client ID (e.g., 07-tendermint-5)
# This client ID is what IBC v2 packets reference — not a channel ID

# Verify client state
gaiad query ibc client state 07-tendermint-5

Send an IBC v2 token transfer:

# IBC v2 transfer references client ID, not channel ID
gaiad tx ibc-transfer transfer \
  --source-client-id 07-tendermint-5 \     # IBC v2 client (not channel)
  --destination-client-id 07-tendermint-12 \ # Counterparty client on Hub
  --amount 1000000uatom \
  --receiver cosmos1... \
  --timeout-timestamp 1800 \               # 1800 seconds = 30 minutes
  --from validator \
  --chain-id yourchain-1

Note the fundamental difference from IBC Classic: you specify client IDs, not channel IDs. The router on each chain handles directing the packet to the correct module without needing a channel.

Step 6: Connecting to Ethereum via IBC Eureka

Ethereum connectivity is the headline feature of IBC Eureka. IBC v2 provides affordable IBC transactions to Ethereum through the use of Succinct’s Processor SP1, a zkVM that runs a Rust-based Tendermint light client to verify the consensus state of a Cosmos chain, with inclusion or exclusion of IBC packets verified. solidity-ibc-eureka

An illustrative cost of sending tokens from Ethereum to a Cosmos chain, using a gas cost of 2.5 gwei, ETH cost of $2600, and 149,000 gas, is only $0.97. Only receives and acknowledgments require verification using a ZK proof. solidity-ibc-eureka

The IBC Eureka Ethereum architecture:

Cosmos Chain ←→ Cosmos Hub ←→ IBC Solidity (Ethereum Mainnet)
                    ↑                     ↑
           Tendermint light client    SP1 zkVM Tendermint-rs
           (CosmWasm 08-wasm)        (ZK proof of Cosmos state)

Deploy the Ethereum light client on your chain:

The Ethereum connectivity requires deploying two contracts: an Ethereum light client on your Cosmos chain (via 08-wasm), and the IBC Solidity contracts on Ethereum.

# 1. Download the official SP1 Tendermint Ethereum light client
# (maintained by Interchain Labs / Succinct Labs)
curl -L https://github.com/cosmos/solidity-ibc-eureka/releases/latest/download/sp1-tendermint.wasm \
  -o sp1-tendermint.wasm

# 2. Upload to your chain (requires 08-wasm module active)
gaiad tx wasm store sp1-tendermint.wasm \
  --from validator \
  --gas 6000000 \
  --chain-id yourchain-1

# 3. Instantiate the light client via governance
# The light client tracks Ethereum's state on your Cosmos chain
gaiad tx gov submit-proposal \
  --type "wasm-instantiate" \
  --title "Deploy Ethereum SP1 Light Client for IBC Eureka" \
  --description "Instantiates the SP1 Tendermint light client for Ethereum connectivity via IBC Eureka" \
  --from validator

# 4. After instantiation, create an IBC client using the wasm light client
# client-id: 08-wasm-0 (or next available)
gaiad query ibc client states | grep "08-wasm"

Use Skip:Go for user-facing Ethereum transfers:

Skip:Go combines an API, on-chain smart contracts, smart relay, and Go Fast, the solver network, to handle transaction generation and execution for users. It is the interface that users will interact with to use IBC Eureka. Skip:Go docs

For production use cases where you are building user-facing applications that bridge between your Cosmos chain and Ethereum, Skip:Go provides the recommended integration layer. Direct IBC packet submission to Ethereum is technically possible but operationally complex, Skip:Go handles the ZK proof generation, packet routing, and relayer coordination.

# Skip:Go API for Ethereum-Cosmos transfers
# POST https://api.skip.money/v2/fungible/route
{
  "source_asset_denom": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  # USDC on Ethereum
  "source_asset_chain_id": "1",
  "dest_asset_denom": "ibc/...",
  "dest_asset_chain_id": "osmosis-1",
  "amount_in": "1000000"
}

Step 7: Production Monitoring for IBC v10

A cosmos ibc tutorial for production is incomplete without the monitoring layer. IBC Classic and IBC v2 require different monitoring approaches because they use different identifiers and packet lifecycle events.

Prometheus metrics exposed by ibc-go v10:

# Key IBC metrics to monitor (Prometheus)
# Classic channels
ibc_transfer_send_packets_total          # Packets sent per channel
ibc_transfer_receive_packets_total       # Packets received per channel
ibc_transfer_ack_packets_total          # Acknowledged packets per channel
ibc_transfer_timeout_packets_total      # Timed out packets per channel (critical)

# IBC v2 clients
ibc_client_updates_total               # Client updates per client ID
ibc_client_misbehaviour_total          # Misbehaviour detections (security signal)

# Light client expiry (critical for uptime)
ibc_client_expiry_seconds              # Seconds until client expires

Alert rules for production IBC:

groups:
- name: ibc-monitoring
  rules:
  # Classic channel: timeout accumulation (relayer may be down)
  - alert: IBCTimeoutsAccumulating
    expr: |
      increase(ibc_transfer_timeout_packets_total[15m]) > 5
    labels:
      severity: warning
    annotations:
      summary: "IBC packet timeouts accumulating on {{ $labels.channel_id }}"
      description: "{{ $value }} timeouts in 15 minutes. Relayer may be offline or counterparty chain may be halted."

  # Critical: light client about to expire (causes channel closure)
  - alert: IBCClientExpiryImminent
    expr: |
      ibc_client_expiry_seconds < 86400  # Less than 24 hours
    labels:
      severity: critical
    annotations:
      summary: "IBC client {{ $labels.client_id }} expiring in less than 24 hours"
      description: "Client will expire at {{ $value | humanizeDuration }}. Update client state immediately to prevent channel closure."

  # IBC v2: client misbehaviour detected
  - alert: IBCv2ClientMisbehaviour
    expr: |
      increase(ibc_client_misbehaviour_total[5m]) > 0
    labels:
      severity: critical
    annotations:
      summary: "IBC v2 client misbehaviour detected for {{ $labels.client_id }}"
      description: "Misbehaviour detected. Client may be frozen. Investigate immediately."

  # Packet stuck: sent but not acknowledged or timed out
  - alert: IBCPacketStuck
    expr: |
      (ibc_transfer_send_packets_total - ibc_transfer_ack_packets_total - ibc_transfer_timeout_packets_total) > 50
    for: 30m
    labels:
      severity: warning
    annotations:
      summary: "More than 50 unresolved IBC packets on {{ $labels.channel_id }}"

IBC light client expiry management:

The most operationally critical aspect of any cosmos ibc tutorial is light client expiry. If a light client on either side of a channel expires, because the relayer has not submitted client updates in time, the channel freezes. No packets can be sent or received until the channel is either reopened (if recovery is possible) or replaced with a new channel.

# Check expiry of all IBC clients
gaiad query ibc client states -o json | jq '
  .client_states[] |
  {
    client_id: .client_id,
    trust_period: .client_state.trust_period,
    latest_height: .client_state.latest_height
  }'

# For each active channel, verify the associated client is being updated
# A client must be updated within its trust period (typically 14 days)
# Relayer must run continuously or be scheduled to run at least every trust_period/2

# Check last update for a specific client
gaiad query ibc client consensus-states 07-tendermint-0 \
  | jq '.consensus_states | sort_by(.height.revision_height) | last'

Step 8: Relayer Operations and Redundancy

A single relayer is a single point of failure for your IBC connections. For production Cosmos IBC setups, run at least two independent relayers with different key wallets and different RPC endpoints.

# Start Hermes relayer as a systemd service
# /etc/systemd/system/hermes.service
[Unit]
Description=Hermes IBC Relayer
After=network-online.target

[Service]
User=hermes
ExecStart=/usr/local/bin/hermes start
Restart=on-failure
RestartSec=10s
LimitNOFILE=65535
Environment="RUST_LOG=info"

[Install]
WantedBy=multi-user.target

systemctl enable hermes
systemctl start hermes
journalctl -u hermes -f

Relayer wallet funding automation:

# Monitor relayer wallet balance and alert when low
#!/bin/bash
RELAYER_ADDRESS="cosmos1..."
BALANCE=$(gaiad query bank balances $RELAYER_ADDRESS \
  --chain-id cosmoshub-4 \
  --output json | jq -r '.balances[] | select(.denom=="uatom") | .amount')

if [ "$BALANCE" -lt 10000000 ]; then  # Less than 10 ATOM
  echo "ALERT: Relayer balance low: $BALANCE uatom"
  # Trigger your alerting mechanism
fi

Clear stuck packets:

# Clear packets that are stuck in pending state
hermes clear packets \
  --chain cosmoshub-4 \
  --channel channel-141 \
  --port transfer

# For IBC v2 packets (reference client ID)
hermes clear v2-packets \
  --chain cosmoshub-4 \
  --client 07-tendermint-5

Conclusion

Every cosmos ibc tutorial that predates 2026 describes a protocol that is being superseded. The channel handshakes, the ICS-29 fee middleware, the height-based timeouts, these are IBC Classic patterns that continue to work but that the ecosystem is moving away from.

ibc-go v10 and IBC v2 are not a rip-and-replace migration. The Classic protocol continues to function. What v10 adds is a simpler, more extensible protocol that enables Ethereum connectivity via ZK light clients and removes the operational complexity that has made IBC adoption outside the Cosmos ecosystem slow.

For teams currently on v8: the migration path is direct and well-documented. The biggest operational risks are ICS-29 removal (if you were using fee middleware), the timeout format change for v2 packets, and ensuring your relayer infrastructure supports both protocol versions simultaneously.

At The Good Shell we design and operate Cosmos validator and IBC infrastructure for teams navigating the ibc-go v10 migration. The same principles that protect against Cosmos validator slashing apply to IBC relayer operations: uptime, key management, and monitoring before problems compound.

If your team is preparing the v8 to v10 migration and wants a second pair of eyes on the governance proposal, the dual-protocol relayer config, or the post-upgrade monitoring stack, we run focused IBC migration audits. Book a 30-minute scoping call to see if it fits, or browse our case studies for examples of similar work. For broader infrastructure work see our Web3 infrastructure services.

For chains integrating EigenLayer alongside Cosmos IBC, see our EigenLayer AVS setup guide for the cross-chain infrastructure patterns that connect both ecosystems.

For the authoritative reference, the ibc-go v10 release notes and Hermes relayer documentation cover every configuration option with up-to-date examples.

FAQ: Cosmos IBC Tutorial Questions Answered