IBC-Go Documentation

欢迎阅读 IBC-Go 文档，它是 Inter-Blockchain Communication Protocol（IBC，区块链间通信协议）的 Golang 实现。 Inter-Blockchain Communication Protocol（IBC）是一种使区块链能够彼此通信的协议。支持 IBC 的链只要将数据编码为字节，就可以共享任何类型的数据，从而实现业内功能最丰富的跨链交互。IBC 可用于构建各种跨链应用，包括代币转账、原子交换、多链智能合约（无论虚拟机是否彼此可理解）以及跨链账户控制。IBC 具备安全性且无需许可。 该协议通过规定一组数据结构、抽象和语义来实现这种互操作性，任何满足少量要求的分布式账本都可以实现这些规范。

​

IBC v2 概览

IBC v2 是对 IBC Classic 协议的一次精简重设计。它降低了架构复杂度，并将 IBC 的连接能力扩展到 EVM 等按 gas 计量的环境。该协议围绕三个组件组织：

• Clients（客户端） 跟踪对手链的共识状态，并作为连接的主要标识符。在 IBC v2 中，数据包引用的是源客户端和目标客户端，而不是通道；系统通过针对对手方已存储共识状态证明数据包承诺来完成验证。
• Router（路由器） 按端口 ID 将数据包分发到正确的应用模块。它将 IBC Classic 中原本分散在连接、通道和端口路由器中的路由逻辑整合为单一抽象。
• Applications（应用） 实现 IBCModule 接口以处理数据包生命周期：OnSendPacket、OnRecvPacket、OnAcknowledgementPacket 和 OnTimeoutPacket。这里没有通道握手回调；应用版本和编码格式会在发送时按每个负载单独声明。

IBC v2 中的数据包可携带一个或多个 Payload（负载）。每个负载都会指定源端口、目标端口、应用版本、编码方式（例如 protobuf、JSON 或 ABI）以及原始应用数据。单个数据包可以同时携带多个应用的负载。执行是原子的：如果任一负载失败，该数据包产生的所有状态变更都会回滚。 IBC v2 的显著特性：

• Relayers（中继器） 是链下进程，用于观察发送链上的数据包承诺，并连同 Merkle 证明提交到接收链；对于确认和超时，也会反向执行同样的流程。默认情况下，中继无需许可；IBC v2 还可选择按客户端限制中继，只允许授权白名单中的实体执行。
• 客户端对是连接的基本原语：两条链通过一对轻客户端通信，每条链各保存一个。在数据包流转之前，双方链都要将对方的客户端 ID 注册为自己的对手方。这替代了 IBC Classic 中多步骤的连接与通道握手。
• 灵活的客户端类型：客户端并不限于轻客户端。任何验证模型都可以实现，例如轻客户端、多签、ZK 证明验证器或条件型客户端。这使得在以太坊等链上进行低成本的轻客户端验证成为可能。
• 无需通道升级：由于应用版本和编码方式按每个负载声明，应用可以在不进行通道升级协调的情况下变更其线协议格式。所有应用版本都通过同一条客户端连接进行路由。
• 仅基于时间戳的超时：IBC v2 数据包只携带一个 Unix 时间戳超时值（秒）。区块高度具有链特定性，无法在以太坊等异构链之间直接对应，因此时间戳被用作通用原语。如果数据包在超时前未被接收，中继器可以提交未接收证明，由发送链将该数据包判定为超时。

如需深入理解协议设计，请参阅 IBC v2 规范。 如需高层介绍，请参阅 IBC v2 发布公告博客文章。 如果你希望使用 IBC v2 连接 Cosmos 链与以太坊，可以查看 IBC Eureka 文档。

​

IBC Classic 高层概览

下图展示了 IBC 在高层上的工作方式： 传输层（TAO）提供在链之间建立安全连接并认证数据包所需的基础设施。应用层构建在传输层之上，并精确定义发送链和接收链应如何封装和解释数据包。 IBC 提供了一个可靠、无需许可且通用的基础层（允许安全中继数据包），同时通过将应用设计（即对数据包数据进行解释并执行操作）上移到更高层，借助关注点分离实现可组合性和模块化。这种分层体现在以下类别中：

• IBC/TAO 包括数据包的传输、认证与排序（Transport, Authentication, and Ordering），即基础设施层。
• IBC/APP 包括通过传输层传递的数据包的应用处理器。这些应用包括但不限于同质化代币转账（ICS-20）、NFT 转账（ICS-721）以及跨链账户（ICS-27）。
• 应用模块（Application module）：汇集任何应用、中间件或智能合约，它们可以封装下游应用处理器以提供增强功能。

请注意图中的三个关键要素：

• 各条链依赖中继器进行通信。Relayers 是 IBC 的“物理”连接层：它们是链下进程，通过扫描各链状态、构造适当的数据报，并在协议允许的情况下在对侧链上执行这些数据报，负责在运行 IBC 协议的两条链之间中继数据。
• 多个中继器可以为一个或多个通道提供服务，在链之间发送消息。
• 连接两侧都会使用对方链的轻客户端来快速验证传入消息。

