Merge PR #3357: Staking spec upgrades / some renaming
This commit is contained in:
frog power 4000
committed by
Christopher Goes
Christopher Goes
parent
da0426a2dd
commit
7f74b33e21
@@ -15,7 +15,7 @@ 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.
|
||||
- `state_transitions.md` - standard state transition operations triggered 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
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
|
||||
- `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
|
||||
@@ -38,11 +38,12 @@ 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"
|
||||
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.
|
||||
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 sdk.Unbonding to
|
||||
sdk.Unbonded.
|
||||
|
||||
### Unbonding Delegations
|
||||
|
||||
|
||||
@@ -27,18 +27,23 @@ native staking token of the chain.
|
||||
- Delegation
|
||||
- UnbondingDelegation
|
||||
- Redelegation
|
||||
2. **[Messages](messages.md)**
|
||||
- Queues
|
||||
2. **[State Transistions](state_transitions.md)**
|
||||
- Validator
|
||||
- Delegation
|
||||
- Slashing
|
||||
3. **[Messages](messages.md)**
|
||||
- MsgCreateValidator
|
||||
- MsgEditValidator
|
||||
- MsgDelegate
|
||||
- MsgBeginUnbonding
|
||||
- MsgBeginRedelegate
|
||||
3. **[End-Block](end_block.md)**
|
||||
4. **[End-Block](end_block.md)**
|
||||
- Validator Set Changes
|
||||
- Queues
|
||||
- Unbonding Validators
|
||||
- Unbonding Delegations
|
||||
- Redelegations
|
||||
4. **[Hooks](hooks.md)**
|
||||
5. **[Tags](tags.md)**
|
||||
5. **[Hooks](hooks.md)**
|
||||
6. **[Tags](tags.md)**
|
||||
|
||||
|
||||
@@ -17,6 +17,13 @@ type Pool struct {
|
||||
}
|
||||
```
|
||||
|
||||
## LastTotalPower
|
||||
|
||||
LastTotalPower tracks the total amounts of bonded tokens recorded during the previous
|
||||
end block.
|
||||
|
||||
- LastTotalPower: `0x12 -> amino(sdk.Int)`
|
||||
|
||||
## Params
|
||||
|
||||
Params is a module-wide configuration structure that stores system parameters
|
||||
@@ -37,27 +44,36 @@ type Params struct {
|
||||
|
||||
Validators objects should be primarily stored and accessed by the
|
||||
`OperatorAddr`, an SDK validator address for the operator of the validator. Two
|
||||
additional indexes are maintained in order to fulfill required lookups for
|
||||
slashing and validator-set updates.
|
||||
additional indices are maintained per validator object in order to fulfill
|
||||
required lookups for slashing and validator-set updates. A third special index
|
||||
(`LastValidatorPower`) is also maintained which however remains constant
|
||||
throughout each block, unlike the first two indices which mirror the validator
|
||||
records within a block.
|
||||
|
||||
- Validators: `0x21 | OperatorAddr -> amino(validator)`
|
||||
- ValidatorsByConsAddr: `0x22 | ConsAddr -> OperatorAddr`
|
||||
- ValidatorsByPower: `0x23 | BigEndian(Tokens) | OperatorAddr -> OperatorAddr`
|
||||
- LastValidatorsPower: `0x11 OperatorAddr -> amino(Tokens)
|
||||
|
||||
`Validators` is the primary index - it ensures that each operator can have only one
|
||||
associated validator, where the public key of that validator can change in the
|
||||
future. Delegators can refer to the immutable operator of the validator, without
|
||||
concern for the changing public key.
|
||||
|
||||
`ValidatorByConsAddr` is a secondary index that enables lookups for slashing.
|
||||
`ValidatorByConsAddr` is an additional index that enables lookups for slashing.
|
||||
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 a secondary index that provides a sorted list of
|
||||
`ValidatorsByPower` is an additional index that provides a sorted list o
|
||||
potential validators to quickly determine the current active set. 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
|
||||
is updated during the validator set update process which takes place in [end
|
||||
block](end_block.md).
|
||||
|
||||
Each validator's state is stored in a `Validator` struct:
|
||||
|
||||
```golang
|
||||
@@ -190,3 +206,57 @@ type RedelegationEntry struct {
|
||||
SharesDst sdk.Dec // amount of destination-validator shares created by redelegation
|
||||
}
|
||||
```
|
||||
|
||||
## Queues
|
||||
|
||||
All queues objects are sorted by timestamp. The time used within any queue is
|
||||
first rounded to the nearest nanosecond then sorted. The sortable time format
|
||||
used is a slight modification of the RFC3339Nano and uses the the format string
|
||||
`"2006-01-02T15:04:05.000000000"`. Noteably This format:
|
||||
|
||||
- right pads all zeros
|
||||
- drops the time zone info (uses UTC)
|
||||
|
||||
In all cases, the stored timestamp represents the maturation time of the queue
|
||||
element.
|
||||
|
||||
### UnbondingDelegationQueue
|
||||
|
||||
For the purpose of tracking progress of unbonding delegations the unbonding
|
||||
delegations queue is kept.
|
||||
|
||||
- UnbondingDelegation: `0x41 | format(time) -> []DVPair`
|
||||
|
||||
```
|
||||
type DVPair struct {
|
||||
DelegatorAddr sdk.AccAddress
|
||||
ValidatorAddr sdk.ValAddress
|
||||
}
|
||||
```
|
||||
|
||||
### RedelegationQueue
|
||||
|
||||
For the purpose of tracking progress of redelegations the redelegation queue is
|
||||
kept.
|
||||
|
||||
- UnbondingDelegation: `0x42 | format(time) -> []DVVTriplet`
|
||||
|
||||
```
|
||||
type DVVTriplet struct {
|
||||
DelegatorAddr sdk.AccAddress
|
||||
ValidatorSrcAddr sdk.ValAddress
|
||||
ValidatorDstAddr sdk.ValAddress
|
||||
}
|
||||
```
|
||||
|
||||
### ValidatorQueue
|
||||
|
||||
For the purpose of tracking progress of unbonding validators the validator
|
||||
queue is kept.
|
||||
|
||||
- ValidatorQueueTime: `0x43 | format(time) -> []sdk.ValAddress`
|
||||
|
||||
The stored object as each key is an array of validator operator addresses from
|
||||
which the validator object can be accessed. Typically it is expected that only
|
||||
a single validator record will be associated with a given timestamp however it is possible
|
||||
that multiple validators exist in the queue at the same location.
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
# State Transitions
|
||||
|
||||
This document describes the state transition operations pertaining to:
|
||||
|
||||
- Validators
|
||||
- Delegations
|
||||
- Slashing
|
||||
|
||||
|
||||
## Validators
|
||||
|
||||
### Non-Bonded to Bonded
|
||||
|
||||
When a validator is bonded from any other state the following operations occur:
|
||||
- set `validator.Status` to `Bonded`
|
||||
- update the `Pool` object with tokens moved from `NotBondedTokens` to `BondedTokens`
|
||||
- delete record the existing record from `ValidatorByPowerIndex`
|
||||
- add an new updated record to the `ValidatorByPowerIndex`
|
||||
- update the `Validator` object for this validator
|
||||
- if it exists, delete any `ValidatorQueue` record for this validator
|
||||
|
||||
### Bonded to Unbonding
|
||||
When a validator begins the unbonding process the following operations occur:
|
||||
- update the `Pool` object with tokens moved from `BondedTokens` to `NotBondedTokens`
|
||||
- set `validator.Status` to `Unbonding`
|
||||
- delete record the existing record from `ValidatorByPowerIndex`
|
||||
- add an new updated record to the `ValidatorByPowerIndex`
|
||||
- update the `Validator` object for this validator
|
||||
- insert a new record into the `ValidatorQueue` for this validator
|
||||
|
||||
### Unbonding to Unbonded
|
||||
A validator moves from unbonding to unbonded when the `ValidatorQueue` object
|
||||
moves from bonded to unbonded
|
||||
- update the `Validator` object for this validator
|
||||
- set `validator.Status` to `Unbonded`
|
||||
|
||||
### Jail/Unjail
|
||||
when a validator is jailed it is effectively removed from the Tendermint set.
|
||||
this process may be also be reversed. the following operations occur:
|
||||
- set `Validator.Jailed` and update object
|
||||
- if jailed delete record from `ValidatorByPowerIndex`
|
||||
- if unjailed add record to `ValidatorByPowerIndex`
|
||||
|
||||
|
||||
## Delegations
|
||||
|
||||
### Delegate
|
||||
When a delegation occurs both the validator and the delegtion objects are affected
|
||||
- determine the delegators shares based on tokens delegated and the validator's exchange rate
|
||||
- remove tokens from the sending account
|
||||
- add shares the delegation object or add them to a created validator object
|
||||
- add new delegator shares and update the `Validator` object
|
||||
- update the `Pool` object appropriately if tokens have moved into a bonded validator
|
||||
- delete record the existing record from `ValidatorByPowerIndex`
|
||||
- add an new updated record to the `ValidatorByPowerIndex`
|
||||
|
||||
#### Unbond Delegation
|
||||
As a part of the Undelegate and Complete Unbonding state transitions Unbond
|
||||
Delegation may be called.
|
||||
- subtract the unbonded shares from delegator
|
||||
- update the delegation or remove the delegation if there are no more shares
|
||||
- if the delegation is the operator of the validator and no more shares exist
|
||||
then trigger a jail validator
|
||||
- update the validator with removed the delegator shares and associated coins, update
|
||||
the pool for any shifts between bonded and non-bonded tokens.
|
||||
- remove the validator if it is unbonded and there are no more delegation shares.
|
||||
|
||||
### Undelegate
|
||||
When an delegation occurs both the validator and the delegtion objects are affected
|
||||
- perform an unbond delegation
|
||||
- if the validator is unbonding or bonded add the tokens to an
|
||||
`UnbondingDelegation` Entry
|
||||
- if the validator is unbonded send the tokens directly to the withdraw
|
||||
account
|
||||
|
||||
### Complete Unbonding
|
||||
For undelegations which do not complete immediately, the following operations
|
||||
occur when the unbonding delegation queue element matures:
|
||||
- remove the entry from the `UnbondingDelegation` object
|
||||
- withdraw the tokens to the delegator withdraw address
|
||||
|
||||
### Begin Redelegation
|
||||
Redelegations affect the delegation, source and destination validators.
|
||||
- perform an unbond delegation from the source validator
|
||||
- using the generated tokens perform a Delegate to the destination
|
||||
validator
|
||||
- record the token amount in an new entry in the relevant `Redelegation`
|
||||
|
||||
### Complete Redelegation
|
||||
When a redelegations complete the following occurs:
|
||||
- remove the entry from the `Redelegation` object
|
||||
|
||||
|
||||
TODO TODO TOFU TODO
|
||||
## Slashing
|
||||
|
||||
### Slash Validator
|
||||
|
||||
### Slash Unbonding Delegation
|
||||
|
||||
### Slash Redelegation
|
||||
Reference in New Issue
Block a user