[][src]Crate pallet_staking

Staking Module

The Staking module is used to manage funds at stake by network maintainers.

Overview

The Staking module is the means by which a set of network maintainers (known as authorities in some contexts and validators in others) are chosen based upon those who voluntarily place funds under deposit. Under deposit, those funds are rewarded under normal operation but are held at pain of slash (expropriation) should the staked maintainer be found not to be discharging its duties properly.

Terminology

Goals

The staking system in Substrate NPoS is designed to make the following possible:

Scenarios

Staking

Almost any interaction with the Staking module requires a process of bonding (also known as being a staker). To become bonded, a fund-holding account known as the stash account, which holds some or all of the funds that become frozen in place as part of the staking process, is paired with an active controller account, which issues instructions on how they shall be used.

An account pair can become bonded using the bond call.

Stash accounts can change their associated controller using the set_controller call.

There are three possible roles that any staked account pair can be in: Validator, Nominator and Idle (defined in StakerStatus). There are three corresponding instructions to change between roles, namely: validate, nominate, and chill.

Validating

A validator takes the role of either validating blocks or ensuring their finality, maintaining the veracity of the network. A validator should avoid both any sort of malicious misbehavior and going offline. Bonded accounts that state interest in being a validator do NOT get immediately chosen as a validator. Instead, they are declared as a candidate and they might get elected at the next era as a validator. The result of the election is determined by nominators and their votes.

An account can become a validator candidate via the validate call.

Nomination

A nominator does not take any direct role in maintaining the network, instead, it votes on a set of validators to be elected. Once interest in nomination is stated by an account, it takes effect at the next election round. The funds in the nominator's stash account indicate the weight of its vote. Both the rewards and any punishment that a validator earns are shared between the validator and its nominators. This rule incentivizes the nominators to NOT vote for the misbehaving/offline validators as much as possible, simply because the nominators will also lose funds if they vote poorly.

An account can become a nominator via the nominate call.

Rewards and Slash

The reward and slashing procedure is the core of the Staking module, attempting to embrace valid behavior while punishing any misbehavior or lack of availability.

Rewards must be claimed for each era before it gets too old by $HISTORY_DEPTH using the payout_stakers call. Any account can call payout_stakers, which pays the reward to the validator as well as its nominators. Only the [Trait::MaxNominatorRewardedPerValidator] biggest stakers can claim their reward. This is to limit the i/o cost to mutate storage for each nominator's account.

Slashing can occur at any point in time, once misbehavior is reported. Once slashing is determined, a value is deducted from the balance of the validator and all the nominators who voted for this validator (values are deducted from the stash account of the slashed entity).

Slashing logic is further described in the documentation of the slashing module.

Similar to slashing, rewards are also shared among a validator and its associated nominators. Yet, the reward funds are not always transferred to the stash account and can be configured. See Reward Calculation for more details.

Chilling

Finally, any of the roles above can choose to step back temporarily and just chill for a while. This means that if they are a nominator, they will not be considered as voters anymore and if they are validators, they will no longer be a candidate for the next election.

An account can step back via the chill call.

Session managing

The module implement the trait SessionManager. Which is the only API to query new validator set and allowing these validator set to be rewarded once their era is ended.

Interface

Dispatchable Functions

The dispatchable functions of the Staking module enable the steps needed for entities to accept and change their role, alongside some helper functions to get/set the metadata of the module.

Public Functions

The Staking module contains many public storage items and (im)mutable functions.

Usage

Example: Rewarding a validator by id.

use frame_support::{decl_module, dispatch};
use frame_system::{self as system, ensure_signed};
use pallet_staking::{self as staking};

pub trait Trait: staking::Trait {}

decl_module! {
    pub struct Module<T: Trait> for enum Call where origin: T::Origin {
        /// Reward a validator.
        #[weight = 0]
        pub fn reward_myself(origin) -> dispatch::DispatchResult {
            let reported = ensure_signed(origin)?;
            <staking::Module<T>>::reward_by_ids(vec![(reported, 10)]);
            Ok(())
        }
    }
}

