Channel & Packet Semantics

概述

“通道”抽象为区块链间通信协议提供三类消息传递语义：顺序性、恰好一次传递以及模块权限控制。通道充当一条管道，用于在一条链上的某个模块与另一条链上的某个模块之间传递数据包，确保数据包只会被执行一次、按其发送顺序被传递（如有需要），并且只会在目标链上被传递给拥有通道另一端的对应模块。每个通道都关联到一个特定连接，而一个连接可以关联任意数量的通道，从而允许复用公共标识符，并将头部验证的成本分摊到所有使用该连接和轻客户端的通道上。通道与负载无关。发送和接收 IBC 数据包的模块决定如何构造数据包数据，以及如何处理传入的数据包数据，并且必须利用自身的应用逻辑，根据数据包中包含的数据来确定应当应用哪些状态交易。

动机

区块链间通信协议采用跨链消息传递模型。IBC packets 由外部中继进程从一个区块链中继到另一个区块链。链 A 与链 B 独立确认新区块，从一条链发送到另一条链的数据包可能被任意延迟、审查或重排。数据包对中继器可见，任何中继进程都可以从某条区块链读取数据包并将其提交到另一条区块链。 IBC 协议必须提供顺序保证（针对有序通道）和恰好一次传递保证，以便应用能够对两条链上已连接模块的组合状态进行推理。

示例：某个应用可能希望允许单一的代币化资产在多个区块链之间转移和持有，同时保持可替代性和供应守恒。当某个特定 IBC 数据包被提交到链 B 时，应用可以在链 B 上铸造资产凭证；同时要求在链 A 上发送该数据包时，在链 A 上托管等量资产，直到这些凭证之后通过反向的 IBC 数据包赎回到链 A。这种顺序保证配合正确的应用逻辑，可以确保两条链上的总供应量得到保持，并且在链 B 上铸造的任何凭证之后都可以赎回到链 A。

为了向应用层提供所需的顺序性、恰好一次传递和模块权限控制语义，区块链间通信协议必须实现一种用于强制这些语义的抽象，而通道正是这种抽象。

定义

ConsensusState 的定义见 ICS 2。 Connection 的定义见 ICS 3。 Port 和 authenticateCapability 的定义见 ICS 5。 hash 是一种通用的抗碰撞哈希函数，其具体细节必须由使用该通道的模块共同约定。不同链可以对 hash 采用不同定义。 Identifier、get、set、delete、getCurrentHeight 以及与模块系统相关的原语定义见 ICS 24。关于 pendingInflightPackets 和 restoreChannel 的定义，请参阅升级规范。通道是一个在不同区块链上的特定模块之间实现恰好一次数据包传递的管道，并且至少有一端能够发送数据包，另一端能够接收数据包。双向通道是指数据包可以双向流动的通道：既可以从 A 到 B，也可以从 B 到 A。单向通道是指数据包只能单向流动的通道：只能从 A 到 B（或从 B 到 A，命名顺序是任意的）。有序通道是指数据包会严格按照发送顺序被传递的通道。这种通道类型提供非常严格的顺序保证。要么数据包按照发送顺序被接收；要么如果序列中的某个数据包超时，则其后的所有未来数据包也都不可再接收，并且通道会关闭。 ordered_allow_timeout 通道是 ordered 通道的一种约束较弱的版本。在这种情况下，通道逻辑会以“尽力而为”的方式按顺序传递数据包。在一个数据包流中，通道会按顺序中继所有数据包；如果流中的某个数据包超时，则会执行该数据包的超时逻辑，而其后的其余数据包仍将继续按顺序处理。因此，在这种通道类型下发生超时时，我们不会关闭通道。无序通道是指数据包可以以任意顺序传递的通道，该顺序可能不同于它们的发送顺序。

enum ChannelOrder {
  ORDERED,
  UNORDERED,
  ORDERED_ALLOW_TIMEOUT,
}

方向性与顺序性彼此独立，因此我们可以讨论双向无序通道、单向有序通道等。所有通道都提供恰好一次的数据包传递，这意味着在通道一端发送的数据包，最终会被传递到另一端，不多不少，正好一次。本规范只关注双向通道。单向通道几乎可以使用完全相同的协议，并将在未来的 ICS 中进行说明。通道的一端是在某条链上存储通道元数据的数据结构：

interface ChannelEnd {
  state: ChannelState
  ordering: ChannelOrder
  counterpartyPortIdentifier: Identifier
  counterpartyChannelIdentifier: Identifier
  connectionHops: [Identifier]
  version: string
  upgradeSequence: uint64
}

state 是通道端当前的状态。
ordering 字段表明该通道是 unordered、ordered 还是 ordered_allow_timeout。
counterpartyPortIdentifier 标识对手方链上拥有该通道另一端的端口。
counterpartyChannelIdentifier 标识对手方链上的通道端。
单独存储的 nextSequenceSend 跟踪下一个待发送数据包的序列号。
单独存储的 nextSequenceRecv 跟踪下一个待接收数据包的序列号。
单独存储的 nextSequenceAck 跟踪下一个待确认数据包的序列号。
connectionHops 存储连接标识符列表，顺序从接收端指向发送端。connectionHops[0] 是接收链上的连接端。超过一个连接跳点表示这是一个多跳通道。
version 字符串存储一个不透明的通道版本，该版本在握手期间达成一致。它可用于决定模块级配置，例如该通道使用哪种数据包编码。该版本不会被 IBC 核心协议使用。如果版本字符串中包含供应用解析和解释的结构化元数据，则最佳实践是将所有元数据编码为 JSON 结构体，并将序列化后的字符串放入 version 字段。

关于 upgradeSequence 的细节，请参阅升级规范。通道端具有一种 state：

enum ChannelState {
  INIT,
  TRYOPEN,
  OPEN,
  CLOSED,
  FLUSHING,
  FLUSHINGCOMPLETE,
}

处于 INIT 状态的通道端刚刚开始开启握手。
处于 TRYOPEN 状态的通道端已经确认了对手方链上的握手步骤。
处于 OPEN 状态的通道端已经完成握手，并准备好发送和接收数据包。
处于 CLOSED 状态的通道端已经关闭，不能再用于发送或接收数据包。

关于 FLUSHING 和 FLUSHCOMPLETE 的细节，请参阅升级规范。在区块链间通信协议中，Packet 是如下定义的一个特定接口：

interface Packet {
  sequence: uint64
  timeoutHeight: Height
  timeoutTimestamp: uint64
  sourcePort: Identifier
  sourceChannel: Identifier
  destPort: Identifier
  destChannel: Identifier
  data: bytes
}

sequence 序列号对应发送和接收顺序，其中序列号更早的数据包必须先于序列号更晚的数据包发送和接收。
timeoutHeight 表示目标链上的一个共识高度，在该高度之后该数据包将不再被处理，而会被视为已超时。
timeoutTimestamp 表示目标链上的一个时间戳，在该时间戳之后该数据包将不再被处理，而会被视为已超时。
sourcePort 标识发送链上的端口。
sourceChannel 标识发送链上的通道端。
destPort 标识接收链上的端口。
destChannel 标识接收链上的通道端。
data 是一个不透明值，可由关联模块的应用逻辑定义。

请注意，Packet 从不会被直接序列化。相反，它是一种中间结构，用于某些函数调用中，这些调用可能需要由调用 IBC 处理器的模块来创建或处理。 OpaquePacket 是一种数据包，但会被宿主状态机包裹在一种模糊化的数据类型中，从而使模块除了将其传递给 IBC 处理器之外，不能对其执行其他操作。IBC 处理器可以将 Packet 转换为 OpaquePacket，反之亦然。

type OpaquePacket = object

为了支持新的通道类型（例如 ORDERED_ALLOW_TIMEOUT），该协议引入了标准化的数据包回执，它将作为哨兵值，使接收链能够将 recvPacket 的结果显式写入其存储。

enum PacketReceipt {
  SUCCESSFUL_RECEIPT,
  TIMEOUT_RECEIPT,
}

期望属性

效率

数据包传输与确认的速度应当只受底层链速度的限制。在可能的情况下，证明应当支持批处理。

恰好一次传递

在通道一端发送的 IBC 数据包应当被恰好一次地传递到另一端。
恰好一次安全性不应要求任何网络同步性假设。如果一条或两条链停止运行，数据包最多只能被传递一次；而一旦链恢复运行，数据包应能够再次流动。

顺序性

在 ordered 通道上，数据包应按相同顺序发送和接收：如果链 A 上某个通道端先发送数据包 x，后发送数据包 y，则链 B 上对应的通道端必须先接收数据包 x，再接收数据包 y。如果某个通道先发送数据包 x，后发送数据包 y，且数据包 x 超时，则数据包 y 以及所有在 x 之后发送的数据包都不能被接收。
在 ordered_allow_timeout 通道上，数据包也应按相同顺序发送和接收：如果链 A 上某个通道端先发送数据包 x，后发送数据包 y，则链 B 上对应的通道端必须在处理数据包 y 之前，先接收或确认数据包 x 已超时。
在 unordered 通道上，数据包可以以任意顺序发送和接收。无序数据包与有序数据包一样，都以目标链的高度为基准指定各自独立的超时。

权限控制

通道应当分别授权给两端各自的一个模块，该归属关系在握手期间确定，之后不可变更（更高层逻辑可以通过将端口所有权代币化来将通道所有权代币化）。只有与某个通道端关联的模块才能在其上发送或接收。

技术规范

数据流可视化

客户端、连接、通道与数据包的架构：数据流可视化

预备知识

存储路径

通道结构存储在一个存储路径前缀下，该前缀由端口标识符与通道标识符的组合唯一确定：

function channelPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "channelEnds/ports/{portIdentifier}/channels/{channelIdentifier}"
}

与通道关联的 capability 键存储在 channelCapabilityPath 下：

function channelCapabilityPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
  return "{channelPath(portIdentifier, channelIdentifier)}/key"
}

nextSequenceSend、nextSequenceRecv 和 nextSequenceAck 这几个无符号整数计数器会分别单独存储，以便可以分别对其进行证明：

function nextSequenceSendPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "nextSequenceSend/ports/{portIdentifier}/channels/{channelIdentifier}"
}

function nextSequenceRecvPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "nextSequenceRecv/ports/{portIdentifier}/channels/{channelIdentifier}"
}

function nextSequenceAckPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "nextSequenceAck/ports/{portIdentifier}/channels/{channelIdentifier}"
}

对数据包数据字段的定长承诺按数据包序列号存储：

function packetCommitmentPath(portIdentifier: Identifier, channelIdentifier: Identifier, sequence: uint64): Path {
    return "commitments/ports/{portIdentifier}/channels/{channelIdentifier}/sequences/{sequence}"
}

如果该路径在存储中不存在，则等价于一个零比特。数据包接收回执数据存储在 packetReceiptPath 下。在成功接收的情况下，目标链会写入一个表示成功的哨兵值 SUCCESSFUL_RECEIPT。某些通道类型在数据包于指定超时之后才被接收时，MAY 写入一个表示超时的哨兵值 TIMEOUT_RECEIPT。

function packetReceiptPath(portIdentifier: Identifier, channelIdentifier: Identifier, sequence: uint64): Path {
    return "receipts/ports/{portIdentifier}/channels/{channelIdentifier}/sequences/{sequence}"
}

数据包确认数据存储在 packetAcknowledgementPath 下：

function packetAcknowledgementPath(portIdentifier: Identifier, channelIdentifier: Identifier, sequence: uint64): Path {
    return "acks/ports/{portIdentifier}/channels/{channelIdentifier}/sequences/{sequence}"
}

版本

在握手过程中，通道两端会就与该通道关联的一个版本字节串达成一致。该版本字节串的内容对于 IBC 核心协议而言是且将继续保持不透明。宿主状态机 MAY 使用版本数据来标明所支持的 IBC/APP 协议、约定数据包编码格式，或协商与 IBC 之上自定义逻辑相关的其他通道元数据。宿主状态机 MAY 也可以安全地忽略版本数据，或指定为空字符串。

子协议

注意：如果宿主状态机使用对象能力认证（见 ICS 005），那么所有使用端口的函数都需要额外接收一个 capability 参数。

标识符校验

通道存储在唯一的 (portIdentifier, channelIdentifier) 前缀下。 MAY 提供校验函数 validatePortIdentifier。

type validateChannelIdentifier = (portIdentifier: Identifier, channelIdentifier: Identifier) => boolean

如果未提供，则默认的 validateChannelIdentifier 函数始终返回 true。

通道生命周期管理

发起方	数据报	被操作的链	前置状态 (A, B)	后置状态 (A, B)
参与者	ChanOpenInit	A	(none, none)	(INIT, none)
中继器	ChanOpenTry	B	(INIT, none)	(INIT, TRYOPEN)
中继器	ChanOpenAck	A	(INIT, TRYOPEN)	(OPEN, TRYOPEN)
中继器	ChanOpenConfirm	B	(OPEN, TRYOPEN)	(OPEN, OPEN)

发起方	数据报	被操作的链	前置状态 (A, B)	后置状态 (A, B)
参与者	ChanCloseInit	A	(OPEN, OPEN)	(CLOSED, OPEN)
中继器	ChanCloseConfirm	B	(CLOSED, OPEN)	(CLOSED, CLOSED)
参与者	ChanCloseFrozen	A 或 B	(OPEN, OPEN)	(CLOSED, CLOSED)

打开握手

chanOpenInit 函数由某个模块调用，用于发起与另一条链上模块的通道打开握手。函数 chanOpenInit 和 chanOpenTry 不会将新的通道端写入状态，因为通道版本可能会被应用回调修改。应当在执行应用回调之后，使用 writeChannel 函数将通道端写入状态：

