​
概述

本文档标准规定了 IBC 应用必须实现的接口和状态机逻辑，以便现有通道在初始通道握手完成后仍可升级其应用。

​
背景动机

随着新功能不断加入 IBC 应用，各条链可能希望在不放弃已有通道所积累的状态与网络效应的前提下，利用新的应用特性。所提出的升级协议允许应用对现有通道重新协商，以启用新特性，而无需创建新通道，从而在升级到新的应用逻辑时保留全部现有应用状态。

​
期望属性

  • 双方应用 MUST 就重新协商后的应用参数达成一致。
  • 两条链上的应用状态与逻辑 SHOULD 要么使用旧参数，要么使用新参数，但 MUST NOT 处于中间状态。例如，MUST NOT 出现一方应用运行 v2 逻辑，而其对手方仍在运行 v1 逻辑的情况。
  • 应用升级协议是原子的，即：
    • 要么升级失败，此时应用 MUST 回退到原始应用参数；
    • 要么升级成功，此时双方应用 MUST 采用新的应用参数，并且应用必须正确处理数据包数据。
  • 应用必须能够维护多个不同的受支持版本，使得某一个通道可以处于版本 v1，另一个通道可以处于版本 v2，并且应用能够根据对应通道的应用版本处理相应的通道状态与逻辑。
应用升级协议 MUST NOT 修改通道标识符。

​
技术规范

为了支持通道升级，应用必须实现以下接口： 
interface ModuleUpgradeCallbacks {
  onChanUpgradeInit: onChanUpgradeInit, // read-only
  onChanUpgradeTry: onChanUpgradeTry, // read-only
  onChanUpgradeAck: onChanUpgradeAck, // read-only
  onChanUpgradeOpen: onChanUpgradeOpen
}

​
OnChanUpgradeInit

onChanUpgradeInit 将验证升级参数是否有效，并执行任何自定义的 UpgradeInit 逻辑。 如果所选参数无效，它可以返回错误， 在这种情况下，升级握手将被中止。 该回调会接收新的升级参数。它可以执行必要检查，以确保自己能够支持新的通道参数。如果应用不支持从旧参数升级到新参数，则必须返回错误。 onChanUpgradeInit 可以返回一个修改后的版本，并将其存储在升级中。如果应用需要在版本字符串中存储某些元数据，作为其通道协商的一部分，就可能出现这种情况。 如果返回错误，则 core IBC 将中止握手。 onChanUpgradeInit MUST NOT 写入任何状态变更，因为这类操作只会在升级完成并确认双方都成功后才执行 
function onChanUpgradeInit(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proposedOrdering: ChannelOrder,
  proposedConnectionHops: [Identifier],
  proposedVersion: string) => (version: string, err: Error) {
    // defined by the module
} (version: string)

​
OnChanUpgradeTry

onChanUpgradeTry 将验证对手方为升级选择的参数。 如果应用不支持这些升级所选参数，则该回调必须返回错误以中止握手。 如果需要向版本字符串中添加一些元数据，try 回调可以返回一个修改后的版本。 core IBC 会将其存储为此次升级最终提议的版本。 onChanUpgradeTry MUST NOT 写入任何状态变更，因为这类操作只会在升级完成并确认双方都成功后才执行。 
function onChanUpgradeTry(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proposedOrdering: ChannelOrder,
  proposedConnectionHops: [Identifier],
  proposedVersion: string) => (version: string, err: Error) {
    // defined by the module
} (version: string)

​
OnChanUpgradeAck

如果对手方选择的版本字符串不受支持，onChanUpgradeAck 将返回错误。 如果该回调返回错误，core IBC 将中止握手。 onChanUpgradeAck MUST NOT 写入任何状态变更，因为这类操作只会在升级完成并确认双方都成功后才执行。 
function onChanUpgradeAck(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyVersion: string) => Error {
    // defined by the module
}

​
OnChanUpgradeOpen

onChanUpgradeOpen 会在升级完成后被调用，此时双方都已保证切换到新的通道参数。因此，应用现在可以执行任何必要的状态迁移，以开始支持按照新通道参数进行的数据包处理。 
function onChanUpgradeOpen(
  portIdentifier: Identifier,
  channelIdentifier: Identifier) {
    // defined by the module
}

