Migrations - Cosmos Docs

本指南提供迁移 08-wasm 版本的说明。请注意，以下发布版本已被撤回。升级时请参考对应的迁移章节。

v0.3.1-0.20240717085919-bb71eef0f3bf => v0.3.0+ibc-go-v8.3-wasmvm-v2.0
v0.2.1-0.20240717085554-570d057959e3 => v0.2.0+ibc-go-v7.6-wasmvm-v1.5
v0.2.1-0.20240523101951-4b45d1822fb6 => v0.2.0+ibc-go-v8.3-wasmvm-v2.0
v0.1.2-0.20240412103620-7ee2a2452b79 => v0.1.1+ibc-go-v7.3-wasmvm-v1.5
v0.1.1-0.20231213092650-57fcdb9a9a9d => v0.1.0+ibc-go-v8.0-wasmvm-v1.5
v0.1.1-0.20231213092633-b306e7a706e1 => v0.1.0+ibc-go-v7.3-wasmvm-v1.5

从 ibc-go v8.4.x 升级到 ibc-go v9.0.x

链

ClientState 中的 Initialize、Status、GetTimestampAtHeight、GetLatestHeight、VerifyMembership、VerifyNonMembership、VerifyClientMessage、UpdateState 和 UpdateStateOnMisbehaviour 函数已被移除，其全部逻辑已迁移到 LightClientModule 的函数中。
MigrateContract 函数已从 ClientState 中移除。
SudoMsg 的 VerifyMembershipMsg 和 VerifyNonMembershipMsg 负载已修改。两个结构体的 Path 字段已从 v1.MerklePath 更新为 v2.MerklePath。新的 v2.MerklePath 字段包含 KeyPath，其类型为 [][]byte，而不是 []string。这支持对存储在包含非 UTF-8 编码符号的键下的值进行证明。因此，这两个消息中包含 key_path 的 JSON 字段 path 在序列化时会将各元素编码为 base64 字节串。对于 08-wasm 客户端合约，这是一个破坏性变更，应迁移以正确支持 v2.MerklePath 字段的反序列化。
ExportMetadataMsg 结构体已被移除，合约不再需要实现它。Core IBC 将负责导出轻客户端合约写入存储的所有键值对。
ZeroCustomFields 接口函数已从 ClientState 接口中移除。Core IBC 过去仅在调度 IBC 软件升级时使用该函数来设置 tendermint 客户端状态。该接口函数现已由类型断言替代。
MaxWasmByteSize 函数已移除，改为使用 MaxWasmSize 常量。
HasChecksum、GetAllChecksums 和 Logger 函数已从 types 包移动到 keeper 包中 Keeper 类型的方法。
InitializePinnedCodes 函数已移动到 keeper 包中 Keeper 类型的方法。
CustomQuerier、StargateQuerier 和 QueryPlugins 类型已从 types 包移动到 keeper 包。
NewDefaultQueryPlugins、AcceptListStargateQuerier 和 RejectCustomQuerier 函数已从 types 包移动到 keeper 包。
NewDefaultQueryPlugins 函数签名已变更，新增参数：queryRouter ibcwasm.QueryRouter。
AcceptListStargateQuerier 函数签名已变更，新增一个参数：queryRouter ibcwasm.QueryRouter。
WithQueryPlugins 函数签名已变更，现在接收来自 keeper 包的 QueryPlugins 类型（此前来自 types 包）。
VMGasRegister 变量已从 types 包移动到 keeper 包。

从 v0.3.0+ibc-go-v8.3-wasmvm-v2.0 升级到 v0.4.1-ibc-go-v8.4-wasmvm-v2.0

合约开发者

合约开发者需要更新 SudoMsg 负载 VerifyMembershipMsg 和 VerifyNonMembershipMsg 的 JSON API 消息结构。这两个 JSON API 消息中的 path 字段已重命名为 merkle_path。现有 08-wasm 客户端合约需要执行迁移，以正确处理这些字段的反序列化。