function writeChannel(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  state: ChannelState,
  order: ChannelOrder,
  counterpartyPortIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  connectionHops: [Identifier],
  version: string) {
    channel = ChannelEnd{
      state, order,
      counterpartyPortIdentifier, counterpartyChannelIdentifier,
      connectionHops, version
    }
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

更多细节请参见通道生命周期管理中的处理函数 handleChanOpenInit 和 handleChanOpenTry。正在打开的通道必须提供本地通道标识符、本地端口、远程端口以及远程通道标识符。当打开握手完成后，发起握手的模块将拥有宿主账本上所创建通道的一端，而它所指定的对手方模块将拥有对手方链上所创建通道的另一端。一旦通道被创建，其所有权就不能再更改（尽管可以实现更高层抽象来提供这种能力）。链必须实现一个 generateIdentifier 函数来选择标识符，例如通过递增计数器：

type generateIdentifier = () -> Identifier

function chanOpenInit(
  order: ChannelOrder,
  connectionHops: [Identifier],
  portIdentifier: Identifier,
  counterpartyPortIdentifier: Identifier): (channelIdentifier: Identifier, channelCapability: CapabilityKey) {
    channelIdentifier = generateIdentifier()
    abortTransactionUnless(validateChannelIdentifier(portIdentifier, channelIdentifier))

    abortTransactionUnless(provableStore.get(channelPath(portIdentifier, channelIdentifier)) === null)
    connection = provableStore.get(connectionPath(connectionHops[0]))

    // optimistic channel handshakes are allowed
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(authenticateCapability(portPath(portIdentifier), portCapability))

    channelCapability = newCapability(channelCapabilityPath(portIdentifier, channelIdentifier))
    provableStore.set(nextSequenceSendPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), 1)

    return channelIdentifier, channelCapability
}

chanOpenTry 函数由某个模块调用，用于接受另一条链上模块发起的通道打开握手的第一步。

function chanOpenTry(
  order: ChannelOrder,
  connectionHops: [Identifier],
  portIdentifier: Identifier,
  counterpartyPortIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  counterpartyVersion: string,
  proofInit: CommitmentProof | MultihopProof,
  proofHeight: Height): (channelIdentifier: Identifier, channelCapability: CapabilityKey) {
    channelIdentifier = generateIdentifier()

    abortTransactionUnless(validateChannelIdentifier(portIdentifier, channelIdentifier))
    abortTransactionUnless(authenticateCapability(portPath(portIdentifier), portCapability))

    connection = provableStore.get(connectionPath(connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofInit, connection)

    expected = ChannelEnd{
      INIT, order, portIdentifier,
      "", counterpartyHops,
      counterpartyVersion
    }

    if (connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofInit,
        connectionHops,
        key
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofInit,
        counterpartyPortIdentifier,
        counterpartyChannelIdentifier,
        expected
      ))
    }

    channelCapability = newCapability(channelCapabilityPath(portIdentifier, channelIdentifier))

    // initialize channel sequences
    provableStore.set(nextSequenceSendPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), 1)

    return channelIdentifier, channelCapability
}

chanOpenAck 由发起握手的模块调用，用于确认另一条链上的对手方模块已经接受初始请求。

function chanOpenAck(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  counterpartyVersion: string,
  proofTry: CommitmentProof | MultihopProof,
  proofHeight: Height) {
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel.state === INIT)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofTry, connection)

    expected = ChannelEnd{TRYOPEN, channel.order, portIdentifier,
        channelIdentifier, counterpartyHops, counterpartyVersion}

    if (channel.connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofTry,
        channel.connectionHops,
        key,
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofTry,
        channel.counterpartyPortIdentifier,
        counterpartyChannelIdentifier,
        expected
      ))
    }
    // write will happen in the handler defined in the ICS26 spec
}

chanOpenConfirm 函数由接受握手的模块调用，用于确认另一条链上发起握手模块的确认，并完成通道打开握手。

function chanOpenConfirm(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proofAck: CommitmentProof | MultihopProof,
  proofHeight: Height) {
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === TRYOPEN)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofAck, connection)

    expected = ChannelEnd{OPEN, channel.order, portIdentifier,
      channelIdentifier, counterpartyHops, channel.version}

    if (connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofAck,
        channel.connectionHops,
        key
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofAck,
        channel.counterpartyPortIdentifier,
        channel.counterpartyChannelIdentifier,
        expected
      ))
    }

    // write will happen in the handler defined in the ICS26 spec
}

关闭握手

chanCloseInit 函数可由任一模块调用，以关闭通道在其这一端的状态。通道一旦关闭，就不能重新打开。调用模块在调用 chanCloseInit 的同时，MAY 以原子方式执行适当的应用逻辑。通道关闭后，所有在途数据包都可以立即超时。

function chanCloseInit(
  portIdentifier: Identifier,
  channelIdentifier: Identifier) {
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state !== CLOSED)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)
    channel.state = CLOSED
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

chanCloseConfirm 函数由对手方模块调用，以关闭其这一端的通道，因为另一端已经关闭。调用模块在调用 chanCloseConfirm 的同时，MAY 以原子方式执行适当的应用逻辑。通道一旦关闭，就不能重新打开，标识符也不能复用。之所以防止标识符复用，是因为我们希望防止此前已发送的数据包被潜在重放。重放问题类似于在签名消息中使用序列号，只不过这里是轻客户端算法对消息（IBC 数据包）进行“签名”，而用于防止重放的序列则是端口标识符、通道标识符和数据包序列号的组合。因此，我们不能允许再次复用相同的端口标识符和通道标识符，并将序列重置为零，因为这可能会使数据包能够被重放。如果强制规定并跟踪特定最大高度/时间的超时，则可以安全地复用标识符，未来版本的规范可能会纳入此特性。

function chanCloseConfirm(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proofInit: CommitmentProof | MultihopProof,
  proofHeight: Height) {
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state !== CLOSED)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofInit, connection)

    expected = ChannelEnd{CLOSED, channel.order, portIdentifier,
                          channelIdentifier, counterpartyHops, channel.version}

    if (connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofInit,
        channel.connectionHops,
        key
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofInit,
        channel.counterpartyPortIdentifier,
        channel.counterpartyChannelIdentifier,
        expected
      ))
    }

    // write may happen asynchronously in the handler defined in the ICS26 spec
    // if the channel is closing during an upgrade, 
    // then we can delete all auxiliary upgrade information
    provableStore.delete(channelUpgradePath(portIdentifier, channelIdentifier))
    privateStore.delete(counterpartyUpgradePath(portIdentifier, channelIdentifier))

    channel.state = CLOSED
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

如果通道路径中的任一客户端状态被冻结，chanCloseFrozen 函数可由中继者调用，以强制关闭多跳通道。中继者应向通道的每一端发送被冻结客户端状态的证明，并附带一份从各通道端点开始、沿通道路径直到第一个被冻结客户端为止的被冻结客户端状态证明。通道每一端的多跳证明都会不同，并且都是从各自通道端点一直构造到被冻结客户端的证明。多跳证明从一条具有针对异常行为链的冻结客户端的链开始。然而，冻结客户端存在于通道路径中的下一个区块链上，因此键/值证明会被索引，以便在持有该客户端状态的共识状态上进行求值。客户端状态路径需要知道客户端 ID，而该 ID 可以在异常行为提交之前，通过异常行为链上的 connectionEnd 确定。一旦被冻结，在通道路径中的异常行为得到解决后，通道可以通过治理流程解冻（重新激活）。不过，这一过程不属于协议内流程。示例：给定一条从链 A 到链 E 的多跳通道路径，经过若干连接，且异常行为链为 C A <--> B <--x C x--> D <--> E 假设任意中继者都向链 B 和链 D 提交了异常行为证据，以冻结它们各自针对链 C 的客户端。随后，中继者可以向链 A 提供链 B 上被冻结客户端的多跳证明，以关闭链 A 上的通道；另一名中继者（或同一名中继者）也可以向链 E 中继链 D 上被冻结客户端的多跳证明，以关闭链 E 上的通道端。不过，还必须证明该冻结客户端状态对应于通道路径中的某个特定跳点。因此，必须同时提供链 B 上的连接端证明，且其对手方连接端位于链 C，并结合客户端状态证明，以证明客户端状态中的 clientID 与连接端中的 clientID 一致。此外，连接端中的 connectionID MUST 与通道 connectionHops 字段中的预期 ID 匹配。

function chanCloseFrozen(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proofConnection: MultihopProof,
  proofClientState: MultihopProof,
  proofHeight: Height) {
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    hopsLength = channel.connectionHops.length
    abortTransactionUnless(hopsLength === 1)
    abortTransactionUnless(channel.state !== CLOSED)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // lookup connectionID for connectionEnd corresponding to misbehaving chain
    let connectionIdx = proofConnection.ConnectionProofs.length + 1
    abortTransactionUnless(connectionIdx < hopsLength)
    let connectionID = channel.ConnectionHops[connectionIdx]
    let connectionProofKey = connectionPath(connectionID)
    let connectionProofValue = proofConnection.KeyProof.Value
    let frozenConnectionEnd = abortTransactionUnless(Unmarshal(connectionProofValue))

    // the clientID in the connection end must match the clientID for the frozen client state
    let clientID = frozenConnectionEnd.ClientId

    // truncated connectionHops. e.g. client D on chain C is frozen: A, B, C, D, E -> A, B, C
    let connectionHops = channel.ConnectionHops[:len(mProof.ConnectionProofs)+1]

    // verify the connection proof
    abortTransactionUnless(connection.verifyMultihopMembership(
      connection,
      proofHeight,
      proofConnection,
      connectionHops,
      connectionProofKey,
      connectionProofValue))


    // key and value for the frozen client state
    let clientStateKey = clientStatePath(clientID)
    let clientStateValue = proofClientState.KeyProof.Value
    let frozenClientState = abortTransactionUnless(Unmarshal(clientStateValue))

    // ensure client state is frozen by checking FrozenHeight
    abortTransactionUnless(frozenClientState.FrozenHeight.RevisionHeight !== 0)

   // verify the frozen client state proof
    abortTransactionUnless(connection.verifyMultihopMembership(
      connection,
      proofHeight,
      proofConnection,
      connectionHops,
      clientStateKey,
      clientStateValue))

    channel.state = FROZEN
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

多跳工具函数

// Return the counterparty connectionHops
function getCounterPartyHops(proof: CommitmentProof | MultihopProof, lastConnection: ConnectionEnd) string[] {

  let counterpartyHops: string[] = [lastConnection.counterpartyConnectionIdentifier]
  if typeof(proof) === 'MultihopProof' {
    for connData in proofs.ConnectionProofs {
      connectionEnd = abortTransactionUnless(Unmarshal(connData.Value))
      counterpartyHops.push(connectionEnd.GetCounterparty().GetConnectionID())
    }

    // reverse the hops so they are ordered from sender --> receiver
    counterpartyHops = counterpartyHops.reverse()
  }

  return counterpartyHops
}

数据包流转与处理

数据包的一生

要将一个数据包从机器 A 上的模块 1 发送到机器 B 上的模块 2，从零开始必须依次发生以下步骤。模块可以通过 ICS 25 或 ICS 26 与 IBC 处理器交互。

初始客户端和端口设置，顺序任意
1. 在 A 上为 B 创建客户端（见 ICS 2）
2. 在 B 上为 A 创建客户端（见 ICS 2）
3. 模块 1 绑定到一个端口（见 ICS 5）
4. 模块 2 绑定到一个端口（见 ICS 5），并通过带外方式将其传达给模块 1
按顺序建立连接与通道，并进行乐观发送
1. 模块 1 从 A 向 B 发起连接打开握手（见 ICS 3）
2. 1 到 2 使用新创建的连接发起通道打开握手（本 ICS）
3. 通过新创建的通道将数据包从 1 发送到 2（本 ICS）
成功完成握手（如果任一握手失败，则可以关闭连接/通道，并使数据包超时）
1. 连接打开握手成功完成（见 ICS 3）（这需要中继进程参与）
2. 通道打开握手成功完成（本 ICS）（这需要中继进程参与）
机器 B 上模块 2 对数据包进行确认（如果超时高度已过，则数据包超时）（这需要中继进程参与）
确认消息（可能）从机器 B 上的模块 2 中继回机器 A 上的模块 1

从空间上表示，数据包在两台机器之间的传输可渲染如下：数据包传输

发送数据包

模块通过调用 sendPacket 函数，在由该调用模块拥有的通道端上发送数据（以 IBC 数据包的形式）。调用模块在调用 sendPacket 时，必须以原子方式一并执行应用逻辑。 IBC 处理程序按顺序执行以下步骤：

检查通道是否已打开并可发送数据包
检查调用模块是否拥有发送端口（见 ICS 5）
检查指定的超时高度在目标链上是否尚未经过
递增与该通道关联的发送序列计数器
存储一个定长承诺，用于表示数据包数据和数据包超时信息
返回已发送数据包的序列号

请注意，完整的数据包不会存储在链的状态中，只会存储一个针对数据和超时值的简短哈希承诺。数据包数据可以根据交易执行结果计算出来，并且可能作为日志输出返回，供中继器建立索引。

function sendPacket(
  capability: CapabilityKey,
  sourcePort: Identifier,
  sourceChannel: Identifier,
  timeoutHeight: Height,
  timeoutTimestamp: uint64,
  data: bytes): uint64 {
    channel = provableStore.get(channelPath(sourcePort, sourceChannel))

    // check that the channel must be OPEN to send packets;
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === OPEN)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)

    // check if the calling module owns the sending port
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(sourcePort, sourceChannel), capability))

    // disallow packets with a zero timeoutHeight and timeoutTimestamp
    abortTransactionUnless(timeoutHeight !== 0 || timeoutTimestamp !== 0)

    // check that the timeout height hasn't already passed in the local client tracking the receiving chain
    latestClientHeight = provableStore.get(clientPath(connection.clientIdentifier)).latestClientHeight()
    abortTransactionUnless(timeoutHeight === 0 || latestClientHeight < timeoutHeight)

    // increment the send sequence counter
    sequence = provableStore.get(nextSequenceSendPath(sourcePort, sourceChannel))
    provableStore.set(nextSequenceSendPath(sourcePort, sourceChannel), sequence+1)

    // store commitment to the packet data & packet timeout
    provableStore.set(
      packetCommitmentPath(sourcePort, sourceChannel, sequence),
      hash(hash(data), timeoutHeight, timeoutTimestamp)
    )

    // log that a packet can be safely sent
    emitLogEntry("sendPacket", {
      sequence: sequence,
      data: data,
      timeoutHeight: timeoutHeight,
      timeoutTimestamp: timeoutTimestamp
    })

    return sequence
}

