cosmos-sdk/docs/spec/ibc/channels-and-packets.md

3 Channels & Packets

(Back to table of contents)

3.1 Background

IBC uses a cross-chain message passing model that makes no assumptions about network synchrony. IBC data packets (hereafter just packets) are relayed from one blockchain to the other by external infrastructure. Chain A and chain B confirm new blocks independently, and packets from one chain to the other may be delayed or censored arbitrarily. The speed of packet transmission and confirmation is limited only by the speed of the underlying chains.

The IBC protocol as defined here is payload-agnostic. The packet receiver on chain B decides how to act upon the incoming message, and may add its own application logic to determine which state transactions to apply according to what data the packet contains. Both chains must only agree that the packet has been received and either accepted or rejected.

To facilitate useful application logic, we introduce an IBC channel: a set of reliable messaging queues that allows us to guarantee a cross-chain causal ordering[5] of IBC packets. Causal ordering means that if packet x is processed before packet y on chain A, packet x must also be processed before packet y on chain B.

IBC channels implement a vector clock for the restricted case of two processes (in our case, blockchains). Given x → y means x is causally before y, and chains A and B, and a ⇒ b means a implies b:

A:send(msg_i ) → B:receive(msg_i )

B:receive(msg_i ) → A:receipt(msg_i )

A:send(msg_i ) → A:send(msg_i+1 )

x → A:send(msg_i ) ⇒ x → B:receive(msg_i )

y → B:receive(msg_i ) ⇒ y → A:receipt(msg_i )

Every transaction on the same chain already has a well-defined causality relation (order in history). IBC provides an ordering guarantee across two chains which can be used to reason about the combined state of both chains as a whole.

For example, an application may wish to allow a single tokenized asset to be transferred between and held on multiple blockchains while preserving fungibility and conservation of supply. The application can mint asset vouchers on chain B when a particular IBC packet is committed to chain B, and require outgoing sends of that packet on chain A to escrow an equal amount of the asset on chain A until the vouchers are later redeemed back to chain A with an IBC packet in the reverse direction. This ordering guarantee along with correct application logic can ensure that total supply is preserved across both chains and that any vouchers minted on chain B can later be redeemed back to chain A.

This section provides definitions for packets and channels, a high-level specification of the queue interface, and a list of the necessary proofs. To implement wire-compatible IBC, chain A and chain B must also use a common encoding format. An example binary encoding format can be found in Appendix C.

3.2 Definitions

3.2.1 Packet

We define an IBC packet P as the five-tuple (type, sequence, source, destination, data), where:

type is an opaque routing field (an integer or string)

sequence is an unsigned, arbitrary-precision integer

source is a string uniquely identifying the chain, connection, and channel from which this packet was sent

destination is a string uniquely identifying the chain, connection, and channel which should receive this packet

data is an opaque application payload

3.2.2 Receipt

We define an IBC receipt R as the four-tuple (sequence, source, destination, result), where

sequence is an unsigned, arbitrary-precision integer

source is a string uniquely identifying the chain, connection, and channel from which this packet was sent

destination is a string uniquely identifying the chain, connection, and channel which should receive this packet

result is a code of either success or failure

3.2.3 Queue

To implement strict message ordering, we introduce an ordered queue. A queue can be conceptualized as a slice of an infinite array. Two numerical indices - q_head and q_tail - bound the slice, such that for every index where head <= index < tail, there is a queue element q[q_index]. Elements can be appended to the tail (end) and removed from the head (beginning). We introduce one further method, advance, to facilitate efficient queue cleanup.

Each IBC-supporting blockchain must provide a queue abstraction with the following functionality:

init

set q_head = 0
set q_tail = 0

peek ⇒ e

match q_head == q_tail with
true ⇒ return nil
false ⇒ return q[q_head]

pop ⇒ e

match q_head == q_tail with
true ⇒ return nil
false ⇒ set q_head = q_head + 1; return q[q_head-1]

retrieve(i) ⇒ e

match q_head <= i < q_tail with
true ⇒ return q_i
false ⇒ return nil

push(e)

