From a07b235f67d31419ae5adcaf4dc37fdaab85c1d1 Mon Sep 17 00:00:00 2001
From: frog power 4000 <rigel.rozanski@gmail.com>
Date: Wed, 20 Feb 2019 13:21:57 -0500
Subject: [PATCH] Merge PR #3683: spec-spec update, spec file reorg, TOC
 updates

* spec reorg

* ...

* PENDING.md

* @alexanderbez comments
---
 PENDING.md                                    |  1 +
 docs/spec/SPEC-SPEC.md                        | 39 +++++++++----
 .../spec/auth/{gas_fees.md => 01_concepts.md} |  4 +-
 docs/spec/auth/{state.md => 02_state.md}      |  8 +--
 .../spec/auth/{handlers.md => 03_messages.md} |  4 ++
 docs/spec/auth/{types.md => 03_types.md}      | 10 ++--
 docs/spec/auth/{keepers.md => 04_keepers.md}  |  4 +-
 docs/spec/auth/{vesting.md => 05_vesting.md}  |  0
 docs/spec/auth/README.md                      | 36 +++++++-----
 docs/spec/bank/{state.md => 01_state.md}      |  2 +-
 docs/spec/bank/{keepers.md => 02_keepers.md}  | 14 ++---
 .../spec/bank/{messages.md => 03_messages.md} |  4 +-
 docs/spec/bank/{tags.md => 04_tags.md}        |  0
 docs/spec/bank/README.md                      | 20 +++----
 ...1_reference_counting.md => 01_concepts.md} |  2 +
 .../distribution/{state.md => 02_state.md}    |  0
 .../{end_block.md => 03_end_block.md}         |  0
 .../{messages.md => 04_messages.md}           |  0
 .../distribution/{hooks.md => 05_hooks.md}    |  0
 .../spec/distribution/{tags.md => 06_tags.md} |  0
 docs/spec/distribution/README.md              | 19 +++++++
 .../{overview.md => 01_concepts.md}           |  4 +-
 .../spec/governance/{state.md => 02_state.md} | 16 +++---
 .../{messages.md => 03_messages.md}           | 10 ++--
 docs/spec/governance/{tags.md => 04_tags.md}  |  0
 ...rovements.md => 05_future_improvements.md} |  4 +-
 docs/spec/governance/README.md                | 31 ++++++----
 docs/spec/mint/{state.md => 01_state.md}      |  6 +-
 .../{begin_block.md => 02_begin_block.md}     |  0
 docs/spec/mint/README.md                      | 11 +++-
 docs/spec/params/{keeper.md => 01_keeper.md}  |  0
 .../params/{subspace.md => 02_subspace.md}    |  0
 docs/spec/params/README.md                    |  7 ++-
 .../slashing/{overview.md => 01_concepts.md}  | 10 ++--
 docs/spec/slashing/{state.md => 02_state.md}  |  0
 .../slashing/{messages.md => 03_messages.md}  |  4 +-
 .../{begin-block.md => 04_begin_block.md}     |  0
 docs/spec/slashing/{hooks.md => 05_hooks.md}  |  0
 docs/spec/slashing/{tags.md => 06_tags.md}    |  0
 .../{tombstone.md => 07_tombstone.md}         |  0
 docs/spec/slashing/README.md                  | 29 ++++++----
 docs/spec/staking/{state.md => 01_state.md}   |  2 +-
 ...transitions.md => 02_state_transitions.md} |  0
 .../staking/{messages.md => 03_messages.md}   |  0
 .../staking/{end_block.md => 04_end_block.md} |  0
 docs/spec/staking/{hooks.md => 05_hooks.md}   |  0
 docs/spec/staking/{tags.md => 06_tags.md}     |  0
 docs/spec/staking/README.md                   | 57 +++++++++----------
 48 files changed, 210 insertions(+), 148 deletions(-)
 rename docs/spec/auth/{gas_fees.md => 01_concepts.md} (98%)
 rename docs/spec/auth/{state.md => 02_state.md} (95%)
 rename docs/spec/auth/{handlers.md => 03_messages.md} (95%)
 rename docs/spec/auth/{types.md => 03_types.md} (96%)
 rename docs/spec/auth/{keepers.md => 04_keepers.md} (97%)
 rename docs/spec/auth/{vesting.md => 05_vesting.md} (100%)
 rename docs/spec/bank/{state.md => 01_state.md} (97%)
 rename docs/spec/bank/{keepers.md => 02_keepers.md} (97%)
 rename docs/spec/bank/{messages.md => 03_messages.md} (94%)
 rename docs/spec/bank/{tags.md => 04_tags.md} (100%)
 rename docs/spec/distribution/{f1_reference_counting.md => 01_concepts.md} (99%)
 rename docs/spec/distribution/{state.md => 02_state.md} (100%)
 rename docs/spec/distribution/{end_block.md => 03_end_block.md} (100%)
 rename docs/spec/distribution/{messages.md => 04_messages.md} (100%)
 rename docs/spec/distribution/{hooks.md => 05_hooks.md} (100%)
 rename docs/spec/distribution/{tags.md => 06_tags.md} (100%)
 rename docs/spec/governance/{overview.md => 01_concepts.md} (99%)
 rename docs/spec/governance/{state.md => 02_state.md} (97%)
 rename docs/spec/governance/{messages.md => 03_messages.md} (98%)
 rename docs/spec/governance/{tags.md => 04_tags.md} (100%)
 rename docs/spec/governance/{future_improvements.md => 05_future_improvements.md} (95%)
 rename docs/spec/mint/{state.md => 01_state.md} (96%)
 rename docs/spec/mint/{begin_block.md => 02_begin_block.md} (100%)
 rename docs/spec/params/{keeper.md => 01_keeper.md} (100%)
 rename docs/spec/params/{subspace.md => 02_subspace.md} (100%)
 rename docs/spec/slashing/{overview.md => 01_concepts.md} (95%)
 rename docs/spec/slashing/{state.md => 02_state.md} (100%)
 rename docs/spec/slashing/{messages.md => 03_messages.md} (97%)
 rename docs/spec/slashing/{begin-block.md => 04_begin_block.md} (100%)
 rename docs/spec/slashing/{hooks.md => 05_hooks.md} (100%)
 rename docs/spec/slashing/{tags.md => 06_tags.md} (100%)
 rename docs/spec/slashing/{tombstone.md => 07_tombstone.md} (100%)
 rename docs/spec/staking/{state.md => 01_state.md} (99%)
 rename docs/spec/staking/{state_transitions.md => 02_state_transitions.md} (100%)
 rename docs/spec/staking/{messages.md => 03_messages.md} (100%)
 rename docs/spec/staking/{end_block.md => 04_end_block.md} (100%)
 rename docs/spec/staking/{hooks.md => 05_hooks.md} (100%)
 rename docs/spec/staking/{tags.md => 06_tags.md} (100%)

