README
¶
IBC CLI
IBC CLI deploys IBC onto a chain and runs the relayer and attestor processes that carry packets across it.
See docs/6-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.4 or later
Support
| Supported | |
|---|---|
| Chain types | evm |
| Light client types | attestation |
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 --chain <chainA> --counterparty-chain <chainB> --yes
./bin/ibc deploy client --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> --chain <chainA> --yes
./bin/ibc deploy ift --name <name> --symbol <symbol> --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/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. |
|
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/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 state proofs.
|
Package prover generates packet membership/non-membership proofs and light-client state proofs. |
|
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 a single ICS26Router.multicall transaction.
|
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 a single ICS26Router.multicall transaction. |
|
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/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 signs and broadcasts transactions for the relayer.
|
Package txsubmitter signs and broadcasts transactions for the relayer. |
|
txsubmitter/evm
Package evm submits transactions to EVM chains.
|
Package evm submits transactions to EVM chains. |
|
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. |
Click to show internal directories.
Click to hide internal directories.