Add specs for feegrant (#8496)
* add specs * address review comments * Address review changes Co-authored-by: Amaury <amaury.martiny@protonmail.com> * review changes * address review changes Co-authored-by: Marie Gauthier <marie.gauthier63@gmail.com> Co-authored-by: Amaury <amaury.martiny@protonmail.com> Co-authored-by: Marie Gauthier <marie.gauthier63@gmail.com>
This commit is contained in:
atheeshp
GitHub
parent
0ddb7041a8
commit
0af248b95b
|
|
@ -0,0 +1,70 @@
|
|||
<!--
|
||||
order: 1
|
||||
-->
|
||||
|
||||
# Concepts
|
||||
|
||||
## FeeAllowanceGrant
|
||||
|
||||
`FeeAllowanceGrant` is stored in the KVStore to record a grant with full context. Every grant will contain `granter`, `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 (`BasicFeeAllowance` or `PeriodicFeeAllowance`, see below) is granted to `grantee`. `allowance` accepts an interface which implements `FeeAllowanceI`, encoded as `Any` type. There can be only one existing fee grant allowed for a `grantee` and `granter`, self grants are not allowed.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/feegrant/v1beta1/feegrant.proto#L75-L81
|
||||
|
||||
`FeeAllowanceI` looks like:
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/x/feegrant/types/fees.go#L9-L32
|
||||
|
||||
## Fee Allowance types
|
||||
There are two types of fee allowances present at the moment:
|
||||
- `BasicFeeAllowance`
|
||||
- `PeriodicFeeAllowance`
|
||||
|
||||
## BasicFeeAllowance
|
||||
|
||||
`BasicFeeAllowance` is permission for `grantee` to use fee from a `granter`'s account. If any of the `spend_limit` or `expiration` reaches its limit, the grant will be removed from the state.
|
||||
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/feegrant/v1beta1/feegrant.proto#L13-L26
|
||||
|
||||
- `spend_limit` is the limit of coins that are allowed to be used from the `granter` account. If it is empty, it assumes there's no spend limit, `grantee` can use any number of available tokens from `granter` account address before the expiration.
|
||||
|
||||
- `expiration` specifies 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 `spend_limit` and `expiration`, it is still a valid grant. It won't restrict the `grantee` to use any number of tokens from `granter` and it won't have any expiration. The only way to restrict the `grantee` is by revoking the grant.
|
||||
|
||||
## PeriodicFeeAllowance
|
||||
|
||||
`PeriodicFeeAllowance` 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.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/feegrant/v1beta1/feegrant.proto#L28-L73
|
||||
|
||||
- `basic` is the instance of `BasicFeeAllowance` which is optional for periodic fee allowance. If empty, the grant will have no `expiration` and no `spend_limit`.
|
||||
|
||||
- `period` is the specific period of time or blocks, after each period passes, `period_spend_limit` will be reset.
|
||||
|
||||
- `period_spend_limit` specifies the maximum number of coins that can be spent in the period.
|
||||
|
||||
- `period_can_spend` is the number of coins left to be spent before the period_reset time.
|
||||
|
||||
- `period_reset` keeps 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.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/cmd.go#L224-L235
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/client/tx/tx.go#L120
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/x/auth/tx/builder.go#L268-L277
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/tx/v1beta1/tx.proto#L160-L181
|
||||
|
||||
Example cmd:
|
||||
```go
|
||||
./simd tx gov submit-proposal --title="Test Proposal" --description="My awesome proposal" --type="Text" --from validator-key --fee-account=cosmos1xh44hxt7spr67hqaa7nyx5gnutrz5fraw6grxn --chain-id=testnet --fees="10stake"
|
||||
```
|
||||
|
||||
## DeductGrantedFeeDecorator
|
||||
|
||||
`feegrant` module also adds a `DeductGrantedFeeDecorator` ante handler. Whenever a transaction is being executed with `granter` field set, then this ante handler will check whether `payer` and `granter` have proper fee allowance grant in state. If it exists the fees will be deducted from the `granter`'s account address. If the `granter` field isn't set then this ante handler works as normal fee deductor.
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
<!--
|
||||
order: 2
|
||||
-->
|
||||
|
||||
# State
|
||||
|
||||
## FeeAllowance
|
||||
|
||||
Fee Allowances are identified by combining `Grantee` (the account address of fee allowance grantee) with the `Granter` (the account address of fee allowance granter).
|
||||
|
||||
Fee allowances are stored in the state as follows:
|
||||
|
||||
- FeeAllowance: `0x00 | grantee_addr_len (1 byte) | grantee_addr_bytes | granter_addr_len (1 byte) | granter_addr_bytes -> ProtocolBuffer(FeeAllowance)`
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/x/feegrant/types/feegrant.pb.go#L358-L363
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
<!--
|
||||
order: 3
|
||||
-->
|
||||
|
||||
# Messages
|
||||
|
||||
## Msg/GrantFeeAllowance
|
||||
|
||||
A fee allowance grant will be created with the `MsgGrantFeeAllowance` message.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/feegrant/v1beta1/tx.proto#L22-L28
|
||||
|
||||
## Msg/RevokeFeeAllowance
|
||||
|
||||
An allowed grant fee allowance can be removed with the `MsgRevokeFeeAllowance` message.
|
||||
|
||||
+++ https://github.com/cosmos/cosmos-sdk/blob/d97e7907f176777ed8a464006d360bb3e1a223e4/proto/cosmos/feegrant/v1beta1/tx.proto#L33-L37
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
<!--
|
||||
order: 4
|
||||
-->
|
||||
|
||||
# Events
|
||||
|
||||
The feegrant module emits the following events:
|
||||
|
||||
# Handlers
|
||||
|
||||
### MsgGrantFeeAllowance
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
| -------- | ------------- | ------------------ |
|
||||
| message | action | set_feegrant |
|
||||
| message | granter | {granterAddress} |
|
||||
| message | grantee | {granteeAddress} |
|
||||
|
||||
### MsgRevokeFeeAllowance
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
| -------- | ------------- | ------------------ |
|
||||
| message | action | revoke_feegrant |
|
||||
| message | granter | {granterAddress} |
|
||||
| message | grantee | {granteeAddress} |
|
||||
|
||||
### Exec fee allowance
|
||||
|
||||
| Type | Attribute Key | Attribute Value |
|
||||
| -------- | ------------- | ------------------ |
|
||||
| message | action | use_feegrant |
|
||||
| message | granter | {granterAddress} |
|
||||
| message | grantee | {granteeAddress} |
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
<!--
|
||||
order: 0
|
||||
title: Fee grant
|
||||
parent:
|
||||
title: "feegrant"
|
||||
-->
|
||||
|
||||
## Abstract
|
||||
|
||||
This document specifies the feegrant module. For the full ADR, please see [Fee Grant ADR-029](https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/docs/architecture/adr-029-fee-grant-module.md).
|
||||
|
||||
This module allows accounts to grant fee allowances and to use fees from their accounts. Grantees can execute any transaction without the need to maintain sufficient fees.
|
||||
|
||||
## Contents
|
||||
|
||||
1. **[Concepts](01_concepts.md)**
|
||||
- [FeeAllowanceGrant](01_concepts.md#feeallowancegrant)
|
||||
- [Fee Allowance types](01_concepts.md#fee-allowance-types)
|
||||
- [BasicFeeAllowance](01_concepts.md#basicfeeallowance)
|
||||
- [PeriodicFeeAllowance](01_concepts.md#periodicfeeallowance)
|
||||
- [FeeAccount flag](01_concepts.md#feeaccount-flag)
|
||||
- [DeductGrantedFeeDecorator](01_concepts.md#deductgrantedfeedecorator)
|
||||
2. **[State](02_state.md)**
|
||||
- [FeeAllowance](02_state.md#feeallowance)
|
||||
3. **[Messages](03_messages.md)**
|
||||
- [Msg/GrantFeeAllowance](03_messages.md#msggrantfeeallowance)
|
||||
- [Msg/RevokeFeeAllowance](03_messages.md#msgrevokefeeallowance)
|
||||
3. **[Events](04_events.md)**
|
||||
- [MsgGrantFeeAllowance](04_events.md#msggrantfeeallowance)
|
||||
- [MsgrevokeFeeAllowance](04_events.md#msgrevokefeeallowance)
|
||||
- [Exec fee allowance](04_events.md#exec-fee-allowance)
|
||||
|
||||
Loading…
Reference in New Issue