docs: Revert SPEC-SPEC and update x/{auth,bank,evidence,slashing}

docs/spec/SPEC-SPEC.md

@@ -19,33 +19,28 @@ element as a part of a larger description.
 
 ## Common Layout
 
-The specifications should be contained in a single `README.md` file inside the
-`spec/` folder of a given module.
-
-The following generalized document structure should be used to breakdown
-specifications for modules. Each bullet item corresponds to a new section in
-the document, and should begin with a secondary heading (`## {HEADING}` in
-Markdown). The `XX` at the beginning of the section name should be replaced
-with a number to indicate document flow (ex. read `01. Concepts` before
-`02. State Transitions`). The following list is nonbinding and all sections are
-optional.
-
-- `XX. Abstract` - overview of the module
-- `XX. Concepts` - describe specialized concepts and definitions used throughout the spec
-- `XX. State` - specify and describe structures expected to marshalled into the store, and their keys
-- `XX. State Transitions` - standard state transition operations triggered by hooks, messages, etc.
-- `XX. Messages` - specify message structure(s) and expected state machine behaviour(s)
-- `XX. BeginBlock` - specify any begin-block operations
-- `XX. EndBlock` - specify any end-block operations
-- `XX. Hooks` - describe available hooks to be called by/from this module
-- `XX. Events` - list and describe event tags used
-- `XX. Params` - list all module parameters, their types (in JSON) and examples
-- `XX. Future Improvements` - describe future improvements of this module
-- `XX. Appendix` - supplementary details referenced elsewhere within the spec
+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_events.md` - list and describe event tags used
+- `XX_params.md` - list all module parameters, their types (in JSON) and examples
+- `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
 
-Within the `State` section, the following notation `->` should be used to describe key to
+Within `state.md` the following notation `->` should be used to describe key to
 value mapping:
 
 ```

x/auth/keeper/account.go

@@ -5,7 +5,7 @@ import (
 	"github.com/cosmos/cosmos-sdk/x/auth/types"
 )
 
-// NewAccountWithAddress implements sdk.AccountKeeper.
+// NewAccountWithAddress implements AccountKeeperI.
 func (ak AccountKeeper) NewAccountWithAddress(ctx sdk.Context, addr sdk.AccAddress) types.AccountI {
 	acc := ak.proto()
 	err := acc.SetAddress(addr)
@@ -25,7 +25,7 @@ func (ak AccountKeeper) NewAccount(ctx sdk.Context, acc types.AccountI) types.Ac
 	return acc
 }
 
-// GetAccount implements sdk.AccountKeeper.
+// GetAccount implements AccountKeeperI.
 func (ak AccountKeeper) GetAccount(ctx sdk.Context, addr sdk.AccAddress) types.AccountI {
 	store := ctx.KVStore(ak.key)
 	bz := store.Get(types.AddressStoreKey(addr))
@@ -46,7 +46,7 @@ func (ak AccountKeeper) GetAllAccounts(ctx sdk.Context) (accounts []types.Accoun
 	return accounts
 }
 
-// SetAccount implements sdk.AccountKeeper.
+// SetAccount implements AccountKeeperI.
 func (ak AccountKeeper) SetAccount(ctx sdk.Context, acc types.AccountI) {
 	addr := acc.GetAddress()
 	store := ctx.KVStore(ak.key)

x/auth/keeper/keeper.go

@@ -14,6 +14,36 @@ import (
 	paramtypes "github.com/cosmos/cosmos-sdk/x/params/types"
 )
 
+// AccountKeeperI is the interface contract that x/auth's keeper implements.
+type AccountKeeperI interface {
+	// Return a new account with the next account number and the specified address. Does not save the new account to the store.
+	NewAccountWithAddress(sdk.Context, sdk.AccAddress) types.AccountI
+
+	// Return a new account with the next account number. Does not save the new account to the store.
+	NewAccount(sdk.Context, types.AccountI) types.AccountI
+
+	// Retrieve an account from the store.
+	GetAccount(sdk.Context, sdk.AccAddress) types.AccountI
+
+	// Set an account in the store.
+	SetAccount(sdk.Context, types.AccountI)
+
+	// Remove an account from the store.
+	RemoveAccount(sdk.Context, types.AccountI)
+
+	// Iterate over all accounts, calling the provided function. Stop iteraiton when it returns false.
+	IterateAccounts(sdk.Context, func(types.AccountI) bool)
+
+	// Fetch the public key of an account at a specified address
+	GetPubKey(sdk.Context, sdk.AccAddress) (crypto.PubKey, error)
+
+	// Fetch the sequence of an account at a specified address.
+	GetSequence(sdk.Context, sdk.AccAddress) (uint64, error)
+
+	// Fetch the next account number, and increment the internal counter.
+	GetNextAccountNumber(sdk.Context) uint64
+}
+
 // AccountKeeper encodes/decodes accounts using the go-amino (binary)
 // encoding/decoding library.
 type AccountKeeper struct {
@@ -26,7 +56,9 @@ type AccountKeeper struct {
 	proto func() types.AccountI
 }
 
-// NewAccountKeeper returns a new sdk.AccountKeeper that uses go-amino to
+var _ AccountKeeperI = &AccountKeeper{}
+
+// NewAccountKeeper returns a new AccountKeeperI that uses go-amino to
 // (binary) encode and decode concrete sdk.Accounts.
 func NewAccountKeeper(
 	cdc codec.BinaryMarshaler, key sdk.StoreKey, paramstore paramtypes.Subspace, proto func() types.AccountI,

x/auth/spec/02_state.md

@@ -15,30 +15,39 @@ Accounts are exposed externally as an interface, and stored internally as
 either a base account or vesting account. Module clients wishing to add more
 account types may do so.
 
-- `0x01 | Address -> amino(account)`
+- `0x01 | Address -> ProtocolBuffer(account)`
 
 ### 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
-- in order to write the account to the store, the account keeper will need to be used.
+Note that all of these methods operate on an account struct confirming to the
+interface - in order to write the account to the store, the account keeper will
+need to be used.
 
 ```go
