cli

module
v0.2.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0

README

IBC CLI

IBC CLI deploys IBC onto a chain and runs the relayer and attestor processes that carry packets across it.

See docs/ibc/ibc-cli/ for guides on operating IBC CLI. Start with Deploy IBC and send a token, which brings up two chains, deploys the stack on both, and moves a token between them.

Prerequisites

  • Go 1.26.10 or later

Support

Supported
Chain types evm
Light client types attestation, besu

CLI Commands

The ibc binary covers the whole lifecycle: creating a configuration and keys, deploying IBC and its applications onto chains, running the relayer and attestor, and sending transactions and queries against what you deployed. See CLI commands for the full reference.

# build the CLI
make build

# create a new config at ~/.ibc/ibc.yml
./bin/ibc config new

# migrate the database (skip if running migrations on relayer startup.
# `relayer run` migrates on startup automatically unless passed --no-migrate)
./bin/ibc migrate up

# generate a new local signing key, or import an existing private key
./bin/ibc keys new ecdsa <name>
./bin/ibc keys import ecdsa <name> --private-key <hex>

# deploy IBC between two configured chains (idempotent; a rerun continues a partial deployment)
./bin/ibc deploy core --chain <chainA> --yes
./bin/ibc deploy core --chain <chainB> --yes
./bin/ibc deploy client attestation --chain <chainA> --counterparty-chain <chainB> --yes
./bin/ibc deploy client attestation --chain <chainB> --counterparty-chain <chainA> --yes

# deploy the GMP app on each chain, so contracts can be called across the connection
./bin/ibc deploy gmp --chain <chainA> --yes
./bin/ibc deploy gmp --chain <chainB> --yes

# deploy an IFT token on each chain, then register the bridge between the two
./bin/ibc deploy ift --name <name> --symbol <symbol> --rate-limit-capacity <baseUnits> --chain <chainA> --yes
./bin/ibc deploy ift --name <name> --symbol <symbol> --rate-limit-capacity <baseUnits> --chain <chainB> --yes
./bin/ibc deploy ift-bridge --chain-a <chainA> --ift-a <addressA> --chain-b <chainB> --ift-b <addressB> --yes

# mint the token, then send it across a connection
./bin/ibc tx ift mint --chain <chainA> --ift <addressA> --to <recipient> --amount <baseUnits> --from <signer>
./bin/ibc tx ift send --chain <chainA> --ift <addressA> --client-id <clientID> --to <receiver> --amount <baseUnits> --from <signer>

# run the relayer and/or attestor after populating config
./bin/ibc relayer run
./bin/ibc attestor run

Configuration

See Configuration for the full configuration reference, or internal/config/ibc.yml for a worked example.

E2E

Repository-wide black-box tests live in ../e2e/, with the harness in ../e2e/internal/harness as a separate Go module. From the repository root, make -C e2e doctor && make -C e2e test runs the suite.

Directories

