From 593a0bf9e553569d0753929c27c4fcef628628ba Mon Sep 17 00:00:00 2001 From: Nhu Viet Nguyen Date: Thu, 28 Mar 2024 13:08:51 +0100 Subject: [PATCH 01/10] feat: feegrant module for blobs submission via DA Light node --- developers/feegrant-for-blobs.md | 130 +++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 developers/feegrant-for-blobs.md diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md new file mode 100644 index 00000000000..148adb35a44 --- /dev/null +++ b/developers/feegrant-for-blobs.md @@ -0,0 +1,130 @@ +# FeeGrant Module for Blobs submission + +## Overview + +This guide provides developers with the knowledge to use the FeeGrant module on the Celestia's mocha testnet chain for +granting a data availability node's account to submit blobs without constantly funding it, enabling a third-party +account to cover the transaction fees. + +## Pre-requisites + +- Celestia application CLI installed. +- Celestia node and CLI tools installed. +- Access to a mocha's node (e.g., `https://rpc.celestia-mocha.com:443`). +- Running DA Light node on mocha testnet. +- Separate celestia account with sufficient funds. + +## Introduction + +Each DA node contains a celestia account that is used to pay for blobs submissions. In order to unify the fee payment +process, the FeeGrant module allows a third-party account to pay for the fees incurred by the DA node's account. +This module is useful for projects that require a third-party to cover the fees for the DA node's account. You will need +one account that will contain the funds and another account that will be in the DA node. You will see the DA node's +account once you initialise the node. + +## Granting Fee Allowances + +To grant fee allowances, allowing a third-party (granter) account to pay for the fees incurred by a Celestia data +availability node (grantee) account, use the following command: + +```shell +celestia-appd tx feegrant grant \ + [grantee_address] [granter_address] \ + --home [path_to_grantee] \ + --node [rpc_endpoint] \ + --spend-limit 1000000utia \ + --allowed-messages "/cosmos.bank.v1beta1.MsgSend,/celestia.blob.v1.MsgPayForBlobs" \ + --chain-id mocha-4 \ + --keyring-backend test \ + --fees 20000utia \ + --broadcast-mode block \ + --yes +``` + +Example +transaction: [Fee Grant Transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) + +## Verifying Balances and Transactions + +Before diving into the specifics of verifying balances and transactions, it's important to note that currently, it's +necessary to fund the light node in order for its transactions to be included in the state. We recognize this step as an +extra layer of complexity and are actively working on improving the user experience. Future updates to the +nodes implementations will aim to make this step non-mandatory for the FeeGrant module to function effectively, +streamlining the process for developers and users alike. + +### Check Balance of the New DA Light Node + +To check the balance of a new light node, use the following command: + +```shell +celestia state balance --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ +``` + +Example response when the account balance does not exist: + +```json +{ + "result": { + "denom": "utia", + "amount": "0" + } +} +``` + +This indicates that the light node currently does not have any funds. + +### Funding the Light Node + +As of now, to ensure the light node's transactions are included in the state, you must initially fund the light node +with the least amount of funds using the following command: + +```shell +celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ + --node https://rpc.celestia-mocha.com:443 \ + --chain-id mocha-4 \ + --keyring-backend test \ + --fees 20000utia \ + --broadcast-mode block \ + --yes \ + --home ~/.celestia-app-devops/ +``` + +### Submitting a Blob + +To submit a blob, utilize the following command: + +```shell +celestia blob submit --input-file blob.json --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ +``` + +### Checking Account Balances After Submission + +Light Node Account: +After submitting a blob, you can check the light node account's balance to verify that the fees have been deducted: + +```shell +celestia state balance --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ +``` + +Example output showing fees are not deducted: + +```json +{ + "result": { + "denom": "utia", + "amount": "10000" + } +} +``` + +### Third-Party Account: + +To confirm that the fees have been deducted from the third-party account that granted the fee allowance, run: + +```shell +celestia-appd query bank balances [granter_address] \ +--node https://rpc.celestia-mocha.com:443 --denom utia +``` + +This output will show the remaining balance after fees have been deducted, confirming that the FeeGrant module is +working as intended. \ No newline at end of file From f1dd9e76415100034d3639e702fdc0003a30fdd6 Mon Sep 17 00:00:00 2001 From: jcstein Date: Thu, 28 Mar 2024 11:23:59 -0400 Subject: [PATCH 02/10] docs: formatting --- .vitepress/config.ts | 4 ++ developers/feegrant-for-blobs.md | 78 ++++++++++++++++++-------------- 2 files changed, 49 insertions(+), 33 deletions(-) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 9c1b9eba780..ef1133e26f0 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -508,6 +508,10 @@ function sidebarHome() { text: "Transaction resubmission guidelines", link: "/developers/transaction-resubmission", }, + { + text: "FeeGrant module for blobs submission", + link: "/developers/feegrant-for-blobs", + }, { text: "Node API", link: "/developers/node-api", diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index 148adb35a44..13e21ae4513 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -1,10 +1,11 @@ -# FeeGrant Module for Blobs submission +# FeeGrant module for blobs submission ## Overview -This guide provides developers with the knowledge to use the FeeGrant module on the Celestia's mocha testnet chain for -granting a data availability node's account to submit blobs without constantly funding it, enabling a third-party -account to cover the transaction fees. +This guide provides developers with the knowledge to use the FeeGrant +module on the Celestia's mocha testnet chain for granting a data +availability node's account to submit blobs without constantly +funding it, enabling a third-party account to cover the transaction fees. ## Pre-requisites @@ -16,16 +17,19 @@ account to cover the transaction fees. ## Introduction -Each DA node contains a celestia account that is used to pay for blobs submissions. In order to unify the fee payment -process, the FeeGrant module allows a third-party account to pay for the fees incurred by the DA node's account. -This module is useful for projects that require a third-party to cover the fees for the DA node's account. You will need -one account that will contain the funds and another account that will be in the DA node. You will see the DA node's -account once you initialise the node. +Each DA node contains a celestia account that is used to pay for blobs +submissions. In order to unify the fee payment process, the FeeGrant module +allows a third-party account to pay for the fees incurred by the DA node's +account. This module is useful for projects that require a third-party to +cover the fees for the DA node's account. You will need one account that will +contain the funds and another account that will be in the DA node. You will +see the DA node's account once you initialise the node. -## Granting Fee Allowances +## Granting fee allowances -To grant fee allowances, allowing a third-party (granter) account to pay for the fees incurred by a Celestia data -availability node (grantee) account, use the following command: +To grant fee allowances, allowing a third-party (granter) account to pay +for the fees incurred by a Celestia data availability node (grantee) +account, use the following command: ```shell celestia-appd tx feegrant grant \ @@ -41,24 +45,27 @@ celestia-appd tx feegrant grant \ --yes ``` -Example -transaction: [Fee Grant Transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) +Example transaction: +[Fee Grant Transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) -## Verifying Balances and Transactions +## Verifying balances and transactions -Before diving into the specifics of verifying balances and transactions, it's important to note that currently, it's -necessary to fund the light node in order for its transactions to be included in the state. We recognize this step as an -extra layer of complexity and are actively working on improving the user experience. Future updates to the -nodes implementations will aim to make this step non-mandatory for the FeeGrant module to function effectively, +Before diving into the specifics of verifying balances and transactions, +it's important to note that currently, it's necessary to fund the light node +in order for its transactions to be included in the state. We recognize +this step as a extra layer of complexity and are actively working on improving +the user experience. Future updates to the nodes implementations will aim to +make this step non-mandatory for the FeeGrant module to function effectively, streamlining the process for developers and users alike. -### Check Balance of the New DA Light Node +### Check balance of the new DA light node To check the balance of a new light node, use the following command: - + ```shell celestia state balance --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ ``` + Example response when the account balance does not exist: @@ -73,10 +80,11 @@ Example response when the account balance does not exist: This indicates that the light node currently does not have any funds. -### Funding the Light Node +### Funding the light node -As of now, to ensure the light node's transactions are included in the state, you must initially fund the light node -with the least amount of funds using the following command: +As of now, to ensure the light node's transactions are included in the +state, you must initially fund the light node with the least amount +of funds using the following command: ```shell celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ @@ -89,22 +97,25 @@ celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ --home ~/.celestia-app-devops/ ``` -### Submitting a Blob +### Submitting a blob To submit a blob, utilize the following command: - + ```shell celestia blob submit --input-file blob.json --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ ``` + -### Checking Account Balances After Submission +### Checking account balances after submission Light Node Account: -After submitting a blob, you can check the light node account's balance to verify that the fees have been deducted: - +After submitting a blob, you can check the light node account's balance +to verify that the fees have been deducted: + ```shell celestia state balance --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ ``` + Example output showing fees are not deducted: @@ -117,14 +128,15 @@ Example output showing fees are not deducted: } ``` -### Third-Party Account: +### Third-party account: -To confirm that the fees have been deducted from the third-party account that granted the fee allowance, run: +To confirm that the fees have been deducted from the third-party account that +granted the fee allowance, run: ```shell celestia-appd query bank balances [granter_address] \ --node https://rpc.celestia-mocha.com:443 --denom utia ``` -This output will show the remaining balance after fees have been deducted, confirming that the FeeGrant module is -working as intended. \ No newline at end of file +This output will show the remaining balance after fees have been deducted, +confirming that the FeeGrant module is working as intended. From 3d508c05573f41715a72c6c1bd85528f7b8dcbda Mon Sep 17 00:00:00 2001 From: jcstein Date: Thu, 28 Mar 2024 12:01:00 -0400 Subject: [PATCH 03/10] docs: feegrant edits --- developers/feegrant-for-blobs.md | 40 ++++++++++++++++---------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index 13e21ae4513..2731926db92 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -3,21 +3,21 @@ ## Overview This guide provides developers with the knowledge to use the FeeGrant -module on the Celestia's mocha testnet chain for granting a data +module on the Celestia's Mocha testnet chain for granting a data availability node's account to submit blobs without constantly funding it, enabling a third-party account to cover the transaction fees. ## Pre-requisites -- Celestia application CLI installed. -- Celestia node and CLI tools installed. -- Access to a mocha's node (e.g., `https://rpc.celestia-mocha.com:443`). -- Running DA Light node on mocha testnet. -- Separate celestia account with sufficient funds. +- celestia-app CLI installed +- celestia-node and CLI tools installed +- Access to a Mocha node (e.g., `https://rpc.celestia-mocha.com:443`) +- Running DA Light node on Mocha testnet +- Separate Celestia account with sufficient funds ## Introduction -Each DA node contains a celestia account that is used to pay for blobs +Each DA node contains a Celestia account that is used to pay for blobs submissions. In order to unify the fee payment process, the FeeGrant module allows a third-party account to pay for the fees incurred by the DA node's account. This module is useful for projects that require a third-party to @@ -31,7 +31,7 @@ To grant fee allowances, allowing a third-party (granter) account to pay for the fees incurred by a Celestia data availability node (grantee) account, use the following command: -```shell +```bash celestia-appd tx feegrant grant \ [grantee_address] [granter_address] \ --home [path_to_grantee] \ @@ -46,13 +46,13 @@ celestia-appd tx feegrant grant \ ``` Example transaction: -[Fee Grant Transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) +[FeeGrant transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) ## Verifying balances and transactions Before diving into the specifics of verifying balances and transactions, it's important to note that currently, it's necessary to fund the light node -in order for its transactions to be included in the state. We recognize +in order for its transactions to be included in the state of the chain. We recognize this step as a extra layer of complexity and are actively working on improving the user experience. Future updates to the nodes implementations will aim to make this step non-mandatory for the FeeGrant module to function effectively, @@ -62,8 +62,8 @@ streamlining the process for developers and users alike. To check the balance of a new light node, use the following command: -```shell -celestia state balance --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ +```bash +celestia state balance --node.store ~/.celestia-light-mocha-4/ ``` @@ -86,7 +86,7 @@ As of now, to ensure the light node's transactions are included in the state, you must initially fund the light node with the least amount of funds using the following command: -```shell +```bash celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ --node https://rpc.celestia-mocha.com:443 \ --chain-id mocha-4 \ @@ -94,26 +94,26 @@ celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ --fees 20000utia \ --broadcast-mode block \ --yes \ - --home ~/.celestia-app-devops/ + --home ~/.celestia-app/ ``` ### Submitting a blob To submit a blob, utilize the following command: -```shell -celestia blob submit --input-file blob.json --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ +```bash +celestia blob submit 0x6B656B 'nice' --node.store $NODE_STORE ``` ### Checking account balances after submission -Light Node Account: +Light node account: After submitting a blob, you can check the light node account's balance to verify that the fees have been deducted: -```shell -celestia state balance --token $CEL_AUTH_TOKEN --node.store ~/.celestia-light-mocha-4/ +```bash +celestia state balance --node.store ~/.celestia-light-mocha-4/ ``` @@ -133,7 +133,7 @@ Example output showing fees are not deducted: To confirm that the fees have been deducted from the third-party account that granted the fee allowance, run: -```shell +```bash celestia-appd query bank balances [granter_address] \ --node https://rpc.celestia-mocha.com:443 --denom utia ``` From 0041d7fb3b415f53b5ab72f737f6866613d571d8 Mon Sep 17 00:00:00 2001 From: jcstein Date: Thu, 28 Mar 2024 12:18:38 -0400 Subject: [PATCH 04/10] docs: copy edits --- developers/feegrant-for-blobs.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index 2731926db92..f868e30d473 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -18,12 +18,11 @@ funding it, enabling a third-party account to cover the transaction fees. ## Introduction Each DA node contains a Celestia account that is used to pay for blobs -submissions. In order to unify the fee payment process, the FeeGrant module +submissions. To unify the fee payment process, the FeeGrant module allows a third-party account to pay for the fees incurred by the DA node's -account. This module is useful for projects that require a third-party to -cover the fees for the DA node's account. You will need one account that will -contain the funds and another account that will be in the DA node. You will -see the DA node's account once you initialise the node. +account. You will need one account that will contain the funds and another +account that will be in the DA node. You will see the DA node's account +once you initialize the node. ## Granting fee allowances @@ -45,7 +44,7 @@ celestia-appd tx feegrant grant \ --yes ``` -Example transaction: +Example: [FeeGrant transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) ## Verifying balances and transactions @@ -53,7 +52,7 @@ Example transaction: Before diving into the specifics of verifying balances and transactions, it's important to note that currently, it's necessary to fund the light node in order for its transactions to be included in the state of the chain. We recognize -this step as a extra layer of complexity and are actively working on improving +this step as an extra layer of complexity and are actively working on improving the user experience. Future updates to the nodes implementations will aim to make this step non-mandatory for the FeeGrant module to function effectively, streamlining the process for developers and users alike. From a98424d3ffa2dc029e74d56893043052d9ae979a Mon Sep 17 00:00:00 2001 From: jcstein Date: Thu, 28 Mar 2024 12:48:47 -0400 Subject: [PATCH 05/10] docs: use original blob example with file input --- developers/feegrant-for-blobs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index f868e30d473..b1954f2ac26 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -101,7 +101,7 @@ celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ To submit a blob, utilize the following command: ```bash -celestia blob submit 0x6B656B 'nice' --node.store $NODE_STORE +celestia blob submit --input-file blob.json --node.store ~/.celestia-light-mocha-4/ ``` From b8e8093996aed543574546b7f504864e1d4d2de0 Mon Sep 17 00:00:00 2001 From: jcstein Date: Thu, 28 Mar 2024 12:54:04 -0400 Subject: [PATCH 06/10] docs: coderabbit suggestions --- developers/feegrant-for-blobs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index b1954f2ac26..155504e3dfe 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -51,8 +51,8 @@ Example: Before diving into the specifics of verifying balances and transactions, it's important to note that currently, it's necessary to fund the light node -in order for its transactions to be included in the state of the chain. We recognize -this step as an extra layer of complexity and are actively working on improving +for its transactions to be included in the state of the chain. +This step adds an extra layer of complexity and are actively working on improving the user experience. Future updates to the nodes implementations will aim to make this step non-mandatory for the FeeGrant module to function effectively, streamlining the process for developers and users alike. From 713b8f8287a1b02a100040e0de162e8dbcd74f4b Mon Sep 17 00:00:00 2001 From: jcstein Date: Thu, 28 Mar 2024 13:26:42 -0400 Subject: [PATCH 07/10] docs: swap granter and grantee order --- developers/feegrant-for-blobs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index 155504e3dfe..3bf4cf15212 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -32,8 +32,8 @@ account, use the following command: ```bash celestia-appd tx feegrant grant \ - [grantee_address] [granter_address] \ - --home [path_to_grantee] \ + [granter_address] [grantee_address] \ + --home [path_to_granter] \ --node [rpc_endpoint] \ --spend-limit 1000000utia \ --allowed-messages "/cosmos.bank.v1beta1.MsgSend,/celestia.blob.v1.MsgPayForBlobs" \ From 277a69b550b164115709ea6c0f0b460c6a7e34a1 Mon Sep 17 00:00:00 2001 From: jcstein Date: Wed, 17 Apr 2024 17:25:54 -0400 Subject: [PATCH 08/10] docs: add port for example celestia-appd cmds --- nodes/celestia-app-commands.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/nodes/celestia-app-commands.md b/nodes/celestia-app-commands.md index cc6f1ea5494..2e870c6382d 100644 --- a/nodes/celestia-app-commands.md +++ b/nodes/celestia-app-commands.md @@ -123,7 +123,7 @@ Example usage: ```sh celestia-appd q bank balances celestia1czpgn3hdh9sodm06d5qk23xzgpq2uyc8ggdqgw \ - --node https://rpc-mocha.pops.one + --node https://rpc-mocha.pops.one:443 ``` Transfer tokens from one wallet to another: @@ -137,7 +137,7 @@ Example usage: ```sh celestia-appd tx bank send \ - 19000000utia --node https://rpc-mocha.pops.one/ --chain-id mocha + 19000000utia --node https://rpc-mocha.pops.one:443 --chain-id mocha ``` To see options: From c335d08699af9124206fe545812e77bfb08f747f Mon Sep 17 00:00:00 2001 From: jcstein Date: Wed, 17 Apr 2024 18:00:54 -0400 Subject: [PATCH 09/10] docs: add draft for feegrant --- developers/feegrant-for-blobs.md | 78 ++++++++++++++++++++++++++------ 1 file changed, 64 insertions(+), 14 deletions(-) diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index 3bf4cf15212..087461f1399 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -24,17 +24,27 @@ account. You will need one account that will contain the funds and another account that will be in the DA node. You will see the DA node's account once you initialize the node. -## Granting fee allowances +## Granting fee allowances using celestia-appd To grant fee allowances, allowing a third-party (granter) account to pay for the fees incurred by a Celestia data availability node (grantee) -account, use the following command: +account, use the following commands. + +Set your account addresses for grantee and granter, and +the RPC URL: + +```bash +export GRANTER_ADDRESS= +export GRANTEE_ADDRESS= +export RPC_URL=https://rpc.celestia-mocha.com:443 +``` + +Then, send the feegrant transaction: ```bash celestia-appd tx feegrant grant \ - [granter_address] [grantee_address] \ - --home [path_to_granter] \ - --node [rpc_endpoint] \ + $GRANTER_ADDRESS $GRANTEE_ADDRESS \ + --node $RPC_URL \ --spend-limit 1000000utia \ --allowed-messages "/cosmos.bank.v1beta1.MsgSend,/celestia.blob.v1.MsgPayForBlobs" \ --chain-id mocha-4 \ @@ -47,6 +57,47 @@ celestia-appd tx feegrant grant \ Example: [FeeGrant transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) +## Granting fee allowances using celestia-node + +**WIP** + +Notes + +- using node you now can easily give permission for other nodes to submit transactions on +your behalf(I mean your node will pay fees for these txs) +- you can revoke the grant as well +- The node that receives the grant has to run a node with +`--granter.address=celestia1v96seg23ehfhfjwk0wcy3s5y0krptt284vh236` to use +granting functionality. + +The granter address will be stored until the next run of your local node. +So, in case the granter revokes permission, you will have to restart the +node without this flag. I guess, important to know that such transactions +(with granter) will consume more gas than the regular ones. + +This PR also added a `gasMultiplier`, for the transactions with the Options. +Not sure if is it relevant for docs or not. +I’ve also added a specific error for the case when you run your node as a +grantee, but the granter revokes his permission. In this case, your tx will +be failed with an error: +granter has revoked the grant . This will mean that you have to restart the +node w/o a flag. + +```bash +# to grant permission, you’ll have to execute: +celestia state grant-fee celestia12psg90lwvxdktnqerr2p5mxuw2v3je497uv6tj 2000 1000000 +``` + +```bash +# revoke +celestia state revoke-grant-fee celestia12psg90lwvxdktnqerr2p5mxuw2v3je497uv6tj 2000 1000000 +``` + +```bash +# run in grantee mode +celestia full start --core.ip full.consensus.mocha-4.celestia-mocha.com --p2p.network=mocha --granter.address=celestia1v96seg23ehfhfjwk0wcy3s5y0krptt284vh236 +``` + ## Verifying balances and transactions Before diving into the specifics of verifying balances and transactions, @@ -60,11 +111,10 @@ streamlining the process for developers and users alike. ### Check balance of the new DA light node To check the balance of a new light node, use the following command: - + ```bash -celestia state balance --node.store ~/.celestia-light-mocha-4/ +celestia state balance ``` - Example response when the account balance does not exist: @@ -86,8 +136,8 @@ state, you must initially fund the light node with the least amount of funds using the following command: ```bash -celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ - --node https://rpc.celestia-mocha.com:443 \ +celestia-appd tx bank send $GRANTER_ADDRESS $GRANTEE_ADDRESS 10000utia \ + --node $RPC_URL \ --chain-id mocha-4 \ --keyring-backend test \ --fees 20000utia \ @@ -101,7 +151,7 @@ celestia-appd tx bank send [granter_address] [grantee_address] 10000utia \ To submit a blob, utilize the following command: ```bash -celestia blob submit --input-file blob.json --node.store ~/.celestia-light-mocha-4/ +celestia blob submit --input-file blob.json ``` @@ -112,7 +162,7 @@ After submitting a blob, you can check the light node account's balance to verify that the fees have been deducted: ```bash -celestia state balance --node.store ~/.celestia-light-mocha-4/ +celestia state balance ``` @@ -127,13 +177,13 @@ Example output showing fees are not deducted: } ``` -### Third-party account: +### Third-party account To confirm that the fees have been deducted from the third-party account that granted the fee allowance, run: ```bash -celestia-appd query bank balances [granter_address] \ +celestia-appd query bank balances $GRANTER_ADDRESS \ --node https://rpc.celestia-mocha.com:443 --denom utia ``` From 844e2222162231e04596200ba3a22e62111b427b Mon Sep 17 00:00:00 2001 From: jcstein Date: Thu, 18 Apr 2024 22:15:22 -0400 Subject: [PATCH 10/10] docs: updates to feegrant guide --- developers/feegrant-for-blobs.md | 223 +++++++++++++++++++------------ 1 file changed, 135 insertions(+), 88 deletions(-) diff --git a/developers/feegrant-for-blobs.md b/developers/feegrant-for-blobs.md index 087461f1399..e320c58fe12 100644 --- a/developers/feegrant-for-blobs.md +++ b/developers/feegrant-for-blobs.md @@ -9,108 +9,99 @@ funding it, enabling a third-party account to cover the transaction fees. ## Pre-requisites -- celestia-app CLI installed -- celestia-node and CLI tools installed +- celestia-node binary (`celestia`) [installed](../nodes/celestia-node.md) - Access to a Mocha node (e.g., `https://rpc.celestia-mocha.com:443`) - Running DA Light node on Mocha testnet -- Separate Celestia account with sufficient funds +- One account with sufficient funds, the "granter" +- One account with no funds, the "grantee" ## Introduction Each DA node contains a Celestia account that is used to pay for blobs submissions. To unify the fee payment process, the FeeGrant module -allows a third-party account to pay for the fees incurred by the DA node's -account. You will need one account that will contain the funds and another -account that will be in the DA node. You will see the DA node's account -once you initialize the node. +allows a third-party account (granter) to pay for the fees incurred by +a DA node's (grantee) account. You will need one account that will +contain the funds, the granter, and another account that will be in the +DA node you run to post blobs, the grantee. You will see the DA node's account +once you initialize the node. Learn more about managing accounts with +`cel-key` in [create a wallet with celestia-node](./celestia-node-key#create-a-wallet-with-celestia-node). -## Granting fee allowances using celestia-appd +## Granting fee allowances using celestia-node -To grant fee allowances, allowing a third-party (granter) account to pay -for the fees incurred by a Celestia data availability node (grantee) -account, use the following commands. +To get started granting the fee allowance, you will need +two separate keys to run the light node with. One to begin the +FeeGrant as the granter and another to use the FeeGrant as the grantee. -Set your account addresses for grantee and granter, and -the RPC URL: +Set some variables for your accounts for the remainder of the guide: ```bash export GRANTER_ADDRESS= export GRANTEE_ADDRESS= -export RPC_URL=https://rpc.celestia-mocha.com:443 +export RPC_URL=rpc.celestia-mocha.com ``` -Then, send the feegrant transaction: +### FeeGrant module implementation in celestia-node -```bash -celestia-appd tx feegrant grant \ - $GRANTER_ADDRESS $GRANTEE_ADDRESS \ - --node $RPC_URL \ - --spend-limit 1000000utia \ - --allowed-messages "/cosmos.bank.v1beta1.MsgSend,/celestia.blob.v1.MsgPayForBlobs" \ - --chain-id mocha-4 \ - --keyring-backend test \ - --fees 20000utia \ - --broadcast-mode block \ - --yes -``` +Using celestia-node, you now can easily give permission for +other nodes to submit transactions on your behalf. It is also +possible to revoke the grant. -Example: -[FeeGrant transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) +The node that receives the grant has to run a node with the +`--granter.address=$GRANTER_ADDRESS>` flag to use FeeGrant functionality. -## Granting fee allowances using celestia-node +The granter address will be stored until the next run of your local node. +So, in case the granter revokes permission, you will have to restart the +node without this flag. -**WIP** +::: tip +Transactions paid for by the the FeeGrant module will consume more gas than +regular `PayForBlobs` transactions. -Notes +| Fee and transaction type | Transaction 1 | Transaction 2 | +|--------------------------------|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------| +| 0.000176 fee with feegrant on Mocha testnet | [Link](https://mocha.celenium.io/tx/82384c8006c6cf73072ffeb160f78c659447dba1757e4a4f6d5e6684935acc61) | [Link](https://mocha.celenium.io/tx/83fa70a496eaf4fa21da43c88c1f0bf8f9aa6676ec1d47f183fca948ab418f94) | +| 0.00016 fee without feegrant on Mocha testnet | [Link](https://mocha.celenium.io/tx/9e15dcf7e82288bdf0efc06edf92a30eead60d5ed6518a4721fee1bc34613e2c) | [Link](https://mocha.celenium.io/tx/a670112dee5bc2001b18225587f2cce86c97016a87d33cc1425b755518050348) | -- using node you now can easily give permission for other nodes to submit transactions on -your behalf(I mean your node will pay fees for these txs) -- you can revoke the grant as well -- The node that receives the grant has to run a node with -`--granter.address=celestia1v96seg23ehfhfjwk0wcy3s5y0krptt284vh236` to use -granting functionality. +::: -The granter address will be stored until the next run of your local node. -So, in case the granter revokes permission, you will have to restart the -node without this flag. I guess, important to know that such transactions -(with granter) will consume more gas than the regular ones. +### Grant permission for an allowance as a granter -This PR also added a `gasMultiplier`, for the transactions with the Options. -Not sure if is it relevant for docs or not. -I’ve also added a specific error for the case when you run your node as a -grantee, but the granter revokes his permission. In this case, your tx will -be failed with an error: -granter has revoked the grant . This will mean that you have to restart the -node w/o a flag. +First, your node will need to be running with a command similar to: ```bash -# to grant permission, you’ll have to execute: -celestia state grant-fee celestia12psg90lwvxdktnqerr2p5mxuw2v3je497uv6tj 2000 1000000 +celestia light start --p2p.network mocha --core.ip $RPC_URL \ + --keyring.accname granter_key ``` +Then, grant the fee to the grantee: + ```bash -# revoke -celestia state revoke-grant-fee celestia12psg90lwvxdktnqerr2p5mxuw2v3je497uv6tj 2000 1000000 +celestia state grant-fee $GRANTEE_ADDRESS 2000 1000000 ``` +Note that the `--amount uint` flag specifies the spend limit (in utia) for the +grantee. The default value is 0 which means the grantee does not have a spend +limit. + +To set a limit of 42069 utia, use the following command: + ```bash -# run in grantee mode -celestia full start --core.ip full.consensus.mocha-4.celestia-mocha.com --p2p.network=mocha --granter.address=celestia1v96seg23ehfhfjwk0wcy3s5y0krptt284vh236 +celestia state grant-fee $GRANTEE_ADDRESS 2000 1000000 \ + --amount 42069 ``` -## Verifying balances and transactions +Find the [example transaction on Celenium](https://mocha.celenium.io/tx/532c2d63b0732e335def1cb7f805bb798793fda43f88a955c5a9224dc6d0433e). -Before diving into the specifics of verifying balances and transactions, -it's important to note that currently, it's necessary to fund the light node -for its transactions to be included in the state of the chain. -This step adds an extra layer of complexity and are actively working on improving -the user experience. Future updates to the nodes implementations will aim to -make this step non-mandatory for the FeeGrant module to function effectively, -streamlining the process for developers and users alike. +## Using a FeeGrant allowance as a grantee in celestia-node -### Check balance of the new DA light node +First, start your node with the grantee account: -To check the balance of a new light node, use the following command: +```bash +celestia light start --core.ip $RPC_URL --p2p.network=mocha + --granter.address=$GRANTER_ADDRESS +``` + +To check the balance of a light node, use the following command: ```bash celestia state balance @@ -129,33 +120,30 @@ Example response when the account balance does not exist: This indicates that the light node currently does not have any funds. -### Funding the light node - -As of now, to ensure the light node's transactions are included in the -state, you must initially fund the light node with the least amount -of funds using the following command: +Now submit a blob: ```bash -celestia-appd tx bank send $GRANTER_ADDRESS $GRANTEE_ADDRESS 10000utia \ - --node $RPC_URL \ - --chain-id mocha-4 \ - --keyring-backend test \ - --fees 20000utia \ - --broadcast-mode block \ - --yes \ - --home ~/.celestia-app/ +celestia blob submit 0x42690c204d39600fddd3 0x6665656772616e74 ``` -### Submitting a blob +You'll see the height and the commitment of your blob: -To submit a blob, utilize the following command: - -```bash -celestia blob submit --input-file blob.json +```json +{ + "result": { + "height": 1639397, + "commitments": [ + "19L/C4iBEsqXGzC5ZxJ3vtuGBiAdQAMIEnbYjKEGcac=" + ] + } +} ``` - -### Checking account balances after submission +After the transactions made making this guide, +[see that the account balance is still 0 utia](https://mocha.celenium.io/address/celestia1e500l0nlwqj7x5vsqcxqd8rns5khvfw0skgu60). + + +## Checking account balances after submission Light node account: After submitting a blob, you can check the light node account's balance @@ -172,14 +160,73 @@ Example output showing fees are not deducted: { "result": { "denom": "utia", - "amount": "10000" + "amount": "0" } } ``` -### Third-party account +## Optional: Revoke permission for a FeeGrant allowance as a granter + +To revoke the feegrant, run your light node as the granter and run: + +```bash +celestia state revoke-grant-fee $GRANTEE_ADDRESS 2000 1000000 +``` + +There is also a specific error for the case when you run your node as a +grantee, but the granter revokes their permission. In this case, your transaction will +fail with the error: `granter has revoked the grant` +This will mean that you have to restart the node without the `granter.address` +flag. + + +### Optional: Submitting a blob from file input + +To submit a blob from file input: + +```bash +celestia blob submit --input-file blob.json +``` + + +## Optional: Granting fee allowances using celestia-appd + +To grant fee allowances, allowing a third-party (granter) account to pay +for the fees incurred by a Celestia data availability node (grantee) +account, use the following commands. + +Set your account addresses for grantee and granter, and +the RPC URL: + +```bash +export GRANTER_ADDRESS= +export GRANTEE_ADDRESS= +export RPC_URL=https://rpc.celestia-mocha.com:443 +``` + +Then, send the feegrant transaction: + + +```bash +celestia-appd tx feegrant grant \ + $GRANTER_ADDRESS $GRANTEE_ADDRESS \ + --node $RPC_URL \ + --spend-limit 1000000utia \ + --allowed-messages "/cosmos.bank.v1beta1.MsgSend,/celestia.blob.v1.MsgPayForBlobs" \ + --chain-id mocha-4 \ + --keyring-backend test \ + --fees 20000utia \ + --broadcast-mode block \ + --yes +``` + + +Example: +[FeeGrant transaction on Mocha](https://mocha.celenium.io/tx/802a17777fbeab416f6fa2c25f0c56dd9cc8a92afc2a96293d114ac7c22efb5c) + +### Optional: Checking the granter's account -To confirm that the fees have been deducted from the third-party account that +To confirm that the fees have been deducted from the granter's account that granted the fee allowance, run: ```bash