接收数据包

模块通过调用 recvPacket 函数，接收在对手链对应通道端上发送的 IBC 数据包。调用模块在调用 recvPacket 时，必须以原子方式一并执行应用逻辑，或将该数据包排队以供后续执行。 IBC 处理程序按顺序执行以下步骤：

检查通道和连接是否已打开并可接收数据包
检查调用模块是否拥有接收端口
检查数据包元数据是否与通道和连接信息匹配
检查数据包序列是否为该通道端预期接收的下一个序列（适用于 ordered 和 ordered_allow_timeout 通道）
检查超时高度和时间戳是否尚未经过
检查外发链状态中数据包数据承诺的包含证明
可选地（如果实现了通道升级以及确认和数据包回执的删除）：拒绝任何在成功通道升级之前已使用过序列号的数据包
设置一个存储路径以表明该数据包已被接收（仅适用于无序通道）
递增与该通道端关联的数据包接收序列（仅适用于 ordered 和 ordered_allow_timeout 通道）

我们传入签名并提交该数据包的 relayer 地址，以便模块可以选择性地提供一些奖励。这为手续费支付奠定了基础，但也可以用于其他技术手段（例如计算排行榜）。

function recvPacket(
  packet: OpaquePacket,
  proof: CommitmentProof | MultihopProof,
  proofHeight: Height,
  relayer: string): Packet {

    channel = provableStore.get(channelPath(packet.destPort, packet.destChannel))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === OPEN || (channel.state === FLUSHING) || (channel.state === FLUSHCOMPLETE))
    counterpartyUpgrade = privateStore.get(counterpartyUpgradePath(packet.destPort, packet.destChannel))
    // defensive check that ensures chain does not process a packet higher than the last packet sent before
    // counterparty went into FLUSHING mode. If the counterparty is implemented correctly, this should never abort
    abortTransactionUnless(counterpartyUpgrade.nextSequenceSend == 0 || packet.sequence < counterpartyUpgrade.nextSequenceSend)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.destPort, packet.destChannel), capability))
    abortTransactionUnless(packet.sourcePort === channel.counterpartyPortIdentifier)
    abortTransactionUnless(packet.sourceChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    if (len(channel.connectionHops) > 1) {
      key = packetCommitmentPath(packet.GetSourcePort(), packet.GetSourceChannel(), packet.GetSequence())
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proof,
        channel.ConnectionHops,
        key,
        hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)
      ))
    } else {
      abortTransactionUnless(connection.verifyPacketData(
        proofHeight,
        proof,
        packet.sourcePort,
        packet.sourceChannel,
        packet.sequence,
        hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)
      ))
    }

    // do sequence check before any state changes
    if channel.order == ORDERED || channel.order == ORDERED_ALLOW_TIMEOUT {
        nextSequenceRecv = provableStore.get(nextSequenceRecvPath(packet.destPort, packet.destChannel))
        if (packet.sequence < nextSequenceRecv) {
          // event is emitted even if transaction is aborted
          emitLogEntry("recvPacket", {
            data: packet.data
            timeoutHeight: packet.timeoutHeight,
            timeoutTimestamp: packet.timeoutTimestamp,
            sequence: packet.sequence,
            sourcePort: packet.sourcePort,
            sourceChannel: packet.sourceChannel,
            destPort: packet.destPort,
            destChannel: packet.destChannel,
            order: channel.order,
            connection: channel.connectionHops[0]
          })
        }

        abortTransactionUnless(packet.sequence === nextSequenceRecv)
    }

    switch channel.order {
      case ORDERED:
      case UNORDERED:
        abortTransactionUnless(packet.timeoutHeight === 0 || getConsensusHeight() < packet.timeoutHeight)
        abortTransactionUnless(packet.timeoutTimestamp === 0 || currentTimestamp() < packet.timeoutTimestamp)
        break;

      case ORDERED_ALLOW_TIMEOUT:
        // for ORDERED_ALLOW_TIMEOUT, we do not abort on timeout
        // instead increment next sequence recv and write the sentinel timeout value in packet receipt
        // then return
        if (getConsensusHeight() >= packet.timeoutHeight && packet.timeoutHeight != 0) || (currentTimestamp() >= packet.timeoutTimestamp && packet.timeoutTimestamp != 0) {
          nextSequenceRecv = nextSequenceRecv + 1
          provableStore.set(nextSequenceRecvPath(packet.destPort, packet.destChannel), nextSequenceRecv)
          provableStore.set(
            packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence),
            TIMEOUT_RECEIPT
          )
        }
        return;

      default:
        // unsupported channel type
        abortTransactionUnless(false)
    }

    // REPLAY PROTECTION: in order to free storage, implementations may choose to 
    // delete acknowledgements and packet receipts when a channel upgrade is successfully 
    // completed. In that case, implementations must also make sure that any packet with 
    // a sequence already used before the channel upgrade is rejected. This is needed to 
    // prevent replay attacks (see this PR in ibc-go for an example of how this is achieved:
    // https://github.com/cosmos/ibc-go/pull/5651).
    
    // all assertions passed (except sequence check), we can alter state

    switch channel.order {
      case ORDERED:
      case ORDERED_ALLOW_TIMEOUT:
        nextSequenceRecv = nextSequenceRecv + 1
        provableStore.set(nextSequenceRecvPath(packet.destPort, packet.destChannel), nextSequenceRecv)
        break;

      case UNORDERED:
        // for unordered channels we must set the receipt so it can be verified on the other side
        // this receipt does not contain any data, since the packet has not yet been processed
        // it's the sentinel success receipt: []byte{0x01}
        packetReceipt = provableStore.get(packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence))
        if (packetReceipt != null) {
          emitLogEntry("recvPacket", {
            data: packet.data
            timeoutHeight: packet.timeoutHeight,
            timeoutTimestamp: packet.timeoutTimestamp,
            sequence: packet.sequence,
            sourcePort: packet.sourcePort,
            sourceChannel: packet.sourceChannel,
            destPort: packet.destPort,
            destChannel: packet.destChannel,
            order: channel.order,
            connection: channel.connectionHops[0]
          })
        }

        abortTransactionUnless(packetReceipt === null)
        provableStore.set(
          packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence),
          SUCCESSFUL_RECEIPT
        )
      break;
    }

    // log that a packet has been received
    emitLogEntry("recvPacket", {
      data: packet.data
      timeoutHeight: packet.timeoutHeight,
      timeoutTimestamp: packet.timeoutTimestamp,
      sequence: packet.sequence,
      sourcePort: packet.sourcePort,
      sourceChannel: packet.sourceChannel,
      destPort: packet.destPort,
      destChannel: packet.destChannel,
      order: channel.order,
      connection: channel.connectionHops[0]
    })

    // return transparent packet
    return packet
}

写入确认

模块调用 writeAcknowledgement 函数，以写入处理 IBC 数据包后产生的数据，发送链随后可以对其进行验证，这有点类似于“执行回执”或“RPC 调用响应”。调用模块 MUST 以原子方式执行应用逻辑，并同时调用 writeAcknowledgement。这是一种异步确认，其内容不需要在接收到数据包时就确定，只需在处理完成时确定即可。在同步场景下，writeAcknowledgement 可以与 recvPacket 在同一笔交易中（以原子方式）调用。确认数据包并非必需；但是，如果有序通道使用确认机制，则必须要么确认全部数据包，要么一个都不确认（因为确认是按顺序处理的）。请注意，如果数据包未被确认，则源链上的数据包承诺将无法删除。IBC 的未来版本可能会加入机制，让模块声明自己是否会确认数据包，以便进行清理。 writeAcknowledgement 不会检查被确认的数据包是否确实已被接收，因为这会导致对已确认数据包的证明被验证两次。这个正确性要求由调用模块负责。调用模块 MUST 仅对先前由 recvPacket 接收过的数据包调用 writeAcknowledgement。 IBC 处理器按顺序执行以下步骤：

检查该数据包的确认是否尚未写入
在该数据包对应的唯一存储路径上设置不透明确认值

function writeAcknowledgement(
  packet: Packet,
  acknowledgement: bytes) {
    // acknowledgement must not be empty
    abortTransactionUnless(len(acknowledgement) !== 0)

    // cannot already have written the acknowledgement
    abortTransactionUnless(provableStore.get(packetAcknowledgementPath(packet.destPort, packet.destChannel, packet.sequence) === null))

    // write the acknowledgement
    provableStore.set(
      packetAcknowledgementPath(packet.destPort, packet.destChannel, packet.sequence),
      hash(acknowledgement)
    )

    // log that a packet has been acknowledged
    emitLogEntry("writeAcknowledgement", {
      sequence: packet.sequence,
      timeoutHeight: packet.timeoutHeight,
      port: packet.destPort,
      channel: packet.destChannel,
      timeoutTimestamp: packet.timeoutTimestamp,
      data: packet.data,
      acknowledgement
    })
}

处理确认

模块调用 acknowledgePacket 函数，以处理此前由调用模块通过某个通道发送给对手链上对手模块的数据包确认。 acknowledgePacket 还会清理数据包承诺，因为既然该数据包已经被接收并处理，该承诺就不再需要了。调用模块 MAY 以原子方式执行适当的应用确认处理逻辑，并同时调用 acknowledgePacket。我们像在接收数据包中一样传入 relayer 地址，以便这里也可以进行可能的激励。

function acknowledgePacket(
  packet: OpaquePacket,
  acknowledgement: bytes,
  proof: CommitmentProof | MultihopProof,
  proofHeight: Height,
  relayer: string): Packet {

    // abort transaction unless that channel is open, calling module owns the associated port, and the packet fields match
    channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === OPEN || channel.state === FLUSHING)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability))
    abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier)
    abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // verify we sent the packet and haven't cleared it out yet
    abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))
           === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp))

    // abort transaction unless correct acknowledgement on counterparty chain
    if (len(channel.connectionHops) > 1) {
      key = packetAcknowledgementPath(packet.GetDestPort(), packet.GetDestChannel(), packet.GetSequence())
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proof,
        channel.ConnectionHops,
        key,
        acknowledgement
      ))
    } else {
      abortTransactionUnless(connection.verifyPacketAcknowledgement(
        proofHeight,
        proof,
        packet.destPort,
        packet.destChannel,
        packet.sequence,
        acknowledgement
      ))
    }

    // abort transaction unless acknowledgement is processed in order
    if (channel.order === ORDERED || channel.order == ORDERED_ALLOW_TIMEOUT) {
      nextSequenceAck = provableStore.get(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel))
      abortTransactionUnless(packet.sequence === nextSequenceAck)
      nextSequenceAck = nextSequenceAck + 1
      provableStore.set(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel), nextSequenceAck)
    }

    // all assertions passed, we can alter state

    // delete our commitment so we can't "acknowledge" again
    provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))

    if channel.state == FLUSHING {
      upgradeTimeout = privateStore.get(counterpartyUpgradeTimeout(portIdentifier, channelIdentifier))
      if upgradeTimeout != nil {
        // counterparty-specified timeout must not have exceeded
        // if it has, then restore the channel and abort upgrade handshake
        if (upgradeTimeout.timeoutHeight != 0 && currentHeight() >= upgradeTimeout.timeoutHeight) ||
            (upgradeTimeout.timeoutTimestamp != 0 && currentTimestamp() >= upgradeTimeout.timeoutTimestamp ) {
                restoreChannel(portIdentifier, channelIdentifier)
        } else if pendingInflightPackets(portIdentifier, channelIdentifier) == nil {
          // if this was the last in-flight packet, then move channel state to FLUSHCOMPLETE
          channel.state = FLUSHCOMPLETE
          publicStore.set(channelPath(portIdentifier, channelIdentifier), channel)
        }
      }
    }

    // return transparent packet
    return packet
}

确认封装

远程链返回的确认在 IBC 协议中被定义为任意字节。这些数据既可能编码成功执行，也可能编码失败（超时以外的任何情况）。目前没有通用方法来区分这两种情况，这就要求任何客户端侧的数据包可视化工具都必须理解每一种应用特定协议，才能区分中继成功还是失败。为缓解这个问题，我们提供了额外的确认格式规范，应用特定协议 SHOULD 使用该规范。

message Acknowledgement {
  oneof response {
    bytes result = 21;
    string error = 22;
  }
}

