Add specs for feegrant

x/feegrant/spec/01_concepts.md

@@ -0,0 +1,71 @@
+<!--
+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 permissoin to `grantee`(another account address) to use fees, where as `grantee` is an account address of beneficiary. and `allowance` is what kind of fee allowance(`BasicFeeAllowance` or `PeriodicFeeAllowance`) is granted to grantee. `allowance` can accepts an interface which implements `FeeAllowanceI` as `Any` type. There can be only one existing feegrant allowed for a `grantee` and `granter`, self grant not allowed.
+
++++ https://github.com/cosmos/cosmos-sdk/blob/master/proto/cosmos/feegrant/v1beta1/feegrant.proto#L75-L81
+
+`FeeAllowanceI` looks like: 
+
++++ https://github.com/cosmos/cosmos-sdk/blob/master/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 one time permission for `grantee` to use fee from a `granter`'s account. if any of the `spend_limit` or `expiration` reached the grant will be removed from the state.
+
+
++++ https://github.com/cosmos/cosmos-sdk/blob/master/proto/cosmos/feegrant/v1beta1/feegrant.proto#L13-L26
+
+- `spend_limit` is a limit of coins that are allowed to use from the `granter` account. If no value mentioned assumes as no limit for coins, `grantee` can use any number of available tokens from `granter` account address before the expiration.
+
+- `expiration` is time of when the grant can be expire. If the value left empty there is no expiry for the grant.
+
+- whenever a grant created with the empty values of `spend_limit` and `expiration` still it is valid grant. It won't restrict the `grantee` to use any number of tokens from `granter` and no expiration. The only way to restrict the `grantee` is 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 mention how many maximum of coins can be used in a mentioned period of time.
+
++++ https://github.com/cosmos/cosmos-sdk/blob/master/proto/cosmos/feegrant/v1beta1/feegrant.proto#L28-L73
+
+- `basic` is the instance of `BasicFeeAllowance` which is optional for periodic fee allowance. if empty grant will have no `expiration` and no `spend_limit`
+
+- `period` is the specific period of time or blocks, after period crossed `period_spend_limit` will be reset. 
+
+- `period_spend_limit` keeps track of how many coins left in the period.
+
+- `period_can_spend` specifies max coins can be used in every period.
+
+- `period_reset` keeps track of when a next period reset should happen.
+
+## FeeAccount flag
+
+`feegrant` module will introduce a `FeeAccount` flag for cli for the sake executing transactions with fee granter, when this flag set `clientCtx` will append the granter account address for transaction generated through cli.
+
+```go 
+message Fee {
+  repeated cosmos.base.v1beta1.Coin amount = 1;
+  uint64 gas_limit = 2;
+  string payer = 3;
+  string granter = 4;
+}
+```
+
+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` has 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 | granter -> ProtocolBuffer(FeeAllowance)`
+
++++ https://github.com/cosmos/cosmos-sdk/blob/master/x/feegrant/types/feegrant.pb.go#L358-L363

x/feegrant/spec/03_messages.md

@@ -0,0 +1,18 @@
+<!--
+order: 3
+-->
+
+# Messages
+
+## MsgGrantFeeAllowance
+
+A fee allowance grant will be created `MsgGrantFeeAllowance` message.
+
++++ https://github.com/cosmos/cosmos-sdk/blob/master/proto/cosmos/feegrant/v1beta1/tx.proto#L22-L28
+
+## MsgRevokeFeeAllowance
+
+An allowed grant fee allowance can be removed with `MsgRevokeFeeAllowance` message.
+
++++ https://github.com/cosmos/cosmos-sdk/blob/master/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 ADR specifies the feegrant module. [Fee Grant](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 be able to execute any transaction even their accounts' are not having gas 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)**
+    - [MsgGrantFeeAllowance](03_messages.md#msggrantfeeallowance)
+    - [MsgRevokeFeeAllowance](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)
+