From d2a579e9d4390270fb52e6771417115e7e405a2e Mon Sep 17 00:00:00 2001 From: Damian Nolan Date: Tue, 9 Jul 2024 15:08:33 +0200 Subject: [PATCH] docs: update migration docs for merkle path v2 changes (#6757) * docs: update migration docs for merkle path v2 changes * chore: fix indentation in snippet * chore: indentation * chore: update documentation to add cosmwasm_std::Binary to example diffs * chore: update version from v0.2.0-ibc-go-v7.6-wasmvm-v1.5 to v0.2.0-ibc-go-v7.3-wasmvm-v1.5 --- .../03-light-clients/04-wasm/09-migrations.md | 88 +++++++++++++++++++ docs/docs/05-migrations/13-v8-to-v9.md | 2 +- 2 files changed, 89 insertions(+), 1 deletion(-) diff --git a/docs/docs/03-light-clients/04-wasm/09-migrations.md b/docs/docs/03-light-clients/04-wasm/09-migrations.md index 1acc23d441a..bc1f94e426c 100644 --- a/docs/docs/03-light-clients/04-wasm/09-migrations.md +++ b/docs/docs/03-light-clients/04-wasm/09-migrations.md @@ -9,6 +9,94 @@ slug: /ibc/light-clients/wasm/migrations This guide provides instructions for migrating 08-wasm versions. +## 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. + +```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](./05-governance.md#migrating-an-existing-wasm-light-client-contract). + +An example of the required changes in a client contract may look like: + +```diff +#[cw_serde] +pub struct MerklePath { ++ pub key_path: Vec, +- pub key_path: Vec, +} +``` + +Please refer to the [`cosmwasm_std`](https://docs.rs/cosmwasm-std/2.0.4/cosmwasm_std/struct.Binary.html) 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. + +```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](./05-governance.md#migrating-an-existing-wasm-light-client-contract). + +An example of the required changes in a client contract may look like: + +```diff +#[cw_serde] +pub struct MerklePath { ++ pub key_path: Vec, +- pub key_path: Vec, +} +``` + +Please refer to the [`cosmwasm_std`](https://docs.rs/cosmwasm-std/2.0.4/cosmwasm_std/struct.Binary.html) documentation for more information. + ## From ibc-go v7.3.x to ibc-go v8.0.x ### Chains diff --git a/docs/docs/05-migrations/13-v8-to-v9.md b/docs/docs/05-migrations/13-v8-to-v9.md index 4c059015cac..3481bf536be 100644 --- a/docs/docs/05-migrations/13-v8-to-v9.md +++ b/docs/docs/05-migrations/13-v8-to-v9.md @@ -203,7 +203,7 @@ The `IterateConsensusMetadata` function has been removed. ### 08-wasm -- The `VerifyMembershipMsg` and `VerifyNonMembershipMsg` payloads for `SudoMsg` have been extended to include a new field, `MerklePath`. The existing `Path` field will remain the same. The new `MerklePath` field is used if and only if the provided key path contains non-utf8 encoded symbols, and as a result will encode the JSON field `merkle_path` as a base64 encoded bytestring. See [23-commitment](#23-commitment). +- 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`, see [23-commitment](#23-commitment). 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. See [08-wasm migrations](../03-light-clients/04-wasm/09-migrations.md) for more information. - 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.