referrerpolicy=no-referrer-when-downgrade

pallet_staking_async/
lib.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! # Staking Async Pallet
19//!
20//! This pallet is a fork of the original `pallet-staking`, with a number of key differences:
21//!
22//! * It no longer has access to a secure timestamp, previously used to calculate the duration of an
23//!   era.
24//! * It no longer has access to a pallet-session.
25//! * It no longer has access to a pallet-authorship.
26//! * It is capable of working with a multi-page `ElectionProvider``, aka.
27//!   `pallet-election-provider-multi-block`.
28//!
29//! While `pallet-staking` was somewhat general-purpose, this pallet is absolutely NOT right from
30//! the get-go: It is designed to be used ONLY in Polkadot/Kusama AssetHub system parachains.
31//!
32//! ## Reward and Inflation
33//!
34//! This pallet supports two reward modes, controlled by [`Config::DisableMinting`]:
35//!
36//! ### Non-minting mode (`DisableMinting = true`)
37//!
38//! Staking does **not** mint tokens. It expects an external source (e.g. `pallet-dap`) to
39//! fund the general staker reward pot ([`PotAccountProvider`]). At each era boundary,
40//! staking snapshots the accumulated balance into an era-specific pot via
41//! [`EraRewardManager`](reward::EraRewardManager). Payouts transfer from the era pot.
42//!
43//! Unclaimed rewards from expired eras (past `HistoryDepth`) are withdrawn and passed to
44//! [`Config::UnclaimedRewardHandler`].
45//!
46//! [`DisableMintingGuard`] is set on the first successful snapshot as a safety net — it
47//! prevents the payout side from falling back to legacy minting for eras that should have
48//! reward pots.
49//!
50//! ### Legacy minting mode (`DisableMinting = false`)
51//!
52//! At era boundary, [`Config::EraPayout`] computes inflation based on `total_staked`,
53//! `total_issuance`, and era duration. Tokens are minted on-the-fly during `payout_stakers`.
54//! The treasury remainder is sent to [`Config::RewardRemainder`]. [`MaxStakedRewards`] can
55//! cap the staker portion. [`Config::MaxEraDuration`] caps the effective era duration.
56//!
57//! This mode is kept for Kusama/non-polkadot runtime's compatibility where inflation depends on the
58//! staking ratio.
59//!
60//! ### Switching modes
61//!
62//! Switching from legacy to non-minting is a one-way migration. Once `DisableMinting` is
63//! set to `true`, it must **never** be switched back — eras created in non-minting mode
64//! have funded reward pots, and switching to legacy would orphan those pots and cause
65//! double-minting.
66//!
67//! ## Slashing Pipeline and Withdrawal Restrictions
68//!
69//! This pallet implements a robust slashing mechanism that ensures the integrity of the staking
70//! system while preventing stakers from withdrawing funds that might still be subject to slashing.
71//!
72//! ### Overview of the Slashing Pipeline
73//!
74//! The slashing process consists of multiple phases:
75//!
76//! 1. **Offence Reporting**: Offences are reported from the relay chain through `on_new_offences`
77//! 2. **Queuing**: Valid offences are added to the `OffenceQueue` for processing
78//! 3. **Processing**: Offences are processed incrementally over multiple blocks
79//! 4. **Application**: Slashes are either applied immediately or deferred based on configuration
80//!
81//! ### Phase 1: Offence Reporting
82//!
83//! Offences are reported from the relay chain (e.g., from BABE, GRANDPA, BEEFY, or parachain
84//! modules) through the `on_new_offences` function:
85//!
86//! ```text
87//! struct Offence {
88//!     offender: AccountId,        // The validator being slashed
89//!     reporters: Vec<AccountId>,  // Who reported the offence (may be empty)
90//!     slash_fraction: Perbill,    // Percentage of stake to slash
91//! }
92//! ```
93//!
94//! **Reporting Deadlines**:
95//! - With deferred slashing: Offences must be reported within `SlashDeferDuration - 1` eras
96//! - With immediate slashing: Offences can be reported up to `BondingDuration` eras old
97//!
98//! Example: If `SlashDeferDuration = 27` and current era is 100:
99//! - Oldest reportable offence: Era 74 (100 - 26)
100//! - Offences from era 73 or earlier are rejected
101//!
102//! ### Phase 2: Queuing
103//!
104//! When an offence passes validation, it's added to the queue:
105//!
106//! 1. **Storage**: Added to `OffenceQueue`: `(EraIndex, AccountId) -> OffenceRecord`
107//! 2. **Era Tracking**: Era added to `OffenceQueueEras` (sorted vector of eras with offences)
108//! 3. **Duplicate Handling**: If an offence already exists for the same validator in the same era,
109//!    only the higher slash fraction is kept
110//!
111//! ### Phase 3: Processing
112//!
113//! Offences are processed incrementally in `on_initialize` each block:
114//!
115//! ```text
116//! 1. Load oldest offence from queue
117//! 2. Move to `ProcessingOffence` storage
118//! 3. For each exposure page (from last to first):
119//!    - Calculate slash for validator's own stake
120//!    - Calculate slash for each nominator (pro-rata based on exposure)
121//!    - Track total slash and reward amounts
122//! 4. Once all pages processed, create `UnappliedSlash`
123//! ```
124//!
125//! **Key Features**:
126//! - **Page-by-page processing**: Large validator sets don't overwhelm a single block
127//! - **Pro-rata slashing**: Nominators slashed proportionally to their stake
128//! - **Reward calculation**: A portion goes to reporters (if any)
129//!
130//! ### Phase 4: Application
131//!
132//! Based on `SlashDeferDuration`, slashes are either:
133//!
134//! **Immediate (SlashDeferDuration = 0)**:
135//! - Applied right away in the same block
136//! - Funds deducted from staking ledger immediately
137//!
138//! **Deferred (SlashDeferDuration > 0)**:
139//! - Stored in `UnappliedSlashes` for future application
140//! - Applied at era: `offence_era + SlashDeferDuration`
141//! - Can be cancelled by governance before application
142//!
143//! ### Storage Items Involved
144//!
145//! - `OffenceQueue`: Pending offences to process
146//! - `OffenceQueueEras`: Sorted list of eras with offences
147//! - `ProcessingOffence`: Currently processing offence
148//! - `ValidatorSlashInEra`: Tracks highest slash per validator per era
149//! - `UnappliedSlashes`: Deferred slashes waiting for application
150//!
151//! ### Withdrawal Restrictions
152//!
153//! To maintain slashing guarantees, withdrawals are restricted:
154//!
155//! **Withdrawal Era Calculation**:
156//! ```text
157//! earliest_era_to_withdraw = min(
158//!     active_era,
159//!     last_fully_processed_offence_era + BondingDuration
160//! )
161//! ```
162//!
163//! **Example**:
164//! - Active era: 100
165//! - Oldest unprocessed offence: Era 70
166//! - BondingDuration: 28
167//! - Withdrawal allowed only for chunks with era ≤ 97 (70 - 1 + 28)
168//!
169//! **Withdrawal Timeline Example with an Offence**:
170//! ```text
171//! Era:        90    91    92    93    94    95    96    97    98    99    100   ...  117   118
172//!             |     |     |     |     |     |     |     |     |     |     |          |     |
173//! Unbond:     U
174//! Offence:    X
175//! Reported:               R
176//! Processed:              P (within next few blocks)
177//! Slash Applied:                                                                       S
178//! Withdraw:                                                                            ❌    ✓
179//!
180//! With BondingDuration = 28 and SlashDeferDuration = 27:
181//! - User unbonds in era 90
182//! - Offence occurs in era 90
183//! - Reported in era 92 (typically within 2 days, but reportable until Era 116)
184//! - Processed in era 92 (within next few blocks after reporting)
185//! - Slash deferred for 27 eras, applied at era 117 (90 + 27)
186//! - Cannot withdraw unbonded chunks until era 118 (90 + 28)
187//!
188//! The 28-era bonding duration ensures that any offences committed before or during
189//! unbonding have time to be reported, processed, and applied before funds can be
190//! withdrawn. This provides a window for governance to cancel slashes that may have
191//! resulted from software bugs.
192//! ```
193//!
194//! **Key Restrictions**:
195//! 1. Cannot withdraw if previous era has unapplied slashes
196//! 2. Cannot withdraw funds from eras with unprocessed offences
197
198#![cfg_attr(not(feature = "std"), no_std)]
199#![recursion_limit = "256"]
200
201#[cfg(feature = "runtime-benchmarks")]
202pub mod benchmarking;
203#[cfg(any(feature = "runtime-benchmarks", test))]
204pub mod testing_utils;
205
206#[cfg(test)]
207pub(crate) mod mock;
208#[cfg(test)]
209mod tests;
210
211pub mod asset;
212pub mod election_size_tracker;
213pub mod ledger;
214pub mod migrations;
215mod pallet;
216pub mod reward;
217pub mod session_rotation;
218pub mod slashing;
219pub mod weights;
220
221extern crate alloc;
222use alloc::{vec, vec::Vec};
223use codec::{Decode, DecodeWithMemTracking, Encode, HasCompact, MaxEncodedLen};
224use frame_election_provider_support::ElectionProvider;
225use frame_support::{
226	traits::{
227		tokens::fungible::{Credit, Debt},
228		ConstU32, Contains, Get, LockIdentifier,
229	},
230	weights::Weight,
231	BoundedVec, DebugNoBound, DefaultNoBound, EqNoBound, PartialEqNoBound, WeakBoundedVec,
232};
233use frame_system::pallet_prelude::BlockNumberFor;
234use ledger::LedgerIntegrityState;
235use scale_info::TypeInfo;
236use sp_runtime::{
237	traits::{AtLeast32BitUnsigned, One, StaticLookup, UniqueSaturatedInto},
238	BoundedBTreeMap, Debug, Perbill, Saturating,
239};
240use sp_staking::{EraIndex, ExposurePage, PagedExposureMetadata, ServiceKind, SessionIndex};
241pub use sp_staking::{Exposure, IndividualExposure, StakerStatus};
242pub use weights::WeightInfo;
243
244// public exports
245pub use ledger::{StakingLedger, UnlockChunk};
246pub use pallet::{pallet::*, UseNominatorsAndValidatorsMap, UseValidatorsMap};
247
248pub(crate) const STAKING_ID: LockIdentifier = *b"staking ";
249pub(crate) const LOG_TARGET: &str = "runtime::staking-async";
250
251// syntactic sugar for logging.
252#[macro_export]
253macro_rules! log {
254	($level:tt, $patter:expr $(, $values:expr)* $(,)?) => {
255		log::$level!(
256			target: crate::LOG_TARGET,
257			concat!("[{:?}] 💸 ", $patter), <frame_system::Pallet<T>>::block_number() $(, $values)*
258		)
259	};
260}
261
262/// Alias for a bounded set of exposures behind a validator, parameterized by this pallet's
263/// election provider.
264pub type BoundedExposuresOf<T> = BoundedVec<
265	(
266		<T as frame_system::Config>::AccountId,
267		Exposure<<T as frame_system::Config>::AccountId, BalanceOf<T>>,
268	),
269	MaxWinnersPerPageOf<<T as Config>::ElectionProvider>,
270>;
271
272/// Alias for the maximum number of winners (aka. active validators), as defined in by this pallet's
273/// config.
274pub type MaxWinnersOf<T> = <T as Config>::MaxValidatorSet;
275
276/// Alias for the maximum number of winners per page, as expected by the election provider.
277pub type MaxWinnersPerPageOf<P> = <P as ElectionProvider>::MaxWinnersPerPage;
278
279/// Maximum number of nominations per nominator.
280pub type MaxNominationsOf<T> =
281	<<T as Config>::NominationsQuota as NominationsQuota<BalanceOf<T>>>::MaxNominations;
282
283/// Counter for the number of "reward" points earned by a given validator.
284pub type RewardPoint = u32;
285
286/// The balance type of this pallet.
287pub type BalanceOf<T> = <T as Config>::CurrencyBalance;
288
289type PositiveImbalanceOf<T> = Debt<<T as frame_system::Config>::AccountId, <T as Config>::Currency>;
290pub type NegativeImbalanceOf<T> =
291	Credit<<T as frame_system::Config>::AccountId, <T as Config>::Currency>;
292
293type AccountIdLookupOf<T> = <<T as frame_system::Config>::Lookup as StaticLookup>::Source;
294
295/// Information regarding the active era (era in used in session).
296#[derive(Encode, Decode, Debug, TypeInfo, MaxEncodedLen, PartialEq, Eq, Clone)]
297pub struct ActiveEraInfo {
298	/// Index of era.
299	pub index: EraIndex,
300	/// Moment of start expressed as millisecond from `$UNIX_EPOCH`.
301	///
302	/// Start can be none if start hasn't been set for the era yet,
303	/// Start is set on the first on_finalize of the era to guarantee usage of `Time`.
304	pub start: Option<u64>,
305}
306
307/// Reward points of an era. Used to split era total payout between validators.
308///
309/// This points will be used to reward validators and their respective nominators.
310#[derive(
311	PartialEqNoBound, Encode, Decode, DebugNoBound, TypeInfo, MaxEncodedLen, DefaultNoBound,
312)]
313#[codec(mel_bound())]
314#[scale_info(skip_type_params(T))]
315pub struct EraRewardPoints<T: Config> {
316	/// Total number of points. Equals the sum of reward points for each validator.
317	pub total: RewardPoint,
318	/// The reward points earned by a given validator.
319	pub individual: BoundedBTreeMap<T::AccountId, RewardPoint, T::MaxValidatorSet>,
320}
321
322/// A destination account for payment.
323#[derive(
324	PartialEq,
325	Eq,
326	Copy,
327	Clone,
328	Encode,
329	Decode,
330	DecodeWithMemTracking,
331	Debug,
332	TypeInfo,
333	MaxEncodedLen,
334)]
335pub enum RewardDestination<AccountId> {
336	/// Pay into the stash account, increasing the amount at stake accordingly.
337	Staked,
338	/// Pay into the stash account, not increasing the amount at stake.
339	Stash,
340	#[deprecated(
341		note = "`Controller` will be removed after January 2024. Use `Account(controller)` instead."
342	)]
343	Controller,
344	/// Pay into a specified account.
345	Account(AccountId),
346	/// Receive no reward.
347	None,
348}
349
350/// Preference of what happens regarding validation.
351#[derive(
352	PartialEq,
353	Eq,
354	Clone,
355	Encode,
356	Decode,
357	DecodeWithMemTracking,
358	Debug,
359	TypeInfo,
360	Default,
361	MaxEncodedLen,
362)]
363pub struct ValidatorPrefs {
364	/// Reward that validator takes up-front; only the rest is split between themselves and
365	/// nominators.
366	#[codec(compact)]
367	pub commission: Perbill,
368	/// Whether or not this validator is accepting more nominations. If `true`, then no nominator
369	/// who is not already nominating this validator may nominate them. By default, validators
370	/// are accepting nominations.
371	pub blocked: bool,
372}
373
374/// Status of a paged snapshot progress.
375#[derive(PartialEq, Eq, Clone, Encode, Decode, Debug, TypeInfo, MaxEncodedLen, Default)]
376pub enum SnapshotStatus<AccountId> {
377	/// Paged snapshot is in progress, the `AccountId` was the last staker iterated in the list.
378	Ongoing(AccountId),
379	/// All the stakers in the system have been consumed since the snapshot started.
380	Consumed,
381	/// Waiting for a new snapshot to be requested.
382	#[default]
383	Waiting,
384}
385
386/// A record of the nominations made by a specific account.
387#[derive(
388	PartialEqNoBound, EqNoBound, Clone, Encode, Decode, DebugNoBound, TypeInfo, MaxEncodedLen,
389)]
390#[codec(mel_bound())]
391#[scale_info(skip_type_params(T))]
392pub struct Nominations<T: Config> {
393	/// The targets of nomination.
394	pub targets: BoundedVec<T::AccountId, MaxNominationsOf<T>>,
395	/// The era the nominations were submitted.
396	///
397	/// Except for initial nominations which are considered submitted at era 0.
398	pub submitted_in: EraIndex,
399	/// Whether the nominations have been suppressed. This can happen due to slashing of the
400	/// validators, or other events that might invalidate the nomination.
401	///
402	/// NOTE: this for future proofing and is thus far not used.
403	pub suppressed: bool,
404}
405
406/// Facade struct to encapsulate `PagedExposureMetadata` and a single page of `ExposurePage`.
407///
408/// This is useful where we need to take into account the validator's own stake and total exposure
409/// in consideration, in addition to the individual nominators backing them.
410#[derive(Encode, Decode, Debug, TypeInfo, PartialEq, Eq)]
411pub struct PagedExposure<AccountId, Balance: HasCompact + codec::MaxEncodedLen> {
412	exposure_metadata: PagedExposureMetadata<Balance>,
413	exposure_page: ExposurePage<AccountId, Balance>,
414}
415
416impl<AccountId, Balance: HasCompact + Copy + AtLeast32BitUnsigned + codec::MaxEncodedLen>
417	PagedExposure<AccountId, Balance>
418{
419	/// Create a new instance of `PagedExposure` from legacy clipped exposures.
420	pub fn from_clipped(exposure: Exposure<AccountId, Balance>) -> Self {
421		Self {
422			exposure_metadata: PagedExposureMetadata {
423				total: exposure.total,
424				own: exposure.own,
425				nominator_count: exposure.others.len() as u32,
426				page_count: 1,
427			},
428			exposure_page: ExposurePage { page_total: exposure.total, others: exposure.others },
429		}
430	}
431
432	/// Create a new instance of `PagedExposure` from just the exposure metadata (overview).
433	///
434	/// This creates a `PagedExposure` with an empty `others` list, useful when only the
435	/// validator's own stake needs to be considered (e.g., when nominators are not slashable).
436	pub fn from_overview(overview: PagedExposureMetadata<Balance>) -> Self {
437		Self {
438			exposure_metadata: PagedExposureMetadata {
439				total: overview.total,
440				own: overview.own,
441				nominator_count: overview.nominator_count,
442				page_count: 1,
443			},
444			exposure_page: ExposurePage { page_total: overview.total, others: vec![] },
445		}
446	}
447
448	/// Returns total exposure of this validator across pages
449	pub fn total(&self) -> Balance {
450		self.exposure_metadata.total
451	}
452
453	/// Returns total exposure of this validator for the current page
454	pub fn page_total(&self) -> Balance {
455		self.exposure_page.page_total + self.exposure_metadata.own
456	}
457
458	/// Returns validator's own stake that is exposed
459	pub fn own(&self) -> Balance {
460		self.exposure_metadata.own
461	}
462
463	/// Returns the portions of nominators stashes that are exposed in this page.
464	pub fn others(&self) -> &Vec<IndividualExposure<AccountId, Balance>> {
465		&self.exposure_page.others
466	}
467}
468
469/// A pending slash record. The value of the slash has been computed but not applied yet,
470/// rather deferred for several eras.
471#[derive(Encode, Decode, DebugNoBound, TypeInfo, MaxEncodedLen, PartialEqNoBound, EqNoBound)]
472#[scale_info(skip_type_params(T))]
473pub struct UnappliedSlash<T: Config> {
474	/// The stash ID of the offending validator.
475	pub validator: T::AccountId,
476	/// The validator's own slash.
477	pub own: BalanceOf<T>,
478	/// All other slashed stakers and amounts.
479	pub others: WeakBoundedVec<(T::AccountId, BalanceOf<T>), T::MaxExposurePageSize>,
480	/// Reporters of the offence; bounty payout recipients.
481	pub reporter: Option<T::AccountId>,
482	/// The amount of payout.
483	pub payout: BalanceOf<T>,
484}
485
486/// Something that defines the maximum number of nominations per nominator based on a curve.
487///
488/// The method `curve` implements the nomination quota curve and should not be used directly.
489/// However, `get_quota` returns the bounded maximum number of nominations based on `fn curve` and
490/// the nominator's balance.
491pub trait NominationsQuota<Balance> {
492	/// Strict maximum number of nominations that caps the nominations curve. This value can be
493	/// used as the upper bound of the number of votes per nominator.
494	type MaxNominations: Get<u32>;
495
496	/// Returns the voter's nomination quota within reasonable bounds [`min`, `max`], where `min`
497	/// is 1 and `max` is `Self::MaxNominations`.
498	fn get_quota(balance: Balance) -> u32 {
499		Self::curve(balance).clamp(1, Self::MaxNominations::get())
500	}
501
502	/// Returns the voter's nomination quota based on its balance and a curve.
503	fn curve(balance: Balance) -> u32;
504}
505
506/// Check if validator was inactive at some era.
507///
508/// The check is based on the [`RewardPoint`]s the validator received during the era, per
509/// [`ServiceKind`].
510pub trait IsValidatorInactive<AccountId> {
511	/// Tell if the validator is considered inactive in `era`, given its `points` per service.
512	///
513	/// A service the validator earned nothing for may be missing from `points`. Points of eras
514	/// before they were recorded per service count as [`ServiceKind::RelayConsensus`].
515	fn is_inactive(era: EraIndex, stash: &AccountId, points: &[(ServiceKind, RewardPoint)])
516		-> bool;
517}
518
519/// A validator is never inactive, so no validator can be chilled for inactivity.
520impl<AccountId> IsValidatorInactive<AccountId> for () {
521	fn is_inactive(
522		_era: EraIndex,
523		_stash: &AccountId,
524		_points: &[(ServiceKind, RewardPoint)],
525	) -> bool {
526		false
527	}
528}
529
530/// A validator is inactive if it earned no points for any service.
531pub struct AllZero;
532impl<AccountId> IsValidatorInactive<AccountId> for AllZero {
533	fn is_inactive(
534		_era: EraIndex,
535		_stash: &AccountId,
536		points: &[(ServiceKind, RewardPoint)],
537	) -> bool {
538		points.iter().all(|(_, points)| *points == 0)
539	}
540}
541
542/// Notified when a new era becomes active.
543pub trait OnEraStart<AccountId> {
544	/// Whether the hook is in use. When `false`, staking does not keep the elected set, and at
545	/// era start it only removes a copy kept while the hook was enabled, charged as one read and
546	/// one write.
547	///
548	/// Expected to be constant for a given runtime version.
549	fn enabled() -> bool {
550		true
551	}
552
553	/// Called once when `era` becomes active, with the validators elected for it.
554	fn on_era_start(era: EraIndex, validators: &[AccountId]);
555
556	/// Upper bound of the weight of [`Self::on_era_start`] for `validators` validators.
557	fn weight(validators: u32) -> Weight;
558}
559
560impl<AccountId> OnEraStart<AccountId> for () {
561	fn enabled() -> bool {
562		false
563	}
564
565	fn on_era_start(_era: EraIndex, _validators: &[AccountId]) {}
566
567	fn weight(_validators: u32) -> Weight {
568		Weight::zero()
569	}
570}
571
572/// A nomination quota that allows up to MAX nominations for all validators.
573pub struct FixedNominationsQuota<const MAX: u32>;
574impl<Balance, const MAX: u32> NominationsQuota<Balance> for FixedNominationsQuota<MAX> {
575	type MaxNominations = ConstU32<MAX>;
576
577	fn curve(_: Balance) -> u32 {
578		MAX
579	}
580}
581
582pub use sp_staking::EraPayout;
583
584/// Mode of era-forcing.
585#[derive(
586	Copy,
587	Clone,
588	PartialEq,
589	Eq,
590	Encode,
591	Decode,
592	DecodeWithMemTracking,
593	Debug,
594	TypeInfo,
595	MaxEncodedLen,
596	serde::Serialize,
597	serde::Deserialize,
598)]
599pub enum Forcing {
600	/// Not forcing anything - just let whatever happen.
601	NotForcing,
602	/// Force a new era, then reset to `NotForcing` as soon as it is done.
603	/// Note that this will force to trigger an election until a new era is triggered, if the
604	/// election failed, the next session end will trigger a new election again, until success.
605	ForceNew,
606	/// Avoid a new era indefinitely.
607	ForceNone,
608	/// Force a new era at the end of all sessions indefinitely.
609	ForceAlways,
610}
611
612impl Default for Forcing {
613	fn default() -> Self {
614		Forcing::NotForcing
615	}
616}
617
618/// A utility struct that provides a way to check if a given account is a staker.
619///
620/// This struct implements the `Contains` trait, allowing it to determine whether
621/// a particular account is currently staking by checking if the account exists in
622/// the staking ledger.
623///
624/// Intended to be used in [`crate::Config::Filter`].
625pub struct AllStakers<T: Config>(core::marker::PhantomData<T>);
626
627impl<T: Config> Contains<T::AccountId> for AllStakers<T> {
628	/// Checks if the given account ID corresponds to a staker.
629	///
630	/// # Returns
631	/// - `true` if the account has an entry in the staking ledger (indicating it is staking).
632	/// - `false` otherwise.
633	fn contains(account: &T::AccountId) -> bool {
634		Ledger::<T>::contains_key(account)
635	}
636}
637
638/// Size of the rotating pool of era-specific pot accounts.
639///
640/// Era pots are addressed by `era % POT_POOL_SIZE`, so a pot account is reused
641/// every `POT_POOL_SIZE` eras instead of a fresh account being created per era.
642/// This bounds the total storage footprint contributed by era pot accounts to a
643/// constant rather than growing with chain age.
644///
645/// Must be strictly greater than [`Config::HistoryDepth`] so that a slot is only
646/// reused after its previous era has been pruned and drained. The
647/// [`integrity_test`] enforces this invariant at runtime startup.
648pub(crate) const POT_POOL_SIZE: u32 = 200;
649
650/// Maps an era index to its slot in the rotating pot pool.
651pub(crate) fn pot_slot(era: EraIndex) -> u32 {
652	era % POT_POOL_SIZE
653}
654
655/// Kind of reward managed by staking pots.
656#[derive(
657	Debug, Clone, Copy, PartialEq, Eq, Encode, Decode, codec::DecodeWithMemTracking, TypeInfo,
658)]
659pub enum RewardKind {
660	/// Staker rewards (nominators + validators).
661	#[codec(index = 0)]
662	StakerRewards,
663	/// Pot for validator self-stake incentive.
664	#[codec(index = 1)]
665	ValidatorSelfStake,
666}
667
668/// Identifies a reward pot account.
669#[derive(
670	Debug, Clone, Copy, PartialEq, Eq, Encode, Decode, codec::DecodeWithMemTracking, TypeInfo,
671)]
672pub enum RewardPot {
673	/// General pot: funded by an external source (e.g. pallet-dap).
674	/// At era boundaries, staking snapshots the balance into an era-specific pot.
675	#[codec(index = 0)]
676	General(RewardKind),
677	/// Era-specific pot: snapshotted from the general pot at era boundaries.
678	/// See `POT_POOL_SIZE` for the slot rotation scheme.
679	#[codec(index = 1)]
680	Era(EraIndex, RewardKind),
681}
682
683/// Trait for generating reward pot account IDs.
684pub trait PotAccountProvider<AccountId> {
685	fn pot_account(pot: RewardPot) -> AccountId;
686}
687
688/// Seed-based pot account provider for production use.
689///
690/// Era pots are derived from `(slot, kind)` where `slot = era % POT_POOL_SIZE`,
691/// so a fixed pool of accounts rotates instead of creating one per era.
692pub struct Seed<S>(core::marker::PhantomData<S>);
693
694impl<AccountId, S> PotAccountProvider<AccountId> for Seed<S>
695where
696	AccountId: codec::FullCodec,
697	S: Get<frame_support::PalletId>,
698{
699	fn pot_account(pot: RewardPot) -> AccountId {
700		use sp_runtime::traits::AccountIdConversion;
701		// Era pots are addressed by slot (`era % POT_POOL_SIZE`), not by the
702		// raw era index, so a fixed pool of accounts rotates instead of
703		// growing per era.
704		let normalized = match pot {
705			RewardPot::Era(era, kind) => RewardPot::Era(pot_slot(era), kind),
706			other => other,
707		};
708		S::get().into_sub_account_truncating(normalized)
709	}
710}
711
712/// Sequential pot account provider for testing.
713///
714/// Mirrors the production rotation: era pots collide every `POT_POOL_SIZE`
715/// eras so tests exercise the same pool reuse path.
716#[cfg(feature = "std")]
717pub struct SequentialTest;
718
719#[cfg(feature = "std")]
720impl<AccountId> PotAccountProvider<AccountId> for SequentialTest
721where
722	AccountId: From<u64>,
723{
724	fn pot_account(pot: RewardPot) -> AccountId {
725		match pot {
726			RewardPot::General(RewardKind::StakerRewards) => AccountId::from(200_000u64),
727			RewardPot::General(RewardKind::ValidatorSelfStake) => AccountId::from(200_001u64),
728			RewardPot::Era(era, RewardKind::StakerRewards) => {
729				AccountId::from(100_000 + (pot_slot(era) as u64 * 10))
730			},
731			RewardPot::Era(era, RewardKind::ValidatorSelfStake) => {
732				AccountId::from(100_000 + (pot_slot(era) as u64 * 10) + 1)
733			},
734		}
735	}
736}
737
738/// Budget recipient for staker rewards.
739///
740/// Exposes the general staker reward pot so DAP can drip inflation into it.
741pub struct StakerRewardRecipient<P>(core::marker::PhantomData<P>);
742
743impl<AccountId, P> sp_staking::budget::BudgetRecipient<AccountId> for StakerRewardRecipient<P>
744where
745	P: PotAccountProvider<AccountId>,
746{
747	fn budget_key() -> sp_staking::budget::BudgetKey {
748		sp_staking::budget::BudgetKey::truncate_from(b"staker_rewards".to_vec())
749	}
750
751	fn pot_account() -> AccountId {
752		P::pot_account(RewardPot::General(RewardKind::StakerRewards))
753	}
754}
755
756/// Budget recipient for validator self-stake incentive.
757///
758/// Exposes the general validator incentive pot so DAP can drip inflation into it.
759pub struct ValidatorIncentiveRecipient<P>(core::marker::PhantomData<P>);
760
761impl<AccountId, P> sp_staking::budget::BudgetRecipient<AccountId> for ValidatorIncentiveRecipient<P>
762where
763	P: PotAccountProvider<AccountId>,
764{
765	fn budget_key() -> sp_staking::budget::BudgetKey {
766		sp_staking::budget::BudgetKey::truncate_from(b"validator_incentive".to_vec())
767	}
768
769	fn pot_account() -> AccountId {
770		P::pot_account(RewardPot::General(RewardKind::ValidatorSelfStake))
771	}
772}
773
774/// A smart type to determine the [`Config::PlanningEraOffset`], given:
775///
776/// * Expected relay session duration, `RS`
777/// * Time taking into consideration for XCM sending, `S`
778///
779/// It will use the estimated election duration, the relay session duration, and add one as it knows
780/// the relay chain will want to buffer validators for one session. This is needed because we use
781/// this in our calculation based on the "active era".
782pub struct PlanningEraOffsetOf<T, RS, S>(core::marker::PhantomData<(T, RS, S)>);
783impl<T: Config, RS: Get<BlockNumberFor<T>>, S: Get<BlockNumberFor<T>>> Get<SessionIndex>
784	for PlanningEraOffsetOf<T, RS, S>
785{
786	fn get() -> SessionIndex {
787		let election_duration = <T::ElectionProvider as ElectionProvider>::duration_with_export();
788		let sessions_needed = (election_duration + S::get()) / RS::get();
789		// add one, because we know the RC session pallet wants to buffer for one session, and
790		// another one cause we will receive activation report one session after that.
791		sessions_needed
792			.saturating_add(One::one())
793			.saturating_add(One::one())
794			.unique_saturated_into()
795	}
796}