Skip to content

Commit 960a312

Browse files
Eengineer1ankurdotb
Eengineer1
and
ankurdotb
authored
docs: Added feeabstraction basis (#50)
* docs: Added feeabstraction basis * Added anchor * Align values * Update cheqd-cli-fee-abstraction.md * Update cheqd-cli-fee-abstraction.md * Added clarification * Added REST API alternative * Added pre-requisites * Update cheqd-cli-fee-abstraction.md * Added address conversion section * copyedit --------- Co-authored-by: Ankur Banerjee <[email protected]>
1 parent 683a2e8 commit 960a312

File tree

2 files changed

+242
-0
lines changed

2 files changed

+242
-0
lines changed

‎SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
* [Manage accounts](docs/cheqd-cli/cheqd-cli-accounts.md)
1313
* [Manage a node](docs/cheqd-cli/cheqd-cli-node-management.md)
1414
* [Make transactions](docs/cheqd-cli/cheqd-cli-token-transactions.md)
15+
* [Use fee abstraction](docs/cheqd-cli/cheqd-cli-fee-abstraction.md)
1516

1617
## 🏦 Validator Guides
1718

‎docs/cheqd-cli/cheqd-cli-fee-abstraction.md

+241
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Leveraging Fee Abstraction through cheqd CLI
2+
3+
## Overview
4+
5+
A `cheqd-node` instance can be controlled and configured using the [cheqd Cosmos CLI](README.md).
6+
7+
This document contains the Fee Abstraction commands for [paying for transactions](cheqd-cli-token-transactions.md) using governance-approved alternative tokens, e.g., a stablecoin such as USDC. The Fee Abstraction module routes requests for supported IBC denominations to [Osmosis DEX](https://app.osmosis.zone), and uses existing liquidity pools (e.g., the [CHEQ/USDC pool](https://app.osmosis.zone/pool/1273)) to convert the tokens on the fly. The underlying transaction on cheqd network is **always** funded in CHEQ tokens.
8+
9+
Various commands are available for declaring fees in transactions, along with querying and configuring allowed denominations through governance proposals.
10+
11+
## Supported IBC denominations
12+
13+
Fees for transactions cannot be denominated in arbitrary alternative tokens, when attempting to pay for transactions with non-CHEQ tokens. Supported IBC denominations must be approved using decentralised governance.
14+
15+
## Prerequisites for using Fee Abstraction
16+
17+
The equivalent IBC denomination amount is required to pay for transactions. **Ensure this amount is available in the equivalent Osmosis account** related to the cheqd account/key provided in the transaction.
18+
19+
### Looking up balance of equivalent Osmosis account
20+
21+
You can find out if you've got sufficient balance in supported IBC denominations using the following methods:
22+
23+
1. **Through Leap Wallet**
24+
1. Ensure you have added the cheqd wallet you want to use for transactions to a supported desktop/mobile wallet. The recommended wallet app is [Leap Wallet](https://www.leapwallet.io/download). If you previously used Keplr Wallet, we recommend [migrating from Keplr Wallet to Leap Wallet](https://docs.cheqd.io/product/network/wallets/migrate) as it has better support for [looking up real-time gas prices](./cheqd-cli-token-transactions.md).
25+
2. Once you've added the cheqd wallet account to Leap Wallet, use the network switcher to switch to **Osmosis**. This will allow you to see the balances you have on Osmosis chain, including native OSMO as well as any IBC denominations such as USDC.
26+
2. **Converting your cheqd address to Osmosis using CLI**
27+
1. Use a [bech32 converter tool like this one](https://cosmosdrops.io/en/tools/bech32-converter) to convert a cheqd wallet address to an Osmosis address (use the prefix `osmo` for target address to convert to).
28+
2. Once you have obtained your Osmosis address, you can look up its balance using the [Osmosis CLI](https://docs.osmosis.zone/osmosis-core/osmosisd/) or through a block explorer like [Mintscan](https://mintscan.io/osmosis).
29+
30+
### Getting sufficient balance of supported IBC denominations on equivalent Osmosis account
31+
32+
If you do not have sufficient balances in supported IBC denominations on Osmosis, you need to top-up the specific token you want in your Osmosis account
33+
34+
#### For USDC
35+
36+
1. If you already have USDC (regardless of which chain it is on), use [Noble Express Transfer](https://express.noble.xyz/) to transfer it as Cosmos-native Noble USDC into Osmosis.
37+
2. Acquire USDC on Osmosis by [swapping existing tokens to USDC](https://docs.osmosis.zone/overview/educate/getting-started#swapping-tokens).
38+
39+
## Interacting with Fee Abstraction
40+
41+
### Querying allowed IBC denominations via CLI
42+
43+
As tokens supported for fee abstraction can only be allowlisted by governance, use the following command to find out which IBC denominations are supported:
44+
45+
```bash
46+
cheqd-noded query feeabs all-host-chain-config --node <url>
47+
```
48+
49+
#### Arguments
50+
51+
* `--node`: IP address or URL of node to send the request to
52+
* `--output json` (optional): Provides the output in JSON format
53+
54+
#### Example
55+
56+
```bash
57+
$ cheqd-noded query feeabs all-host-chain-config --node https://rpc.cheqd.network:443
58+
59+
all_host_chain_config:
60+
- ibc_denom: ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4
61+
osmosis_pool_token_denom_in: ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4
62+
pool_id: 1273
63+
status: 0
64+
```
65+
66+
#### Response
67+
68+
1. The `ibc_denom` is the IBC denomination of the supported asset **on Osmsosis** (not the IBC denomination of the asset on cheqd).
69+
2. If the `status` is `0`, the IBC denomination is allowed for transactions. If the `status` is `1`, the IBC denomination is not allowed for transactions. Also, if the IBC denomination is not included in the response, it is not allowed for transactions.
70+
71+
### Querying allowed IBC denominations via REST API
72+
73+
You can also query allowed IBC denominations using the REST API, which can be useful for applications that do not use the node CLI. You can fetch this by initiating a GET request to:
74+
75+
* **Mainnet**: `https://api.cheqd.net/fee-abstraction/feeabs/v1/all-host-chain-config`
76+
* **Testnet**: `https://api.cheqd.network/fee-abstraction/feeabs/v1/all-host-chain-config`
77+
78+
#### Response format for allowed IBC denominations from REST API
79+
80+
```json
81+
{
82+
"all_host_chain_config": [
83+
{
84+
"ibc_denom": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
85+
"osmosis_pool_token_denom_in": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
86+
"pool_id": "1273",
87+
"status": 0
88+
}
89+
]
90+
}
91+
```
92+
93+
### Querying allowed IBC denominations via REST API with a specific IBC denomination
94+
95+
You can also query allowed IBC denominations for a specific IBC denomination using the REST API. You can fetch this by initiating a GET request to:
96+
97+
* **Mainnet**: `https://api.cheqd.net/fee-abstraction/feeabs/v1/host-chain-config/<ibc_denom>`
98+
* **Testnet**: `https://api.cheqd.network/fee-abstraction/feeabs/v1/host-chain-config/<ibc_denom>`
99+
100+
#### Response format for allowed IBC denominations from REST API with a specific IBC denomination
101+
102+
```json
103+
{
104+
"host_chain_config": {
105+
"ibc_denom": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
106+
"osmosis_pool_token_denom_in": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
107+
"pool_id": "1273",
108+
"status": 0
109+
}
110+
}
111+
```
112+
113+
## Querying and declaring fees in transactions
114+
115+
### Querying real-time gas prices via CLI
116+
117+
Refer to the [Querying real-time gas prices via CLI](cheqd-cli-token-transactions.md#querying-real-time-gas-prices-via-cli) section in the [cheqd-cli-token-transactions.md](cheqd-cli-token-transactions.md) document.
118+
119+
> **Note**: The real-time gas prices are used to calculate the fees for transactions. Denominations for fees are specified in the chain-native denomination, which is `ncheq`. You'll need to convert the gas price amount to the desired IBC denomination, as described within the next section.
120+
121+
### Converting gas prices from `ncheq` to IBC denomination and vice versa
122+
123+
```bash
124+
cheqd-noded query feeabs osmo-arithmetic-twap <ibc_denom> --node <url>
125+
```
126+
127+
#### Arguments
128+
129+
* `ibc_denom`: The IBC denomination to convert the gas price to
130+
* `--node`: IP address or URL of node to send the request to
131+
* `--output json` (optional): Provides the output in JSON format
132+
133+
#### Example
134+
135+
```bash
136+
$ cheqd-noded query feeabs osmo-arithmetic-twap ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4 --node https://rpc.cheqd.network:443
137+
138+
osmo_arithmetic_twap: "34874.714483483365588155"
139+
```
140+
141+
If the desired IBC denomination is not configured, the response will error out with a message indicating that the IBC denomination is not allowed for transactions.
142+
143+
### Declaring fees in transactions
144+
145+
```bash
146+
cheqd-noded tx bank <from_key_or_address> <to_address> <amount> --gas <gas> --gas-prices <gas_prices> --fees <fees> --node <url>
147+
```
148+
149+
#### Arguments
150+
151+
* `from_key_or_address`: The key or address of the sender. If the key is used, the key must be unlocked in the keyring.
152+
* `to_address`: The address of the recipient
153+
* `amount`: The amount to send, in the format `1000ncheq`. The amount must be in the chain-native denomination, which is `ncheq`
154+
* `gas`: The amount of gas to use or `auto` to calculate the gas automatically
155+
* `gas_prices`: The gas prices to use, in the format `5000ncheq` or `0.00000016ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4`
156+
* `fees`: The fees to pay, in the format `1000000000ncheq` or `0.032ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4`
157+
* `--node`: IP address or URL of node to send the request to
158+
159+
> **Note**: Use either `--gas` and `--gas-prices` or `--fees` to declare fees in transactions. If `--fees` is used, the `--gas` and `--gas-prices` flags are ignored.
160+
161+
#### Example
162+
163+
##### Declaring fees in transactions using `--gas` and `--gas-prices`
164+
165+
```bash
166+
$ cheqd-noded tx bank key1 cheqd1rnr5jrt4exl0samwj0yegv99jeskl0hsxmcz96 1000000000ncheq --gas auto --gas-prices 0.00000016ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4 --node https://rpc.cheqd.network:443
167+
168+
{"height":"0","txhash":"<tx_hash>","codespace":"","code":0,"data":"","raw_log":"[]","logs":[],"info":"","gas_wanted":"0","gas_used":"0","tx":null,"timestamp":"","events":[]}
169+
```
170+
171+
##### Declaring fees in transactions using `--fees`
172+
173+
```bash
174+
$ cheqd-noded tx bank key1 cheqd1rnr5jrt4exl0samwj0yegv99jeskl0hsxmcz96 1000000000ncheq --fees 0.032ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4 --node https://rpc.cheqd.network:443 -y
175+
176+
{"height":"0","txhash":"<tx_hash>","codespace":"","code":0,"data":"","raw_log":"[]","logs":[],"info":"","gas_wanted":"0","gas_used":"0","tx":null,"timestamp":"","events":[]}
177+
```
178+
179+
> **Note**: Use with the `-y` flag to skip the confirmation prompt. Any fees declared in transactions are deducted from the sender's account by first converting the fees to the chain-native denomination, which is `ncheq`. Use with any compatible transaction type declared in the `tx` command.
180+
181+
##### Declaring fees for identity transactions
182+
183+
```bash
184+
$ cheqd-noded tx cheqd create-did did-document.json --fees 1.6ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4 --node https://rpc.cheqd.network:443 -y
185+
186+
{"height":"0","txhash":"<tx_hash>","codespace":"","code":0,"data":"","raw_log":"[]","logs":[],"info":"","gas_wanted":"0","gas_used":"0","tx":null,"timestamp":"","events":[]}
187+
```
188+
189+
Identity transactions require fees to be declared using the `--fees` flag. The fees are deducted from the sender's account by first converting the fees to the chain-native denomination, which is `ncheq`.
190+
191+
Similarly, declare fees for DID-Linked Resource transactions using the `--fees` flag.
192+
193+
```bash
194+
$ cheqd-noded tx resource create resource-payload.json data.json --fees 0.08ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4 --node https://rpc.cheqd.network:443 -y
195+
196+
{"height":"0","txhash":"<tx_hash>","codespace":"","code":0,"data":"","raw_log":"[]","logs":[],"info":"","gas_wanted":"0","gas_used":"0","tx":null,"timestamp":"","events":[]}
197+
```
198+
199+
## Configuring allowed IBC denominations through governance proposals
200+
201+
### Submitting a governance proposal to allow an IBC denomination
202+
203+
```bash
204+
cheqd-noded tx gov submit-legacy-proposal add-hostzone-config <proposal-file> --from <key> --node <url>
205+
```
206+
207+
#### Arguments
208+
209+
* `proposal-file`: The JSON file containing the proposal details
210+
* `key`: The key of the proposer to submit the proposal on behalf of
211+
* `--node`: IP address or URL of node to send the request to
212+
213+
#### Example
214+
215+
```bash
216+
$ cheqd-noded tx gov submit-legacy-proposal add-hostzone-config proposal.json --from key1 --gas auto --gas-prices 5000ncheq --node https://rpc.cheqd.network:443
217+
218+
{"height":"0","txhash":"<tx_hash>","codespace":"","code":0,"data":"","raw_log":"[]","logs":[],"info":"","gas_wanted":"0","gas_used":"0","tx":null,"timestamp":"","events":[]}
219+
```
220+
221+
```json
222+
{
223+
"title": "Add $USDC IBC denomination to Host Zone",
224+
"description": "Add $USDC IBC denomination to the Host Zone configuration",
225+
"host_chain_fee_abs_config": {
226+
"ibc_denom": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
227+
"osmosis_pool_token_denom_in": "ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4",
228+
"pool_id": "1273",
229+
"status": 0
230+
},
231+
"deposit": "100000000000ncheq"
232+
}
233+
```
234+
235+
> **Note**: Use with the `add-hostzone-config` proposal type to allow an IBC denomination for transactions. The proposal must be submitted by a proposer with the required deposit amount in the chain-native denomination, which is `ncheq`. The proposal details are specified in the JSON file. Fees can be declared using either the `--gas` and `--gas-prices` flags or the `--fees` flag.
236+
237+
## Appendix
238+
239+
* `ibc/498A0751C798A0D9A389AA3691123DADA57DAA4FE165D5C75894505B876BA6E4`: The $USDC IBC denomination for the Osmosis chain
240+
* `ibc/92AE2F53284505223A1BB80D132F859A00E190C6A738772F0B3EF65E20BA484F`: The $EURe IBC denomination for the Osmosis chain
241+
* `ibc/7A08C6F11EF0F59EB841B9F788A87EC9F2361C7D9703157EC13D940DC53031FA`: The $CHEQ IBC denomination for the Osmosis chain

0 commit comments

Comments
 (0)