Grant is stored in the KVStore to record a grant with full context. Every grant will contain
grantee and what kind of
allowance is granted.
granter is an account address who is giving permission to
grantee (the beneficiary account address) to pay for some or all of
grantee's transaction fees.
allowance defines what kind of fee allowance (
PeriodicAllowance, see below) is granted to
allowance accepts an interface which implements
FeeAllowanceI, encoded as
Any type. There can be only one existing fee grant allowed for a
granter, self grants are not allowed.
FeeAllowanceI looks like:
# Fee Allowance types
There are two types of fee allowances present at the moment:
BasicAllowance is permission for
grantee to use fee from a
granter's account. If any of the
expiration reaches its limit, the grant will be removed from the state.
spend_limitis the limit of coins that are allowed to be used from the
granteraccount. If it is empty, it assumes there's no spend limit,
granteecan use any number of available tokens from
granteraccount address before the expiration.
expirationspecifies an optional time when this allowance expires. If the value is left empty, there is no expiry for the grant.
When a grant is created with empty values for
expiration, it is still a valid grant. It won't restrict the
granteeto use any number of tokens from
granterand it won't have any expiration. The only way to restrict the
granteeis by revoking the grant.
PeriodicAllowance is a repeating fee allowance for the mentioned period, we can mention when the grant can expire as well as when a period can reset. We can also define the maximum number of coins that can be used in a mentioned period of time.
basicis the instance of
BasicAllowancewhich is optional for periodic fee allowance. If empty, the grant will have no
periodis the specific period of time, after each period passes,
period_spend_limitwill be reset.
period_spend_limitspecifies the maximum number of coins that can be spent in the period.
period_can_spendis the number of coins left to be spent before the period_reset time.
period_resetkeeps track of when a next period reset should happen.
# FeeAccount flag
feegrant module introduces a
FeeAccount flag for CLI for the sake of executing transactions with fee granter. When this flag is set,
clientCtx will append the granter account address for transactions generated through CLI.
# Granted Fee Deductions
Fees are deducted from grants in the
x/auth ante handler. To learn more about how ante handlers work, read the Auth Module AnteHandlers Guide.
In order to prevent DoS attacks, using a filtered
x/feegrant incurs gas. The SDK must assure that the
grantee's transactions all conform to the filter set by the
granter. The SDK does this by iterating over the allowed messages in the filter and charging 10 gas per filtered message. The SDK will then iterate over the messages being sent by the
grantee to ensure the messages adhere to the filter, also charging 10 gas per message. The SDK will stop iterating and fail the transaction if it finds a message that does not conform to the filter.
WARNING: The gas is charged against the granted allowance. Ensure your messages conform to the filter, if any, before sending transactions using your allowance.