Implementation Details

Era payout

The era payout is computed using yearly inflation curve defined at T::RewardCurve as such:

staker_payout = yearly_inflation(npos_token_staked / total_tokens) * total_tokens / era_per_year

This payout is used to reward stakers as defined in next section

remaining_payout = max_yearly_inflation * total_tokens / era_per_year - staker_payout

The remaining reward is send to the configurable end-point T::RewardRemainder.

Reward Calculation

Validators and nominators are rewarded at the end of each era. The total reward of an era is calculated using the era duration and the staking rate (the total amount of tokens staked by nominators and validators, divided by the total token supply). It aims to incentivize toward a defined staking rate. The full specification can be found here.

Total reward is split among validators and their nominators depending on the number of points they received during the era. Points are added to a validator using reward_by_ids or reward_by_indices.

Module implements pallet_authorship::EventHandler to add reward points to block producer and block producer of referenced uncles.

The validator and its nominator split their reward as following:

The validator can declare an amount, named commission, that does not get shared with the nominators at each reward payout through its ValidatorPrefs. This value gets deducted from the total reward that is paid to the validator and its nominators. The remaining portion is split among the validator and all of the nominators that nominated the validator, proportional to the value staked behind this validator (i.e. dividing the own or others by total in Exposure).

All entities who receive a reward have the option to choose their reward destination through the Payee storage item (see set_payee), to be one of the following:

Additional Fund Management Operations

Any funds already placed into stash can be the target of the following operations:

The controller account can free a portion (or all) of the funds using the unbond call. Note that the funds are not immediately accessible. Instead, a duration denoted by BondingDuration (in number of eras) must pass until the funds can actually be removed. Once the BondingDuration is over, the withdraw_unbonded call can be used to actually withdraw the funds.

Note that there is a limitation to the number of fund-chunks that can be scheduled to be unlocked in the future via unbond. In case this maximum (MAX_UNLOCKING_CHUNKS) is reached, the bonded account must first wait until a successful call to withdraw_unbonded to remove some of the chunks.

Election Algorithm

The current election algorithm is implemented based on Phragmén. The reference implementation can be found here.

The election algorithm, aside from electing the validators with the most stake value and votes, tries to divide the nominator votes among candidates in an equal manner. To further assure this, an optional post-processing can be applied that iteratively normalizes the nominator staked values until the total difference among votes of a particular nominator are less than a threshold.

GenesisConfig

The Staking module depends on the GenesisConfig. The GenesisConfig is optional and allow to set some initial stakers.

Modules

benchmarking

Staking pallet benchmarking.

inflation

This module expose one function P_NPoS (Payout NPoS) or compute_total_payout which returns the total payout for the era given the era duration and the staking rate in NPoS. The staking rate in NPoS is the total amount of tokens staked by nominators and validators, divided by the total token supply.

offchain_election

Helpers for offchain worker election.

slashing

A slashing implementation for NPoS systems.

testing_utils

Testing utils for staking. Provides some common functions to setup staking state, such as bonding validators, nominators, and generating different types of solutions.

weight

Macros

log

Structs

ActiveEra

The active era information, it holds index and start.

ActiveEraInfo

Information regarding the active era (era in used in session).

Bonded

Map from all locked "stash" accounts to the controller account.

CanceledSlashPayout

The amount of currency given to reporters of a slash event which was canceled by extraordinary circumstances (e.g. governance).

CurrentEra

The current era index.

ElectionResult

The result of an election round.

ElectionSize

Some indications about the size of the election. This must be submitted with the solution.

EraElectionStatus

Flag to control the execution of the offchain election. When Open(_), we accept solutions to be submitted.

EraRewardPoints

Reward points of an era. Used to split era total payout between validators.

ErasRewardPoints

Rewards for the last HISTORY_DEPTH eras. If reward hasn't been set or has been removed then 0 reward is returned.

