Added optional packet metadata to the packet and message types (cosmo…

…s#2305)

* added optional packet metadata to the packet and message types

* added docs

* breaking the api (backports should add a utility function for this)

* adding nil metadata on all the calls

* added metadata to the cli

* added events

* breaking api for FungibleTokenPacketData

* hex encoding metadata

* added abstraction

* fixed bad merge

* added tests with metadata

* added missing metadata to packet for recv

* cleaning up metadata on every test

* reset metadata

* added metadata flag

* lint

* Update modules/apps/transfer/client/cli/tx.go

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

* fixed bad call in tests

Co-authored-by: Damian Nolan <damiannolan@gmail.com>

docs/apps/transfer/events.md

@@ -23,6 +23,7 @@ order: 5
 | fungible_token_packet | denom | {denom} |
 | fungible_token_packet | amount | {amount} |
 | fungible_token_packet | success | {ackSuccess} |
+| fungible_token_packet | metadata | {metadata} |
 | denomination_trace | trace_hash | {hex_hash} |
 
 ## `OnAcknowledgePacket` callback
@@ -34,6 +35,7 @@ order: 5
 | fungible_token_packet | receiver | {receiver} |
 | fungible_token_packet | denom | {denom} |
 | fungible_token_packet | amount | {amount} |
+| fungible_token_packet | metadata | {metadata} |
 | fungible_token_packet | acknowledgement | {ack.String()} |
 | fungible_token_packet | success | error | {ack.Response} |
 
@@ -45,3 +47,4 @@ order: 5
 | fungible_token_packet | refund_receiver | {receiver} |
 | fungible_token_packet | denom | {denom} |
 | fungible_token_packet | amount | {amount} |
+| fungible_token_packet | metadata | {metadata} |

docs/apps/transfer/messages.md

@@ -17,6 +17,7 @@ type MsgTransfer struct {
  Receiver string
  TimeoutHeight ibcexported.Height
  TimeoutTimestamp uint64
+ Metadata []byte
 }
 ```
 

docs/ibc/proto-docs.md

@@ -2255,6 +2255,7 @@ https://github.com/cosmos/ibc/tree/master/spec/app/ics-020-fungible-token-transf
 | `receiver` | [string](#string) | | the recipient address on the destination chain |
 | `timeout_height` | [ibc.core.client.v1.Height](#ibc.core.client.v1.Height) | | Timeout height relative to the current block height. The timeout is disabled when set to 0. |
 | `timeout_timestamp` | [uint64](#uint64) | | Timeout timestamp in absolute nanoseconds since unix epoch. The timeout is disabled when set to 0. |
+| `metadata` | [bytes](#bytes) | | optional metadata |
 
 
 
@@ -2269,7 +2270,7 @@ MsgTransferResponse defines the Msg/Transfer response type.
 
 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| `sequence` | [uint64](#uint64) | | sequence number of the packet on the channel. |
+| `sequence` | [uint64](#uint64) | | sequence number of the transfer packet sent |
 
 
 
@@ -2316,6 +2317,7 @@ https://github.com/cosmos/ibc/tree/master/spec/app/ics-020-fungible-token-transf
 | `amount` | [string](#string) | | the token amount to be transferred |
 | `sender` | [string](#string) | | the sender address |
 | `receiver` | [string](#string) | | the recipient address on the destination chain |
+| `metadata` | [bytes](#bytes) | | optional metadata |
 
 
 

go.mod

@@ -43,7 +43,7 @@ require (
  github.com/bgentry/go-netrc v0.0.0-20140422174119-9fd32a8b3d3d // indirect
  github.com/bgentry/speakeasy v0.1.0 // indirect
  github.com/btcsuite/btcd v0.22.1 // indirect
- github.com/cenkalti/backoff/v4 v4.1.3 // indirect
+ github.com/cenkalti/backoff/v4 v4.1.1 // indirect
  github.com/cespare/xxhash v1.1.0 // indirect
  github.com/cespare/xxhash/v2 v2.1.2 // indirect
  github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e // indirect

go.sum

@@ -180,9 +180,8 @@ github.com/c-bata/go-prompt v0.2.2/go.mod h1:VzqtzE2ksDBcdln8G7mk2RX9QyGjH+OVqOC
 github.com/casbin/casbin/v2 v2.1.2/go.mod h1:YcPU1XXisHhLzuxH9coDNf2FbKpjGlbCg3n9yuLkIJQ=
 github.com/cenkalti/backoff v2.2.1+incompatible h1:tNowT99t7UNflLxfYYSlKYsBpXdEet03Pg2g16Swow4=
 github.com/cenkalti/backoff v2.2.1+incompatible/go.mod h1:90ReRw6GdpyfrHakVjL/QHaoyV4aDUVVkXQJJJ3NXXM=
+github.com/cenkalti/backoff/v4 v4.1.1 h1:G2HAfAmvm/GcKan2oOQpBXOd2tT2G57ZnZGWa1PxPBQ=
 github.com/cenkalti/backoff/v4 v4.1.1/go.mod h1:scbssz8iZGpm3xbr14ovlUdkxfGXNInqkPWOWmG2CLw=
-github.com/cenkalti/backoff/v4 v4.1.3 h1:cFAlzYUlVYDysBEH2T5hyJZMh3+5+WCBvSnK6Q8UtC4=
-github.com/cenkalti/backoff/v4 v4.1.3/go.mod h1:scbssz8iZGpm3xbr14ovlUdkxfGXNInqkPWOWmG2CLw=
 github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/cespare/cp v0.1.0/go.mod h1:SOGHArjBr4JWaSDEVpWpo/hNg6RoKrls6Oh40hiwW+s=
 github.com/cespare/xxhash v1.1.0 h1:a6HrQnmkObjyL+Gs60czilIUGqrzKutQD6XZog3p+ko=

modules/apps/29-fee/transfer_test.go

@@ -30,7 +30,7 @@ func (suite *FeeTestSuite) TestFeeTransfer() {
 
  msgs := []sdk.Msg{
  types.NewMsgPayPacketFee(fee, path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, suite.chainA.SenderAccount.GetAddress().String(), nil),
- transfertypes.NewMsgTransfer(path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, coin, suite.chainA.SenderAccount.GetAddress().String(), suite.chainB.SenderAccount.GetAddress().String(), clienttypes.NewHeight(1, 100), 0),
+ transfertypes.NewMsgTransfer(path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, coin, suite.chainA.SenderAccount.GetAddress().String(), suite.chainB.SenderAccount.GetAddress().String(), clienttypes.NewHeight(1, 100), 0, nil),
  }
  res, err := suite.chainA.SendMsgs(msgs...)
  suite.Require().NoError(err) // message committed

modules/apps/transfer/client/cli/tx.go

@@ -22,6 +22,7 @@ const (
  flagPacketTimeoutHeight = "packet-timeout-height"
  flagPacketTimeoutTimestamp = "packet-timeout-timestamp"
  flagAbsoluteTimeouts = "absolute-timeouts"
+ flagMetadata = "metadata"
 )
 
 // NewTransferTxCmd returns the command to create a NewMsgTransfer transaction
@@ -76,6 +77,11 @@ corresponding to the counterparty channel. Any timeout set to 0 is disabled.`),
  return err
  }
 
