cosmos/ibc is the specification repository for interchain communication

One repository holds the spec, the tooling and the generated code

The repository describes itself as the canonical home of the inter-blockchain communication protocol, containing both the specifications that define it and the implementations that run it. It consolidates design rationale, protocol semantics and encoding descriptions.

The directory layout makes the split explicit, and it is a table in the project documentation rather than something you have to infer.

| Path | What it is | | --- | --- | | `spec/` | The Interchain Standards, the specifications for the protocol itself | | `cli/` | The IBC CLI, which deploys IBC onto a chain and runs the relayer and attestor processes | | `docs/` | How IBC works, the contracts, and the CLI, as tutorials and reference | | `e2e/` | Repository-wide black-box acceptance tests | | `proto/` | Canonical protobuf source files used across the services and implementations | | `gen/` | Committed code generated from canonical schemas and contract artifacts | | `examples/` | Runnable local chain setups to develop against | | `scripts/` | Repository-level scripts |

Two entries in that table carry most of the weight. The `spec/` directory is the protocol itself, and `cli/` is the only substantial piece of runnable software that lives here. The `examples/` directory points at a Besu to Besu setup.

The audience is therefore split between protocol engineers, who work in `spec/`, and operators, who work with the CLI.

IBC v2 drops the connection and channel handshakes

The current iteration of the protocol is IBC v2, and the project documentation states plainly what changed: it streamlines integration by removing the connection and channel handshake layers in favour of direct client-to-client packet flow.

That is a large change to the shape of the protocol. In IBC v1, which the documentation calls the original version, cross-chain communication is established through connection and channel handshakes before applications can exchange packets. In v2 the packet flows directly between clients, so the two layers that existed to negotiate a channel before use are gone from the path.

The v2 standard set is small, and every one of the listed standards is at the Draft stage. The core transport group covers client semantics, packet semantics, port allocation, host requirements and IBC application callbacks, and the application layer has one standard, General Message Passing, ICS-027. All of them are listed as implemented by ibc-go and maintained by the protocol team.

The IBC v1 set is larger and further along. Client semantics, connection semantics, channel and packet semantics, port allocation, vector commitments, host requirements, handler interface and routing module are all at the Candidate stage, and most are listed with two implementations, ibc-go and ibc-rs.

The stage column is the interesting one for anyone making a decision. A Candidate standard has a defined form and an implementation to test against, while a Draft standard is still being written, which is why the v2 set is uniformly earlier than the v1 set.

The standards table is how the protocol is governed

Every standard in the documentation is listed with its Interchain Standard number, its title, its stage and its maintainer, plus implementations where there are any. There is also a meta standard, ICS-001, the ICS Specification Standard, whose stage is listed as not applicable because it describes how the other standards are written rather than what the protocol does.

The table starts from a threshold. The documentation states that all standards at or past the Draft stage are listed, in ICS number order and sorted by category, so anything earlier than Draft is not published in this list.

The implementations column is the part that tells you how portable a standard is in practice. Most v1 core standards name both ibc-go and ibc-rs, which are two separate implementations of the same specification. Port allocation in v1 is the exception, listed with ibc-go alone, and in v2 everything is ibc-go alone. Two independent implementations of a standard is a much stronger position than one, because it tells you the specification is unambiguous enough to build twice.

The maintainer column is uniform, the protocol team, which is a simplification rather than a sign that nobody else is involved. The mechanism for outside participation is the contribution process, with guidelines in `spec/CONTRIBUTING.md`, and the repository also carries a `.gitvote.yml`.

The CLI deploys IBC and runs two distinct processes

The `cli/` directory holds the IBC CLI, and the documentation describes its two jobs. It deploys IBC onto a chain, and it runs the relayer and attestor processes that carry packets across it.

Two processes with different names is worth pausing on. The relayer is the component that observes packets committed on one chain and submits the corresponding proofs and messages on the other, which is the mechanism by which a packet crosses the boundary. The attestor is a separate role in the same deployment, and the CLI is what starts and manages both. The documentation covers them in `docs/6-ibc-cli/1-overview.md`.

For a developer, the practical surface is the CLI rather than the spec. The `docs/` tree is organised as a tutorial set, starting from what IBC is and why, through the components that carry a single packet between two chains, and then the CLI reference, so the reading order in the repository is the intended learning order.

