feat: channel aliasing with migration (#8473)

Co-authored-by: Gjermund Garaba <[email protected]>

Author: AdityaSripal

docs/docs/02-apps/01-transfer/10-IBCv2-transfer.md

@@ -63,3 +63,27 @@ Because IBC v2 no longer uses channels, it is no longer possible to rely on a fi
 ## Changes to the application module interface
 
 Instead of implementing token transfer for `port.IBCModule`, IBC v2 uses the new application interface `api.IBCModule`. More information on the interface differences can be found in the [application section](../../01-ibc/03-apps/00-ibcv2apps.md). 
+
+## MsgTransfer Entrypoint
+
+The `MsgTransfer` entrypoint has been retained in order to retain support for the common entrypoint integrated in most existing frontends.
+
+If `MsgTransfer` is used with a clientID as the `msg.SourceChannel` then the handler will automatically use the IBC v2 protocol. It will internally call the `MsgSendPacket` endpoint so that the execution flow is the same in the state machine for all IBC v2 packets while still presenting the same endpoint for users.
+
+Of course, we want to still retain support for sending v2 packets on existing channels. The denominations of tokens once they leave the origin chain are prefixed by the port and channel ID in IBC v1. Moreover, the transfer escrow accounts holding the original tokens are generated from the channel IDs. Thus, if we wish to interact these remote tokens using IBC v2, we must still use the v1 channel identifiers that they were originally sent with.
+
+Thus, `MsgTransfer` has an additional `UseAliasing` boolean field to indicate that we wish to use IBC v2 protocol while still using the old v1 channel identifiers. This enables users to interact with the same tokens, DEX pools, and cross-chain DEFI protocols using the same denominations that they had previously with the IBC v2 protocol. To use the `MsgTransfer` with aliasing we can submit the message like so:
+
+```go
+MsgTransfer{
+	SourcePort:       "transfer",
+	SourceChannel:    "channel-4", //note: we are using an existing v1 channel identiifer
+	Token:            "uatom",
+	Sender:           {senderAddr},
+	Receiver:         {receiverAddr},
+	TimeoutHeight:    ZeroHeight, // note: IBC v2 does not use timeout height
+	TimeoutTimestamp: 100_000_000,
+	Memo:             "",
+	UseAliasing:      true, // set aliasing to true so the handler uses IBC v2 instead of IBC v1
+}
+```

modules/apps/transfer/keeper/msg_server.go

@@ -53,20 +53,21 @@ func (k Keeper) Transfer(goCtx context.Context, msg *types.MsgTransfer) (*types.
 		return nil, errorsmod.Wrapf(err, "failed to validate %s packet data", types.V1)
 	}
 
-	// if a channel exists with source channel, then use IBC V1 protocol
-	// otherwise use IBC V2 protocol
-	channel, isIBCV1 := k.channelKeeper.GetChannel(ctx, msg.SourcePort, msg.SourceChannel)
+	// if the channel does not exist, or we are using channel aliasing then use IBC V2 protocol
+	// otherwise use IBC V1 protocol
+	channel, hasChannel := k.channelKeeper.GetChannel(ctx, msg.SourcePort, msg.SourceChannel)
+	isIBCV2 := !hasChannel || msg.UseAliasing
 
 	var sequence uint64
-	if isIBCV1 {
+	if isIBCV2 {
+		// otherwise try to send an IBC V2 packet, if the sourceChannel is not a IBC V2 client
+		// then core IBC will return a CounterpartyNotFound error
+		sequence, err = k.transferV2Packet(ctx, msg.Encoding, msg.SourceChannel, msg.TimeoutTimestamp, packetData)
+	} else {
 		// if a V1 channel exists for the source channel, then use IBC V1 protocol
 		sequence, err = k.transferV1Packet(ctx, msg.SourceChannel, token, msg.TimeoutHeight, msg.TimeoutTimestamp, packetData)
 		// telemetry for transfer occurs here, in IBC V2 this is done in the onSendPacket callback
 		telemetry.ReportTransfer(msg.SourcePort, msg.SourceChannel, channel.Counterparty.PortId, channel.Counterparty.ChannelId, token)
-	} else {
-		// otherwise try to send an IBC V2 packet, if the sourceChannel is not a IBC V2 client
-		// then core IBC will return a CounterpartyNotFound error
-		sequence, err = k.transferV2Packet(ctx, msg.Encoding, msg.SourceChannel, msg.TimeoutTimestamp, packetData)
 	}
 	if err != nil {
 		return nil, err

modules/apps/transfer/types/msgs.go

@@ -8,6 +8,7 @@ import (
 	sdk "github.com/cosmos/cosmos-sdk/types"
 
 	clienttypes "github.com/cosmos/ibc-go/v10/modules/core/02-client/types"
+	channeltypes "github.com/cosmos/ibc-go/v10/modules/core/04-channel/types"
 	host "github.com/cosmos/ibc-go/v10/modules/core/24-host"
 	ibcerrors "github.com/cosmos/ibc-go/v10/modules/core/errors"
 )
@@ -61,13 +62,35 @@ func NewMsgTransfer(
 	}
 }
 
+// NewMsgTransferAliased creates a new MsgTransfer instance
+// with isV2 set to true, indicating that it is using the V2 protocol
+// with v1 channel identifiers.
+func NewMsgTransferAliased(
+	sourcePort, sourceChannel string,
+	token sdk.Coin, sender, receiver string,
+	timeoutHeight clienttypes.Height, timeoutTimestamp uint64,
+	memo string,
+) *MsgTransfer {
+	return &MsgTransfer{
+		SourcePort:       sourcePort,
+		SourceChannel:    sourceChannel,
+		Token:            token,
+		Sender:           sender,
+		Receiver:         receiver,
+		TimeoutHeight:    timeoutHeight,
+		TimeoutTimestamp: timeoutTimestamp,
+		Memo:             memo,
+		UseAliasing:      true, // This indicates that the message is using the V2 protocol with aliased channel identifiers
+	}
+}
+
 // NewMsgTransferWithEncoding creates a new MsgTransfer instance
 // with the provided encoding
 func NewMsgTransferWithEncoding(
 	sourcePort, sourceChannel string,
 	token sdk.Coin, sender, receiver string,
 	timeoutHeight clienttypes.Height, timeoutTimestamp uint64,
-	memo string, encoding string,
+	memo string, encoding string, useAliasing bool,
 ) *MsgTransfer {
 	return &MsgTransfer{
 		SourcePort:       sourcePort,
@@ -79,6 +102,7 @@ func NewMsgTransferWithEncoding(
 		TimeoutTimestamp: timeoutTimestamp,
 		Memo:             memo,
 		Encoding:         encoding,
+		UseAliasing:      useAliasing,
 	}
 }
 
@@ -118,8 +142,18 @@ func (msg MsgTransfer) validateIdentifiers() error {
 	if err := host.PortIdentifierValidator(msg.SourcePort); err != nil {
 		return errorsmod.Wrapf(err, "invalid source port ID %s", msg.SourcePort)
 	}
-	if err := host.ChannelIdentifierValidator(msg.SourceChannel); err != nil {
-		return errorsmod.Wrapf(err, "invalid source channel ID %s", msg.SourceChannel)
+	// if we are using aliasing, then the source channel must be in the channel id format
+	// expected by ibc-go
+	// otherwise, it may be either a client id using v2 directly or a channel id using ibc v1
+	// thus, we perform a less strict check
+	if msg.UseAliasing {
+		if _, err := channeltypes.ParseChannelSequence(msg.SourceChannel); err != nil {
+			return errorsmod.Wrapf(err, "invalid source channel ID %s", msg.SourceChannel)
+		}
+	} else {
+		if err := host.ChannelIdentifierValidator(msg.SourceChannel); err != nil {
+			return errorsmod.Wrapf(err, "invalid source channel ID %s", msg.SourceChannel)
+		}
 	}
 
 	return nil

modules/apps/transfer/types/msgs_test.go

@@ -27,7 +27,7 @@ const (
 	// 195 characters
 	invalidLongPort = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis eros neque, ultricies vel ligula ac, convallis porttitor elit. Maecenas tincidunt turpis elit, vel faucibus nisl pellentesque sodales"
 
-	validChannel        = "testchannel"
+	validChannel        = "channel-5"
 	eurekaClient        = "07-tendermint-0"
 	invalidChannel      = "(invalidchannel1)"
 	invalidShortChannel = "invalid"
@@ -58,11 +58,13 @@ func TestMsgTransferValidation(t *testing.T) {
 		expError error
 	}{
 		{"valid msg with base denom", types.NewMsgTransfer(validPort, validChannel, coin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), nil},
+		{"valid aliased channel", types.NewMsgTransferAliased(validPort, validChannel, coin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), nil},
+		{"valid aliased channel with encoding", types.NewMsgTransferWithEncoding(validPort, validChannel, coin, sender, receiver, clienttypes.ZeroHeight(), 100, "", "application/json", true), nil},
 		{"valid eureka msg with base denom", types.NewMsgTransfer(validPort, eurekaClient, coin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), nil},
-		{"valid eureka msg with base denom and encoding", types.NewMsgTransferWithEncoding(validPort, eurekaClient, coin, sender, receiver, clienttypes.ZeroHeight(), 100, "", "application/json"), nil},
+		{"valid eureka msg with base denom and encoding", types.NewMsgTransferWithEncoding(validPort, eurekaClient, coin, sender, receiver, clienttypes.ZeroHeight(), 100, "", "application/json", false), nil},
 		{"valid msg with trace hash", types.NewMsgTransfer(validPort, validChannel, ibcCoin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), nil},
 		{"valid eureka msg with trace hash", types.NewMsgTransfer(validPort, eurekaClient, ibcCoin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), nil},
-		{"valid eureka msg with trace hash with encoding", types.NewMsgTransferWithEncoding(validPort, eurekaClient, ibcCoin, sender, receiver, clienttypes.ZeroHeight(), 100, "", "application/json"), nil},
+		{"valid eureka msg with trace hash with encoding", types.NewMsgTransferWithEncoding(validPort, eurekaClient, ibcCoin, sender, receiver, clienttypes.ZeroHeight(), 100, "", "application/json", false), nil},
 		{"invalid ibc denom", types.NewMsgTransfer(validPort, validChannel, invalidIBCCoin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), ibcerrors.ErrInvalidCoins},
 		{"too short port id", types.NewMsgTransfer(invalidShortPort, validChannel, coin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), host.ErrInvalidID},
 		{"too long port id", types.NewMsgTransfer(invalidLongPort, validChannel, coin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), host.ErrInvalidID},
@@ -77,6 +79,7 @@ func TestMsgTransferValidation(t *testing.T) {
 		{"missing recipient address", types.NewMsgTransfer(validPort, validChannel, coin, sender, "", clienttypes.ZeroHeight(), 100, ""), ibcerrors.ErrInvalidAddress},
 		{"too long recipient address", types.NewMsgTransfer(validPort, validChannel, coin, sender, ibctesting.GenerateString(types.MaximumReceiverLength+1), clienttypes.ZeroHeight(), 100, ""), ibcerrors.ErrInvalidAddress},
 		{"empty coin", types.NewMsgTransfer(validPort, validChannel, sdk.Coin{}, sender, receiver, clienttypes.ZeroHeight(), 100, ""), ibcerrors.ErrInvalidCoins},
+		{"invalid aliased channel", types.NewMsgTransferAliased(validPort, eurekaClient, coin, sender, receiver, clienttypes.ZeroHeight(), 100, ""), host.ErrInvalidID},
 	}
 
 	for _, tc := range testCases {