+ metadataStr, err := cmd.Flags().GetString(flagMetadata)
+ if err != nil {
+ return err
+ }
+
  // if the timeouts are not absolute, retrieve latest block height and block timestamp
  // for the consensus state connected to the destination port/channel
  if !absoluteTimeouts {
@@ -111,7 +117,7 @@ corresponding to the counterparty channel. Any timeout set to 0 is disabled.`),
  }
 
  msg := types.NewMsgTransfer(
- srcPort, srcChannel, coin, sender, receiver, timeoutHeight, timeoutTimestamp,
+ srcPort, srcChannel, coin, sender, receiver, timeoutHeight, timeoutTimestamp, []byte(metadataStr),
  )
  return tx.GenerateOrBroadcastTxCLI(clientCtx, cmd.Flags(), msg)
  },
@@ -120,6 +126,7 @@ corresponding to the counterparty channel. Any timeout set to 0 is disabled.`),
  cmd.Flags().String(flagPacketTimeoutHeight, types.DefaultRelativePacketTimeoutHeight, "Packet timeout block height. The timeout is disabled when set to 0-0.")
  cmd.Flags().Uint64(flagPacketTimeoutTimestamp, types.DefaultRelativePacketTimeoutTimestamp, "Packet timeout timestamp in nanoseconds from now. Default is 10 minutes. The timeout is disabled when set to 0.")
  cmd.Flags().Bool(flagAbsoluteTimeouts, false, "Timeout flags are used as absolute timeouts.")