如果应用对确认字节使用了不同格式，则它 MUST 不能被反序列化为该格式的有效 protobuf 消息。请注意，所有数据包都恰好包含一个非空字段，并且该字段必须是 result 或 error。字段编号 21 和 22 是特意选择的，目的是避免与其他用于确认的 protobuf 消息格式发生意外冲突。任何采用此格式的消息，其第一个字节都将是非 ASCII 值 0xaa（result）或 0xb2（error）。

超时

应用语义可能需要某种超时机制：即链在将交易视为错误之前，等待其被处理的最长时间。由于两条链具有不同的本地时钟，这显然会成为双花攻击的攻击面之一；攻击者可能延迟中继回执，或等到超时刚过后才发送数据包，因此应用自身不能安全地实现朴素的超时逻辑。请注意，为了避免任何可能的“双花”攻击，超时算法要求目标链处于运行状态且可达。在完全网络分区的情况下，任何事情都无法被证明，只能等待重新连通；超时必须在接收链上被证明，而不能仅仅依据发送链上缺少响应这一事实。

发送端

timeoutPacket 函数由某个模块调用，该模块此前曾尝试向对手方模块发送数据包；当该数据包在对手方链上的超时高度或超时时间戳已经过去，且该数据包尚未被提交时，可通过此函数证明该数据包已无法再被执行，并允许调用模块安全地执行相应的状态转换。调用模块可以在调用 timeoutPacket 的同时，以原子方式执行适当的应用层超时处理逻辑。对于有序通道，timeoutPacket 会检查接收通道端的 recvSequence，并在数据包超时后关闭该通道。对于无序通道，timeoutPacket 会检查 receipt key 不存在（如果数据包已被接收，则该键应已写入）。无序通道应当能够在存在超时数据包的情况下继续运行。如果对后续数据包的超时高度之间施加了关联约束，则可以安全地对某个已超时数据包之前的所有数据包执行批量超时处理。本规范暂不展开这些细节。与接收数据包中的做法一样，我们传入 relayer 地址，以便在这里也支持可能的激励机制。

function timeoutPacket(
  packet: OpaquePacket,
  proof: CommitmentProof | MultihopProof,
  proofHeight: Height,
  nextSequenceRecv: Maybe<uint64>,
  relayer: string): Packet {

    channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel))
    abortTransactionUnless(channel !== null)

    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability))
    abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)

    // note: the connection may have been closed
    abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier)

    // get the timestamp from the final consensus state in the channel path
    var proofTimestamp
    if (channel.connectionHops.length > 1) {
      consensusState = abortTransactionUnless(Unmarshal(proof.ConsensusProofs[proof.ConsensusProofs.length-1].Value))
      proofTimestamp = consensusState.GetTimestamp()
    } else {
      proofTimestamp, err = connection.getTimestampAtHeight(connection, proofHeight)
    }

    // check that timeout height or timeout timestamp has passed on the other end
    abortTransactionUnless(
      (packet.timeoutHeight > 0 && proofHeight >= packet.timeoutHeight) ||
      (packet.timeoutTimestamp > 0 && proofTimestamp >= packet.timeoutTimestamp))

    // verify we actually sent this packet, check the store
    abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))
           === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp))

    switch channel.order {
      case ORDERED:
        // ordered channel: check that packet has not been received
        // only allow timeout on next sequence so all sequences before the timed out packet are processed (received/timed out)
        // before this packet times out
        abortTransactionUnless(packet.sequence == nextSequenceRecv)
        // ordered channel: check that the recv sequence is as claimed
        if (channel.connectionHops.length > 1) {
          key = nextSequenceRecvPath(packet.srcPort, packet.srcChannel)
          abortTransactionUnless(connection.verifyMultihopMembership(
              connection,
              proofHeight,
              proof,
              channel.ConnectionHops,
              key,
              nextSequenceRecv
          ))
        } else {
            abortTransactionUnless(connection.verifyNextSequenceRecv(
              proofHeight,
              proof,
              packet.destPort,
              packet.destChannel,
              nextSequenceRecv
          ))
        }
        break;

      case UNORDERED:
        if (channel.connectionHops.length > 1) {
          key = packetReceiptPath(packet.srcPort, packet.srcChannel, packet.sequence)
          abortTransactionUnless(connection.verifyMultihopNonMembership(
            connection,
            proofHeight,
            proof,
            channel.ConnectionHops,
            key
          ))
        } else {
          // unordered channel: verify absence of receipt at packet index
          abortTransactionUnless(connection.verifyPacketReceiptAbsence(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
          ))
        }
        break;

      // NOTE: For ORDERED_ALLOW_TIMEOUT, the relayer must first attempt the receive on the destination chain
      // before the timeout receipt can be written and subsequently proven on the sender chain in timeoutPacket
      case ORDERED_ALLOW_TIMEOUT:
        abortTransactionUnless(packet.sequence == nextSequenceRecv - 1)

        if (channel.connectionHops.length > 1) {
          abortTransactionUnless(connection.verifyMultihopMembership(
              connection,
              proofHeight,
              proof,
              channel.ConnectionHops,
              packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence),
              TIMEOUT_RECEIPT
          ))
        } else {
          abortTransactionUnless(connection.verifyPacketReceipt(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
            TIMEOUT_RECEIPT,
          ))
        }
        break;

      default:
        // unsupported channel type
        abortTransactionUnless(true)
    }

    // all assertions passed, we can alter state

    // delete our commitment
    provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))

    if channel.state == FLUSHING {
      upgradeTimeout = privateStore.get(counterpartyUpgradeTimeout(portIdentifier, channelIdentifier))
      if upgradeTimeout != nil {
        // counterparty-specified timeout must not have exceeded
        // if it has, then restore the channel and abort upgrade handshake
        if (upgradeTimeout.timeoutHeight != 0 && currentHeight() >= upgradeTimeout.timeoutHeight) ||
            (upgradeTimeout.timeoutTimestamp != 0 && currentTimestamp() >= upgradeTimeout.timeoutTimestamp ) {
                restoreChannel(portIdentifier, channelIdentifier)
        } else if pendingInflightPackets(portIdentifier, channelIdentifier) == nil {
          // if this was the last in-flight packet, then move channel state to FLUSHCOMPLETE
          channel.state = FLUSHCOMPLETE
          publicStore.set(channelPath(portIdentifier, channelIdentifier), channel)
        }
      }
    }

    // only close on strictly ORDERED channels
    if channel.order === ORDERED {
      // if the channel is ORDERED and a packet is timed out in FLUSHING state then
      // all upgrade information is deleted and the channel is set to CLOSED.

      if channel.State == FLUSHING {
        // delete auxiliary upgrade state
        provableStore.delete(channelUpgradePath(portIdentifier, channelIdentifier))
        privateStore.delete(counterpartyUpgradePath(portIdentifier, channelIdentifier))
      }

      // ordered channel: close the channel
      channel.state = CLOSED
      provableStore.set(channelPath(packet.sourcePort, packet.sourceChannel), channel)
    }
    // on ORDERED_ALLOW_TIMEOUT, increment NextSequenceAck so that next packet can be acknowledged after this packet timed out.
    if channel.order === ORDERED_ALLOW_TIMEOUT {
      nextSequenceAck = nextSequenceAck + 1
      provableStore.set(nextSequenceAckPath(packet.srcPort, packet.srcChannel), nextSequenceAck)
    }

    // return transparent packet
    return packet
}

关闭时超时处理

模块会调用 timeoutOnClose 函数，以证明某个尚未被接收的数据包所发往的通道已经关闭，因此该数据包将永远不会被接收（即使 timeoutHeight 或 timeoutTimestamp 尚未到达）。调用模块在调用 timeoutOnClose 的同时，可以原子性地执行适当的应用层超时处理逻辑。我们像在接收数据包中一样传入 relayer 地址，以便这里也能支持可能的激励机制。

function timeoutOnClose(
  packet: Packet,
  proof: CommitmentProof | MultihopProof,
  proofClosed: CommitmentProof | MultihopProof,
  proofHeight: Height,
  nextSequenceRecv: Maybe<uint64>,
  relayer: string): Packet {

    channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel))
    // note: the channel may have been closed
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability))
    abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    // note: the connection may have been closed
    abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier)

    // verify we actually sent this packet, check the store
    abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))
           === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp))

    // return hops from counterparty's view
    counterpartyHops = getCounterpartyHops(proof, connection)

    // check that the opposing channel end has closed
    expected = ChannelEnd{CLOSED, channel.order, channel.portIdentifier,
                          channel.channelIdentifier, counterpartyHops, channel.version}

    // verify channel is closed
    if (channel.connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.VerifyMultihopMembership(
        connection,
        proofHeight,
        proofClosed,
        channel.ConnectionHops,
        key,
        expected
      ))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofClosed,
        channel.counterpartyPortIdentifier,
        channel.counterpartyChannelIdentifier,
        expected
      ))
    }

    switch channel.order {
      case ORDERED:
        // ordered channel: check that packet has not been received
        abortTransactionUnless(packet.sequence >= nextSequenceRecv)

        // ordered channel: check that the recv sequence is as claimed
        if (channel.connectionHops.length > 1) {
          key = nextSequenceRecvPath(packet.destPort, packet.destChannel)
          abortTransactionUnless(connection.verifyMultihopMembership(
            connection,
            proofHeight,
            proof,
            channel.ConnectionHops,
            key,
            nextSequenceRecv
          ))
        } else {
          abortTransactionUnless(connection.verifyNextSequenceRecv(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            nextSequenceRecv
          ))
        }
        break;

      case UNORDERED:
        // unordered channel: verify absence of receipt at packet index
        if (channel.connectionHops.length > 1) {
          abortTransactionUnless(connection.verifyMultihopNonMembership(
            connection,
            proofHeight,
            proof,
            channel.ConnectionHops,
            key
          ))
        } else {
          abortTransactionUnless(connection.verifyPacketReceiptAbsence(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
          ))
        }
        break;

      case ORDERED_ALLOW_TIMEOUT:
        // if packet.sequence >= nextSequenceRecv, then the relayer has not attempted
        // to receive the packet on the destination chain (e.g. because the channel is already closed).
        // In this situation it is not needed to verify the presence of a timeout receipt.
        // Otherwise, if packet.sequence < nextSequenceRecv, then the relayer has attempted
        // to receive the packet on the destination chain, and nextSequenceRecv has been incremented.
        // In this situation, verify the presence of timeout receipt. 
        if packet.sequence < nextSequenceRecv {
          abortTransactionUnless(connection.verifyPacketReceipt(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
            TIMEOUT_RECEIPT,
          ))
        }
        break;

      default:
        // unsupported channel type
        abortTransactionUnless(true)
    }

    // all assertions passed, we can alter state

    // delete our commitment
    provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))

    // return transparent packet
    return packet
}

清理状态

数据包必须先被确认，才能被清理。

竞态条件分析

同时发起握手尝试

如果两台机器同时相互发起通道开启握手，并尝试使用相同的标识符，那么两边都会失败，并且必须使用新的标识符。

标识符分配

目标链上的标识符分配存在一个无法避免的竞态条件。模块最好使用伪随机、无价值属性的标识符。不过，即便成功抢占了另一个模块想要使用的标识符，这最多只是令人困扰，无法对握手实施中间人攻击，因为接收模块必须已经拥有该握手目标端口的所有权。

超时 / 数据包确认

数据包超时与数据包确认之间不存在竞态条件，因为数据包要么在被接收之前已经超过超时高度，要么没有超过。

握手期间的中间人攻击

跨链状态验证能够防止连接握手和通道握手期间的中间人攻击，因为所有信息（源、目标客户端、通道等）都已被发起握手的模块知晓，并会在握手完成前得到确认。

连接 / 通道关闭时仍在传输中的数据包

如果某个连接或通道在数据包仍在传输过程中被关闭，这些数据包将无法再在目标链上被接收，并且可以在源链上超时处理。

查询通道

可以通过 queryChannel 查询通道：

function queryChannel(connId: Identifier, chanId: Identifier): ChannelEnd | void {
    return provableStore.get(channelPath(connId, chanId))
}

属性与不变量

通道标识符与端口标识符的唯一组合遵循先到先得原则：一旦某个组合已被分配，只有拥有相关端口的模块才能在该通道上发送或接收。
假设各条链在超时窗口内保持存活，数据包将被恰好投递一次；如果发生超时，则也只能在发送链上被恰好超时处理一次。
通道握手不会被任一条区块链上的其他模块或另一条区块链的 IBC 处理程序实施中间人攻击。

向后兼容性

不适用。

向前兼容性

数据结构和编码可以在连接层或通道层进行版本化。通道逻辑完全不关心数据包数据格式，模块可以在任何时候以任意方式对其进行修改。

示例实现

Go 语言的 ICS 04 实现可见于 ibc-go repository。
Rust 语言的 ICS 04 实现可见于 ibc-rs repository。

历史

2019 年 6 月 5 日 - 提交草案 2019 年 7 月 4 日 - 针对无序通道和确认机制进行修改 2019 年 7 月 16 日 - 为多跳路由的未来兼容性进行调整 2019 年 7 月 29 日 - 修订以处理连接关闭后的超时情况 2019 年 8 月 13 日 - 多项编辑 2019 年 8 月 25 日 - 清理 2022 年 1 月 10 日 - 添加 ORDERED_ALLOW_TIMEOUT 通道类型及相应逻辑 2023 年 3 月 28 日 - 添加 writeChannel 函数，用于在执行应用回调后写入通道端状态 2024 年 12 月 4 日 - 移除关于乐观数据包发送的描述

版权

