IBC-Go v2 to v3 - Cosmos Docs

本文档旨在突出显示一些重要变更，这些变更可能需要比 CHANGELOG 中提供的更多信息。任何 ibc-go 用户必须执行的变更都应在此记录。基于本文档面向的四类潜在用户，内容分为四个部分：

链
IBC 应用
中继器
IBC 轻客户端

注意： ibc-go 遵循 Golang 语义化版本规范，因此在主版本发布时，所有 import 都必须更新版本号。

github.com/cosmos/ibc-go/v2 -> github.com/cosmos/ibc-go/v3

从 ibc-go v1 或 v2 升级时，不需要进行 genesis 迁移或原地迁移。

链

ICS20

transferkeeper.NewKeeper(...) 现在需要传入一个 ICS4Wrapper。除非 ICS 20 要连接到一个中间件应用，否则 ICS4Wrapper 应为 IBC Channel Keeper。

ICS27

ICS27 Interchain Accounts 已新增为 ibc-go 支持的 IBC 应用。更多信息请参阅 ICS27 文档。

升级提案

如果链将采用 ICS27，则必须在 app.go 中执行 upgrade handler 时设置相应参数：

app.UpgradeKeeper.SetUpgradeHandler("v3",
  func(ctx sdk.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
    / set the ICS27 consensus version so InitGenesis is not run
    fromVM[icatypes.ModuleName] = icamodule.ConsensusVersion()

    / create ICS27 Controller submodule params
    controllerParams := icacontrollertypes.Params{
    ControllerEnabled: true,
}

    / create ICS27 Host submodule params
    hostParams := icahosttypes.Params{
    HostEnabled: true,
    AllowMessages: []string{"/cosmos.bank.v1beta1.MsgSend", ...
},
}

    / initialize ICS27 module
    icamodule.InitModule(ctx, controllerParams, hostParams)

    ...

    return app.mm.RunMigrations(ctx, app.configurator, fromVM)
})

只有在链集成了这些子模块时，才需要设置 host 和 controller 子模块参数。例如，如果某条链选择不集成 controller 子模块，则可以向 InitModule 传入空参数。

为 ICS27 模块添加 `StoreUpgrades`

对于 ICS27，还必须为新的 ICS27 模块手动添加 store upgrades，然后在 app.go 中配置 store loader 以应用这些升级：

if upgradeInfo.Name == "v3" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) {
    storeUpgrades := store.StoreUpgrades{
    Added: []string{
    icacontrollertypes.StoreKey, icahosttypes.StoreKey
},
}

app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades))
}

这可以确保在迁移开始前，新模块的 store 已被添加到 multistore 中。只有在链集成了这些子模块时，才需要添加 host 和 controller 子模块 key。例如，如果某条链选择不集成 controller 子模块，则无需将 controller key 添加到 Added 字段中。

Genesis 迁移

如果链将采用 ICS27 且选择通过导出 genesis 进行升级，则必须在 genesis 迁移期间设置 ICS27 参数。所需的迁移代码可能如下：

controllerGenesisState := icatypes.DefaultControllerGenesis()
  / overwrite parameters as desired
  controllerGenesisState.Params = icacontrollertypes.Params{
    ControllerEnabled: true,
}
    hostGenesisState := icatypes.DefaultHostGenesis()
  / overwrite parameters as desired
  hostGenesisState.Params = icahosttypes.Params{
    HostEnabled: true,
    AllowMessages: []string{"/cosmos.bank.v1beta1.MsgSend", ...
},
}
    icaGenesisState := icatypes.NewGenesisState(controllerGenesisState, hostGenesisState)

  / set new ics27 genesis state
  appState[icatypes.ModuleName] = clientCtx.Codec.MustMarshalJSON(icaGenesisState)

Ante decorator

AnteDecorator 结构体中 channelkeeper.Keeper 类型的字段已被替换为 *keeper.Keeper 类型的字段：

type AnteDecorator struct {
- k channelkeeper.Keeper
+ k *keeper.Keeper
}

