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>
This commit is contained in:
parent
7b09f95ab5
commit
0b2497049a
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue