chore: denom traces migration handler

docs/migrations/support-denoms-with-slashes.md

@@ -28,41 +28,17 @@ The transfer module will now support slashes in base denoms, so we must iterate
 ### Upgrade Proposal
 
 ```go
-// Here the upgrade name is the upgrade name set by the chain
-app.UpgradeKeeper.SetUpgradeHandler("supportSlashedDenomsUpgrade",
+app.UpgradeKeeper.SetUpgradeHandler("MigrateTraces",
     func(ctx sdk.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
-        // list of traces that must replace the old traces in store
-        var newTraces []ibctransfertypes.DenomTrace
-        app.TransferKeeper.IterateDenomTraces(ctx,
-            func(dt ibctransfertypes.DenomTrace) bool {
-                // check if the new way of splitting FullDenom
-                // into Trace and BaseDenom passes validation and
-                // is the same as the current DenomTrace.
-                // If it isn't then store the new DenomTrace in the list of new traces.
-                newTrace := ibctransfertypes.ParseDenomTrace(dt.GetFullDenomPath())
-                if err := newTrace.Validate(); err == nil && !equalTraces(newTrace, dt) {
-                    newTraces = append(newTraces, newTrace)
-                }
-
-                return false
-            })
-
-        // replace the outdated traces with the new trace information
-        for _, nt := range newTraces {
-            app.TransferKeeper.SetDenomTrace(ctx, nt)
-        }
-
+        // transfer module consensus version has been bumped to 2
         return app.mm.RunMigrations(ctx, app.configurator, fromVM)
     })
-
-func equalTraces(dtA, dtB ibctransfertypes.DenomTrace) bool {
-    return dtA.BaseDenom == dtB.BaseDenom && dtA.Path == dtB.Path
-}
+
 ```
 
 This is only necessary if there are denom traces in the store with incorrect trace information from previously received coins that had a slash in the base denom. However, it is recommended that any chain upgrading to support base denominations with slashes runs this code for safety.
 
