Skip to main content
The IBC CLI is an all-in-one tool for deploying, configuring, and running an IBC connection between chains, simplifying the process of setting up and managing IBC connections. It consists of three parts:
  • Contract deployment for IBC Solidity contracts on EVM chains
  • A relayer for moving packets between chains
  • An attestor service for attestation light clients
Each of these services is configurable under a single configuration file. Proof aggregation and transaction-building logic are internalized in the relayer. Relayers and attestors can be run in a single process or standalone using the CLI. IBC CLI also handles contract deployment and configuration for the operator. One ibc.yml configuring the relayer, attestor, and deployment halves of the ibc binary

​
Deployment

You can deploy the IBC Solidity contracts to an EVM chain with an RPC endpoint and a funded key. The IBC CLI deploys them and wires them to each other. It deploys the following contracts:
  • The core routing stack: an access manager, the ICS26Router, and IBCMulticall, with both contracts behind proxies.
  • A light client on each chain tracking the other, registered on the router: an attestation light client, or a Besu light client when the tracked chain runs Besu QBFT or IBFT 2.0.
  • The ICS27GMP app and its account logic.
  • IFT token contracts, and the bridges between them.
Signer keys, contract addresses, client IDs, and finality settings all have to stay consistent across the on-chain and off-chain pieces, which can be difficult to manage by hand. The CLI handles the deployment and the checks that catch a mismatch, so you do not write your own deployment and query scripts. Follow the tutorial to learn the full process of deploying IBC between two chains and sending a token. Each side can use a different client type. The tutorial pairs an attestation light client with a Besu consensus light client. Deployment is done from a single key. It becomes the access manager’s admin, which governs the router, multicall, and the GMP app, and the default owner of any token you deploy. See Permissions and upgrades for more details.

​
The relayer

Relayers are responsible for moving packets between chains. The IBC CLI provides a relayer service that can run on its own, or in one process with an attestor. It moves packets between the chains named in its configuration file. Its work starts after an application has already sent a packet. The relayer reads that send transaction on the source chain, gathers the proofs the packet needs, and submits them to the destination chain. It then carries the acknowledgement back, or times the packet out if it never arrived. The Relayer page covers what a relayer is for and what it is trusted with. Relayer internals: relay API, store, delivery, and prover, between the source and destination chains

​
Starting a relay

A relay starts one of two ways:
  • With autoRelay enabled on a client end, the relayer subscribes to that chain over a websocket and carries packets leaving it as they are sent.
  • Manually: a relay begins by calling the relayer’s API, naming the source chain, the transaction, and which of its packets to relay.
Packets heading the same way are batched and delivered together, rather than one at a time.

​
Proof generation and transaction building

Before it can deliver anything, the relayer needs proof of the packets for the light client. It runs one prover for each light client it submits to, and the prover depends on the client type. For an attestation light client, the prover asks the client’s attestors to attest to the chain’s state at a height. It verifies each signature and checks that the attested data matches the expected chain state or packet claim before counting it toward the client’s threshold. Once enough attestors agree, it packages the attestation and its signatures together. That package is the proof. For a Besu light client, the prover reads the sealed header and an eth_getProof result from the Besu chain itself and packages the header with the account and storage proofs. The client’s validator rules are checked when the transaction is simulated. Either way it returns the client updates for a height, and a proof for each packet in the batch. The relayer then turns each batch of packets heading to the same destination into one transaction. Every configured EVM chain must have router and IBCMulticall addresses to run a relayer; an attestor requires only the router address. CLI deployments include both in the generated config. Each batch carries a list of operations: first the client update needed for the height just proved, if any, then one delivery for each packet in the batch. When the client needs several updates, as a Besu client crossing validator set changes can, the relayer first sends all but the last in transactions of their own, and the last goes with the deliveries; see Relayer.

​
Signing and gas

A relayer’s signing key is set in the IBC CLI’s configuration file. That key can be a file on disk or a remote key manager. The ibc keys commands can create a key and add it to the configuration in one step. A connection relayed in both directions submits to both chains, so it needs a funded key on each to pay gas. Nothing reimburses those fees.

​
Database

The relayer keeps a database to store the status of each packet and the transactions that carried it. It runs on SQLite by default, and Postgres support is available for production deployments, configured in the configuration file.

​
Relayer API

The relayer exposes a gRPC API. Relay asks it to deliver the packets in a transaction, and Packets lists the packets it knows about and the state each one reached.

​
The attestor

An attestor signs statements about a chain: its state at a height, and the packets it holds. See Attestors for what it signs and why that is trustworthy. An attestor process is a stateless gRPC service with a connection to the chain it watches. It has a signer, and a rule for how far behind the head it will sign. Its signer is configured in the IBC CLI’s configuration file. Just like the relayer’s signer, it can be a key file or a remote key manager. An attestor’s finality offset decides how far behind the chain head it signs. One process can host several attestors, each with its own signer and one chain it watches. That is what lets a single process attest for several chains at once. One ibc attestor process serving three named attestors, each with its own signer and chain RPC IBC CLI allows you to run an attestor as its own standalone process, or in-process with the relayer.
Warning: Run one attestor per process in security-critical deployments.

​
Configuration

IBC CLI stores the configuration for deployment, the relayer, and attestors in a single YAML file at ~/.ibc/ibc.yml. It has eight blocks:
  • chains: the chains all three parts talk to, with router and multicall addresses for relaying, an RPC endpoint, and a websocket endpoint where auto-relay is enabled.
  • relayer: the connections to relay, and per-chain relay settings.
  • attestors: the attestors this process runs, or queries over the network.
  • signers: the keys, each under an alias the other blocks reference by name.
  • server and db: the address to listen on, and the relayer’s database.
  • logging and observability: the log level and format, and the metrics endpoint.
Most configurations can be generated. ibc config new writes a starting file, config add-chain appends a chain, and the ibc keys commands can append a signer. After deploying, ibc deploy render-config prints the complete config with deployment settings merged in. Add --populate-config to save it. The IBC CLI also validates the file with the ibc config validate command. The configuration reference carries every key and its default. CLI commands and the API reference cover the rest of the surface. See Observability and metrics for metric export modes and the metrics reference.

​
Next steps