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

3 Packets

(Back to table of contents)

IBC uses an asynchronous message passing model that makes no assumptions about network synchrony. Chain A and chain B confirm new blocks independently, and IBC packets from one chain to the other may be delayed or censored arbitrarily. The speed of the IBC packet queue 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 (or not). Both chains must only agree that the packet has been received and either accepted or rejected, which is determined independently of any application logic.

To facilitate building useful application logic, we introduce a reliable messaging queue (hereafter just referred to as a queue) to allow 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 implements a vector clock for the restricted case of two processes (in our case, blockchains).

Formally, 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 fungible asset to be transferred between and held on multiple blockchains while preserving 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 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.1 Definitions

We introduce the abstraction of an IBC connection: a set of the required components to facilitate bidirectional communication between two blockchains A and B.

An IBC connection 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.2 Requirements

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 implement a reliable ordered packet queue with the following interface specification:

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

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 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.

These two queues have different purposes and store elements of different types. By parsing the key of a Merkle proof, a recipient can uniquely identify which queue, if any, this message belongs to. We now define k = (remote id, [send|receipt], index). This tuple is used to route and verify every message, before the contents of the packet are processed by the appropriate application logic.

We define every message in a send queue to consist of two fields: an enumerable type, and an opaque payload. The IBC protocol relies on the type for routing, and lets the appropriate module process the data as it sees fit. The receipt queue stores if it was an error, an optional error code, and an optional return value. We use the same index as the received message, so that the results of A:q_B.send[i] are stored at B:q_A.receipt[i]. (read: the message at index i in the send queue for chain B as stored on chain A)

V_send = (type, data)

V_receipt = (result, [success|error code])

3.3 Sending a packet

{ todo: cleanup wording }

A proper implementation of IBC requires all relevant state to be encapsulated, so that other modules can only interact with it via a fixed API (to be defined in the next sections) rather than directly mutating internal state. This allows the IBC module to provide security guarantees.

Sending an IBC packet involves an application module calling the send method of the IBC module with a packet and a destination chain id. 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 so, the IBC module simply pushes the packet to the tail of the send queue, which enables all the proofs described above.

The permissioning of which module can write which packet can be defined per type, so this module can maintain any application-level invariants related to this area. Thus, the "coin" module can maintain the constant supply of tokens, while another module can maintain its own invariants, without IBC messages providing a means to escape their encapsulations. The IBC module must associate every supported message type with a particular handler (f_type) and return an error for unsupported types.

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

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.4 Receiving a packet

{ 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.5 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).