Struct pallet_staking::Module

pub struct Module<T: Trait>(_);

Implementations

impl<T: Trait + 'static> Module<T>

pub fn history_depth() -> u32

Number of eras to keep in history.

Information is kept for eras in [current_era - history_depth; current_era].

Must be more than the number of eras delayed by session otherwise. I.e. active era must always be in history. I.e. active_era > current_era - history_depth must be guaranteed.

pub fn validator_count() -> u32

The ideal number of staking participants.

pub fn minimum_validator_count() -> u32

Minimum number of staking participants before emergency conditions are imposed.

pub fn invulnerables() -> Vec<T::AccountId>

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.

pub fn bonded<K: EncodeLike<T::AccountId>>(key: K) -> Option<T::AccountId>

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

pub fn ledger<K: EncodeLike<T::AccountId>>(
    key: K
) -> Option<StakingLedger<T::AccountId, BalanceOf<T>>>

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

pub fn payee<K: EncodeLike<T::AccountId>>(key: K) -> RewardDestination

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

pub fn validators<K: EncodeLike<T::AccountId>>(key: K) -> ValidatorPrefs

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

pub fn nominators<K: EncodeLike<T::AccountId>>(
    key: K
) -> Option<Nominations<T::AccountId>>

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

pub fn current_era() -> Option<EraIndex>

The current era index.

This is the latest planned era, depending on how the Session pallet queues the validator set, it might be active or not.

pub fn active_era() -> Option<ActiveEraInfo>

The active era information, it holds index and start.

The active era is the era currently rewarded. Validator set of this era must be equal to SessionInterface::validators.

pub fn eras_start_session_index<K: EncodeLike<EraIndex>>(
    key: K
) -> Option<SessionIndex>

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

pub fn eras_stakers<KArg1, KArg2>(
    k1: KArg1,
    k2: KArg2
) -> Exposure<T::AccountId, BalanceOf<T>> where
    KArg1: EncodeLike<EraIndex>,
    KArg2: EncodeLike<T::AccountId>, 

pub fn eras_stakers_clipped<KArg1, KArg2>(
    k1: KArg1,
    k2: KArg2
) -> Exposure<T::AccountId, BalanceOf<T>> where
    KArg1: EncodeLike<EraIndex>,
    KArg2: EncodeLike<T::AccountId>, 

pub fn eras_validator_prefs<KArg1, KArg2>(
    k1: KArg1,
    k2: KArg2
) -> ValidatorPrefs where
    KArg1: EncodeLike<EraIndex>,
    KArg2: EncodeLike<T::AccountId>, 

pub fn eras_validator_reward<K: EncodeLike<EraIndex>>(
    key: K
) -> Option<BalanceOf<T>>

The total validator era payout for the last HISTORY_DEPTH eras.

Eras that haven't finished yet or has been removed doesn't have reward.

pub fn eras_reward_points<K: EncodeLike<EraIndex>>(
    key: K
) -> EraRewardPoints<T::AccountId>

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

pub fn eras_total_stake<K: EncodeLike<EraIndex>>(key: K) -> BalanceOf<T>

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.

pub fn force_era() -> Forcing

Mode of era forcing.

pub fn slash_reward_fraction() -> Perbill

The percentage of the slash that is distributed to reporters.

The rest of the slashed value is handled by the Slash.

pub fn canceled_payout() -> BalanceOf<T>

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

pub fn snapshot_validators() -> Option<Vec<T::AccountId>>

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

pub fn snapshot_nominators() -> Option<Vec<T::AccountId>>

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

pub fn queued_elected() -> Option<ElectionResult<T::AccountId, BalanceOf<T>>>

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.

pub fn queued_score() -> Option<ElectionScore>

The score of the current QueuedElected.

pub fn era_election_status() -> ElectionStatus<T::BlockNumber>

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

pub fn is_current_session_final() -> bool

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

impl<T: Trait> Module<T>

Can also be called using Call.

pub fn bond(
    origin: T::Origin,
    controller: <T::Lookup as StaticLookup>::Source,
    value: BalanceOf<T>,
    payee: RewardDestination
) -> DispatchResult

Take the origin account as a stash and lock up value of its balance. controller will be the account that controls it.

value must be more than the minimum_balance specified by T::Currency.

The dispatch origin for this call must be Signed by the stash account.

Emits Bonded.

• Independent of the arguments. Moderate complexity.
• O(1).
• Three extra DB entries.

NOTE: Two of the storage writes (Self::bonded, Self::payee) are never cleaned unless the origin falls below existential deposit and gets removed as dust.

Base Weight: 67.87 µs DB Weight:

• Read: Bonded, Ledger, [Origin Account], Current Era, History Depth, Locks
• Write: Bonded, Payee, [Origin Account], Locks, Ledger

NOTE: Calling this function will bypass origin filters.

pub fn validate(origin: T::Origin, prefs: ValidatorPrefs) -> DispatchResult

Declare the desire to validate for the origin controller.

Effects will be felt at the beginning of the next era.