+ cmd.Flags().String(flagMetadata, "", "Metadata to be sent along with the packet. The CLI accepts only strings here but you can construct a packet with arbitrary bytes via code.")
  flags.AddTxFlagsToCmd(cmd)
 
  return cmd

modules/apps/transfer/ibc_module.go

@@ -1,6 +1,7 @@
 package transfer
 
 import (
+ "encoding/hex"
  "fmt"
  "math"
  "strings"
@@ -194,6 +195,7 @@ func (im IBCModule) OnRecvPacket(
  sdk.NewAttribute(types.AttributeKeyReceiver, data.Receiver),
  sdk.NewAttribute(types.AttributeKeyDenom, data.Denom),
  sdk.NewAttribute(types.AttributeKeyAmount, data.Amount),
+ sdk.NewAttribute(types.AttributeKeyMetadata, hex.EncodeToString(data.Metadata)),
  sdk.NewAttribute(types.AttributeKeyAckSuccess, fmt.Sprintf("%t", ack.Success())),
  }
 
@@ -240,6 +242,7 @@ func (im IBCModule) OnAcknowledgementPacket(
  sdk.NewAttribute(types.AttributeKeyReceiver, data.Receiver),
  sdk.NewAttribute(types.AttributeKeyDenom, data.Denom),
  sdk.NewAttribute(types.AttributeKeyAmount, data.Amount),
+ sdk.NewAttribute(types.AttributeKeyMetadata, hex.EncodeToString(data.Metadata)),
  sdk.NewAttribute(types.AttributeKeyAck, ack.String()),
  ),
  )
@@ -286,6 +289,7 @@ func (im IBCModule) OnTimeoutPacket(
  sdk.NewAttribute(types.AttributeKeyRefundReceiver, data.Sender),
  sdk.NewAttribute(types.AttributeKeyRefundDenom, data.Denom),
  sdk.NewAttribute(types.AttributeKeyRefundAmount, data.Amount),
+ sdk.NewAttribute(types.AttributeKeyMetadata, hex.EncodeToString(data.Metadata)),
  ),
  )
 

modules/apps/transfer/keeper/mbt_relay_test.go

@@ -146,7 +146,8 @@ func FungibleTokenPacketFromTla(packet TlaFungibleTokenPacket) FungibleTokenPack
  DenomFromTla(packet.Data.Denom),
  packet.Data.Amount,
  AddressFromString(packet.Data.Sender),
- AddressFromString(packet.Data.Receiver)),
+ AddressFromString(packet.Data.Receiver),
+ nil),
  }
 }
 
@@ -346,7 +347,8 @@ func (suite *KeeperTestSuite) TestModelBasedRelay() {
  sender,
  tc.packet.Data.Receiver,
  clienttypes.NewHeight(1, 110),
- 0)
+ 0,
+ nil)
  }
  case "OnRecvPacket":
  err = suite.chainB.GetSimApp().TransferKeeper.OnRecvPacket(suite.chainB.GetContext(), packet, tc.packet.Data)