本文所有内容均依据 Apache 2.0 许可证授权。

Synopsis

The “channel” abstraction provides message delivery semantics to the interblockchain communication protocol, in three categories: ordering, exactly-once delivery, and module permissioning. A channel serves as a conduit for packets passing between a module on one chain and a module on another, ensuring that packets are executed only once, delivered in the order in which they were sent (if necessary), and delivered only to the corresponding module owning the other end of the channel on the destination chain. Each channel is associated with a particular connection, and a connection may have any number of associated channels, allowing the use of common identifiers and amortising the cost of header verification across all the channels utilising a connection & light client. Channels are payload-agnostic. The modules which send and receive IBC packets decide how to construct packet data and how to act upon the incoming packet data, and must utilise their own application logic to determine which state transactions to apply according to what data the packet contains.

Motivation

The interblockchain communication protocol uses a cross-chain message passing model. IBC packets are relayed from one blockchain to the other by external relayer processes. Chain A and chain B confirm new blocks independently, and packets from one chain to the other may be delayed, censored, or re-ordered arbitrarily. Packets are visible to relayers and can be read from a blockchain by any relayer process and submitted to any other blockchain. The IBC protocol must provide ordering (for ordered channels) and exactly-once delivery guarantees to allow applications to reason about the combined state of connected modules on two chains.

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.

In order to provide the desired ordering, exactly-once delivery, and module permissioning semantics to the application layer, the interblockchain communication protocol must implement an abstraction to enforce these semantics — channels are this abstraction.

Definitions

ConsensusState is as defined in ICS 2. Connection is as defined in ICS 3. Port and authenticateCapability are as defined in ICS 5. hash is a generic collision-resistant hash function, the specifics of which must be agreed on by the modules utilising the channel. hash can be defined differently by different chains. Identifier, get, set, delete, getCurrentHeight, and module-system related primitives are as defined in ICS 24. See upgrades spec for definition of pendingInflightPackets and restoreChannel. A channel is a pipeline for exactly-once packet delivery between specific modules on separate blockchains, which has at least one end capable of sending packets and one end capable of receiving packets. A bidirectional channel is a channel where packets can flow in both directions: from A to B and from B to A. A unidirectional channel is a channel where packets can only flow in one direction: from A to B (or from B to A, the order of naming is arbitrary). An ordered channel is a channel where packets are delivered exactly in the order which they were sent. This channel type offers a very strict guarantee of ordering. Either, the packets are received in the order they were sent, or if a packet in the sequence times out; then all future packets are also not receivable and the channel closes. An ordered_allow_timeout channel is a less strict version of the ordered channel. Here, the channel logic will take a best effort approach to delivering the packets in order. In a stream of packets, the channel will relay all packets in order and if a packet in the stream times out, the timeout logic for that packet will execute and the rest of the later packets will continue processing in order. Thus, we do not close the channel on a timeout with this channel type. An unordered channel is a channel where packets can be delivered in any order, which may differ from the order in which they were sent.

enum ChannelOrder {
  ORDERED,
  UNORDERED,
  ORDERED_ALLOW_TIMEOUT,
}

Directionality and ordering are independent, so one can speak of a bidirectional unordered channel, a unidirectional ordered channel, etc. All channels provide exactly-once packet delivery, meaning that a packet sent on one end of a channel is delivered no more and no less than once, eventually, to the other end. This specification only concerns itself with bidirectional channels. Unidirectional channels can use almost exactly the same protocol and will be outlined in a future ICS. An end of a channel is a data structure on one chain storing channel metadata:

interface ChannelEnd {
  state: ChannelState
  ordering: ChannelOrder
  counterpartyPortIdentifier: Identifier
  counterpartyChannelIdentifier: Identifier
  connectionHops: [Identifier]
  version: string
  upgradeSequence: uint64
}

The state is the current state of the channel end.
The ordering field indicates whether the channel is unordered, ordered, or ordered_allow_timeout.
The counterpartyPortIdentifier identifies the port on the counterparty chain which owns the other end of the channel.
The counterpartyChannelIdentifier identifies the channel end on the counterparty chain.
The nextSequenceSend, stored separately, tracks the sequence number for the next packet to be sent.
The nextSequenceRecv, stored separately, tracks the sequence number for the next packet to be received.
The nextSequenceAck, stored separately, tracks the sequence number for the next packet to be acknowledged.
The connectionHops stores the list of connection identifiers ordered starting from the receiving end towards the sender. connectionHops[0] is the connection end on the receiving chain. More than one connection hop indicates a multi-hop channel.
The version string stores an opaque channel version, which is agreed upon during the handshake. This can determine module-level configuration such as which packet encoding is used for the channel. This version is not used by the core IBC protocol. If the version string contains structured metadata for the application to parse and interpret, then it is considered best practice to encode all metadata in a JSON struct and include the marshalled string in the version field.

See the upgrade spec for details on upgradeSequence. Channel ends have a state:

enum ChannelState {
  INIT,
  TRYOPEN,
  OPEN,
  CLOSED,
  FLUSHING,
  FLUSHINGCOMPLETE,
}

A channel end in INIT state has just started the opening handshake.
A channel end in TRYOPEN state has acknowledged the handshake step on the counterparty chain.
A channel end in OPEN state has completed the handshake and is ready to send and receive packets.
A channel end in CLOSED state has been closed and can no longer be used to send or receive packets.

See the upgrade spec for details on FLUSHING and FLUSHCOMPLETE. A Packet, in the interblockchain communication protocol, is a particular interface defined as follows:

interface Packet {
  sequence: uint64
  timeoutHeight: Height
  timeoutTimestamp: uint64
  sourcePort: Identifier
  sourceChannel: Identifier
  destPort: Identifier
  destChannel: Identifier
  data: bytes
}

The sequence number corresponds to the order of sends and receives, where a packet with an earlier sequence number must be sent and received before a packet with a later sequence number.
The timeoutHeight indicates a consensus height on the destination chain after which the packet will no longer be processed, and will instead count as having timed-out.
The timeoutTimestamp indicates a timestamp on the destination chain after which the packet will no longer be processed, and will instead count as having timed-out.
The sourcePort identifies the port on the sending chain.
The sourceChannel identifies the channel end on the sending chain.
The destPort identifies the port on the receiving chain.
The destChannel identifies the channel end on the receiving chain.
The data is an opaque value which can be defined by the application logic of the associated modules.

Note that a Packet is never directly serialised. Rather it is an intermediary structure used in certain function calls that may need to be created or processed by modules calling the IBC handler. An OpaquePacket is a packet, but cloaked in an obscuring data type by the host state machine, such that a module cannot act upon it other than to pass it to the IBC handler. The IBC handler can cast a Packet to an OpaquePacket and vice versa.

type OpaquePacket = object

In order to enable new channel types (e.g. ORDERED_ALLOW_TIMEOUT), the protocol introduces standardized packet receipts that will serve as sentinel values for the receiving chain to explicitly write to its store the outcome of a recvPacket.

enum PacketReceipt {
  SUCCESSFUL_RECEIPT,
  TIMEOUT_RECEIPT,
}

Desired Properties

Efficiency

The speed of packet transmission and confirmation should be limited only by the speed of the underlying chains. Proofs should be batchable where possible.

Exactly-once delivery

IBC packets sent on one end of a channel should be delivered exactly once to the other end.
No network synchrony assumptions should be required for exactly-once safety. If one or both of the chains halt, packets may be delivered no more than once, and once the chains resume packets should be able to flow again.

Ordering

On ordered channels, packets should be sent and received in the same order: if packet x is sent before packet y by a channel end on chain A, packet x must be received before packet y by the corresponding channel end on chain B. If packet x is sent before packet y by a channel and packet x is timed out; then packet y and any packet sent after x cannot be received.
On ordered_allow_timeout channels, packets should be sent and received in the same order: if packet x is sent before packet y by a channel end on chain A, packet x must be received or timed out before packet y by the corresponding channel end on chain B.
On unordered channels, packets may be sent and received in any order. Unordered packets, like ordered packets, have individual timeouts specified in terms of the destination chain’s height.

Permissioning

Channels should be permissioned to one module on each end, determined during the handshake and immutable afterwards (higher-level logic could tokenize channel ownership by tokenising ownership of the port). Only the module associated with a channel end should be able to send or receive on it.

Technical Specification

Dataflow visualisation

The architecture of clients, connections, channels and packets: Dataflow Visualisation

Preliminaries

Store paths

Channel structures are stored under a store path prefix unique to a combination of a port identifier and channel identifier:

function channelPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "channelEnds/ports/{portIdentifier}/channels/{channelIdentifier}"
}

The capability key associated with a channel is stored under the channelCapabilityPath:

function channelCapabilityPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
  return "{channelPath(portIdentifier, channelIdentifier)}/key"
}

The nextSequenceSend, nextSequenceRecv, and nextSequenceAck unsigned integer counters are stored separately so they can be proved individually:

function nextSequenceSendPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "nextSequenceSend/ports/{portIdentifier}/channels/{channelIdentifier}"
}

function nextSequenceRecvPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "nextSequenceRecv/ports/{portIdentifier}/channels/{channelIdentifier}"
}

function nextSequenceAckPath(portIdentifier: Identifier, channelIdentifier: Identifier): Path {
    return "nextSequenceAck/ports/{portIdentifier}/channels/{channelIdentifier}"
}

Constant-size commitments to packet data fields are stored under the packet sequence number:

function packetCommitmentPath(portIdentifier: Identifier, channelIdentifier: Identifier, sequence: uint64): Path {
    return "commitments/ports/{portIdentifier}/channels/{channelIdentifier}/sequences/{sequence}"
}

Absence of the path in the store is equivalent to a zero-bit. Packet receipt data are stored under the packetReceiptPath. In the case of a successful receive, the destination chain writes a sentinel success value of SUCCESSFUL_RECEIPT. Some channel types MAY write a sentinel timeout value TIMEOUT_RECEIPT if the packet is received after the specified timeout.

function packetReceiptPath(portIdentifier: Identifier, channelIdentifier: Identifier, sequence: uint64): Path {
    return "receipts/ports/{portIdentifier}/channels/{channelIdentifier}/sequences/{sequence}"
}

Packet acknowledgement data are stored under the packetAcknowledgementPath:

function packetAcknowledgementPath(portIdentifier: Identifier, channelIdentifier: Identifier, sequence: uint64): Path {
    return "acks/ports/{portIdentifier}/channels/{channelIdentifier}/sequences/{sequence}"
}

Versioning

During the handshake process, two ends of a channel come to agreement on a version bytestring associated with that channel. The contents of this version bytestring are and will remain opaque to the IBC core protocol. Host state machines MAY utilise the version data to indicate supported IBC/APP protocols, agree on packet encoding formats, or negotiate other channel-related metadata related to custom logic on top of IBC. Host state machines MAY also safely ignore the version data or specify an empty string.

Sub-protocols

Note: If the host state machine is utilising object capability authentication (see ICS 005), all functions utilising ports take an additional capability parameter.

Identifier validation

Channels are stored under a unique (portIdentifier, channelIdentifier) prefix. The validation function validatePortIdentifier MAY be provided.

type validateChannelIdentifier = (portIdentifier: Identifier, channelIdentifier: Identifier) => boolean

If not provided, the default validateChannelIdentifier function will always return true.

Channel lifecycle management

Initiator	Datagram	Chain acted upon	Prior state (A, B)	Posterior state (A, B)
Actor	ChanOpenInit	A	(none, none)	(INIT, none)
Relayer	ChanOpenTry	B	(INIT, none)	(INIT, TRYOPEN)
Relayer	ChanOpenAck	A	(INIT, TRYOPEN)	(OPEN, TRYOPEN)
Relayer	ChanOpenConfirm	B	(OPEN, TRYOPEN)	(OPEN, OPEN)

Initiator	Datagram	Chain acted upon	Prior state (A, B)	Posterior state (A, B)
Actor	ChanCloseInit	A	(OPEN, OPEN)	(CLOSED, OPEN)
Relayer	ChanCloseConfirm	B	(CLOSED, OPEN)	(CLOSED, CLOSED)
Actor	ChanCloseFrozen	A or B	(OPEN, OPEN)	(CLOSED, CLOSED)

Opening handshake

The chanOpenInit function is called by a module to initiate a channel opening handshake with a module on another chain. Functions chanOpenInit and chanOpenTry do no set the new channel end in state because the channel version might be modified by the application callback. A function writeChannel should be used to write the channel end in state after executing the application callback:

function writeChannel(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  state: ChannelState,
  order: ChannelOrder,
  counterpartyPortIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  connectionHops: [Identifier],
  version: string) {
    channel = ChannelEnd{
      state, order,
      counterpartyPortIdentifier, counterpartyChannelIdentifier,
      connectionHops, version
    }
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

See handler functions handleChanOpenInit and handleChanOpenTry in Channel lifecycle management for more details. The opening channel must provide the identifiers of the local channel identifier, local port, remote port, and remote channel identifier. When the opening handshake is complete, the module which initiates the handshake will own the end of the created channel on the host ledger, and the counterparty module which it specifies will own the other end of the created channel on the counterparty chain. Once a channel is created, ownership cannot be changed (although higher-level abstractions could be implemented to provide this). Chains MUST implement a function generateIdentifier which chooses an identifier, e.g. by incrementing a counter:

type generateIdentifier = () -> Identifier

function chanOpenInit(
  order: ChannelOrder,
  connectionHops: [Identifier],
  portIdentifier: Identifier,
  counterpartyPortIdentifier: Identifier): (channelIdentifier: Identifier, channelCapability: CapabilityKey) {
    channelIdentifier = generateIdentifier()
    abortTransactionUnless(validateChannelIdentifier(portIdentifier, channelIdentifier))

    abortTransactionUnless(provableStore.get(channelPath(portIdentifier, channelIdentifier)) === null)
    connection = provableStore.get(connectionPath(connectionHops[0]))

    // optimistic channel handshakes are allowed
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(authenticateCapability(portPath(portIdentifier), portCapability))

    channelCapability = newCapability(channelCapabilityPath(portIdentifier, channelIdentifier))
    provableStore.set(nextSequenceSendPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), 1)

    return channelIdentifier, channelCapability
}

