IBC CLI v0.2.0-rc.1

Description

This release candidate adds automatic relaying, Besu IBFT 2.0 and QBFT light client support, partial-failure relay batching through IBCMulticall, and operational reliability and observability improvements.

Features

• Auto-relay: the relayer can watch for new packets over WebSockets and clear them automatically, with optional clearing on startup and at a configured interval.
• Besu light client: the CLI can deploy and relay over Besu IBFT 2.0 and QBFT light clients. It detects the consensus mechanism automatically.
• IBCMulticall: EVM packet batches are relayed through IBCMulticall. Individual calls can fail without reverting the rest of the batch, and failed packets remain retryable.
• Remote provers: the relayer can use a remote ProverService for light client types it does not implement locally.
• Observability: relayer, attestor, EVM RPC, wallet, and attestation aggregation metrics have been added, together with configurable structured logging and gRPC health checks.

Improvements

• EVM transaction submission: the relayer allocates nonces locally, replaces transactions using the lowest unmined nonce, and escalates replacement fees when transactions remain pending.
• Configuration: unknown YAML fields are rejected by default, validation errors include their configuration paths, and ibc config validate supports target-specific and live validation.
• RPC hardening: EVM RPC requests have timeouts and request and response size limits. Concurrent requests reuse connections.
• Relay throughput: new clearing work is bounded per pass, client updates can be submitted separately, and the default packet batch size is reduced to 25.
• Release artifacts: release archives include SPDX SBOMs and provenance attestations. Checksums and multi-platform container images are signed.
• Version reporting: ibc --version reports the CLI commit and the pinned ibc-contracts and ibc-go versions.

Bug Fixes

• Relay dispatch: completed packets are no longer dispatched twice by concurrent clearing work.
• Attestation validation: the relayer counts only signatures accepted by the light client and validates configured attestor addresses.
• Deployment configuration: reconciling a deployment no longer discards operator-supplied configuration.
• EVM validation: RPC chain IDs, acknowledgement emitters, and checksummed IFT bridge addresses are validated.

Breaking Changes and Upgrading

This release includes configuration and API-breaking changes. Configuration files now reject unknown fields. Remote provers use the declared client type with a separate remoteProver block instead of type: remote and params. Besu clients use type besu; besu-qbft is no longer accepted. Deployment manifests store typed attestation or besu parameters instead of an untyped params map. The remote ProverService API replaces StateProof with ClientUpdatePayloads, and deployment client commands use type-specific subcommands such as ibc deploy client attestation and ibc deploy client besu.

Existing configuration must be updated before starting this release. Pre-v0.2 deployment manifests are not migrated and must be recreated or converted to the typed format. Remote prover implementations must be updated for the new API. Database migrations run automatically during ibc relayer run unless --no-migrate is passed; operators using that flag must run ibc migrate up first.

This is a pre-release intended for testing and integration feedback before the final v0.2.0 release. For the full changelog, see the section below.

What's Changed