​
Synopsis

This standard document specifies the interfaces and state machine logic that IBC applications must implement in order to enable existing channels to upgrade their applications after the initial channel handshake.

​
Motivation

As new features get added to IBC applications, chains may wish to take advantage of new application features without abandoning the accumulated state and network effect(s) of an already existing channel. The upgrade protocol proposed would allow applications to renegotiate an existing channel to take advantage of new features without having to create a new channel, thus preserving all existing application state while upgrading to new application logic.

​
Desired Properties

  • Both applications MUST agree to the renegotiated application parameters.
  • Application state and logic on both chains SHOULD either be using the old parameters or the new parameters, but MUST NOT be in an in-between state, e.g., it MUST NOT be possible for an application to run v2 logic, while its counterparty is still running v1 logic.
  • The application upgrade protocol is atomic, i.e.,
    • either it is unsuccessful and then the application MUST fall-back to the original application parameters;
    • or it is successful and then both applications MUST adopt the new application parameters and the applications must process packet data appropriately.
  • The application must be able to maintain several different supported versions such that one channel may be on version v1 and another channel may be on version v2 and the application can handle the channel state and logic accordingly depending on the application version for the respective channel.
The application upgrade protocol MUST NOT modify the channel identifiers.

​
Technical Specification

In order to support channel upgrades, the application must implement the following interface: 
interface ModuleUpgradeCallbacks {
  onChanUpgradeInit: onChanUpgradeInit, // read-only
  onChanUpgradeTry: onChanUpgradeTry, // read-only
  onChanUpgradeAck: onChanUpgradeAck, // read-only
  onChanUpgradeOpen: onChanUpgradeOpen
}

​
OnChanUpgradeInit

onChanUpgradeInit will verify that the upgrade parameters are valid and perform any custom UpgradeInit logic. It may return an error if the chosen parameters are invalid in which case the upgrade handshake is aborted. The callback is provided the new upgrade parameters. It may perform the necessary checks to ensure that it can support the new channel parameters. If upgrading the application from the previous parameters to the new parameters is not supported, it must return an error. onChanUpgradeInit may return a modified version to be stored in the upgrade. This may occur if the application needs to store some metadata in the version string as part of its channel negotiation. If an error is returned, then core IBC will abort the handshake. onChanUpgradeInit MUST NOT write any state changes as this will be done only once the upgrade is completed and confirmed to succeed on both sides 
function onChanUpgradeInit(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proposedOrdering: ChannelOrder,
  proposedConnectionHops: [Identifier],
  proposedVersion: string) => (version: string, err: Error) {
    // defined by the module
} (version: string)

​
OnChanUpgradeTry

onChanUpgradeTry will verify the upgrade-chosen parameters from the counterparty. If the upgrade-chosen parameters are unsupported by the application, the callback must return an error to abort the handshake. The try callback may return a modified version, in case it needs to add some metadata to the version string. This will be stored as the final proposed version of the upgrade by core IBC. onChanUpgradeTry MUST NOT write any state changes as this will be done only once the upgrade is completed and confirmed to succeed on both sides. 
function onChanUpgradeTry(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  proposedOrdering: ChannelOrder,
  proposedConnectionHops: [Identifier],
  proposedVersion: string) => (version: string, err: Error) {
    // defined by the module
} (version: string)

​
OnChanUpgradeAck

onChanUpgradeAck will error if the counterparty selected version string is unsupported. If an error is returned by the callback, core IBC will abort the handshake. onChanUpgradeAck MUST NOT write any state changes as this will be done only once the upgrade is completed and confirmed to succeed on both sides. 
function onChanUpgradeAck(
  portIdentifier: Identifier,
  channelIdentifier: Identifier,
  counterpartyVersion: string) => Error {
    // defined by the module
}

​
OnChanUpgradeOpen

onChanUpgradeOpen is called after the upgrade is complete and both sides are guaranteed to move to the new channel parameters. Thus, the application may now perform any state migrations necessary to start supporting packet processing according to the new channel parameters. 
function onChanUpgradeOpen(
  portIdentifier: Identifier,
  channelIdentifier: Identifier) {
    // defined by the module
}