Skip to content

Commit

Permalink
Add specs for feegrant (#8496)
Browse files Browse the repository at this point in the history 
* add specs

* address review comments

* Address review changes

Co-authored-by: Amaury <[email protected]>

* review changes

* address review changes

Co-authored-by: Marie Gauthier <[email protected]>

Co-authored-by: Amaury <[email protected]>
Co-authored-by: Marie Gauthier <[email protected]>
  • Loading branch information
@atheeshp @amaury1093 @blushi
3 people authored Feb 4, 2021
1 parent 0ddb704 commit 0af248b
Show file tree
Hide file tree
Showing 5 changed files with 167 additions and 0 deletions.
70 changes: 70 additions & 0 deletions x/feegrant/spec/01_concepts.md
View file
Original file line number Diff line number Diff line change
@@ -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.
15 changes: 15 additions & 0 deletions x/feegrant/spec/02_state.md
View file
Original file line number Diff line number Diff line change
@@ -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
17 changes: 17 additions & 0 deletions x/feegrant/spec/03_messages.md
View file
Original file line number Diff line number Diff line change
@@ -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
33 changes: 33 additions & 0 deletions x/feegrant/spec/04_events.md
View file
Original file line number Diff line number Diff line change
@@ -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} |
32 changes: 32 additions & 0 deletions x/feegrant/spec/README.md
View file
Original file line number Diff line number Diff line change
@@ -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)

0 comments on commit 0af248b

Please sign in to comment.