# Understand the Feegrant Module
feegrant (opens new window) module enables the granter (a user, contract, or module) to pay the fees for someone else (the grantee) when the grantee wants to broadcast a transaction on the blockchain. The granter retains full access to their tokens and is able to revoke the allowance at any time.
# Using feegrant to grant an allowance
An often-discussed use case for the
feegrant module is improved onboarding experience, because new users do not have to acquire tokens before they can start interacting with the blockchain or smart contract.
Two fee allowance types (opens new window) are implemented with the
Grantee uses fees from a granter's account. The allowance can have a one-time limit, an expiration, or no limit.
Grantee uses fees from a granter's account. The allowance has a limit that is periodically reset.
In this tutorial, you will set up two tokens in your blockchain: a default token called
stake to use for fees, and another token called
kudos to send to your friends.
- You will learn how to spin up a single-node network using the simulation application in the Cosmos SDK (
- You will set Alice up to be a validator.
- Bob will be the grantee, who receives a
BasicAllowancethat allows Bob to send
kudostokens to Alice, even though Bob has zero
staketo pay for fees.
- Alice will be the granter, who grants a
Before you start the tutorial, you need to install the
Change directories and check out
Check to make sure the installation was successful:
The version number
0.44.0 is output to the console.
If you have used
simd before, you might already have a
.simapp directory in your home directory. To keep the previous data, either save the directory to another location or use the
--home flag and specify a different directory for each command in the following instructions. If you do not want to keep the previous data, remove the previous directory (
rm -rf ~/.simapp).
Run the following commands to configure the
Set the chain ID:
Set the keyring backend (opens new window):
# Key setup
You will have to create a few test keys for your users.
Add a key for Alice, the validator:
Add a key for Bob, the grantee:
If you would like to see an overview of your keys, use:
To avoid having to copy and paste the user addresses, now is a good time to export the user keys to variables that you can access and use for this tutorial.
# Chain setup
The following commands set up a chain using the simulation application (
Initialize the node:
Alice is your validator. Add Alice and an initial balance to the genesis file:
Add Bob and an initial balance to the genesis file:
Note that Bob has only
kudos tokens and is not able to pay for any fees that might be needed.
Generate a transaction to add Alice to the initial validator set:
Add the validator transaction to the genesis file:
# Start chain
You are now ready to start a single node network on your local machine.
Start the chain:
# Grant allowance
Before Bob can send
kudos to Alice, you must set up an allowance for Bob so that Alice pays for any gas fees the transaction might incur.
BasicAllowance is a permission for a grantee to use up fees until the
expiration is reached. Open up a new terminal window and create an allowance with a spend limit of
100000stake and no expiration date:
View the allowance:
# Send tokens
First, check the balances of Alice and Bob. Verifying the initial balance provides a baseline so that you can later confirm if your transaction was successful:
Note that Alice has
4999000000stake because she bonded
1000000stake to become a validator during the chain setup.
Any transaction that is sent using the
tx command can use the
--fee-account flag to specify an account as input to pay for the fees.
kudos tokens from Bob to Alice, while Alice pays the fees:
Look at the balances again:
Notice how Alice has
500stake less than before. The
500stake was added to the transaction that Bob signed.
View the allowance again:
spend_limit has been reduced and Bob now has
99500stake left to spend on fees.
# Revoke allowance
The granter can revoke the allowance from the grantee using the
View the allowance:
# 🎉 Congratulations 🎉
By completing this tutorial, you have learned how to use the
Want a demonstration of x/feegrant and x/authz? In the following video Amaury Martiny, Core Developer at Parity Technologies, and Likhita Polavarapu, Software Developer at Vitwit, present a workshop on the significant UX benefits of both modules and how to integrate them into blockchain applications.
To summarize, this section has explored:
- How to configure and use the simulation application (simapp).
- How to create an allowance.
- How to make a transaction with fees paid by a granter.
- How to revoke an allowance.
There is a lot more that you can do with the
feegrant module. You can add a list of allowed messages, set an expiration date, and set a time duration after which the spend limit is refilled. To learn more about the
feegrant module and different types of allowances, check out the Cosmos SDK Feegrant Module (opens new window) documentation.