github.com/Finschia/finschia-sdk@v0.48.1/x/staking/spec/02_state_transitions.md (about)

     1  <!--
     2  order: 2
     3  -->
     4  
     5  # State Transitions
     6  
     7  This document describes the state transition operations pertaining to:
     8  
     9  1. [Validators](./02_state_transitions.md#validators)
    10  2. [Delegations](./02_state_transitions.md#delegations)
    11  3. [Slashing](./02_state_transitions.md#slashing)
    12  
    13  ## Validators
    14  
    15  State transitions in validators are performed on every [`EndBlock`](./05_end_block.md#validator-set-changes)
    16  in order to check for changes in the active `ValidatorSet`.
    17  
    18  A validator can be `Unbonded`, `Unbonding` or `Bonded`. `Unbonded`
    19  and `Unbonding` are collectively called `Not Bonded`. A validator can move
    20  directly between all the states, except for from `Bonded` to `Unbonded`.
    21  
    22  ### Not bonded to Bonded
    23  
    24  The following transition occurs when a validator's ranking in the `ValidatorPowerIndex` surpasses
    25  that of the `LastValidator`.
    26  
    27  - set `validator.Status` to `Bonded`
    28  - send the `validator.Tokens` from the `NotBondedTokens` to the `BondedPool` `ModuleAccount`
    29  - delete the existing record from `ValidatorByPowerIndex`
    30  - add a new updated record to the `ValidatorByPowerIndex`
    31  - update the `Validator` object for this validator
    32  - if it exists, delete any `ValidatorQueue` record for this validator
    33  
    34  ### Bonded to Unbonding
    35  
    36  When a validator begins the unbonding process the following operations occur:
    37  
    38  - send the `validator.Tokens` from the `BondedPool` to the `NotBondedTokens` `ModuleAccount`
    39  - set `validator.Status` to `Unbonding`
    40  - delete the existing record from `ValidatorByPowerIndex`
    41  - add a new updated record to the `ValidatorByPowerIndex`
    42  - update the `Validator` object for this validator
    43  - insert a new record into the `ValidatorQueue` for this validator
    44  
    45  ### Unbonding to Unbonded
    46  
    47  A validator moves from unbonding to unbonded when the `ValidatorQueue` object
    48  moves from bonded to unbonded
    49  
    50  - update the `Validator` object for this validator
    51  - set `validator.Status` to `Unbonded`
    52  
    53  ### Jail/Unjail
    54  
    55  when a validator is jailed it is effectively removed from the Tendermint set.
    56  this process may be also be reversed. the following operations occur:
    57  
    58  - set `Validator.Jailed` and update object
    59  - if jailed delete record from `ValidatorByPowerIndex`
    60  - if unjailed add record to `ValidatorByPowerIndex`
    61  
    62  Jailed validators are not present in any of the following stores:
    63  
    64  - the power store (from consensus power to address)
    65  
    66  ## Delegations
    67  
    68  ### Delegate
    69  
    70  When a delegation occurs both the validator and the delegation objects are affected
    71  
    72  - determine the delegators shares based on tokens delegated and the validator's exchange rate
    73  - remove tokens from the sending account
    74  - add shares the delegation object or add them to a created validator object
    75  - add new delegator shares and update the `Validator` object
    76  - transfer the `delegation.Amount` from the delegator's account to the `BondedPool` or the `NotBondedPool` `ModuleAccount` depending if the `validator.Status` is `Bonded` or not
    77  - delete the existing record from `ValidatorByPowerIndex`
    78  - add an new updated record to the `ValidatorByPowerIndex`
    79  
    80  ### Begin Unbonding
    81  
    82  As a part of the Undelegate and Complete Unbonding state transitions Unbond
    83  Delegation may be called.
    84  
    85  - subtract the unbonded shares from delegator
    86  - if the validator is `Unbonding` or `Bonded` add the tokens to an `UnbondingDelegation` Entry
    87  - if the validator is `Unbonded` send the tokens directly to the withdraw
    88    account
    89  - update the delegation or remove the delegation if there are no more shares
    90  - if the delegation is the operator of the validator and no more shares exist then trigger a jail validator
    91  - update the validator with removed the delegator shares and associated coins
    92  - if the validator state is `Bonded`, transfer the `Coins` worth of the unbonded
    93    shares from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
    94  - remove the validator if it is unbonded and there are no more delegation shares.
    95  
    96  ### Complete Unbonding
    97  
    98  For undelegations which do not complete immediately, the following operations
    99  occur when the unbonding delegation queue element matures:
   100  
   101  - remove the entry from the `UnbondingDelegation` object
   102  - transfer the tokens from the `NotBondedPool` `ModuleAccount` to the delegator `Account`
   103  
   104  ### Begin Redelegation
   105  
   106  Redelegations affect the delegation, source and destination validators.
   107  
   108  - perform an `unbond` delegation from the source validator to retrieve the tokens worth of the unbonded shares
   109  - using the unbonded tokens, `Delegate` them to the destination validator
   110  - if the `sourceValidator.Status` is `Bonded`, and the `destinationValidator` is not,
   111    transfer the newly delegated tokens from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
   112  - otherwise, if the `sourceValidator.Status` is not `Bonded`, and the `destinationValidator`
   113    is `Bonded`, transfer the newly delegated tokens from the `NotBondedPool` to the `BondedPool` `ModuleAccount`
   114  - record the token amount in an new entry in the relevant `Redelegation`
   115  
   116  From when a redelegation begins until it completes, the delegator is in a state of "pseudo-unbonding", and can still be
   117  slashed for infractions that occured before the redelegation began.
   118  
   119  ### Complete Redelegation
   120  
   121  When a redelegations complete the following occurs:
   122  
   123  - remove the entry from the `Redelegation` object
   124  
   125  ## Slashing
   126  
   127  ### Slash Validator
   128  
   129  When a Validator is slashed, the following occurs:
   130  
   131  - The total `slashAmount` is calculated as the `slashFactor` (a chain parameter) \* `TokensFromConsensusPower`,
   132    the total number of tokens bonded to the validator at the time of the infraction.
   133  - Every unbonding delegation and pseudo-unbonding redelegation such that the infraction occured before the unbonding or
   134    redelegation began from the validator are slashed by the `slashFactor` percentage of the initialBalance.
   135  - Each amount slashed from redelegations and unbonding delegations is subtracted from the
   136    total slash amount.
   137  - The `remaingSlashAmount` is then slashed from the validator's tokens in the `BondedPool` or
   138    `NonBondedPool` depending on the validator's status. This reduces the total supply of tokens.
   139  
   140  In the case of a slash due to any infraction that requires evidence to submitted (for example double-sign), the slash
   141  occurs at the block where the evidence is included, not at the block where the infraction occured.
   142  Put otherwise, validators are not slashed retroactively, only when they are caught.
   143  
   144  ### Slash Unbonding Delegation
   145  
   146  When a validator is slashed, so are those unbonding delegations from the validator that began unbonding
   147  after the time of the infraction. Every entry in every unbonding delegation from the validator
   148  is slashed by `slashFactor`. The amount slashed is calculated from the `InitialBalance` of the
   149  delegation and is capped to prevent a resulting negative balance. Completed (or mature) unbondings are not slashed.
   150  
   151  ### Slash Redelegation
   152  
   153  When a validator is slashed, so are all redelegations from the validator that began after the
   154  infraction. Redelegations are slashed by `slashFactor`.
   155  Redelegations that began before the infraction are not slashed.
   156  The amount slashed is calculated from the `InitialBalance` of the delegation and is capped to
   157  prevent a resulting negative balance.
   158  Mature redelegations (that have completed pseudo-unbonding) are not slashed.
   159  
   160  ## How Shares are calculated
   161  
   162  At any given point in time, each validator has a number of tokens, `T`, and has a number of shares issued, `S`.
   163  Each delegator, `i`, holds a number of shares, `S_i`.
   164  The number of tokens is the sum of all tokens delegated to the validator, plus the rewards, minus the slashes.
   165  
   166  The delegator is entitled to a portion of the underlying tokens proportional to their proportion of shares.
   167  So delegator `i` is entitled to `T * S_i / S` of the validator's tokens.
   168  
   169  When a delegator delegates new tokens to the validator, they receive a number of shares proportional to their contribution.
   170  So when delegator `j` delegates `T_j` tokens, they receive `S_j = S * T_j / T` shares.
   171  The total number of tokens is now `T + T_j`, and the total number of shares is `S + S_j`.
   172  `j`s proportion of the shares is the same as their proportion of the total tokens contributed: `(S + S_j) / S = (T + T_j) / T`.
   173  
   174  A special case is the initial delegation, when `T = 0` and `S = 0`, so `T_j / T` is undefined.
   175  For the initial delegation, delegator `j` who delegates `T_j` tokens receive `S_j = T_j` shares.
   176  So a validator that hasn't received any rewards and has not been slashed will have `T = S`.