---

Welcome to the documentation for IBC-Go, the Golang implementation of the Inter-Blockchain Communication Protocol! The Inter-Blockchain Communication Protocol (IBC) is a protocol that allows blockchains to talk to each other. Chains that speak IBC can share any type of data as long as it’s encoded in bytes, enabling the industry’s most feature-rich cross-chain interactions. IBC can be used to build a wide range of cross-chain applications that include token transfers, atomic swaps, multi-chain smart contracts (with or without mutually comprehensible VMs), and cross-chain account control. IBC is secure and permissionless. The protocol realizes this interoperability by specifying a set of data structures, abstractions, and semantics that can be implemented by any distributed ledger that satisfies a small set of requirements.

​

Overview of IBC v2

IBC v2 is a streamlined redesign of the IBC Classic protocol. It reduces architectural complexity and expands IBC connectivity to gas-metered environments such as the EVM. The protocol is organized around three components:

• Clients track the consensus state of a counterparty chain and serve as the primary identifier for a connection. A packet in IBC v2 references a source client and a destination client — not a channel — and is verified by proving the packet commitment against the counterparty’s stored consensus state.
• Router directs packets to the correct application module by port ID. It consolidates the routing logic that was previously spread across connections, channels, and the port router in IBC Classic into a single abstraction.
• Applications implement the IBCModule interface to handle the packet lifecycle: OnSendPacket, OnRecvPacket, OnAcknowledgementPacket, and OnTimeoutPacket. There are no channel handshake callbacks; application version and encoding are declared per-payload at send time.

Packets in IBC v2 carry one or more Payloads. Each payload specifies the source port, destination port, application version, encoding (e.g. protobuf, JSON, or ABI), and the raw application data. A single packet can carry payloads for multiple applications simultaneously. Execution is atomic: if any payload fails, all state changes from that packet are rolled back. Notable features of IBC v2:

• Relayers are off-chain processes that observe packet commitments on the sending chain and submit them with Merkle proofs to the receiving chain, and do the same in reverse for acknowledgements and timeouts. Relaying is permissionless by default; IBC v2 optionally allows chains to restrict relaying per client to an authorized allowlist.
• Client pairs are the connection primitive: two chains communicate via a pair of light clients, one on each chain. Before packets can flow, each chain registers the other’s client ID as its counterparty. This replaces the multi-step connection and channel handshakes of IBC Classic.
• Flexible client types: clients are not restricted to light clients. Any verification model can be implemented — light clients, multi-sig, ZK-proof verifiers, or conditional clients. This enables cost-efficient light client verification on chains like Ethereum.
• No channel upgrades: since application version and encoding are declared per-payload, applications can change their wire format without a channel upgrade coordination process. All application versions route through the same client connection.
• Timestamp-only timeout: IBC v2 packets carry a single Unix timestamp timeout (in seconds). Block heights are chain-specific and don’t translate across heterogeneous chains like Ethereum, so timestamps are used instead as a universal primitive. If a packet is not received before the timeout, a relayer can submit a proof of non-receipt and the sending chain times out the packet.

For a detailed understanding of the protocol design, refer to the IBC v2 specification. For a high-level introduction, see the IBC v2 announcement blog post. If you are interested in using IBC v2 to connect Cosmos chains and Ethereum, take a look at the IBC Eureka documentation.

​

High-level overview of IBC Classic

The following diagram shows how IBC works at a high level: The transport layer (TAO) provides the necessary infrastructure to establish secure connections and authenticate data packets between chains. The application layer builds on top of the transport layer and defines exactly how data packets should be packaged and interpreted by the sending and receiving chains. IBC provides a reliable, permissionless, and generic base layer (allowing for the secure relaying of data packets), while allowing for composability and modularity with separation of concerns by moving application designs (interpreting and acting upon the packet data) to a higher-level layer. This separation is reflected in the categories:

• IBC/TAO comprises the Transport, Authentication, and Ordering of packets, i.e. the infrastructure layer.
• IBC/APP consists of the application handlers for the data packets being passed over the transport layer. These include but are not limited to fungible token transfers (ICS-20), NFT transfers (ICS-721), and interchain accounts (ICS-27).
• Application module: groups any application, middleware or smart contract that may wrap downstream application handlers to provide enhanced functionality.

Note three crucial elements in the diagram:

• The chains depend on relayers to communicate. Relayers are the “physical” connection layer of IBC: off-chain processes responsible for relaying data between two chains running the IBC protocol by scanning the state of each chain, constructing appropriate datagrams, and executing them on the opposite chain as is allowed by the protocol.
• Many relayers can serve one or more channels to send messages between the chains.
• Each side of the connection uses the light client of the other chain to quickly verify incoming messages.