diff --git a/x/staking/spec/01_state.md b/x/staking/spec/01_state.md index 66c6c0c5d6..7238994118 100644 --- a/x/staking/spec/01_state.md +++ b/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 diff --git a/x/staking/spec/02_state_transitions.md b/x/staking/spec/02_state_transitions.md index 4a69769b95..b46f1f002a 100644 --- a/x/staking/spec/02_state_transitions.md +++ b/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 diff --git a/x/staking/spec/03_messages.md b/x/staking/spec/03_messages.md index d0f059ecf6..fb6eb06837 100644 --- a/x/staking/spec/03_messages.md +++ b/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 diff --git a/x/staking/spec/05_end_block.md b/x/staking/spec/05_end_block.md index c0777896fb..769b986b7c 100644 --- a/x/staking/spec/05_end_block.md +++ b/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