Merge Pull Request cosmos#3241: Add Fee & Gas Spec

docs/spec/auth/README.md

@@ -16,14 +16,15 @@ This module will be used in the Cosmos Hub.
 1. **[State](state.md)**
     1. [Accounts](state.md#accounts)
         1. [Account Interface](state.md#account-interface)
-        1. [Base Account](state.md#baseaccount)
-        1. [Vesting Account](state.md#vestingaccount)
+        2. [Base Account](state.md#baseaccount)
+        3. [Vesting Account](state.md#vestingaccount)
 1. **[Types](types.md)**
     1. [StdFee](types.md#stdfee)
-    1. [StdSignature](types.md#stdsignature)
-    1. [StdTx](types.md#stdtx)
-    1. [StdSignDoc](types.md#stdsigndoc)
+    2. [StdSignature](types.md#stdsignature)
+    3. [StdTx](types.md#stdtx)
+    4. [StdSignDoc](types.md#stdsigndoc)
 1. **[Keepers](keepers.md)**
     1. [AccountKeeper](keepers.md#account-keeper)
 1. **[Handlers](handlers.md)**
     1. [Ante Handler](handlers.md#ante-handler)
+1. **[Gas & Fees](gas_fees.md)**

docs/spec/auth/gas_fees.md

@@ -0,0 +1,28 @@
+# Gas & Fees
+
+Fees serve two purposes for an operator of the network.
+
+Fees limit the growth of the state stored by every full node and allow for
+general purpose censorship of transactions of little economic value. Fees
+are best suited as an anti-spam mechanism where validators are disinterested in
+the use of the network and identities of users.
+
+Fees are determined by the gas limits and gas prices transactions provide.
+Operators should set minimum gas prices when starting their nodes. They must set
+the unit costs of gas in each token denomination they wish to support:
+
+`gaiad start ... --minimum-gas-prices=0.00001steak,0.05photinos`
+
+When adding transactions to mempool or gossipping transactions, validators check
+if the transaction's gas prices, which are determined by the provided fees, meet
+any of the validator's minimum gas prices. In other words, a transaction must
+provide a fee of at least one denomination that matches a validator's minimum
+gas price.
+
+Tendermint does not currently provide fee based mempool prioritization, and fee
+based mempool filtering is local to node and not part of consensus. But with
+minimum gas prices set, such a mechanism could be implemented by node operators.
+
+Because the market value for tokens will fluctuate, validators are expected to
+dynamically adjust their minimum gas prices to a level that would encourage the
+use of the network.