R4R: Staking Spec Upgrade

PENDING.md

@@ -6,6 +6,7 @@ BREAKING CHANGES
   * [gaia-lite] [\#2182] Renamed and merged all redelegations endpoints into `/staking/redelegations`
   * [\#3176](https://github.com/cosmos/cosmos-sdk/issues/3176) `tx/sign` endpoint now expects `BaseReq` fields as nested object.
   * [\#2222] all endpoints renamed from `/stake` -> `/staking`
+  * [\#1268] `LooseTokens` -> `NotBondedTokens`
   * [\#3289] misc renames:
     * `Validator.UnbondingMinTime` -> `Validator.UnbondingCompletionTime` 
     * `Delegation` -> `Value` in `MsgCreateValidator` and `MsgDelegate` 
@@ -31,9 +32,10 @@ BREAKING CHANGES
   * [\#3064](https://github.com/cosmos/cosmos-sdk/issues/3064) Sanitize `sdk.Coin` denom. Coins denoms are now case insensitive, i.e. 100fooToken equals to 100FOOTOKEN.
   * [\#3195](https://github.com/cosmos/cosmos-sdk/issues/3195) Allows custom configuration for syncable strategy
   * [\#3242](https://github.com/cosmos/cosmos-sdk/issues/3242) Fix infinite gas
-  meter utilization during aborted ante handler executions.
-  * [\#2222] [x/staking] `/stake` -> `/staking` module rename
-  * \#3292 [x/distribution] Enable or disable withdraw addresses with a parameter in the param store
+    meter utilization during aborted ante handler executions.
+  * [x/distribution] \#3292 Enable or disable withdraw addresses with a parameter in the param store
+  * [staking] \#2222 `/stake` -> `/staking` module rename
+  * [staking] \#1268 `LooseTokens` -> `NotBondedTokens`
   * [staking] \#1402 Redelegation and unbonding-delegation structs changed to include multiple an array of entries 
   * [staking] \#3289 misc renames:
     * `Validator.UnbondingMinTime` -> `Validator.UnbondingCompletionTime` 
@@ -109,7 +111,8 @@ IMPROVEMENTS
     slashing, and staking modules.
   * [\#3093](https://github.com/cosmos/cosmos-sdk/issues/3093) Ante handler does no longer read all accounts in one go when processing signatures as signature
     verification may fail before last signature is checked.
-  * [x/stake] \#1402 Add for multiple simultaneous redelegations or unbonding-delegations within an unbonding period 
+  * [staking] \#1402 Add for multiple simultaneous redelegations or unbonding-delegations within an unbonding period 
+  * [staking] \#1268 staking spec rewrite
 
 * Tendermint
 

client/lcd/lcd_test.go

@@ -347,12 +347,12 @@ func TestPoolParamsQuery(t *testing.T) {
 	pool := getStakingPool(t, port)
 
 	initialPool := staking.InitialPool()
-	initialPool.LooseTokens = initialPool.LooseTokens.Add(sdk.NewInt(100))
-	initialPool.BondedTokens = initialPool.BondedTokens.Add(sdk.NewInt(100)) // Delegate tx on GaiaAppGenState
-	initialPool.LooseTokens = initialPool.LooseTokens.Add(sdk.NewInt(50))    // freeFermionsAcc = 50 on GaiaAppGenState
+	initialPool.NotBondedTokens = initialPool.NotBondedTokens.Add(sdk.NewInt(100))
+	initialPool.BondedTokens = initialPool.BondedTokens.Add(sdk.NewInt(100))      // Delegate tx on GaiaAppGenState
+	initialPool.NotBondedTokens = initialPool.NotBondedTokens.Add(sdk.NewInt(50)) // freeFermionsAcc = 50 on GaiaAppGenState
 
 	require.Equal(t, initialPool.BondedTokens, pool.BondedTokens)
-	require.Equal(t, initialPool.LooseTokens, pool.LooseTokens)
+	require.Equal(t, initialPool.NotBondedTokens, pool.NotBondedTokens)
 }
 
 func TestValidatorsQuery(t *testing.T) {

client/lcd/test_helpers.go

@@ -291,7 +291,7 @@ func InitializeTestLCD(
 		accAuth.Coins = sdk.Coins{sdk.NewInt64Coin(stakingTypes.DefaultBondDenom, 100)}
 		acc := gapp.NewGenesisAccount(&accAuth)
 		genesisState.Accounts = append(genesisState.Accounts, acc)
-		genesisState.StakingData.Pool.LooseTokens = genesisState.StakingData.Pool.LooseTokens.Add(sdk.NewInt(100))
+		genesisState.StakingData.Pool.NotBondedTokens = genesisState.StakingData.Pool.NotBondedTokens.Add(sdk.NewInt(100))
 	}
 
 	appState, err := codec.MarshalJSONIndent(cdc, genesisState)

cmd/gaia/app/genesis.go

@@ -154,7 +154,7 @@ func GaiaAppGenState(cdc *codec.Codec, genDoc tmtypes.GenesisDoc, appGenTxs []js
 	for _, acc := range genesisState.Accounts {
 		for _, coin := range acc.Coins {
 			if coin.Denom == bondDenom {
-				stakingData.Pool.LooseTokens = stakingData.Pool.LooseTokens.
+				stakingData.Pool.NotBondedTokens = stakingData.Pool.NotBondedTokens.
 					Add(coin.Amount) // increase the supply
 			}
 		}

cmd/gaia/app/genesis_test.go

@@ -44,7 +44,7 @@ func makeGenesisState(t *testing.T, genTxs []auth.StdTx) GenesisState {
 		acc := auth.NewBaseAccountWithAddress(sdk.AccAddress(msg.ValidatorAddr))
 		acc.Coins = sdk.Coins{sdk.NewInt64Coin(bondDenom, 150)}
 		genAccs[i] = NewGenesisAccount(&acc)
-		stakingData.Pool.LooseTokens = stakingData.Pool.LooseTokens.Add(sdk.NewInt(150)) // increase the supply
+		stakingData.Pool.NotBondedTokens = stakingData.Pool.NotBondedTokens.Add(sdk.NewInt(150)) // increase the supply
 	}
 
 	// create the final app state

cmd/gaia/app/sim_test.go

@@ -188,7 +188,7 @@ func appStateFn(r *rand.Rand, accs []simulation.Account, genesisTimestamp time.T
 		delegations = append(delegations, delegation)
 	}
 
-	stakingGenesis.Pool.LooseTokens = sdk.NewInt((amount * numAccs) + (numInitiallyBonded * amount))
+	stakingGenesis.Pool.NotBondedTokens = sdk.NewInt((amount * numAccs) + (numInitiallyBonded * amount))
 	stakingGenesis.Validators = validators
 	stakingGenesis.Bonds = delegations
 

docs/gaia/gaiacli.md

@@ -499,9 +499,9 @@ gaiacli query staking pool
 
 With the `pool` command you will get the values for:
 
-- Loose and bonded tokens
+- Not-bonded and bonded tokens
 - Token supply
-- Current anual inflation and the block in which the last inflation was processed
+- Current annual inflation and the block in which the last inflation was processed
 - Last recorded bonded shares
 
 ##### Query Delegations To Validator

docs/spec/SPEC-SPEC.md

@@ -0,0 +1,45 @@
+# Specification of Specifications
+
+This file intends to outline the common structure for specifications within
+this directory. 
+
+## Tense
+
+For consistency, specs should be written in passive present tense.
+
+## 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 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
+
+### Notation for key-value mapping
+
+Within `state.md` the following notation `->` should be used to describe key to
+value mapping:
+
+```
+key -> value 
+```
+
+to represent byte concatenation the `|` may be used. In addition, encoding
+type may be specified, for example:
+
+```
+0x00 | addressBytes | address2Bytes -> amino(value_object) 
+```
+
+Additionally, index mappings may be specified by mapping to the `nil` value, for example:
+
+```
+0x01 | address2Bytes | addressBytes -> nil
+```

docs/spec/bank/transactions.md → docs/spec/bank/messages.md

@@ -1,4 +1,4 @@
-## Transactions
+## Messages
 
 ### MsgSend
 

docs/spec/distribution/transactions.md → docs/spec/distribution/messages.md

@@ -1,4 +1,4 @@
-# Transactions
+# Messages
 
 ## MsgWithdrawDelegationRewardsAll
 

docs/spec/governance/transactions.md → docs/spec/governance/messages.md

@@ -1,6 +1,6 @@
 # Implementation (2/2)
 
-## Transactions
+## Messages
 
 ### Proposal Submission
 

docs/spec/reserve-pool/TODO.md

@@ -0,0 +1,3 @@
+TODO 
+
+The reserve pool is the pool of collected funds for use by governance taken via the `CommunityTax`

docs/spec/slashing/transactions.md → docs/spec/slashing/messages.md

@@ -1,6 +1,6 @@
-## Transactions
+## Messages
 
-In this section we describe the processing of transactions for the `slashing` module.
+In this section we describe the processing of messages for the `slashing` module.
 
 ### Unjail
 

docs/spec/staking/TODO.md

@@ -0,0 +1,7 @@
+
+ - `state.md` needs updates to include 
+   - LastValidatorPower
+   - LastTotalPower
+   - state for the queues: UnbondingDelegation, UnbondingValidator, Redelegation
+ - introduce `state_transitions.md` to describe validator/delegator state
+   transitions which are called from transactions

docs/spec/staking/end_block.md

@@ -1,68 +1,62 @@
 # End-Block 
 
-## Unbonding Validator Queue
-
-For all unbonding validators that have finished their unbonding period, this switches their validator.Status
-from sdk.Unbonding to sdk.Unbonded if they still have any delegation left.  Otherwise, it deletes it from state.
-
-```golang
-validatorQueue(currTime time.Time):
-    // unbonding validators are in ordered queue from oldest to newest
-    for all unbondingValidators whose CompleteTime < currTime:
-        validator = GetValidator(unbondingValidator.ValidatorAddr)
-        if validator.DelegatorShares == 0 {
-            RemoveValidator(unbondingValidator)
-        } else {
-            validator.Status = sdk.Unbonded
-            SetValidator(unbondingValidator)
-        }
-    return
-```
+Each abci end block call, the operations to update queues and validator set
+changes are specified to execute. 
 
 ## Validator Set Changes
 
-The Tendermint validator set may be updated by state transitions that run at
-the end of every block. The Tendermint validator set may be changed by
-validators either being jailed due to inactivity/unexpected behaviour (covered
-in slashing) or changed in validator power. Determining which validator set
-changes must be made occurs during staking transactions (and slashing
-transactions) - during end-block the already accounted changes are applied and
-the changes cleared
-
-```golang
-EndBlock() ValidatorSetChanges
-    vsc = GetValidTendermintUpdates()
-    ClearTendermintUpdates()
-    return vsc
-```
-
-## CompleteUnbonding
-
-Complete the unbonding and transfer the coins to the delegate. Realize any
-slashing that occurred during the unbonding period.
-
-```golang
-unbondingQueue(currTime time.Time):
-    // unbondings are in ordered queue from oldest to newest
-    for all unbondings whose CompleteTime < currTime:
-        validator = GetValidator(unbonding.ValidatorAddr)
-        AddCoins(unbonding.DelegatorAddr, unbonding.Balance)
-        removeUnbondingDelegation(unbonding)
-    return
-```
-
-## CompleteRedelegation
-
-Note that unlike CompleteUnbonding slashing of redelegating shares does not
-take place during completion. Slashing on redelegated shares takes place
-actively as a slashing occurs. The redelegation completion queue serves simply to
-clean up state, as redelegations older than an unbonding period need not be kept,
-as that is the max time that their old validator's evidence can be used to slash them.
-
-```golang
-redelegationQueue(currTime time.Time):
-    // redelegations are in ordered queue from oldest to newest
-    for all redelegations whose CompleteTime < currTime:
-        removeRedelegation(redelegation)
-    return
-```
+The staking validator set is updated during this process by state transitions
+that run at the end of every block. As a part of this process any updated
+validators are also returned back to Tendermint for inclusion in the Tendermint
+validator set which is responsible for validating Tendermint messages at the
+consensus layer. Operations are as following:
+
+ - the new validator set is taken as the top `params.MaxValidators` number of
+   validators retrieved from the ValidatorsByPower index
+ - the previous validator set is compared with the new validator set 
+   - missing validators begin unbonding
+   - new validator are instantly bonded
+
+In all cases, any validators leaving or entering the bonded validator set or
+changing balances and staying within the bonded validator set incur an update
+message which is passed back to Tendermint.
+
+## Queues 
+
+Within staking, certain state-transitions are not instantaneous but take place
+of a duration of time (typically the unbonding period). When these transitions
+are mature certain operations must take place in order to complete the state
+operation. This is achieved through the use of queues which are
+checked/processed at the end of each block. 
+
+### Unbonding Validators
+
+When a validator is kicked out of the bonded validator set (either through
+being jailed, or not having sufficient bonded tokens) it begin the unbonding
+process - as well as all its delegations begin unbonding while still being
+delegated to this validator. At this point the validator is said to an
+unbonding validator, whereby it will mature to become an unbonded
+validator after the unbonding period has passed. 
+
+Each block the validator queue is to be checked for mature unbonding
+validators. For all unbonding validators that have finished their unbonding
+period, the validator.Status is switched from sdk.Unbonding to sdk.Unbonded.
+If at this switch they do not have any delegation left the validator object
+instead just deleted from state.
+
+### Unbonding Delegations
+
+Complete the unbonding of all mature `UnbondingDelegations.Entries` within the
+`UnbondingDelegations` queue with the following procedure: 
+ - transfer the balance coins to the delegator's wallet address
+ - remove the mature entry from `UnbondingDelegation.Entries`
+ - remove the `UnbondingDelegation` object from the store if there are no
+   remaining entries. 
+
+### Redelegations
+
+Complete the unbonding of all mature `Redelegation.Entries` within the
+`Redelegations` queue with the following procedure: 
+ - remove the mature entry from `Redelegation.Entries`
+ - remove the `Redelegation` object from the store if there are no
+   remaining entries.