As one of the primary use case of the Fee Grant module is to help with onboarding new users, this section of the guide will show how to allow users to execute transactions using the allowance granted to them.
Now that an allowance has been assigned to an account address, you should be able to verify the details of that grant. The returned information will include the granter's address, the allowance amount, and any other conditions set by the granter, such as the expiration date of the allowance.
The following command using secretcli will give the details of a grant allowance:
Results:
This can also be achieved via the following API endpoint where api_endpoint is an API endpoint connected to one of the Archway networks (Testnet or Mainnet). granter is the address that granted the allowance and grantee is the address that received the allowance:
Results:
The following example will allow a user to unwrap sSCRT into SCRT using a feegrant on mainnet.
Before moving forward, ensure that you have completed the following prerequisites:
Set the fee granter and contract addresses.
Define the transaction details which includes the message to the contract (MsgExecuteContract) and sign and broadcast the transaction.
The Fee Grant faucet is backend appilication that allows you to give out fee grants to users.
This tutorial explores how to manage fee grants using secretjs. The Faucet serves as a backend service, granting, revoking, and querying fee allowances for blockchain addresses through a simple HTTP interface.
Follow these steps to install and run the Fee Grant Faucet.
Git
Node.js
npm (Node Package Manager)
Clone the repository to your local machine and navigate to the project directory:
Install the necessary Node.js dependencies:
Create a .env file in the root of the project directory. Use the .env.sample provided in the repository as a reference and fill in the necessary details. Ensure these variables are correctly set in your .env file for the script to function.
Before diving into the code, it's essential to set up the environment:
CHAIN_ID: Identifier of the blockchain network.
LCD_NODE: URL of the Light Client Daemon (LCD) for interacting with the blockchain.
FAUCET_MNEMOMIC: Mnemonic for the wallet used in transactions.
Don't forget to fill up your Faucet with SCRT.
Start the application:
The script uses Node Express, a popular Node.js framework, to create a web server:
Endpoint Creation: An endpoint /claim/:address is set up. It's designed to handle fee grants for a specified blockchain address passed as a parameter.
The script includes robust functionality for managing fee grants:
Address Validation: Uses validateAddress to ensure the provided blockchain address is valid.
Querying Balance and Fee Grants: Before granting a fee, the script can check the existing balance and any active fee grants for the address.
The core functionality of the script lies in managing fee grants:
Function giveFeeGrant: Depending on the situation, this function either revokes an old fee grant and issues a new one or issues a new grant directly.
Message Construction:
MsgRevokeAllowance: Used to revoke an existing fee grant.
MsgGrantAllowance: Used to grant a new fee allowance to an address.
Handling transactions is a critical part of the script:
Broadcasting Transactions: Utilizes secretjs.tx.broadcast to send the transaction to the blockchain.
Transaction Parameters: Includes memo, fee, and gas limit details.
JSON Output: The script outputs a JSON object with the feegrant details, including grantee, granter, spend limit, and expiration.
The script incorporates error handling mechanisms:
Invalid Addresses: Returns an error if the provided address is invalid.
Transaction Failures: Catches and logs transaction-related errors.
Here are some key code snippets and example responses:
Endpoint /claim/:address:
Example JSON Response from the faucet:
Building a smart contract dapp that enables users to request a fee grant is a challenging task since all transactions necessitate the payment of transaction fees. However, there are several methods that can be utilized. Here are a few examples:
The granter can manually execute each fee grant allowance transaction using the secretcli
Construct a deployment script containing addresses that you wish to assign a fee grant to. This script will utilize the secretcli to perform the fee grant transaction for each specified address.
Implement a simple frontend application that verifies and validates a user's account. After confirming that they are the account owner, the application would execute a Javascript transaction with secret.js to carry out the fee grant transaction.
The secretcli is a key tool for accessing the fundamental functionalities of the Archway Blockchain. To install secretcli, refer to Install. Here is an illustration of a typical transaction for creating a grant allowance:
Let's break down a few of the components:
granter_address: This value represents the address of the account providing tokens to the grantee for transaction execution.
grantee_address: This denotes the account receiving tokens, enabling it to perform transactions using these grants.
allowed-messages: Through the AllowedMsgAllowance type, you can limit the message type a grantee can use the grant for. If not specified, all messages are allowed.
expiration: The deadline by which the allowance must be used or it will expire.
spend-limit: The maximum allowance provided to the grantee. This amount is adjusted as tokens are utilized.
This section demonstrates how to create a grant allowance using secretjs. By following the steps outlined in this section, you'll be able to structure a grant allowance message, and execute the necessary transaction which will grant allowances to designated accounts.
The allowance message comprises three essential components: the granter, grantee, and the actual allowance. As previously mentioned, the granter is the address responsible for granting the allowance, while the grantee is the recipient who can utilize the granted allowance. The allowance component is slightly more intricate, with its structure dependent on the specific type of allowance employed.
To illustrate, let's examine the structure of a grantMsg using the following example:
Now, all that remains is to execute the transaction:
You can find a working example of this in the Fee Grant Faucet here.
An allowance in the context of the Fee Grant module is a specified amount of tokens that a granter permits a grantee to use for paying transaction fees. It should be noted that there can be only one existing fee grant allowed for a grantee and granter and self grants are not allowed.
In the allowance mechanism, there are two key players:
The Granter: The granter is the account that provides the allowance. This account will be debited whenever the grantee pays transaction fees using the allowance.
The Grantee: The grantee is the account that receives the allowance. This account can use the allowance to pay for transaction fees.
There are three allowance types that can be granted:
Basic Fee Allowance: This is a simple allowance model where a granter can specify a maximum limit up to which a grantee can use tokens to pay transaction fees. The allowance can also have an expiration date after which it can no longer be used.
Periodic Fee Allowance: This allowance model is more complex and versatile. It allows the granter to set a periodic reset of the allowance, creating a recurring "budget" for the grantee. This could be used to create a daily, weekly, or monthly allowance, for example.
Allowed Msg Allowance: Creates allowance only for specified message types.
In this guide, our emphasis will be on generating allowances utilizing the BasicAllowance type. For detailed information on each allowance type, please refer to the following.
Granting an allowance involves the granter sending a special type of transaction that includes information about the grantee and the details of the allowance. Once the transaction is included in a block, the allowance is active and can be used by the grantee.
Revoking an allowance is also a simple process. The granter sends a revoke transaction that includes the address of the grantee. Once this transaction is processed, the grantee can no longer use the allowance to pay fees.
It's important to note that allowances may have an expiry date set by the granter. Once an allowance has expired, it can no longer be used to pay for transaction fees. Grantees must be aware of their allowance expiry dates and ensure that they use their allowances before they expire.
Similarly, if an allowance is exhausted (i.e., the fees for a transaction exceed the remaining allowance), the transaction will not be processed.
The Secret Network Fee Grant module is an interesting and powerful feature that allows accounts to grant allowances to other accounts, enabling them to pay fees for transactions from the allowance. This feature opens up numerous possibilities, and one popular use case involves subsidizing the onboarding process for new users who may not possess the native network token required to execute initial transactions.
This guide provides basic solutions for achieving two key goals: first, granting users an allowance on the Secret Network, and second, enabling the end user to use this allowance to execute transactions.