IBC-Go v7 to v8 - Cosmos Docs

本指南提供了迁移到 ibc-go v8.0.0 版本的说明。本文档根据四类潜在用户群体分为四个部分：

从 v7 迁移到 v8

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

链

IBC keeper 中 PortKeeper 字段的类型已更改为 *portkeeper.Keeper：

/ Keeper defines each ICS keeper for IBC
type Keeper struct {
  / implements gRPC QueryServer interface
  types.QueryServer

  cdc codec.BinaryCodec

  ClientKeeper     clientkeeper.Keeper
  ConnectionKeeper connectionkeeper.Keeper
  ChannelKeeper    channelkeeper.Keeper
- PortKeeper       portkeeper.Keeper
+ PortKeeper       *portkeeper.Keeper
  Router           *porttypes.Router

  authority string
}

app.go 中所需的修改请参见这个 PR。 transfer 模块的 NewGenesisState 函数新增了一个 sdk.Coins 类型的额外参数 totalEscrowed。该参数指定模块托管账户中代币的总量。

Cosmos SDK v0.50 升级

ibc-go v8.0.0 版本已升级到 Cosmos SDK v0.50。请按照 Cosmos SDK v0.50 升级指南处理其 API 的破坏性变更。

权限标识

以下 keeper 的 NewKeeper 函数现在需要传入一个权限标识（例如地址）：

你必须将 authority 传给 ica/host keeper（由 #3520 实现）。参见 diff：

/ app.go