- func NewAnteDecorator(k channelkeeper.Keeper) AnteDecorator {
+ func NewAnteDecorator(k *keeper.Keeper) AnteDecorator {
  return AnteDecorator{k: k}
}

IBC 应用

`OnChanOpenTry` 必须返回协商后的应用版本

OnChanOpenTry 应用回调已被修改。返回签名现在包含应用版本。 IBC 应用必须在 OnChanOpenTry 中使用对端版本完成应用版本协商。随后，必须在 OnChanOpenTry 中将协商后的应用版本返回给 core IBC。 Core IBC 会将该版本设置到 TRYOPEN 通道中。

`OnChanOpenAck` 将新增 `counterpartyChannelID` 参数

OnChanOpenAck 应用回调已被修改。参数中现在包含对端 channel id。

`IBCModule` 接口中移除了 `NegotiateAppVersion`

此前，这部分逻辑由 NegotiateAppVersion 函数处理。中继器会在调用 ChanOpenTry 前查询该函数。随后，应用还需要验证传入的版本是否正确。现在，应用会在通道握手期间完成这一版本协商，因此不再需要 NegotiateAppVersion。

在应用回调之前不会设置通道状态

Core IBC 中的通道握手逻辑已经过重组。在执行应用回调之前，通道状态不会先写入状态存储。应用必须仅依赖传入的通道参数，而不是通过 channel keeper 查询通道状态。

IBC 应用回调已从 `AppModule` 移动到 `IBCModule`

此前，IBC 模块回调属于 AppModule 类型的一部分。推荐做法是创建一个 IBCModule 类型，并将 IBC 模块回调从 AppModule 移动到单独文件 ibc_module.go 中的 IBCModule。通过采用上述格式，此版本破坏了 mock module 的 Go API。 IBC 模块回调已从 mock module 的 AppModule 移动到一个新的 IBCModule 类型中。作为此版本的一部分，mock module 现在支持 middleware 测试。更多信息请参阅 README。请参考 mock 和 transfer 模块作为示例。此外，simapp 展示了一个示例，说明现在应如何优先将 IBCModule 类型而非 AppModule 添加到 IBC router 中。

IBC 测试包

现在创建 TestChain 时，chainID 的起始索引为 1。任何对 GetChainID(0) 的调用现在都会失败。请将所有对 GetChainID 的调用索引加 1。

中继器

AppVersion gRPC 已被移除。 MsgChanOpenTry 中的 version 字符串已被弃用，且会被 core IBC 忽略。中继器不再需要在 ChanOpenTry 步骤中决定要使用的版本。 IBC 应用会使用对端版本来确定正确版本。

IBC 轻客户端

GetProofSpecs 函数已从 ClientState 接口中移除。此前 core IBC 并未使用该函数。不使用该函数的轻客户端可以将其删除。

This document is intended to highlight significant changes which may require more information than presented in the CHANGELOG. Any changes that must be done by a user of ibc-go should be documented here. There are four sections based on the four potential user groups of this document:

Chains
IBC Apps
Relayers
IBC Light Clients

Note: ibc-go supports golang semantic versioning and therefore all imports must be updated to bump the version number on major releases.

github.com/cosmos/ibc-go/v2 -> github.com/cosmos/ibc-go/v3

No genesis or in-place migrations are required when upgrading from v1 or v2 of ibc-go.

Chains

ICS20

The transferkeeper.NewKeeper(...) now takes in an ICS4Wrapper. The ICS4Wrapper should be the IBC Channel Keeper unless ICS 20 is being connected to a middleware application.

ICS27

ICS27 Interchain Accounts has been added as a supported IBC application of ibc-go. Please see the ICS27 documentation for more information.

Upgrade Proposal

If the chain will adopt ICS27, it must set the appropriate params during the execution of the upgrade handler in app.go:

app.UpgradeKeeper.SetUpgradeHandler("v3",
  func(ctx sdk.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
    / set the ICS27 consensus version so InitGenesis is not run
    fromVM[icatypes.ModuleName] = icamodule.ConsensusVersion()

    / create ICS27 Controller submodule params
    controllerParams := icacontrollertypes.Params{
    ControllerEnabled: true,
}

    / create ICS27 Host submodule params
    hostParams := icahosttypes.Params{
    HostEnabled: true,
    AllowMessages: []string{"/cosmos.bank.v1beta1.MsgSend", ...
},
}

    / initialize ICS27 module
    icamodule.InitModule(ctx, controllerParams, hostParams)

    ...

    return app.mm.RunMigrations(ctx, app.configurator, fromVM)
})

The host and controller submodule params only need to be set if the chain integrates those submodules. For example, if a chain chooses not to integrate a controller submodule, it may pass empty params into InitModule.

Add `StoreUpgrades` for ICS27 module

For ICS27 it is also necessary to manually add store upgrades for the new ICS27 module and then configure the store loader to apply those upgrades in app.go:

if upgradeInfo.Name == "v3" && !app.UpgradeKeeper.IsSkipHeight(upgradeInfo.Height) {
    storeUpgrades := store.StoreUpgrades{
    Added: []string{
    icacontrollertypes.StoreKey, icahosttypes.StoreKey
},
}

app.SetStoreLoader(upgradetypes.UpgradeStoreLoader(upgradeInfo.Height, &storeUpgrades))
}

This ensures that the new module’s stores are added to the multistore before the migrations begin. The host and controller submodule keys only need to be added if the chain integrates those submodules. For example, if a chain chooses not to integrate a controller submodule, it does not need to add the controller key to the Added field.

Genesis migrations

If the chain will adopt ICS27 and chooses to upgrade via a genesis export, then the ICS27 parameters must be set during genesis migration. The migration code required may look like:

controllerGenesisState := icatypes.DefaultControllerGenesis()
  / overwrite parameters as desired
  controllerGenesisState.Params = icacontrollertypes.Params{
    ControllerEnabled: true,
}
    hostGenesisState := icatypes.DefaultHostGenesis()
  / overwrite parameters as desired
  hostGenesisState.Params = icahosttypes.Params{
    HostEnabled: true,
    AllowMessages: []string{"/cosmos.bank.v1beta1.MsgSend", ...
},
}
    icaGenesisState := icatypes.NewGenesisState(controllerGenesisState, hostGenesisState)

  / set new ics27 genesis state
  appState[icatypes.ModuleName] = clientCtx.Codec.MustMarshalJSON(icaGenesisState)

Ante decorator

The field of type channelkeeper.Keeper in the AnteDecorator structure has been replaced with a field of type *keeper.Keeper:

type AnteDecorator struct {
- k channelkeeper.Keeper
+ k *keeper.Keeper
}

- func NewAnteDecorator(k channelkeeper.Keeper) AnteDecorator {
+ func NewAnteDecorator(k *keeper.Keeper) AnteDecorator {
  return AnteDecorator{k: k}
}

IBC Apps

`OnChanOpenTry` must return negotiated application version

The OnChanOpenTry application callback has been modified. The return signature now includes the application version. IBC applications must perform application version negotiation in OnChanOpenTry using the counterparty version. The negotiated application version then must be returned in OnChanOpenTry to core IBC. Core IBC will set this version in the TRYOPEN channel.

`OnChanOpenAck` will take additional `counterpartyChannelID` argument

The OnChanOpenAck application callback has been modified. The arguments now include the counterparty channel id.

`NegotiateAppVersion` removed from `IBCModule` interface

Previously this logic was handled by the NegotiateAppVersion function. Relayers would query this function before calling ChanOpenTry. Applications would then need to verify that the passed in version was correct. Now applications will perform this version negotiation during the channel handshake, thus removing the need for NegotiateAppVersion.

Channel state will not be set before application callback

The channel handshake logic has been reorganized within core IBC. Channel state will not be set in state after the application callback is performed. Applications must rely only on the passed in channel parameters instead of querying the channel keeper for channel state.

IBC application callbacks moved from `AppModule` to `IBCModule`

Previously, IBC module callbacks were apart of the AppModule type. The recommended approach is to create an IBCModule type and move the IBC module callbacks from AppModule to IBCModule in a separate file ibc_module.go. The mock module go API has been broken in this release by applying the above format. The IBC module callbacks have been moved from the mock modules AppModule into a new type IBCModule. As apart of this release, the mock module now supports middleware testing. Please see the README for more information. Please review the mock and transfer modules as examples. Additionally, simapp provides an example of how IBCModule types should now be added to the IBC router in favour of AppModule.

IBC testing package

TestChains are now created with chainID’s beginning from an index of 1. Any calls to GetChainID(0) will now fail. Please increment all calls to GetChainID by 1.

Relayers

AppVersion gRPC has been removed. The version string in MsgChanOpenTry has been deprecated and will be ignored by core IBC. Relayers no longer need to determine the version to use on the ChanOpenTry step. IBC applications will determine the correct version using the counterparty version.

IBC Light Clients

The GetProofSpecs function has been removed from the ClientState interface. This function was previously unused by core IBC. Light clients which don’t use this function may remove it.

​链

​ICS20

​ICS27

​升级提案

​为 ICS27 模块添加 StoreUpgrades

​Genesis 迁移

​Ante decorator

​IBC 应用

​OnChanOpenTry 必须返回协商后的应用版本

​OnChanOpenAck 将新增 counterpartyChannelID 参数

​IBCModule 接口中移除了 NegotiateAppVersion

​在应用回调之前不会设置通道状态

​IBC 应用回调已从 AppModule 移动到 IBCModule

​IBC 测试包

​中继器

​IBC 轻客户端

​Chains

​ICS20

​ICS27

​Upgrade Proposal

​Add StoreUpgrades for ICS27 module

​Genesis migrations

​Ante decorator

​IBC Apps

​OnChanOpenTry must return negotiated application version

​OnChanOpenAck will take additional counterpartyChannelID argument

​NegotiateAppVersion removed from IBCModule interface

​Channel state will not be set before application callback

​IBC application callbacks moved from AppModule to IBCModule

​IBC testing package

​Relayers

​IBC Light Clients

链

ICS20

ICS27

升级提案

为 ICS27 模块添加 `StoreUpgrades`

Genesis 迁移

Ante decorator

IBC 应用

`OnChanOpenTry` 必须返回协商后的应用版本

`OnChanOpenAck` 将新增 `counterpartyChannelID` 参数

`IBCModule` 接口中移除了 `NegotiateAppVersion`

在应用回调之前不会设置通道状态

IBC 应用回调已从 `AppModule` 移动到 `IBCModule`

IBC 测试包

中继器

IBC 轻客户端

Chains

ICS20

ICS27

Upgrade Proposal

Add `StoreUpgrades` for ICS27 module

Genesis migrations

Ante decorator

IBC Apps

`OnChanOpenTry` must return negotiated application version

`OnChanOpenAck` will take additional `counterpartyChannelID` argument

`NegotiateAppVersion` removed from `IBCModule` interface

Channel state will not be set before application callback

IBC application callbacks moved from `AppModule` to `IBCModule`

IBC testing package

Relayers

IBC Light Clients