-For a more detailed sample, please check out the code changes in [this pull request](https://github.com/cosmos/ibc-go/pull/1527).
+For a more detailed sample, please check out the code changes in [this pull request](https://github.com/cosmos/ibc-go/pull/1680).
 
 ### Genesis Migration
 

docs/migrations/v3-to-v4.md

@@ -18,7 +18,27 @@ No genesis or in-place migrations required when upgrading from v1 or v2 of ibc-g
 
 ## Chains
 
-- No relevant changes were made in this release.
+### Migration to fix support for base denoms with slashes
+
+As part of [v1.5.0](https://github.com/cosmos/ibc-go/releases/tag/v1.5.0), [v2.3.0](https://github.com/cosmos/ibc-go/releases/tag/v2.3.0) and [v3.1.0](https://github.com/cosmos/ibc-go/releases/tag/v3.1.0) some [migration handler code sample was documented](https://github.com/cosmos/ibc-go/blob/main/docs/migrations/support-denoms-with-slashes.md#upgrade-proposal) that needs to run in order to correct the trace information of coins transferred using ICS20 whose base denom contains slashes.
+
+Based on feedback from the community we add now an improved solution to run the same migration that does not require copying a large piece of code over from the migration document, but instead requires only adding a one-line upgrade handler.
+
+If the chain will migrate to supporting base denoms with slashes, it must set the appropriate params during the execution of the upgrade handler in `app.go`: 
+```go
+app.UpgradeKeeper.SetUpgradeHandler("MigrateTraces",
+    func(ctx sdk.Context, _ upgradetypes.Plan, fromVM module.VersionMap) (module.VersionMap, error) {
+        // transfer module consensus version has been bumped to 2
+        return app.mm.RunMigrations(ctx, app.configurator, fromVM)
+    })
+
+```
+
+If a chain receives coins of a base denom with slashes before it upgrades to supporting it, the receive may pass however the trace information will be incorrect.
+
+E.g. If a base denom of `testcoin/testcoin/testcoin` is sent to a chain that does not support slashes in the base denom, the receive will be successful. However, the trace information stored on the receiving chain will be: `Trace: "transfer/{channel-id}/testcoin/testcoin", BaseDenom: "testcoin"`.
+
+This incorrect trace information must be corrected when the chain does upgrade to fully supporting denominations with slashes.
 
 ## IBC Apps
 

modules/apps/transfer/keeper/migrations.go

@@ -0,0 +1,52 @@
+package keeper
+
+import (
+	sdk "github.com/cosmos/cosmos-sdk/types"
+
+	"github.com/cosmos/ibc-go/v4/modules/apps/transfer/types"
+)
+
+// Migrator is a struct for handling in-place store migrations.
+type Migrator struct {
+	keeper Keeper
+}
+
+// NewMigrator returns a new Migrator.
+func NewMigrator(keeper Keeper) Migrator {
+	return Migrator{keeper: keeper}
+}
+
+// MigrateTraces migrates the DenomTraces to the correct format, accounting for slashes in the BaseDenom.
+func (m Migrator) MigrateTraces(ctx sdk.Context) error {
+	var iterErr error
+
+	// list of traces that must replace the old traces in store
+	var newTraces []types.DenomTrace
+	m.keeper.IterateDenomTraces(ctx,
+		func(dt types.DenomTrace) (stop bool) {
+			// check if the new way of splitting FullDenom
+			// into Trace and BaseDenom passes validation and
+			// is the same as the current DenomTrace.
+			// If it isn't then store the new DenomTrace in the list of new traces.
+			newTrace := types.ParseDenomTrace(dt.GetFullDenomPath())
+			err := newTrace.Validate()
+			if err != nil {
+				iterErr = err
+				return true
+			}
+			if !equalTraces(newTrace, dt) {
+				newTraces = append(newTraces, newTrace)
+			}
+			return false
+		})
+
+	// replace the outdated traces with the new trace information
+	for _, nt := range newTraces {
+		m.keeper.SetDenomTrace(ctx, nt)
+	}
+	return iterErr
+}
+
+func equalTraces(dtA, dtB types.DenomTrace) bool {
+	return dtA.BaseDenom == dtB.BaseDenom && dtA.Path == dtB.Path
+}

modules/apps/transfer/keeper/migrations_test.go

@@ -0,0 +1,110 @@
+package keeper_test
+
+import (
+	"fmt"
+
+	transferkeeper "github.com/cosmos/ibc-go/v4/modules/apps/transfer/keeper"
+	transfertypes "github.com/cosmos/ibc-go/v4/modules/apps/transfer/types"
+)
+
+func (suite *KeeperTestSuite) TestMigratorMigrateTraces() {
+
+	testCases := []struct {
+		msg            string
+		malleate       func()
+		expectedTraces transfertypes.Traces
+	}{
+
+		{
+			"success: two slashes in base denom",
+			func() {
+				suite.chainA.GetSimApp().TransferKeeper.SetDenomTrace(
+					suite.chainA.GetContext(),
+					transfertypes.DenomTrace{
+						BaseDenom: "1", Path: "transfer/channel-0/gamm/pool",
+					})
+			},
+			transfertypes.Traces{
+				{
+					BaseDenom: "gamm/pool/1", Path: "transfer/channel-0",
+				},
+			},
+		},
+		{
+			"success: one slash in base denom",
+			func() {
+				suite.chainA.GetSimApp().TransferKeeper.SetDenomTrace(
+					suite.chainA.GetContext(),
+					transfertypes.DenomTrace{
+						BaseDenom: "", Path: "transfer/channel-149/erc/0x85bcBCd7e79Ec36f4fBBDc54F90C643d921151AA",
+					})
+			},
+			transfertypes.Traces{
+				{
+					BaseDenom: "erc/0x85bcBCd7e79Ec36f4fBBDc54F90C643d921151AA", Path: "transfer/channel-149",
+				},
+			},
+		},
+		{
+			"success: multiple slashes in a row in base denom",
+			func() {
+				suite.chainA.GetSimApp().TransferKeeper.SetDenomTrace(
+					suite.chainA.GetContext(),
+					transfertypes.DenomTrace{
+						BaseDenom: "1", Path: "transfer/channel-5/gamm//pool",
+					})
+			},
+			transfertypes.Traces{
+				{
+					BaseDenom: "gamm//pool/1", Path: "transfer/channel-5",
+				},
+			},
+		},
+		{
+			"success: multihop base denom",
+			func() {
+				suite.chainA.GetSimApp().TransferKeeper.SetDenomTrace(
+					suite.chainA.GetContext(),
+					transfertypes.DenomTrace{
+						BaseDenom: "transfer/channel-1/uatom", Path: "transfer/channel-0",
+					})
+			},
+			transfertypes.Traces{
+				{
+					BaseDenom: "uatom", Path: "transfer/channel-0/transfer/channel-1",
+				},
+			},
+		},
+		{
+			// the expected value will change with the implementation of the fix for #1698
+			"no change: non-standard port",
+			func() {
+				suite.chainA.GetSimApp().TransferKeeper.SetDenomTrace(
+					suite.chainA.GetContext(),
+					transfertypes.DenomTrace{
+						BaseDenom: "customport/channel-7/uatom", Path: "transfer/channel-0/transfer/channel-1",
+					})
+			},
+			transfertypes.Traces{
+				{
+					BaseDenom: "customport/channel-7/uatom", Path: "transfer/channel-0/transfer/channel-1",
+				},
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		suite.Run(fmt.Sprintf("case %s", tc.msg), func() {
+			suite.SetupTest() // reset
+
+			tc.malleate() // explicitly set up denom traces
+
+			migrator := transferkeeper.NewMigrator(suite.chainA.GetSimApp().TransferKeeper)
+			err := migrator.MigrateTraces(suite.chainA.GetContext())
+			suite.Require().NoError(err)
+
+			traces := suite.chainA.GetSimApp().TransferKeeper.GetAllDenomTraces(suite.chainA.GetContext())
+			suite.Require().Equal(tc.expectedTraces, traces)
+		})
+	}
+}

modules/apps/transfer/module.go

@@ -120,6 +120,11 @@ func (am AppModule) LegacyQuerierHandler(*codec.LegacyAmino) sdk.Querier {
 func (am AppModule) RegisterServices(cfg module.Configurator) {
 	types.RegisterMsgServer(cfg.MsgServer(), am.keeper)
 	types.RegisterQueryServer(cfg.QueryServer(), am.keeper)
+
+	m := keeper.NewMigrator(am.keeper)
+	if err := cfg.RegisterMigration(types.ModuleName, 1, m.MigrateTraces); err != nil {
+		panic(fmt.Sprintf("failed to migrate transfer app from version 1 to 2: %v", err))
+	}
 }
 
 // InitGenesis performs genesis initialization for the ibc-transfer module. It returns
@@ -139,7 +144,7 @@ func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.Raw
 }
 
 // ConsensusVersion implements AppModule/ConsensusVersion.
-func (AppModule) ConsensusVersion() uint64 { return 1 }
+func (AppModule) ConsensusVersion() uint64 { return 2 }
 
 // BeginBlock implements the AppModule interface
 func (am AppModule) BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock) {

modules/apps/transfer/types/trace.go

@@ -71,6 +71,9 @@ func (dt DenomTrace) GetFullDenomPath() string {
 	if dt.Path == "" {
 		return dt.BaseDenom
 	}
+	if dt.BaseDenom == "" {
+		return dt.Path
+	}
 	return dt.GetPrefix() + dt.BaseDenom
 }