The dispatch origin for this call must be Signed by the controller, not the stash. And, it can be only called when EraElectionStatus is Closed.

• Independent of the arguments. Insignificant complexity.
• Contains a limited number of reads.
• Writes are limited to the origin account key.

---

Base Weight: 17.13 µs DB Weight:

• Read: Era Election Status, Ledger
• Write: Nominators, Validators

NOTE: Calling this function will bypass origin filters.

pub fn nominate(
    origin: T::Origin,
    targets: Vec<<T::Lookup as StaticLookup>::Source>
) -> DispatchResult

Declare the desire to nominate targets for the origin controller.

Effects will be felt at the beginning of the next era. This can only be called when EraElectionStatus is Closed.

The dispatch origin for this call must be Signed by the controller, not the stash. And, it can be only called when EraElectionStatus is Closed.

• The transaction's complexity is proportional to the size of targets (N) which is capped at CompactAssignments::LIMIT (MAX_NOMINATIONS).
• Both the reads and writes follow a similar pattern.

---

Base Weight: 22.34 + .36 * N µs where N is the number of targets DB Weight:

• Reads: Era Election Status, Ledger, Current Era
• Writes: Validators, Nominators

NOTE: Calling this function will bypass origin filters.

pub fn submit_election_solution(
    origin: T::Origin,
    winners: Vec<ValidatorIndex>,
    compact: CompactAssignments,
    score: ElectionScore,
    era: EraIndex,
    size: ElectionSize
) -> DispatchResultWithPostInfo

Submit an election result to the chain. If the solution:

1. is valid.
2. has a better score than a potentially existing solution on chain.

then, it will be put on chain.

A solution consists of two pieces of data:

1. winners: a flat vector of all the winners of the round.
2. assignments: the compact version of an assignment vector that encodes the edge weights.

Both of which may be computed using phragmen, or any other algorithm.

Additionally, the submitter must provide:

• The score that they claim their solution has.

Both validators and nominators will be represented by indices in the solution. The indices should respect the corresponding types (ValidatorIndex and NominatorIndex). Moreover, they should be valid when used to index into SnapshotValidators and SnapshotNominators. Any invalid index will cause the solution to be rejected. These two storage items are set during the election window and may be used to determine the indices.

A solution is valid if:

0. It is submitted when EraElectionStatus is Open.
1. Its claimed score is equal to the score computed on-chain.
2. Presents the correct number of winners.
3. All indexes must be value according to the snapshot vectors. All edge values must also be correct and should not overflow the granularity of the ratio type (i.e. 256 or billion).
4. For each edge, all targets are actually nominated by the voter.
5. Has correct self-votes.

A solutions score is consisted of 3 parameters:

1. min { support.total } for each support of a winner. This value should be maximized.
2. sum { support.total } for each support of a winner. This value should be minimized.
3. sum { support.total^2 } for each support of a winner. This value should be minimized (to ensure less variance)

See crate::weight module.

NOTE: Calling this function will bypass origin filters.

pub fn submit_election_solution_unsigned(
    origin: T::Origin,
    winners: Vec<ValidatorIndex>,
    compact: CompactAssignments,
    score: ElectionScore,
    era: EraIndex,
    size: ElectionSize
) -> DispatchResultWithPostInfo

Unsigned version of submit_election_solution.

Note that this must pass the [ValidateUnsigned] check which only allows transactions from the local node to be included. In other words, only the block author can include a transaction in the block.

See crate::weight module.

NOTE: Calling this function will bypass origin filters.

impl<T: Trait> Module<T>

pub fn slashable_balance_of(stash: &T::AccountId) -> BalanceOf<T>

The total balance that can be slashed from a stash account as of right now.

pub fn create_stakers_snapshot() -> (bool, Weight)

Dump the list of validators and nominators into vectors and keep them on-chain.

This data is used to efficiently evaluate election results. returns true if the operation is successful.

pub fn pre_dispatch_checks(
    score: ElectionScore,
    era: EraIndex
) -> DispatchResultWithPostInfo

Basic and cheap checks that we perform in validate unsigned, and in the execution.

State reads: ElectionState, CurrentEr, QueuedScore.

This function does weight refund in case of errors, which is based upon the fact that it is called at the very beginning of the call site's function.

pub fn check_and_replace_solution(
    winners: Vec<ValidatorIndex>,
    compact_assignments: CompactAssignments,
    compute: ElectionCompute,
    claimed_score: ElectionScore,
    era: EraIndex,
    election_size: ElectionSize
) -> DispatchResultWithPostInfo

Checks a given solution and if correct and improved, writes it on chain as the queued result of the next round. This may be called by both a signed and an unsigned transaction.

pub fn reward_by_ids(
    validators_points: impl IntoIterator<Item = (T::AccountId, u32)>
)

Add reward points to validators using their stash account ID.

Validators are keyed by stash account ID and must be in the current elected set.

For each element in the iterator the given number of points in u32 is added to the validator, thus duplicates are handled.

At the end of the era each the total payout will be distributed among validator relatively to their points.

COMPLEXITY: Complexity is number_of_validator_to_reward x current_elected_len. If you need to reward lots of validator consider using reward_by_indices.