diff --git a/PENDING.md b/PENDING.md
index bfe66c6e338..003685c6fea 100644
--- a/PENDING.md
+++ b/PENDING.md
@@ -45,6 +45,7 @@
 
 ### SDK
 
+* [\#3300] Update the spec-spec, spec file reorg, and TOC updates.
 * [\#3665] Overhaul sdk.Uint type in preparation for Coins's Int -> Uint migration.
 
 ### Tendermint
diff --git a/docs/spec/SPEC-SPEC.md b/docs/spec/SPEC-SPEC.md
index 5b65833c796..7cb3ec01679 100644
--- a/docs/spec/SPEC-SPEC.md
+++ b/docs/spec/SPEC-SPEC.md
@@ -7,20 +7,35 @@ this directory.
 
 For consistency, specs should be written in passive present tense.
 
+## Pseudo-Code
+
+Generally, pseudo-code should be minimized throughout the spec. Often, simple
+bulleted-lists which describe a function's operations are sufficient and should
+be considered preferable. In certain instances, due to the complex nature of
+the functionality being described pseudo-code may the most suitable form of
+specification. In these cases use of pseudo-code is permissible, but should be
+presented in a concise manner, ideally restricted to only the complex
+element as a part of a larger description. 
+
 ## Common Layout
 
-The following generalized structure should be used to breakdown specifications
-for modules. Note that not all files may be required depending on the modules 
-function
-
- - `overview.md` - describe module
- - `state.md` - specify and describe structures expected to marshalled into the store, and their keys
- - `state_transitions.md` - standard state transition operations triggered by hooks, messages, etc. 
- - `end_block.md` - specify any end-block operations
- - `begin_block.md` - specify any begin-block operations
- - `messages.md` - specify message structure and expected state machine behaviour 
- - `hooks.md` - describe available hooks to be called by/from this module 
- - `tags.md` - list and describe event tags used
+The following generalized file structure should be used to breakdown
+specifications for modules. With the exception of README.md, `XX` at the
+beginning of the file name should be replaced with a number to indicate
+document flow (ex. read `01_state.md` before `02_state_transitions.md`). The
+following list is nonbinding and all files are optional. 
+
+ - `README.md` - overview of the module
+ - `XX_concepts.md` - describe specialized concepts and definitions used throughout the spec
+ - `XX_state.md` - specify and describe structures expected to marshalled into the store, and their keys
+ - `XX_state_transitions.md` - standard state transition operations triggered by hooks, messages, etc. 
+ - `XX_messages.md` - specify message structure(s) and expected state machine behaviour(s)
+ - `XX_begin_block.md` - specify any begin-block operations
+ - `XX_end_block.md` - specify any end-block operations
+ - `XX_hooks.md` - describe available hooks to be called by/from this module 
+ - `XX_tags.md` - list and describe event tags used
+ - `XX_future_improvements.md` - describe future improvements of this module
+ - `XX_appendix.md` - supplementary details referenced elsewhere within the spec
 
 ### Notation for key-value mapping
 
diff --git a/docs/spec/auth/gas_fees.md b/docs/spec/auth/01_concepts.md
similarity index 98%
rename from docs/spec/auth/gas_fees.md
rename to docs/spec/auth/01_concepts.md
index 309f590ced8..388c5a8ac81 100644
--- a/docs/spec/auth/gas_fees.md
+++ b/docs/spec/auth/01_concepts.md
@@ -1,4 +1,6 @@
-# Gas & Fees
+# Concepts
+
+## Gas & Fees
 
 Fees serve two purposes for an operator of the network.
 
diff --git a/docs/spec/auth/state.md b/docs/spec/auth/02_state.md
similarity index 95%
rename from docs/spec/auth/state.md
rename to docs/spec/auth/02_state.md
index 29b5a93abdb..ad061d9a95b 100644
--- a/docs/spec/auth/state.md
+++ b/docs/spec/auth/02_state.md
@@ -1,6 +1,6 @@
-## State
+# State
 
-### Accounts
+## Accounts
 
 Accounts contain authentication information for a uniquely identified external user of an SDK blockchain,
 including public key, address, and account number / sequence number for replay protection. For efficiency,
@@ -13,7 +13,7 @@ account types may do so.
 
 - `0x01 | Address -> amino(account)`
 
-#### Account Interface
+### Account Interface
 
 The account interface exposes methods to read and write standard account information.
 Note that all of these methods operate on an account struct confirming to the interface
@@ -53,6 +53,6 @@ type BaseAccount struct {
 }
 ```
 
-#### Vesting Account
+### Vesting Account
 
 See [Vesting](vesting.md).
diff --git a/docs/spec/auth/handlers.md b/docs/spec/auth/03_messages.md
similarity index 95%
rename from docs/spec/auth/handlers.md
rename to docs/spec/auth/03_messages.md
index 2f8909c6306..9180f2da40a 100644
--- a/docs/spec/auth/handlers.md
+++ b/docs/spec/auth/03_messages.md
@@ -1,3 +1,7 @@
+# Messages
+
+TODO make this file conform to typical messages spec
+
 ## Handlers
 
 The auth module presently has no transaction handlers of its own, but does expose
diff --git a/docs/spec/auth/types.md b/docs/spec/auth/03_types.md
similarity index 96%
rename from docs/spec/auth/types.md
rename to docs/spec/auth/03_types.md
index 30c5ac8b1b8..4d37c55c8e6 100644
--- a/docs/spec/auth/types.md
+++ b/docs/spec/auth/03_types.md
@@ -1,4 +1,4 @@
-## Types
+# Types
 
 Besides accounts (specified in [State](state.md)), the types exposed by the auth module
 are `StdFee`, the combination of an amount and gas limit, `StdSignature`, the combination
@@ -6,7 +6,7 @@ of an optional public key and a cryptographic signature as a byte array, `StdTx`
 a struct which implements the `sdk.Tx` interface using `StdFee` and `StdSignature`, and
 `StdSignDoc`, a replay-prevention structure for `StdTx` which transaction senders must sign over.
 
-### StdFee
+## StdFee
 
 A `StdFee` is simply the combination of a fee amount, in any number of denominations,
 and a gas limit (where dividing the amount by the gas limit gives a "gas price").
@@ -18,7 +18,7 @@ type StdFee struct {
 }
 ```
 
-### StdSignature
+## StdSignature
 
 A `StdSignature` is the combination of an optional public key and a cryptographic signature
 as a byte array. The SDK is agnostic to particular key or signature formats and supports any
@@ -31,7 +31,7 @@ type StdSignature struct {
 }
 ```
 
-### StdTx
+## StdTx
 
 A `StdTx` is a struct which implements the `sdk.Tx` interface, and is likely to be generic
 enough to serve the purposes of many Cosmos SDK blockchains.
@@ -45,7 +45,7 @@ type StdTx struct {
 }
 ```
 
-### StdSignDoc
+## StdSignDoc
 
 A `StdSignDoc` is a replay-prevention structure to be signed over, which ensures that
 any submitted transaction (which is simply a signature over a particular bytestring)
diff --git a/docs/spec/auth/keepers.md b/docs/spec/auth/04_keepers.md
similarity index 97%
rename from docs/spec/auth/keepers.md
rename to docs/spec/auth/04_keepers.md
index 27611decd47..61af1efa1f5 100644
--- a/docs/spec/auth/keepers.md
+++ b/docs/spec/auth/04_keepers.md
@@ -1,8 +1,8 @@
-## Keepers
+# Keepers
 
 The auth module only exposes one keeper, the account keeper, which can be used to read and write accounts.
 
-### Account Keeper
+## Account Keeper
 
 Presently only one fully-permissioned account keeper is exposed, which has the ability to both read and write
 all fields of all accounts, and to iterate over all stored accounts.
diff --git a/docs/spec/auth/vesting.md b/docs/spec/auth/05_vesting.md
similarity index 100%
rename from docs/spec/auth/vesting.md
rename to docs/spec/auth/05_vesting.md
diff --git a/docs/spec/auth/README.md b/docs/spec/auth/README.md
index be6647a801e..92ff7f4de91 100644
--- a/docs/spec/auth/README.md
+++ b/docs/spec/auth/README.md
@@ -13,18 +13,24 @@ This module will be used in the Cosmos Hub.
 
 ## Contents
 
-1. **[State](state.md)**
-    1. [Accounts](state.md#accounts)
-        1. [Account Interface](state.md#account-interface)
-        2. [Base Account](state.md#baseaccount)
-        3. [Vesting Account](state.md#vestingaccount)
-1. **[Types](types.md)**
-    1. [StdFee](types.md#stdfee)
-    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)**
+1. **[Concepts](01_concepts.md)**
+    - [Gas & Fees](01_concepts.md#gas-&-fees)
+2. **[State](02_state.md)**
+    - [Accounts](02_state.md#accounts)
+3. **[Messages](03_messages.md)**
+    - [Handlers](03_messages.md#handlers)
+4. **[Types](03_types.md)**
+    - [StdFee](03_types.md#stdfee)
+    - [StdSignature](03_types.md#stdsignature)
+    - [StdTx](03_types.md#stdtx)
+    - [StdSignDoc](03_types.md#stdsigndoc)
+5. **[Keepers](04_keepers.md)**
+    - [Account Keeper](04_keepers.md#account-keeper)
+6. **[Vesting](05_vesting.md)**
+    - [Intro and Requirements](05_vesting.md#intro-and-requirements)
+    - [Vesting Account Types](05_vesting.md#vesting-account-types)
+    - [Vesting Account Specification](05_vesting.md#vesting-account-specification)
+    - [Keepers & Handlers](05_vesting.md#keepers-&-handlers)
+    - [Genesis Initialization](05_vesting.md#genesis-initialization)
+    - [Examples](05_vesting.md#examples)
+    - [Glossary](05_vesting.md#glossary)
diff --git a/docs/spec/bank/state.md b/docs/spec/bank/01_state.md
similarity index 97%
rename from docs/spec/bank/state.md
rename to docs/spec/bank/01_state.md
index aa6585bbffb..b3421b607b3 100644
--- a/docs/spec/bank/state.md
+++ b/docs/spec/bank/01_state.md
@@ -1,4 +1,4 @@
-## State
+# State
 
 Presently, the bank module has no inherent state — it simply reads and writes accounts using the `AccountKeeper` from the `auth` module.
 
diff --git a/docs/spec/bank/keepers.md b/docs/spec/bank/02_keepers.md
similarity index 97%
rename from docs/spec/bank/keepers.md
rename to docs/spec/bank/02_keepers.md
index 3c6eab7725d..ed277bd2311 100644
--- a/docs/spec/bank/keepers.md
+++ b/docs/spec/bank/02_keepers.md
@@ -1,12 +1,12 @@
-## Keepers
+# Keepers
 
 The bank module provides three different exported keeper interfaces which can be passed to other modules which need to read or update account balances. Modules should use the least-permissive interface which provides the functionality they require.
 
 Note that you should always review the `bank` module code to ensure that permissions are limited in the way that you expect.
 
-### Common Types
+## Common Types
 
-#### Input
+### Input
 
 An input of a multiparty transfer
 
@@ -17,7 +17,7 @@ type Input struct {
 }
 ```
 
-#### Output
+### Output
 
 An output of a multiparty transfer.
 
@@ -28,7 +28,7 @@ type Output struct {
 }
 ```
 
-### BaseKeeper
+## BaseKeeper
 
 The base keeper provides full-permission access: the ability to arbitrary modify any account's balance and mint or burn coins.
 
@@ -82,7 +82,7 @@ inputOutputCoins(inputs []Input, outputs []Output)
     addCoins(output.Address, output.Coins)
 ```
 
-### SendKeeper
+## SendKeeper
 
 The send keeper provides access to account balances and the ability to transfer coins between accounts, but not to alter the total supply (mint or burn coins).
 
@@ -100,7 +100,7 @@ sendCoins(from AccAddress, to AccAddress, amt Coins)
   addCoins(to, amt)
 ```
 
-### ViewKeeper
+## ViewKeeper
 
 The view keeper provides read-only access to account balances but no balance alteration functionality. All balance lookups are `O(1)`.
 
diff --git a/docs/spec/bank/messages.md b/docs/spec/bank/03_messages.md
similarity index 94%
rename from docs/spec/bank/messages.md
rename to docs/spec/bank/03_messages.md
index fd9331763e2..f249d2cbd95 100644
--- a/docs/spec/bank/messages.md
+++ b/docs/spec/bank/03_messages.md
@@ -1,6 +1,6 @@
-## Messages
+# Messages
 
-### MsgSend
+## MsgSend
 
 ```golang
 type MsgSend struct {
diff --git a/docs/spec/bank/tags.md b/docs/spec/bank/04_tags.md
similarity index 100%
rename from docs/spec/bank/tags.md
rename to docs/spec/bank/04_tags.md
diff --git a/docs/spec/bank/README.md b/docs/spec/bank/README.md
index bee48c02946..ba4beb856be 100644
--- a/docs/spec/bank/README.md
+++ b/docs/spec/bank/README.md
@@ -14,13 +14,13 @@ This module will be used in the Cosmos Hub.
 
 ## Contents
 
-1. **[State](state.md)**
-1. **[Keepers](keepers.md)**
-    1. [Common Types](keepers.md#common-types)
-        1. [Input](keepers.md#input)
-        1. [Output](keepers.md#output)
-    1. [BaseKeeper](keepers.md#basekeeper)
-    1. [SendKeeper](keepers.md#sendkeeper)
-    1. [ViewKeeper](keepers.md#viewkeeper) 
-1. **[Transactions](transactions.md)**
-    1. [MsgSend](transactions.md#msgsend)
+1. **[State](01_state.md)**
+2. **[Keepers](02_keepers.md)**
+    - [Common Types](02_keepers.md#common-types)
+    - [BaseKeeper](02_keepers.md#basekeeper)
+    - [SendKeeper](02_keepers.md#sendkeeper)
+    - [ViewKeeper](02_keepers.md#viewkeeper)
+3. **[Messages](03_messages.md)**
+    - [MsgSend](03_messages.md#msgsend)
+4. **[Tags](04_tags.md)**
+    - [Handlers](04_tags.md#handlers)
diff --git a/docs/spec/distribution/f1_reference_counting.md b/docs/spec/distribution/01_concepts.md
similarity index 99%
rename from docs/spec/distribution/f1_reference_counting.md
rename to docs/spec/distribution/01_concepts.md
index 2563be872f7..38485dcdaf7 100644
--- a/docs/spec/distribution/f1_reference_counting.md
+++ b/docs/spec/distribution/01_concepts.md
@@ -1,3 +1,5 @@
+# Concepts
+
 ## Reference Counting in F1 Fee Distribution
 
 In F1 fee distribution, in order to calculate the rewards a delegator ought to receive when they
diff --git a/docs/spec/distribution/state.md b/docs/spec/distribution/02_state.md
similarity index 100%
rename from docs/spec/distribution/state.md
rename to docs/spec/distribution/02_state.md
diff --git a/docs/spec/distribution/end_block.md b/docs/spec/distribution/03_end_block.md
similarity index 100%
rename from docs/spec/distribution/end_block.md
rename to docs/spec/distribution/03_end_block.md
diff --git a/docs/spec/distribution/messages.md b/docs/spec/distribution/04_messages.md
similarity index 100%
rename from docs/spec/distribution/messages.md
rename to docs/spec/distribution/04_messages.md
diff --git a/docs/spec/distribution/hooks.md b/docs/spec/distribution/05_hooks.md
similarity index 100%
rename from docs/spec/distribution/hooks.md
rename to docs/spec/distribution/05_hooks.md
diff --git a/docs/spec/distribution/tags.md b/docs/spec/distribution/06_tags.md
similarity index 100%
rename from docs/spec/distribution/tags.md
rename to docs/spec/distribution/06_tags.md
diff --git a/docs/spec/distribution/README.md b/docs/spec/distribution/README.md
index 8cbe9355a8d..8221974ea48 100644
--- a/docs/spec/distribution/README.md
+++ b/docs/spec/distribution/README.md
@@ -74,3 +74,22 @@ In conclusion, we can only have Atom commission and unbonded atoms
 provisions or bonded atom provisions with no Atom commission, and we elect to
 implement the former. Stakeholders wishing to rebond their provisions may elect
 to set up a script to periodically withdraw and rebond rewards.
+
+## Contents
+
+1. **[Concepts](01_concepts.md)**
+    - [Reference Counting in F1 Fee Distribution](01_concepts.md#reference-counting-in-f1-fee-distribution)
+2. **[02_state.md](02_state.md)**
+    - [State](02_state.md#state)
+3. **[End Block](03_end_block.md)**
+4. **[Messages](04_messages.md)**
+    - [MsgWithdrawDelegationRewardsAll](04_messages.md#msgwithdrawdelegationrewardsall)
+    - [MsgWithdrawDelegationReward](04_messages.md#msgwithdrawdelegationreward)
+    - [MsgWithdrawValidatorRewardsAll](04_messages.md#msgwithdrawvalidatorrewardsall)
+    - [Common calculations ](04_messages.md#common-calculations-)
+5. **[Hooks](05_hooks.md)**
+    - [Create or modify delegation distribution](05_hooks.md#create-or-modify-delegation-distribution)
+    - [Commission rate change](05_hooks.md#commission-rate-change)
+    - [Change in Validator State](05_hooks.md#change-in-validator-state)
+6. **[Tags](06_tags.md)**
+    - [Handlers](06_tags.md#handlers)
diff --git a/docs/spec/governance/overview.md b/docs/spec/governance/01_concepts.md
similarity index 99%
rename from docs/spec/governance/overview.md
rename to docs/spec/governance/01_concepts.md
index e2efe5544a4..9dce6355053 100644
--- a/docs/spec/governance/overview.md
+++ b/docs/spec/governance/01_concepts.md
@@ -1,4 +1,4 @@
-# Design Overview
+# Concepts
 
 *Disclaimer: This is work in progress. Mechanisms are susceptible to change.*
 
@@ -185,4 +185,4 @@ Once a block contains more than 2/3rd *precommits* where a common
 nodes, non-validating full nodes and light-nodes) are expected to switch to the
 new version of the software. 
 
-*Note: Not clear how the flip is handled programatically*
\ No newline at end of file
+*Note: Not clear how the flip is handled programatically*
diff --git a/docs/spec/governance/state.md b/docs/spec/governance/02_state.md
similarity index 97%
rename from docs/spec/governance/state.md
rename to docs/spec/governance/02_state.md
index f28a309a448..75af3cf22cc 100644
--- a/docs/spec/governance/state.md
+++ b/docs/spec/governance/02_state.md
@@ -1,8 +1,6 @@
-# Implementation (1/2)
+# State
 
-## State
-
-### Parameters and base types
+## Parameters and base types
 
 `Parameters` define the rules according to which votes are run. There can only
 be one active parameter set at any given time. If governance wants to change a
@@ -65,7 +63,7 @@ const (
 )
 ```
 
-### Deposit
+## Deposit
 
 ```go
   type Deposit struct {
@@ -74,7 +72,7 @@ const (
   }
 ```
 
-### ValidatorGovInfo
+## ValidatorGovInfo
 
 This type is used in a temp map when tallying
 
@@ -85,7 +83,7 @@ This type is used in a temp map when tallying
   }
 ```
 
-### Proposals
+## Proposals
 
 `Proposals` are an item to be voted on.
 
@@ -117,7 +115,7 @@ We also mention a method to update the tally for a given proposal:
   func (proposal Proposal) updateTally(vote byte, amount sdk.Dec)
 ```
 
-### Stores
+## Stores
 
 *Stores are KVStores in the multistore. The key to find the store is the first parameter in the list*`
 
@@ -132,7 +130,7 @@ For pseudocode purposes, here are the two function we will use to read or write
 * `load(StoreKey, Key)`: Retrieve item stored at key `Key` in store found at key `StoreKey` in the multistore
 * `store(StoreKey, Key, value)`: Write value `Value` at key `Key` in store found at key `StoreKey` in the multistore
 
-### Proposal Processing Queue
+## Proposal Processing Queue
 
 **Store:**
 * `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the
diff --git a/docs/spec/governance/messages.md b/docs/spec/governance/03_messages.md
similarity index 98%
rename from docs/spec/governance/messages.md
rename to docs/spec/governance/03_messages.md
index 17004e4b87d..aaca50330da 100644
--- a/docs/spec/governance/messages.md
+++ b/docs/spec/governance/03_messages.md
@@ -1,8 +1,6 @@
-# Implementation (2/2)
+# Messages
 
-## Messages
-
-### Proposal Submission
+## Proposal Submission
 
 Proposals can be submitted by any Atom holder via a `TxGovSubmitProposal`
 transaction.
@@ -69,7 +67,7 @@ upon receiving txGovSubmitProposal from sender do
   return proposalID
 ```
 
-### Deposit
+## Deposit
 
 Once a proposal is submitted, if
 `Proposal.TotalDeposit < ActiveParam.MinDeposit`, Atom holders can send
@@ -138,7 +136,7 @@ upon receiving txGovDeposit from sender do
   store(Proposals, <txGovVote.ProposalID|'proposal'>, proposal)
 ```
 
-### Vote
+## Vote
 
 Once `ActiveParam.MinDeposit` is reached, voting period starts. From there,
 bonded Atom holders are able to send `TxGovVote` transactions to cast their
diff --git a/docs/spec/governance/tags.md b/docs/spec/governance/04_tags.md
similarity index 100%
rename from docs/spec/governance/tags.md
rename to docs/spec/governance/04_tags.md
diff --git a/docs/spec/governance/future_improvements.md b/docs/spec/governance/05_future_improvements.md
similarity index 95%
rename from docs/spec/governance/future_improvements.md
rename to docs/spec/governance/05_future_improvements.md
index 9e0b0f4dfbb..1cd6c9466c0 100644
--- a/docs/spec/governance/future_improvements.md
+++ b/docs/spec/governance/05_future_improvements.md
@@ -1,4 +1,4 @@
-# Future improvements (not in scope for MVP)
+# Future Improvements
 
 The current documentation only describes the minimum viable product for the 
 governance module. Future improvements may include:
@@ -27,4 +27,4 @@ governance module. Future improvements may include:
   process.
 * **Better process for proposal review:** There would be two parts to 
   `proposal.Deposit`, one for anti-spam (same as in MVP) and an other one to 
-  reward third party auditors.
\ No newline at end of file
+  reward third party auditors.
diff --git a/docs/spec/governance/README.md b/docs/spec/governance/README.md
index 6cc1edb5084..d4d77a16c7f 100644
--- a/docs/spec/governance/README.md
+++ b/docs/spec/governance/README.md
@@ -21,15 +21,22 @@ This module will be used in the Cosmos Hub, the first Hub in the Cosmos network.
 
 The following specification uses *Atom* as the native staking token. The module can be adapted to any Proof-Of-Stake blockchain by replacing *Atom* with the native staking token of the chain.
 
-1.  **[Design overview](overview.md)**
-2.  **Implementation**
-    1. **[State](state.md)**
-        1.  Parameters
-        2.  Proposals
-        3.  Proposal Processing Queue
-    2. **[Transactions](transactions.md)**
-        1.  Proposal Submission
-        2.  Deposit
-        3.  Claim Deposit
-        4.  Vote
-3.  **[Future improvements](future_improvements.md)**
+1. **[Concepts](01_concepts.md)**
+    - [Proposal submission](01_concepts.md#proposal-submission)
+    - [Vote](01_concepts.md#vote)
+    - [Software Upgrade](01_concepts.md#software-upgrade)
+2. **[State](02_state.md)**
+    - [Parameters and base types](02_state.md#parameters-and-base-types)
+    - [Deposit](02_state.md#deposit)
+    - [ValidatorGovInfo](02_state.md#validatorgovinfo)
+    - [Proposals](02_state.md#proposals)
+    - [Stores](02_state.md#stores)
+    - [Proposal Processing Queue](02_state.md#proposal-processing-queue)
+3. **[Messages](03_messages.md)**
+    - [Proposal Submission](03_messages.md#proposal-submission)
+    - [Deposit](03_messages.md#deposit)
+    - [Vote](03_messages.md#vote)
+4. **[Tags](04_tags.md)**
+    - [EndBlocker](04_tags.md#endblocker)
+    - [Handlers](04_tags.md#handlers)
+5. **[Future Improvements](05_future_improvements.md)**
diff --git a/docs/spec/mint/state.md b/docs/spec/mint/01_state.md
similarity index 96%
rename from docs/spec/mint/state.md
rename to docs/spec/mint/01_state.md
index 42a8df5182e..bb528dcf74d 100644
--- a/docs/spec/mint/state.md
+++ b/docs/spec/mint/01_state.md
@@ -1,6 +1,6 @@
-## State
+# State
 
-### Minter
+## Minter
 
 The minter is a space for holding current inflation information.
 
@@ -13,7 +13,7 @@ type Minter struct {
 }
 ```
 
-### Params
+## Params
 
 Minting params are held in the global params store. 
 
diff --git a/docs/spec/mint/begin_block.md b/docs/spec/mint/02_begin_block.md
similarity index 100%
rename from docs/spec/mint/begin_block.md
rename to docs/spec/mint/02_begin_block.md
diff --git a/docs/spec/mint/README.md b/docs/spec/mint/README.md
index 085986b3745..096a44a9911 100644
--- a/docs/spec/mint/README.md
+++ b/docs/spec/mint/README.md
@@ -1,4 +1,11 @@
 # Mint Specification
 
-- [State](./state.md)
-- [Begin Block](./begin_block.md)
\ No newline at end of file
+## Contents
+
+1. **[State](01_state.md)**
+    - [Minter](01_state.md#minter)
+    - [Params](01_state.md#params)
+2. **[Begin-Block](02_begin_block.md)**
+    - [NextInflationRate](02_begin_block.md#nextinflationrate)
+    - [NextAnnualProvisions](02_begin_block.md#nextannualprovisions)
+    - [BlockProvision](02_begin_block.md#blockprovision)
diff --git a/docs/spec/params/keeper.md b/docs/spec/params/01_keeper.md
similarity index 100%
rename from docs/spec/params/keeper.md
rename to docs/spec/params/01_keeper.md
diff --git a/docs/spec/params/subspace.md b/docs/spec/params/02_subspace.md
similarity index 100%
rename from docs/spec/params/subspace.md
rename to docs/spec/params/02_subspace.md
diff --git a/docs/spec/params/README.md b/docs/spec/params/README.md
index d9c8b9221fb..a7728e8680e 100644
--- a/docs/spec/params/README.md
+++ b/docs/spec/params/README.md
@@ -16,5 +16,8 @@ The following contents explains how to use params module for master and user mod
 
 ## Contents
 
-1. [Keeper](keeper.md)
-1. [Subspace](subspace.md)
+1. **[Keeper](01_keeper.md)**
+2. **[Subspace](02_subspace.md)**
+    - [Key](02_subspace.md#key)
+    - [KeyTable](02_subspace.md#keytable)
+    - [ParamSet](02_subspace.md#paramset)
diff --git a/docs/spec/slashing/overview.md b/docs/spec/slashing/01_concepts.md
similarity index 95%
rename from docs/spec/slashing/overview.md
rename to docs/spec/slashing/01_concepts.md
index 63f0e494f85..006c4ed9b72 100644
--- a/docs/spec/slashing/overview.md
+++ b/docs/spec/slashing/01_concepts.md
@@ -1,12 +1,12 @@
-## Conceptual overview
+# Concepts
 
-### States
+## States
 
 At any given time, there are any number of validators registered in the state machine.
 Each block, the top `n = MaximumBondedValidators` validators who are not jailed become *bonded*, meaning that they may propose and vote on blocks.
 Validators who are *bonded* are *at stake*, meaning that part or all of their stake and their delegators' stake is at risk if they commit a protocol fault.
 
-### Tombstone Caps
+## Tombstone Caps
 
 In order to mitigate the impact of initially likely categories of non-malicious protocol faults, the Cosmos Hub implements for each validator
 a *tombstone* cap, which only allows a validator to be slashed once for a double sign fault. For example, if you misconfigure your HSM and double-sign
@@ -15,7 +15,7 @@ to avoid, but tombstone caps somewhat blunt the economic impact of unintentional
 
 Liveness faults do not have caps, as they can't stack upon each other.  Liveness bugs are "detected" as soon as the infraction occurs, and the validators are immediately put in jail, so it is not possible for them to commit multiple liveness faults without unjailing in between.
 
-#### ASCII timelines
+## ASCII timelines
 
 *Code*
 
@@ -39,4 +39,4 @@ A single infraction is committed then later discovered, at which point the valid
 [----------C<sub>1</sub>--C<sub>2</sub>---C<sub>3</sub>---D<sub>1</sub>,D<sub>2</sub>,D<sub>3</sub>V<sub>u</sub>-----]
 
 Multiple infractions are committed and then later discovered, at which point the validator is jailed and slashed for only one infraction.
-Because the validator is also tombstoned, they can not rejoin the validator set.
\ No newline at end of file
+Because the validator is also tombstoned, they can not rejoin the validator set.
diff --git a/docs/spec/slashing/state.md b/docs/spec/slashing/02_state.md
similarity index 100%
rename from docs/spec/slashing/state.md
rename to docs/spec/slashing/02_state.md
diff --git a/docs/spec/slashing/messages.md b/docs/spec/slashing/03_messages.md
similarity index 97%
rename from docs/spec/slashing/messages.md
rename to docs/spec/slashing/03_messages.md
index 342f3468bde..ce9c1af9498 100644
--- a/docs/spec/slashing/messages.md
+++ b/docs/spec/slashing/03_messages.md
@@ -1,8 +1,8 @@
-## Messages
+# Messages
 
 In this section we describe the processing of messages for the `slashing` module.
 
-### Unjail
+## Unjail
 
 If a validator was automatically unbonded due to downtime and wishes to come back online &
 possibly rejoin the bonded set, it must send `TxUnjail`:
diff --git a/docs/spec/slashing/begin-block.md b/docs/spec/slashing/04_begin_block.md
similarity index 100%
rename from docs/spec/slashing/begin-block.md
rename to docs/spec/slashing/04_begin_block.md
diff --git a/docs/spec/slashing/hooks.md b/docs/spec/slashing/05_hooks.md
similarity index 100%
rename from docs/spec/slashing/hooks.md
rename to docs/spec/slashing/05_hooks.md
diff --git a/docs/spec/slashing/tags.md b/docs/spec/slashing/06_tags.md
similarity index 100%
rename from docs/spec/slashing/tags.md
rename to docs/spec/slashing/06_tags.md
diff --git a/docs/spec/slashing/tombstone.md b/docs/spec/slashing/07_tombstone.md
similarity index 100%
rename from docs/spec/slashing/tombstone.md
rename to docs/spec/slashing/07_tombstone.md
diff --git a/docs/spec/slashing/README.md b/docs/spec/slashing/README.md
index 2240930f8e8..a63be0c1d18 100644
--- a/docs/spec/slashing/README.md
+++ b/docs/spec/slashing/README.md
@@ -16,15 +16,20 @@ This module will be used by the Cosmos Hub, the first hub in the Cosmos ecosyste
 
 ## Contents
 
-1. **[Overview](overview.md)**
-1. **[State](state.md)**
-    1. [SigningInfo](state.md#signing-info)
-2. **[Transactions](transactions.md)**
-    1. [Unjail](transactions.md#unjail)
-3. **[Hooks](hooks.md)**
-    1. [Validator Bonded](hooks.md#validator-bonded)
-4. **[Begin Block](begin-block.md)**
-    1. [Evidence handling](begin-block.md#evidence-handling)
-    2. [Uptime tracking](begin-block.md#uptime-tracking)
-5. **[Future Improvements](future-improvements.md)**
-    1. [State cleanup](future-improvements.md#state-cleanup)
+1. **[Concepts](01_concepts.md)**
+    - [States](01_concepts.md#states)
+    - [Tombstone Caps](01_concepts.md#tombstone-caps)
+    - [ASCII timelines](01_concepts.md#ascii-timelines)
+2. **[State](02_state.md)**
+    - [Signing Info](02_state.md#signing-info)
+3. **[Messages](03_messages.md)**
+    - [Unjail](03_messages.md#unjail)
+4. **[Begin-Block](04_begin_block.md)**
+    - [Evidence handling](04_begin_block.md#evidence-handling)
+    - [Uptime tracking](04_begin_block.md#uptime-tracking)
+5. **[05_hooks.md](05_hooks.md)**
+    - [Hooks](05_hooks.md#hooks)
+6. **[Tags](06_tags.md)**
+    - [Handlers](06_tags.md#handlers)
+7. **[Staking Tombstone](07_tombstone.md)**
+    - [Abstract](07_tombstone.md#abstract)
diff --git a/docs/spec/staking/state.md b/docs/spec/staking/01_state.md
similarity index 99%
rename from docs/spec/staking/state.md
rename to docs/spec/staking/01_state.md
index 0adcb58198b..b730de8a56e 100644
--- a/docs/spec/staking/state.md
+++ b/docs/spec/staking/01_state.md
@@ -117,7 +117,7 @@ with the `ValidatorAddr` Delegators are indexed in the store as follows:
 
 - Delegation: ` 0x31 | DelegatorAddr | ValidatorAddr -> amino(delegation)`
 
-Atom holders may delegate coins to validators; under this circumstance their
+Stake holders may delegate coins to validators; under this circumstance their
 funds are held in a `Delegation` data structure. It is owned by one
 delegator, and is associated with the shares for one validator. The sender of
 the transaction is the owner of the bond.
diff --git a/docs/spec/staking/state_transitions.md b/docs/spec/staking/02_state_transitions.md
similarity index 100%
rename from docs/spec/staking/state_transitions.md
rename to docs/spec/staking/02_state_transitions.md
diff --git a/docs/spec/staking/messages.md b/docs/spec/staking/03_messages.md
similarity index 100%
rename from docs/spec/staking/messages.md
rename to docs/spec/staking/03_messages.md
diff --git a/docs/spec/staking/end_block.md b/docs/spec/staking/04_end_block.md
similarity index 100%
rename from docs/spec/staking/end_block.md
rename to docs/spec/staking/04_end_block.md
diff --git a/docs/spec/staking/hooks.md b/docs/spec/staking/05_hooks.md
similarity index 100%
rename from docs/spec/staking/hooks.md
rename to docs/spec/staking/05_hooks.md
diff --git a/docs/spec/staking/tags.md b/docs/spec/staking/06_tags.md
similarity index 100%
rename from docs/spec/staking/tags.md
rename to docs/spec/staking/06_tags.md
diff --git a/docs/spec/staking/README.md b/docs/spec/staking/README.md
index 09f457589d9..a44d8ed3c83 100644
--- a/docs/spec/staking/README.md
+++ b/docs/spec/staking/README.md
@@ -16,34 +16,29 @@ network.
 
 ## Contents
 
-The following specification uses *Atom* as the native staking token. The module
-can be adapted to any Proof-Of-Stake blockchain by replacing *Atom* with the
-native staking token of the chain.
-
- 1. **[State](state.md)**	
-   - Pool
-   - Params
-   - Validator
-   - Delegation
-   - UnbondingDelegation
-   - Redelegation
-   - Queues
- 2. **[State Transistions](state_transitions.md)**	
-   - Validator
-   - Delegation
-   - Slashing
- 3. **[Messages](messages.md)**	
-   - MsgCreateValidator
-   - MsgEditValidator
-   - MsgDelegate
-   - MsgBeginUnbonding
-   - MsgBeginRedelegate
- 4. **[End-Block](end_block.md)**	
-   - Validator Set Changes
-   - Queues 
-   - Unbonding Validators
-   - Unbonding Delegations
-   - Redelegations
- 5. **[Hooks](hooks.md)**	
- 6. **[Tags](tags.md)**	
-
+1. **[State](01_state.md)**
+    - [Pool](01_state.md#pool)
+    - [LastTotalPower](01_state.md#lasttotalpower)
+    - [Params](01_state.md#params)
+    - [Validator](01_state.md#validator)
+    - [Delegation](01_state.md#delegation)
+    - [UnbondingDelegation](01_state.md#unbondingdelegation)
+    - [Redelegation](01_state.md#redelegation)
+    - [Queues](01_state.md#queues)
+2. **[State Transitions](02_state_transitions.md)**
+    - [Validators](02_state_transitions.md#validators)
+    - [Delegations](02_state_transitions.md#delegations)
+    - [Slashing](02_state_transitions.md#slashing)
+3. **[Messages](03_messages.md)**
+    - [MsgCreateValidator](03_messages.md#msgcreatevalidator)
+    - [MsgEditValidator](03_messages.md#msgeditvalidator)
+    - [MsgDelegate](03_messages.md#msgdelegate)
+    - [MsgBeginUnbonding](03_messages.md#msgbeginunbonding)
+    - [MsgBeginRedelegate](03_messages.md#msgbeginredelegate)
+4. **[End-Block ](04_end_block.md)**
+    - [Validator Set Changes](04_end_block.md#validator-set-changes)
+    - [Queues ](04_end_block.md#queues-)
+5. **[Hooks](05_hooks.md)**
+6. **[Tags](06_tags.md)**
+    - [EndBlocker](06_tags.md#endblocker)
+    - [Handlers](06_tags.md#handlers)