Staking spec updates (#8843)

* Overview of keepers in object capability model (OCM)

* Updates to the spec, making clarifications

* Create a sequence diagram of a (fresh) delegation

* Misc notes, not yet decided where to put them

* Description of the shares abstraction in validators

* Model all keeper dependencies and move the UML file to docs

* Move and rename delegation sequence diagram

* Move shares description

* Remove TODO

* Diagram touch-ups

* Add how consensus power is calculated

* remove temp file

* Diagram improvements

* Describe slashing in more detail

* Describe redelegation

* Describe unbonding

* Delegation updates

* Delegation updates

* Make a diagram describing overall transaction flow

* Add delegation flows for the events of tokens being bonded/unbonding/etc.

* Grammar fix

* Diagram updates: distinguish alts, remove numbering.

* Use groups instead of "func:" participants

* Remove unused keepers from dependency diagram

* Add title to unbonding diagram

* Move keeper dependencies

* small doc updates

* remove numbers on sequence diagram

* !!!WIP EndBlock

* Explain "Last"-prefix in storage

* Remove `panic` step (they are supposed to never happen)

* EndBlock sequence diagram (with TODOs)

* Add TODO

* More visible TODOs

* Remove numbering

* Complete EndBlock

* Remove numbering

* Remove TODOs and update title

* add title back

* remove endblock seq-diagram

* spec updates

* Make power index update conditional on not being jailed

* update title

* Delete sequnce diagrams

* Fix tokens to consensus power ratio

* Fix type

Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com>

Co-authored-by: hjort <>
Co-authored-by: Amaury <1293565+amaurym@users.noreply.github.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

x/staking/spec/01_state.md

@@ -7,6 +7,7 @@ order: 1
 ## LastTotalPower
 
 LastTotalPower tracks the total amounts of bonded tokens recorded during the previous end block.
+Store entries prefixed with "Last" must remain unchanged until EndBlock.
 
 - LastTotalPower: `0x12 -> ProtocolBuffer(sdk.Int)`
 
@@ -29,12 +30,12 @@ Validators can have one of three statuses
   active set during [`EndBlock`](./05_end_block.md#validator-set-changes) and their status is updated to `Bonded`.
   They are signing blocks and receiving rewards. They can receive further delegations.
   They can be slashed for misbehavior. Delegators to this validator who unbond their delegation
-  must wait the duration of the UnbondingTime, a chain-specific param. during which time
+  must wait the duration of the UnbondingTime, a chain-specific param, during which time
   they are still slashable for offences of the source validator if those offences were committed
   during the period of time that the tokens were bonded.
-- `Unbonding`: When a validator leaves the active set, either by choice or due to slashing or
+- `Unbonding`: When a validator leaves the active set, either by choice or due to slashing, jailing or
   tombstoning, an unbonding of all their delegations begins. All delegations must then wait the UnbondingTime
-  before moving their tokens to their accounts from the `BondedPool`.
+  before their tokens are moved to their accounts from the `BondedPool`.
 
 Validators objects should be primarily stored and accessed by the
 `OperatorAddr`, an SDK validator address for the operator of the validator. Two
@@ -59,10 +60,10 @@ When Tendermint reports evidence, it provides the validator address, so this
 map is needed to find the operator. Note that the `ConsAddr` corresponds to the
 address which can be derived from the validator's `ConsPubKey`.
 
-`ValidatorsByPower` is an additional index that provides a sorted list o
+`ValidatorsByPower` is an additional index that provides a sorted list of
 potential validators to quickly determine the current active set. Here
-ConsensusPower is validator.Tokens/10^6. Note that all validators where
-`Jailed` is true are not stored within this index.
+ConsensusPower is validator.Tokens/10^6 by default. Note that all validators
+where `Jailed` is true are not stored within this index.
 
 `LastValidatorsPower` is a special index that provides a historical list of the
 last-block's bonded validators. This index remains constant during a block but
@@ -151,7 +152,7 @@ A redelegation object is created every time a redelegation occurs. To prevent
 - the (re)delegator already has another immature redelegation in progress
   with a destination to a validator (let's call it `Validator X`)
 - and, the (re)delegator is attempting to create a _new_ redelegation
-  where the source validator for this new redelegation is `Validator-X`.
+  where the source validator for this new redelegation is `Validator X`.
 
 +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L200-L228
 
@@ -182,7 +183,7 @@ delegations queue is kept.
 For the purpose of tracking progress of redelegations the redelegation queue is
 kept.
 
-- UnbondingDelegation: `0x42 | format(time) -> []DVVTriplet`
+- RedelegationQueue: `0x42 | format(time) -> []DVVTriplet`
 
 +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/staking.proto#L140-L152
 

x/staking/spec/02_state_transitions.md

@@ -15,7 +15,11 @@ This document describes the state transition operations pertaining to:
 State transitions in validators are performed on every [`EndBlock`](./05_end_block.md#validator-set-changes)
 in order to check for changes in the active `ValidatorSet`.
 
-### Unbonded to Bonded
+A validator can be `Unbonded`, `Unbonding` or `Bonded`. `Unbonded`
+and `Unbonding` are collectively called `Not Bonded`. A validator can move
+directly between all the states, except for from `Bonded` to `Unbonded`.
+
+### Not bonded to Bonded
 
 The following transition occurs when a validator's ranking in the `ValidatorPowerIndex` surpasses
 that of the `LastValidator`.
@@ -55,6 +59,9 @@ this process may be also be reversed. the following operations occur:
 - if jailed delete record from `ValidatorByPowerIndex`
 - if unjailed add record to `ValidatorByPowerIndex`
 
+Jailed validators are not present in any of the following stores:
+- the power store (from consensus power to address)
+
 ## Delegations
 
 ### Delegate

x/staking/spec/03_messages.md

@@ -62,7 +62,6 @@ assigned to `Delegation.Shares`.
 This service message is expected to fail if:
 
 - the validator is does not exist
-- the validator is jailed
 - the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
 - the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares
 - the amount delegated is less than the minimum allowed delegation
@@ -75,6 +74,12 @@ The delegator receives newly minted shares at the current exchange rate.
 The exchange rate is the number of existing shares in the validator divided by
 the number of currently delegated tokens.
 
+The validator is updated in the `ValidatorByPower` index, and the delegation is
+tracked in validator object in the `Validators` index.
+
+It is possible to delegate to a jailed validator, the only difference being it
+will not be added to the power index until it is unjailed.
+
 ## Msg/Undelegate
 
 The `Msg/Undelegate` service message allows delegators to undelegate their tokens from

x/staking/spec/05_end_block.md

@@ -16,7 +16,7 @@ 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
+  validators retrieved from the `ValidatorsByPower` index
 - the previous validator set is compared with the new validator set:
   - missing validators begin unbonding and their `Tokens` are transferred from the
     `BondedPool` to the `NotBondedPool` `ModuleAccount`
@@ -25,7 +25,12 @@ consensus layer. Operations are as following:
 
 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.
+message reporting their new consensus power which is passed back to Tendermint.
+
+The `LastTotalPower` and `LastValidatorsPower` hold the state of the total power
+and validator power from the end of the last block, and are used to check for
+changes that have occured in `ValidatorsByPower` and the total new power, which
+is calculated during `EndBlock`.
 
 ## Queues
 
@@ -41,14 +46,15 @@ When a validator is kicked out of the bonded validator set (either through
 being jailed, or not having sufficient bonded tokens) it begins the unbonding
 process along with all its delegations begin unbonding (while still being
 delegated to this validator). At this point the validator is said to be an
-unbonding validator, whereby it will mature to become an "unbonded validator"
+"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
-(namely with a completion time <= current time). At this point any mature
-validators which do not have any delegations remaining are deleted from state.
-For all other mature unbonding validators that still have remaining
-delegations, the `validator.Status` is switched from `types.Unbonding` to
+(namely with a completion time <= current time and completion height <= current
+block height). At this point any mature validators which do not have any
+delegations remaining are deleted from state. For all other mature unbonding
+validators that still have remaining delegations, the `validator.Status` is
+switched from `types.Unbonding` to
 `types.Unbonded`.
 
 ### Unbonding Delegations