diff --git a/x/transfermiddleware/spec/packet-forward-middleware.md b/x/transfermiddleware/spec/packet-forward-middleware.md new file mode 100644 index 000000000..674d52afa --- /dev/null +++ b/x/transfermiddleware/spec/packet-forward-middleware.md @@ -0,0 +1,40 @@ +# Transfer Middleware integrated with Packet-Forward-Middleware +## Context +As the requirment of Composable (we want to mint native token that represent ibc-token that was sent from Picasso), the Transfer-middleware had been developed. The ideal of Transfer-middleware is lock the ibc-token that was sent and mint the same amount of native-token to receiver address. + +=> Transfer-middleware will effect to packet-forward-middleware, so we need to handle it. + +## Problem when packet forward from Picasso to Cosmos chain + +When we want to forward a transfer packet from Picasso to a Cosmos chain via Composable, Composable will lock ibc-token from Picasso, mint native token and then send that native token to Cosmos chain. + +### Handle transfer package with PFM memo +When we receive a packet that will be forwarded, we will check if that packet was received from Picasso. If then, we will: +- Send the ibc token to escrow address +- Mint native token to the receiver address on Composable +- Disable denom composition. So that, the PFM module will not replace the transfer denom and we can forward the transfer package with the native denom that was minted. + +### Handle Ack +When we receive the package with memo for forwarding, we will extract the memo to store the transfer data package. The data will be used to check the ACK. When we receiver the ACK the responsible with the forwarding package, we will handle it. + +If Success Ack, then nothing happen. +If Error Ack, we want to burn the ibc-token that lock in the escrow account (from Picasso to Composable) and native-token that lock in escrow account (from Composable to Cosmos chain). + +### Handle TimeOut +Same as Error Ack + +## Problem when packet forward from Cosmos chain to Picasso +When we want to forward a transfer packet from Cosmos chain to Picasso, there are 2 scenario. First, we send cosmos chain token. The second, we send token that was received from Picasso. + +In the first case, every things will active like normal. But it will have a problem with the second case. + +### Handle transfer package +Composable after receive a transfer message with a PFM that forward to Picasso, it will check if the transfer token is the parachain token that store in the state. If so, It will: +- send the amount of locked native token in escrow address to receiver on Composable +- burn the amount of token that just unlocked +- unlock the amount of ibc token in escrow address +- transfer the amount of ibc token just unlocked to Picasso +### Handle Ack +If Success Ack, then nothing happen. +If Error Ack, PFM module will refund the amount of sent token to the sender. the Transfermiddleware module will recovery the amount of token that lock to the escrow address. +