docs: ics20 hooks (#2465)

* docs: IBC hooks * update * Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * fix * lint * Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * lint * Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * lint * lint * Update x/uibc/README.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
umee-network · Mar 20, 2024 · ded07e7 · ded07e7
1 parent cc5dbee
commit ded07e7
Show file tree

Hide file tree

Showing 3 changed files with 125 additions and 10 deletions.
diff --git a/x/uibc/README.md b/x/uibc/README.md
@@ -8,22 +8,135 @@ The `x/uibc` is a Cosmos Module providing:
 
 ## Content
 
-- [IBC Quota](#ibc-quota)
+- [IBC ICS20 Hooks](#ibc-ics20-hooks)
+- [IBC ICS20 Quota](#ibc-ics20-quota)
 
-## IBC Quota
+## IBC ICS20 Hooks
+
+The IBC ICS20 hooks are part of our [ICS20 middleware](https://github.com/umee-network/umee/blob/main/x/uibc/uics20/ibc_module.go#L25) that enables ICS-20 token transfers to trigger message execution. This functionality allows cross-chain calls that involve token movement. IBC hooks enable powerful use cases such as cross-chain lending and leverage.
+
+### Hooks: Concepts
+
+Users can define ICS20 hook instructions in the ICS20 transfer Memo field, that will trigger a procedure call once the transfer is successfully recorded in the UX Chain.
+
+### Hooks: Design
+
+The ICS20 packet data Memo field (introduced in [IBC v3.4.0](https://medium.com/the-interchain-foundation/moving-beyond-simple-token-transfers-d42b2b1dc29b)) allows attaching arbitrary data to a token transfer. The hook execution will be triggered if and only if:
+
+- The packet data `memo` field can be JSON deserialized into the [`umee/uibc/v1/ICS20Memo`](https://github.com/umee-network/umee/blob/v6.4.0-beta1/proto/umee/uibc/v1/uibc.proto#L14). This means that the JSON serialized object into the memo string must extend the ICS20Memo struct.
+- `ICS20Memo.fallback_addr` if defined, must be a correct bech32 Umee address.
+
+The fallback address is optional. It is used when the memo is valid, but the hook execution (messages) fails. We strongly recommend to always use it. Otherwise, the funds can be stuck in the chain if the hook execution fails.
+If memo has a correct structure, and fallback addr is defined but malformed, we cancel the transfer (otherwise we would not be able to use it correctly).
+
+The hooks processing has the following flow:
+
+- Check ICS20 Quota. If quota exceeds, the transfer is cancelled.
+- Deserialize Memo into `ICS20Memo`. If fails, assume the memo doesn't have hook instructions and continue with a normal transfer.
+- Validate `ICS20Memo.fallback_addr`. If fails, the transfer is cancelled.
+- Unpack and validate `ICS20Memo.messsages` (procedures). If fails, continue with the transfer, and overwrite the recipient with the `fallback_addr` if it is defined.
+- Execute the transfer.
+- Execute the hooks messages. If they fail and `fallback_addr` is defined, then revert the transfer (and all related state changes and events) and use send the tokens to the `fallback_addr` instead.
+
+### Proto
+
+```protocol-buffer
+message ICS20Memo {
+  // messages is a list of `sdk.Msg`s that will be executed when handling ICS20 transfer.
+  repeated google.protobuf.Any messages = 1;
+  // fallback_addr [optional] is a bech23 account address used to overwrite the original ICS20
+  // recipient as described in the Design section above.
+  string fallback_addr = 2 [(cosmos_proto.scalar) = "cosmos.AddressString"];
+}
+```
+
+### Supported Messages
+
+The `ICS20Memo` is a list of native `sdk.Message`. Only the following combinations are supported currently:
+
+- `[MsgSupply]`
+- `[MsgSupplyCollateral]`
+- `[MsgLiquidate]`
+
+Validation:
+
+- The operator (defined as the message signer) in each message, must be the same as the ICS20 transfer recipient,
+- messages must only use the subset of the transferred tokens.
+
+NOTE: because the received amount of tokens may be different from the amount originally sent (relayers or hop chains may charge transfer fees), if the amount of tokens in each message exceeds the amount received, we adjust the token amount in the messages.
+
+### Example
+
+Example 1: valid Memo Hook. Send `400 ibc/C0737D24596F82E8BD5471426ED00BDB5DA34FF13BE2DC0B23F7B35EA992B5CD` (here, the denom is an IBC denom of remote chain representing `uumee`). Execute a hook procedure to supply and collateralize `312uumee` and the reminder amount will be credited to the recipient balance.
+
+```json
+{
+  "fallback_addr": "umee10h9stc5v6ntgeygf5xf945njqq5h32r5r2argu",
+  "messages": [
+    {
+      "@type": "/umee.leverage.v1.MsgSupplyCollateral",
+      "supplier": "umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due",
+      "asset": { "denom": "uumee", "amount": "312" }
+    }
+  ]
+}
+```
+
+Command to make a transaction:
+
+```sh
+umeed tx ibc-transfer transfer transfer channel-1 umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due  \
+  400ibc/C0737D24596F82E8BD5471426ED00BDB5DA34FF13BE2DC0B23F7B35EA992B5CD \
+  --from umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due \
+  --memo '{"fallback_addr":"umee10h9stc5v6ntgeygf5xf945njqq5h32r5r2argu","messages":[{"@type":"/umee.leverage.v1.MsgSupplyCollateral","supplier":"umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due","asset":{"denom":"uumee","amount":"312"}}]}'
+```
+
+Example 2: memo struct is correct, struct is correct, but it doesn't pass the validation. The procedure wants to use `uother` denom, but the transfer sends `uumee` coins. Since the `fallback_addr` is correctly defined, all coins will go to the `fallback_addr`.
+
+```json
+{
+  "fallback_addr": "umee10h9stc5v6ntgeygf5xf945njqq5h32r5r2argu",
+  "messages": [
+    {
+      "@type": "/umee.leverage.v1.MsgSupplyCollateral",
+      "supplier": "umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due",
+      "asset": { "denom": "uother", "amount": "312" }
+    }
+  ]
+}
+```
+
+Command to make a transaction:
+
+```sh
+$ umeed tx ibc-transfer transfer transfer channel-1 umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due \
+  400ibc/C0737D24596F82E8BD5471426ED00BDB5DA34FF13BE2DC0B23F7B35EA992B5CD \
+  --from umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due \
+  --memo '{"fallback_addr":"umee10h9stc5v6ntgeygf5xf945njqq5h32r5r2argu","messages":[{"@type":"/umee.leverage.v1.MsgSupplyCollateral","supplier":"umee1y6xz2ggfc0pcsmyjlekh0j9pxh6hk87ymc9due","asset":{"denom":"uother","amount":"312"}}]}'
+```
+
+### Compatibility with IBC Apps Hooks
+
+The IBC Apps repo has [`ibc-hooks`](https://github.com/cosmos/ibc-apps/tree/main/modules/ibc-hooks) middleware, which has similar functionality and the Memo structure is compatible with the one defined here. IBC App hooks support only CosmWasm procedures, with instructions defined in the `Memo.wasm` field and fallback fully managed by the CW contract. This implementation is compatible with IBC Apps: in the future we can support IBC Apps `wasm` hooks, without breaking our `Memo` struct.
+
+### Limitations
+
+The current protocol requires that the IBC receiver is the same as the "operator" (supplier, liquidator) in the `Memo.messages`.
+
+## IBC ICS20 Quota
 
 Hack or lending abuse is impossible to stop once the funds leave the chain. One mitigation is to limit the IBC inflows and outflows and be able to stop a chain and recover the funds with a migration.
 
-### Concepts
+### Quota: Concept
 
 Inflow is an ICS-20 transaction of sending tokens to the Umee chain.
 Outflow is an ICS-20 transaction sending tokens out of the Umee chain.
 
 IBC Quota is an upper limit in USD amount.
 
-### Design
+### Quota: Design
 
-All inflows and outflows are measured in token average USD value using our x/oracle `AvgKeeper`. The `AvgKeeper` aggregates TVWAP prices over 16h window.
+All inflows and outflows are measured in token average USD value using our x/oracle `AvgKeeper`. The `AvgKeeper` aggregates TVWAP prices over a 16h window.
 
 We are tracking inflows and outflows for tokens which are registered in x/leverage Token Registry.
 NOTE: we measure per token as defined in the x/leverage, not the IBC Denom Path (there can be multiple paths). Since creating a channel is permission less, we want to use the same quota token.
@@ -53,7 +166,7 @@ Inflows and outflows metrics above are used to **limit ICS-20 transfers** of tok
 
 See `../../proto/umee/uibc/v1/quota.proto` for the list of all params.
 
-If a any `total_quota` or `token_quota` parameter is set to zero then we consider it as unlimited.
+If any `total_quota` or `token_quota` parameter is set to zero then we consider it as unlimited.
 
 Transfer is **reverted** whenever it breaks any quota.
 
@@ -80,11 +193,11 @@ In the state we store:
 
 ### Messages
 
-The RPC [Messages](https://github.com/umee-network/umee/blob/main/proto/umee/uibc/v1/tx.proto#L16) provide an access to the x/gov to change the module parameters.
+The [Messages](https://github.com/umee-network/umee/blob/main/proto/umee/uibc/v1/tx.proto#L16) RPC provides access to the x/gov to change the module parameters.
 
 ### Queries
 
-The RPC [Queries](https://github.com/umee-network/umee/blob/main/proto/umee/uibc/v1/query.proto#L15) allow to query module parameters and current outflow sums.
+The [Queries](https://github.com/umee-network/umee/blob/main/proto/umee/uibc/v1/query.proto#L15) RPC allows querying module parameters and current outflow sums.
 
 ### Events
 

diff --git a/x/uibc/uics20/ibc_module.go b/x/uibc/uics20/ibc_module.go
@@ -50,8 +50,9 @@ func NewICS20Module(app porttypes.IBCModule, cdc codec.JSONCodec, k quota.Keeper
 //     validation, then we continue with the transfer and overwrite the original receiver to
 //     fallback_addr if it's defined.
 //  4. Execute the downstream middleware and the transfer app.
-//  5. Execute hooks. If hook execution fails, we don't use the the fallback_addr nor ignore the
-//     transfer. This is because there could be other middlewares that are already executed.
+//  5. Execute hooks. If hook execution fails, and the fallback_addr is defined, then we revert
+//     the transfer (and all related state changes and events) and use send the tokens to the
+//     `fallback_addr` instead.
 func (im ICS20Module) OnRecvPacket(ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress,
 ) exported.Acknowledgement {
 	ftData, err := deserializeFTData(im.cdc, packet)

diff --git a/x/uibc/uics20/memo_handler.go b/x/uibc/uics20/memo_handler.go
@@ -75,6 +75,7 @@ func (mh *MemoHandler) onRecvPacketPrepare(
 				sdkerrors.Wrap(err, "ICS20 memo fallback_addr defined, but not formatted correctly")
 		}
 		if mh.fallbackReceiver.Equals(mh.receiver) {
+			// no need to specify fallback address if it's the same as the original receiver
 			mh.fallbackReceiver = nil
 		}
 	}