modules/apps/transfer/keeper/msg_server.go

@@ -21,7 +21,7 @@ func (k Keeper) Transfer(goCtx context.Context, msg *types.MsgTransfer) (*types.
 
  sequence, err := k.sendTransfer(
  ctx, msg.SourcePort, msg.SourceChannel, msg.Token, sender, msg.Receiver, msg.TimeoutHeight, msg.TimeoutTimestamp,
- )
+  msg.Metadata)
  if err != nil {
  return nil, err
  }

modules/apps/transfer/keeper/msg_server_test.go

@@ -54,6 +54,7 @@ func (suite *KeeperTestSuite) TestMsgTransfer() {
  path.EndpointA.ChannelID,
  coin, suite.chainA.SenderAccount.GetAddress().String(), suite.chainB.SenderAccount.GetAddress().String(),
  suite.chainB.GetTimeoutHeight(), 0, // only use timeout height
+ []byte("custom metadata"),
  )
 
  tc.malleate()

modules/apps/transfer/keeper/relay.go

@@ -59,6 +59,7 @@ func (k Keeper) SendTransfer(
  receiver string,
  timeoutHeight clienttypes.Height,
  timeoutTimestamp uint64,
+ metadata []byte,
 ) error {
  _, err := k.sendTransfer(
  ctx,
@@ -69,6 +70,7 @@ func (k Keeper) SendTransfer(
  receiver,
  timeoutHeight,
  timeoutTimestamp,
+ metadata,
  )
  return err
 }
@@ -83,6 +85,7 @@ func (k Keeper) sendTransfer(
  receiver string,
  timeoutHeight clienttypes.Height,
  timeoutTimestamp uint64,
+ metadata []byte,
 ) (uint64, error) {
  if !k.GetSendEnabled(ctx) {
  return 0, types.ErrSendDisabled
@@ -163,7 +166,7 @@ func (k Keeper) sendTransfer(
  }
 
  packetData := types.NewFungibleTokenPacketData(
- fullDenomPath, token.Amount.String(), sender.String(), receiver,
+ fullDenomPath, token.Amount.String(), sender.String(), receiver, metadata,
  )
 
  sequence, err := k.ics4Wrapper.SendPacket(ctx, channelCap, sourcePort, sourceChannel, timeoutHeight, timeoutTimestamp, packetData.GetBytes())

modules/apps/transfer/keeper/relay_test.go

@@ -18,10 +18,11 @@ import (
 // chainA and coin that orignate on chainB
 func (suite *KeeperTestSuite) TestSendTransfer() {
  var (
- amount sdk.Coin
- path *ibctesting.Path
- sender sdk.AccAddress
- err error
+ amount sdk.Coin
+ path *ibctesting.Path
+ sender sdk.AccAddress
+ err error
+ metadata []byte
  )
 
  testCases := []struct {
@@ -37,6 +38,14 @@ func (suite *KeeperTestSuite) TestSendTransfer() {
  amount = sdk.NewCoin(sdk.DefaultBondDenom, sdk.NewInt(100))
  }, true, true,
  },
+ {
+ "successful transfer from source chain with metadata",
+ func() {
+ suite.coordinator.CreateTransferChannels(path)
+ amount = sdk.NewCoin(sdk.DefaultBondDenom, sdk.NewInt(100))
+ metadata = []byte("metadata")
+ }, true, true,
+ },
  {
  "successful transfer with coin from counterparty chain",
  func() {
@@ -45,6 +54,15 @@ func (suite *KeeperTestSuite) TestSendTransfer() {
  amount = types.GetTransferCoin(path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, sdk.DefaultBondDenom, sdk.NewInt(100))
  }, false, true,
  },
+ {
+ "successful transfer with coin from counterparty chain with metadata",
+ func() {
+ // send coin from chainA back to chainB
+ suite.coordinator.CreateTransferChannels(path)
+ amount = types.GetTransferCoin(path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, sdk.DefaultBondDenom, sdk.NewInt(100))
+ metadata = []byte("metadata")
+ }, false, true,
+ },
  {
  "source channel not found",
  func() {
@@ -100,18 +118,19 @@ func (suite *KeeperTestSuite) TestSendTransfer() {
  path = NewTransferPath(suite.chainA, suite.chainB)
  suite.coordinator.SetupConnections(path)
  sender = suite.chainA.SenderAccount.GetAddress()
+ metadata = []byte{}
 
  tc.malleate()
 
  if !tc.sendFromSource {
  // send coin from chainB to chainA
  coinFromBToA := sdk.NewCoin(sdk.DefaultBondDenom, sdk.NewInt(100))
- transferMsg := types.NewMsgTransfer(path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, coinFromBToA, suite.chainB.SenderAccount.GetAddress().String(), suite.chainA.SenderAccount.GetAddress().String(), clienttypes.NewHeight(1, 110), 0)
+ transferMsg := types.NewMsgTransfer(path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, coinFromBToA, suite.chainB.SenderAccount.GetAddress().String(), suite.chainA.SenderAccount.GetAddress().String(), clienttypes.NewHeight(1, 110), 0, nil)
  _, err = suite.chainB.SendMsgs(transferMsg)
  suite.Require().NoError(err) // message committed
 
  // receive coin on chainA from chainB
- fungibleTokenPacket := types.NewFungibleTokenPacketData(coinFromBToA.Denom, coinFromBToA.Amount.String(), suite.chainB.SenderAccount.GetAddress().String(), suite.chainA.SenderAccount.GetAddress().String())
+ fungibleTokenPacket := types.NewFungibleTokenPacketData(coinFromBToA.Denom, coinFromBToA.Amount.String(), suite.chainB.SenderAccount.GetAddress().String(), suite.chainA.SenderAccount.GetAddress().String(), nil)
  packet := channeltypes.NewPacket(fungibleTokenPacket.GetBytes(), 1, path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, clienttypes.NewHeight(1, 110), 0)
 
  // get proof of packet commitment from chainB
@@ -128,6 +147,7 @@ func (suite *KeeperTestSuite) TestSendTransfer() {
  err = suite.chainA.GetSimApp().TransferKeeper.SendTransfer(
  suite.chainA.GetContext(), path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, amount,
  sender, suite.chainB.SenderAccount.GetAddress().String(), suite.chainB.GetTimeoutHeight(), 0,
+ metadata,
  )
 
  if tc.expPass {
@@ -148,6 +168,7 @@ func (suite *KeeperTestSuite) TestOnRecvPacket() {
  trace types.DenomTrace
  amount math.Int
  receiver string
+ metadata []byte
  )
 
  testCases := []struct {
@@ -157,7 +178,13 @@ func (suite *KeeperTestSuite) TestOnRecvPacket() {
  expPass bool
  }{
  {"success receive on source chain", func() {}, true, true},
+ {"success receive on source chain with metadata", func() {
+ metadata = []byte("metadata")
+ }, true, true},
  {"success receive with coin from another chain as source", func() {}, false, true},
+ {"success receive with coin from another chain as source with metadata", func() {
+ metadata = []byte("metadata")
+ }, false, true},
  {"empty coin", func() {
  trace = types.DenomTrace{}
  amount = sdk.ZeroInt()
@@ -198,13 +225,14 @@ func (suite *KeeperTestSuite) TestOnRecvPacket() {
  suite.coordinator.Setup(path)
  receiver = suite.chainB.SenderAccount.GetAddress().String() // must be explicitly changed in malleate
 
+ metadata = []byte{} // can be explicitly changed in malleate
  amount = sdk.NewInt(100) // must be explicitly changed in malleate
  seq := uint64(1)
 
  if tc.recvIsSource {
  // send coin from chainB to chainA, receive them, acknowledge them, and send back to chainB
  coinFromBToA := sdk.NewCoin(sdk.DefaultBondDenom, sdk.NewInt(100))
- transferMsg := types.NewMsgTransfer(path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, coinFromBToA, suite.chainB.SenderAccount.GetAddress().String(), suite.chainA.SenderAccount.GetAddress().String(), clienttypes.NewHeight(1, 110), 0)
+ transferMsg := types.NewMsgTransfer(path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, coinFromBToA, suite.chainB.SenderAccount.GetAddress().String(), suite.chainA.SenderAccount.GetAddress().String(), clienttypes.NewHeight(1, 110), 0, metadata)
  res, err := suite.chainB.SendMsgs(transferMsg)
  suite.Require().NoError(err) // message committed
 
@@ -223,13 +251,13 @@ func (suite *KeeperTestSuite) TestOnRecvPacket() {
  }
 
  // send coin from chainA to chainB
- transferMsg := types.NewMsgTransfer(path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, sdk.NewCoin(trace.IBCDenom(), amount), suite.chainA.SenderAccount.GetAddress().String(), receiver, clienttypes.NewHeight(1, 110), 0)
+ transferMsg := types.NewMsgTransfer(path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, sdk.NewCoin(trace.IBCDenom(), amount), suite.chainA.SenderAccount.GetAddress().String(), receiver, clienttypes.NewHeight(1, 110), 0, metadata)
  _, err := suite.chainA.SendMsgs(transferMsg)
  suite.Require().NoError(err) // message committed
 
  tc.malleate()
 
- data := types.NewFungibleTokenPacketData(trace.GetFullDenomPath(), amount.String(), suite.chainA.SenderAccount.GetAddress().String(), receiver)
+ data := types.NewFungibleTokenPacketData(trace.GetFullDenomPath(), amount.String(), suite.chainA.SenderAccount.GetAddress().String(), receiver, metadata)
  packet := channeltypes.NewPacket(data.GetBytes(), seq, path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, clienttypes.NewHeight(1, 100), 0)
 
  err = suite.chainB.GetSimApp().TransferKeeper.OnRecvPacket(suite.chainB.GetContext(), packet, data)
@@ -302,7 +330,7 @@ func (suite *KeeperTestSuite) TestOnAcknowledgementPacket() {
 
  tc.malleate()
 
- data := types.NewFungibleTokenPacketData(trace.GetFullDenomPath(), amount.String(), suite.chainA.SenderAccount.GetAddress().String(), suite.chainB.SenderAccount.GetAddress().String())
+ data := types.NewFungibleTokenPacketData(trace.GetFullDenomPath(), amount.String(), suite.chainA.SenderAccount.GetAddress().String(), suite.chainB.SenderAccount.GetAddress().String(), nil)
  packet := channeltypes.NewPacket(data.GetBytes(), 1, path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, clienttypes.NewHeight(1, 100), 0)
 
  preCoin := suite.chainA.GetSimApp().BankKeeper.GetBalance(suite.chainA.GetContext(), suite.chainA.SenderAccount.GetAddress(), trace.IBCDenom())
@@ -398,7 +426,7 @@ func (suite *KeeperTestSuite) TestOnTimeoutPacket() {
 
  tc.malleate()
 
- data := types.NewFungibleTokenPacketData(trace.GetFullDenomPath(), amount.String(), sender, suite.chainB.SenderAccount.GetAddress().String())
+ data := types.NewFungibleTokenPacketData(trace.GetFullDenomPath(), amount.String(), sender, suite.chainB.SenderAccount.GetAddress().String(), nil)
  packet := channeltypes.NewPacket(data.GetBytes(), 1, path.EndpointA.ChannelConfig.PortID, path.EndpointA.ChannelID, path.EndpointB.ChannelConfig.PortID, path.EndpointB.ChannelID, clienttypes.NewHeight(1, 100), 0)
 
  preCoin := suite.chainA.GetSimApp().BankKeeper.GetBalance(suite.chainA.GetContext(), suite.chainA.SenderAccount.GetAddress(), trace.IBCDenom())