There is also an `e2e/` directory of repository-wide black-box acceptance tests, which is a useful signal about how the project validates itself. Black-box tests at this level exercise the protocol across two chains rather than unit testing a function, and a repository that ships those as part of the main tree is one that expects the specifications to be checked against running systems.

Protobuf sources and generated code are committed side by side

The `proto/` directory holds the canonical protobuf source files used across the services and implementations, and `gen/` holds committed code generated from canonical schemas and contract artifacts. Both are in the repository, which means the generated output is reviewable in a diff rather than being a build artefact.

The `gen/` tree also contains Solidity ABI bindings, and the Makefile treats them as a separate project. The `GEN_SOLIDITY_ABI_DIR` variable points at `gen/go/solidity-abi`, and there are dedicated targets for linting those bindings and for compiling them with a test run.

A structural detail in the Makefile explains a lot about the repository. There is deliberately no Go module at the root, so the variable `GO_MODULE_DIRS` lists the modules that do exist, which are `cli`, `e2e` and the generated Solidity ABI directory. Anything that scans the Go code has to iterate those directories explicitly, because there is no single module to point at.

That is a direct consequence of the repository holding several things at once. A spec repository with one implementation could have a single root module. This one cannot, and the build tooling reflects it.

The Makefile encodes the governance checks

The checks in the Makefile are more than hygiene, given what this repository is.

The `lint-license` target runs the Apache skywalking-eyes license tool with a pinned version of 0.8.0 and the repository's `.licenserc.yaml` configuration, and there is a matching `lint-fix-license` target that adds missing headers. Every file in a specification repository needs an SPDX header, because the text of a standard is copied into implementations, and an unattributed file is a provenance problem rather than a style problem.

The `vulncheck` target installs govulncheck at a pinned version of 1.8.0 and runs it over each module in turn, with careful handling of the exit codes so a module that cannot be scanned is reported rather than silently passing. There is a `.govulncheck-ignore` file at the repository root, which means known findings are tracked explicitly rather than suppressed silently.

The rest of the file follows the same pattern of pinned versions and explicit targets, with `lint-gen` and `test-gen` for the generated bindings and a `help` target that lists every command with its description. The Makefile also carries an SPDX header of its own.

The licence is Apache-2.0, with a LICENSE file and a NOTICE file in the root, and the repository carries an OpenSSF Scorecard badge alongside a `.licenserc.yaml`, a `.golangci.yml` and a CHANGELOG.md.

Where to look if you want to run IBC rather than read it

The honest limitation of this repository is that it is a specification, and a specification is not something you can deploy on its own. The implementations ibc-go and ibc-rs live in separate repositories, and both appear in the implementations column of the standards table.

The difference in approach between the two paths is the thing to be clear about. Reading the spec gives you the exact semantics, including the edge cases that the prose in a tutorial usually smooths over, and it is the only source that is authoritative for both implementations at once. Building from the spec means implementing packets, proofs, timeouts and handshakes yourself, which is a serious undertaking and something only a chain team that wants its own implementation would take on.

Using an implementation instead gives you working code, and the cost is that you are bound by whatever that implementation has chosen, including its defaults, its error handling and its own bugs. The v1 standards where both ibc-go and ibc-rs are listed are the ones where a team can compare, and a difference in behaviour between the two is usually a sign that the spec left something open.

The CLI here sits in between. It is the tool that deploys IBC onto a chain and runs the processes that move packets, so it is the natural entry point for someone who wants to see the protocol work before deciding how deeply to commit to it. The `examples/besu-to-besu/` setup is the fastest way to do that, since it is a runnable local chain environment rather than a description of one.

Editorial conclusion

cosmos/ibc suits a protocol implementer, a chain team deciding whether to support cross-chain messaging, or a developer who needs the exact semantics of a standard rather than a blog summary of it. It is the wrong repository to look for application level APIs, because the runnable code here is the CLI and the tooling, not the chain modules. Check first whether the standard you care about has reached the Draft or Candidate stage, since every IBC v2 standard listed is still at Draft, and read the CLI documentation in `docs/6-ibc-cli/` before assuming the relayer and attestor roles are interchangeable.

Frequently asked questions

Official sources

1. cosmos/ibc on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases