Crates.io | pallet-staking |
lib.rs | pallet-staking |
version | 35.0.0 |
source | src |
created_at | 2020-02-27 23:23:49.168947 |
updated_at | 2024-07-12 23:03:19.832408 |
description | FRAME pallet staking (polkadot v1.14.0) |
homepage | https://substrate.io |
repository | https://github.com/paritytech/polkadot-sdk.git |
max_upload_size | |
id | 213387 |
size | 740,036 |
The Staking module is used to manage funds at stake by network maintainers.
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.
The staking system in Substrate NPoS is designed to make the following possible:
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. The controller account, which this pallet now assigns the stash account to, issues instructions on how funds shall be used.
An account can become a bonded stash account using the
bond
call.
Stash accounts can update their associated controller back to their stash account using the
set_controller
call.
Note: Controller accounts are being deprecated in favor of proxy accounts, so it is no longer possible to set a unique address for a stash's controller.
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
.
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.
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.
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. When a
validator has more than [Config::MaxExposurePageSize
] nominators, nominators are divided into pages with each call to
payout_stakers
paying rewards to one page of nominators in a sequential and ascending manner. Any account can also
call payout_stakers_by_page
to explicitly pay reward for a given page. As evident, this means only the
[Config::MaxExposurePageSize
] nominators are rewarded per call. 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.
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.
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.
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.
The Staking module contains many public storage items and (im)mutable functions.
use pallet_staking::{self as staking};
#[frame_support::pallet]
pub mod pallet {
use super::*;
use frame_support::pallet_prelude::*;
use frame_system::pallet_prelude::*;
#[pallet::pallet]
pub struct Pallet<T>(_);
#[pallet::config]
pub trait Config: frame_system::Config + staking::Config {}
#[pallet::call]
impl<T: Config> Pallet<T> {
/// Reward a validator.
#[pallet::weight(0)]
pub fn reward_myself(origin: OriginFor<T>) -> DispatchResult {
let reported = ensure_signed(origin)?;
<staking::Pallet<T>>::reward_by_ids(vec![(reported, 10)]);
Ok(())
}
}
}
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
.
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:
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.
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.
The Staking module depends on the
GenesisConfig
. The GenesisConfig
is optional and allow to set some initial stakers.
Validators
at the end of each era.License: Apache-2.0