The chanOpenTry function is called by a module to accept the first step of a channel opening handshake initiated by a module on another chain.

function chanOpenTry(
  order: ChannelOrder,
  connectionHops: [Identifier],
  portIdentifier: Identifier,
  counterpartyPortIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  counterpartyVersion: string,
  proofInit: CommitmentProof | MultihopProof,
  proofHeight: Height): (channelIdentifier: Identifier, channelCapability: CapabilityKey) {
    channelIdentifier = generateIdentifier()

    abortTransactionUnless(validateChannelIdentifier(portIdentifier, channelIdentifier))
    abortTransactionUnless(authenticateCapability(portPath(portIdentifier), portCapability))

    connection = provableStore.get(connectionPath(connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofInit, connection)

    expected = ChannelEnd{
      INIT, order, portIdentifier,
      "", counterpartyHops,
      counterpartyVersion
    }

    if (connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofInit,
        connectionHops,
        key
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofInit,
        counterpartyPortIdentifier,
        counterpartyChannelIdentifier,
        expected
      ))
    }

    channelCapability = newCapability(channelCapabilityPath(portIdentifier, channelIdentifier))

    // initialize channel sequences
    provableStore.set(nextSequenceSendPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceRecvPath(portIdentifier, channelIdentifier), 1)
    provableStore.set(nextSequenceAckPath(portIdentifier, channelIdentifier), 1)

    return channelIdentifier, channelCapability
}

The chanOpenAck is called by the handshake-originating module to acknowledge the acceptance of the initial request by the counterparty module on the other chain.

function chanOpenAck(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyChannelIdentifier: Identifier,
  counterpartyVersion: string,
  proofTry: CommitmentProof | MultihopProof,
  proofHeight: Height) {
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel.state === INIT)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofTry, connection)

    expected = ChannelEnd{TRYOPEN, channel.order, portIdentifier,
        channelIdentifier, counterpartyHops, counterpartyVersion}

    if (channel.connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofTry,
        channel.connectionHops,
        key,
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofTry,
        channel.counterpartyPortIdentifier,
        counterpartyChannelIdentifier,
        expected
      ))
    }
    // write will happen in the handler defined in the ICS26 spec
}

The chanOpenConfirm function is called by the handshake-accepting module to acknowledge the acknowledgement of the handshake-originating module on the other chain and finish the channel opening handshake.

function chanOpenConfirm(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proofAck: CommitmentProof | MultihopProof,
  proofHeight: Height) {
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === TRYOPEN)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofAck, connection)

    expected = ChannelEnd{OPEN, channel.order, portIdentifier,
      channelIdentifier, counterpartyHops, channel.version}

    if (connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofAck,
        channel.connectionHops,
        key
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofAck,
        channel.counterpartyPortIdentifier,
        channel.counterpartyChannelIdentifier,
        expected
      ))
    }

    // write will happen in the handler defined in the ICS26 spec
}

Closing handshake

The chanCloseInit function is called by either module to close their end of the channel. Once closed, channels cannot be reopened. Calling modules MAY atomically execute appropriate application logic in conjunction with calling chanCloseInit. Any in-flight packets can be timed-out as soon as a channel is closed.

function chanCloseInit(
  portIdentifier: Identifier,
  channelIdentifier: Identifier) {
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state !== CLOSED)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)
    channel.state = CLOSED
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

The chanCloseConfirm function is called by the counterparty module to close their end of the channel, since the other end has been closed. Calling modules MAY atomically execute appropriate application logic in conjunction with calling chanCloseConfirm. Once closed, channels cannot be reopened and identifiers cannot be reused. Identifier reuse is prevented because we want to prevent potential replay of previously sent packets. The replay problem is analogous to using sequence numbers with signed messages, except where the light client algorithm “signs” the messages (IBC packets), and the replay prevention sequence is the combination of port identifier, channel identifier, and packet sequence - hence we cannot allow the same port identifier & channel identifier to be reused again with a sequence reset to zero, since this might allow packets to be replayed. It would be possible to safely reuse identifiers if timeouts of a particular maximum height/time were mandated & tracked, and future specification versions may incorporate this feature.

function chanCloseConfirm(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proofInit: CommitmentProof | MultihopProof,
  proofHeight: Height) {
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state !== CLOSED)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // return hops from counterparty's view
    counterpartyHops = getCounterPartyHops(proofInit, connection)

    expected = ChannelEnd{CLOSED, channel.order, portIdentifier,
                          channelIdentifier, counterpartyHops, channel.version}

    if (connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proofInit,
        channel.connectionHops,
        key
        expected))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofInit,
        channel.counterpartyPortIdentifier,
        channel.counterpartyChannelIdentifier,
        expected
      ))
    }

    // write may happen asynchronously in the handler defined in the ICS26 spec
    // if the channel is closing during an upgrade, 
    // then we can delete all auxiliary upgrade information
    provableStore.delete(channelUpgradePath(portIdentifier, channelIdentifier))
    privateStore.delete(counterpartyUpgradePath(portIdentifier, channelIdentifier))

    channel.state = CLOSED
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

The chanCloseFrozen function is called by a relayer to force close a multi-hop channel if any client state in the channel path is frozen. A relayer should send proof of the frozen client state to each end of the channel with a proof of the frozen client state in the channel path starting from each channel end up until the first frozen client. The multi-hop proof for each channel end will be different and consist of a proof formed starting from each channel end up to the frozen client. The multi-hop proof starts with a chain with a frozen client for the misbehaving chain. However, the frozen client exists on the next blockchain in the channel path so the key/value proof is indexed to evaluate on the consensus state holding that client state. The client state path requires knowledge of the client id which can be determined from the connectionEnd on the misbehaving chain prior to the misbehavior submission. Once frozen, it is possible for a channel to be unfrozen (reactivated) via governance processes once the misbehavior in the channel path has been resolved. However, this process is out-of-protocol. Example: Given a multi-hop channel path over connections from chain A to chain E and misbehaving chain C A <--> B <--x C x--> D <--> E Assume any relayer submits evidence of misbehavior to chain B and chain D to freeze their respective clients for chain C. A relayer may then provide a multi-hop proof of the frozen client on chain B to chain A to close the channel on chain A, and another relayer (or the same one) may also relay a multi-hop proof of the frozen client on chain D to chain E to close the channel end on chain E. However, it must also be proven that the frozen client state corresponds to a specific hop in the channel path. Therefore, a proof of the connection end on chain B with counterparty connection end on chain C must also be provided along with the client state proof to prove that the clientID for the client state matches the clientID in the connection end. Furthermore, the connectionID for the connection end MUST match the expected ID from the channel’s connectionHops field.

function chanCloseFrozen(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proofConnection: MultihopProof,
  proofClientState: MultihopProof,
  proofHeight: Height) {
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(portIdentifier, channelIdentifier), capability))
    channel = provableStore.get(channelPath(portIdentifier, channelIdentifier))
    abortTransactionUnless(channel !== null)
    hopsLength = channel.connectionHops.length
    abortTransactionUnless(hopsLength === 1)
    abortTransactionUnless(channel.state !== CLOSED)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // lookup connectionID for connectionEnd corresponding to misbehaving chain
    let connectionIdx = proofConnection.ConnectionProofs.length + 1
    abortTransactionUnless(connectionIdx < hopsLength)
    let connectionID = channel.ConnectionHops[connectionIdx]
    let connectionProofKey = connectionPath(connectionID)
    let connectionProofValue = proofConnection.KeyProof.Value
    let frozenConnectionEnd = abortTransactionUnless(Unmarshal(connectionProofValue))

    // the clientID in the connection end must match the clientID for the frozen client state
    let clientID = frozenConnectionEnd.ClientId

    // truncated connectionHops. e.g. client D on chain C is frozen: A, B, C, D, E -> A, B, C
    let connectionHops = channel.ConnectionHops[:len(mProof.ConnectionProofs)+1]

    // verify the connection proof
    abortTransactionUnless(connection.verifyMultihopMembership(
      connection,
      proofHeight,
      proofConnection,
      connectionHops,
      connectionProofKey,
      connectionProofValue))


    // key and value for the frozen client state
    let clientStateKey = clientStatePath(clientID)
    let clientStateValue = proofClientState.KeyProof.Value
    let frozenClientState = abortTransactionUnless(Unmarshal(clientStateValue))

    // ensure client state is frozen by checking FrozenHeight
    abortTransactionUnless(frozenClientState.FrozenHeight.RevisionHeight !== 0)

   // verify the frozen client state proof
    abortTransactionUnless(connection.verifyMultihopMembership(
      connection,
      proofHeight,
      proofConnection,
      connectionHops,
      clientStateKey,
      clientStateValue))

    channel.state = FROZEN
    provableStore.set(channelPath(portIdentifier, channelIdentifier), channel)
}

Multihop utility functions

// Return the counterparty connectionHops
function getCounterPartyHops(proof: CommitmentProof | MultihopProof, lastConnection: ConnectionEnd) string[] {

  let counterpartyHops: string[] = [lastConnection.counterpartyConnectionIdentifier]
  if typeof(proof) === 'MultihopProof' {
    for connData in proofs.ConnectionProofs {
      connectionEnd = abortTransactionUnless(Unmarshal(connData.Value))
      counterpartyHops.push(connectionEnd.GetCounterparty().GetConnectionID())
    }

    // reverse the hops so they are ordered from sender --> receiver
    counterpartyHops = counterpartyHops.reverse()
  }

  return counterpartyHops
}

Packet flow & handling

A day in the life of a packet

The following sequence of steps must occur for a packet to be sent from module 1 on machine A to module 2 on machine B, starting from scratch. The module can interface with the IBC handler through ICS 25 or ICS 26.

Initial client & port setup, in any order
1. Client created on A for B (see ICS 2)
2. Client created on B for A (see ICS 2)
3. Module 1 binds to a port (see ICS 5)
4. Module 2 binds to a port (see ICS 5), which is communicated out-of-band to module 1
Establishment of a connection & channel, optimistic send, in order
1. Connection opening handshake started from A to B by module 1 (see ICS 3)
2. Channel opening handshake started from 1 to 2 using the newly created connection (this ICS)
3. Packet sent over the newly created channel from 1 to 2 (this ICS)
Successful completion of handshakes (if either handshake fails, the connection/channel can be closed & the packet timed-out)
1. Connection opening handshake completes successfully (see ICS 3) (this will require participation of a relayer process)
2. Channel opening handshake completes successfully (this ICS) (this will require participation of a relayer process)
Packet confirmation on machine B, module 2 (or packet timeout if the timeout height has passed) (this will require participation of a relayer process)
Acknowledgement (possibly) relayed back from module 2 on machine B to module 1 on machine A

Represented spatially, packet transit between two machines can be rendered as follows:

Sending packets

The sendPacket function is called by a module in order to send data (in the form of an IBC packet) on a channel end owned by the calling module. Calling modules MUST execute application logic atomically in conjunction with calling sendPacket. The IBC handler performs the following steps in order:

Checks that the channel is opened to send packets
Checks that the calling module owns the sending port (see ICS 5)
Checks that the timeout height specified has not already passed on the destination chain
Increments the send sequence counter associated with the channel
Stores a constant-size commitment to the packet data & packet timeout
Returns the sequence number of the sent packet

Note that the full packet is not stored in the state of the chain - merely a short hash-commitment to the data & timeout value. The packet data can be calculated from the transaction execution and possibly returned as log output which relayers can index.

function sendPacket(
  capability: CapabilityKey,
  sourcePort: Identifier,
  sourceChannel: Identifier,
  timeoutHeight: Height,
  timeoutTimestamp: uint64,
  data: bytes): uint64 {
    channel = provableStore.get(channelPath(sourcePort, sourceChannel))

    // check that the channel must be OPEN to send packets;
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === OPEN)
    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)

    // check if the calling module owns the sending port
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(sourcePort, sourceChannel), capability))

    // disallow packets with a zero timeoutHeight and timeoutTimestamp
    abortTransactionUnless(timeoutHeight !== 0 || timeoutTimestamp !== 0)

    // check that the timeout height hasn't already passed in the local client tracking the receiving chain
    latestClientHeight = provableStore.get(clientPath(connection.clientIdentifier)).latestClientHeight()
    abortTransactionUnless(timeoutHeight === 0 || latestClientHeight < timeoutHeight)

    // increment the send sequence counter
    sequence = provableStore.get(nextSequenceSendPath(sourcePort, sourceChannel))
    provableStore.set(nextSequenceSendPath(sourcePort, sourceChannel), sequence+1)

    // store commitment to the packet data & packet timeout
    provableStore.set(
      packetCommitmentPath(sourcePort, sourceChannel, sequence),
      hash(hash(data), timeoutHeight, timeoutTimestamp)
    )

    // log that a packet can be safely sent
    emitLogEntry("sendPacket", {
      sequence: sequence,
      data: data,
      timeoutHeight: timeoutHeight,
      timeoutTimestamp: timeoutTimestamp
    })

    return sequence
}

