docs: update v9 migration doc for merkle path v2 (#6708)

* docs: update v9 migration doc for merkle path v2 * nit * lint --------- Co-authored-by: Carlos Rodriguez <[email protected]>
cosmos · Jul 2, 2024 · 56e526c · 56e526c
1 parent ad2ba78
commit 56e526c
Showing 1 changed file with 53 additions and 47 deletions.
diff --git a/docs/docs/05-migrations/13-v8-to-v9.md b/docs/docs/05-migrations/13-v8-to-v9.md
@@ -24,51 +24,6 @@ There are four sections based on the four potential user groups of this document
 
 ## IBC Apps
 
-### API removals
-
-The `exported.ChannelI` and `exported.CounterpartyChannelI` interfaces have been removed. Please use the concrete types.
-The `exported.ConnectionI` and `exported.CounterpartyConnectionI` interfaces have been removed. Please use the concrete types.
-The `exported.Proof` interface has been removed. Please use the `MerkleProof` concrete type.
-
-The functions `GetState()`, `GetOrdering()`, `GetCounterparty()`, `GetConnectionHops()`, `GetVersion()` of the `Channel` type have been removed.
-The functions `GetPortID()`, `GetChannelID()` of the `CounterpartyChannel` type have been removed.
-The functions `GetClientID()`, `GetState()`, `GetCounterparty()`, `GetVersions()`, and `GetDelayPeriod` of the `Connection` type have been removed. 
-The functions `GetClientID()`, `GetConnectionID()`, and `GetPrefix()` of the `CounterpartyConnection` type have been removed. 
-
-The utility function `QueryLatestConsensusState` of `04-channel` CLI has been removed.
-
-### API deprecation notice
-
-The testing package functions `coordinator.Setup`, `coordinator.SetupClients`, `coordinator.SetupConnections`, `coordinator.CreateConnections`, and `coordinator.CreateChannels` have been deprecated and will be removed in v10.
-Please use the new functions `path.Setup`, `path.SetupClients`, `path.SetupConnections`, `path.CreateConnections`, `path.CreateChannels`.
-
-### IBC testing package
-
-- The `mock.PV` type has been removed in favour of [`cmttypes.MockPV`](https://github.com/cometbft/cometbft/blob/v0.38.5/types/priv_validator.go#L50) ([#5709](https://github.com/cosmos/ibc-go/pull/5709)).
-- Functions `ConstructUpdateTMClientHeader` and `ConstructUpdateTMClientHeaderWithTrustedHeight` of `TestChain` type have been replaced with `IBCClientHeader`. This function will construct a `07-tendermint` header to update the light client on the counterparty chain. The trusted height must be passed in as a non-zero height.
-- `GetValsAtHeight` has been renamed to `GetTrustedValidators`
-- `AssertEventsLegacy` function of `ibctesting` package (alias for `"github.com/cosmos/ibc-go/v9/testing"`)  has been removed and `AssertEvents` function should be used instead (ref: [#6070](https://github.com/cosmos/ibc-go/pull/6070)).
-
-```diff
-// testing/events.go
-- func AssertEventsLegacy(
--   suite *testifysuite.Suite,
--   expected EventsMap,
--   actual []abci.Event,
-- )
-
-func AssertEvents(
-  suite *testifysuite.Suite,
-  expected []abci.Event,
-  actual []abci.Event,
-)
-```
-
-### IBC core
-
-- `UnmarshalPacketData` now takes in the context, portID, and channelID. This allows the packet data to be unmarshaled based on the channel version.
-- `Router` reference has been removed from IBC core keeper: [#6138](https://github.com/cosmos/ibc-go/pull/6138)
-
 ### ICS20 - Transfer
 
 - With support for multidenom transfer packets, the `NewMsgTransfer` constructor function to create a new `MsgTransfer` instance now accepts multiple coins instead of just one:
@@ -133,6 +88,56 @@ func NewMsgModuleQuerySafe(
 ) *MsgModuleQuerySafe {
 ```
 
+### IBC core
+
+### API removals
+
+- The `exported.ChannelI` and `exported.CounterpartyChannelI` interfaces have been removed. Please use the concrete types.
+- The `exported.ConnectionI` and `exported.CounterpartyConnectionI` interfaces have been removed. Please use the concrete types.
+- The `exported.Proof` interface has been removed. Please use the `MerkleProof` concrete type.
+- The functions `GetState()`, `GetOrdering()`, `GetCounterparty()`, `GetConnectionHops()`, `GetVersion()` of the `Channel` type have been removed.
+- The functions `GetPortID()`, `GetChannelID()` of the `CounterpartyChannel` type have been removed.
+- The functions `GetClientID()`, `GetState()`, `GetCounterparty()`, `GetVersions()`, and `GetDelayPeriod` of the `Connection` type have been removed. 
+- The functions `GetClientID()`, `GetConnectionID()`, and `GetPrefix()` of the `CounterpartyConnection` type have been removed. 
+- The utility function `QueryLatestConsensusState` of `04-channel` CLI has been removed.
+- `UnmarshalPacketData` now takes in the context, portID, and channelID. This allows the packet data to be unmarshaled based on the channel version.
+- `Router` reference has been removed from IBC core keeper: [#6138](https://github.com/cosmos/ibc-go/pull/6138). Please use `PortKeeper.Router` instead.
+
+### 02-client
+
+- The `QueryVerifyMembershipRequest` protobuf message has been modified to include `commitment.v2.MerklePath`. The deprecated `commitment.v1.MerklePath` field has been `reserved`. [See 23-commitment](#23-commitment)
+
+### 23-commitment
+
+- The `MerklePath` type has been deprecated and a new `commitment.v2.MerklePath` type has been introduced (ref: [#6644](https://github.com/cosmos/ibc-go/pull/6644)). The new `commitment.v2.MerklePath` contains `repeated bytes` in favour of `repeated string`. This allows users to prove values stored under keys which contain non-utf8 encoded symbols. As a result, changes have been made to the 02-client `Query` service and 08-wasm contract API messages for JSON blobs. See [02-client](#02-client) and [08-wasm](#08-wasm), respectively.
+
+### IBC testing package
+
+- The `mock.PV` type has been removed in favour of [`cmttypes.MockPV`](https://github.com/cometbft/cometbft/blob/v0.38.5/types/priv_validator.go#L50) ([#5709](https://github.com/cosmos/ibc-go/pull/5709)).
+- Functions `ConstructUpdateTMClientHeader` and `ConstructUpdateTMClientHeaderWithTrustedHeight` of `TestChain` type have been replaced with `IBCClientHeader`. This function will construct a `07-tendermint` header to update the light client on the counterparty chain. The trusted height must be passed in as a non-zero height.
+- `GetValsAtHeight` has been renamed to `GetTrustedValidators`
+- `AssertEventsLegacy` function of `ibctesting` package (alias for `"github.com/cosmos/ibc-go/v9/testing"`)  has been removed and `AssertEvents` function should be used instead (ref: [#6070](https://github.com/cosmos/ibc-go/pull/6070)).
+
+```diff
+// testing/events.go
+- func AssertEventsLegacy(
+-   suite *testifysuite.Suite,
+-   expected EventsMap,
+-   actual []abci.Event,
+- )
+
+func AssertEvents(
+  suite *testifysuite.Suite,
+  expected []abci.Event,
+  actual []abci.Event,
+)
+```
+
+#### API deprecation notice
+
+The testing package functions `coordinator.Setup`, `coordinator.SetupClients`, `coordinator.SetupConnections`, `coordinator.CreateConnections`, and `coordinator.CreateChannels` have been deprecated and will be removed in v10.
+Please use the new functions `path.Setup`, `path.SetupClients`, `path.SetupConnections`, `path.CreateConnections`, `path.CreateChannels`.
+
 ## Relayers
 
 - Renaming of event attribute keys in [#5603](https://github.com/cosmos/ibc-go/pull/5603).
@@ -177,5 +182,6 @@ The `IterateConsensusMetadata` function has been removed.
 
 ### 08-wasm
 
-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 `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 `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.