ibc

Abstract

This specification 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 (opens new window).

Contents

1. Applications

   1.1. Transfer

2. Core

3. Light Clients

   3.1 Solo Machine Client

   3.2 Tendermint Client

   3.3 Localhost Client

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 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 (opens new window): Implemented in x/ibc/core/02-client (opens new window)
• ICS 003 - Connection Semantics (opens new window): Implemented in x/ibc/core/03-connection (opens new window)
• ICS 004 - Channel and Packet Semantics (opens new window): Implemented in x/ibc/core/04-channel (opens new window)
• ICS 005 - Port Allocation (opens new window): Implemented in x/ibc/core/05-port (opens new window)
• ICS 006 - Solo Machine Client (opens new window): Implemented in x/ibc/light-clients/06-solomachine (opens new window)
• ICS 007 - Tendermint Client (opens new window): Implemented in x/ibc/light-clients/07-tendermint (opens new window)
• ICS 009 - Loopback Client (opens new window): Implemented in x/ibc/light-clients/09-localhost (opens new window)
• ICS 018- Relayer Algorithms (opens new window): Implemented in it's own relayer repository (opens new window)
• ICS 020 - Fungible Token Transfer (opens new window): Implemented in x/ibc/applications/transfer (opens new window)
• ICS 023 - Vector Commitments (opens new window): Implemented in x/ibc/core/23-commitment (opens new window)
• ICS 024 - Host Requirements (opens new window): Implemented in x/ibc/core/24-host (opens new window)
• ICS 025 - Handler Interface (opens new window): 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 (opens new window): 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 (opens new window): 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.

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 (opens new window)) modules:

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