从 v0.2.0+ibc-go-v7.3-wasmvm-v1.5 升级到 v0.3.1-ibc-go-v7.4-wasmvm-v1.5

合约开发者

从 v0.2.0+ibc-go-v8.3-wasmvm-v2.0 升级到 v0.3.0-ibc-go-v8.3-wasmvm-v2.0

合约开发者

面向 ibc-go v8.3.x 及以上版本的 08-wasm v0.3.0 发布为客户端合约开发者引入了一项破坏性变更。合约 API SudoMsg 负载 VerifyMembershipMsg 和 VerifyNonMembershipMsg 已被修改。两个结构体的 Path 字段编码已从 v1.MerklePath 更新为 v2.MerklePath，以支持对存储在包含非 UTF-8 编码符号的键下的值进行证明。因此，Path 字段现在包含一个由 key_path 组成的 MerklePath，其类型为 [][]byte，而不是 []string。VerifyMembershipMsg 和 VerifyNonMembershipMsg 两个结构体中包含 key_path 的 JSON 字段 path 现在会将各元素序列化为 base64 编码的字节串。下面给出 JSON 差异示例。

{
  "verify_membership": {
    "height": {
      "revision_height": 1
    },
    "delay_time_period": 0,
    "delay_block_period": 0,
    "proof":"dmFsaWQgcHJvb2Y=",
    "path": {
+      "key_path":["L2liYw==","L2tleS9wYXRo"]
-      "key_path":["/ibc","/key/path"]
    },
    "value":"dmFsdWU="
  }
}

现有 08-wasm 客户端合约需要执行迁移，以正确处理 key_path 从 []string 到 [][]byte 的反序列化。合约开发者应了解 08-wasm 在此处提供的迁移路径。客户端合约中所需变更的示例如下：

#[cw_serde]
pub struct MerklePath {
+   pub key_path: Vec<cosmwasm_std::Binary>,
-   pub key_path: Vec<String>,
}

更多信息请参阅 cosmwasm_std 文档。

从 v0.1.1+ibc-go-v7.3-wasmvm-v1.5 升级到 v0.2.0-ibc-go-v7.3-wasmvm-v1.5

合约开发者

面向 ibc-go v7.6.x 及以上版本的 08-wasm v0.2.0 发布为客户端合约开发者引入了一项破坏性变更。合约 API SudoMsg 负载 VerifyMembershipMsg 和 VerifyNonMembershipMsg 已被修改。两个结构体的 Path 字段编码已从 v1.MerklePath 更新为 v2.MerklePath，以支持对存储在包含非 UTF-8 编码符号的键下的值进行证明。因此，Path 字段现在包含一个由 key_path 组成的 MerklePath，其类型为 [][]byte，而不是 []string。VerifyMembershipMsg 和 VerifyNonMembershipMsg 两个结构体中包含 key_path 的 JSON 字段 path 现在会将各元素序列化为 base64 编码的字节串。下面给出 JSON 差异示例。

{
  "verify_membership": {
    "height": {
      "revision_height": 1
    },
    "delay_time_period": 0,
    "delay_block_period": 0,
    "proof":"dmFsaWQgcHJvb2Y=",
    "path": {
+      "key_path":["L2liYw==","L2tleS9wYXRo"]
-      "key_path":["/ibc","/key/path"]
    },
    "value":"dmFsdWU="
  }
}

#[cw_serde]
pub struct MerklePath {
+   pub key_path: Vec<cosmwasm_std::Binary>,
-   pub key_path: Vec<String>,
}

更多信息请参阅 cosmwasm_std 文档。

从 ibc-go v7.3.x 升级到 ibc-go v8.0.x

链