Trait Implementations

impl<T: Trait> Callable<T> for Module<T>

type Call = Call<T>

impl<T: Clone + Trait> Clone for Module<T>

fn clone(&self) -> Module<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Copy + Trait> Copy for Module<T>

impl<T: Trait> Debug for Module<T> where
    T: Debug, 

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Eq + Trait> Eq for Module<T>

impl<T> EventHandler<<T as Trait>::AccountId, <T as Trait>::BlockNumber> for Module<T> where
    T: Trait + Trait + Trait, 

Add reward points to block authors:

• 20 points to the block producer for producing a (non-uncle) block in the relay chain,
• 2 points to the block producer for each reference to a previously unreferenced uncle, and
• 1 point to the producer of each referenced uncle block.

fn note_author(author: T::AccountId)

Note that the given account ID is the author of the current block.

fn note_uncle(author: T::AccountId, _age: T::BlockNumber)

Note that the given account ID authored the given uncle, and how many blocks older than the current block it is (age >= 0, so siblings are allowed)

impl<T: Trait> IntegrityTest for Module<T>

fn integrity_test()

Run integrity test.

impl<T: Trait> ModuleErrorMetadata for Module<T>

fn metadata() -> &'static [ErrorMetadata]

impl<T: Trait> OffchainWorker<<T as Trait>::BlockNumber> for Module<T>

fn offchain_worker(now: T::BlockNumber)

This function is being called after every block import (when fully synced).

impl<T: Trait> OnFinalize<<T as Trait>::BlockNumber> for Module<T>

fn on_finalize(_block_number_not_used: T::BlockNumber)

The block is being finalized. Implement to have something happen.

impl<T: Trait> OnInitialize<<T as Trait>::BlockNumber> for Module<T>

fn on_initialize(now: T::BlockNumber) -> Weight

The block is being initialized. Implement to have something happen.

impl<T: Trait> OnOffenceHandler<<T as Trait>::AccountId, (<T as Trait>::ValidatorId, <T as Trait>::FullIdentification), u64> for Module<T> where
    T: Trait<ValidatorId = <T as Trait>::AccountId>,
    T: Trait<FullIdentification = Exposure<<T as Trait>::AccountId, BalanceOf<T>>, FullIdentificationOf = ExposureOf<T>>,
    T::SessionHandler: SessionHandler<<T as Trait>::AccountId>,
    T::SessionManager: SessionManager<<T as Trait>::AccountId>,
    T::ValidatorIdOf: Convert<<T as Trait>::AccountId, Option<<T as Trait>::AccountId>>, 

This is intended to be used with FilterHistoricalOffences.

fn on_offence(
    offenders: &[OffenceDetails<T::AccountId, IdentificationTuple<T>>],
    slash_fraction: &[Perbill],
    slash_session: SessionIndex
) -> Result<Weight, ()>

A handler for an offence of a particular kind.

fn can_report() -> bool

Can an offence be reported now or not. This is an method to short-circuit a call into on_offence. Ideally, a correct implementation should return false if on_offence will return Err. Nonetheless, this is up to the implementation and this trait cannot guarantee it.

impl<T: Trait> OnRuntimeUpgrade for Module<T>

fn on_runtime_upgrade() -> u64

Perform a module upgrade.

impl<T: PartialEq + Trait> PartialEq<Module<T>> for Module<T>

fn eq(&self, other: &Module<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Module<T>) -> bool

This method tests for !=.

impl<T: Trait> SessionManager<<T as Trait>::AccountId, Exposure<<T as Trait>::AccountId, <<T as Trait>::Currency as Currency<<T as Trait>::AccountId>>::Balance>> for Module<T>

fn new_session(
    new_index: SessionIndex
) -> Option<Vec<(T::AccountId, Exposure<T::AccountId, BalanceOf<T>>)>>

If there was a validator set change, its returns the set of new validators along with their full identifications.

fn start_session(start_index: SessionIndex)

fn end_session(end_index: SessionIndex)

impl<T: Trait> SessionManager<<T as Trait>::AccountId> for Module<T>

In this implementation new_session(session) must be called before end_session(session-1) i.e. the new session must be planned before the ending of the previous session.

Once the first new_session is planned, all session must start and then end in order, though some session can lag in between the newest session planned and the latest session started.

fn new_session(new_index: SessionIndex) -> Option<Vec<T::AccountId>>

Plan a new session, and optionally provide the new validator set.

fn start_session(start_index: SessionIndex)

Start the session.

fn end_session(end_index: SessionIndex)

End the session.

impl<T: Trait> StructuralEq for Module<T>

impl<T: Trait> StructuralPartialEq for Module<T>

impl<T: Trait> ValidateUnsigned for Module<T>

type Call = Call<T>

The call to validate

fn validate_unsigned(
    source: TransactionSource,
    call: &Self::Call
) -> TransactionValidity

Return the validity of the call

fn pre_dispatch(call: &Self::Call) -> Result<(), TransactionValidityError>

Validate the call right before dispatch.