IBC Core Protocol Spec

These basic structures form the foundation of the IBC protocol

For legacy IBC implementations, refer to the IBC‑go docs.

The latest version of Inter‑Blockchain Communication (IBC) enables token transfers across multiple blockchain environments through a standard set of components, interfaces, and a defined packet flow.

Core Data Structures

The Packet is the primary container for cross‑chain communication. Each packet wraps one or more application‑specific Payload objects.

packet.ts

// The main data 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 for ordering
  timeout: uint64;       // UNIX timestamp (seconds) when the packet expires
  data: Payload[];       // List of application payloads
}

// Application‑specific data and routing information
interface Payload {
sourcePort: bytes; // Identifies sending application module
destPort: bytes;   // Identifies receiving application module
version: string;   // App‑specific version for interpretation
encoding: string;  // MIME‑type for decoding appData
appData: bytes;    // Opaque application data
}

Key Components

Client (ICS‑02) – Light Client

An on‑chain light client that verifies the state of a counter‑party chain using cryptographic proofs against a trusted consensus state.

Primary entry points

• createClient
• updateClient
• verifyMembership
• verifyNonMembership

Provable Store (ICS‑24)

A Merkle‑proof‑capable key‑value store required on the host chain. Standardized paths enable verification by counter‑party chains.

Value	Path Format
Packet Commitment	{sourceClientId}0x1{bigEndianUint64Sequence}
Packet Receipt	{destClientId}0x2{bigEndianUint64Sequence}
Acknowledgement	{destClientId}0x3{bigEndianUint64Sequence}

Port Allocation (ICS‑05)

Applications must bind to unique portId values during initialization. The port is referenced in every Payload to route incoming packets.

Application Callbacks (ICS‑26)

An IBC‑enabled application must implement these callbacks:

• OnRecvPacket(payload) – Executed on the destination chain to process incoming data. Must return an Acknowledgement (success or error).
• OnAcknowledgePacket(payload, acknowledgement) – Executed on the source chain once an acknowledgement is verified, finalizing or compensating the originating action.
• OnTimeoutPacket(payload) – Executed on the source chain if no acknowledgement is received before timeout, allowing rollback or refunds.

Packet Lifecycle

The end‑to‑end flow from send to completion involves five discrete steps. Expand any step below for details.

1. SendPacket (Source Chain)

The sending application submits one or more Payload objects. The IBC handler wraps them in a Packet, assigns a new sequence number, and stores a cryptographic commitment at the Packet Commitment path.

2. RecvPacket (Destination Chain)

A relayer delivers the Packet together with a proof of its commitment. The destination chain’s IBC handler:

1. Locates the correct light client via destClientId.
2. Verifies the proof.
3. Stores a Receipt at the Packet Receipt path.
4. Invokes the destination module’s OnRecvPacket callback.

3. WriteAcknowledgement (Destination Chain)

The destination application returns an Acknowledgement (success data or error) from OnRecvPacket. The IBC handler commits this acknowledgement at the Acknowledgement path, making it available for relayers.

4. AcknowledgePacket (Source Chain)

A relayer brings the acknowledgement and its proof back to the source chain. After proof verification, the source chain’s handler:

• Deletes the original packet commitment.
• Calls OnAcknowledgePacket on the sending application to finalize the cross‑chain operation.

5. TimeoutPacket (Source Chain)

If no acknowledgement arrives before timeout, a relayer submits a non‑existence proof for the Packet Receipt. The source chain deletes the packet commitment and triggers OnTimeoutPacket, allowing the application to revert or refund the original transaction.