Receiving packets

The recvPacket function is called by a module in order to receive an IBC packet sent on the corresponding channel end on the counterparty chain. Atomically in conjunction with calling recvPacket, calling modules MUST either execute application logic or queue the packet for future execution. The IBC handler performs the following steps in order:

Checks that the channel & connection are open to receive packets
Checks that the calling module owns the receiving port
Checks that the packet metadata matches the channel & connection information
Checks that the packet sequence is the next sequence the channel end expects to receive (for ordered and ordered_allow_timeout channels)
Checks that the timeout height and timestamp have not yet passed
Checks the inclusion proof of packet data commitment in the outgoing chain’s state
Optionally (in case channel upgrades and deletion of acknowledgements and packet receipts are implemented): reject any packet with a sequence already used before a successful channel upgrade
Sets a store path to indicate that the packet has been received (unordered channels only)
Increments the packet receive sequence associated with the channel end (ordered and ordered_allow_timeout channels only)

We pass the address of the relayer that signed and submitted the packet to enable a module to optionally provide some rewards. This provides a foundation for fee payment, but can be used for other techniques as well (like calculating a leaderboard).

function recvPacket(
  packet: OpaquePacket,
  proof: CommitmentProof | MultihopProof,
  proofHeight: Height,
  relayer: string): Packet {

    channel = provableStore.get(channelPath(packet.destPort, packet.destChannel))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === OPEN || (channel.state === FLUSHING) || (channel.state === FLUSHCOMPLETE))
    counterpartyUpgrade = privateStore.get(counterpartyUpgradePath(packet.destPort, packet.destChannel))
    // defensive check that ensures chain does not process a packet higher than the last packet sent before
    // counterparty went into FLUSHING mode. If the counterparty is implemented correctly, this should never abort
    abortTransactionUnless(counterpartyUpgrade.nextSequenceSend == 0 || packet.sequence < counterpartyUpgrade.nextSequenceSend)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.destPort, packet.destChannel), capability))
    abortTransactionUnless(packet.sourcePort === channel.counterpartyPortIdentifier)
    abortTransactionUnless(packet.sourceChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    if (len(channel.connectionHops) > 1) {
      key = packetCommitmentPath(packet.GetSourcePort(), packet.GetSourceChannel(), packet.GetSequence())
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proof,
        channel.ConnectionHops,
        key,
        hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)
      ))
    } else {
      abortTransactionUnless(connection.verifyPacketData(
        proofHeight,
        proof,
        packet.sourcePort,
        packet.sourceChannel,
        packet.sequence,
        hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp)
      ))
    }

    // do sequence check before any state changes
    if channel.order == ORDERED || channel.order == ORDERED_ALLOW_TIMEOUT {
        nextSequenceRecv = provableStore.get(nextSequenceRecvPath(packet.destPort, packet.destChannel))
        if (packet.sequence < nextSequenceRecv) {
          // event is emitted even if transaction is aborted
          emitLogEntry("recvPacket", {
            data: packet.data
            timeoutHeight: packet.timeoutHeight,
            timeoutTimestamp: packet.timeoutTimestamp,
            sequence: packet.sequence,
            sourcePort: packet.sourcePort,
            sourceChannel: packet.sourceChannel,
            destPort: packet.destPort,
            destChannel: packet.destChannel,
            order: channel.order,
            connection: channel.connectionHops[0]
          })
        }

        abortTransactionUnless(packet.sequence === nextSequenceRecv)
    }

    switch channel.order {
      case ORDERED:
      case UNORDERED:
        abortTransactionUnless(packet.timeoutHeight === 0 || getConsensusHeight() < packet.timeoutHeight)
        abortTransactionUnless(packet.timeoutTimestamp === 0 || currentTimestamp() < packet.timeoutTimestamp)
        break;

      case ORDERED_ALLOW_TIMEOUT:
        // for ORDERED_ALLOW_TIMEOUT, we do not abort on timeout
        // instead increment next sequence recv and write the sentinel timeout value in packet receipt
        // then return
        if (getConsensusHeight() >= packet.timeoutHeight && packet.timeoutHeight != 0) || (currentTimestamp() >= packet.timeoutTimestamp && packet.timeoutTimestamp != 0) {
          nextSequenceRecv = nextSequenceRecv + 1
          provableStore.set(nextSequenceRecvPath(packet.destPort, packet.destChannel), nextSequenceRecv)
          provableStore.set(
            packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence),
            TIMEOUT_RECEIPT
          )
        }
        return;

      default:
        // unsupported channel type
        abortTransactionUnless(false)
    }

    // REPLAY PROTECTION: in order to free storage, implementations may choose to 
    // delete acknowledgements and packet receipts when a channel upgrade is successfully 
    // completed. In that case, implementations must also make sure that any packet with 
    // a sequence already used before the channel upgrade is rejected. This is needed to 
    // prevent replay attacks (see this PR in ibc-go for an example of how this is achieved:
    // https://github.com/cosmos/ibc-go/pull/5651).
    
    // all assertions passed (except sequence check), we can alter state

    switch channel.order {
      case ORDERED:
      case ORDERED_ALLOW_TIMEOUT:
        nextSequenceRecv = nextSequenceRecv + 1
        provableStore.set(nextSequenceRecvPath(packet.destPort, packet.destChannel), nextSequenceRecv)
        break;

      case UNORDERED:
        // for unordered channels we must set the receipt so it can be verified on the other side
        // this receipt does not contain any data, since the packet has not yet been processed
        // it's the sentinel success receipt: []byte{0x01}
        packetReceipt = provableStore.get(packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence))
        if (packetReceipt != null) {
          emitLogEntry("recvPacket", {
            data: packet.data
            timeoutHeight: packet.timeoutHeight,
            timeoutTimestamp: packet.timeoutTimestamp,
            sequence: packet.sequence,
            sourcePort: packet.sourcePort,
            sourceChannel: packet.sourceChannel,
            destPort: packet.destPort,
            destChannel: packet.destChannel,
            order: channel.order,
            connection: channel.connectionHops[0]
          })
        }

        abortTransactionUnless(packetReceipt === null)
        provableStore.set(
          packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence),
          SUCCESSFUL_RECEIPT
        )
      break;
    }

    // log that a packet has been received
    emitLogEntry("recvPacket", {
      data: packet.data
      timeoutHeight: packet.timeoutHeight,
      timeoutTimestamp: packet.timeoutTimestamp,
      sequence: packet.sequence,
      sourcePort: packet.sourcePort,
      sourceChannel: packet.sourceChannel,
      destPort: packet.destPort,
      destChannel: packet.destChannel,
      order: channel.order,
      connection: channel.connectionHops[0]
    })

    // return transparent packet
    return packet
}

Writing acknowledgements

The writeAcknowledgement function is called by a module in order to write data which resulted from processing an IBC packet that the sending chain can then verify, a sort of “execution receipt” or “RPC call response”. Calling modules MUST execute application logic atomically in conjunction with calling writeAcknowledgement. This is an asynchronous acknowledgement, the contents of which do not need to be determined when the packet is received, only when processing is complete. In the synchronous case, writeAcknowledgement can be called in the same transaction (atomically) with recvPacket. Acknowledging packets is not required; however, if an ordered channel uses acknowledgements, either all or no packets must be acknowledged (since the acknowledgements are processed in order). Note that if packets are not acknowledged, packet commitments cannot be deleted on the source chain. Future versions of IBC may include ways for modules to specify whether or not they will be acknowledging packets in order to allow for cleanup. writeAcknowledgement does not check if the packet being acknowledged was actually received, because this would result in proofs being verified twice for acknowledged packets. This aspect of correctness is the responsibility of the calling module. The calling module MUST only call writeAcknowledgement with a packet previously received from recvPacket. The IBC handler performs the following steps in order:

Checks that an acknowledgement for this packet has not yet been written
Sets the opaque acknowledgement value at a store path unique to the packet

function writeAcknowledgement(
  packet: Packet,
  acknowledgement: bytes) {
    // acknowledgement must not be empty
    abortTransactionUnless(len(acknowledgement) !== 0)

    // cannot already have written the acknowledgement
    abortTransactionUnless(provableStore.get(packetAcknowledgementPath(packet.destPort, packet.destChannel, packet.sequence) === null))

    // write the acknowledgement
    provableStore.set(
      packetAcknowledgementPath(packet.destPort, packet.destChannel, packet.sequence),
      hash(acknowledgement)
    )

    // log that a packet has been acknowledged
    emitLogEntry("writeAcknowledgement", {
      sequence: packet.sequence,
      timeoutHeight: packet.timeoutHeight,
      port: packet.destPort,
      channel: packet.destChannel,
      timeoutTimestamp: packet.timeoutTimestamp,
      data: packet.data,
      acknowledgement
    })
}

Processing acknowledgements

The acknowledgePacket function is called by a module to process the acknowledgement of a packet previously sent by the calling module on a channel to a counterparty module on the counterparty chain. acknowledgePacket also cleans up the packet commitment, which is no longer necessary since the packet has been received and acted upon. Calling modules MAY atomically execute appropriate application acknowledgement-handling logic in conjunction with calling acknowledgePacket. We pass the relayer address just as in Receiving packets to allow for possible incentivization here as well.

function acknowledgePacket(
  packet: OpaquePacket,
  acknowledgement: bytes,
  proof: CommitmentProof | MultihopProof,
  proofHeight: Height,
  relayer: string): Packet {

    // abort transaction unless that channel is open, calling module owns the associated port, and the packet fields match
    channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel))
    abortTransactionUnless(channel !== null)
    abortTransactionUnless(channel.state === OPEN || channel.state === FLUSHING)
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability))
    abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier)
    abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)
    abortTransactionUnless(connection.state === OPEN)

    // verify we sent the packet and haven't cleared it out yet
    abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))
           === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp))

    // abort transaction unless correct acknowledgement on counterparty chain
    if (len(channel.connectionHops) > 1) {
      key = packetAcknowledgementPath(packet.GetDestPort(), packet.GetDestChannel(), packet.GetSequence())
      abortTransactionUnless(connection.verifyMultihopMembership(
        connection,
        proofHeight,
        proof,
        channel.ConnectionHops,
        key,
        acknowledgement
      ))
    } else {
      abortTransactionUnless(connection.verifyPacketAcknowledgement(
        proofHeight,
        proof,
        packet.destPort,
        packet.destChannel,
        packet.sequence,
        acknowledgement
      ))
    }

    // abort transaction unless acknowledgement is processed in order
    if (channel.order === ORDERED || channel.order == ORDERED_ALLOW_TIMEOUT) {
      nextSequenceAck = provableStore.get(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel))
      abortTransactionUnless(packet.sequence === nextSequenceAck)
      nextSequenceAck = nextSequenceAck + 1
      provableStore.set(nextSequenceAckPath(packet.sourcePort, packet.sourceChannel), nextSequenceAck)
    }

    // all assertions passed, we can alter state

    // delete our commitment so we can't "acknowledge" again
    provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))

    if channel.state == FLUSHING {
      upgradeTimeout = privateStore.get(counterpartyUpgradeTimeout(portIdentifier, channelIdentifier))
      if upgradeTimeout != nil {
        // counterparty-specified timeout must not have exceeded
        // if it has, then restore the channel and abort upgrade handshake
        if (upgradeTimeout.timeoutHeight != 0 && currentHeight() >= upgradeTimeout.timeoutHeight) ||
            (upgradeTimeout.timeoutTimestamp != 0 && currentTimestamp() >= upgradeTimeout.timeoutTimestamp ) {
                restoreChannel(portIdentifier, channelIdentifier)
        } else if pendingInflightPackets(portIdentifier, channelIdentifier) == nil {
          // if this was the last in-flight packet, then move channel state to FLUSHCOMPLETE
          channel.state = FLUSHCOMPLETE
          publicStore.set(channelPath(portIdentifier, channelIdentifier), channel)
        }
      }
    }

    // return transparent packet
    return packet
}

Acknowledgement Envelope

The acknowledgement returned from the remote chain is defined as arbitrary bytes in the IBC protocol. This data may either encode a successful execution or a failure (anything besides a timeout). There is no generic way to distinguish the two cases, which requires that any client-side packet visualiser understands every app-specific protocol in order to distinguish the case of successful or failed relay. In order to reduce this issue, we offer an additional specification for acknowledgement formats, which SHOULD be used by the app-specific protocols.

message Acknowledgement {
  oneof response {
    bytes result = 21;
    string error = 22;
  }
}

If an application uses a different format for acknowledgement bytes, it MUST not deserialise to a valid protobuf message of this format. Note that all packets contain exactly one non-empty field, and it must be result or error. The field numbers 21 and 22 were explicitly chosen to avoid accidental conflicts with other protobuf message formats used for acknowledgements. The first byte of any message with this format will be the non-ASCII values 0xaa (result) or 0xb2 (error).

Timeouts

Application semantics may require some timeout: an upper limit to how long the chain will wait for a transaction to be processed before considering it an error. Since the two chains have different local clocks, this is an obvious attack vector for a double spend - an attacker may delay the relay of the receipt or wait to send the packet until right after the timeout - so applications cannot safely implement naive timeout logic themselves. Note that in order to avoid any possible “double-spend” attacks, the timeout algorithm requires that the destination chain is running and reachable. One can prove nothing in a complete network partition, and must wait to connect; the timeout must be proven on the recipient chain, not simply the absence of a response on the sending chain.

Sending end

