CHANGELOG 中展示的更多信息。任何需要由 ibc-go 用户执行的变更都应记录在这里。 本文档根据四类潜在用户群体分为四个部分:
- 链
- IBC 应用
- 中继器
- IBC 轻客户端
链
链会执行自动迁移,以移除现有的 localhost 客户端,并将 solomachine 迁移到 protobuf 定义的 v3 版本。 新增了一个可选的升级处理器,用于修剪已过期的 tendermint 共识状态。它可在任意升级过程中使用(自 v7 起)。要执行这一可选的状态修剪,请在
app/app.go 中对升级处理器的函数调用添加以下内容。
轻客户端注册
链必须显式注册其希望集成的所有轻客户端模块类型。Tendermint 注册
要注册 tendermint 客户端,请修改app.go 文件并加入 tendermint 的 AppModuleBasic:
AppModuleBasic 的 PR。
Solo machine 注册
要注册 solo machine 客户端,请修改app.go 文件并加入 solo machine 的 AppModuleBasic:
AppModuleBasic 的 PR。
测试包 API
testing/endpoint.go 中的 SetChannelClosed 工具方法已更新为 SetChannelState,它接收一个 channeltypes.State 参数,因此 ChannelState 现在可以被设置为任意一种可能的通道状态。
IBC 应用
- 此版本没有相关变更。
中继器
- 此版本没有相关变更。
IBC 轻客户端
ClientState 接口变更
VerifyUpgradeAndUpdateState 函数已被修改。客户端状态和共识状态的返回值已被移除。
轻客户端必须自行处理客户端状态与共识状态的全部管理工作,包括在客户端存储中设置更新后的客户端状态和共识状态。
现在要求 Initialize 方法在创建客户端时,将初始客户端状态、共识状态以及所有客户端特定元数据写入提供的存储中。
CheckHeaderAndUpdateState 方法已拆分为以下 4 个新方法:
-
VerifyClientMessage用于验证ClientMessage。ClientMessage可以是Header、Misbehaviour或批量更新。CheckForMisbehaviour、UpdateState和UpdateStateOnMisbehaviour的调用将假定ClientMessage的内容已通过验证且可信。如果ClientMessage验证失败,则应返回错误。 -
CheckForMisbehaviour用于检查Header或Misbehaviour类型中是否存在作恶证据。 -
UpdateStateOnMisbehaviour在检测并验证出作恶行为后,对ClientState执行适当的状态变更。 -
UpdateState会按需更新并存储 IBC 客户端的相关信息,例如ClientState及其对应的ConsensusState。如果ClientMessage的类型为Misbehaviour,则返回错误。更新成功后,会返回一个包含已更新共识状态高度的列表。
CheckMisbehaviourAndUpdateState 函数已从 ClientState 接口中移除。该功能现在由 VerifyClientMessage、CheckForMisbehaviour 和 UpdateStateOnMisbehaviour 的组合来完成。
ClientState 接口中新增了 GetTimestampAtHeight 函数。它应返回与给定高度关联的共识状态时间戳。
在 ibc-go/v7 之前,ClientState 接口会为对手方状态存储中每一种待验证的数据类型定义一个方法。现在,所有 IBC 数据类型的状态验证函数已合并为两个通用方法:
VerifyMembership 和 VerifyNonMembership。这两个方法都应接收一个标准化的键路径
exported.Path,其定义见 ICS 24 host requirements。成员关系验证要求调用方提供已编组的值 []byte。对于非数据包处理的验证,延迟周期参数应为零。核心 IBC 现在允许零 proof height,并且可以将其传入 VerifyMembership 和 VerifyNonMembership。如果零 proof height 属于无效行为,轻客户端有责任返回错误。
下面展示了 ibc-go 当前执行通道状态验证的示例。
Header 与 Misbehaviour
exported.Header 与 exported.Misbehaviour 接口类型已合并,并重命名为 ClientMessage 接口。
GetHeight 函数已从 exported.Header 中移除,因此它也不再包含在 ClientMessage 接口中。
ConsensusState
由于核心 IBC 未使用 GetRoot 函数,它已从共识状态接口中移除。
客户端 Keeper
Keeper 函数CheckMisbehaviourAndUpdateState 已被移除,因为 UpdateClient 现在可以处理基于 ClientMessage 类型的 ClientState 更新,而该类型可以是任意 Misbehaviour 实现。
SDK 消息
MsgSubmitMisbehaviour 已被弃用,因为 MsgUpdateClient 现在可以提交 ClientMessage 类型,而该类型可以是任意 Misbehaviour 实现。
MsgUpdateClient 中的字段 header 已重命名为 client_message。
Solomachine
在 ibc-go/v7 中,06-solomachine 客户端实现已被简化。新增了原地存储迁移,用于将 solomachine 客户端从 v2 迁移到 v3。
ClientState
ClientState protobuf 消息定义已更新,移除了已弃用的 bool 字段 allow_update_after_proposal。
Header 与 Misbehaviour
06-solomachine 的 protobuf 消息 Header 已更新,移除了 sequence 字段。该字段被认为是冗余的,因为实现可以安全地依赖 ClientState 中维护的 sequence 值。
Misbehaviour protobuf 消息也已更新,移除了 client_id 字段。
SignBytes
最值得注意的是,SignBytes protobuf 定义已被修改:将 data_type 字段替换为新的 path 字段。path 字段定义为 bytes,表示 data 所存储位置对应的序列化 ICS-24 标准化键路径。
DataType 枚举及其所有关联数据类型均已移除,这大幅减少了消息定义数量以及构造 SignBytes 消息类型的复杂度。同样地,solomachine 实现现在必须在构造 SignatureAndData 以验证 SignBytes 数据签名时使用序列化后的 path 值。
IBC 模块常量
IBC 模块常量已从host 包移动到 exported 包。所有相关用法都需要更新。
升级到 Cosmos SDK 0.47
以下内容应视为对 Cosmos SDK v0.47 UPGRADING.md 的补充。Protobuf
Protobuf 代码生成、lint 和格式化已更新为使用ghcr.io/cosmos/proto-builder:0.11.5 Docker 容器。IBC protobuf 定义现已通过 CI 工作流打包并发布到 buf.build/cosmos/ibc。third_party/proto 目录已移除,改为使用 buf.build 进行依赖管理。
应用模块
AppModule 接口的旧版 API 已从 ibc-go 模块中移除。例如,对于
导入
由于仓库已从 confio 迁移到 cosmos,ics23 的导入路径已更新。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
Chains will perform automatic migrations to remove existing localhost clients and to migrate the solomachine to v3 of the protobuf definition. An optional upgrade handler has been added to prune expired tendermint consensus states. It may be used during any upgrade (from v7 onwards). Add the following to the function call to the upgrade handler inapp/app.go, to perform the optional state pruning.
Light client registration
Chains must explicitly register the types of any light client modules it wishes to integrate.Tendermint registration
To register the tendermint client, modify theapp.go file to include the tendermint AppModuleBasic:
AppModuleBasic for the tendermint client.
Solo machine registration
To register the solo machine client, modify theapp.go file to include the solo machine AppModuleBasic:
AppModuleBasic for the solo machine client.
Testing package API
TheSetChannelClosed utility method in testing/endpoint.go has been updated to SetChannelState, which will take a channeltypes.State argument so that the ChannelState can be set to any of the possible channel states.
IBC Apps
- No relevant changes were made in this release.
Relayers
- No relevant changes were made in this release.
IBC Light Clients
ClientState interface changes
The VerifyUpgradeAndUpdateState function has been modified. The client state and consensus state return values have been removed.
Light clients must handle all management of client and consensus states including the setting of updated client state and consensus state in the client store.
The Initialize method is now expected to set the initial client state, consensus state and any client-specific metadata in the provided store upon client creation.
The CheckHeaderAndUpdateState method has been split into 4 new methods:
-
VerifyClientMessageverifies aClientMessage. AClientMessagecould be aHeader,Misbehaviour, or batch update. Calls toCheckForMisbehaviour,UpdateState, andUpdateStateOnMisbehaviourwill assume that the content of theClientMessagehas been verified and can be trusted. An error should be returned if theClientMessagefails to verify. -
CheckForMisbehaviourchecks for evidence of a misbehaviour inHeaderorMisbehaviourtypes. -
UpdateStateOnMisbehaviourperforms appropriate state changes on aClientStategiven that misbehaviour has been detected and verified. -
UpdateStateupdates and stores as necessary any associated information for an IBC client, such as theClientStateand correspondingConsensusState. An error is returned ifClientMessageis of typeMisbehaviour. Upon successful update, a list containing the updated consensus state height is returned.
CheckMisbehaviourAndUpdateState function has been removed from ClientState interface. This functionality is now encapsulated by the usage of VerifyClientMessage, CheckForMisbehaviour, UpdateStateOnMisbehaviour.
The function GetTimestampAtHeight has been added to the ClientState interface. It should return the timestamp for a consensus state associated with the provided height.
Prior to ibc-go/v7 the ClientState interface defined a method for each data type which was being verified in the counterparty state store.
The state verification functions for all IBC data types have been consolidated into two generic methods, VerifyMembership and VerifyNonMembership.
Both are expected to be provided with a standardised key path, exported.Path, as defined in ICS 24 host requirements. Membership verification requires callers to provide the marshalled value []byte. Delay period values should be zero for non-packet processing verification. A zero proof height is now allowed by core IBC and may be passed into VerifyMembership and VerifyNonMembership. Light clients are responsible for returning an error if a zero proof height is invalid behaviour.
See below for an example of how ibc-go now performs channel state verification.
Header and Misbehaviour
exported.Header and exported.Misbehaviour interface types have been merged and renamed to ClientMessage interface.
GetHeight function has been removed from exported.Header and thus is not included in the ClientMessage interface
ConsensusState
The GetRoot function has been removed from consensus state interface since it was not used by core IBC.
Client keeper
Keeper functionCheckMisbehaviourAndUpdateState has been removed since function UpdateClient can now handle updating ClientState on ClientMessage type which can be any Misbehaviour implementations.
SDK message
MsgSubmitMisbehaviour is deprecated since MsgUpdateClient can now submit a ClientMessage type which can be any Misbehaviour implementations.
The field header in MsgUpdateClient has been renamed to client_message.
Solomachine
The06-solomachine client implementation has been simplified in ibc-go/v7. In-place store migrations have been added to migrate solomachine clients from v2 to v3.
ClientState
The ClientState protobuf message definition has been updated to remove the deprecated bool field allow_update_after_proposal.
Header and Misbehaviour
The 06-solomachine protobuf message Header has been updated to remove the sequence field. This field was seen as redundant as the implementation can safely rely on the sequence value maintained within the ClientState.
Misbehaviour protobuf message has been updated to remove the client_id field.
SignBytes
Most notably, the SignBytes protobuf definition has been modified to replace the data_type field with a new field, path. The path field is defined as bytes and represents a serialized ICS-24 standardized key path under which the data is stored.
DataType enum and all associated data types have been removed, greatly reducing the number of message definitions and complexity in constructing the SignBytes message type. Likewise, solomachine implementations must now use the serialized path value when constructing SignatureAndData for signature verification of SignBytes data.
IBC module constants
IBC module constants have been moved from thehost package to the exported package. Any usages will need to be updated.
Upgrading to Cosmos SDK 0.47
The following should be considered as complementary to Cosmos SDK v0.47 UPGRADING.md.Protobuf
Protobuf code generation, linting and formatting have been updated to leverage theghcr.io/cosmos/proto-builder:0.11.5 docker container. IBC protobuf definitions are now packaged and published to buf.build/cosmos/ibc via CI workflows. The third_party/proto directory has been removed in favour of dependency management using buf.build.
App modules
Legacy APIs of theAppModule interface have been removed from ibc-go modules. For example, for