在 v7 发布线中，与 ibc-go v7.3.x 及以上兼容的 08-wasm 版本里，上传的 Wasm 字节码校验和都存储在单个键下。自 ibc-go v8.0.x 起，校验和改为使用 collections.KeySet 存储，其完整功能在 Cosmos SDK v0.50 中才可用。因此，08-wasm 模块中配置了一个自动迁移处理器，用于将已存储的校验和迁移到 collections.KeySet。

从 v0.1.0+ibc-go-v8.0-wasmvm-v1.5 升级到 v0.2.0-ibc-go-v8.3-wasmvm-v2.0

WasmEngine 接口已更新，以反映 Wasm VM 函数签名的变化：

type WasmEngine interface {
- StoreCode(code wasmvm.WasmCode) (wasmvm.Checksum, error)
+ StoreCode(code wasmvm.WasmCode, gasLimit uint64) (wasmvmtypes.Checksum, uint64, error)

  StoreCodeUnchecked(code wasmvm.WasmCode) (wasmvm.Checksum, error)

  Instantiate(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    info wasmvmtypes.MessageInfo,
    initMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) (*wasmvmtypes.Response, uint64, error)
+ ) (*wasmvmtypes.ContractResult, uint64, error)

  Query(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    queryMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) ([]byte, uint64, error)
+ ) (*wasmvmtypes.QueryResult, uint64, error)

  Migrate(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    migrateMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) (*wasmvmtypes.Response, uint64, error)
+ ) (*wasmvmtypes.ContractResult, uint64, error)

  Sudo(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    sudoMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) (*wasmvmtypes.Response, uint64, error)
+ ) (*wasmvmtypes.ContractResult, uint64, error)

  GetCode(checksum wasmvm.Checksum) (wasmvm.WasmCode, error)

  Pin(checksum wasmvm.Checksum) error

  Unpin(checksum wasmvm.Checksum) error
}

MockWasmEngine 接口中的函数也需要进行类似修改。

链

WasmConfig 的 SupportedCapabilities 字段现在的类型为 []string：

type WasmConfig struct {
  DataDir string
- SupportedCapabilities string
+ SupportedCapabilities []string
  ContractDebugMode bool
}

This guide provides instructions for migrating 08-wasm versions. Please note that the following releases are retracted. Please refer to the appropriate migrations section for upgrading.

v0.3.1-0.20240717085919-bb71eef0f3bf => v0.3.0+ibc-go-v8.3-wasmvm-v2.0
v0.2.1-0.20240717085554-570d057959e3 => v0.2.0+ibc-go-v7.6-wasmvm-v1.5
v0.2.1-0.20240523101951-4b45d1822fb6 => v0.2.0+ibc-go-v8.3-wasmvm-v2.0
v0.1.2-0.20240412103620-7ee2a2452b79 => v0.1.1+ibc-go-v7.3-wasmvm-v1.5
v0.1.1-0.20231213092650-57fcdb9a9a9d => v0.1.0+ibc-go-v8.0-wasmvm-v1.5
v0.1.1-0.20231213092633-b306e7a706e1 => v0.1.0+ibc-go-v7.3-wasmvm-v1.5

From ibc-go v8.4.x to ibc-go v9.0.x

Chains

