github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/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  State transitions in validators are performed on every [`EndBlock`](./05_end_block.md#validator-set-changes) 
    15  in order to check for changes in the active `ValidatorSet`.
    16  
    17  ### Unbonded to Bonded
    18  
    19  The following transition occurs when a validator's ranking in the `ValidatorPowerIndex` surpasses 
    20  that of the `LastValidator`.
    21  
    22  - set `validator.Status` to `Bonded`
    23  - send the `validator.Tokens` from the `NotBondedTokens` to the `BondedPool` `ModuleAccount`
    24  - delete the existing record from `ValidatorByPowerIndex`
    25  - add a new updated record to the `ValidatorByPowerIndex`
    26  - update the `Validator` object for this validator
    27  - if it exists, delete any `ValidatorQueue` record for this validator
    28  
    29  ### Bonded to Unbonding
    30  
    31  When a validator begins the unbonding process the following operations occur:
    32  
    33  - send the `validator.Tokens` from the `BondedPool` to the `NotBondedTokens` `ModuleAccount`
    34  - set `validator.Status` to `Unbonding`
    35  - delete the existing record from `ValidatorByPowerIndex`
    36  - add a new updated record to the `ValidatorByPowerIndex`
    37  - update the `Validator` object for this validator
    38  - insert a new record into the `ValidatorQueue` for this validator
    39  
    40  ### Unbonding to Unbonded
    41  
    42  A validator moves from unbonding to unbonded when the `ValidatorQueue` object
    43  moves from bonded to unbonded
    44  
    45  - update the `Validator` object for this validator
    46  - set `validator.Status` to `Unbonded`
    47  
    48  ### Jail/Unjail
    49  
    50  when a validator is jailed it is effectively removed from the Tendermint set.
    51  this process may be also be reversed. the following operations occur:
    52  
    53  - set `Validator.Jailed` and update object
    54  - if jailed delete record from `ValidatorByPowerIndex`
    55  - if unjailed add record to `ValidatorByPowerIndex`
    56  
    57  ## Delegations
    58  
    59  ### Delegate
    60  
    61  When a delegation occurs both the validator and the delegation objects are affected
    62  
    63  - determine the delegators shares based on tokens delegated and the validator's exchange rate
    64  - remove tokens from the sending account
    65  - add shares the delegation object or add them to a created validator object
    66  - add new delegator shares and update the `Validator` object
    67  - 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
    68  - delete the existing record from `ValidatorByPowerIndex`
    69  - add an new updated record to the `ValidatorByPowerIndex`
    70  
    71  ### Begin Unbonding
    72  
    73  As a part of the Undelegate and Complete Unbonding state transitions Unbond
    74  Delegation may be called.
    75  
    76  - subtract the unbonded shares from delegator
    77  - if the validator is `Unbonding` or `Bonded` add the tokens to an `UnbondingDelegation` Entry
    78  - if the validator is `Unbonded` send the tokens directly to the withdraw
    79    account
    80  - update the delegation or remove the delegation if there are no more shares
    81  - if the delegation is the operator of the validator and no more shares exist then trigger a jail validator
    82  - update the validator with removed the delegator shares and associated coins
    83  - if the validator state is `Bonded`, transfer the `Coins` worth of the unbonded
    84    shares from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
    85  - remove the validator if it is unbonded and there are no more delegation shares.
    86  
    87  ### Complete Unbonding
    88  
    89  For undelegations which do not complete immediately, the following operations
    90  occur when the unbonding delegation queue element matures:
    91  
    92  - remove the entry from the `UnbondingDelegation` object
    93  - transfer the tokens from the `NotBondedPool` `ModuleAccount` to the delegator `Account`
    94  
    95  ### Begin Redelegation
    96  
    97  Redelegations affect the delegation, source and destination validators.
    98  
    99  - perform an `unbond` delegation from the source validator to retrieve the tokens worth of the unbonded shares
   100  - using the unbonded tokens, `Delegate` them to the destination validator
   101  - if the `sourceValidator.Status` is `Bonded`, and the `destinationValidator` is not, 
   102    transfer the newly delegated tokens from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
   103  - otherwise, if the `sourceValidator.Status` is not `Bonded`, and the `destinationValidator` 
   104    is `Bonded`, transfer the newly delegated tokens from the `NotBondedPool` to the `BondedPool` `ModuleAccount`
   105  - record the token amount in an new entry in the relevant `Redelegation`
   106  
   107  ### Complete Redelegation
   108  
   109  When a redelegations complete the following occurs:
   110  
   111  - remove the entry from the `Redelegation` object
   112  
   113  ## Slashing
   114  
   115  ### Slash Validator
   116  
   117  When a Validator is slashed, the following occurs:
   118  
   119  - The total `slashAmount` is calculated as the `slashFactor` (a chain parameter) * `TokensFromConsensusPower`,
   120  the total number of tokens bonded to the validator at the time of the infraction.
   121  - Every unbonding delegation and redelegation from the validator are slashed by the `slashFactor`
   122  percentage of the initialBalance.
   123  - Each amount slashed from redelegations and unbonding delegations is subtracted from the
   124  total slash amount.
   125  - The `remaingSlashAmount` is then slashed from the validator's tokens in the `BondedPool` or
   126  `NonBondedPool` depending on the validator's status. This reduces the total supply of tokens.
   127  
   128  ### Slash Unbonding Delegation
   129  
   130  When a validator is slashed, so are those unbonding delegations from the validator that began unbonding 
   131  after the time of the infraction. Every entry in every unbonding delegation from the validator 
   132  is slashed by `slashFactor`. The amount slashed is calculated from the `InitialBalance` of the 
   133  delegation and is capped to prevent a resulting negative balance. Completed (or mature) unbondings are not slashed.
   134  
   135  ### Slash Redelegation
   136  
   137  When a validator is slashed, so are all redelegations from the validator that began after the
   138  infraction. Redelegations are slashed by `slashFactor`.
   139  The amount slashed is calculated from the `InitialBalance` of the delegation and is capped to
   140  prevent a resulting negative balance. Mature redelegations are not slashed.