set q[q_tail] = e; set q_tail = q_tail + 1

advance(i)

set q_head = i; set q_tail = max(q_tail, i)

head ⇒ i

return q_head

tail ⇒ i

return q_tail

3.2.4 Channel

We introduce the abstraction of an IBC channel: a set of the required packet queues to facilitate ordered bidirectional communication between two blockchains A and B. An IBC connection, as defined earlier, can have any number of associated channels. IBC connections handle header initialization & updates. All IBC channels use the same connection, but implement independent queues and thus independent ordering guarantees.

An IBC channel consists of four distinct queues, two on each chain:

Outgoing_A: Outgoing IBC packets from chain A to chain B, stored on chain A

Incoming_A: Execution logs for incoming IBC packets from chain B, stored on chain A

Outgoing_B: Outgoing IBC packets from chain B to chain A, stored on chain B

Incoming_B: Execution logs for incoming IBC packets from chain A, stored on chain B

3.3 Requirements

In order to provide the ordering guarantees specified above, each blockchain utilizing the IBC protocol must provide proofs that particular IBC packets have been stored at particular indices in the outgoing packet queue, and particular IBC packet execution results have been stored at particular indices in the incoming packet queue.

We use the previously-defined Merkle proof M_k,v,h to provide the requisite proofs. In order to do so, we must define a unique, deterministic key in the Merkle store for each message in the queue:

key: (queue name, [head|tail|index])

The index is stored as a fixed-length unsigned integer in big endian format, so that the lexicographical order of the byte representation of the key is consistent with their sequence number. This allows us to quickly iterate over the queue, as well as prove the content of a packet (or lack of packet) at a given sequence. head and tail are two special constants that store an integer index, and are chosen such that their serializated representation cannot collide with that of any possible index.

Once written to the queue, a packet must be immutable (except for deletion when popped from the queue). That is, if a value v is written to a queue, then every valid proof M_k,v,h must refer to the same v. In practice, this means that an IBC implementation must ensure that only the IBC module can write to the IBC subspace of the blockchain's Merkle store. This property is essential to safely process asynchronous messages.

Each incoming & outgoing queue for each connection must be provably associated with another uniquely identified chain, so that an observer can prove that a message was intended for that chain and only that chain. This can easily be done by prefixing the queue keys in the Merkle store with a string unique to the other chain, such as the chain identifier or the hash of the genesis block.

3.4 Sending a packet

To send an IBC packet, an application module on the source chain must call the send method of the IBC module, providing a packet as defined above. The IBC module must ensure that the destination chain was already properly registered and that the calling module has permission to write this packet. If all is in order, the IBC module simply pushes the packet to the tail of Outgoing_A, which enables all the proofs described above.

If desired, the packet payload can contain additional module routing information in the form of a kind, so that different modules can write different kinds of packets and maintain any application-level invariants related to this area. For example, a "coin" module can ensure a fixed supply, or a "NFT" module can ensure token uniqueness. The IBC module must associate every supported message with a particular handler (f_kind) and return an error for unsupported types.

(IBCsend(D, type, data) ⇒ Success) ⇒ push(q_D.send ,V_send{type, data})

3.5 Receiving a packet

We also consider how a given blockchain A is expected to receive the packet from a source chain S with a merkle proof, given the current set of trusted headers for that chain, T_S:

A:IBCreceive(S, M_k,v,h) ⇒ match

• q_S.receipt = ∅ ⇒ Error("unregistered sender"),
• k = (_, reciept, _) ⇒ Error("must be a send"),
• k = (d, _, _) and d ≠ A ⇒ Error("sent to a different chain"),
• k = (_, send, i) and head(q_S.receipt) ≠ i ⇒ Error("out of order"),
• H_h ∉ T_S ⇒ Error("must submit header for height h"),
• valid(H_h ,M_k,v,h ) = false ⇒ Error("invalid merkle proof"),
• v = (type, data) ⇒ (result, err) := f_type(data); push(q_S.receipt , (result, err)); Success

Note that this requires not only an valid proof, but also that the proper header as well as all prior messages were previously submitted. This returns success upon accepting a proper message, even if the message execution returned an error (which must then be relayed to the sender).

