cosmos-sdk/x/ibc/spec

ibc

Abstract

This paper defines the implementation of the IBC protocol on the Cosmos SDK, the changes made to the specification and where to find each specific ICS spec within the module.

For the general specification please refer to the Interchain Standards.

Contents

1. Concepts
2. State
3. State Transitions
4. Messages
5. Callbacks
6. Events

Implementation Details

As stated above, the IBC implementation on the Cosmos SDK introduces some changes to the general specification, in order to avoid code duplication and to take advantage of the SDK architectural components such as the AnteHandler and transaction routing through Handlers.

Interchain Standards reference

The following list is a mapping from each Interchain Standard to their implementation in the SDK's x/ibc module:

• ICS 002 - Client Semantics: Implemented in x/ibc/02-client
• ICS 003 - Connection Semantics: Implemented in x/ibc/03-connection
• ICS 004 - Channel and Packet Semantics: Implemented in x/ibc/04-channel
• ICS 005 - Port Allocation: Implemented in x/ibc/05-port
• ICS 006 - Solo Machine Client: Implemented in x/ibc/light-clients/solomachine
• ICS 007 - Tendermint Client: Implemented in x/ibc/07-tendermint
• ICS 009 - Loopback Client: Implemented in x/ibc/09-localhost
• ICS 018- Relayer Algorithms: Implemented in it's own relayer repository
• ICS 020 - Fungible Token Transfer: Implemented in x/ibc-transfer
• ICS 023 - Vector Commitments: Implemented in x/ibc/23-commitment
• ICS 024 - Host Requirements: Implemented in x/ibc/24-host
• ICS 025 - Handler Interface: Handler interfaces are implemented at the top level in x/ibc/handler.go, which call each ICS submodule's handlers (i.e x/ibc/{XX-ICS}/handler.go).
• ICS 026 - Routing Module: Replaced by ADR 15 - IBC Packet Receiver.

Architecture Decision Records (ADR)

The following ADR provide the design and architecture decision of IBC-related components.

• ADR 001 - Coin Source Tracing: standard to hash the ICS20's fungible token denomination trace path in order to support special characters and limit the maximum denomination length.
• ADR 17 - Historical Header Module: Introduces the ability to introspect past consensus states in order to verify their membership in the counterparty clients.
• ADR 19 - Protobuf State Encoding: Migration from Amino to Protobuf for state encoding.
• ADR 020 - Protocol Buffer Transaction Encoding: Client side migration to Protobuf.
• ADR 021 - Protocol Buffer Query Encoding: Queries migration to Protobuf.
• ADR 026 - IBC Client Recovery Mechanisms: Allows IBC Clients to be recovered after freezing or expiry.

SDK Modules

• x/capability: The capability module provides object-capability keys support through scoped keepers in order to authenticate usage of ports or channels. Check ADR 3 - Dynamic Capability Store for more details.
• x/evidence: The evidence module provides the interfaces and client logic to handle light client misbehaviour. Check ADR 09 - Evidence Module for more details.

IBC module architecture

NOTE for auditors: If you're not familiar with the overall module structure from the SDK modules, please check this document as prerequisite reading.

For ease of auditing, every Interchain Standard has been developed in its own package. The development team separated the IBC TAO (Transport, Authentication, Ordering) ICS specifications from the IBC application level specification. The following tree describes the architecture of the directories that the ibc (TAO) and ibc-transfer (ICS20) modules:

x/
├── ibc/
│  ├── 02-client/
│  ├── 03-connection/
│  ├── 04-channel/
│  ├── 05-port/
│  ├── light-clients/
│  │   └── solomachine/
│  ├── 07-tendermint/
│  ├── 09-localhost/
│  ├── 23-commitment/
│  ├── 24-host/
│  ├── client
│  │   ├── cli
│  │   │   └── cli.go
│  │   └── rest
│  │       └── rest.go
│  ├── keeper
│  │   ├── keeper.go
│  │   └── querier.go
│  ├── types
│  │   ├── errors.go
│  │   └── keys.go
│  ├── handler.go
│  └── module.go
└── ibc-transfer/