The timeoutPacket function is called by a module which originally attempted to send a packet to a counterparty module, where the timeout height or timeout timestamp has passed on the counterparty chain without the packet being committed, to prove that the packet can no longer be executed and to allow the calling module to safely perform appropriate state transitions. Calling modules MAY atomically execute appropriate application timeout-handling logic in conjunction with calling timeoutPacket. In the case of an ordered channel, timeoutPacket checks the recvSequence of the receiving channel end and closes the channel if a packet has timed out. In the case of an unordered channel, timeoutPacket checks the absence of the receipt key (which will have been written if the packet was received). Unordered channels are expected to continue in the face of timed-out packets. If relations are enforced between timeout heights of subsequent packets, safe bulk timeouts of all packets prior to a timed-out packet can be performed. This specification omits details for now. We pass the relayer address just as in Receiving packets to allow for possible incentivization here as well.

function timeoutPacket(
  packet: OpaquePacket,
  proof: CommitmentProof | MultihopProof,
  proofHeight: Height,
  nextSequenceRecv: Maybe<uint64>,
  relayer: string): Packet {

    channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel))
    abortTransactionUnless(channel !== null)

    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability))
    abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    abortTransactionUnless(connection !== null)

    // note: the connection may have been closed
    abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier)

    // get the timestamp from the final consensus state in the channel path
    var proofTimestamp
    if (channel.connectionHops.length > 1) {
      consensusState = abortTransactionUnless(Unmarshal(proof.ConsensusProofs[proof.ConsensusProofs.length-1].Value))
      proofTimestamp = consensusState.GetTimestamp()
    } else {
      proofTimestamp, err = connection.getTimestampAtHeight(connection, proofHeight)
    }

    // check that timeout height or timeout timestamp has passed on the other end
    abortTransactionUnless(
      (packet.timeoutHeight > 0 && proofHeight >= packet.timeoutHeight) ||
      (packet.timeoutTimestamp > 0 && proofTimestamp >= packet.timeoutTimestamp))

    // verify we actually sent this packet, check the store
    abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))
           === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp))

    switch channel.order {
      case ORDERED:
        // ordered channel: check that packet has not been received
        // only allow timeout on next sequence so all sequences before the timed out packet are processed (received/timed out)
        // before this packet times out
        abortTransactionUnless(packet.sequence == nextSequenceRecv)
        // ordered channel: check that the recv sequence is as claimed
        if (channel.connectionHops.length > 1) {
          key = nextSequenceRecvPath(packet.srcPort, packet.srcChannel)
          abortTransactionUnless(connection.verifyMultihopMembership(
              connection,
              proofHeight,
              proof,
              channel.ConnectionHops,
              key,
              nextSequenceRecv
          ))
        } else {
            abortTransactionUnless(connection.verifyNextSequenceRecv(
              proofHeight,
              proof,
              packet.destPort,
              packet.destChannel,
              nextSequenceRecv
          ))
        }
        break;

      case UNORDERED:
        if (channel.connectionHops.length > 1) {
          key = packetReceiptPath(packet.srcPort, packet.srcChannel, packet.sequence)
          abortTransactionUnless(connection.verifyMultihopNonMembership(
            connection,
            proofHeight,
            proof,
            channel.ConnectionHops,
            key
          ))
        } else {
          // unordered channel: verify absence of receipt at packet index
          abortTransactionUnless(connection.verifyPacketReceiptAbsence(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
          ))
        }
        break;

      // NOTE: For ORDERED_ALLOW_TIMEOUT, the relayer must first attempt the receive on the destination chain
      // before the timeout receipt can be written and subsequently proven on the sender chain in timeoutPacket
      case ORDERED_ALLOW_TIMEOUT:
        abortTransactionUnless(packet.sequence == nextSequenceRecv - 1)

        if (channel.connectionHops.length > 1) {
          abortTransactionUnless(connection.verifyMultihopMembership(
              connection,
              proofHeight,
              proof,
              channel.ConnectionHops,
              packetReceiptPath(packet.destPort, packet.destChannel, packet.sequence),
              TIMEOUT_RECEIPT
          ))
        } else {
          abortTransactionUnless(connection.verifyPacketReceipt(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
            TIMEOUT_RECEIPT,
          ))
        }
        break;

      default:
        // unsupported channel type
        abortTransactionUnless(true)
    }

    // all assertions passed, we can alter state

    // delete our commitment
    provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))

    if channel.state == FLUSHING {
      upgradeTimeout = privateStore.get(counterpartyUpgradeTimeout(portIdentifier, channelIdentifier))
      if upgradeTimeout != nil {
        // counterparty-specified timeout must not have exceeded
        // if it has, then restore the channel and abort upgrade handshake
        if (upgradeTimeout.timeoutHeight != 0 && currentHeight() >= upgradeTimeout.timeoutHeight) ||
            (upgradeTimeout.timeoutTimestamp != 0 && currentTimestamp() >= upgradeTimeout.timeoutTimestamp ) {
                restoreChannel(portIdentifier, channelIdentifier)
        } else if pendingInflightPackets(portIdentifier, channelIdentifier) == nil {
          // if this was the last in-flight packet, then move channel state to FLUSHCOMPLETE
          channel.state = FLUSHCOMPLETE
          publicStore.set(channelPath(portIdentifier, channelIdentifier), channel)
        }
      }
    }

    // only close on strictly ORDERED channels
    if channel.order === ORDERED {
      // if the channel is ORDERED and a packet is timed out in FLUSHING state then
      // all upgrade information is deleted and the channel is set to CLOSED.

      if channel.State == FLUSHING {
        // delete auxiliary upgrade state
        provableStore.delete(channelUpgradePath(portIdentifier, channelIdentifier))
        privateStore.delete(counterpartyUpgradePath(portIdentifier, channelIdentifier))
      }

      // ordered channel: close the channel
      channel.state = CLOSED
      provableStore.set(channelPath(packet.sourcePort, packet.sourceChannel), channel)
    }
    // on ORDERED_ALLOW_TIMEOUT, increment NextSequenceAck so that next packet can be acknowledged after this packet timed out.
    if channel.order === ORDERED_ALLOW_TIMEOUT {
      nextSequenceAck = nextSequenceAck + 1
      provableStore.set(nextSequenceAckPath(packet.srcPort, packet.srcChannel), nextSequenceAck)
    }

    // return transparent packet
    return packet
}

Timing-out on close

The timeoutOnClose function is called by a module in order to prove that the channel to which an unreceived packet was addressed has been closed, so the packet will never be received (even if the timeoutHeight or timeoutTimestamp has not yet been reached). Calling modules MAY atomically execute appropriate application timeout-handling logic in conjunction with calling timeoutOnClose. We pass the relayer address just as in Receiving packets to allow for possible incentivization here as well.

function timeoutOnClose(
  packet: Packet,
  proof: CommitmentProof | MultihopProof,
  proofClosed: CommitmentProof | MultihopProof,
  proofHeight: Height,
  nextSequenceRecv: Maybe<uint64>,
  relayer: string): Packet {

    channel = provableStore.get(channelPath(packet.sourcePort, packet.sourceChannel))
    // note: the channel may have been closed
    abortTransactionUnless(authenticateCapability(channelCapabilityPath(packet.sourcePort, packet.sourceChannel), capability))
    abortTransactionUnless(packet.destChannel === channel.counterpartyChannelIdentifier)

    connection = provableStore.get(connectionPath(channel.connectionHops[0]))
    // note: the connection may have been closed
    abortTransactionUnless(packet.destPort === channel.counterpartyPortIdentifier)

    // verify we actually sent this packet, check the store
    abortTransactionUnless(provableStore.get(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))
           === hash(packet.data, packet.timeoutHeight, packet.timeoutTimestamp))

    // return hops from counterparty's view
    counterpartyHops = getCounterpartyHops(proof, connection)

    // check that the opposing channel end has closed
    expected = ChannelEnd{CLOSED, channel.order, channel.portIdentifier,
                          channel.channelIdentifier, counterpartyHops, channel.version}

    // verify channel is closed
    if (channel.connectionHops.length > 1) {
      key = channelPath(counterparty.PortId, counterparty.ChannelId)
      abortTransactionUnless(connection.VerifyMultihopMembership(
        connection,
        proofHeight,
        proofClosed,
        channel.ConnectionHops,
        key,
        expected
      ))
    } else {
      abortTransactionUnless(connection.verifyChannelState(
        proofHeight,
        proofClosed,
        channel.counterpartyPortIdentifier,
        channel.counterpartyChannelIdentifier,
        expected
      ))
    }

    switch channel.order {
      case ORDERED:
        // ordered channel: check that packet has not been received
        abortTransactionUnless(packet.sequence >= nextSequenceRecv)

        // ordered channel: check that the recv sequence is as claimed
        if (channel.connectionHops.length > 1) {
          key = nextSequenceRecvPath(packet.destPort, packet.destChannel)
          abortTransactionUnless(connection.verifyMultihopMembership(
            connection,
            proofHeight,
            proof,
            channel.ConnectionHops,
            key,
            nextSequenceRecv
          ))
        } else {
          abortTransactionUnless(connection.verifyNextSequenceRecv(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            nextSequenceRecv
          ))
        }
        break;

      case UNORDERED:
        // unordered channel: verify absence of receipt at packet index
        if (channel.connectionHops.length > 1) {
          abortTransactionUnless(connection.verifyMultihopNonMembership(
            connection,
            proofHeight,
            proof,
            channel.ConnectionHops,
            key
          ))
        } else {
          abortTransactionUnless(connection.verifyPacketReceiptAbsence(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
          ))
        }
        break;

      case ORDERED_ALLOW_TIMEOUT:
        // if packet.sequence >= nextSequenceRecv, then the relayer has not attempted
        // to receive the packet on the destination chain (e.g. because the channel is already closed).
        // In this situation it is not needed to verify the presence of a timeout receipt.
        // Otherwise, if packet.sequence < nextSequenceRecv, then the relayer has attempted
        // to receive the packet on the destination chain, and nextSequenceRecv has been incremented.
        // In this situation, verify the presence of timeout receipt. 
        if packet.sequence < nextSequenceRecv {
          abortTransactionUnless(connection.verifyPacketReceipt(
            proofHeight,
            proof,
            packet.destPort,
            packet.destChannel,
            packet.sequence
            TIMEOUT_RECEIPT,
          ))
        }
        break;

      default:
        // unsupported channel type
        abortTransactionUnless(true)
    }

    // all assertions passed, we can alter state

    // delete our commitment
    provableStore.delete(packetCommitmentPath(packet.sourcePort, packet.sourceChannel, packet.sequence))

    // return transparent packet
    return packet
}

Cleaning up state

Packets must be acknowledged in order to be cleaned-up.

Reasoning about race conditions

Simultaneous handshake attempts

If two machines simultaneously initiate channel opening handshakes with each other, attempting to use the same identifiers, both will fail and new identifiers must be used.

Identifier allocation

There is an unavoidable race condition on identifier allocation on the destination chain. Modules would be well-advised to utilise pseudo-random, non-valuable identifiers. Managing to claim the identifier that another module wishes to use, however, while annoying, cannot man-in-the-middle a handshake since the receiving module must already own the port to which the handshake was targeted.

Timeouts / packet confirmation

There is no race condition between a packet timeout and packet confirmation, as the packet will either have passed the timeout height prior to receipt or not.

Man-in-the-middle attacks during handshakes

Verification of cross-chain state prevents man-in-the-middle attacks for both connection handshakes & channel handshakes since all information (source, destination client, channel, etc.) is known by the module which starts the handshake and confirmed prior to handshake completion.

Connection / channel closure with in-flight packets

If a connection or channel is closed while packets are in-flight, the packets can no longer be received on the destination chain and can be timed-out on the source chain.

Querying channels

Channels can be queried with queryChannel:

function queryChannel(connId: Identifier, chanId: Identifier): ChannelEnd | void {
    return provableStore.get(channelPath(connId, chanId))
}

Properties & Invariants

The unique combinations of channel & port identifiers are first-come-first-serve: once a pair has been allocated, only the modules owning the ports in question can send or receive on that channel.
Packets are delivered exactly once, assuming that the chains are live within the timeout window, and in case of timeout can be timed-out exactly once on the sending chain.
The channel handshake cannot be man-in-the-middle attacked by another module on either blockchain or another blockchain’s IBC handler.

Backwards Compatibility

Not applicable.

Forwards Compatibility

Data structures & encoding can be versioned at the connection or channel level. Channel logic is completely agnostic to packet data formats, which can be changed by the modules any way they like at any time.

Example Implementations

Implementation of ICS 04 in Go can be found in ibc-go repository.
Implementation of ICS 04 in Rust can be found in ibc-rs repository.

History

Jun 5, 2019 - Draft submitted Jul 4, 2019 - Modifications for unordered channels & acknowledgements Jul 16, 2019 - Alterations for multi-hop routing future compatibility Jul 29, 2019 - Revisions to handle timeouts after connection closure Aug 13, 2019 - Various edits Aug 25, 2019 - Cleanup Jan 10, 2022 - Add ORDERED_ALLOW_TIMEOUT channel type and appropriate logic Mar 28, 2023 - Add writeChannel function to write channel end after executing application callback Dec 4, 2024 - Remove the description for optimistic packet sending

Copyright

All content herein is licensed under Apache 2.0.

​概述

​动机

​定义

​期望属性

​效率

​恰好一次传递

​顺序性

​权限控制

​技术规范

​数据流可视化

​预备知识

​存储路径

​版本

​子协议

​标识符校验

​通道生命周期管理

打开握手

关闭握手

多跳工具函数

​数据包流转与处理

数据包的一生

发送数据包

​接收数据包

​写入确认

​处理确认