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

     1  <!--
     2  order: 3
     3  -->
     4  
     5  # Messages
     6  
     7  In this section we describe the processing of the staking messages and the corresponding updates to the state. All created/modified state objects specified by each message are defined within the [state](./02_state_transitions.md) section.
     8  
     9  ## MsgCreateValidator
    10  
    11  A validator is created using the `MsgCreateValidator` message.
    12  The validator must be created with an initial delegation from the operator.
    13  
    14  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L16-L17
    15  
    16  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L35-L51
    17  
    18  This message is expected to fail if:
    19  
    20  - another validator with this operator address is already registered
    21  - another validator with this pubkey is already registered
    22  - the initial self-delegation tokens are of a denom not specified as the bonding denom
    23  - the commission parameters are faulty, namely:
    24      - `MaxRate` is either > 1 or < 0
    25      - the initial `Rate` is either negative or > `MaxRate`
    26      - the initial `MaxChangeRate` is either negative or > `MaxRate`
    27  - the description fields are too large
    28  
    29  This message creates and stores the `Validator` object at appropriate indexes.
    30  Additionally a self-delegation is made with the initial tokens delegation
    31  tokens `Delegation`. The validator always starts as unbonded but may be bonded
    32  in the first end-block.
    33  
    34  ## MsgEditValidator
    35  
    36  The `Description`, `CommissionRate` of a validator can be updated using the
    37  `MsgEditValidator` message.
    38  
    39  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L19-L20
    40  
    41  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L56-L76
    42  
    43  This message is expected to fail if:
    44  
    45  - the initial `CommissionRate` is either negative or > `MaxRate`
    46  - the `CommissionRate` has already been updated within the previous 24 hours
    47  - the `CommissionRate` is > `MaxChangeRate`
    48  - the description fields are too large
    49  
    50  This message stores the updated `Validator` object.
    51  
    52  ## MsgDelegate
    53  
    54  Within this message the delegator provides coins, and in return receives
    55  some amount of their validator's (newly created) delegator-shares that are
    56  assigned to `Delegation.Shares`.
    57  
    58  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L22-L24
    59  
    60  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L81-L90
    61  
    62  This message is expected to fail if:
    63  
    64  - the validator does not exist
    65  - the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
    66  - the exchange rate is invalid, meaning the validator has no tokens (due to slashing) but there are outstanding shares
    67  - the amount delegated is less than the minimum allowed delegation
    68  
    69  If an existing `Delegation` object for provided addresses does not already
    70  exist then it is created as part of this message otherwise the existing
    71  `Delegation` is updated to include the newly received shares.
    72  
    73  The delegator receives newly minted shares at the current exchange rate.
    74  The exchange rate is the number of existing shares in the validator divided by
    75  the number of currently delegated tokens.
    76  
    77  The validator is updated in the `ValidatorByPower` index, and the delegation is
    78  tracked in validator object in the `Validators` index.
    79  
    80  It is possible to delegate to a jailed validator, the only difference being it
    81  will not be added to the power index until it is unjailed.
    82  
    83  ![Delegation sequence](../../../docs/uml/svg/delegation_sequence.svg)
    84  
    85  ## MsgUndelegate
    86  
    87  The `MsgUndelegate` message allows delegators to undelegate their tokens from
    88  validator.
    89  
    90  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L30-L32
    91  
    92  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L112-L121
    93  
    94  This message returns a response containing the completion time of the undelegation:
    95  
    96  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L123-L126
    97  
    98  This message is expected to fail if:
    99  
   100  - the delegation doesn't exist
   101  - the validator doesn't exist
   102  - the delegation has less shares than the ones worth of `Amount`
   103  - existing `UnbondingDelegation` has maximum entries as defined by `params.MaxEntries`
   104  - the `Amount` has a denomination different than one defined by `params.BondDenom`
   105  
   106  When this message is processed the following actions occur:
   107  
   108  - validator's `DelegatorShares` and the delegation's `Shares` are both reduced by the message `SharesAmount`
   109  - calculate the token worth of the shares remove that amount tokens held within the validator
   110  - with those removed tokens, if the validator is:
   111      - `Bonded` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares.
   112      - `Unbonding` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
   113      - `Unbonded` - then send the coins the message `DelegatorAddr`
   114  - if there are no more `Shares` in the delegation, then the delegation object is removed from the store
   115      - under this situation if the delegation is the validator's self-delegation then also jail the validator.
   116  
   117  ![Unbond sequence](../../../docs/uml/svg/unbond_sequence.svg)
   118  
   119  ## MsgBeginRedelegate
   120  
   121  The redelegation command allows delegators to instantly switch validators. Once
   122  the unbonding period has passed, the redelegation is automatically completed in
   123  the EndBlocker.
   124  
   125  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L26-L28
   126  
   127  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L95-L105
   128  
   129  This message returns a response containing the completion time of the redelegation:
   130  
   131  +++ https://github.com/cosmos/cosmos-sdk/blob/v0.40.0/proto/cosmos/staking/v1beta1/tx.proto#L107-L110
   132  
   133  This message is expected to fail if:
   134  
   135  - the delegation doesn't exist
   136  - the source or destination validators don't exist
   137  - the delegation has less shares than the ones worth of `Amount`
   138  - the source validator has a receiving redelegation which is not matured (aka. the redelegation may be transitive)
   139  - existing `Redelegation` has maximum entries as defined by `params.MaxEntries`
   140  - the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
   141  
   142  When this message is processed the following actions occur:
   143  
   144  - the source validator's `DelegatorShares` and the delegations `Shares` are both reduced by the message `SharesAmount`
   145  - calculate the token worth of the shares remove that amount tokens held within the source validator.
   146  - if the source validator is:
   147      - `Bonded` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with a completion time a full unbonding period from the current time. Update pool shares to reduce BondedTokens and increase NotBondedTokens by token worth of the shares (this may be effectively reversed in the next step however).
   148      - `Unbonding` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
   149      - `Unbonded` - no action required in this step
   150  - Delegate the token worth to the destination validator, possibly moving tokens back to the bonded state.
   151  - if there are no more `Shares` in the source delegation, then the source delegation object is removed from the store
   152      - under this situation if the delegation is the validator's self-delegation then also jail the validator.
   153  
   154  ![Begin redelegation sequence](../../../docs/uml/svg/begin_redelegation_sequence.svg)