From f5e6685dfd53bc0dfdb8cf874710131c3e0b0dbc Mon Sep 17 00:00:00 2001
From: Zaki Manian <zaki@manian.org>
Date: Thu, 24 Jan 2019 08:38:27 -0800
Subject: [PATCH] Merge Pull Request #3241: Add Fee & Gas Spec

---
 docs/spec/auth/README.md   | 11 ++++++-----
 docs/spec/auth/gas_fees.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 5 deletions(-)
 create mode 100644 docs/spec/auth/gas_fees.md

diff --git a/docs/spec/auth/README.md b/docs/spec/auth/README.md
index 6db6db226..be6647a80 100644
--- a/docs/spec/auth/README.md
+++ b/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)**
diff --git a/docs/spec/auth/gas_fees.md b/docs/spec/auth/gas_fees.md
new file mode 100644
index 000000000..fbe210394
--- /dev/null
+++ b/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.