/ ICA Host keeper
app.ICAHostKeeper = icahostkeeper.NewKeeper(
  appCodec, keys[icahosttypes.StoreKey], app.GetSubspace(icahosttypes.SubModuleName),
  app.IBCFeeKeeper, / use ics29 fee as ics4Wrapper in middleware stack
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  app.AccountKeeper, scopedICAHostKeeper, app.MsgServiceRouter(),
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

你必须将 authority 传给 ica/controller keeper（由 #3590 实现）。参见 diff：

/ app.go

/ ICA Controller keeper
app.ICAControllerKeeper = icacontrollerkeeper.NewKeeper(
  appCodec, keys[icacontrollertypes.StoreKey], app.GetSubspace(icacontrollertypes.SubModuleName),
  app.IBCFeeKeeper, / use ics29 fee as ics4Wrapper in middleware stack
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  scopedICAControllerKeeper, app.MsgServiceRouter(),
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

你必须将 authority 传给 ibctransfer keeper（由 #3553 实现）。参见 diff：

/ app.go

/ Create Transfer Keeper and pass IBCFeeKeeper as expected Channel and PortKeeper
/ since fee middleware will wrap the IBCKeeper for underlying application.
app.TransferKeeper = ibctransferkeeper.NewKeeper(
  appCodec, keys[ibctransfertypes.StoreKey], app.GetSubspace(ibctransfertypes.ModuleName),
  app.IBCFeeKeeper, / ISC4 Wrapper: fee IBC middleware
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  app.AccountKeeper, app.BankKeeper, scopedTransferKeeper,
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

你应当将 authority 传给 IBC keeper（由 #3640 和 #3650 实现）。参见 diff：

/ app.go

/ IBC Keepers
app.IBCKeeper = ibckeeper.NewKeeper(
  appCodec, 
  keys[ibcexported.StoreKey],
  app.GetSubspace(ibcexported.ModuleName),
  app.StakingKeeper,
  app.UpgradeKeeper,
  scopedIBCKeeper,
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

该权限标识决定了允许执行某些消息（例如 MsgUpdateParams）的交易签名者。

测试包

SetupWithGenesisAccounts 函数已被移除。
新增了 RelayPacketWithResults 函数。该函数会返回数据包接收交易的结果、接收链上写入的确认，以及在中继步骤失败或任一链上不存在数据包承诺时返回的错误。

Params 迁移

以下子模块现在自行管理 Params：

ica/controller #3590
ica/host #3520
ibc/connection #3650
ibc/client #3640
ibc/transfer #3553

每个模块都对应一个 MsgUpdateParams 消息，其中包含一个 Params，可以完整指定以更新该模块的 Params。为了能够成功从 x/params 迁移到新的自包含方式，仍然必须在 app.go 中初始化旧版 params subspace。可参考这里。对于不依赖从 x/params 迁移参数的新链，每个模块都新增了一个预期接口。这使链开发者可以在 NewKeeper 函数中将 nil 作为 legacySubspace 参数传入。

Governance V1 迁移

提案已迁移为 gov v1 消息（见 #4620）。提案 ClientUpdateProposal 已弃用，应改用 MsgRecoverClient。同样，提案 UpgradeProposal 已弃用，应改用 MsgIBCSoftwareUpgrade。这两个提案都将在下一个主版本中移除。只有当签名者是在实例化 IBC keeper 时指定的权限标识时，MsgRecoverClient 和 MsgIBCSoftwareUpgrade 才允许执行。因此请确保为 IBC keeper 提供了正确的权限标识。从 BasicModuleManager 中移除 UpgradeProposalHandler 和 UpdateClientProposalHandler：

app.BasicModuleManager = module.NewBasicManagerFromManager(
  app.ModuleManager,
  map[string]module.AppModuleBasic{
    genutiltypes.ModuleName: genutil.NewAppModuleBasic(genutiltypes.DefaultMessageValidator),
    govtypes.ModuleName: gov.NewAppModuleBasic(
      []govclient.ProposalHandler{
      paramsclient.ProposalHandler,
-     ibcclientclient.UpdateClientProposalHandler,
-     ibcclientclient.UpgradeProposalHandler,
    },
  ),
})

v8 将支持处理仍在进行中的旧版 recover client 提案（即 ClientUpdateProposal），但链在此之后应仅使用 MsgRecoverClient，以避免升级到 v9 时正在进行中的客户端恢复失败。更多信息请参见这个 issue。请注意，ibc-go 提供了测试 ibc-go 升级的能力：

仓库中的所有 e2e 测试都可以使用自定义 Docker 链镜像运行。
提供了一个可导入工作流，可供其他任何仓库用来测试链升级。

Transfer 迁移

transfer 模块中配置了一个自动迁移处理器，用于为 transfer 模块铸造的所有 voucher 的 IBC denomination 设置代币面额元数据。

IBC 应用

ICS20 - Transfer

IsBound 函数已重命名为 hasCapability，并改为不导出。

ICS27 - 跨链账户

SerializeCosmosTx 和 DeserializeCosmosTx 函数现在接收一个额外的 string 类型参数 encoding，用于指定交易消息序列化时采用的格式。支持 protobuf 和 proto3 JSON 两种格式。
controller 子模块的 IsBound 函数已重命名为 hasCapability，并改为不导出。
host 子模块的 IsBound 函数已重命名为 hasCapability，并改为不导出。

中继器

MsgChannelOpenInitResponse、MsgChannelOpenTryResponse、MsgTransferResponse、MsgRegisterInterchainAccountResponse 和 MsgSendTxResponse 中的 Getter 函数已被移除。现在可以直接访问这些字段。
channeltypes.EventTypeTimeoutPacketOnClose（其中 channeltypes 是 "github.com/cosmos/ibc-go/v8/modules/core/04-channel" 的导入别名）已被移除，因为核心 IBC 不会发出任何使用该键的事件。
键为 connectiontypes.EventTypeConnectionOpenInit 的事件（其中 connectiontypes 是 "github.com/cosmos/ibc-go/v8/modules/core/03-connection/types" 的导入别名）中，键为 counterparty_connection_id 的属性已被移除；键为 channeltypes.EventTypeChannelOpenInit 的事件（其中 channeltypes 是 "github.com/cosmos/ibc-go/v8/modules/core/04-channel" 的导入别名）中，键为 counterparty_channel_id 的属性也已被移除，因为这两个值（counterparty connection ID 和 counterparty channel ID）在 ConnectionOpenInit 和 ChannelOpenInit 中分别为空。
作为迁移到治理 V1 消息的一部分，事件已进行如下变更：

/ IBC client events vars
var (
  EventTypeCreateClient          = "create_client"
  EventTypeUpdateClient          = "update_client"
  EventTypeUpgradeClient         = "upgrade_client"
  EventTypeSubmitMisbehaviour    = "client_misbehaviour"
- EventTypeUpdateClientProposal  = "update_client_proposal"
- EventTypeUpgradeClientProposal = "upgrade_client_proposal"
+ EventTypeRecoverClient              = "recover_client"
+ EventTypeScheduleIBCSoftwareUpgrade = "schedule_ibc_software_upgrade"
  EventTypeUpgradeChain               = "upgrade_chain"
)

IBC 轻客户端

MerklePath 类型的 Pretty 和 String 函数已被移除。

This guide provides instructions for migrating to version v8.0.0 of ibc-go. There are four sections based on the four potential user groups of this document:

Migrating from v7 to v8

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

Chains

The type of the PortKeeper field of the IBC keeper have been changed to *portkeeper.Keeper:

/ Keeper defines each ICS keeper for IBC
type Keeper struct {
  / implements gRPC QueryServer interface
  types.QueryServer

  cdc codec.BinaryCodec

  ClientKeeper     clientkeeper.Keeper
  ConnectionKeeper connectionkeeper.Keeper
  ChannelKeeper    channelkeeper.Keeper
- PortKeeper       portkeeper.Keeper
+ PortKeeper       *portkeeper.Keeper
  Router           *porttypes.Router

  authority string
}

See this PR for the changes required in app.go. An extra parameter totalEscrowed of type sdk.Coins has been added to transfer module’s NewGenesisState function. This parameter specifies the total amount of tokens that are in the module’s escrow accounts.

Cosmos SDK v0.50 upgrade

Version v8.0.0 of ibc-go upgrades to Cosmos SDK v0.50. Please follow the Cosmos SDK v0.50 upgrading guide to account for its API breaking changes.

Authority

An authority identifier (e.g. an address) needs to be passed in the NewKeeper functions of the following keepers:

You must pass the authority to the ica/host keeper (implemented in #3520). See diff:

/ app.go

/ ICA Host keeper
app.ICAHostKeeper = icahostkeeper.NewKeeper(
  appCodec, keys[icahosttypes.StoreKey], app.GetSubspace(icahosttypes.SubModuleName),
  app.IBCFeeKeeper, / use ics29 fee as ics4Wrapper in middleware stack
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  app.AccountKeeper, scopedICAHostKeeper, app.MsgServiceRouter(),
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

You must pass the authority to the ica/controller keeper (implemented in #3590). See diff:

/ app.go

/ ICA Controller keeper
app.ICAControllerKeeper = icacontrollerkeeper.NewKeeper(
  appCodec, keys[icacontrollertypes.StoreKey], app.GetSubspace(icacontrollertypes.SubModuleName),
  app.IBCFeeKeeper, / use ics29 fee as ics4Wrapper in middleware stack
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  scopedICAControllerKeeper, app.MsgServiceRouter(),
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

You must pass the authority to the ibctransfer keeper (implemented in #3553). See diff:

/ app.go

/ Create Transfer Keeper and pass IBCFeeKeeper as expected Channel and PortKeeper
/ since fee middleware will wrap the IBCKeeper for underlying application.
app.TransferKeeper = ibctransferkeeper.NewKeeper(
  appCodec, keys[ibctransfertypes.StoreKey], app.GetSubspace(ibctransfertypes.ModuleName),
  app.IBCFeeKeeper, / ISC4 Wrapper: fee IBC middleware
  app.IBCKeeper.ChannelKeeper, &app.IBCKeeper.PortKeeper,
  app.AccountKeeper, app.BankKeeper, scopedTransferKeeper,
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

You should pass the authority to the IBC keeper (implemented in #3640 and #3650). See diff:

/ app.go

/ IBC Keepers
app.IBCKeeper = ibckeeper.NewKeeper(
  appCodec, 
  keys[ibcexported.StoreKey],
  app.GetSubspace(ibcexported.ModuleName),
  app.StakingKeeper,
  app.UpgradeKeeper,
  scopedIBCKeeper,
+ authtypes.NewModuleAddress(govtypes.ModuleName).String(),
)

The authority determines the transaction signer allowed to execute certain messages (e.g. MsgUpdateParams).

Testing package

The function SetupWithGenesisAccounts has been removed.
The function RelayPacketWithResults has been added. This function returns the result of the packet receive transaction, the acknowledgement written on the receiving chain, an error if a relay step fails or the packet commitment does not exist on either chain.

Params migration

Params are now self managed in the following submodules:

ica/controller #3590
ica/host #3520
ibc/connection #3650
ibc/client #3640
ibc/transfer #3553

Each module has a corresponding MsgUpdateParams message with a Params which can be specified in full to update the modules’ Params. Legacy params subspaces must still be initialised in app.go in order to successfully migrate from `x/params“ to the new self-contained approach. See reference this for reference. For new chains which do not rely on migration of parameters from x/params, an expected interface has been added for each module. This allows chain developers to provide nil as the legacySubspace argument to NewKeeper functions.

Governance V1 migration

Proposals have been migrated to gov v1 messages (see #4620). The proposal ClientUpdateProposal has been deprecated and MsgRecoverClient should be used instead. Likewise, the proposal UpgradeProposal has been deprecated and MsgIBCSoftwareUpgrade should be used instead. Both proposals will be removed in the next major release. MsgRecoverClient and MsgIBCSoftwareUpgrade will only be allowed to be executed if the signer is the authority designated at the time of instantiating the IBC keeper. So please make sure that the correct authority is provided to the IBC keeper. Remove the UpgradeProposalHandler and UpdateClientProposalHandler from the BasicModuleManager:

app.BasicModuleManager = module.NewBasicManagerFromManager(
  app.ModuleManager,
  map[string]module.AppModuleBasic{
    genutiltypes.ModuleName: genutil.NewAppModuleBasic(genutiltypes.DefaultMessageValidator),
    govtypes.ModuleName: gov.NewAppModuleBasic(
      []govclient.ProposalHandler{
      paramsclient.ProposalHandler,
-     ibcclientclient.UpdateClientProposalHandler,
-     ibcclientclient.UpgradeProposalHandler,
    },
  ),
})

Support for in-flight legacy recover client proposals (i.e. ClientUpdateProposal) will be made for v8, but chains should use MsgRecoverClient only afterwards to avoid in-flight client recovery failing when upgrading to v9. See this issue for more information. Please note that ibc-go offers facilities to test an ibc-go upgrade:

All e2e tests of the repository can be run with custom Docker chain images.
An importable workflow that can be used from any other repository to test chain upgrades.

Transfer migration

An automatic migration handler is configured in the transfer module to set the denomination metadata for the IBC denominations of all vouchers minted by the transfer module.

IBC Apps

ICS20 - Transfer

The function IsBound has been renamed to hasCapability and made unexported.

ICS27 - Interchain Accounts

Functions SerializeCosmosTx and DeserializeCosmosTx now accept an extra parameter encoding of type string that specifies the format in which the transaction messages are marshaled. Both protobuf and proto3 JSON formats are supported.
The function IsBound of controller submodule has been renamed to hasCapability and made unexported.
The function IsBound of host submodule has been renamed to hasCapability and made unexported.

Relayers

Getter functions in MsgChannelOpenInitResponse, MsgChannelOpenTryResponse, MsgTransferResponse, MsgRegisterInterchainAccountResponse and MsgSendTxResponse have been removed. The fields can be accessed directly.
channeltypes.EventTypeTimeoutPacketOnClose (where channeltypes is an import alias for "github.com/cosmos/ibc-go/v8/modules/core/04-channel") has been removed, since core IBC does not emit any event with this key.
Attribute with key counterparty_connection_id has been removed from event with key connectiontypes.EventTypeConnectionOpenInit (where connectiontypes is an import alias for "github.com/cosmos/ibc-go/v8/modules/core/03-connection/types") and attribute with key counterparty_channel_id has been removed from event with key channeltypes.EventTypeChannelOpenInit (where channeltypes is an import alias for "github.com/cosmos/ibc-go/v8/modules/core/04-channel") since both (counterparty connection ID and counterparty channel ID) are empty on ConnectionOpenInit and ChannelOpenInit respectively.
As part of the migration to governance V1 messages the following changes in events have been made:

/ IBC client events vars
var (
  EventTypeCreateClient          = "create_client"
  EventTypeUpdateClient          = "update_client"
  EventTypeUpgradeClient         = "upgrade_client"
  EventTypeSubmitMisbehaviour    = "client_misbehaviour"
- EventTypeUpdateClientProposal  = "update_client_proposal"
- EventTypeUpgradeClientProposal = "upgrade_client_proposal"
+ EventTypeRecoverClient              = "recover_client"
+ EventTypeScheduleIBCSoftwareUpgrade = "schedule_ibc_software_upgrade"
  EventTypeUpgradeChain               = "upgrade_chain"
)

IBC Light Clients

Functions Pretty and String of type MerklePath have been removed.

​链

​Cosmos SDK v0.50 升级

​权限标识

​测试包

​Params 迁移

​Governance V1 迁移

​Transfer 迁移

​IBC 应用

​ICS20 - Transfer

​ICS27 - 跨链账户

​中继器

​IBC 轻客户端

​Chains

​Cosmos SDK v0.50 upgrade

​Authority

​Testing package

​Params migration

​Governance V1 migration

​Transfer migration

​IBC Apps

​ICS20 - Transfer

​ICS27 - Interchain Accounts

​Relayers

​IBC Light Clients

链

Cosmos SDK v0.50 升级

权限标识

测试包

Params 迁移

Governance V1 迁移

Transfer 迁移

IBC 应用

ICS20 - Transfer

ICS27 - 跨链账户

中继器

IBC 轻客户端

Chains

Cosmos SDK v0.50 upgrade

Authority

Testing package

Params migration

Governance V1 migration

Transfer migration

IBC Apps

ICS20 - Transfer

ICS27 - Interchain Accounts

Relayers

IBC Light Clients