--help. The sections run in the order a reader meets them: config and keys, then deploy, then relayer and attestor, then tx and query, then migrate.
Global flags
--home is where the config file, the keystore, the manifests, and the relayer’s database live. A command that reads the config changes into that directory first, so a config naming keys/alice.json finds ~/.ibc/keys/alice.json.
config
The config is a YAML file describing every chain, connection, attestor, and signer the other commands use.
ibc config add-chain
Add a chain entry to the config.
--router out until the chain has a router to point at. ibc deploy render-config prints the finished chain entries, with the router and multicall addresses filled in from the manifests.
ibc config new
Create new config file.
The command refuses to overwrite an existing file, so it is safe to run twice.
ibc config validate
Validate config structure and cross-references.
--live adds checks that need live chain RPC endpoints. Pass relayer or attestor to also verify the file is sufficient to run that process. This command rejects unknown fields and unresolved cross-references.
"relayer": "valid" or "attestor": "valid".
keys
Keys live in <ibc-home>/keys/, one file each. These can be named by signers in the config file.
ibc keys import
Import a private key into <ibc-home>/keys/<name>.
ibc keys list
Lists every key from <ibc-home>/keys/.
ibc keys new
Saves key into <ibc-home>/keys/<name> or prints to stdout if name is not provided.
ibc keys show
Show key details from <ibc-home>/keys/<name>; optionally print the private key.
Warning: Do not run keys show --private on a shared or recorded terminal. The private key it prints controls every asset its address holds.
deploy
Deploying a working connection between two chains takes deploy core on both, then a deploy client subcommand on both, each client tracking the other chain. The tutorial walks that through end to end.
--chain is declared once for the whole deploy group, and the commands that provision something reject an empty value themselves: deploy core, deploy client attestation, deploy client besu, deploy gmp, and deploy ift.
--dry-run prints the steps a provisioning command would take and submits nothing. It has no effect on deploy show, deploy status, or deploy render-config; render-config --populate-config still writes the configuration.
Manifests are machine-generated. A command that provisions something reads the manifest, decides from it what is already done, and writes it back.
Warning: Do not edit a manifest by hand. A deploy command decides what to skip from it, and an edit that disagrees with the chain either is overwritten or makes the next run fail.
ibc deploy client attestation
Deploy and register an attestation light client.
--chain and watches --counterparty-chain. --attestors names the attestors watching the counterparty, since those are the signatures this client verifies. For remote attestors, pass the address instead of names. Left out entirely, the command fails when the config lists no attestors for the counterparty chain.
Rerunning with the same --client-id continues that client. Rerunning with different attestors or a different threshold under the same id fails and lists the differences, because those values are fixed when the client is constructed.
ibc deploy client besu
Deploy and register a Besu light client that trusts a recent counterparty header.
--chain is required.
evm.ics26Router with its deployed router address first; no local counterparty manifest is required. Rerunning under the same id with a different router, trusting period or trust level fails and lists the differences. See Besu light clients for choosing the trusting period.
ibc deploy core
Deploy the core IBC routing stack on one chain.
Deploys the access manager, router, and multicall. The manifest records the
proxies as
core.router and core.multicall. Rerunning resumes unfinished
deployment steps and skips contracts already deployed.
Pass --populate-config to write the router and multicall addresses into the chain’s config entry. With --dry-run, the config stays unchanged.
ibc deploy gmp
Deploy the ICS27-GMP app on one chain.
ibc deploy ift
Deploy an IFT token on one chain and set its rate limit, which IFT requires before any transfer. Rerunning with a different rate limit updates it. With an --owner other than the deployer no limit is set and the rate-limit flags are rejected: the owner must call setIFTRateLimit before any transfer.
ibc deploy ift-bridge
Register both sides of an IFT bridge between two chains’ tokens.
ibc deploy render-config
Print the existing config plus the settings to relay between two chains.
ibc deploy show
Print the recorded deployment manifest for a chain.
ibc deploy status
Verify recorded deployments against live chain state.
relayer
The relayer runs in the foreground and serves gRPC on server.listenAddr.
ibc relayer relay
Trigger relaying of the packets emitted by a source transaction.
ibc relayer run
Run the relayer.
One process can be both.
relayer run serves the relayer API and also runs every attestor the config marks local. It applies pending database migrations at startup, and --no-migrate skips that.
ibc relayer packets
List the packets the relayer is aware of, most recent first.
--all follows the pages and prints the combined result, and --cursor resumes from a previous one.
Use the short names in the flag table for --state. For example, --state succeeded selects PACKET_STATE_SUCCEEDED results. See API for the returned states.
attestor
The attestor also runs in the foreground and serves gRPC on server.listenAddr. The query commands take an attestor’s name as an argument rather than a flag, and --host dials an address directly instead of resolving that name through the config.
ibc attestor info
Query a local attestor’s identity.
ibc attestor latest-height
Query a local attestor’s latest attestable height.
ibc attestor run
Run the attestor.
ibc attestor state-attestation
Query a local attestor for a state attestation at --height.
Pass a positive
--height. Zero and omission are rejected. Use ibc attestor latest-height <name> to get the highest attestable height.
tx
These commands submit transactions to a chain.
ibc tx ift mint
Mint --amount of the IFT token at --ift to --to. The --from signer must be the token’s owner.
ibc tx ift send
Initiate a cross-chain transfer of --amount of the IFT token at --ift, over the bridge registered for --client-id, to --to on the counterparty chain.
relayer relay.
query
These commands read chain state and submit nothing.
ibc query ift balance
Query an address’s IFT token balance.
migrate
These commands move the schema of the relayer’s database up and down.
ibc migrate down
Migrate DB down.
migrate down reverses one migration, the most recent.
ibc migrate status
Print migration status.
ibc migrate up
Migrate DB up.
Migrations run against the db block, so --db picks a different database for one invocation.
Next steps
- Configuration for the file these commands read.
- API for the gRPC calls behind
relayer relay,relayer packets, and the attestor queries.