Fee Grants

With the Provenance Blockchain, it's possible for one account (the granter) to pay for the transaction(s) of another account (the grantee) using the x/feegrant module.

With a feegrant, there is a granter, a grantee, and an allowance.

"Granter" - The account that will be paying.

"Grantee" - The account that executes Txs.

"Allowance" - Limitations on how funds can be spent.

The granter gives the grantee the ability to have the granter pay for Txs issued by the grantee (possibly with limitations).

Overview

First, the granter decides what limitations they want on how the grantee spends the granted funds. That will determine which type of allowance to use.

There are three types of allowances available:

BasicAllowance - Can be unlimited, or limited by amount and/or expiration date.

PeriodicAllowance - Extends a BasicAllowance to also limit spending to a specified amount over a specified amount of time (e.g. 10B nhash per day).

AllowedMsgAllowance - Limits another allowance to a specified set of Msg types.

The most common setup is either a BasicAllowance or an AllowedMsgAllowance with a BasicAllowance in it.

The provenanced CLI will automatically use the correct allowance type based on the flags provided.

Setup

Once the decisions have been made on the allowance, the granter can create the grant using a MsgGrantAllowance. This is most easily done using the provenanced command.

The command to execute here is provenanced tx feegrant grant <granter_key_or_address> <grantee> [flags]

Key flags:

-spend-limit <coins> Sets the spend-limit for the allowance.

-expiration <datetime stamp> Sets the expiration of the allowance. Uses ISO8601 format, e.g. 2022-01-30T15:04:05Z.

-period <seconds> Sets the number of seconds in a period (for a PeriodicAllowance).

-period-limit <coins> Sets the amount that can be spent each period.

-allowed-messages <msg list> Sets the list of msgs that this grant can be used on, e.g. "/cosmos.gov.v1.MsgSubmitProposal,/cosmos.gov.v1.MsgVote".

Note that this command ignores the --from flag, and gets that value instead from the first argument provided.

Setup Examples

Note: All of these examples assume that you have a properly set up client.toml.

Also, they assume that either you're using the system's default config home or you have the PIO_HOME environment variable defined and set to your provenanced config home directory.

In all of these examples:

The granter will have the address pb1granterlllllllllllllllllllllllll0j68cl.

The grantee will have the address pb1granteelllllllllllllllllllllllllg42c4h.

These commands are for the granter to execute in order to set up the fee grant.

The granter is willing to pay for any and all Txs that the grantee issues.

plain text
$provenanced tx feegrant grant pb1granterlllllllllllllllllllllllll0j68cl \
    pb1granteelllllllllllllllllllllllllg42c4h \
    --gas auto --gas-prices 1nhash

The granter wants to pay for all of the grantee's ibc update-params msgs without expiration.

plain text
$provenanced tx feegrant grant pb1granterlllllllllllllllllllllllll0j68cl \
    pb1granteelllllllllllllllllllllllllg42c4h \
    --allowed-messages '/ibc.core.client.v1.MsgUpdateClient' \
    --gas auto --gas-prices 1nhash

The granter is willing to pay up to 100B nhash (100 hash) on any and all Txs that the grantee issues.

plain text
$provenanced tx feegrant grant pb1granterlllllllllllllllllllllllll0j68cl \
    pb1granteelllllllllllllllllllllllllg42c4h \
    --spend-limit 100000000000 \
    --gas auto --gas-prices 1nhash

The granter is willing to pay up to 100B nhash (100 hash) on any Txs that the grantee issues until the end of 2026.

plain text
$provenanced tx feegrant grant pb1granterlllllllllllllllllllllllll0j68cl \
    pb1granteelllllllllllllllllllllllllg42c4h \
    --spend-limit 100000000000 \
    --expiration '2026-12-31T23:59:59Z' \
    --gas auto --gas-prices 1nhash

Using a Fee Grant.

After the granter has set up the feegrant, the grantee can use it! To use it, the grantee sets the granter field in the Tx's auth info for any Txs that the granter will pay for. This can be done using the --fee-granter flag on any tx command.

For example, to vote yes on governance proposal 5 using a feegrant, the grantee could execute this command:

plain text
$provenanced tx gov vote 5 yes \
    --fee-granter pb1granterlllllllllllllllllllllllll0j68cl \
    --from pb1granteelllllllllllllllllllllllllg42c4h \
    --gas auto --gas-prices 1nhash