github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/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  
    13  ```go
    14  type MsgCreateValidator struct {
    15      Description    Description
    16      Commission     Commission
    17  
    18      DelegatorAddr  sdk.AccAddress
    19      ValidatorAddr  sdk.ValAddress
    20      PubKey         crypto.PubKey
    21      Delegation     sdk.Coin
    22  }
    23  ```
    24  
    25  This message is expected to fail if:
    26  
    27  - another validator with this operator address is already registered
    28  - another validator with this pubkey is already registered
    29  - the initial self-delegation tokens are of a denom not specified as the bonding denom
    30  - the commission parameters are faulty, namely:
    31    - `MaxRate` is either > 1 or < 0
    32    - the initial `Rate` is either negative or > `MaxRate`
    33    - the initial `MaxChangeRate` is either negative or > `MaxRate`
    34  - the description fields are too large
    35  
    36  This message creates and stores the `Validator` object at appropriate indexes.
    37  Additionally a self-delegation is made with the initial tokens delegation
    38  tokens `Delegation`. The validator always starts as unbonded but may be bonded
    39  in the first end-block.
    40  
    41  ## MsgEditValidator
    42  
    43  The `Description`, `CommissionRate` of a validator can be updated using the
    44  `MsgEditCandidacy`.  
    45  
    46  ```go
    47  type MsgEditCandidacy struct {
    48      Description     Description
    49      ValidatorAddr   sdk.ValAddress
    50      CommissionRate  sdk.Dec
    51  }
    52  ```
    53  
    54  This message is expected to fail if:
    55  
    56  - the initial `CommissionRate` is either negative or > `MaxRate`
    57  - the `CommissionRate` has already been updated within the previous 24 hours
    58  - the `CommissionRate` is > `MaxChangeRate`
    59  - the description fields are too large
    60  
    61  This message stores the updated `Validator` object.
    62  
    63  ## MsgDelegate
    64  
    65  Within this message the delegator provides coins, and in return receives
    66  some amount of their validator's (newly created) delegator-shares that are
    67  assigned to `Delegation.Shares`.
    68  
    69  ```go
    70  type MsgDelegate struct {
    71    DelegatorAddr sdk.AccAddress
    72    ValidatorAddr sdk.ValAddress
    73    Amount        sdk.Coin
    74  }
    75  ```
    76  
    77  This message is expected to fail if:
    78  
    79  - the validator is does not exist
    80  - the validator is jailed
    81  - the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
    82  
    83  If an existing `Delegation` object for provided addresses does not already
    84  exist than it is created as part of this message otherwise the existing
    85  `Delegation` is updated to include the newly received shares.
    86  
    87  ## MsgBeginUnbonding
    88  
    89  The begin unbonding message allows delegators to undelegate their tokens from
    90  validator.
    91  
    92  ```go
    93  type MsgBeginUnbonding struct {
    94    DelegatorAddr sdk.AccAddress
    95    ValidatorAddr sdk.ValAddress
    96    Amount         sdk.Coin
    97  }
    98  ```
    99  
   100  This message is expected to fail if:
   101  
   102  - the delegation doesn't exist
   103  - the validator doesn't exist
   104  - the delegation has less shares than the ones worth of `Amount`
   105  - existing `UnbondingDelegation` has maximum entries as defined by `params.MaxEntries`
   106  - the `Amount` has a denomination different than one defined by `params.BondDenom`
   107  
   108  When this message is processed the following actions occur:
   109  
   110  - validator's `DelegatorShares` and the delegation's `Shares` are both reduced by the message `SharesAmount`
   111  - calculate the token worth of the shares remove that amount tokens held within the validator
   112  - with those removed tokens, if the validator is:
   113    - `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.
   114    - `Unbonding` - add them to an entry in `UnbondingDelegation` (create `UnbondingDelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
   115    - `Unbonded` - then send the coins the message `DelegatorAddr`
   116  - if there are no more `Shares` in the delegation, then the delegation object is removed from the store
   117    - under this situation if the delegation is the validator's self-delegation then also jail the validator.
   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  ```go
   126  type MsgBeginRedelegate struct {
   127    DelegatorAddr    sdk.AccAddress
   128    ValidatorSrcAddr sdk.ValAddress
   129    ValidatorDstAddr sdk.ValAddress
   130    Amount           sdk.Coin
   131  }
   132  ```
   133  
   134  This message is expected to fail if:
   135  
   136  - the delegation doesn't exist
   137  - the source or destination validators don't exist
   138  - the delegation has less shares than the ones worth of `Amount`
   139  - the source validator has a receiving redelegation which is not matured (aka. the redelegation may be transitive)
   140  - existing `Redelegation` has maximum entries as defined by `params.MaxEntries`
   141  - the `Amount` `Coin` has a denomination different than one defined by `params.BondDenom`
   142  
   143  When this message is processed the following actions occur:
   144  
   145  - the source validator's `DelegatorShares` and the delegations `Shares` are both reduced by the message `SharesAmount`
   146  - calculate the token worth of the shares remove that amount tokens held within the source validator.
   147  - if the source validator is:
   148    - `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).
   149    - `Unbonding` - add an entry to the `Redelegation` (create `Redelegation` if it doesn't exist) with the same completion time as the validator (`UnbondingMinTime`).
   150    - `Unbonded` - no action required in this step
   151  - Delegate the token worth to the destination validator, possibly moving  tokens back to the bonded state.
   152  - if there are no more `Shares` in the source delegation, then the source delegation object is removed from the store
   153    - under this situation if the delegation is the validator's self-delegation then also jail the validator.