The Initialize, Status, GetTimestampAtHeight, GetLatestHeight, VerifyMembership, VerifyNonMembership, VerifyClientMessage, UpdateState and UpdateStateOnMisbehaviour functions in ClientState have been removed and all their logic has been moved to functions of the LightClientModule.
The MigrateContract function has been removed from ClientState.
The VerifyMembershipMsg and VerifyNonMembershipMsg payloads for SudoMsg have been modified. The Path field of both structs has been updated from v1.MerklePath to v2.MerklePath. The new v2.MerklePath field contains a KeyPath of [][]byte as opposed to []string. This supports proving values stored under keys which contain non-utf8 encoded symbols. As a result, the JSON field path containing key_path of both messages will marshal elements as a base64 encoded bytestrings. This is a breaking change for 08-wasm client contracts and they should be migrated to correctly support deserialisation of the v2.MerklePath field.
The ExportMetadataMsg struct has been removed and is no longer required for contracts to implement. Core IBC will handle exporting all key/value’s written to the store by a light client contract.
The ZeroCustomFields interface function has been removed from the ClientState interface. Core IBC only used this function to set tendermint client states when scheduling an IBC software upgrade. The interface function has been replaced by a type assertion.
The MaxWasmByteSize function has been removed in favor of the MaxWasmSize constant.
The HasChecksum, GetAllChecksums and Logger functions have been moved from the types package to a method on the Keeper type in the keeper package.
The InitializePinnedCodes function has been moved to a method on the Keeper type in the keeper package.
The CustomQuerier, StargateQuerier and QueryPlugins types have been moved from the types package to the keeper package.
The NewDefaultQueryPlugins, AcceptListStargateQuerier and RejectCustomQuerier functions has been moved from the types package to the keeper package.
The NewDefaultQueryPlugins function signature has changed to take an argument: queryRouter ibcwasm.QueryRouter.
The AcceptListStargateQuerier function signature has changed to take an additional argument: queryRouter ibcwasm.QueryRouter.
The WithQueryPlugins function signature has changed to take in the QueryPlugins type from the keeper package (previously from the types package).
The VMGasRegister variable has been moved from the types package to the keeper package.

From v0.3.0+ibc-go-v8.3-wasmvm-v2.0 to v0.4.1-ibc-go-v8.4-wasmvm-v2.0

Contract developers

Contract developers are required to update their JSON API message structure for the SudoMsg payloads VerifyMembershipMsg and VerifyNonMembershipMsg. The path field on both JSON API messages has been renamed to merkle_path. A migration is required for existing 08-wasm client contracts in order to correctly handle the deserialisation of these fields.

From v0.2.0+ibc-go-v7.3-wasmvm-v1.5 to v0.3.1-ibc-go-v7.4-wasmvm-v1.5

Contract developers

From v0.2.0+ibc-go-v8.3-wasmvm-v2.0 to v0.3.0-ibc-go-v8.3-wasmvm-v2.0

Contract developers

The v0.3.0 release of 08-wasm for ibc-go v8.3.x and above introduces a breaking change for client contract developers. The contract API SudoMsg payloads VerifyMembershipMsg and VerifyNonMembershipMsg have been modified. The encoding of the Path field of both structs has been updated from v1.MerklePath to v2.MerklePath to support proving values stored under keys which contain non-utf8 encoded symbols. As a result, the Path field now contains a MerklePath composed of key_path of [][]byte as opposed to []string. The JSON field path containing key_path of both VerifyMembershipMsg and VerifyNonMembershipMsg structs will now marshal elements as base64 encoded bytestrings. See below for example JSON diff.

{
  "verify_membership": {
    "height": {
      "revision_height": 1
    },
    "delay_time_period": 0,
    "delay_block_period": 0,
    "proof":"dmFsaWQgcHJvb2Y=",
    "path": {
+      "key_path":["L2liYw==","L2tleS9wYXRo"]
-      "key_path":["/ibc","/key/path"]
    },
    "value":"dmFsdWU="
  }
}

A migration is required for existing 08-wasm client contracts in order to correctly handle the deserialisation of key_path from []string to [][]byte. Contract developers should familiarise themselves with the migration path offered by 08-wasm here. An example of the required changes in a client contract may look like:

#[cw_serde]
pub struct MerklePath {
+   pub key_path: Vec<cosmwasm_std::Binary>,
-   pub key_path: Vec<String>,
}

Please refer to the cosmwasm_std documentation for more information.

From v0.1.1+ibc-go-v7.3-wasmvm-v1.5 to v0.2.0-ibc-go-v7.3-wasmvm-v1.5

Contract developers