-type Account interface {
-  GetAddress() AccAddress
-  SetAddress(AccAddress)
+// AccountI is an interface used to store coins at a given address within state.
+// It presumes a notion of sequence numbers for replay protection,
+// a notion of account numbers for replay protection for previously pruned accounts,
+// and a pubkey for authentication purposes.
+//
+// Many complex conditions can be used in the concrete struct which implements AccountI.
+type AccountI interface {
+	proto.Message
 
-  GetPubKey() PubKey
-  SetPubKey(PubKey)
+	GetAddress() sdk.AccAddress
+	SetAddress(sdk.AccAddress) error // errors if already set.
 
-  GetAccountNumber() uint64
-  SetAccountNumber(uint64)
+	GetPubKey() crypto.PubKey // can return nil.
+	SetPubKey(crypto.PubKey) error
 
-  GetSequence() uint64
-  SetSequence(uint64)
+	GetAccountNumber() uint64
+	SetAccountNumber(uint64) error
 
-  GetCoins() Coins
-  SetCoins(Coins)
+	GetSequence() uint64
+	SetSequence(uint64) error
+
+	// Ensure that account implements stringer
+	String() string
 }
 ```
 
@@ -47,13 +56,15 @@ type Account interface {
 A base account is the simplest and most common account type, which just stores all requisite
 fields directly in a struct.
 
-```go
-type BaseAccount struct {
-  Address       AccAddress
-  Coins         Coins
-  PubKey        PubKey
-  AccountNumber uint64
-  Sequence      uint64
+```protobuf
+// BaseAccount defines a base account type. It contains all the necessary fields
+// for basic account functionality. Any custom account type should extend this
+// type for additional functionality (e.g. vesting).
+message BaseAccount {
+  string address = 1;
+  google.protobuf.Any pub_key = 2;
+  uint64 account_number = 3;
+  uint64 sequence       = 4;
 }
 ```
 

x/auth/spec/04_keepers.md

@@ -12,32 +12,33 @@ Presently only one fully-permissioned account keeper is exposed, which has the a
 all fields of all accounts, and to iterate over all stored accounts.
 
 ```go
-type AccountKeeper interface {
-  // Return a new account with the next account number and the specified address. Does not save the new account to the store.
-  NewAccountWithAddress(AccAddress) Account
+// AccountKeeperI is the interface contract that x/auth's keeper implements.
+type AccountKeeperI interface {
+	// Return a new account with the next account number and the specified address. Does not save the new account to the store.
+	NewAccountWithAddress(sdk.Context, sdk.AccAddress) types.AccountI
 
-  // Return a new account with the next account number. Does not save the new account to the store.
-  NewAccount(Account) Account
+	// Return a new account with the next account number. Does not save the new account to the store.
+	NewAccount(sdk.Context, types.AccountI) types.AccountI
 
-  // Retrieve an account from the store
-  GetAccount(AccAddress) Account
+	// Retrieve an account from the store.
+	GetAccount(sdk.Context, sdk.AccAddress) types.AccountI
 
-  // Set an account in the store
-  SetAccount(Account)
+	// Set an account in the store.
+	SetAccount(sdk.Context, types.AccountI)
 
-  // Remove an account from the store
-  RemoveAccount(Account)
+	// Remove an account from the store.
+	RemoveAccount(sdk.Context, types.AccountI)
 
-  // Iterate over all accounts, calling the provided function. Stop iteraiton when it returns false.
-  IterateAccounts(func(Account) (bool))
+	// Iterate over all accounts, calling the provided function. Stop iteraiton when it returns false.
+	IterateAccounts(sdk.Context, func(types.AccountI) bool)
 
-  // Fetch the public key of an account at a specified address
-  GetPubKey(AccAddress) PubKey
+	// Fetch the public key of an account at a specified address
+	GetPubKey(sdk.Context, sdk.AccAddress) (crypto.PubKey, error)
 
-  // Fetch the sequence of an account at a specified address
-  GetSequence(AccAddress) uint64
+	// Fetch the sequence of an account at a specified address.
+	GetSequence(sdk.Context, sdk.AccAddress) (uint64, error)
 
-  // Fetch the next account number, and increment the internal counter
-  GetNextAccountNumber() uint64
+	// Fetch the next account number, and increment the internal counter.
+	GetNextAccountNumber(sdk.Context) uint64
 }
 ```

x/auth/spec/07_params.md

@@ -7,7 +7,7 @@ order: 7
 The auth module contains the following parameters:
 
 | Key                    | Type            | Example |
-|------------------------|-----------------|---------|
+| ---------------------- | --------------- | ------- |
 | MaxMemoCharacters      | string (uint64) | "256"   |
 | TxSigLimit             | string (uint64) | "7"     |
 | TxSizeCostPerByte      | string (uint64) | "10"    |

x/auth/spec/README.md

@@ -21,24 +21,19 @@ This module will be used in the Cosmos Hub.
 ## Contents
 
 1. **[Concepts](01_concepts.md)**
-    - [Gas & Fees](01_concepts.md#gas-&-fees)
+   - [Gas & Fees](01_concepts.md#gas-&-fees)
 2. **[State](02_state.md)**
-    - [Accounts](02_state.md#accounts)
+   - [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)
-7. **[Parameters](07_params.md)**
+   - [Handlers](03_messages.md#handlers)
+4. **[Keepers](04_keepers.md)**
+   - [Account Keeper](04_keepers.md#account-keeper)
+5. **[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)
+6. **[Parameters](07_params.md)**

x/bank/spec/01_state.md

@@ -0,0 +1,11 @@
+<!--
+order: 1
+-->
+
+# State
+
+The `x/bank` module keeps state of two primary objects, account balances and the
+total supply of all balances.
+
+- Balances: `[]byte("balances") | []byte(address) / []byte(balance.Denom) -> ProtocolBuffer(balance)`
+- Supply: `0x0 -> ProtocolBuffer(Supply)`