ErasStakers

Exposure of validator at era.

ErasStakersClipped

Clipped Exposure of validator at era.

ErasStartSessionIndex

The session index at which the era start for the last HISTORY_DEPTH eras.

ErasTotalStake

The total amount staked for the last HISTORY_DEPTH eras. If total hasn't been set or has been removed then 0 stake is returned.

ErasValidatorPrefs

Similar to ErasStakers, this holds the preferences of validators.

ErasValidatorReward

The total validator era payout for the last HISTORY_DEPTH eras.

Exposure

A snapshot of the stake backing a single validator in the system.

ExposureOf

A typed conversion from stash account ID to the active exposure of nominators on that account.

FilterHistoricalOffences

Filter historical offences out and only allow those from the bonding period.

ForceEra

Mode of era forcing.

GenericCompactAssignments

A struct to encode a election assignment in a compact way.

GenesisConfig

Genesis config for the module, allow to build genesis storage.

IndividualExposure

The amount of exposure (to slashing) than an individual nominator has.

Invulnerables

Any validators that may never be slashed or forcibly kicked. It's a Vec since they're easy to initialize and the performance hit is minimal (we expect no more than four invulnerables) and restricted to testnets.

IsCurrentSessionFinal

True if the current planned session is final. Note that this does not take era forcing into account.

Ledger

Map from all (unlocked) "controller" accounts to the info regarding the staking.

MinimumValidatorCount

Minimum number of staking participants before emergency conditions are imposed.

Module
Nominations

A record of the nominations made by a specific account.

Nominators

The map from nominator stash key to the set of stash keys of all validators to nominate.

Payee

Where the reward payment should be made. Keyed by stash.

QueuedElected

The next validator set. At the end of an era, if this is available (potentially from the result of an offchain worker), it is immediately used. Otherwise, the on-chain election is executed.

QueuedScore

The score of the current [QueuedElected].

SlashRewardFraction

The percentage of the slash that is distributed to reporters.

SnapshotNominators

Snapshot of nominators at the beginning of the current election window. This should only have a value when [EraElectionStatus] == ElectionStatus::Open(_).

SnapshotValidators

Snapshot of validators at the beginning of the current election window. This should only have a value when [EraElectionStatus] == ElectionStatus::Open(_).

StakingLedger

The ledger of a (bonded) stash.

StashOf

A Convert implementation that finds the stash of the given controller account, if any.

UnappliedSlash

A pending slash record. The value of the slash has been computed but not applied yet, rather deferred for several eras.

UnappliedSlashes

All unapplied slashes that are queued for later.

UnlockChunk

Just a Balance/BlockNumber tuple to encode when a chunk of funds will be unlocked.

ValidatorCount

The ideal number of staking participants.

ValidatorPrefs

Preference of what happens regarding validation.

Validators

The map from (wannabe) validator stash key to the preferences of that validator.

Enums

Call

Dispatchable calls.

ElectionCompute

Indicate how an election round was computed.

ElectionStatus

The status of the upcoming (offchain) election.

Error

Error for the staking module.

Forcing

Mode of era-forcing.

RawEvent

Events for this module.

RewardDestination

A destination account for payment.

StakerStatus

Indicates the initial status of the staker.

Constants

MAX_NOMINATIONS
MAX_UNLOCKING_CHUNKS

Traits

SessionInterface

Means for interacting with a specialized version of the session trait.

Trait

Type Definitions

BalanceOf

The balance type of this module.

ChainAccuracy

Accuracy used for on-chain election.

CompactAssignments

The compact type for election solutions.

EraIndex

Counter for the number of eras that have passed.

Event

RawEvent specialized for the configuration Trait

NominatorIndex

Data type used to index nominators in the compact type

OffchainAccuracy

Accuracy used for off-chain election. This better be small.

RewardPoint

Counter for the number of "reward" points earned by a given validator.

ValidatorIndex

Data type used to index validators in the compact type.