From 8938b00ddd390bf9ea9f27ab76f869636e7c7f51 Mon Sep 17 00:00:00 2001 From: Tien Nguyen Date: Fri, 31 May 2024 17:28:07 +0700 Subject: [PATCH] Update and refactor docs (#202) --- README.md | 56 +++++++++++++++++++++--------------------------- sample_pool.json | 10 ++++----- testnode.sh | 10 +++++---- 3 files changed, 36 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 74b42909..d5a8bd24 100644 --- a/README.md +++ b/README.md @@ -7,15 +7,10 @@ The concrete use cases which motivated this module include: - The desire to use IBC token as transaction fees on any chain instead of having to use native token as fee. - To fully take advantage of the newly represented Osmosis [``swap router``](https://github.com/osmosis-labs/osmosis/tree/main/cosmwasm/contracts) with the [``ibc-hooks``](https://github.com/osmosis-labs/osmosis/tree/main/x/ibc-hooks) module and the [``async-icq``](https://github.com/strangelove-ventures/async-icq) module. - ## Description Fee abstraction modules enable users on any Cosmos chain with IBC connections to pay fee using ibc token. -Fee-abs implementation: - -- Fee-abs module imported to the customer chain. - The implememtation also uses Osmosis swap router and async-icq module which are already deployed on Osmosis testnet. ## Prototype @@ -36,7 +31,7 @@ Fee-abs mechanism in a nutshell: We'll goes into all the details now: -#### Pulling `twap data` and update exchange rate +### Pulling `twap data` and update exchange rate For this to work, we first has to set up an ibc channel from `feeabs` to `async-icq`. This channel set-up process can be done by anyone, just like setting up an ibc transfer channel. Once that ibc channel is there, we'll use that channel to ibc-query Twap data. Let's call this the querying channel. @@ -44,32 +39,31 @@ The process of pulling Twap data and update exchange rate : ![Diagram of the process of pulling Twap data and updating exchange rate](https://i.imgur.com/HJ9a26H.png "Diagram of the process of pulling Twap data and updating exchange rate") -Description : - For every `update exchange rate period`, at fee-abs `BeginBlocker()` we submit a `InterchainQueryPacketData` which wrapped `QueryArithmeticTwapToNowRequest` to the querying channel on the customer chain's end. Then relayers will submit `MsgReceivePacket` so that our `QueryTwapPacket` which will be routed to `async-icq` module to be processed. `async-icq` module then unpack `InterchainQueryPacketData` and send query to TWAP module. The correspone response will be wrapped in the ibc acknowledgement. Relayers then submit `MsgAcknowledgement` to the customer chain so that the ibc acknowledgement is routed to fee-abs to be processed. Fee-abs then update exchange rate according to the Twap wrapped in the ibc acknowledgement. +**Description** : +For every `update exchange rate period`, at fee-abs `BeginBlocker()` we submit a `InterchainQueryPacketData` which wrapped `QueryArithmeticTwapToNowRequest` to the querying channel on the customer chain's end. Then relayers will submit `MsgReceivePacket` so that our `QueryTwapPacket` which will be routed to `async-icq` module to be processed. `async-icq` module then unpack `InterchainQueryPacketData` and send query to TWAP module. The correspone response will be wrapped in the ibc acknowledgement. Relayers then submit `MsgAcknowledgement` to the customer chain so that the ibc acknowledgement is routed to fee-abs to be processed. Fee-abs then update exchange rate according to the Twap wrapped in the ibc acknowledgement. -#### Handling txs with ibc-token fee +### Handling txs with ibc-token fee We modified `MempoolFeeDecorator` so that it can handle ibc-token as fee. If the tx has ibc-token fee, the AnteHandler will first check if that token is allowed (which is setup by Gov) we basically replace the amount of ibc-token with the equivalent native-token amount which is calculated by `exchange rate` * `ibc-token amount`. We have an account to manage the ibc-token user used to pay for tx fee. The collected ibc-token fee is sent to that account instead of community pool account. -#### Swap accumulated ibc-tokens fee +### Swap accumulated ibc-tokens fee Fee-abstraction will use osmosis's Cross chain Swap (XCS) feature to do this. We basically ibc transfer to the osmosis crosschain swap contract with custom memo to swap the osmosis fee back to customer chain's native-token and ibc transfer back to the customer chain. -##### How XCS work +#### How XCS work -###### Reverse With Path-unwinding to get Ibc-token on Osmosis +##### Reverse With Path-unwinding to get Ibc-token on Osmosis - Create a ibc transfer message with a specific MEMO to work with ibc [``packet-forward-middleware``](https://github.com/strangelove-ventures/packet-forward-middleware) which is path-unwinding (an ibc feature that allow to automatic define the path and ibc transfer multiple hop follow the defined path) - Ibc transfer the created packet to get the fee Ibc-token on Osmosis -Ex: When you sent STARS on Hub to Osmosis, you will get Osmosis(Hub(STARS)) which is different with STARS on Osmosis Osmosis(STARS). It will reverse back Osmosis(Hub(STARS)) to Osmosis(STARS): +Example: When you sent STARS on Hub to Osmosis, you will get Osmosis(Hub(STARS)) which is different with STARS on Osmosis Osmosis(STARS). It will reverse back Osmosis(Hub(STARS)) to Osmosis(STARS): ![Diagram of the process of swapping accumulated ibc-tokens fee](https://i.imgur.com/D1wSrMm.png "Diagram of the process of swapping accumulated ibc-tokens fee") - -###### Swap Ibc-token +##### Swap IBC token After reverse the ibc-token, XCS will : @@ -85,25 +79,25 @@ Current version of fee-abstraction working with XCSv2 This repository is branched by the cosmos-sdk versions and ibc-go versions used. Currently fee abstraction supports: - SDK v0.50.x & IBC-go v8.* - - branch: release/v8.0.x - - path: github.com/osmosis-labs/fee-abstraction/v8 + - branch: `release/v8.0.x` + - path: `github.com/osmosis-labs/fee-abstraction/v8` - SDK v0.47.x & IBC-go v7.* - - branch: release/v7.0.x - - path: github.com/osmosis-labs/fee-abstraction/v7 + - branch: `release/v7.0.x` + - path: `github.com/osmosis-labs/fee-abstraction/v7` - SDK v0.46.x (Obsolete) - - branch: release/v6.0.x - - path: github.com/osmosis-labs/fee-abstraction/v6 + - branch: `release/v6.0.x` + - path: `github.com/osmosis-labs/fee-abstraction/v6` - SDK v0.45.x (Obsolete) - - branch: release/v4.0.x - - path: github.com/osmosis-labs/fee-abstraction/v4 + - branch: `release/v4.0.x` + - path: `github.com/osmosis-labs/fee-abstraction/v4` ## Acknowledgements -* cosmos-sdk: - * many developers :) -* async-icq - * strangelove ventures -* ideation - * osmosis grants program -* mergify configuration and branching strategy - * ibc-go +- cosmos-sdk: + - many developers :) +- async-icq + - strangelove ventures +- ideation + - osmosis grants program +- mergify configuration and branching strategy + - ibc-go diff --git a/sample_pool.json b/sample_pool.json index 3a63999a..b6d3282c 100644 --- a/sample_pool.json +++ b/sample_pool.json @@ -1,7 +1,7 @@ { - "weights": "1ibc/9117A26BA81E29FA4F78F57DC2BD90CD3D26848101BA880445F119B22A1E254E,1ibc/C053D637CCA2A2BA030E2C5EE1B28A16F71CCB0E45E8BE52766DC1B241B77878", - "initial-deposit": "500000000000ibc/9117A26BA81E29FA4F78F57DC2BD90CD3D26848101BA880445F119B22A1E254E,100000000000ibc/C053D637CCA2A2BA030E2C5EE1B28A16F71CCB0E45E8BE52766DC1B241B77878", - "swap-fee": "0.01", - "exit-fee": "0", - "future-governor": "168h" + "weights": "1ibc/9117A26BA81E29FA4F78F57DC2BD90CD3D26848101BA880445F119B22A1E254E,1ibc/C053D637CCA2A2BA030E2C5EE1B28A16F71CCB0E45E8BE52766DC1B241B77878", + "initial-deposit": "500000000000ibc/9117A26BA81E29FA4F78F57DC2BD90CD3D26848101BA880445F119B22A1E254E,100000000000ibc/C053D637CCA2A2BA030E2C5EE1B28A16F71CCB0E45E8BE52766DC1B241B77878", + "swap-fee": "0.01", + "exit-fee": "0", + "future-governor": "168h" } diff --git a/testnode.sh b/testnode.sh index 03edc9d0..a49de129 100755 --- a/testnode.sh +++ b/testnode.sh @@ -9,7 +9,10 @@ LOGLEVEL="info" TRACE="" # validate dependencies are installed -command -v jq > /dev/null 2>&1 || { echo >&2 "jq not installed. More info: https://stedolan.github.io/jq/download/"; exit 1; } +command -v jq >/dev/null 2>&1 || { + echo >&2 "jq not installed. More info: https://stedolan.github.io/jq/download/" + exit 1 +} # remove existing daemon rm -rf ~/.feeapp* @@ -21,7 +24,7 @@ rm -rf ~/.feeapp* feeappd keys add $KEY --keyring-backend $KEYRING --algo $KEYALGO # Set moniker and chain-id for Evmos (Moniker can be anything, chain-id must be an integer) -feeappd init $MONIKER --chain-id $CHAINID +feeappd init $MONIKER --chain-id $CHAINID # Allocate genesis accounts (cosmos formatted addresses) feeappd genesis add-genesis-account $KEY 100000000000000000000000000stake --keyring-backend $KEYRING @@ -40,5 +43,4 @@ if [[ $1 == "pending" ]]; then fi # Start the node (remove the --pruning=nothing flag if historical queries are not needed) -feeappd start --pruning=nothing --minimum-gas-prices=0.0001stake - +feeappd start --pruning=nothing --minimum-gas-prices=0.0001stake