# Understand the Feegrant Module
The 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 feegrant module:
BasicAllowanceGrantee uses fees from a granter's account. The allowance can have a one-time limit, an expiration, or no limit.
PeriodicAllowanceGrantee 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 (
simapp). - You will set Alice up to be a validator.
- Bob will be the grantee, who receives a
BasicAllowancethat allows Bob to sendkudostokens to Alice, even though Bob has zerostaketo pay for fees. - Alice will be the granter, who grants a
BasicAllowanceto Bob.
# Requirements
Before you start the tutorial, you need to install the simd binary.
Clone the cosmos-sdk repository:
Change directories and check out v0.44.0:
Install the simd binary:
Check to make sure the installation was successful:
The version number 0.44.0 is output to the console.
# Configuration
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 simd binary.
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 (simapp).
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.
The BasicAllowance is a permission for a grantee to use up fees until the spend_limit or 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.
Send 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:
Note how 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 revoke command.
Revoke allowance:
View the allowance:
# 🎉 Congratulations 🎉
By completing this tutorial, you have learned how to use the feegrant module!
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.