Path Synopsis
api
attestor
evm
evm/ibc
Package ibc translates IBC packets to and from the Solidity router ABI.
Package ibc translates IBC packets to and from the Solidity router ABI.
Package besu provides header parsing and sealing, storage slot derivation and ABI encoding for Besu light-client payloads.
Package besu provides header parsing and sealing, storage slot derivation and ABI encoding for Besu light-client payloads.
besutest
Package besutest provides the Besu QBFT and IBFT2 light-client fixtures, generated by the e2e harness (make -C e2e generate-besu-fixtures), and the fixture schema the generator writes and ibc-contracts' Solidity tests read.
Package besutest provides the Besu QBFT and IBFT2 light-client fixtures, generated by the e2e harness (make -C e2e generate-besu-fixtures), and the fixture schema the generator writes and ibc-contracts' Solidity tests read.
cmd
ibc command
internal
chains
Package chains defines chain-agnostic clients for reading chain state.
Package chains defines chain-agnostic clients for reading chain state.
chains/evm
Package evm implements the chain client for EVM chains.
Package evm implements the chain client for EVM chains.
config
Package config contains config and flag parsing logic
Package config contains config and flag parsing logic
deploy
Package deploy is the target-agnostic deployment engine: manifest-driven, idempotent steps over a per-target Target implementation.
Package deploy is the target-agnostic deployment engine: manifest-driven, idempotent steps over a per-target Target implementation.
deploy/evm
Package evm implements the deploy Target for EVM chains.
Package evm implements the deploy Target for EVM chains.
deploy/manifest
Package manifest stores generated per-chain deployment records.
Package manifest stores generated per-chain deployment records.
livevalidate
Package livevalidate exercises every network-dependent check a relayer config implies, without starting a runnable process.
Package livevalidate exercises every network-dependent check a relayer config implies, without starting a runnable process.
network
Package network provides network-related tools.
Package network provides network-related tools.
pkg/ecrecover
Package ecrecover recovers secp256k1 signers in the form the light clients accept.
Package ecrecover recovers secp256k1 signers in the form the light clients accept.
pkg/graceful
Package graceful contains API for working with graceful application shutdown.
Package graceful contains API for working with graceful application shutdown.
relay/prover
Package prover generates packet membership/non-membership proofs and light-client update payloads.
Package prover generates packet membership/non-membership proofs and light-client update payloads.
relay/prover/besubft
Package besubft implements prover.Prover for a Besu light client, QBFT or IBFT 2.0: it reads the client's state from the host chain, fetches sealed headers and eth_getProof results from the Besu chain it tracks and encodes update and membership payloads.
Package besubft implements prover.Prover for a Besu light client, QBFT or IBFT 2.0: it reads the client's state from the host chain, fetches sealed headers and eth_getProof results from the Besu chain it tracks and encodes update and membership payloads.
relay/prover/remote
Package remote implements the relayer's Prover against a ProverService, so a custom light client is a service rather than code in the relayer.
Package remote implements the relayer's Prover against a ProverService, so a custom light client is a service rather than code in the relayer.
relay/txbuilder
Package txbuilder assembles transactions from packet relay and client update details.
Package txbuilder assembles transactions from packet relay and client update details.
relay/txbuilder/evm
Package evm implements txbuilder.TxBuilder for EVM chains: it packs an ICS26Router.updateClient call plus one recvPacket/ackPacket/timeoutPacket call per packet relay item into an IBCMulticall batch.
Package evm implements txbuilder.TxBuilder for EVM chains: it packs an ICS26Router.updateClient call plus one recvPacket/ackPacket/timeoutPacket call per packet relay item into an IBCMulticall batch.
relay/watcher
SPDX-License-Identifier: Apache-2.0
SPDX-License-Identifier: Apache-2.0
service/relayer
Package relayer implements the relayer business logic.
Package relayer implements the relayer business logic.
testutil/certs
Package certs writes throwaway self-signed certificates for tests that load TLS settings from files.
Package certs writes throwaway self-signed certificates for tests that load TLS settings from files.
testutil/proverservice
Package proverservice serves the attestation prover over ProverService, so the contract can be exercised without a second light-client implementation.
Package proverservice serves the attestation prover over ProverService, so the contract can be exercised without a second light-client implementation.
testutil/proverservice/cmd command
Command testprover serves the attestation prover over ProverService so the wire contract can be exercised end to end.
Command testprover serves the attestation prover over ProverService so the wire contract can be exercised end to end.
txsubmitter
Package txsubmitter simulates, signs, and broadcasts transactions for the relayer.
Package txsubmitter simulates, signs, and broadcasts transactions for the relayer.
txsubmitter/evm
Package evm signs and broadcasts EVM transactions.
Package evm signs and broadcasts EVM transactions.
types/v2
Package v2 contains shared IBC v2 domain types.
Package v2 contains shared IBC v2 domain types.
Package keyfile owns the on-disk format for local signer credentials.
Package keyfile owns the on-disk format for local signer credentials.
Package routeraccess owns which ICS26Router methods a deployment opens to everyone through its AccessManager.
Package routeraccess owns which ICS26Router methods a deployment opens to everyone through its AccessManager.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL