From d6ca3048e3a9daacfdfa334faa4a256b265e86b5 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 15:30:57 +0100 Subject: [PATCH 01/12] docs: IBC hooks --- x/uibc/README.md | 113 +++++++++++++++++++++++++++++++++- x/uibc/uics20/ibc_module.go | 5 +- x/uibc/uics20/memo_handler.go | 1 + 3 files changed, 115 insertions(+), 4 deletions(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 09ef7824f0..8549fa8557 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -8,9 +8,118 @@ The `x/uibc` is a Cosmos Module providing: ## Content -- [IBC Quota](#ibc-quota) +- [IBC ICS20 Hooks](#ics20-ibc-hooks) +- [IBC ICS20 Quota](#isc20-ibc-quota) -## IBC Quota +## IBC ICS20 Hooks + +The IBC ICS20 hooks is 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 are useful for a variety of use cases, including cross-chain swaps, which are an extremely powerful primitive. + +### Concepts + +User can define a ICS20 hook instructions in ICS20 transfer Memo field, that will trigger procedure call once the transfer is successfully recorded in the UX Chain. + +### 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 to attach 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 used when the memo is valid, but the hook execution (messages) fail. 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 than the amount originally sent (relayers or hoop 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 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 only support cosmwasm procedures: the instruction is defined in the `Memo.wasm` field and fallback is fully handled 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. + +## 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. diff --git a/x/uibc/uics20/ibc_module.go b/x/uibc/uics20/ibc_module.go index bdba70a29b..ec32a28cac 100644 --- 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 index ccccb64b40..a9fafd4ab3 100644 --- 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 } } From fe5e8d454ecb80a77a9ce90da4de69bdf17252ca Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 15:36:28 +0100 Subject: [PATCH 02/12] update --- x/uibc/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 8549fa8557..f01caff41e 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -63,7 +63,7 @@ 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 than the amount originally sent (relayers or hoop 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. +NOTE: because the received amount of tokens may be different than 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 @@ -119,6 +119,10 @@ $ umeed tx ibc-transfer transfer transfer channel-1 umee1y6xz2ggfc0pcsmyjlekh0j9 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 only support cosmwasm procedures: the instruction is defined in the `Memo.wasm` field and fallback is fully handled 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 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. From 21eb9e62fb2435ef375141e0eca497b79931140c Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 18:46:27 +0100 Subject: [PATCH 03/12] Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- x/uibc/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index f01caff41e..06cd81c4ae 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -13,15 +13,15 @@ The `x/uibc` is a Cosmos Module providing: ## IBC ICS20 Hooks -The IBC ICS20 hooks is 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 are useful for a variety of use cases, including cross-chain swaps, which are an extremely powerful primitive. +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 are useful for a variety of use cases, including cross-chain swaps, which are an extremely powerful primitive. ### Concepts -User can define a ICS20 hook instructions in ICS20 transfer Memo field, that will trigger procedure call once the transfer is successfully recorded in the UX Chain. +Users can define ICS20 hook instructions in ICS20 transfer Memo field, that will trigger procedure call once the transfer is successfully recorded in the UX Chain. ### 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 to attach arbitrary data to a token transfer. The hook execution will be triggered if and only if: +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 to attach 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. @@ -91,7 +91,7 @@ umeed tx ibc-transfer transfer transfer channel-1 umee1y6xz2ggfc0pcsmyjlekh0j9px --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 to the `fallback_addr`. +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 { From fb23acd7b5314b27193af5ba6854bbffb2f6e9fe Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 18:47:42 +0100 Subject: [PATCH 04/12] fix --- x/uibc/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 06cd81c4ae..647d848d6d 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -8,8 +8,8 @@ The `x/uibc` is a Cosmos Module providing: ## Content -- [IBC ICS20 Hooks](#ics20-ibc-hooks) -- [IBC ICS20 Quota](#isc20-ibc-quota) +- [IBC ICS20 Hooks](#ibc-ics20-hooks) +- [IBC ICS20 Quota](#ibc-isc20-quota) ## IBC ICS20 Hooks From 14abd8e6ec552b0c02d0dd3190b0c97308bdf4f0 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 18:56:08 +0100 Subject: [PATCH 05/12] lint --- x/uibc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 647d848d6d..284ced3c95 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -9,7 +9,7 @@ The `x/uibc` is a Cosmos Module providing: ## Content - [IBC ICS20 Hooks](#ibc-ics20-hooks) -- [IBC ICS20 Quota](#ibc-isc20-quota) +- [IBC ICS20 Quota](#ibc-ics20-quota) ## IBC ICS20 Hooks From 20712afbdb18f0d897a43a72edca5402da39ca51 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 19:37:14 +0100 Subject: [PATCH 06/12] Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- x/uibc/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 284ced3c95..7c0072bcbe 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -17,16 +17,16 @@ The IBC ICS20 hooks are part of our [ICS20 middleware](https://github.com/umee-n ### Concepts -Users can define ICS20 hook instructions in ICS20 transfer Memo field, that will trigger procedure call once the transfer is successfully recorded in the UX Chain. +Users can define ICS20 hook instructions in the ICS20 transfer Memo field, that will trigger procedure call once the transfer is successfully recorded in the UX Chain. ### 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 to attach arbitrary data to a token transfer. The hook execution will be triggered if and only if: +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. +- 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 used when the memo is valid, but the hook execution (messages) fail. We strongly recommend to always use it. Otherwise the funds can be stuck in the chain if the hook execution fails. +The fallback address is optional. It used when the memo is valid, but the hook execution (messages) fail. 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: @@ -60,7 +60,7 @@ The `ICS20Memo` is a list of native `sdk.Message`. Only the following combinatio Validation: -- the operator (defined as the message signer) in each message, must be the same as the ICS20 transfer recipient, +- 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 than 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. @@ -117,11 +117,11 @@ $ umeed tx ibc-transfer transfer transfer channel-1 umee1y6xz2ggfc0pcsmyjlekh0j9 ### 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 only support cosmwasm procedures: the instruction is defined in the `Memo.wasm` field and fallback is fully handled 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. +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 only support cosmwasm procedures: the instruction is defined in the `Memo.wasm` field, and fallback is fully handled 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 same as the "operator" (supplier, liquidator) in the `Memo.messages`. +The current protocol requires that the IBC receiver is the same as the "operator" (supplier, liquidator) in the `Memo.messages`. ## IBC ICS20 Quota From 0d8c0a8e15a432cec32ee48e4512c219a122b174 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 19:40:15 +0100 Subject: [PATCH 07/12] lint --- x/uibc/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 7c0072bcbe..78896c5f36 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -136,7 +136,7 @@ IBC Quota is an upper limit in USD amount. ### 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. @@ -166,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. @@ -193,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 From 40e19d035cfb8f1097a0d5be75def22f387a2bf8 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 20:36:27 +0100 Subject: [PATCH 08/12] Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- x/uibc/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 78896c5f36..d506168e76 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -17,7 +17,7 @@ The IBC ICS20 hooks are part of our [ICS20 middleware](https://github.com/umee-n ### Concepts -Users can define ICS20 hook instructions in the ICS20 transfer Memo field, that will trigger procedure call once the transfer is successfully recorded in the UX Chain. +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. ### Design @@ -26,7 +26,7 @@ The ICS20 packet data Memo field (introduced in [IBC v3.4.0](https://medium.com/ - 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 used when the memo is valid, but the hook execution (messages) fail. We strongly recommend to always use it. Otherwise, the funds can be stuck in the chain if the hook execution fails. +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: @@ -63,7 +63,7 @@ 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 than 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. +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 @@ -117,7 +117,7 @@ $ umeed tx ibc-transfer transfer transfer channel-1 umee1y6xz2ggfc0pcsmyjlekh0j9 ### 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 only support cosmwasm procedures: the instruction is defined in the `Memo.wasm` field, and fallback is fully handled 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. +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 From 0c9caa9aa89fa32343633f42f2ddcb9d6ae84971 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 20:36:44 +0100 Subject: [PATCH 09/12] lint --- x/uibc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index d506168e76..bf6a722fd7 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -13,7 +13,7 @@ The `x/uibc` is a Cosmos Module providing: ## 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 are useful for a variety of use cases, including cross-chain swaps, which are an extremely powerful primitive. +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 are useful for a variety of use cases, including cross-chain lending and leverage, which are an extremely powerful primitive. ### Concepts From 27bfad0c92630ffcc730eb22f1fa7bb29f1e8c80 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 20:40:05 +0100 Subject: [PATCH 10/12] lint --- x/uibc/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index bf6a722fd7..ea4c1ee1ee 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -15,11 +15,11 @@ The `x/uibc` is a Cosmos Module providing: 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 are useful for a variety of use cases, including cross-chain lending and leverage, which are an extremely powerful primitive. -### Concepts +### 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. -### Design +### 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: @@ -127,14 +127,14 @@ The current protocol requires that the IBC receiver is the same as the "operator 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 a 16h window. From a89abd835e862179926d017ab08bbb31019729e0 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 20:56:52 +0100 Subject: [PATCH 11/12] Update x/uibc/README.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- x/uibc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index ea4c1ee1ee..3b82090c83 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -24,7 +24,7 @@ Users can define ICS20 hook instructions in the ICS20 transfer Memo field, that 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. +- `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). From 41c61cb5f024991efb28c4512a2c51333ca77572 Mon Sep 17 00:00:00 2001 From: Robert Zaremba Date: Wed, 20 Mar 2024 20:57:21 +0100 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- x/uibc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/uibc/README.md b/x/uibc/README.md index 3b82090c83..6998dd8b9a 100644 --- a/x/uibc/README.md +++ b/x/uibc/README.md @@ -13,7 +13,7 @@ The `x/uibc` is a Cosmos Module providing: ## 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 are useful for a variety of use cases, including cross-chain lending and leverage, which are an extremely powerful primitive. +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