The v0.2.0 release of 08-wasm for ibc-go v7.6.x and above introduces a breaking change for client contract developers. The contract API SudoMsg payloads VerifyMembershipMsg and VerifyNonMembershipMsg have been modified. The encoding of the Path field of both structs has been updated from v1.MerklePath to v2.MerklePath to support proving values stored under keys which contain non-utf8 encoded symbols. As a result, the Path field now contains a MerklePath composed of key_path of [][]byte as opposed to []string. The JSON field path containing key_path of both VerifyMembershipMsg and VerifyNonMembershipMsg structs will now marshal elements as base64 encoded bytestrings. See below for example JSON diff.

{
  "verify_membership": {
    "height": {
      "revision_height": 1
    },
    "delay_time_period": 0,
    "delay_block_period": 0,
    "proof":"dmFsaWQgcHJvb2Y=",
    "path": {
+      "key_path":["L2liYw==","L2tleS9wYXRo"]
-      "key_path":["/ibc","/key/path"]
    },
    "value":"dmFsdWU="
  }
}

#[cw_serde]
pub struct MerklePath {
+   pub key_path: Vec<cosmwasm_std::Binary>,
-   pub key_path: Vec<String>,
}

Please refer to the cosmwasm_std documentation for more information.

From ibc-go v7.3.x to ibc-go v8.0.x

Chains

In the 08-wasm versions compatible with ibc-go v7.3.x and above from the v7 release line, the checksums of the uploaded Wasm bytecodes are all stored under a single key. From ibc-go v8.0.x the checksums are stored using collections.KeySet, whose full functionality became available in Cosmos SDK v0.50. There is therefore an automatic migration handler configured in the 08-wasm module to migrate the stored checksums to collections.KeySet.

From v0.1.0+ibc-go-v8.0-wasmvm-v1.5 to v0.2.0-ibc-go-v8.3-wasmvm-v2.0

The WasmEngine interface has been updated to reflect changes in the function signatures of Wasm VM:

type WasmEngine interface {
- StoreCode(code wasmvm.WasmCode) (wasmvm.Checksum, error)
+ StoreCode(code wasmvm.WasmCode, gasLimit uint64) (wasmvmtypes.Checksum, uint64, error)

  StoreCodeUnchecked(code wasmvm.WasmCode) (wasmvm.Checksum, error)

  Instantiate(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    info wasmvmtypes.MessageInfo,
    initMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) (*wasmvmtypes.Response, uint64, error)
+ ) (*wasmvmtypes.ContractResult, uint64, error)

  Query(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    queryMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) ([]byte, uint64, error)
+ ) (*wasmvmtypes.QueryResult, uint64, error)

  Migrate(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    migrateMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) (*wasmvmtypes.Response, uint64, error)
+ ) (*wasmvmtypes.ContractResult, uint64, error)

  Sudo(
    checksum wasmvm.Checksum,
    env wasmvmtypes.Env,
    sudoMsg []byte,
    store wasmvm.KVStore,
    goapi wasmvm.GoAPI,
    querier wasmvm.Querier,
    gasMeter wasmvm.GasMeter,
    gasLimit uint64,
    deserCost wasmvmtypes.UFraction,
- ) (*wasmvmtypes.Response, uint64, error)
+ ) (*wasmvmtypes.ContractResult, uint64, error)

  GetCode(checksum wasmvm.Checksum) (wasmvm.WasmCode, error)

  Pin(checksum wasmvm.Checksum) error

  Unpin(checksum wasmvm.Checksum) error
}

Similar changes were required in the functions of MockWasmEngine interface.

Chains

The SupportedCapabilities field of WasmConfig is now of type []string:

type WasmConfig struct {
  DataDir string
- SupportedCapabilities string
+ SupportedCapabilities []string
  ContractDebugMode bool
}

​从 ibc-go v8.4.x 升级到 ibc-go v9.0.x

​链

​从 v0.3.0+ibc-go-v8.3-wasmvm-v2.0 升级到 v0.4.1-ibc-go-v8.4-wasmvm-v2.0

