Skip to main content

Staking

ℹ️info

JMES's staking module inherits from the Cosmos SDK's staking module. This document is a stub and mainly covers important JMES-specific notes on how it is used.

The staking module enables JMES's proof-of-stake functionality by requiring validators to bond bJMES, the native staking asset.

Message types​

MsgDelegate​


_5
type MsgDelegate struct {
_5
DelegatorAddress sdk.AccAddress `json:"delegator_address" yaml:"delegator_address"`
_5
ValidatorAddress sdk.ValAddress `json:"validator_address" yaml:"validator_address"`
_5
Amount sdk.Coin `json:"amount" yaml:"amount"`
_5
}

MsgUndelegate​


_5
type MsgUndelegate struct {
_5
DelegatorAddress sdk.AccAddress `json:"delegator_address" yaml:"delegator_address"`
_5
ValidatorAddress sdk.ValAddress `json:"validator_address" yaml:"validator_address"`
_5
Amount sdk.Coin `json:"amount" yaml:"amount"`
_5
}

MsgBeginRedelegate​


_6
type MsgBeginRedelegate struct {
_6
DelegatorAddress sdk.AccAddress `json:"delegator_address" yaml:"delegator_address"`
_6
ValidatorSrcAddress sdk.ValAddress `json:"validator_src_address" yaml:"validator_src_address"`
_6
ValidatorDstAddress sdk.ValAddress `json:"validator_dst_address" yaml:"validator_dst_address"`
_6
Amount sdk.Coin `json:"amount" yaml:"amount"`
_6
}

MsgEditValidator​


_6
type MsgEditValidator struct {
_6
Description Description `json:"description" yaml:"description"`
_6
ValidatorAddress sdk.ValAddress `json:"address" yaml:"address"`
_6
CommissionRate *sdk.Dec `json:"commission_rate" yaml:"commission_rate"`
_6
MinSelfDelegation *sdk.Int `json:"min_self_delegation" yaml:"min_self_delegation"`
_6
}

MsgCreateValidator​


_9
type MsgCreateValidator struct {
_9
Description Description `json:"description" yaml:"description"`
_9
Commission CommissionRates `json:"commission" yaml:"commission"`
_9
MinSelfDelegation sdk.Int `json:"min_self_delegation" yaml:"min_self_delegation"`
_9
DelegatorAddress sdk.AccAddress `json:"delegator_address" yaml:"delegator_address"`
_9
ValidatorAddress sdk.ValAddress `json:"validator_address" yaml:"validator_address"`
_9
PubKey crypto.PubKey `json:"pubkey" yaml:"pubkey"`
_9
Value sdk.Coin `json:"value" yaml:"value"`
_9
}

Transitions​

End-Block​

This section was taken from the official Cosmos SDK docs, and placed here for your convenience to understand the Staking module's parameters.

Each abci end block call, the operations to update queues and validator set changes are specified to execute.

Validator set changes​

The staking validator set is updated during this process by state transitions that run at the end of every block. As a part of this process, any updated validators are also returned back to Tendermint for inclusion in the Tendermint validator set, which is responsible for validating Tendermint messages at the consensus layer. The following operations are done:

  • The new validator set is taken as the top params.MaxValidators number of validators retrieved from the ValidatorsByPower index.
  • The previous validator set is compared with the new validator set:
    • Missing validators begin unbonding, and their Tokens are transferred from the BondedPool to the NotBondedPool ModuleAccount.
    • New validators are instantly bonded, and their Tokens are transferred from the NotBondedPool to the BondedPool ModuleAccount.

In all cases, any validators leaving or entering the bonded validator set or changing balances and staying within the bonded validator set incur an update message that is passed back to Tendermint.

Queues​

Within staking, certain state transitions are not instantaneous but happen over a duration of time, typically the unbonding period. When these transitions are mature, certain operations must take place to complete the state operation. It is achieved through the use of queues that are checked and processed at the end of each block.

Unbonding validators​

When a validator is kicked out of the bonded validator set, because either they are jailed or they don't have sufficient bonded tokens, it begins the unbonding process along with all its delegations begin unbonding, while still being delegated to this validator. At this point, the validator is said to be an unbonding validator, whereby it matures to become an unbonded validator after the unbonding period has passed.

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 that do not have any remaining delegations 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​

Complete the unbonding of all mature UnbondingDelegations.Entries within the UnbondingDelegations queue with the following procedure:

  • Transfer the balance coins to the delegator's wallet address.
  • Remove the mature entry from UnbondingDelegation.Entries.
  • Remove the UnbondingDelegation object from the store, if there are no remaining entries.
Redelegations​

Complete the unbonding of all mature Redelegation.Entries within the Redelegations queue with the following procedure:

  • Remove the mature entry from Redelegation.Entries.
  • Remove the Redelegation object from the store, if there are no remaining entries.

Parameters​

The subspace for the Staking module is staking.


_6
type Params struct {
_6
UnbondingTime time.Duration `json:"unbonding_time" yaml:"unbonding_time"`
_6
MaxValidators uint16 `json:"max_validators" yaml:"max_validators"`
_6
MaxEntries uint16 `json:"max_entries" yaml:"max_entries"`
_6
BondDenom string `json:"bond_denom" yaml:"bond_denom"`
_6
}

The genesis parameters for the staking module outlined in the Genesis Builder Script are as follows:


_7
# Staking: change bond_denom to ubJMES and max validators to 100
_7
genesis['app_state']['staking']['params'] = {
_7
'unbonding_time': '1814400s', # 21 days
_7
'max_validators': 100,
_7
'max_entries': 7,
_7
'historical_entries': 10000,
_7
'bond_denom': DENOM_BJMES

unbonding_time​

  • type: time.Duration
  • default: 3 weeks

Time duration of unbonding in seconds.

max_validators​

  • type: uint16
  • default: 100

Maximum number of active validators.

max_entries​

  • type: uint16
  • default: 7

Maximum entries for either unbonding delegation or redelegation per pair or trio. Be aware of potential overflow because this is user-determined.

bond_denom​

  • type: string
  • default: ubJMES

Denomination of the asset required for staking.