3.6 Handling a receipt

{ todo: cleanup logic }

When we wish to create a transaction that atomically commits or rolls back across two chains, we must look at the receipts from sending the original message. For example, if I want to send tokens from Alice on chain A to Bob on chain B, chain A must decrement Alice's account if and only if Bob's account was incremented on chain B. We can achieve that by storing a protected intermediate state on chain A, which is then committed or rolled back based on the result of executing the transaction on chain B.

To do this requires that we not only provable send a message from chain A to chain B, but provably return the result of that message (the receipt) from chain B to chain A. As one noticed above in the implementation of IBCreceive, if the valid IBC message was sent from A to B, then the result of executing it, even if it was an error, is stored in B:q_A.receipt. Since the receipts are stored in a queue with the same key construction as the sending queue, we can generate the same set of proofs for them, and perform a similar sequence of steps to handle a receipt coming back to S for a message previously sent to A:

S:IBCreceipt(A, M_k,v,h) ⇒ match

• q_A.send = ∅ ⇒ Error("unregistered sender"),
• k = (_, send, _) ⇒ Error("must be a recipient"),
• k = (d, _, _) and d ≠ S ⇒ Error("sent to a different chain"),
• H_h ∉ T_A ⇒ Error("must submit header for height h"),
• not valid(H_h , M_k,v,h ) ⇒ Error("invalid merkle proof"),
• k = (_, receipt, head|tail) ⇒ Error("only accepts message proofs"),
• k = (_, receipt, i) and head(q_S.send) ≠ i ⇒ Error("out of order"),
• v = (_, error) ⇒ (type, data) := pop(q_S.send ); rollback_type(data); Success
• v = (res, success) ⇒ (type, data) := pop(q_S.send ); commit_type(data, res); Success

This enforces that the receipts are processed in order, to allow some the application to make use of some basic assumptions about ordering. It also removes the message from the send queue, as there is now proof it was processed on the receiving chain and there is no more need to store this information.

3.7 Packet relayer

{ todo: cleanup wording }

The blockchain itself only records the intention to send the given message to the recipient chain, it doesn't make any network connections as that would add unbounded delays and non-determinism into the state machine. We define the concept of a relay process that connects two chain by querying one for all proofs needed to prove outgoing messages and submit these proofs to the recipient chain.

The relay process must have access to accounts on both chains with sufficient balance to pay for transaction fees but needs no other permissions. Many relay processes may run in parallel without violating any safety consideration. However, they will consume unnecessary fees if they submit the same proof multiple times, so some minimal coordination is ideal.

As an example, here is a naive algorithm for relaying send messages from A to B, without error handling. We must also concurrently run the relay of receipts from B back to A, in order to complete the cycle. Note that all reads of variables belonging to a chain imply queries and all function calls imply submitting a transaction to the blockchain.

while true
   pending := tail(A:q<sub>B.send</sub>)
   received := tail(B:q<sub>A.receive</sub>)
   if pending > received
       U<sub>h</sub> := A:latestHeader
       B:updateHeader(U<sub>h</sub>)
       for i :=received...pending
           k := (B, send, i)
           packet := A:M<sub>k,v,h</sub>
           B:IBCreceive(A, packet)
   sleep(desiredLatency)

Note that updating a header is a costly transaction compared to posting a merkle proof for a known header. Thus, a process could wait until many messages are pending, then submit one header along with multiple merkle proofs, rather than a separate header for each message. This decreases total computation cost (and fees) at the price of additional latency and is a trade-off each relay can dynamically adjust.

In the presence of multiple concurrent relays, any given relay can perform local optimizations to minimize the number of headers it submits, but remember the frequency of header submissions defines the latency of the packet transfer.

Indeed, it is ideal if each user that initiates the creation of an IBC packet also relays it to the recipient chain. The only constraint is that the relay must be able to pay the appropriate fees on the destination chain. However, in order to avoid bottlenecks, a group may sponsor an account to pay fees for a public relayer that moves all unrelayed packets (perhaps with a high latency).