Merge PR cosmos#3683: spec-spec update, spec file reorg, TOC updates

* spec reorg

* ...

* PENDING.md

* @alexanderbez comments

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

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
 

docs/spec/auth/gas_fees.md → 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.
 

docs/spec/auth/state.md → 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).

docs/spec/auth/handlers.md → 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

docs/spec/auth/types.md → docs/spec/auth/03_types.md

@@ -1,12 +1,12 @@
-## 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
 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)

docs/spec/auth/keepers.md → 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.

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)

docs/spec/bank/state.md → 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.
 

docs/spec/bank/keepers.md → 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)`.
 

docs/spec/bank/messages.md → docs/spec/bank/03_messages.md

@@ -1,6 +1,6 @@
-## Messages
+# Messages
 
-### MsgSend
+## MsgSend
 
 ```golang
 type MsgSend struct {

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)

docs/spec/distribution/f1_reference_counting.md → 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

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)

docs/spec/governance/overview.md → 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*
+*Note: Not clear how the flip is handled programatically*

docs/spec/governance/state.md → 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