​合约开发者

​从 v0.2.0+ibc-go-v7.3-wasmvm-v1.5 升级到 v0.3.1-ibc-go-v7.4-wasmvm-v1.5

​合约开发者

​从 v0.2.0+ibc-go-v8.3-wasmvm-v2.0 升级到 v0.3.0-ibc-go-v8.3-wasmvm-v2.0

​合约开发者

​从 v0.1.1+ibc-go-v7.3-wasmvm-v1.5 升级到 v0.2.0-ibc-go-v7.3-wasmvm-v1.5

​合约开发者

​从 ibc-go v7.3.x 升级到 ibc-go v8.0.x

​链

​从 v0.1.0+ibc-go-v8.0-wasmvm-v1.5 升级到 v0.2.0-ibc-go-v8.3-wasmvm-v2.0

​链

​From ibc-go v8.4.x to ibc-go v9.0.x

​Chains

​From v0.3.0+ibc-go-v8.3-wasmvm-v2.0 to v0.4.1-ibc-go-v8.4-wasmvm-v2.0

​Contract developers

​From v0.2.0+ibc-go-v7.3-wasmvm-v1.5 to v0.3.1-ibc-go-v7.4-wasmvm-v1.5

​Contract developers

​From v0.2.0+ibc-go-v8.3-wasmvm-v2.0 to v0.3.0-ibc-go-v8.3-wasmvm-v2.0

​Contract developers

​From v0.1.1+ibc-go-v7.3-wasmvm-v1.5 to v0.2.0-ibc-go-v7.3-wasmvm-v1.5

​Contract developers

​From ibc-go v7.3.x to ibc-go v8.0.x

​Chains

​From v0.1.0+ibc-go-v8.0-wasmvm-v1.5 to v0.2.0-ibc-go-v8.3-wasmvm-v2.0

​Chains

从 ibc-go v8.4.x 升级到 ibc-go v9.0.x

链

从 v0.3.0+ibc-go-v8.3-wasmvm-v2.0 升级到 v0.4.1-ibc-go-v8.4-wasmvm-v2.0

合约开发者

从 v0.2.0+ibc-go-v7.3-wasmvm-v1.5 升级到 v0.3.1-ibc-go-v7.4-wasmvm-v1.5

合约开发者

从 v0.2.0+ibc-go-v8.3-wasmvm-v2.0 升级到 v0.3.0-ibc-go-v8.3-wasmvm-v2.0

合约开发者

从 v0.1.1+ibc-go-v7.3-wasmvm-v1.5 升级到 v0.2.0-ibc-go-v7.3-wasmvm-v1.5

合约开发者

从 ibc-go v7.3.x 升级到 ibc-go v8.0.x

链

从 v0.1.0+ibc-go-v8.0-wasmvm-v1.5 升级到 v0.2.0-ibc-go-v8.3-wasmvm-v2.0

链

From ibc-go v8.4.x to ibc-go v9.0.x

Chains

From v0.3.0+ibc-go-v8.3-wasmvm-v2.0 to v0.4.1-ibc-go-v8.4-wasmvm-v2.0

Contract developers

From v0.2.0+ibc-go-v7.3-wasmvm-v1.5 to v0.3.1-ibc-go-v7.4-wasmvm-v1.5

Contract developers

From v0.2.0+ibc-go-v8.3-wasmvm-v2.0 to v0.3.0-ibc-go-v8.3-wasmvm-v2.0

Contract developers

From v0.1.1+ibc-go-v7.3-wasmvm-v1.5 to v0.2.0-ibc-go-v7.3-wasmvm-v1.5

Contract developers

From ibc-go v7.3.x to ibc-go v8.0.x

Chains

From v0.1.0+ibc-go-v8.0-wasmvm-v1.5 to v0.2.0-ibc-go-v8.3-wasmvm-v2.0

Chains