Add specs for feegrant

x/feegrant/spec/01_concepts.md

@@ -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.

x/feegrant/spec/02_state.md

@@ -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

x/feegrant/spec/03_messages.md

@@ -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

x/feegrant/spec/04_events.md

@@ -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}   |

x/feegrant/spec/README.md

@@ -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)
+