IBC

互链通信协议概览
这是 IBC v2 [Eureka] 的摘要视图。如需更完整的细节、指南及更多内容,请访问官方的《Eureka 文档》。

核心数据结构

Packet 是 IBC v2 中用于跨链通信的主要容器。每个数据包都可以封装一个或多个应用专用的 Payload 对象。
// 在链之间发送的主容器
interface Packet {
  sourceClientId: bytes;    // 目标链的客户端 ID(存储在源链上)
  destClientId: bytes;      // 源链的客户端 ID(存储在目标链上)
  sequence: uint64;         // 每个客户端对单调递增的 nonce
  timeout: uint64;          // 数据包过期的 UNIX 时间戳(秒)
  data: Payload[];          // 应用负载
}

// 应用专用数据
interface Payload {
  sourcePort: bytes;  // 发送方应用标识符
  destPort: bytes;    // 接收方应用标识符
  version: string;    // 应用版本
  encoding: string;   // 用于解码的 MIME 类型
  value: bytes;       // 不透明的应用数据
}
超时时间是基于目标链的时钟来衡量的,而不是源链。这可以确保即使存在时钟漂移也依然安全。

链上关键组件

轻客户端通过针对受信任共识的密码学证明,验证对手方链的状态。每个 IBC 客户端都会定义一个 ClientState(长期参数)以及持续演进的 ConsensusState(状态快照)。如果共识假设被破坏,作恶证据可以冻结该客户端。
一种支持 Merkle 证明的键值存储,用于保存承诺。
值路径格式
数据包承诺{sourceClientId}0x1{bigEndianUint64Sequence}
数据包回执{destClientId}0x3{bigEndianUint64Sequence}
确认{destClientId}0x2{bigEndianUint64Sequence}
这些标准化路径使对手方能够验证数据包是否存在、回执以及确认信息。
IBC 处理器为数据包中继公开了标准函数: SendPacket、RecvPacket、AcknowledgePacket 和 TimeoutPacket。它强制执行仅一次投递,确保有效的顺序语义(有序、无序或有序允许超时),并将数据包分发给正确的应用。
应用在初始化期间必须绑定唯一的 portId 值。每个 Payload 中都会引用端口,以便为入站数据包进行路由。

应用接口(ICS-26)

启用 IBC 的应用必须实现以下回调,以管理数据包生命周期:
  • OnRecvPacket(...) - 在目标链上执行,用于处理传入数据。必须返回一个确认,其中可以包含成功数据或错误信息。
  • OnAcknowledgePacket(...) - 在确认被验证后于源链上执行。它提供确认数据,以便发送方应用完成最终处理或回滚操作。
  • OnTimeoutPacket(...) - 当发生超时时于源链上执行,用于支持回滚或退款。

数据包生命周期

应用数据会被封装进一个 Packet,分配一个 sequence,并提交到数据包承诺路径。
目标链通过其轻客户端验证数据包承诺证明。验证成功后,会在数据包回执路径存储一个回执,并调用 OnRecvPacket。
接收方应用返回一个 Acknowledgement。该确认会被提交到确认路径下,从而允许源链进行证明验证。
源链验证确认证明,删除原始承诺,并在发送方应用上调用 OnAcknowledgePacket。
如果在目标链产生回执之前 timeout 已经过期,源链会通过不存在性证明来验证这一点,删除承诺,并触发 OnTimeoutPacket。

IBC

An Overview of the Inter-Blockchain Communication Protocol
This is a summary view of IBC v2 [Eureka]. For more comprehensive details, guides and more please visit the official Eureka documentation.

Core Data Structures

The Packet is the primary container for cross-chain communication in IBC v2. Each packet may wrap one or more application-specific Payload objects.
// Main container sent between chains
interface Packet {
  sourceClientId: bytes;    // Client ID for destination chain (stored on source)
  destClientId: bytes;      // Client ID for source chain (stored on destination)
  sequence: uint64;         // Monotonically increasing nonce per client-pair
  timeout: uint64;          // UNIX timestamp (seconds) for packet expiry
  data: Payload[];          // Application payload(s)
}

// Application-specific data
interface Payload {
  sourcePort: bytes;  // Sending application identifier
  destPort: bytes;    // Receiving application identifier
  version: string;    // Application version
  encoding: string;   // MIME-type for decoding
  value: bytes;       // Opaque app data
}
Timeout is measured against the destination chain’s clock, not the source. This ensures safety even under clock drift.

Key On-Chain Components

A light client verifies the state of a counterparty chain with cryptographic proofs against trusted consensus.Each IBC client defines a ClientState (long-term parameters) and evolving ConsensusStates (snapshots). If consensus assumptions are violated, misbehaviour evidence can freeze the client.
A Merkle-proof-capable key–value store used for commitments.
ValuePath Format
Packet Commitment{sourceClientId}0x1{bigEndianUint64Sequence}
Packet Receipt{destClientId}0x3{bigEndianUint64Sequence}
Acknowledgement{destClientId}0x2{bigEndianUint64Sequence}
These standardized paths allow counterparties to verify packet existence, receipts, and acknowledgements.
The IBC handler exposes the standard functions for packet relay: SendPacket, RecvPacket, AcknowledgePacket, and TimeoutPacket.It enforces exactly-once delivery, ensures valid ordering (ordered, unordered, or ordered-allow-timeout), and dispatches packets to the correct application.
Applications must bind to unique portId values during initialization. Ports are referenced in every Payload for routing incoming packets.

Application Interface (ICS-26)

An IBC-enabled application must implement these callbacks to manage the packet lifecycle:
  • OnRecvPacket(...) – Executed on the destination chain to process incoming data. Must return an Acknowledgement, which may contain success data or an error.
  • OnAcknowledgePacket(...) – Executed on the source chain once an acknowledgement is verified. Provides acknowledgement data so the sending application can finalize or revert actions.
  • OnTimeoutPacket(...) – Executed on the source chain if a timeout occurs, enabling rollback or refunds.

Packet Lifecycle

Application data is wrapped into a Packet, assigned a sequence, and committed at the Packet Commitment path.
Destination chain verifies the packet commitment proof via its light client. Upon success, it stores a Receipt at the Packet Receipt path and invokes OnRecvPacket.
The receiving application returns an Acknowledgement. This is committed under the Acknowledgement path, allowing proof for the source chain.
Source chain verifies the acknowledgement proof, deletes the original commitment, and calls OnAcknowledgePacket on the sending application.
If the timeout elapses before a receipt exists on the destination chain, the source verifies this via proof of non-existence, deletes the commitment, and triggers OnTimeoutPacket.