IBC
互链通信协议概览
这是 IBC v2 [Eureka] 的摘要视图。如需更完整的细节、指南及更多内容,请访问官方的《Eureka 文档》。
核心数据结构
Packet 是 IBC v2 中用于跨链通信的主要容器。每个数据包都可以封装一个或多个应用专用的 Payload 对象。
超时时间是基于目标链的时钟来衡量的,而不是源链。这可以确保即使存在时钟漂移也依然安全。
链上关键组件
客户端(ICS-02)- 轻客户端
客户端(ICS-02)- 轻客户端
轻客户端通过针对受信任共识的密码学证明,验证对手方链的状态。每个 IBC 客户端都会定义一个
ClientState(长期参数)以及持续演进的 ConsensusState(状态快照)。如果共识假设被破坏,作恶证据可以冻结该客户端。可证明存储(ICS-24)
可证明存储(ICS-24)
一种支持 Merkle 证明的键值存储,用于保存承诺。
这些标准化路径使对手方能够验证数据包是否存在、回执以及确认信息。
| 值 | 路径格式 |
|---|---|
| 数据包承诺 | {sourceClientId}0x1{bigEndianUint64Sequence} |
| 数据包回执 | {destClientId}0x3{bigEndianUint64Sequence} |
| 确认 | {destClientId}0x2{bigEndianUint64Sequence} |
路由与处理器(ICS-25)
路由与处理器(ICS-25)
IBC 处理器为数据包中继公开了标准函数:
SendPacket、RecvPacket、AcknowledgePacket 和 TimeoutPacket。它强制执行仅一次投递,确保有效的顺序语义(有序、无序或有序允许超时),并将数据包分发给正确的应用。端口分配(ICS-05)
端口分配(ICS-05)
应用在初始化期间必须绑定唯一的
portId 值。每个 Payload 中都会引用端口,以便为入站数据包进行路由。应用接口(ICS-26)
启用 IBC 的应用必须实现以下回调,以管理数据包生命周期:OnRecvPacket(...)- 在目标链上执行,用于处理传入数据。必须返回一个确认,其中可以包含成功数据或错误信息。OnAcknowledgePacket(...)- 在确认被验证后于源链上执行。它提供确认数据,以便发送方应用完成最终处理或回滚操作。OnTimeoutPacket(...)- 当发生超时时于源链上执行,用于支持回滚或退款。
数据包生命周期
1. SendPacket(源链)
1. SendPacket(源链)
应用数据会被封装进一个
Packet,分配一个 sequence,并提交到数据包承诺路径。2. RecvPacket(目标链)
2. RecvPacket(目标链)
目标链通过其轻客户端验证数据包承诺证明。验证成功后,会在数据包回执路径存储一个回执,并调用
OnRecvPacket。3. WriteAcknowledgement(目标链)
3. WriteAcknowledgement(目标链)
接收方应用返回一个
Acknowledgement。该确认会被提交到确认路径下,从而允许源链进行证明验证。4. AcknowledgePacket(源链)
4. AcknowledgePacket(源链)
源链验证确认证明,删除原始承诺,并在发送方应用上调用
OnAcknowledgePacket。5. TimeoutPacket(源链)
5. TimeoutPacket(源链)
如果在目标链产生回执之前
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
ThePacket is the primary container for cross-chain communication in IBC v2. Each packet may wrap one or more application-specific Payload objects.
Timeout is measured against the destination chain’s clock, not the source. This ensures safety even under clock drift.
Key On-Chain Components
Client (ICS-02) – Light Client
Client (ICS-02) – Light Client
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.Provable Store (ICS-24)
Provable Store (ICS-24)
A Merkle-proof-capable key–value store used for commitments.
These standardized paths allow counterparties to verify packet existence, receipts, and acknowledgements.
| Value | Path Format |
|---|---|
| Packet Commitment | {sourceClientId}0x1{bigEndianUint64Sequence} |
| Packet Receipt | {destClientId}0x3{bigEndianUint64Sequence} |
| Acknowledgement | {destClientId}0x2{bigEndianUint64Sequence} |
Routing & Handler (ICS-25)
Routing & Handler (ICS-25)
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.Port Allocation (ICS-05)
Port Allocation (ICS-05)
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
1. SendPacket (Source Chain)
1. SendPacket (Source Chain)
Application data is wrapped into a
Packet, assigned a sequence, and committed at the Packet Commitment path.2. RecvPacket (Destination Chain)
2. RecvPacket (Destination Chain)
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.3. WriteAcknowledgement (Destination Chain)
3. WriteAcknowledgement (Destination Chain)
The receiving application returns an
Acknowledgement. This is committed under the Acknowledgement path, allowing proof for the source chain.4. AcknowledgePacket (Source Chain)
4. AcknowledgePacket (Source Chain)
Source chain verifies the acknowledgement proof, deletes the original commitment, and calls
OnAcknowledgePacket on the sending application.5. TimeoutPacket (Source Chain)
5. TimeoutPacket (Source Chain)
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.