CHANGELOG 中提供的更多信息的重要变更。
任何需要由 ibc-go 用户执行的变更,都应记录在这里。
根据本文档的四类潜在用户群体,内容分为四个部分:
- 链
- IBC 应用
- Relayer
- IBC 轻客户端
链
ibc-go/v6 版本为 27-interchain-accounts 引入了一组新的迁移。ICS27 通道能力的所有权将从 ICS27 认证模块转移,并在后续由 ICS27 controller 子模块持有。
对于包含使用 ICS27 controller 子模块的自定义认证模块的链,这要求在链升级处理器中加入一个迁移函数。随后会自动运行后续迁移处理器,以确认 ICS27 通道能力的所有权已成功转移。
对于不包含使用 ICS27 controller 子模块的自定义认证模块的链,不需要执行此迁移。
此迁移为新增 ICS27 controller 子模块 MsgServer 提供支持,它为集成现有认证形式(如 Cosmos SDK 提供的 x/gov 和 x/group)提供了标准化方式。
更多信息请参阅 ICS27 controller 子模块文档。
升级提案
请参考 PR #2383 以集成 ICS27 通道能力迁移逻辑,或按照以下步骤进行:- 将升级迁移逻辑添加到链发行版中。例如,可以将其维护在
app/upgrades/v6包下。
- 在
app.go中设置升级处理器。moduleName参数指的是该认证模块的ScopedKeeper名称。这个名称是在app.go中通过x/capabilitykeeper 的ScopeToModule(moduleName string)方法实例化时提供的。这里可以查看simapp中的示例。
IBC 应用
ICS27 - 跨链账户
Controller API
在早期版本的 ibc-go 中,集成 ICS27 跨链账户 controller 功能的链开发者需要创建一个自定义的Base Application,也就是所谓的认证模块,参见文档中的 构建认证模块 一节。
这个 Base Application 旨在与 ICS27 controller 子模块的 Keeper 组合使用,并根据链的具体使用场景支持多种消息认证形式。
在 ibc-go v6 之前,controller 子模块仅暴露以下两个函数(下文称为旧版 API):
不过,这些函数现已被弃用,取而代之的是新的 controller 子模块 MsgServer,并将在后续版本中移除。
这两套 API 在 ibc-go v6 中仍然可用并保持向后兼容,但现在建议这些 API 的使用者遵循 Cosmos SDK ADR 031 和 ADR 033 中描述的消息传递范式。这一能力由 Cosmos SDK 的 MsgServiceRouter 提供支持,因此创建自定义应用逻辑的链开发者现在可以在其模块中省略 ICS27 controller 子模块的 Keeper,改为依赖消息路由。
根据使用场景,自定义认证模块的开发者会面临以下三种情况之一:
我的认证模块需要访问 IBC 数据包回调
希望消费 IBC 数据包回调并在收到数据包确认后作出响应的应用开发者,必须继续使用 controller 子模块的旧版 API。不过,认证模块将不再需要 ScopedKeeper,因为通道能力将由 controller 子模块认领。例如,假设有一个跨链账户认证模块 keeper ICAAuthKeeper,则该认证模块的 ScopedKeeper(scopedICAAuthKeeper)不再需要,可以从 keeper 构造函数的参数列表中移除,如下所示:
ScopedKeeper 名称。因此,在迁移运行完成之前,不能将认证模块的 ScopedKeeper 从链代码中彻底移除。
未来,使用旧版 API 来访问数据包回调的方式将被 IBC Actor Callbacks 取代(更多细节见 ADR 008),届时也可以通过 MsgServiceRouter 访问这些回调。
我的认证模块不需要访问 IBC 数据包回调
认证模块可以从旧版 API 迁移出去,改为与 MsgServiceRouter 组合使用,这样认证模块就可以将消息传递给 controller 子模块的 MsgServer,以注册跨链账户并向跨链账户发送数据包。例如,假设有一个跨链账户认证模块 keeper ICAAuthKeeper,则 ICS27 controller 子模块 keeper(ICAControllerKeeper)和认证模块 scoped keeper(scopedICAAuthKeeper)都不再需要,可以替换为 MsgServiceRouter,如下所示:
MsgServer,而不是使用旧版 API。例如,注册一个跨链账户:
controllertypes 是对 "github.com/cosmos/ibc-go/v6/modules/apps/27-interchain-accounts/controller/types" 的导入别名。
此外,在这种使用场景下,认证模块也不再需要实现 IBCModule 接口。
我不再需要自定义认证模块
如果你的认证模块相比 ibc-go v6 中新增的默认认证模块(即 MsgServer)没有任何额外功能,或者你可以使用通用认证模块,例如 Cosmos SDK(v0.46 及之后版本)中的 x/auth、x/gov 或 x/group 模块,那么你可以完全移除自己的认证模块,改为使用 MsgServer 的 gRPC 端点,或使用 ibc-go v6 中新增的 CLI。
请记住,上文 升级提案 一节中描述的通道能力迁移仍然需要认证模块的 ScopedKeeper 名称。
Host 参数
ICS27 host 子模块的默认参数已更新,加入了AllowAllHostMsgs 通配符 *。
这使得可以执行宿主链 InterfaceRegistry 中为 ICS27 注册的任意 sdk.Msg 类型。
API 破坏性变更
SerializeCosmosTx 现在接收 []proto.Message,而不是 []sdk.Message。这使得无需满足 sdk.Msg 接口也能序列化 proto 消息。
27-interchain-accounts 的 genesis 类型已移动到独立包中:modules/apps/27-interchain-accounts/genesis/types。
这一变更为新增 ICS27 controller 子模块 MsgServer 提供支持,并避免循环导入。对于集成 27-interchain-accounts 的链开发者来说,这项变更带来的影响应当很小。
modules/apps/27-interchain-accounts/host/keeper 中的 ICS27 host 子模块 NewKeeper 函数现在新增了一个 ICS4Wrapper 类型的参数。
这使得 host 子模块能够在通道重新打开握手的场景下正确解包通道版本。
ICS29 - NewKeeper API 变更
ICS29 的 NewKeeper 函数已更新,移除了未使用的 paramSpace 参数。
ICS20 - SendTransfer 不再导出
ICS20 的 SendTransfer 函数已被移除。现在应通过 MsgTransfer 发起 IBC 转账,并路由到 ICS20 的 MsgServer。
示例如下:
ICS04 - SendPacket API 变更
SendPacket API 已简化:
SendPacket 将返回数据包序列号。
IBC 测试包
SendPacket API 已简化:
SendPacket 将返回数据包序列号。
Relayers
- 此版本没有相关变更。
IBC Light Clients
- 此版本没有相关变更。
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
Chains
Theibc-go/v6 release introduces a new set of migrations for 27-interchain-accounts. Ownership of ICS27 channel capabilities is transferred from ICS27 authentication modules and will now reside with the ICS27 controller submodule moving forward.
For chains which contain a custom authentication module using the ICS27 controller submodule this requires a migration function to be included in the chain upgrade handler. A subsequent migration handler is run automatically, asserting the ownership of ICS27 channel capabilities has been transferred successfully.
This migration is not required for chains which do not contain a custom authentication module using the ICS27 controller submodule.
This migration facilitates the addition of the ICS27 controller submodule MsgServer which provides a standardised approach to integrating existing forms of authentication such as x/gov and x/group provided by the Cosmos SDK.
For more information please refer to the ICS27 controller submodule documentation.
Upgrade proposal
Please refer to PR #2383 for integrating the ICS27 channel capability migration logic or follow the steps outlined below:- Add the upgrade migration logic to chain distribution. This may be, for example, maintained under a package
app/upgrades/v6.
- Set the upgrade handler in
app.go. ThemoduleNameparameter refers to the authentication module’sScopedKeepername. This is the name provided upon instantiation inapp.govia thex/capabilitykeeperScopeToModule(moduleName string)method. See here for an example insimapp.
IBC Apps
ICS27 - Interchain Accounts
Controller APIs
In previous releases of ibc-go, chain developers integrating the ICS27 interchain accounts controller functionality were expected to create a customBase Application referred to as an authentication module, see the section Building an authentication module from the documentation.
The Base Application was intended to be composed with the ICS27 controller submodule Keeper and facilitate many forms of message authentication depending on a chain’s particular use case.
Prior to ibc-go v6 the controller submodule exposed only these two functions (to which we will refer as the legacy APIs):
However, these functions have now been deprecated in favour of the new controller submodule MsgServer and will be removed in later releases.
Both APIs remain functional and maintain backwards compatibility in ibc-go v6, however consumers of these APIs are now recommended to follow the message passing paradigm outlined in Cosmos SDK ADR 031 and ADR 033. This is facilitated by the Cosmos SDK MsgServiceRouter and chain developers creating custom application logic can now omit the ICS27 controller submodule Keeper from their module and instead depend on message routing.
Depending on the use case, developers of custom authentication modules face one of three scenarios:
My authentication module needs to access IBC packet callbacks
Application developers that wish to consume IBC packet callbacks and react upon packet acknowledgements must continue using the controller submodule’s legacy APIs. The authentication modules will not need a ScopedKeeper anymore, though, because the channel capability will be claimed by the controller submodule. For example, given an Interchain Accounts authentication module keeper ICAAuthKeeper, the authentication module’s ScopedKeeper (scopedICAAuthKeeper) is not needed anymore and can be removed for the argument list of the keeper constructor function, as shown here:
ScopedKeeper name is still needed as part of the channel capability migration described in section Upgrade proposal above. Therefore the authentication module’s ScopedKeeper cannot be completely removed from the chain code until the migration has run.
In the future, the use of the legacy APIs for accessing packet callbacks will be replaced by IBC Actor Callbacks (see ADR 008 for more details) and it will also be possible to access them with the MsgServiceRouter.
My authentication module does not need access to IBC packet callbacks
The authentication module can migrate from using the legacy APIs and it can be composed instead with the MsgServiceRouter, so that the authentication module is able to pass messages to the controller submodule’s MsgServer to register interchain accounts and send packets to the interchain account. For example, given an Interchain Accounts authentication module keeper ICAAuthKeeper, the ICS27 controller submodule keeper (ICAControllerKeeper) and authentication module scoped keeper (scopedICAAuthKeeper) are not needed anymore and can be replaced with the MsgServiceRouter, as shown here:
MsgServer instead of using the legacy APIs. For example, for registering an interchain account:
controllertypes is an import alias for "github.com/cosmos/ibc-go/v6/modules/apps/27-interchain-accounts/controller/types".
In addition, in this use case the authentication module does not need to implement the IBCModule interface anymore.
I do not need a custom authentication module anymore
If your authentication module does not have any extra functionality compared to the default authentication module added in ibc-go v6 (the MsgServer), or if you can use a generic authentication module, such as the x/auth, x/gov or x/group modules from the Cosmos SDK (v0.46 and later), then you can remove your authentication module completely and use instead the gRPC endpoints of the MsgServer or the CLI added in ibc-go v6.
Please remember that the authentication module’s ScopedKeeper name is still needed as part of the channel capability migration described in section Upgrade proposal above.
Host params
The ICS27 host submodule default params have been updated to include theAllowAllHostMsgs wildcard *.
This enables execution of any sdk.Msg type for ICS27 registered on the host chain InterfaceRegistry.
API breaking changes
SerializeCosmosTx takes in a []proto.Message instead of []sdk.Message. This allows for the serialization of proto messages without requiring the fulfillment of the sdk.Msg interface.
The 27-interchain-accounts genesis types have been moved to their own package: modules/apps/27-interchain-accounts/genesis/types.
This change facilitates the addition of the ICS27 controller submodule MsgServer and avoids cyclic imports. This should have minimal disruption to chain developers integrating 27-interchain-accounts.
The ICS27 host submodule NewKeeper function in modules/apps/27-interchain-accounts/host/keeper now includes an additional parameter of type ICS4Wrapper.
This provides the host submodule with the ability to correctly unwrap channel versions in the event of a channel reopening handshake.
ICS29 - NewKeeper API change
The NewKeeper function of ICS29 has been updated to remove the paramSpace parameter as it was unused.
ICS20 - SendTransfer is no longer exported
The SendTransfer function of ICS20 has been removed. IBC transfers should now be initiated with MsgTransfer and routed to the ICS20 MsgServer.
See below for example:
ICS04 - SendPacket API change
The SendPacket API has been simplified:
SendPacket will return the packet sequence.
IBC testing package
TheSendPacket API has been simplified:
SendPacket will return the packet sequence.
Relayers
- No relevant changes were made in this release.
IBC Light Clients
- No relevant changes were made in this release.