referrerpolicy=no-referrer-when-downgrade

pallet_staking_async/
session_rotation.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//! Manages all era rotation logic based on session increments.
19//!
20//! # Lifecycle:
21//!
22//! When a session ends in RC, a session report is sent to AH with the ending session index. Given
23//! there are 6 sessions per Era, and we configure the PlanningEraOffset to be 1, the following
24//! happens.
25//!
26//! ## Idle Sessions
27//! In the happy path, first 3 sessions are idle. Nothing much happens in these sessions.
28//!
29//!
30//! ## Planning New Era Session
31//! In the happy path, `planning new era` session is initiated when 3rd session ends and the 4th
32//! starts in the active era.
33//!
34//! **Triggers**
35//! 1. `SessionProgress == SessionsPerEra - PlanningEraOffset`
36//! 2. Forcing is set to `ForceNew` or `ForceAlways`
37//!
38//! **Actions**
39//! 1. Triggers the election process,
40//! 2. Updates the CurrentEra.
41//!
42//! **SkipIf**
43//! CurrentEra = ActiveEra + 1 // this implies planning session has already been triggered.
44//!
45//! **FollowUp**
46//! When the election process is over, we send the new validator set, with the CurrentEra index
47//! as the id of the validator set.
48//!
49//!
50//! ## Era Rotation Session
51//! In the happy path, this happens when the 5th session ends and the 6th starts in the active era.
52//!
53//! **Triggers**
54//! When we receive an activation timestamp from RC.
55//!
56//! **Assertions**
57//! 1. CurrentEra must be ActiveEra + 1.
58//! 2. Id of the activation timestamp same as CurrentEra.
59//!
60//! **Actions**
61//! - Finalize the currently active era.
62//! - Increment ActiveEra by 1.
63//! - Cleanup the old era information.
64//!
65//! **Exceptional Scenarios**
66//! - Delay in exporting validator set: Triggered in a session later than 7th.
67//! - Forcing Era: May triggered in a session earlier than 7th.
68//!
69//! ## Example Flow of a happy path
70//!
71//! * end 0, start 1, plan 2
72//! * end 1, start 2, plan 3
73//! * end 2, start 3, plan 4
74//! * end 3, start 4, plan 5 // `Plan new era` session. Current Era++. Trigger Election.
75//! * **** Somewhere here: Election set is sent to RC, keyed with Current Era
76//! * end 4, start 5, plan 6 // RC::session receives and queues this set.
77//! * end 5, start 6, plan 7 // Session report contains activation timestamp with Current Era.
78
79use crate::*;
80use alloc::{boxed::Box, vec::Vec};
81use frame_election_provider_support::{BoundedSupportsOf, ElectionProvider, PageIndex};
82use frame_support::{
83	pallet_prelude::*,
84	traits::{Defensive, DefensiveMax, DefensiveSaturating, OnUnbalanced, TryCollect},
85	weights::WeightMeter,
86};
87use pallet_staking_async_rc_client::RcClientInterface;
88use sp_runtime::{Perbill, Percent, Saturating};
89use sp_staking::{
90	currency_to_vote::CurrencyToVote, Exposure, Page, PagedExposureMetadata, ServiceKind,
91	SessionIndex, StakerRewardCalculator,
92};
93
94/// A handler for all era-based storage items.
95///
96/// All of the following storage items must be controlled by this type:
97///
98/// [`ErasValidatorPrefs`]
99/// [`ClaimedRewards`]
100/// [`ErasStakersPaged`]
101/// [`ErasStakersOverview`]
102/// [`ErasValidatorReward`]
103/// [`ErasRewardPoints`]
104/// [`ErasRewardPointsByService`]
105/// [`ErasTotalStake`]
106pub struct Eras<T: Config>(core::marker::PhantomData<T>);
107
108impl<T: Config> Eras<T> {
109	pub(crate) fn set_validator_prefs(era: EraIndex, stash: &T::AccountId, prefs: ValidatorPrefs) {
110		debug_assert_eq!(era, Rotator::<T>::planned_era(), "we only set prefs for planning era");
111		<ErasValidatorPrefs<T>>::insert(era, stash, prefs);
112	}
113
114	pub(crate) fn get_validator_prefs(era: EraIndex, stash: &T::AccountId) -> ValidatorPrefs {
115		<ErasValidatorPrefs<T>>::get(era, stash)
116	}
117
118	/// Returns validator commission for this era and page.
119	pub(crate) fn get_validator_commission(era: EraIndex, stash: &T::AccountId) -> Perbill {
120		Self::get_validator_prefs(era, stash).commission
121	}
122
123	/// Returns true if the validator has unclaimed pages and earned reward points in the era
124	/// (a zero-point payout transfers nothing, so there is nothing to claim).
125	pub(crate) fn pending_rewards(era: EraIndex, validator: &T::AccountId) -> bool {
126		let Some(overview) = <ErasStakersOverview<T>>::get(&era, validator) else {
127			// no exposure, so no rewards to claim.
128			return false;
129		};
130
131		// Zero reward points means a payout transfers nothing, so there is nothing to claim.
132		if Self::get_total_reward_points_for_validator(era, validator).is_zero() {
133			return false;
134		}
135
136		ClaimedRewards::<T>::get(era, validator).len() < overview.page_count as usize
137	}
138
139	/// Get exposure for a validator at a given era and page.
140	///
141	/// This is mainly used for rewards and slashing. Validator's self-stake is only returned in
142	/// page 0.
143	///
144	/// This builds a paged exposure from `PagedExposureMetadata` and `ExposurePage` of the
145	/// validator.
146	pub(crate) fn get_paged_exposure(
147		era: EraIndex,
148		validator: &T::AccountId,
149		page: Page,
150	) -> Option<PagedExposure<T::AccountId, BalanceOf<T>>> {
151		let overview = <ErasStakersOverview<T>>::get(&era, validator)?;
152
153		// validator stake is added only in page zero.
154		let validator_stake = if page == 0 { overview.own } else { Zero::zero() };
155
156		// since overview is present, paged exposure will always be present except when a
157		// validator has only own stake and no nominator stake.
158		let exposure_page = <ErasStakersPaged<T>>::get((era, validator, page)).unwrap_or_default();
159
160		// build the exposure
161		Some(PagedExposure {
162			exposure_metadata: PagedExposureMetadata { own: validator_stake, ..overview },
163			exposure_page: exposure_page.into(),
164		})
165	}
166
167	/// Get full exposure of the validator at a given era.
168	pub(crate) fn get_full_exposure(
169		era: EraIndex,
170		validator: &T::AccountId,
171	) -> Exposure<T::AccountId, BalanceOf<T>> {
172		let Some(overview) = <ErasStakersOverview<T>>::get(&era, validator) else {
173			return Exposure::default();
174		};
175
176		let mut others = Vec::with_capacity(overview.nominator_count as usize);
177		for page in 0..overview.page_count {
178			let nominators = <ErasStakersPaged<T>>::get((era, validator, page));
179			others.append(&mut nominators.map(|n| n.others.clone()).defensive_unwrap_or_default());
180		}
181
182		Exposure { total: overview.total, own: overview.own, others }
183	}
184
185	/// Returns the number of pages of exposure a validator has for the given era.
186	///
187	/// For eras where paged exposure does not exist, this returns 1 to keep backward compatibility.
188	pub(crate) fn exposure_page_count(era: EraIndex, validator: &T::AccountId) -> Page {
189		<ErasStakersOverview<T>>::get(&era, validator)
190			.map(|overview| {
191				if overview.page_count == 0 && overview.own > Zero::zero() {
192					// Even though there are no nominator pages, there is still validator's own
193					// stake exposed which needs to be paid out in a page.
194					1
195				} else {
196					overview.page_count
197				}
198			})
199			// Always returns 1 page for older non-paged exposure.
200			// FIXME: Can be cleaned up with issue #13034.
201			.unwrap_or(1)
202	}
203
204	/// Check whether the validator was exposed at specified era.
205	pub(crate) fn was_validator_exposed(era: EraIndex, validator: &T::AccountId) -> bool {
206		<ErasStakersOverview<T>>::contains_key(era, validator)
207	}
208
209	/// Returns the next page that can be claimed or `None` if nothing to claim.
210	pub(crate) fn get_next_claimable_page(era: EraIndex, validator: &T::AccountId) -> Option<Page> {
211		// Find next claimable page of paged exposure.
212		let page_count = Self::exposure_page_count(era, validator);
213		let all_claimable_pages: Vec<Page> = (0..page_count).collect();
214		let claimed_pages = ClaimedRewards::<T>::get(era, validator);
215
216		all_claimable_pages.into_iter().find(|p| !claimed_pages.contains(p))
217	}
218
219	/// Returns whether nominators are slashable for a specific era.
220	///
221	/// This checks the per-era storage [`ErasNominatorsSlashable`] which captures
222	/// the value of [`AreNominatorsSlashable`] at the start of that era.
223	/// If no entry exists for the era, nominators are assumed to be slashable (default).
224	pub(crate) fn are_nominators_slashable(era: EraIndex) -> bool {
225		ErasNominatorsSlashable::<T>::get(era).unwrap_or(true)
226	}
227
228	/// Creates an entry to track validator reward has been claimed for a given era and page.
229	/// Noop if already claimed.
230	pub(crate) fn set_rewards_as_claimed(era: EraIndex, validator: &T::AccountId, page: Page) {
231		let mut claimed_pages = ClaimedRewards::<T>::get(era, validator).into_inner();
232
233		// this should never be called if the reward has already been claimed
234		if claimed_pages.contains(&page) {
235			defensive!("Trying to set an already claimed reward");
236			// nevertheless don't do anything since the page already exist in claimed rewards.
237			return;
238		}
239
240		// add page to claimed entries
241		claimed_pages.push(page);
242		ClaimedRewards::<T>::insert(
243			era,
244			validator,
245			WeakBoundedVec::<_, _>::force_from(claimed_pages, Some("set_rewards_as_claimed")),
246		);
247	}
248
249	/// Store exposure for elected validators at start of an era.
250	///
251	/// If the exposure does not exist yet for the tuple (era, validator), it sets it. Otherwise,
252	/// it updates the existing record by ensuring *intermediate* exposure pages are filled up with
253	/// `T::MaxExposurePageSize` number of backers per page and the remaining exposures are added
254	/// to new exposure pages.
255	pub fn upsert_exposure(
256		era: EraIndex,
257		validator: &T::AccountId,
258		mut exposure: Exposure<T::AccountId, BalanceOf<T>>,
259	) {
260		let page_size = T::MaxExposurePageSize::get().defensive_max(1);
261		if cfg!(debug_assertions) && cfg!(not(feature = "runtime-benchmarks")) {
262			// sanitize the exposure in case some test data from this pallet is wrong.
263			// ignore benchmarks as other pallets might do weird things.
264			let expected_total = exposure
265				.others
266				.iter()
267				.map(|ie| ie.value)
268				.fold::<BalanceOf<T>, _>(Default::default(), |acc, x| acc + x)
269				.saturating_add(exposure.own);
270			debug_assert_eq!(expected_total, exposure.total, "exposure total must equal own + sum(others) for (era: {:?}, validator: {:?}, exposure: {:?})", era, validator, exposure);
271		}
272
273		if let Some(overview) = ErasStakersOverview::<T>::get(era, &validator) {
274			// collect some info from the un-touched overview for later use.
275			let last_page_idx = overview.page_count.saturating_sub(1);
276			let mut last_page =
277				ErasStakersPaged::<T>::get((era, validator, last_page_idx)).unwrap_or_default();
278			let last_page_empty_slots =
279				T::MaxExposurePageSize::get().saturating_sub(last_page.others.len() as u32);
280
281			// update nominator-count, page-count, and total stake in overview (done in
282			// `update_with`).
283			let new_stake_added = exposure.total;
284			let new_nominators_added = exposure.others.len() as u32;
285			let mut updated_overview = overview
286				.update_with::<T::MaxExposurePageSize>(new_stake_added, new_nominators_added);
287
288			// update own stake, if applicable.
289			match (updated_overview.own.is_zero(), exposure.own.is_zero()) {
290				(true, false) => {
291					// first time we see own exposure -- good.
292					// note: `total` is already updated above.
293					updated_overview.own = exposure.own;
294				},
295				(true, true) | (false, true) => {
296					// no new own exposure is added, nothing to do
297				},
298				(false, false) => {
299					debug_assert!(
300						false,
301						"validator own stake already set in overview for (era: {:?}, validator: {:?}, current overview: {:?}, new exposure: {:?})",
302						era,
303						validator,
304						updated_overview,
305						exposure,
306					);
307					defensive!("duplicate validator self stake in election");
308				},
309			};
310
311			ErasStakersOverview::<T>::insert(era, &validator, updated_overview);
312			// we are done updating the overview now, `updated_overview` should not be used anymore.
313			// We've updated:
314			// * nominator count
315			// * total stake
316			// * own stake (if applicable)
317			// * page count
318			//
319			// next step:
320			// * new-keys or updates in `ErasStakersPaged`
321			//
322			// we don't need the information about own stake anymore -- drop it.
323			exposure.total = exposure.total.saturating_sub(exposure.own);
324			exposure.own = Zero::zero();
325
326			// splits the exposure so that `append_to_last_page` will fit within the last exposure
327			// page, up to the max exposure page size. The remaining individual exposures in
328			// `put_in_new_pages` will be added to new pages.
329			let append_to_last_page = exposure.split_others(last_page_empty_slots);
330			let put_in_new_pages = exposure;
331
332			// handle last page first.
333
334			// fill up last page with exposures.
335			last_page.page_total = last_page.page_total.saturating_add(append_to_last_page.total);
336			last_page.others.extend(append_to_last_page.others);
337			ErasStakersPaged::<T>::insert((era, &validator, last_page_idx), last_page);
338
339			// now handle the remaining exposures and append the exposure pages. The metadata update
340			// has been already handled above.
341			let (_unused_metadata, put_in_new_pages_chunks) =
342				put_in_new_pages.into_pages(page_size);
343
344			put_in_new_pages_chunks
345				.into_iter()
346				.enumerate()
347				.for_each(|(idx, paged_exposure)| {
348					let append_at =
349						(last_page_idx.saturating_add(1).saturating_add(idx as u32)) as Page;
350					<ErasStakersPaged<T>>::insert((era, &validator, append_at), paged_exposure);
351				});
352		} else {
353			// expected page count is the number of nominators divided by the page size, rounded up.
354			let expected_page_count = exposure
355				.others
356				.len()
357				.defensive_saturating_add((page_size as usize).defensive_saturating_sub(1))
358				.saturating_div(page_size as usize);
359
360			// no exposures yet for this (era, validator) tuple, calculate paged exposure pages and
361			// metadata from a blank slate.
362			let (exposure_metadata, exposure_pages) = exposure.into_pages(page_size);
363			defensive_assert!(exposure_pages.len() == expected_page_count, "unexpected page count");
364
365			// insert metadata.
366			ErasStakersOverview::<T>::insert(era, &validator, exposure_metadata);
367
368			// Track that this validator was active in this era for slash liability tracking.
369			LastValidatorEra::<T>::insert(validator, era);
370
371			// insert validator's overview.
372			exposure_pages.into_iter().enumerate().for_each(|(idx, paged_exposure)| {
373				let append_at = idx as Page;
374				<ErasStakersPaged<T>>::insert((era, &validator, append_at), paged_exposure);
375			});
376		};
377	}
378
379	pub(crate) fn set_stakers_reward(era: EraIndex, amount: BalanceOf<T>) {
380		ErasValidatorReward::<T>::insert(era, amount);
381	}
382
383	pub(crate) fn get_stakers_reward(era: EraIndex) -> Option<BalanceOf<T>> {
384		ErasValidatorReward::<T>::get(era)
385	}
386
387	pub(crate) fn set_validator_incentive_budget(era: EraIndex, amount: BalanceOf<T>) {
388		ErasValidatorIncentiveBudget::<T>::insert(era, amount);
389	}
390
391	pub(crate) fn get_validator_incentive_budget(era: EraIndex) -> BalanceOf<T> {
392		ErasValidatorIncentiveBudget::<T>::get(era)
393	}
394
395	pub(crate) fn add_sum_validator_incentive_weight(
396		era: EraIndex,
397		incentive_weight: BalanceOf<T>,
398	) {
399		<ErasSumValidatorIncentiveWeight<T>>::mutate(era, |sum| {
400			*sum = sum.saturating_add(incentive_weight);
401		});
402	}
403
404	/// Update the total exposure for all the elected validators in the era.
405	pub(crate) fn add_total_stake(era: EraIndex, stake: BalanceOf<T>) {
406		<ErasTotalStake<T>>::mutate(era, |total_stake| {
407			*total_stake += stake;
408		});
409	}
410
411	/// Check if the rewards for the given era and page index have been claimed.
412	pub(crate) fn is_rewards_claimed(era: EraIndex, validator: &T::AccountId, page: Page) -> bool {
413		ClaimedRewards::<T>::get(era, validator).contains(&page)
414	}
415
416	/// Add reward points earned for `service` to validators using their stash account ID.
417	///
418	/// Points are added to [`ErasRewardPoints`] of the active era, and every entry recorded there
419	/// is also added to [`ErasRewardPointsByService`] under `service`.
420	///
421	/// As a side effect, accumulates `weight × points` into [`ErasSumWeightedPoints`] for the
422	/// active era, where `weight` is the validator's [`ErasValidatorIncentiveWeight`]. This
423	/// keeps the denominator of the weighted-points share up to date without iterating every
424	/// validator at payout time.
425	pub(crate) fn reward_active_era(
426		service: ServiceKind,
427		validators_points: impl IntoIterator<Item = (T::AccountId, u32)>,
428	) {
429		if let Some(active_era) = ActiveEra::<T>::get() {
430			let mut sum_weighted_points_delta: BalanceOf<T> = Zero::zero();
431			let mut recorded_points = Vec::new();
432			<ErasRewardPoints<T>>::mutate(active_era.index, |era_rewards| {
433				for (validator, points) in validators_points.into_iter() {
434					let weight =
435						ErasValidatorIncentiveWeight::<T>::get(active_era.index, &validator)
436							.unwrap_or_else(Zero::zero);
437
438					let recorded = match era_rewards.individual.get_mut(&validator) {
439						Some(individual) => {
440							individual.saturating_accrue(points);
441							true
442						},
443						None => {
444							// not much we can do -- validators should always be less than
445							// `MaxValidatorSet`.
446							era_rewards
447								.individual
448								.try_insert(validator.clone(), points)
449								.defensive()
450								.is_ok()
451						},
452					};
453
454					// Keep the denominator aligned with `individual`, which is the source used
455					// by payouts and try-state recomputation. A defensive overflow may leave
456					// points unrecorded; those points must not be counted in
457					// `ErasSumWeightedPoints`.
458					if recorded && !weight.is_zero() {
459						sum_weighted_points_delta = sum_weighted_points_delta.saturating_add(
460							weight.saturating_mul(IncentiveWeight::<T>::from(points)),
461						);
462					}
463					if recorded {
464						recorded_points.push((validator, points));
465					}
466
467					era_rewards.total.saturating_accrue(points);
468				}
469			});
470			if !recorded_points.is_empty() {
471				ErasRewardPointsByService::<T>::mutate(active_era.index, service, |by_service| {
472					for (validator, points) in recorded_points {
473						let recorded = match by_service.individual.get_mut(&validator) {
474							Some(individual) => {
475								individual.saturating_accrue(points);
476								true
477							},
478							// The accounts of a service are a subset of the tally's, under the same
479							// bound.
480							None => by_service
481								.individual
482								.try_insert(validator, points)
483								.defensive()
484								.is_ok(),
485						};
486						if recorded {
487							by_service.total.saturating_accrue(points);
488						}
489					}
490				});
491			}
492			if !sum_weighted_points_delta.is_zero() {
493				ErasSumWeightedPoints::<T>::mutate(active_era.index, |sum| {
494					*sum = sum.saturating_add(sum_weighted_points_delta);
495				});
496			}
497		}
498	}
499
500	pub(crate) fn get_reward_points(era: EraIndex) -> EraRewardPoints<T> {
501		ErasRewardPoints::<T>::get(era)
502	}
503
504	pub(crate) fn get_total_reward_points_for_validator(
505		era: EraIndex,
506		validator: &T::AccountId,
507	) -> RewardPoint {
508		let points = ErasRewardPoints::<T>::get(era);
509		points.individual.get(validator).copied().unwrap_or_default()
510	}
511
512	/// The points of `validator` in `era` per service.
513	///
514	/// Points of the tally not recorded per service count as
515	/// [`ServiceKind::RelayConsensus`]: they are from before points were recorded per
516	/// service, when only the relay chain session report credited points.
517	pub(crate) fn get_reward_points_by_service_for_validator(
518		era: EraIndex,
519		validator: &T::AccountId,
520	) -> Vec<(ServiceKind, RewardPoint)> {
521		let tally = Self::get_total_reward_points_for_validator(era, validator);
522		// At most one entry per `ServiceKind`.
523		let mut points = ErasRewardPointsByService::<T>::iter_prefix(era)
524			.filter_map(|(service, points)| {
525				points.individual.get(validator).map(|points| (service, *points))
526			})
527			.collect::<Vec<_>>();
528		let recorded = points
529			.iter()
530			.fold(RewardPoint::zero(), |sum, (_, points)| sum.saturating_add(*points));
531		let unrecorded = tally.saturating_sub(recorded);
532		if !unrecorded.is_zero() {
533			match points.iter_mut().find(|(service, _)| *service == ServiceKind::RelayConsensus) {
534				Some((_, points)) => points.saturating_accrue(unrecorded),
535				None => points.push((ServiceKind::RelayConsensus, unrecorded)),
536			}
537		}
538		points
539	}
540
541	/// Whether era `era` uses the weighted-points incentive-share formula
542	/// `share_i = (w_i · ep_i) / Σ_j(w_j · ep_j)`.
543	///
544	/// Returns `true` for eras at or after [`crate::WeightedPointsFormulaStartEra`], and while
545	/// the cutoff is still unset before the migration records it.
546	///
547	/// Returns `false` for pre-cutoff eras, which fall back to the legacy stake-only share
548	/// `share_i = w_i / Σ_j w_j`. Those eras may have reward points credited before their
549	/// [`crate::ErasSumWeightedPoints`] denominator was maintained; recomputing it for the full
550	/// [`Config::HistoryDepth`] window on upgrade would cost `HistoryDepth × MaxValidatorSet`
551	/// reads, so the migration sets the cutoff to `active_era + 1` instead. See
552	/// [`crate::migrations::SetWeightedPointsFormulaStartEra`].
553	///
554	/// Single source of truth for the cutoff decision, shared by the payout path
555	/// ([`crate::Pallet::calculate_validator_incentive_for_page`]) and [`Self::do_try_state`].
556	pub(crate) fn uses_weighted_points(era: EraIndex) -> bool {
557		crate::WeightedPointsFormulaStartEra::<T>::get().map_or(true, |start| era >= start)
558	}
559}
560
561#[cfg(any(feature = "try-runtime", test, feature = "runtime-benchmarks"))]
562#[allow(unused)]
563impl<T: Config> Eras<T> {
564	/// Ensure the given era's data is fully present (all storage intact and not being pruned).
565	pub(crate) fn era_fully_present(era: EraIndex) -> Result<(), sp_runtime::TryRuntimeError> {
566		// these two are only set if we have some validators in an era.
567		let e0 = ErasValidatorPrefs::<T>::iter_prefix_values(era).count() != 0;
568		// note: we don't check `ErasStakersPaged` as a validator can have no backers.
569		let e1 = ErasStakersOverview::<T>::iter_prefix_values(era).count() != 0;
570		ensure!(e0 == e1, "ErasValidatorPrefs and ErasStakersOverview should be consistent");
571
572		// these two must always be set
573		let e2 = ErasTotalStake::<T>::contains_key(era);
574
575		let active_era = Rotator::<T>::active_era();
576		let e4 = if era.saturating_sub(1) > 0 &&
577			era.saturating_sub(1) > active_era.saturating_sub(T::HistoryDepth::get() + 1)
578		{
579			// `ErasValidatorReward` is set at active era n for era n-1, and is not set for era 0 in
580			// our tests. Moreover, it cannot be checked for presence in the oldest present era
581			// (`active_era.saturating_sub(1)`)
582			ErasValidatorReward::<T>::contains_key(era.saturating_sub(1))
583		} else {
584			// ignore
585			e2
586		};
587
588		ensure!(e2 == e4, "era info presence not consistent");
589
590		if e2 {
591			Ok(())
592		} else {
593			Err("era presence mismatch".into())
594		}
595	}
596
597	/// Check if the given era is currently being pruned.
598	pub(crate) fn era_pruning_in_progress(era: EraIndex) -> bool {
599		EraPruningState::<T>::contains_key(era)
600	}
601
602	/// Ensure the given era is either absent or currently being pruned.
603	pub(crate) fn era_absent_or_pruning(era: EraIndex) -> Result<(), sp_runtime::TryRuntimeError> {
604		if Self::era_pruning_in_progress(era) {
605			Ok(())
606		} else {
607			Self::era_absent(era)
608		}
609	}
610
611	/// Ensure the given era has indeed been already pruned. This is called by the main pallet in
612	/// do_prune_era_step.
613	pub(crate) fn era_absent(era: EraIndex) -> Result<(), sp_runtime::TryRuntimeError> {
614		// check double+ maps
615		let e0 = ErasValidatorPrefs::<T>::iter_prefix_values(era).count() != 0;
616		let e1 = ErasStakersPaged::<T>::iter_prefix_values((era,)).count() != 0;
617		let e2 = ErasStakersOverview::<T>::iter_prefix_values(era).count() != 0;
618
619		// check maps
620		// `ErasValidatorReward` is set at active era n for era n-1
621		let e3 = ErasValidatorReward::<T>::contains_key(era);
622		let e4 = ErasTotalStake::<T>::contains_key(era);
623
624		// these two are only populated conditionally, so we only check them for lack of existence
625		let e6 = ClaimedRewards::<T>::iter_prefix_values(era).count() != 0;
626		let e7 = ErasRewardPoints::<T>::contains_key(era);
627		let e8 = ErasRewardPointsByService::<T>::iter_prefix_values(era).count() != 0;
628
629		// Check if era info is consistent - if not, era is in partial pruning state
630		if !vec![e0, e1, e2, e3, e4, e6, e7, e8].windows(2).all(|w| w[0] == w[1]) {
631			return Err("era info absence not consistent - partial pruning state".into());
632		}
633
634		if !e0 {
635			Ok(())
636		} else {
637			Err("era absence mismatch".into())
638		}
639	}
640
641	pub(crate) fn do_try_state() -> Result<(), sp_runtime::TryRuntimeError> {
642		// pruning window works.
643		let active_era = Rotator::<T>::active_era();
644		// we max with 1 as in active era 0 we don't do an election and therefore we don't have some
645		// of the maps populated.
646		let oldest_present_era = active_era.saturating_sub(T::HistoryDepth::get()).max(1);
647
648		for e in oldest_present_era..=active_era {
649			Self::era_fully_present(e)?;
650			Self::check_validator_incentive_weight_consistency(e)?;
651			// Eras strictly older than the cutoff use the legacy stake-only formula and may not
652			// have `ErasSumWeightedPoints` populated, so skip the denominator consistency check.
653			// See
654			// [`crate::migrations::SetWeightedPointsFormulaStartEra`].
655			if Self::uses_weighted_points(e) {
656				Self::check_sum_weighted_points_consistency(e)?;
657			}
658			Self::check_reward_points_by_service_consistency(e)?;
659		}
660
661		// Ensure all eras older than oldest_present_era are either fully pruned or marked for
662		// pruning
663		ensure!(
664			(1..oldest_present_era).all(|e| Self::era_absent_or_pruning(e).is_ok()),
665			"All old eras must be either fully pruned or marked for pruning"
666		);
667
668		Ok(())
669	}
670
671	/// Verify that the sum of individual validator incentive weights matches the stored total.
672	fn check_validator_incentive_weight_consistency(
673		era: EraIndex,
674	) -> Result<(), sp_runtime::TryRuntimeError> {
675		use sp_runtime::traits::Zero;
676
677		let stored_total = ErasSumValidatorIncentiveWeight::<T>::get(era);
678		let computed_total: BalanceOf<T> = ErasValidatorIncentiveWeight::<T>::iter_prefix(era)
679			.fold(BalanceOf::<T>::zero(), |acc, (_, w)| acc.saturating_add(w));
680
681		ensure!(
682			stored_total == computed_total,
683			"ErasSumValidatorIncentiveWeight mismatch: \
684			 stored vs computed individual weights do not match"
685		);
686
687		Ok(())
688	}
689
690	/// Verify that the points of each service never exceed the tally in [`ErasRewardPoints`].
691	///
692	/// Only bounds are checked. The tally can hold points not recorded per service.
693	pub(crate) fn check_reward_points_by_service_consistency(
694		era: EraIndex,
695	) -> Result<(), sp_runtime::TryRuntimeError> {
696		let tally = ErasRewardPoints::<T>::get(era);
697		let mut sum_per_account = alloc::collections::BTreeMap::<T::AccountId, RewardPoint>::new();
698		let mut sum_of_totals: RewardPoint = 0;
699		for by_service in ErasRewardPointsByService::<T>::iter_prefix_values(era) {
700			let sum_of_individual = by_service
701				.individual
702				.values()
703				.fold(0 as RewardPoint, |acc, points| acc.saturating_add(*points));
704			ensure!(
705				by_service.total == sum_of_individual,
706				"the total of a service is not the sum of its entries"
707			);
708			sum_of_totals.saturating_accrue(by_service.total);
709			for (who, points) in by_service.individual {
710				ensure!(
711					tally.individual.contains_key(&who),
712					"an account has points of a service but none in the tally"
713				);
714				sum_per_account.entry(who).or_default().saturating_accrue(points);
715			}
716		}
717		ensure!(
718			sum_per_account
719				.iter()
720				.all(|(who, points)| tally.individual.get(who).is_some_and(|t| points <= t)),
721			"the points of an account per service exceed its points in the tally"
722		);
723		ensure!(sum_of_totals <= tally.total, "the points per service exceed the tally's total");
724		Ok(())
725	}
726
727	/// Verify that the incrementally maintained [`ErasSumWeightedPoints`] matches the
728	/// recomputed value `Σ_v(weight_v · ep_v)` from current storage.
729	fn check_sum_weighted_points_consistency(
730		era: EraIndex,
731	) -> Result<(), sp_runtime::TryRuntimeError> {
732		use sp_runtime::traits::Zero;
733
734		let stored = ErasSumWeightedPoints::<T>::get(era);
735		let reward_points = ErasRewardPoints::<T>::get(era);
736		let computed: BalanceOf<T> =
737			reward_points.individual.iter().fold(BalanceOf::<T>::zero(), |acc, (v, &ep)| {
738				let weight =
739					ErasValidatorIncentiveWeight::<T>::get(era, v).unwrap_or_else(Zero::zero);
740				acc.saturating_add(weight.saturating_mul(BalanceOf::<T>::from(ep)))
741			});
742
743		ensure!(
744			stored == computed,
745			"ErasSumWeightedPoints mismatch: \
746			 stored vs computed (Σ weight · era_points) do not match"
747		);
748
749		Ok(())
750	}
751}
752
753/// Manages session rotation logic.
754///
755/// This controls the following storage items in FULL, meaning that they should not be accessed
756/// directly from anywhere else in this pallet:
757///
758/// * `CurrentEra`: The current planning era
759/// * `ActiveEra`: The current active era
760/// * `BondedEras`: the list of ACTIVE eras and their session index
761pub struct Rotator<T: Config>(core::marker::PhantomData<T>);
762
763impl<T: Config> Rotator<T> {
764	#[cfg(feature = "runtime-benchmarks")]
765	pub(crate) fn legacy_insta_plan_era() -> Vec<T::AccountId> {
766		// Plan the era,
767		Self::plan_new_era();
768		// signal that we are about to call into elect asap.
769		<<T as Config>::ElectionProvider as ElectionProvider>::asap();
770		// immediately call into the election provider to fetch and process the results. We assume
771		// we are using an instant, onchain election here.
772		let msp = <T::ElectionProvider as ElectionProvider>::msp();
773		let lsp = 0;
774		for p in (lsp..=msp).rev() {
775			EraElectionPlanner::<T>::do_elect_paged(p);
776		}
777
778		let validators = crate::ElectableStashes::<T>::take().into_iter().collect::<Vec<_>>();
779		Self::keep_next_era_validators(Self::planned_era(), &validators);
780		validators
781	}
782
783	#[cfg(any(feature = "try-runtime", test))]
784	pub(crate) fn do_try_state() -> Result<(), sp_runtime::TryRuntimeError> {
785		// Check planned era vs active era relationship
786		let active_era = ActiveEra::<T>::get();
787		let planned_era = CurrentEra::<T>::get();
788
789		let bonded = BondedEras::<T>::get();
790
791		match (&active_era, &planned_era) {
792			(None, None) => {
793				// Uninitialized state - both should be None
794				ensure!(bonded.is_empty(), "BondedEras must be empty when ActiveEra is None");
795			},
796			(Some(active), Some(planned)) => {
797				// Normal state - planned can be at most one more than active
798				ensure!(
799					*planned == active.index || *planned == active.index + 1,
800					"planned era is always equal or one more than active"
801				);
802
803				// If we have an active era, bonded eras must always be the range
804				// [active - bonding_duration .. active_era]
805				let bonded_eras: Vec<_> = bonded.iter().map(|(era, _sess)| *era).collect();
806				ensure!(
807					bonded_eras ==
808						(active.index.saturating_sub(T::BondingDuration::get())..=active.index)
809							.collect::<Vec<_>>(),
810					"BondedEras range incorrect"
811				);
812
813				// ErasNominatorsSlashable entries are cleaned up via lazy pruning at HistoryDepth +
814				// 1. Entries can exist from [active - HistoryDepth, active] inclusive.
815				// Entries older than HistoryDepth should have been pruned (or be in the process of
816				// pruning).
817				let oldest_allowed_era = active.index.saturating_sub(T::HistoryDepth::get()).max(1);
818				for (era, _) in ErasNominatorsSlashable::<T>::iter() {
819					// Allow entries being pruned (EraPruningState exists)
820					let being_pruned = EraPruningState::<T>::contains_key(era);
821					ensure!(
822						(era >= oldest_allowed_era && era <= active.index) || being_pruned,
823						"ErasNominatorsSlashable entry exists for era outside history depth range and not being pruned"
824					);
825				}
826			},
827			_ => {
828				ensure!(false, "ActiveEra and CurrentEra must both be None or both be Some");
829			},
830		}
831
832		if let Some((kept_era, _)) = NextEraValidators::<T>::get() {
833			ensure!(
834				Self::is_planning() == Some(kept_era),
835				"kept validators exist only for an era that is planned and not yet active"
836			);
837		}
838
839		Ok(())
840	}
841
842	#[cfg(any(feature = "try-runtime", feature = "std", feature = "runtime-benchmarks", test))]
843	pub fn assert_election_ongoing() {
844		assert!(Self::is_planning().is_some(), "planning era must exist");
845		assert!(
846			T::ElectionProvider::status().is_ok(),
847			"Election provider must be in a good state during election"
848		);
849	}
850
851	/// Latest era that was planned.
852	///
853	/// The returned value does not necessarily indicate that planning for the era with this index
854	/// is underway, but rather the last era that was planned. If `Self::active_era()` is equal to
855	/// this value, it means that the era is currently active and no new era is planned.
856	///
857	/// See [`Self::is_planning()`] to only get the next index if planning in progress.
858	pub fn planned_era() -> EraIndex {
859		CurrentEra::<T>::get().unwrap_or(0)
860	}
861
862	pub fn active_era() -> EraIndex {
863		ActiveEra::<T>::get().map(|a| a.index).defensive_unwrap_or(0)
864	}
865
866	/// Next era that is planned to be started.
867	///
868	/// Returns None if no era is planned.
869	pub fn is_planning() -> Option<EraIndex> {
870		let (active, planned) = (Self::active_era(), Self::planned_era());
871		if planned.defensive_saturating_sub(active) > 1 {
872			defensive!("planned era must always be equal or one more than active");
873		}
874
875		(planned > active).then_some(planned)
876	}
877
878	/// End the session and start the next one.
879	pub(crate) fn end_session(
880		end_index: SessionIndex,
881		activation_timestamp: Option<(u64, u32)>,
882		rewarded_validators: u32,
883	) -> Weight {
884		// baseline weight for processing the relay chain session report
885		let mut weight = T::WeightInfo::rc_on_session_report(rewarded_validators);
886
887		let Some(active_era) = ActiveEra::<T>::get() else {
888			defensive!("Active era must always be available.");
889			return weight;
890		};
891		let current_planned_era = Self::is_planning();
892		let starting = end_index + 1;
893		// the session after the starting session.
894		let planning = starting + 1;
895
896		log!(
897			info,
898			"Session: end {:?}, start {:?} (ts: {:?}), planning {:?}",
899			end_index,
900			starting,
901			activation_timestamp,
902			planning
903		);
904		log!(info, "Era: active {:?}, planned {:?}", active_era.index, current_planned_era);
905
906		match activation_timestamp {
907			Some((time, id)) if Some(id) == current_planned_era => {
908				// We rotate the era if we have the activation timestamp.
909				weight.saturating_accrue(Self::start_era(active_era, starting, time));
910			},
911			Some((_time, id)) => {
912				// RC has done something wrong -- we received the wrong ID. Don't start a new era.
913				crate::log!(
914					warn,
915					"received wrong ID with activation timestamp. Got {}, expected {:?}",
916					id,
917					current_planned_era
918				);
919				Pallet::<T>::deposit_event(Event::Unexpected(
920					UnexpectedKind::UnknownValidatorActivation,
921				));
922			},
923			None => (),
924		}
925
926		// check if we should plan new era.
927		let should_plan_era = match ForceEra::<T>::get() {
928			// see if it's good time to plan a new era.
929			Forcing::NotForcing => Self::is_plan_era_deadline(starting),
930			// Force plan new era only once.
931			Forcing::ForceNew => {
932				ForceEra::<T>::put(Forcing::NotForcing);
933				true
934			},
935			// always plan the new era.
936			Forcing::ForceAlways => true,
937			// never force.
938			Forcing::ForceNone => false,
939		};
940
941		// Note: we call `planning_era` again, as a new era might have started since we checked
942		// it last.
943		let has_pending_era = Self::is_planning().is_some();
944		match (should_plan_era, has_pending_era) {
945			(false, _) => {
946				// nothing to consider
947			},
948			(true, false) => {
949				// happy path
950				Self::plan_new_era();
951			},
952			(true, true) => {
953				// we are waiting for to start the previously planned era, we cannot plan a new era
954				// now.
955				crate::log!(
956					debug,
957					"time to plan a new era {:?}, but waiting for the activation of the previous.",
958					current_planned_era
959				);
960			},
961		}
962
963		Pallet::<T>::deposit_event(Event::SessionRotated {
964			starting_session: starting,
965			active_era: Self::active_era(),
966			planned_era: Self::planned_era(),
967		});
968
969		weight
970	}
971
972	/// Returns the weight of notifying [`Config::OnEraStart`].
973	pub(crate) fn start_era(
974		ending_era: ActiveEraInfo,
975		starting_session: SessionIndex,
976		new_era_start_timestamp: u64,
977	) -> Weight {
978		// verify that a new era was planned
979		debug_assert!(CurrentEra::<T>::get().unwrap_or(0) == ending_era.index + 1);
980
981		let starting_era = ending_era.index + 1;
982
983		// finalize the ending era.
984		Self::end_era(&ending_era, new_era_start_timestamp);
985
986		// start the next era.
987		Self::start_era_inc_active_era(new_era_start_timestamp);
988		Self::start_era_update_bonded_eras(starting_era, starting_session);
989
990		// Snapshot the current nominators slashable setting for this era.
991		// Cleanup will happen via lazy pruning at HistoryDepth.
992		ErasNominatorsSlashable::<T>::insert(starting_era, AreNominatorsSlashable::<T>::get());
993
994		// cleanup election state
995		EraElectionPlanner::<T>::cleanup();
996
997		// Cleanup era pot accounts and mark for lazy pruning.
998		if let Some(old_era) = starting_era.checked_sub(T::HistoryDepth::get() + 1) {
999			reward::EraRewardManager::<T>::cleanup_era(old_era);
1000			log!(debug, "Marking era {:?} for lazy pruning", old_era);
1001			EraPruningState::<T>::insert(old_era, PruningStep::ErasStakersPaged);
1002		}
1003
1004		Self::notify_era_start(starting_era)
1005	}
1006
1007	/// Keep the validators elected for `era` when its election completes, for
1008	/// [`Self::notify_era_start`].
1009	///
1010	/// Costs one write of the set in the block that completes the election.
1011	pub(crate) fn keep_next_era_validators(era: EraIndex, validators: &[T::AccountId]) {
1012		if T::OnEraStart::enabled() {
1013			NextEraValidators::<T>::put((era, BoundedVec::truncate_from(validators.to_vec())));
1014		}
1015	}
1016
1017	/// Notify [`Config::OnEraStart`] with the validators of `era`, taking the copy kept by
1018	/// [`Self::keep_next_era_validators`].
1019	///
1020	/// Taking the copy is charged as one read and one write, with the copy's maximum size as
1021	/// proof size, whether or not the hook is enabled. Without a copy, as for an era whose
1022	/// election completed before the hook was enabled, the hook is not called for that era. With
1023	/// the hook disabled, a copy kept while it was enabled is removed and the hook is not called.
1024	fn notify_era_start(era: EraIndex) -> Weight {
1025		let kept = NextEraValidators::<T>::take();
1026		let take_weight = Self::take_kept_validators_weight();
1027		if !T::OnEraStart::enabled() {
1028			return take_weight;
1029		}
1030		match kept {
1031			Some((kept_era, validators)) if kept_era == era => {
1032				T::OnEraStart::on_era_start(era, &validators);
1033				take_weight.saturating_add(T::OnEraStart::weight(validators.len() as u32))
1034			},
1035			Some(_) => {
1036				defensive!("kept validators belong to another era");
1037				take_weight
1038			},
1039			None => {
1040				log!(warn, "no validators kept for era {:?}, the era-start hook is skipped", era);
1041				take_weight
1042			},
1043		}
1044	}
1045
1046	/// Worst-case weight of [`Self::notify_era_start`].
1047	pub(crate) fn notify_era_start_max_weight() -> Weight {
1048		let hook_weight = if T::OnEraStart::enabled() {
1049			T::OnEraStart::weight(T::MaxValidatorSet::get())
1050		} else {
1051			Weight::zero()
1052		};
1053		Self::take_kept_validators_weight().saturating_add(hook_weight)
1054	}
1055
1056	/// Weight of taking [`NextEraValidators`]: one read and one write, with its maximum encoded
1057	/// size as proof size.
1058	fn take_kept_validators_weight() -> Weight {
1059		let proof_size =
1060			<NextEraValidators<T> as frame_support::traits::StorageInfoTrait>::storage_info()
1061				.iter()
1062				.filter_map(|info| info.max_size)
1063				.map(u64::from)
1064				.sum();
1065		T::DbWeight::get()
1066			.reads_writes(1, 1)
1067			.saturating_add(Weight::from_parts(0, proof_size))
1068	}
1069
1070	fn start_era_inc_active_era(start_timestamp: u64) {
1071		ActiveEra::<T>::mutate(|active_era| {
1072			let new_index = active_era.as_ref().map(|info| info.index + 1).unwrap_or(0);
1073			log!(
1074				debug,
1075				"starting active era {:?} with RC-provided timestamp {:?}",
1076				new_index,
1077				start_timestamp
1078			);
1079			*active_era = Some(ActiveEraInfo { index: new_index, start: Some(start_timestamp) });
1080		});
1081	}
1082
1083	/// The session index of the current active era.
1084	///
1085	/// This must always exist in the `BondedEras` storage item, ergo the function is infallible.
1086	pub fn active_era_start_session_index() -> SessionIndex {
1087		Self::era_start_session_index(Self::active_era()).defensive_unwrap_or(0)
1088	}
1089
1090	/// The session index of a given era.
1091	pub fn era_start_session_index(era: EraIndex) -> Option<SessionIndex> {
1092		BondedEras::<T>::get()
1093			.into_iter()
1094			.rev()
1095			.find_map(|(e, s)| if e == era { Some(s) } else { None })
1096	}
1097
1098	fn start_era_update_bonded_eras(starting_era: EraIndex, start_session: SessionIndex) {
1099		let bonding_duration = T::BondingDuration::get();
1100
1101		BondedEras::<T>::mutate(|bonded| {
1102			if bonded.is_full() {
1103				// remove oldest
1104				let (era_removed, _) = bonded.remove(0);
1105				debug_assert!(
1106					era_removed <= (starting_era.saturating_sub(bonding_duration)),
1107					"should not delete an era that is not older than bonding duration"
1108				);
1109			}
1110
1111			// must work -- we were not full, or just removed the oldest era.
1112			let _ = bonded.try_push((starting_era, start_session)).defensive();
1113		});
1114	}
1115
1116	fn end_era(ending_era: &ActiveEraInfo, new_era_start: u64) {
1117		if T::DisableMinting::get() {
1118			Self::end_era_dap(ending_era);
1119		} else {
1120			Self::end_era_legacy(ending_era, new_era_start);
1121		}
1122	}
1123
1124	/// Legacy end-era: compute inflation via `EraPayout`, mint, send remainder.
1125	fn end_era_legacy(ending_era: &ActiveEraInfo, new_era_start: u64) {
1126		let previous_era_start = ending_era.start.defensive_unwrap_or(new_era_start);
1127		let era_duration = new_era_start.saturating_sub(previous_era_start);
1128
1129		let cap = T::MaxEraDuration::get();
1130		let era_duration = if cap == 0 || era_duration <= cap {
1131			era_duration
1132		} else {
1133			Pallet::<T>::deposit_event(Event::Unexpected(UnexpectedKind::EraDurationBoundExceeded));
1134			log!(
1135				warn,
1136				"capping era duration for era {:?} from {:?} to max {:?}",
1137				ending_era.index,
1138				era_duration,
1139				cap
1140			);
1141			cap
1142		};
1143
1144		let staked = ErasTotalStake::<T>::get(ending_era.index);
1145		let issuance = asset::total_issuance::<T>();
1146		let (validator_payout, remainder) =
1147			T::EraPayout::era_payout(staked, issuance, era_duration);
1148
1149		let total_payout = validator_payout.saturating_add(remainder);
1150		let max_staked_rewards = MaxStakedRewards::<T>::get().unwrap_or(Percent::from_percent(100));
1151
1152		let validator_payout = validator_payout.min(max_staked_rewards * total_payout);
1153		let remainder = total_payout.saturating_sub(validator_payout);
1154
1155		Pallet::<T>::deposit_event(Event::<T>::EraPaid {
1156			era_index: ending_era.index,
1157			validator_payout,
1158			remainder,
1159		});
1160
1161		Eras::<T>::set_stakers_reward(ending_era.index, validator_payout);
1162		T::RewardRemainder::on_unbalanced(asset::issue::<T>(remainder));
1163	}
1164
1165	/// DAP end-era: snapshot from general reward pots into era-specific pots.
1166	///
1167	/// The snapshotted amounts are stored in `ErasValidatorReward` (staker rewards) and
1168	/// `ErasValidatorIncentiveBudget` (incentive). Individual payouts draw from the era pots.
1169	fn end_era_dap(ending_era: &ActiveEraInfo) {
1170		let allocation = reward::EraRewardManager::<T>::snapshot_era_rewards(ending_era.index);
1171
1172		if allocation.staker_rewards.is_zero() {
1173			log!(warn, "Era {:?} has zero staker rewards in general pot", ending_era.index);
1174		}
1175
1176		Eras::<T>::set_stakers_reward(ending_era.index, allocation.staker_rewards);
1177		Eras::<T>::set_validator_incentive_budget(ending_era.index, allocation.validator_incentive);
1178
1179		// Include both staker rewards and validator incentive in the event
1180		Pallet::<T>::deposit_event(Event::<T>::EraPaid {
1181			era_index: ending_era.index,
1182			validator_payout: allocation
1183				.staker_rewards
1184				.saturating_add(allocation.validator_incentive),
1185			remainder: Zero::zero(),
1186		});
1187
1188		if DisableMintingGuard::<T>::get().is_none() {
1189			DisableMintingGuard::<T>::put(ending_era.index);
1190		}
1191	}
1192
1193	/// Plans a new era by kicking off the election process.
1194	///
1195	/// The newly planned era is targeted to activate in the next session.
1196	fn plan_new_era() {
1197		let _ = CurrentEra::<T>::try_mutate(|x| {
1198			log!(info, "Planning new era: {:?}, sending election start signal", x.unwrap_or(0));
1199			let could_start_election = EraElectionPlanner::<T>::plan_new_election();
1200			*x = Some(x.unwrap_or(0) + 1);
1201			could_start_election
1202		});
1203	}
1204
1205	/// Returns whether we are at the session where we should plan the new era.
1206	fn is_plan_era_deadline(start_session: SessionIndex) -> bool {
1207		let planning_era_offset = T::PlanningEraOffset::get().min(T::SessionsPerEra::get());
1208		// session at which we should plan the new era.
1209		let target_plan_era_session = T::SessionsPerEra::get().saturating_sub(planning_era_offset);
1210		let era_start_session = Self::active_era_start_session_index();
1211
1212		// progress of the active era in sessions.
1213		let session_progress = start_session.defensive_saturating_sub(era_start_session);
1214
1215		log!(
1216			debug,
1217			"Session progress within era: {:?}, target_plan_era_session: {:?}",
1218			session_progress,
1219			target_plan_era_session
1220		);
1221		session_progress >= target_plan_era_session
1222	}
1223}
1224
1225/// Manager type which collects the election results from [`Config::ElectionProvider`] and
1226/// finalizes the planning of a new era.
1227///
1228/// This type managed 3 storage items:
1229///
1230/// * [`crate::VoterSnapshotStatus`]
1231/// * [`crate::NextElectionPage`]
1232/// * [`crate::ElectableStashes`]
1233///
1234/// A new election is fetched over multiple pages, and finalized upon fetching the last page.
1235///
1236/// * The intermediate state of fetching the election result is kept in [`NextElectionPage`]. If
1237///   `Some(_)` something is ongoing, otherwise not.
1238/// * We fully trust [`Config::ElectionProvider`] to give us a full set of validators, with enough
1239///   backing after all calls to `maybe_fetch_election_results` are done. Note that older versions
1240///   of this pallet had a `MinimumValidatorCount` to double-check this, but we don't check it
1241///   anymore.
1242/// * `maybe_fetch_election_results` returns a tuple of `(weight, closure)`. The `weight` is the
1243///   worst-case weight that `exec` might consume. The caller should check if `weight` fits within
1244///   the boundaries of that context, and execute `closure` if so.
1245///
1246/// TODOs:
1247///
1248/// * Add a try-state check based on the 3 storage items
1249/// * Move snapshot creation functions here as well.
1250pub(crate) struct EraElectionPlanner<T: Config>(PhantomData<T>);
1251impl<T: Config> EraElectionPlanner<T> {
1252	/// Cleanup all associated storage items.
1253	pub(crate) fn cleanup() {
1254		VoterSnapshotStatus::<T>::kill();
1255		NextElectionPage::<T>::kill();
1256		ElectableStashes::<T>::kill();
1257		Pallet::<T>::register_weight(T::DbWeight::get().writes(3));
1258	}
1259
1260	/// Fetches the number of pages configured by the election provider.
1261	pub(crate) fn election_pages() -> u32 {
1262		<<T as Config>::ElectionProvider as ElectionProvider>::Pages::get()
1263	}
1264
1265	/// Plan a new election
1266	pub(crate) fn plan_new_election() -> Result<(), <T::ElectionProvider as ElectionProvider>::Error>
1267	{
1268		T::ElectionProvider::start()
1269			.inspect_err(|e| log!(warn, "Election provider failed to start: {:?}", e))
1270	}
1271
1272	pub(crate) fn maybe_fetch_election_results() -> (Weight, Box<dyn Fn(&mut WeightMeter)>) {
1273		let Ok(Some(mut required_weight)) = T::ElectionProvider::status() else {
1274			// no election ongoing
1275			let weight = T::DbWeight::get().reads(1);
1276			return (weight, Box::new(move |meter: &mut WeightMeter| meter.consume(weight)));
1277		};
1278
1279		// Add a few things to the required weights that are not captured in `do_elect_paged`, which
1280		// is benchmarked via `fetch_page`.
1281		// * 1 extra read and write for `NextElectionPage`
1282		// * 1 extra write for `RcClientInterface::validator_set` (implementation leak -- we assume
1283		//   that we know this writes one storage item under the hood)
1284		// * 1 extra read for `CurrentEra`
1285		// * 1 extra read for `BondedEras` in `get_prune_up_to`
1286		// * 1 extra write for `NextEraValidators`, if `OnEraStart` is enabled
1287		// ElectableStashes already read in `do_elect_paged`
1288		required_weight.saturating_accrue(T::DbWeight::get().reads_writes(3, 2));
1289		if T::OnEraStart::enabled() {
1290			required_weight.saturating_accrue(T::DbWeight::get().writes(1));
1291		}
1292
1293		let exec = Box::new(move |meter: &mut WeightMeter| {
1294			crate::log!(
1295				debug,
1296				"Election provider is ready, our status is {:?}",
1297				NextElectionPage::<T>::get()
1298			);
1299
1300			debug_assert!(
1301				CurrentEra::<T>::get().unwrap_or(0) ==
1302					ActiveEra::<T>::get().map_or(0, |a| a.index) + 1,
1303				"Next era must be already planned."
1304			);
1305
1306			let current_page = NextElectionPage::<T>::get()
1307				.unwrap_or(Self::election_pages().defensive_saturating_sub(1));
1308			let maybe_next_page = current_page.checked_sub(1);
1309			crate::log!(debug, "fetching page {:?}, next {:?}", current_page, maybe_next_page);
1310
1311			Self::do_elect_paged(current_page);
1312			NextElectionPage::<T>::set(maybe_next_page);
1313
1314			if maybe_next_page.is_none() {
1315				let id = CurrentEra::<T>::get().defensive_unwrap_or(0);
1316				let prune_up_to = Self::get_prune_up_to();
1317				let rc_validators = ElectableStashes::<T>::take().into_iter().collect::<Vec<_>>();
1318				Rotator::<T>::keep_next_era_validators(id, &rc_validators);
1319
1320				crate::log!(
1321					info,
1322					"Sending new validator set of size {:?} to RC. ID: {:?}, prune_up_to: {:?}",
1323					rc_validators.len(),
1324					id,
1325					prune_up_to
1326				);
1327				T::RcClientInterface::validator_set(rc_validators, id, prune_up_to);
1328			}
1329
1330			// consume the reported worst case weight.
1331			meter.consume(required_weight)
1332		});
1333
1334		(required_weight, exec)
1335	}
1336
1337	/// Get the right value of the first session that needs to be pruned on the RC's historical
1338	/// session pallet.
1339	fn get_prune_up_to() -> Option<SessionIndex> {
1340		let bonded_eras = BondedEras::<T>::get();
1341
1342		// get the first session of the oldest era in the bonded eras.
1343		if bonded_eras.is_full() {
1344			bonded_eras.first().map(|(_, first_session)| first_session.saturating_sub(1))
1345		} else {
1346			None
1347		}
1348	}
1349
1350	/// Paginated elect.
1351	///
1352	/// Fetches the election page with index `page` from the election provider.
1353	///
1354	/// The results from the elect call should be stored in the `ElectableStashes` storage. In
1355	/// addition, it stores stakers' information for next planned era based on the paged
1356	/// solution data returned.
1357	///
1358	/// If any new election winner does not fit in the electable stashes storage, it truncates
1359	/// the result of the election. We ensure that only the winners that are part of the
1360	/// electable stashes have exposures collected for the next era.
1361	pub(crate) fn do_elect_paged(page: PageIndex) {
1362		let election_result = T::ElectionProvider::elect(page);
1363		match election_result {
1364			Ok(supports) => {
1365				let inner_processing_results = Self::do_elect_paged_inner(supports);
1366				if let Err(not_included) = inner_processing_results {
1367					defensive!(
1368						"electable stashes exceeded limit, unexpected but election proceeds.\
1369                		{} stashes from election result discarded",
1370						not_included
1371					);
1372				};
1373
1374				Pallet::<T>::deposit_event(Event::PagedElectionProceeded {
1375					page,
1376					result: inner_processing_results.map(|x| x as u32).map_err(|x| x as u32),
1377				});
1378			},
1379			Err(e) => {
1380				log!(warn, "election provider page failed due to {:?} (page: {})", e, page);
1381				Pallet::<T>::deposit_event(Event::PagedElectionProceeded { page, result: Err(0) });
1382			},
1383		}
1384	}
1385
1386	/// Inner implementation of [`Self::do_elect_paged`].
1387	///
1388	/// Returns an error if adding election winners to the electable stashes storage fails due
1389	/// to exceeded bounds. In case of error, it returns the index of the first stash that
1390	/// failed to be included.
1391	pub(crate) fn do_elect_paged_inner(
1392		mut supports: BoundedSupportsOf<T::ElectionProvider>,
1393	) -> Result<usize, usize> {
1394		let planning_era = Rotator::<T>::planned_era();
1395
1396		match Self::add_electables(supports.iter().map(|(s, _)| s.clone())) {
1397			Ok(added) => {
1398				let exposures = Self::collect_exposures(supports);
1399				let _ = Self::store_stakers_info(exposures, planning_era);
1400				Ok(added)
1401			},
1402			Err(not_included_idx) => {
1403				let not_included = supports.len().saturating_sub(not_included_idx);
1404
1405				log!(
1406					warn,
1407					"not all winners fit within the electable stashes, excluding {:?} accounts from solution.",
1408					not_included,
1409				);
1410
1411				// filter out supports of stashes that do not fit within the electable stashes
1412				// storage bounds to prevent collecting their exposures.
1413				supports.truncate(not_included_idx);
1414				let exposures = Self::collect_exposures(supports);
1415				let _ = Self::store_stakers_info(exposures, planning_era);
1416
1417				Err(not_included)
1418			},
1419		}
1420	}
1421
1422	/// Process the output of a paged election.
1423	///
1424	/// Store staking information for the new planned era of a single election page.
1425	pub(crate) fn store_stakers_info(
1426		exposures: BoundedExposuresOf<T>,
1427		new_planned_era: EraIndex,
1428	) -> BoundedVec<T::AccountId, MaxWinnersPerPageOf<T::ElectionProvider>> {
1429		// populate elected stash, stakers, exposures, and the snapshot of validator prefs.
1430		let mut total_stake_page: BalanceOf<T> = Zero::zero();
1431		let mut elected_stashes_page = Vec::with_capacity(exposures.len());
1432		let mut total_backers = 0u32;
1433
1434		let mut total_incentive_weight_page: BalanceOf<T> = Zero::zero();
1435
1436		exposures.into_iter().for_each(|(stash, exposure)| {
1437			log!(
1438				trace,
1439				"storing exposure for stash {:?} with {:?} own-stake and {:?} backers",
1440				stash,
1441				exposure.own,
1442				exposure.others.len()
1443			);
1444			// build elected stash.
1445			elected_stashes_page.push(stash.clone());
1446			// accumulate total stake and backer count for bookkeeping.
1447			total_stake_page = total_stake_page.saturating_add(exposure.total);
1448			total_backers += exposure.others.len() as u32;
1449			let own = exposure.own;
1450			Eras::<T>::upsert_exposure(new_planned_era, &stash, exposure);
1451
1452			// Calculate incentive weight from own-stake. Own-stake appears only on the
1453			// first page of a multi-page exposure, so if the key already exists with a
1454			// non-zero own, something is wrong upstream.
1455			if !own.is_zero() {
1456				if ErasValidatorIncentiveWeight::<T>::contains_key(new_planned_era, &stash) {
1457					defensive!(
1458						"validator own-stake seen twice in the same era across election pages"
1459					);
1460				} else {
1461					let incentive_weight =
1462						T::StakerRewardCalculator::calculate_validator_incentive_weight(own);
1463					if !incentive_weight.is_zero() {
1464						total_incentive_weight_page =
1465							total_incentive_weight_page.saturating_add(incentive_weight);
1466						ErasValidatorIncentiveWeight::<T>::insert(
1467							new_planned_era,
1468							&stash,
1469							incentive_weight,
1470						);
1471					}
1472				}
1473			}
1474		});
1475
1476		let elected_stashes: BoundedVec<_, MaxWinnersPerPageOf<T::ElectionProvider>> =
1477			elected_stashes_page
1478				.try_into()
1479				.expect("both types are bounded by MaxWinnersPerPageOf; qed");
1480
1481		// adds to total stake in this era.
1482		Eras::<T>::add_total_stake(new_planned_era, total_stake_page);
1483
1484		// adds to total validator self-stake weight for incentive distribution.
1485		Eras::<T>::add_sum_validator_incentive_weight(new_planned_era, total_incentive_weight_page);
1486
1487		// collect or update the pref of all winners.
1488		// TODO: rather inefficient, we can do this once at the last page across all entries in
1489		// `ElectableStashes`.
1490		for stash in &elected_stashes {
1491			let pref = Validators::<T>::get(stash);
1492			Eras::<T>::set_validator_prefs(new_planned_era, stash, pref);
1493		}
1494
1495		log!(
1496			debug,
1497			"stored a page of stakers with {:?} validators and {:?} total backers for era {:?}",
1498			elected_stashes.len(),
1499			total_backers,
1500			new_planned_era,
1501		);
1502
1503		elected_stashes
1504	}
1505
1506	/// Consume a set of [`BoundedSupports`] from [`sp_npos_elections`] and collect them into a
1507	/// [`Exposure`].
1508	///
1509	/// Returns vec of all the exposures of a validator in `paged_supports`, bounded by the
1510	/// number of max winners per page returned by the election provider.
1511	fn collect_exposures(
1512		supports: BoundedSupportsOf<T::ElectionProvider>,
1513	) -> BoundedExposuresOf<T> {
1514		let total_issuance = asset::total_issuance::<T>();
1515		let to_currency = |e: frame_election_provider_support::ExtendedBalance| {
1516			T::CurrencyToVote::to_currency(e, total_issuance)
1517		};
1518
1519		supports
1520			.into_iter()
1521			.map(|(validator, support)| {
1522				// Build `struct exposure` from `support`.
1523				let mut others = Vec::with_capacity(support.voters.len());
1524				let mut own: BalanceOf<T> = Zero::zero();
1525				let mut total: BalanceOf<T> = Zero::zero();
1526				support
1527					.voters
1528					.into_iter()
1529					.map(|(nominator, weight)| (nominator, to_currency(weight)))
1530					.for_each(|(nominator, stake)| {
1531						if nominator == validator {
1532							defensive_assert!(own == Zero::zero(), "own stake should be unique");
1533							own = own.saturating_add(stake);
1534						} else {
1535							others.push(IndividualExposure { who: nominator, value: stake });
1536						}
1537						total = total.saturating_add(stake);
1538					});
1539
1540				let exposure = Exposure { own, others, total };
1541				(validator, exposure)
1542			})
1543			.try_collect()
1544			.expect("we only map through support vector which cannot change the size; qed")
1545	}
1546
1547	/// Adds a new set of stashes to the electable stashes.
1548	///
1549	/// Returns:
1550	///
1551	/// `Ok(newly_added)` if all stashes were added successfully.
1552	/// `Err(first_un_included)` if some stashes cannot be added due to bounds.
1553	pub(crate) fn add_electables(
1554		new_stashes: impl Iterator<Item = T::AccountId>,
1555	) -> Result<usize, usize> {
1556		ElectableStashes::<T>::mutate(|electable| {
1557			let pre_size = electable.len();
1558
1559			for (idx, stash) in new_stashes.enumerate() {
1560				if electable.try_insert(stash).is_err() {
1561					return Err(idx);
1562				}
1563			}
1564
1565			Ok(electable.len() - pre_size)
1566		})
1567	}
1568}