• feat(cli): remote prover by @dhfang in #1415
• fix(docs): attestor light client formatting by @bpiv400 in #1430
• feat(cli)!: config hardening by @swift1337 in #1440
• feat(cli): render config improvements by @dhfang in #1431
• feat: Setup configurable log level in cli by @Eric-Warehime in #1443
• feat: Add logging options to config by @Eric-Warehime in #1444
• feat: Log additions to relay by @Eric-Warehime in #1446
• feat(relayer): add metrics by @swift1337 in #1448
• feat(metrics): attestor: distinguish rpc / internal calls by @swift1337 in #1449
• feat(metrics): add eth client metrics by @swift1337 in #1451
• chore: Add IFT relay to demo by @dianab-cl in #1399
• ci: update golangci-lint to v2.13.2 by @gjermundgaraba in #1466
• fix(cli): improve EVM metrics and observability documentation by @gjermundgaraba in #1465
• feat(e2e): add e2e dump by @swift1337 in #1469
• chore: Add action 'Capslock Capability Baseline' by @dianab-cl in #1459
• fix(e2e): typo by @swift1337 in #1472
• fix: Revert "chore: Add IFT relay to demo" by @dianab-cl in #1479
• feat(relayer): auto-relay by @swift1337 in #1461
• fix(cli): reconcile deployment config without losing custom settings by @gjermundgaraba in #1468
• fix(auto-relay): remove panic handlers from watcher by @swift1337 in #1484
• feat(auto-relay): optimize clearer RPC calls by @swift1337 in #1485
• chore(deps): bump cockroachdb/swiss for Go 1.27 support by @gjermundgaraba in #1487
• ci: Add action 'Capslock Capability Diff' by @dianab-cl in #1483
• fix(docs): cli walkthrough by @dhfang in #1500
• chore(deps): bump go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp from 1.43.0 to 1.45.0 in /e2e by @dependabot[bot] in #1498
• feat: add Besu QBFT light client support by @gjermundgaraba in #1481
• ci: Reduce format for static analysis results by @dianab-cl in #1531
• docs: make the docs reference generator script more durable by @evanorti in #1499
• ci: run required checks in the merge queue by @gjermundgaraba in #1542
• fix(e2e): recover from container startup port conflicts by @gjermundgaraba in #1538
• chore: move to ibc-contracts main for the Besu QBFT light client by @gjermundgaraba in #1535
• chore: Bump vulnerable dependencies by @dianab-cl in #1540
• chore(deps): bump the go_modules group across 1 directory with 1 update by @dependabot[bot] in #1544
• ci: replace Depot runners with GitHub-hosted ubuntu-latest by @dianab-cl in #1502
• chore: add issue and PR templates by @dianab-cl in #1539
• ci: Add OpenSSF Scorecard by @dianab-cl in #1533
• feat: Add TLS support by @dianab-cl in #1503
• feat(e2e): add load tests by @swift1337 in #1530
• fix(cli): set an IFT rate limit in deploy ift by @gjermundgaraba in #1555
• test(e2e): relay an IFT transfer over a CLI-deployed Besu QBFT connection by @gjermundgaraba in #1556
• fix(cli): reuse connections to EVM nodes under concurrent calls by @gjermundgaraba in #1547
• fix(cli): match eth_getProof storage proofs to their slots by key by @gjermundgaraba in #1546
• chore(e2e): bump Anvil Docker image to v1.8.5 by @swift1337 in #1566
• docs: document IFT rate limits on the IFT contracts page by @gjermundgaraba in #1567
• fix(link): attestation commitment validation by @dhfang in #1462
• ci: add native Go fuzz tests and daily fuzzing by @gjermundgaraba in #1562
• fix(relayer): only count attestor signatures the light client accepts by @gjermundgaraba in #1563
• fix(besu): repair commit seals the light client would reject by @gjermundgaraba in #1565
• feat(metrics): attestation aggregation metrics by @dhfang in #1470
• feat(cli): add gRPC health checks by @dhfang in #1570
• test(e2e): relay over a CLI-deployed mixed besu-qbft/attestation connection by @gjermundgaraba in #1571
• chore(deps): move to the ibc-contracts go-abigen module by @gjermundgaraba in #1574
• test(e2e): set deploy test routers in place and drop the placeholder router by @gjermundgaraba in #1578
• feat(relayer): additional evm tx submission reliability mechanisms by @dhfang in #1560
• fix(evm): additional evm json rpc validation by @dhfang in #1572
• feat(cli): deploy IBCMulticall by @dhfang in #1584
• refactor(besu)!: generalize the QBFT light client into a besu client type by @gjermundgaraba in #1575
• feat(besu): add Besu IBFT 2.0 light client support by @gjermundgaraba in #15...

IBC CLI v0.1.0

The first beta of IBC CLI, an all-in-one binary that deploys IBC onto EVM chains and runs the relayer and attestors that carry packets between them.

Getting started

Start with Deploy IBC and send a token, which brings up two local chains, deploys the stack on both, and moves an Interchain Fungible Token across. From there, the guides cover running a standalone attestor and a standalone relayer, alongside a full reference for the configuration file, the commands, and the gRPC API.

What's in it

• Deployment — deploy the IBC core stack, attestation light clients, the ICS27 GMP app, and IFT tokens onto EVM chains.
• Relaying — relay packets, acknowledgements, and timeouts, with auto-relay over a websocket subscription or on-demand through the relayer API. Packet state is queryable and backed by SQLite or Postgres.
• Attestation — run attestors in the relayer process or standalone, with keys held in a local keyfile or a remote signer over gRPC.

Known limitations

This is a beta and is not feature-complete or production ready. In particular:

• No metrics.
• No TLS support.
• Auto-relay does not yet recover from a websocket subscription dropping or flush packets existing prior to relayer startup.
• The services require further security audit.

v1.0.0-rc6

Stargate-associated spec RC. This is alpha software, use at your own risk.