ICS20-2: Add Token Forwarding ability to ICS20-2

spec/app/ics-020-fungible-token-transfer/README.md

@@ -51,6 +51,7 @@ interface FungibleTokenPacketDataV2 {
   sender: string
   receiver: string
   memo: string
+  forwardingPath: []string
 }
 
 interface Token {
@@ -92,6 +93,7 @@ The fungible token transfer bridge module tracks escrow addresses associated wit
 ```typescript
 interface ModuleState {
   channelEscrowAddresses: Map<Identifier, string>
+  channelForwardingAddresses: Map<Identifier, string>
 }
 ```
 
@@ -241,6 +243,7 @@ function sendFungibleTokens(
   sender: string,
   receiver: string,
   memo: string,
+  forwardingPath: []string,
   sourcePort: string,
   sourceChannel: string,
   timeoutHeight: Height,
@@ -269,11 +272,16 @@ function sendFungibleTokens(
   transferVersion = getAppVersion(channel.version)
   if transferVersion == "ics20-1" {
     abortTransactionUnless(len(tokens) == 1)
-    v1Denom = tokens[0].trace + tokens[0].denom)
-    data = FungibleTokenPacketData{v1Denom, tokens[0].amount, sender, receiver, memo}
+    token = tokens[0]
+    // abort if forwardingPath defined
+    abortTransactionUnless(forwardingPath == nil)
+    // create v1 denom of the form: port1/channel1/port2/channel2/port3/channel3/denom
+    v1Denom = constructOnChainDenom(token.trace, token.denom)
+    // v1 packet data does not support forwardingPath fields
+    data = FungibleTokenPacketData{v1Denom, token.amount, sender, receiver, memo}
   } else if transferVersion == "ics20-2" {
     // create FungibleTokenPacket data
-    data = FungibleTokenPacketDataV2{tokens, sender, receiver, memo}
+    data = FungibleTokenPacketDataV2{tokens, sender, receiver, memo, forwardingPath}
   } else {
     // should never be reached as transfer version must be negotiated to be either
     // ics20-1 or ics20-2 during channel handshake
@@ -302,6 +310,8 @@ function onRecvPacket(packet: Packet) {
   // getAppVersion returns the transfer version that is embedded in the channel version
   // as the channel version may contain additional app or middleware version(s)
   transferVersion = getAppVersion(channel.version)
+  var tokens []Token
+  var receiver string
   if transferVersion == "ics20-1" {
      FungibleTokenPacketData data = UnmarshalJSON(packet.data)
      trace, denom = parseICS20V1Denom(data.denom)
@@ -311,26 +321,36 @@ function onRecvPacket(packet: Packet) {
        amount: packet.amount
      }
      tokens = []Token{token}
+     receiver = packet.receiver
   } else if transferVersion == "ics20-2" {
     FungibleTokenPacketDataV2 data = UnmarshalJSON(packet.data)
     tokens = data.tokens
+    // if we need to forward the tokens onward
+    // temporarily send to the channel escrow address of the intended receiver
+    if len(forwardingPath) > 0 {
+      receiver = channelForwardingAddresses[packet.destinationChannel]
+    }
   } else {
     // should never be reached as transfer version must be negotiated to be either
     // ics20-1 or ics20-2 during channel handshake
     abortTransactionUnless(false)
   }
 
+  assert(packet.sender !== "")
+  assert(receiver !== "")
+
   // construct default acknowledgement of success
   FungibleTokenPacketAcknowledgement ack = FungibleTokenPacketAcknowledgement{true, null}
+
   prefix = "{packet.sourcePort}/{packet.sourceChannel}/"
+  receivedTokens = []Token
   for token in tokens {
     assert(token.denom !== "")
     assert(token.amount > 0)
-    assert(token.sender !== "")
-    assert(token.receiver !== "")
-
+
     // we are the source if the packets were prefixed by the sending chain
     source = token.trace[0] == prefix
+    var onChainTrace []string
     if source {
       // since we are receiving back to source we remove the prefix from the trace
       onChainTrace = token.trace[1:]
@@ -339,7 +359,7 @@ function onRecvPacket(packet: Packet) {
       // determine escrow account
       escrowAccount = channelEscrowAddresses[packet.destChannel]
       // unescrow tokens to receiver (assumed to fail if balance insufficient)
-      err = bank.TransferCoins(escrowAccount, data.receiver, onChainDenom, token.amount)
+      err = bank.TransferCoins(escrowAccount, receiver, onChainDenom, token.amount)
       if (err != nil) {
         ack = FungibleTokenPacketAcknowledgement{false, "transfer coins failed"}
         // break out of for loop on first error
@@ -348,17 +368,55 @@ function onRecvPacket(packet: Packet) {
     } else {
       // since we are receiving to a new sink zone we prepend the prefix to the trace
       prefix = "{packet.destPort}/{packet.destChannel}/"
-      newTrace = append([]string{prefix}, token.trace...)
-      onChainDenom = constructOnChainDenom(newTrace, token.denom)
+      onChainTrace = append([]string{prefix}, token.trace...)
+      onChainDenom = constructOnChainDenom(onChainTrace, token.denom)
       // sender was source, mint vouchers to receiver (assumed to fail if balance insufficient)
-      err = bank.MintCoins(data.receiver, onChainDenom, token.amount)
+      err = bank.MintCoins(receiver, onChainDenom, token.amount)
       if (err !== nil) {
         ack = FungibleTokenPacketAcknowledgement{false, "mint coins failed"}
         // break out of for loop on first error
         break
       }
     }
+
+    // add the received token to the received tokens list
+    recvToken = Token{
+      denom: token.denom,
+      trace: onChainTrace,
+      amount: token.amount,
+    }
+    receivedTokens = append(receivedTokens, recvToken)
+  }
+
+  // if there is an error ack return immediately and do not forward further
+  if !ack.Success() {
+    return ack
   }
+
+  // if acknowledgement is successful and forwarding path set
+  // then start forwarding
+  if forwardingPath != nil {
+    nextPort, nextChannel = split(forwardingPath[0], "/")
+    // send the tokens we received above to the next port and channel
+    // on the forwarding path
+    // and reduce the forwardingPath by the first element
+    nextSequence = sendFungibleTokens(
+      tokens: receivedTokens,
+      sender: receiver,
+      receiver: data.receiver,
+      memo,
+      forwardingPath[1:],
+      nextPort,
+      nextChannel,
+      Height{},
+      currentTime() + DefaultHopTimeoutPeriod,
+    )
+    // store packet for future sending ack
+    store.set(packetForwardPath(nextPort, nextChannel, nextPacketSequence), packet)
+    // use async ack until we get successful acknowledgement from further down the line.
+    return nil
+  }
+
   return ack
 }
 ```
@@ -373,6 +431,30 @@ function onAcknowledgePacket(
   if !(acknowledgement.success) {
     refundTokens(packet)
   }
+
+  // check if the packet was sent is from a previously forwarded packet
+  prevPacket = store.get(packetForwardPath(packet.sourcePort, packet.sourceChannel))
+
+  if prevPacket != nil {
+    if acknowledgement.success {
+      FungibleTokenPacketAcknowledgement ack = FungibleTokenPacketAcknowledgement{true, "forwarded packet succeeded"}
+      handler.writeAcknowledgement(
+        prevPacket,
+        ack,
+      )
+    } else {
+      // the forwarded packet has failed, thus the funds have been refunded to the forwarding address.
+      // we must revert the changes that came from successfully receiving the tokens on our chain
+      // before propogating the error acknowledgement back to original sender chain
+      revertInFlightChanges(packet, prevPacket)
+      // write error acknowledgement
+      FungibleTokenPacketAcknowledgement ack = FungibleTokenPacketAcknowledgement{false, "forwarded packet failed"}
+      handler.writeAcknowledgement(
+        prevPacket,
+        ack,
+      )
+  }
+
 }
 ```
 
@@ -382,6 +464,31 @@ function onAcknowledgePacket(
 function onTimeoutPacket(packet: Packet) {
   // the packet timed-out, so refund the tokens
   refundTokens(packet)
+
+  // check if the packet was sent is from a previously forwarded packet
+  prevPacket = store.get(packetForwardPath(packet.sourcePort, packet.sourceChannel))
+
+  if prevPacket != nil {
+    // the forwarded packet has failed, thus the funds have been refunded to the forwarding address.
+    // we must revert the changes that came from successfully receiving the tokens on our chain
+    // before propogating the error acknowledgement back to original sender chain
+    revertInFlightChanges(packet, prevPacket)
+    // write error acknowledgement
+    FungibleTokenPacketAcknowledgement ack = FungibleTokenPacketAcknowledgement{false, "forwarded packet failed"}
+    handler.writeAcknowledgement(
+      prevPacket,
+      ack,
+    )
+  }
+}
+```
+
+##### Helper functions
+
+```typescript
+function isSource(portId: string, channelId: string, token: Token) {
+  firstTrace = "{portId}/{channelId}"
+  return token.trace[0] == firstTrace
 }
 ```
 
@@ -428,6 +535,45 @@ function refundTokens(packet: Packet) {
 }
 ```
 
+```typescript
+// revertInFlightChanges reverts the receive packet and send packet
+// that occurs in the middle chains during a packet forwarding
+// If an error occurs further down the line, the state changes
+// on this chain must be reverted before sending back the error acknowledgement
+// to ensure atomic packet forwarding
+function revertInFlightChanges(sentPacket: Packet, receivedPacket: Packet) {
+  // the token on our chain is the token in the sentPacket
+  for token in sentPacket.tokens {
+    // check if the packet we sent out was sending as source or not
+    // in this case we escrowed the outgoing tokens
+    if isSource(sentPacket.sourcePort, sentPacket.sourceChannel, token) {
+      // check if the packet we received was a source token for our chain
+      if isSource(receivedPacket.destinationPort, receivedPacket.desinationChannel, token) {
+        // receive sent tokens from the received escrow to the forward escrow account
+        // so we must send the tokens back from the forward escrow to the original received escrow account
+        forwardEscrow = channelEscrowAddresses[sentPacket.sourceChannel]
+        reverseEscrow = channelEscrowAddresses[packet.destChannel]
+        bank.TransferCoins(forwardEscrow, reverseEscrow, token.denom, token.amount)
+      } else {
+        // receive minted vouchers and sent to the forward escrow account
+        // so we must remove the vouchers from the forward escrow account and burn them
+        bank.BurnCoins(forwardEscrow, token.denom, token.amount)
+      }
+    } else {
+      // in this case we burned the vouchers of the outgoing packets
+      // check if the packet we received was a source token for our chain
+      // in this case, the tokens were unescrowed from the reverse escrow account
+      if isSource(receivedPacket.destinationPort, receivedPacket.desinationChannel, token) {
+        // in this case we must mint the burned vouchers and send them back to the escrow account
+        bank.MintCoins(reverseEscrow, token.denom, token.amount)
+      }
+      // if it wasn't a source token on receive, then we simply had minted vouchers and burned them in the receive.
+      // So no state changes were made, and thus no reversion is necessary
+    }
+  }
+}
+```
+
 ```typescript
 function onTimeoutPacketClose(packet: Packet) {
   // can't happen, only unordered channels allowed