referrerpolicy=no-referrer-when-downgrade

pallet_validator_collators/
lib.rs

1// Copyright (C) Parity Technologies (UK) Ltd.
2// SPDX-License-Identifier: Apache-2.0
3
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8// 	http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15
16//! Validator Collators pallet.
17//!
18//! Stores the validator set announced by the chain that runs `pallet-staking-async`, typically
19//! Asset Hub, and offers it as a session manager, so the relay-chain validators of the current era
20//! collate on a system parachain.
21//!
22//! ## Overview
23//!
24//! The announcing chain sends the active validator set of each era, tagged with the era index of
25//! `pallet-staking-async`.
26//! This pallet stores the latest set, received through `set_validators` from [`Config::SetOrigin`]
27//! or from another pallet through [`Pallet::receive_validator_set`]. It rejects a set whose era
28//! is not newer than the stored one, or that has more validators than [`Config::MaxValidators`].
29//!
30//! The pallet is a [`pallet_session::SessionManager`]. At every session rotation it returns the
31//! stored validators that have registered local session keys, checked with
32//! [`Config::ValidatorRegistration`], and records the returned list in [`DrawnCollators`]. The
33//! runtime may combine this pallet with `pallet-collator-selection` through
34//! [`pallet_session::UnionSessionManager`], so invulnerables and candidates keep collating next to
35//! the validators.
36//!
37//! [`MaxCollators`] optionally caps how many validators are returned. Governance can start with a
38//! low cap and raise it in steps, or lower it again, to roll out validator collators gradually.
39//! The pallet draws the validators at random at the first forced rotation after a set
40//! arrives or the cap changes, and returns them until the next draw. The draw shuffles the whole
41//! set with a seed made of the genesis hash, the era and the relay chain epoch randomness cached in
42//! [`EpochRandomness`], then keeps the first validators with registered keys up to the cap. Every
43//! validator with keys has the same chance to be drawn in each era. A cap change draws again from
44//! the stored set, so the drawn validators can change. Every draw takes its seed from the
45//! randomness cached at the time of the draw. The seed includes the genesis hash, so each chain
46//! draws independently from the same set. A drawn validator that removes its keys is dropped at
47//! the next rotation and its place stays empty, and a validator that registers keys after the draw
48//! waits, until the next set or cap change. Each set, so each era, gets a new draw, which is
49//! enacted at the second forced rotation with no notice, so a validator with keys must already
50//! run a synced collator node to collate when drawn.
51//!
52//! Until governance sets it, the cap is [`Config::DefaultMaxCollators`].
53//!
54//! The pallet implements [`cumulus_pallet_parachain_system::OnSystemEvent`]. The runtime must
55//! include it in the `OnSystemEvent` of `cumulus-pallet-parachain-system`, alone or in a tuple
56//! with other handlers, to keep [`EpochRandomness`] up to date from the relay chain state proof.
57//! The runtime should also return the keys of [`Pallet::relay_keys_to_prove`] from
58//! [`KeyToIncludeInRelayProof`](cumulus_primitives_core::KeyToIncludeInRelayProof), so collators
59//! include the randomness key in the proof.
60//! The draw runs in the session rotation, before the block's own proof is processed, so it uses
61//! the value cached by the previous block.
62//! A block whose proof lacks the trie nodes of the randomness key, or holds a value that does not
63//! decode, is invalid. A proof that shows the key absent, as before the relay chain's first epoch
64//! change, caches the zero value a draw without randomness uses.
65//! Without the `OnSystemEvent` wiring, every draw uses a zero randomness value and logs an error.
66//!
67//! The stored set is the one staking elected for the era. The relay chain enacts only the elected
68//! validators with relay-chain session keys, and each system chain returns only those with keys
69//! registered there, so a returned collator is not necessarily an active relay-chain validator.
70//!
71//! The pallet is also a [`pallet_session::ShouldEndSession`]. Pallet-session queues a new set at
72//! one rotation and enacts it at the next. When a set arrives, or the cap changes while a set is
73//! stored, the pallet forces two rotations in the following two blocks, so the change is in force
74//! without waiting for the regular period. The regular rotations given by
75//! [`Config::PeriodicSession`] continue as before.
76//!
77//! The returned validators author blocks like any collator, so a `pallet-collator-selection` event
78//! handler pays them from its pot and records them in `LastAuthoredBlock`.
79//!
80//! The pallet is also a `pallet_authorship::EventHandler` and counts the blocks each author
81//! produces in [`AuthoredBlocks`]. At a report-time, it removes the counts of the authors outside
82//! the stored set, and hands the counts of the others to [`Config::BlockReporter`] in one call. The
83//! reporter delivers them to the chain that runs `pallet-staking-async` + `points-convertor`, where
84//! they become era points. A report has at most one entry per validator of the stored set, and the
85//! pallet's `integrity_test` checks that [`Config::MaxValidators`] entries fit the reporter's
86//! [`ReportAuthoredBlocks::max_message_size`], so a full report is never too large to send and is
87//! not split. If the reporter rejects it, the counts of ONLY the _currently stored validators_ are
88//! kept for the next report, so [`AuthoredBlocks`] never holds more than the stored set plus the
89//! authors since the last report. Without a stored set every count is dropped.
90//!
91//! A report runs in every block whose number is a multiple of [`ReportPeriod`], and once per
92//! stored set shortly before the expected end of its era. The pallet records the arrival time of
93//! each set in [`ExternalSetReceivedAt`], from [`Config::UnixTime`], and expects the era to end
94//! [`ExpectedEraDuration`] after it. The early report runs in the first block at or after
95//! [`ReportMargin`] before that end, so that in a normal era the counts reach the chain that runs
96//! `pallet-staking-async` before the era rotates. The margin used is at most
97//! [`Config::MaxReportMargin`] and at most half of [`ExpectedEraDuration`]. The early report
98//! removes [`ExternalSetReceivedAt`] and is not retried: if the reporter rejects it, its counts go
99//! out with the next [`ReportPeriod`] report. The periodic report also covers eras that end earlier
100//! or later than expected, a set that never arrives, and the time before the first set arrives. If
101//! both reports fall in the same block, the pallet reports once.
102//!
103//! A runtime must configure `pallet-collator-selection`'s `KickThreshold` to exceed a full Aura
104//! round of the merged list, [`Config::MaxValidators`] plus the invulnerables and candidates, times
105//! the blocks the chain produces per Aura slot. Otherwise bonded candidates are kicked as stale
106//! between their slots. [`Config::MaxValidators`] rather than the cap is the bound, since the cap
107//! can be raised or removed without a runtime upgrade.
108//!
109//! ## TODO
110//!
111//! - Dropping validators that author no blocks for a session, judged among the drawn validators
112//!   under a cap.
113//! - (Only if a need is established) Propagating relay-chain offences to the collator set.
114//! - Under a cap, revisit the redraw period and notice once operators have run collators. A draw
115//!   per era without notice is the first step, with operators expected to run a synced collator
116//!   node all the time. Options: redraw every few eras or sessions, keep a drawn validator for
117//!   several eras while it stays in the active set, and announce the drawn validators before they
118//!   collate so they can sync a node. Open points: the time a node needs to sync, and refilling the
119//!   place of a drawn validator that leaves the active set, which needs notice too.
120
121#![cfg_attr(not(feature = "std"), no_std)]
122
123extern crate alloc;
124
125pub use pallet::*;
126
127#[cfg(test)]
128mod mock;
129
130#[cfg(test)]
131mod tests;
132
133#[cfg(feature = "runtime-benchmarks")]
134mod benchmarking;
135pub mod migrations;
136#[cfg(any(test, feature = "runtime-benchmarks"))]
137mod relay_proof;
138pub mod weights;
139
140const LOG_TARGET: &str = "runtime::validator-collators";
141
142/// Delivers the block counts of one report.
143pub trait ReportAuthoredBlocks<AccountId> {
144	/// Hand over the number of blocks each account authored.
145	///
146	/// `Ok` means the counts were accepted for delivery or credited, not that a remote chain
147	/// applied them.
148	#[allow(clippy::result_unit_err)]
149	fn report(blocks: &[(AccountId, u32)]) -> Result<(), ()>;
150
151	/// The encoded size of what [`Self::report`] sends for `blocks`.
152	///
153	/// By default the encoded `blocks`, as if the transport added nothing: an XCM envelope adds a
154	/// few bytes. Checked against [`Self::max_message_size`] in the pallet's `integrity_test`.
155	#[cfg(feature = "std")]
156	fn message_size(blocks: &[(AccountId, u32)]) -> usize
157	where
158		AccountId: codec::Encode,
159	{
160		codec::Encode::encoded_size(blocks)
161	}
162
163	/// The largest message the transport accepts, `None` without a limit, as for a local credit.
164	#[cfg(feature = "std")]
165	fn max_message_size() -> Option<usize> {
166		None
167	}
168
169	/// Prepare the runtime so that [`Self::report`] succeeds for `blocks` in benchmarks.
170	#[cfg(feature = "runtime-benchmarks")]
171	fn ensure_successful_report(_blocks: &[(AccountId, u32)]) {}
172}
173
174/// Discards the counts.
175impl<AccountId> ReportAuthoredBlocks<AccountId> for () {
176	fn report(_: &[(AccountId, u32)]) -> Result<(), ()> {
177		Ok(())
178	}
179}
180
181#[frame_support::pallet]
182pub mod pallet {
183	pub use crate::weights::WeightInfo;
184	use crate::ReportAuthoredBlocks;
185	use alloc::{collections::BTreeSet, vec, vec::Vec};
186	use cumulus_pallet_parachain_system::{
187		relay_state_snapshot::{Error as RelayProofError, ReadEntryErr},
188		OnSystemEvent, RelayChainStateProof,
189	};
190	use cumulus_primitives_core::{
191		relay_chain::well_known_keys, PersistedValidationData, RelayStorageKey,
192	};
193	use frame_support::{
194		dispatch::DispatchClass,
195		pallet_prelude::*,
196		storage::with_storage_layer,
197		traits::{EnsureOrigin, UnixTime, ValidatorRegistration},
198		weights::WeightMeter,
199		BoundedBTreeSet,
200	};
201	use frame_system::pallet_prelude::*;
202	use pallet_session::{SessionManager, ShouldEndSession};
203	use rand::{seq::SliceRandom, SeedableRng};
204	use rand_chacha::ChaCha20Rng;
205	use sp_runtime::{
206		traits::{BlakeTwo256, Hash, Saturating, Zero},
207		SaturatedConversion,
208	};
209	use sp_staking::{EraIndex, SessionIndex};
210
211	/// A validator set received for an era.
212	#[frame_support::stored]
213	pub struct EraValidatorSet<AccountId, MaxValidators: Get<u32>> {
214		/// The era the set belongs to.
215		pub era: EraIndex,
216		/// The validator stashes of that era.
217		pub validators: BoundedBTreeSet<AccountId, MaxValidators>,
218	}
219
220	/// The collators returned for a session from the validator set of `era`.
221	///
222	/// Always a subset of the [`EraValidatorSet`] of the same `era`, which need not be the one in
223	/// [`ExternalValidatorSet`] any more.
224	#[frame_support::stored]
225	pub struct EraCollators<AccountId, MaxValidators: Get<u32>> {
226		/// The era of the set the collators were taken from.
227		pub era: EraIndex,
228		/// The collators, in drawn order.
229		pub collators: BoundedVec<AccountId, MaxValidators>,
230	}
231
232	/// How many validators of the stored set are drawn as collators.
233	#[frame_support::stored]
234	#[derive(Copy)]
235	pub enum CollatorDraw {
236		/// Every validator with registered keys.
237		#[codec(index = 0)]
238		All,
239		/// Up to this many validators with registered keys.
240		#[codec(index = 1)]
241		UpTo(u32),
242		/// No validator.
243		#[codec(index = 2)]
244		None,
245	}
246
247	impl CollatorDraw {
248		/// The largest number of validators drawn.
249		pub fn limit(self) -> u32 {
250			match self {
251				Self::None => 0,
252				Self::UpTo(max) => max,
253				Self::All => u32::MAX,
254			}
255		}
256	}
257
258	/// Progress of the two rotations that bring a received set into force.
259	#[derive(
260		Clone, Copy, Eq, PartialEq, Default, Encode, Decode, Debug, TypeInfo, MaxEncodedLen,
261	)]
262	pub enum RotationState {
263		/// No forced rotation is pending.
264		#[default]
265		Idle,
266		/// A set was received and the next rotation queues it.
267		AwaitingQueue,
268		/// The set is queued and the next rotation enacts it.
269		AwaitingEnactment,
270	}
271
272	#[pallet::pallet]
273	#[pallet::storage_version(crate::migrations::STORAGE_VERSION)]
274	pub struct Pallet<T>(_);
275
276	/// Configuration trait of this pallet.
277	#[pallet::config]
278	pub trait Config: frame_system::Config<RuntimeEvent: From<Event<Self>>> {
279		/// Origin allowed to submit a validator set.
280		type SetOrigin: EnsureOrigin<Self::RuntimeOrigin>;
281
282		/// Origin allowed to change [`MaxCollators`], [`ReportPeriod`], [`ExpectedEraDuration`]
283		/// and [`ReportMargin`].
284		type UpdateOrigin: EnsureOrigin<Self::RuntimeOrigin>;
285
286		/// Lookup of registered session keys.
287		type ValidatorRegistration: ValidatorRegistration<Self::AccountId>;
288
289		/// Maximum number of validators in a received set.
290		#[pallet::constant]
291		type MaxValidators: Get<u32>;
292
293		/// Maximum number of entries of [`AuthoredBlocks`] that one report reads.
294		///
295		/// Authors are counted between two reports: the validators of the stored set, and the
296		/// other collators of the chain, such as invulnerables and candidates. A sensible value is
297		/// [`Config::MaxValidators`], plus the maximum number of other collators the chain may
298		/// have, plus a small buffer for the authors that leave the collators before the next
299		/// report. Entries beyond it wait for the next report. The `integrity_test` checks that a
300		/// report of this many entries fits a block.
301		#[pallet::constant]
302		type MaxEntriesPerReport: Get<u32>;
303
304		/// The regular session rotation rule kept next to the forced rotations.
305		type PeriodicSession: ShouldEndSession<BlockNumberFor<Self>>;
306
307		/// Hands the block counts of one report to the chain that credits them.
308		type BlockReporter: ReportAuthoredBlocks<Self::AccountId>;
309
310		/// Value of [`MaxCollators`] until governance sets it.
311		///
312		/// A runtime upgrade that changes it keeps the collators drawn under the previous value
313		/// until the next draw, unless the upgrade sets [`PendingRotation`] to
314		/// [`RotationState::AwaitingQueue`].
315		#[pallet::constant]
316		type DefaultMaxCollators: Get<CollatorDraw>;
317
318		/// Number of blocks between two reports until governance sets [`ReportPeriod`].
319		#[pallet::constant]
320		type DefaultReportPeriod: Get<BlockNumberFor<Self>>;
321
322		/// Wall clock time, to time the report before the expected end of an era.
323		type UnixTime: UnixTime;
324
325		/// Value of [`ExpectedEraDuration`] until governance sets it, in milliseconds.
326		#[pallet::constant]
327		type DefaultExpectedEraDuration: Get<u64>;
328
329		/// Value of [`ReportMargin`] until governance sets it, in milliseconds.
330		#[pallet::constant]
331		type DefaultReportMargin: Get<u64>;
332
333		/// Largest value [`Pallet::set_report_margin`] accepts, in milliseconds.
334		///
335		/// A stored [`ReportMargin`] above it, as after a runtime upgrade that lowers it, is used
336		/// up to it.
337		#[pallet::constant]
338		type MaxReportMargin: Get<u64>;
339
340		/// Weight information for extrinsics in this pallet.
341		type WeightInfo: WeightInfo;
342	}
343
344	/// The latest received validator set.
345	#[pallet::storage]
346	pub type ExternalValidatorSet<T: Config> =
347		StorageValue<_, EraValidatorSet<T::AccountId, T::MaxValidators>, OptionQuery>;
348
349	/// Time at which we received the last [`ExternalValidatorSet`], in milliseconds. Removed when
350	/// the report before the expected end of its era is made.
351	#[pallet::storage]
352	pub type ExternalSetReceivedAt<T: Config> = StorageValue<_, u64, OptionQuery>;
353
354	/// How many validators are returned as collators, see [`CollatorDraw`]. Only validators with
355	/// keys count against the cap. It is [`Config::DefaultMaxCollators`] until
356	/// [`Pallet::set_max_collators`] stores a value.
357	///
358	/// The cap applies before the union with the other session manager. A validator that the
359	/// other session manager also returns takes a place under the cap without adding a collator.
360	///
361	/// The merged list becomes Aura's authority list, which Aura writes into the block header
362	/// whenever it changes, and the relay chain rejects a header above its head-data limit. Size
363	/// the cap so that the merged list, invulnerables and candidates included, keeps a
364	/// session-change header within that limit.
365	///
366	/// The validators are drawn at random, see [`DrawnCollators`].
367	///
368	/// A change with a stored set forces two rotations. The first draws [`DrawnCollators`] again
369	/// from the stored set, so the drawn validators can change. The change is in force two blocks
370	/// later. Removing the cap returns every validator of the stored set with registered keys.
371	#[pallet::storage]
372	pub type MaxCollators<T: Config> =
373		StorageValue<_, CollatorDraw, ValueQuery, <T as Config>::DefaultMaxCollators>;
374
375	/// The collators last returned to pallet-session, taken from [`ExternalValidatorSet`].
376	///
377	/// Written at every session rotation, and holds only validators that had registered keys at
378	/// that rotation. It is the draw made at the first rotation after a set arrives or
379	/// the cap changes, and each later rotation returns it again without the validators that have
380	/// removed their keys since. `None` when the last rotation returned no list, as before the
381	/// first set arrives.
382	///
383	/// Pallet-session queues the returned list at one rotation and enacts it at the next, so this
384	/// is ahead of the session validators while [`PendingRotation`] is
385	/// [`RotationState::AwaitingEnactment`].
386	///
387	/// While [`PendingRotation`] is [`RotationState::AwaitingQueue`] it still belongs to the
388	/// previous set or cap: it can be of an older era, missing before the first draw, and not a
389	/// subset of [`ExternalValidatorSet`]. Otherwise it belongs to the era of
390	/// [`ExternalValidatorSet`] and is a subset of it, of at most [`MaxCollators`] validators.
391	#[pallet::storage]
392	pub type DrawnCollators<T: Config> =
393		StorageValue<_, EraCollators<T::AccountId, T::MaxValidators>, OptionQuery>;
394
395	/// Progress of the forced rotations for the latest received set.
396	#[pallet::storage]
397	pub type PendingRotation<T: Config> = StorageValue<_, RotationState, ValueQuery>;
398
399	/// The relay chain randomness of one epoch ago, read from the relay chain state proof of every
400	/// block and written when it changes.
401	#[pallet::storage]
402	pub type EpochRandomness<T: Config> = StorageValue<_, [u8; 32], OptionQuery>;
403
404	/// Number of blocks between two reports of [`AuthoredBlocks`]. A report is made in every
405	/// block whose number is a multiple of it.
406	#[pallet::storage]
407	pub type ReportPeriod<T: Config> =
408		StorageValue<_, BlockNumberFor<T>, ValueQuery, T::DefaultReportPeriod>;
409
410	/// Blocks authored since the last report, per author.
411	#[pallet::storage]
412	pub type AuthoredBlocks<T: Config> =
413		CountedStorageMap<_, Twox64Concat, T::AccountId, u32, ValueQuery>;
414
415	/// Expected time from the arrival of a validator set to the end of its era, in milliseconds.
416	#[pallet::storage]
417	pub type ExpectedEraDuration<T: Config> =
418		StorageValue<_, u64, ValueQuery, T::DefaultExpectedEraDuration>;
419
420	/// Time before the expected end of an era at which the counts are reported, in milliseconds.
421	/// Used up to [`Config::MaxReportMargin`] and up to half of [`ExpectedEraDuration`].
422	#[pallet::storage]
423	pub type ReportMargin<T: Config> = StorageValue<_, u64, ValueQuery, T::DefaultReportMargin>;
424
425	#[pallet::event]
426	#[pallet::generate_deposit(pub(super) fn deposit_event)]
427	pub enum Event<T: Config> {
428		/// A validator set was stored for an era.
429		ValidatorSetReceived { era: EraIndex, count: u32 },
430		/// The maximum number of validator collators was changed.
431		MaxCollatorsSet { max: CollatorDraw },
432		/// No external set is stored, so no validators were returned for the session, with or
433		/// without a cap. This happens in the sessions after this pallet is added to a runtime and
434		/// before the first set arrives, so it is not an `UnexpectedKind`.
435		NothingToDraw,
436		/// `drawn_len` of the `external_len` validators of the set of `era`, all with registered
437		/// keys, were returned for a session and recorded in [`DrawnCollators`]. `new_external` is
438		/// `true` at the first rotation after a set arrives or the cap changes, and `false` at the
439		/// later ones, which return the previous draw again.
440		CollatorsDrawn { era: EraIndex, external_len: u32, drawn_len: u32, new_external: bool },
441		/// The number of blocks between two reports was changed.
442		ReportPeriodSet { period: BlockNumberFor<T> },
443		/// The block counts of `authors` authors were removed. The `reported` of them in the
444		/// stored set were handed to the reporter and the others were dropped.
445		BlocksReported { authors: u32, reported: u32 },
446		/// The reporter rejected the block counts. The counts of the `kept` authors in the stored
447		/// set are kept for the next report, and those of the `dropped` other authors were
448		/// removed.
449		BlocksReportFailed { kept: u32, dropped: u32 },
450		/// The expected time from the arrival of a set to the end of its era was changed.
451		ExpectedEraDurationSet { duration: u64 },
452		/// The time before the expected end of an era at which the counts are reported was
453		/// changed.
454		ReportMarginSet { margin: u64 },
455		/// Something that should never happen happened. See [`UnexpectedKind`].
456		Unexpected(UnexpectedKind),
457	}
458
459	/// The kinds of [`Event::Unexpected`].
460	#[derive(Clone, Encode, Decode, DecodeWithMemTracking, PartialEq, TypeInfo, Debug)]
461	pub enum UnexpectedKind {
462		/// We expected a previously drawn set, but none was found.
463		NoPreviousDrawSet,
464		/// The stored validator set does not decode, so no validators were returned for the
465		/// session.
466		StoredSetUndecodable,
467	}
468
469	#[pallet::error]
470	pub enum Error<T> {
471		/// The era of the set is not newer than the era of the stored set.
472		StaleEra,
473		/// The set has more validators than [`Config::MaxValidators`].
474		TooManyValidators,
475		/// The report period must be greater than zero.
476		ZeroReportPeriod,
477		/// The expected era duration must be greater than zero.
478		ZeroExpectedEraDuration,
479		/// The report margin must be greater than zero.
480		ZeroReportMargin,
481		/// The report margin is above [`Config::MaxReportMargin`].
482		ReportMarginTooHigh,
483	}
484
485	#[pallet::hooks]
486	impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
487		/// Charges the read of [`PendingRotation`] by [`ShouldEndSession::should_end_session`],
488		/// which pallet-session makes in every block without charging it.
489		fn on_initialize(_: BlockNumberFor<T>) -> Weight {
490			T::DbWeight::get().reads(1)
491		}
492
493		/// Reports [`AuthoredBlocks`] at every multiple of [`ReportPeriod`] (`periodic_send` in the
494		/// code), and once per stored set when [`ReportMargin`] or less remains until
495		/// [`ExternalSetReceivedAt`] plus [`ExpectedEraDuration`] (`early_send` in the code).
496		///
497		/// The early report removes [`ExternalSetReceivedAt`], so it is made once per set and not
498		/// retried. If the reporter rejects it, the counts go out with the next [`ReportPeriod`]
499		/// report. Both rules in the same block make one report.
500		///
501		/// It runs after the inherents, so the timestamp is the one of this block. A report that
502		/// does not fit `meter` is not made: an early report stays due and is made in the next
503		/// block it fits, and the counts of a periodic report go out with the next report. During
504		/// a multi-block migration no report is made, and the counts are kept.
505		fn on_poll(now: BlockNumberFor<T>, meter: &mut WeightMeter) {
506			// the base-weight, as per the benchmarks, is everything minus the report.
507			let base_weight = T::WeightInfo::on_poll();
508			if !meter.can_consume(base_weight) {
509				return;
510			}
511
512			let early_send = ExternalSetReceivedAt::<T>::get().is_some_and(|received_at| {
513				let duration = ExpectedEraDuration::<T>::get();
514				let margin =
515					ReportMargin::<T>::get().min(T::MaxReportMargin::get()).min(duration / 2);
516				let now_ms: u64 = T::UnixTime::now().as_millis().saturated_into();
517				now_ms >= received_at.saturating_add(duration.saturating_sub(margin))
518			});
519			let periodic_send = {
520				let period = ReportPeriod::<T>::get();
521				!period.is_zero() && (now % period).is_zero()
522			};
523
524			if !early_send && !periodic_send {
525				// nothing should be sent, we're done.
526				meter.consume(base_weight);
527				return;
528			}
529
530			// either periodic send, or early send, which we don't care to distinguish anymore, and
531			// just send the report.
532			let authors = AuthoredBlocks::<T>::count().min(T::MaxEntriesPerReport::get());
533			let report_weight = Self::report_weight(authors);
534			if !meter.can_consume(base_weight.saturating_add(report_weight)) {
535				log::warn!(
536					target: crate::LOG_TARGET,
537					"the report of authored blocks does not fit the block, postponing it"
538				);
539				meter.consume(base_weight);
540				return;
541			}
542
543			// Remove the arrival only once the report is made, so the early report is made once
544			// per set. Removing it sooner would lose an early report that does not fit `meter`,
545			// which stays due for the next block.
546			if early_send {
547				ExternalSetReceivedAt::<T>::kill();
548			}
549			Self::report_blocks(authors);
550			meter.consume(base_weight.saturating_add(report_weight));
551		}
552
553		fn integrity_test() {
554			assert!(
555				!T::DefaultReportPeriod::get().is_zero(),
556				"`DefaultReportPeriod` must not be zero"
557			);
558			assert!(
559				T::DefaultExpectedEraDuration::get() > 0,
560				"`DefaultExpectedEraDuration` must not be zero"
561			);
562			let margin = T::DefaultReportMargin::get();
563			assert!(
564				margin > 0 && margin <= T::MaxReportMargin::get(),
565				"`DefaultReportMargin` must not be zero and at most `MaxReportMargin`"
566			);
567			let max_items = T::MaxEntriesPerReport::get();
568			assert!(
569				max_items >= T::MaxValidators::get(),
570				"`MaxEntriesPerReport` must leave room for every validator of a set"
571			);
572			// `on_poll` postpones a report that does not fit, so one that does not fit an empty
573			// block is never made.
574			let report = T::WeightInfo::on_poll().saturating_add(Self::report_weight(max_items));
575			let max_block = T::BlockWeights::get().max_block;
576			assert!(
577				report.all_lte(max_block),
578				"a report of {max_items} authors weighs {report:?}, above the block {max_block:?}"
579			);
580
581			#[cfg(feature = "std")]
582			if let Some(max) = T::BlockReporter::max_message_size() {
583				// biggest possible report we could send.
584				let entries = (0..T::MaxValidators::get())
585					.map(|i| {
586						let who = T::AccountId::decode(
587							&mut sp_runtime::traits::TrailingZeroInput::new(&i.encode()),
588						)
589						.expect("infinite input decodes into an account; qed");
590						(who, u32::MAX)
591					})
592					.collect::<Vec<_>>();
593				let size = T::BlockReporter::message_size(&entries);
594				assert!(
595					size <= max,
596					"a report of {} entries is {size} bytes, above the limit of {max}",
597					entries.len()
598				);
599			}
600		}
601
602		#[cfg(feature = "try-runtime")]
603		fn try_state(_: BlockNumberFor<T>) -> Result<(), sp_runtime::TryRuntimeError> {
604			Self::do_try_state()
605		}
606	}
607
608	#[pallet::call]
609	impl<T: Config> Pallet<T> {
610		/// Store the validator set of `era`.
611		#[pallet::call_index(0)]
612		#[pallet::weight(T::WeightInfo::set_validators(validators.len() as u32))]
613		pub fn set_validators(
614			origin: OriginFor<T>,
615			era: EraIndex,
616			validators: BoundedBTreeSet<T::AccountId, T::MaxValidators>,
617		) -> DispatchResult {
618			T::SetOrigin::ensure_origin(origin)?;
619			Self::do_receive_validator_set(era, validators)
620		}
621
622		/// Set the maximum number of validators returned as collators.
623		///
624		/// With a stored set, the change forces two rotations and the first draws
625		/// [`DrawnCollators`] again, so the drawn validators can change.
626		#[pallet::call_index(1)]
627		#[pallet::weight(T::WeightInfo::set_max_collators())]
628		pub fn set_max_collators(origin: OriginFor<T>, max: CollatorDraw) -> DispatchResult {
629			T::UpdateOrigin::ensure_origin(origin)?;
630			MaxCollators::<T>::set(max);
631			if ExternalValidatorSet::<T>::exists() {
632				PendingRotation::<T>::put(RotationState::AwaitingQueue);
633			}
634			Self::deposit_event(Event::MaxCollatorsSet { max });
635			Ok(())
636		}
637
638		/// Set the number of blocks between two reports of the authored blocks.
639		///
640		/// The next report is made at the next multiple of `period`.
641		#[pallet::call_index(2)]
642		#[pallet::weight(T::WeightInfo::set_report_period())]
643		pub fn set_report_period(
644			origin: OriginFor<T>,
645			period: BlockNumberFor<T>,
646		) -> DispatchResult {
647			T::UpdateOrigin::ensure_origin(origin)?;
648			ensure!(!period.is_zero(), Error::<T>::ZeroReportPeriod);
649			ReportPeriod::<T>::put(period);
650			Self::deposit_event(Event::ReportPeriodSet { period });
651			Ok(())
652		}
653
654		/// Set the expected time from the arrival of a validator set to the end of its era, in
655		/// milliseconds.
656		///
657		/// It applies to the stored set too, whose arrival time is kept.
658		#[pallet::call_index(3)]
659		#[pallet::weight(T::WeightInfo::set_expected_era_duration())]
660		pub fn set_expected_era_duration(origin: OriginFor<T>, duration: u64) -> DispatchResult {
661			T::UpdateOrigin::ensure_origin(origin)?;
662			ensure!(duration > 0, Error::<T>::ZeroExpectedEraDuration);
663			ExpectedEraDuration::<T>::put(duration);
664			Self::deposit_event(Event::ExpectedEraDurationSet { duration });
665			Ok(())
666		}
667
668		/// Set the time before the expected end of an era at which the counts are reported, in
669		/// milliseconds.
670		///
671		/// It applies to the stored set too, whose arrival time is kept.
672		#[pallet::call_index(4)]
673		#[pallet::weight(T::WeightInfo::set_report_margin())]
674		pub fn set_report_margin(origin: OriginFor<T>, margin: u64) -> DispatchResult {
675			T::UpdateOrigin::ensure_origin(origin)?;
676			ensure!(margin > 0, Error::<T>::ZeroReportMargin);
677			ensure!(margin <= T::MaxReportMargin::get(), Error::<T>::ReportMarginTooHigh);
678			ReportMargin::<T>::put(margin);
679			Self::deposit_event(Event::ReportMarginSet { margin });
680			Ok(())
681		}
682	}
683
684	impl<T: Config> Pallet<T> {
685		/// Store the validator set of `era` and its arrival time, and schedule the rotations that
686		/// bring it into force.
687		///
688		/// An account listed more than once is kept once, and the set is checked against
689		/// [`Config::MaxValidators`] after that.
690		pub fn receive_validator_set(
691			era: EraIndex,
692			validators: impl IntoIterator<Item = T::AccountId>,
693		) -> DispatchResult {
694			let validators =
695				BoundedBTreeSet::try_from(validators.into_iter().collect::<BTreeSet<_>>())
696					.map_err(|_| Error::<T>::TooManyValidators)?;
697			Self::do_receive_validator_set(era, validators)
698		}
699
700		pub(crate) fn do_receive_validator_set(
701			era: EraIndex,
702			validators: BoundedBTreeSet<T::AccountId, T::MaxValidators>,
703		) -> DispatchResult {
704			ensure!(
705				ExternalValidatorSet::<T>::get().is_none_or(|stored| era > stored.era),
706				Error::<T>::StaleEra
707			);
708			let count = validators.len() as u32;
709			ExternalValidatorSet::<T>::put(EraValidatorSet { era, validators });
710			ExternalSetReceivedAt::<T>::put(T::UnixTime::now().as_millis().saturated_into::<u64>());
711			PendingRotation::<T>::put(RotationState::AwaitingQueue);
712			Self::deposit_event(Event::ValidatorSetReceived { era, count });
713			Ok(())
714		}
715
716		/// The relay chain storage keys this pallet reads from the relay chain state proof.
717		///
718		/// A runtime returns them, next to the keys of other pallets, from
719		/// [`KeyToIncludeInRelayProof`](cumulus_primitives_core::KeyToIncludeInRelayProof).
720		pub fn relay_keys_to_prove() -> Vec<RelayStorageKey> {
721			vec![RelayStorageKey::Top(well_known_keys::ONE_EPOCH_AGO_RANDOMNESS.to_vec())]
722		}
723
724		/// The seed of a draw from the set of `era`, made of the genesis hash, the era and
725		/// [`EpochRandomness`], or a zero value when no randomness is cached.
726		pub(crate) fn draw_seed(era: EraIndex) -> [u8; 32] {
727			let randomness = EpochRandomness::<T>::get().unwrap_or_else(|| {
728				log::error!(
729					target: crate::LOG_TARGET,
730					"no relay chain epoch randomness is cached, drawing with a zero value"
731				);
732				[0; 32]
733			});
734			let genesis = frame_system::Pallet::<T>::block_hash(BlockNumberFor::<T>::zero());
735			BlakeTwo256::hash_of(&(b"validator-collators", genesis, era, randomness)).into()
736		}
737
738		/// Draw up to `cap` validators with registered keys from `set`, in drawn order.
739		///
740		/// The whole set is shuffled before the key filter, so the order depends only on the seed
741		/// and the set.
742		fn draw_collators(
743			set: EraValidatorSet<T::AccountId, T::MaxValidators>,
744			cap: u32,
745		) -> Vec<T::AccountId> {
746			let EraValidatorSet { era, validators } = set;
747			let mut order: Vec<_> = validators.into_iter().collect();
748			order.shuffle(&mut ChaCha20Rng::from_seed(Self::draw_seed(era)));
749			order
750				.into_iter()
751				.filter(T::ValidatorRegistration::is_registered)
752				.take(cap as usize)
753				.collect()
754		}
755
756		/// Weight of [`Self::report_blocks`] with `authors` entries read from [`AuthoredBlocks`].
757		///
758		/// An entry of a validator in the stored set is handed to the reporter and removed, while
759		/// an entry of another author is only removed, which costs less. So the weight assumes as
760		/// many validators as the set holds, and the other authors beyond them.
761		pub(crate) fn report_weight(authors: u32) -> Weight {
762			let validators = authors.min(T::MaxValidators::get());
763			T::WeightInfo::report_blocks(validators, authors.saturating_sub(validators))
764		}
765
766		/// Hand the counted blocks of the stored validators to [`Config::BlockReporter`].
767		///
768		/// Hands the counts of every author in [`ExternalValidatorSet`] to the reporter in one
769		/// call, and removes the counts of the other authors. The filter is the latest set, so
770		/// once a new set arrives, the counts of a [`DrawnCollators`] validator that is not in it
771		/// are dropped. The counts handed over are removed only if the reporter accepts them, and
772		/// the reporter's storage changes are rolled back if it rejects them. Without a stored
773		/// set every count is removed.
774		///
775		/// `authors` is the number of entries in [`AuthoredBlocks`], which the caller reads to
776		/// weigh the report with [`Self::report_weight`] before making it. A rejected report
777		/// removes fewer counts than an accepted one, which is the weighed case.
778		pub(crate) fn report_blocks(authors: u32) {
779			if authors == 0 {
780				return;
781			}
782
783			let validators =
784				ExternalValidatorSet::<T>::get().map(|set| set.validators).unwrap_or_default();
785
786			// read all authored-blocks, and partition them in those that we send and those we may
787			// drop.
788			let (to_send, others): (Vec<_>, Vec<_>) = AuthoredBlocks::<T>::iter()
789				.take(T::MaxEntriesPerReport::get() as usize)
790				.partition(|(who, _)| validators.contains(who));
791			let (kept, dropped) = (to_send.len() as u32, others.len() as u32);
792
793			// We definitely want to delete these ones.
794			others.iter().for_each(|(who, _)| AuthoredBlocks::<T>::remove(who));
795
796			// No message is sent for a report with no entries.
797			let result = with_storage_layer(|| match to_send.is_empty() {
798				true => Ok(()),
799				false => T::BlockReporter::report(&to_send)
800					.map_err(|()| DispatchError::Other("the reporter rejected the counts")),
801			});
802
803			let event = match result {
804				Ok(()) => {
805					// we managed to send, delete the sent ones as well.
806					to_send.iter().for_each(|(who, _)| AuthoredBlocks::<T>::remove(who));
807					Event::BlocksReported { authors, reported: kept }
808				},
809				Err(_) => {
810					// we failed to send, we keep the ones that were authors now, having already
811					// dropped the rest.
812					log::warn!(
813						target: crate::LOG_TARGET,
814						"the reporter rejected the counts of {kept} authors, keeping them and \
815						dropping those of {dropped} authors outside the stored set"
816					);
817					Event::BlocksReportFailed { kept, dropped }
818				},
819			};
820			Self::deposit_event(event);
821		}
822
823		/// Check the pallet invariants.
824		#[cfg(any(test, feature = "try-runtime"))]
825		pub fn do_try_state() -> Result<(), sp_runtime::TryRuntimeError> {
826			// `a` implies `b`: fails only if `a` holds and `b` does not.
827			let implies = |a: bool, b: bool| !a || b;
828
829			// ExternalValidatorSet related
830			ensure!(
831				implies(
832					PendingRotation::<T>::get() != RotationState::Idle,
833					ExternalValidatorSet::<T>::exists()
834				),
835				"a rotation is pending without a stored validator set"
836			);
837			ensure!(
838				ExternalValidatorSet::<T>::exists() == ExternalValidatorSet::<T>::get().is_some(),
839				"the stored validator set does not decode, it may exceed `MaxValidators`"
840			);
841
842			// DrawnCollators related
843			ensure!(
844				implies(DrawnCollators::<T>::exists(), ExternalValidatorSet::<T>::exists()),
845				"drawn collators are stored without a validator set"
846			);
847			ensure!(
848				DrawnCollators::<T>::exists() == DrawnCollators::<T>::get().is_some(),
849				"the drawn collators do not decode"
850			);
851			ensure!(
852				AuthoredBlocks::<T>::iter_values().all(|blocks| blocks > 0),
853				"an author is counted with zero blocks"
854			);
855			ensure!(ExpectedEraDuration::<T>::get() > 0, "the expected era duration is zero");
856			ensure!(ReportMargin::<T>::get() > 0, "the report margin is zero");
857
858			if PendingRotation::<T>::get() == RotationState::AwaitingQueue {
859				// Until the next rotation draws, the drawn collators still belong to the previous
860				// set or cap: of an older era after a new set, possibly by more than one era, or of
861				// the same era after a cap change. Only their era is checked.
862				if let (Some(set), Some(drawn)) =
863					(ExternalValidatorSet::<T>::get(), DrawnCollators::<T>::get())
864				{
865					ensure!(
866						drawn.era <= set.era,
867						"the drawn collators belong to a newer era than the stored set"
868					);
869				}
870				return Ok(());
871			}
872
873			// Keys can change between rotations, so the key filter of the last rotation is not
874			// checked.
875			let Some(set) = ExternalValidatorSet::<T>::get() else { return Ok(()) };
876			let drawn = DrawnCollators::<T>::get().ok_or("no collators are drawn for the set")?;
877			ensure!(drawn.era == set.era, "the drawn collators belong to another era");
878			let mut seen = BTreeSet::new();
879			ensure!(
880				drawn.collators.iter().all(|v| seen.insert(v)),
881				"the drawn collators contain duplicates"
882			);
883			ensure!(
884				drawn.collators.iter().all(|v| set.validators.contains(v)),
885				"a drawn collator is not in the stored validator set"
886			);
887			ensure!(
888				drawn.collators.len() <= MaxCollators::<T>::get().limit() as usize,
889				"more collators are drawn than the cap allows"
890			);
891			// With the pallet wired as `OnSystemEvent`, `on_relay_state_proof` caches a value in
892			// every block's inherent and the cache is never removed. So this holds for every draw
893			// after the first block that runs the pallet, and flags a runtime without that wiring.
894			ensure!(
895				EpochRandomness::<T>::exists(),
896				"collators are drawn without a cached relay chain epoch randomness"
897			);
898			Ok(())
899		}
900
901		/// The stored set, or `None` without one. A stored set that does not decode is `None` too,
902		/// and is logged and reported with [`UnexpectedKind::StoredSetUndecodable`].
903		fn external_validator_set() -> Option<EraValidatorSet<T::AccountId, T::MaxValidators>> {
904			if let Some(external_set) = ExternalValidatorSet::<T>::get() {
905				return Some(external_set);
906			} else if ExternalValidatorSet::<T>::exists() {
907				log::error!(
908					target: crate::LOG_TARGET,
909					"the stored external validator set does not decode"
910				);
911				Self::deposit_event(Event::Unexpected(UnexpectedKind::StoredSetUndecodable));
912			}
913			None
914		}
915	}
916
917	impl<T: Config> SessionManager<T::AccountId> for Pallet<T> {
918		fn new_session(_: SessionIndex) -> Option<Vec<T::AccountId>> {
919			// Advance the forced rotations. `AwaitingQueue` means a new external set or a new cap,
920			// so we draw again.
921			let new_external = match PendingRotation::<T>::get() {
922				RotationState::AwaitingQueue => {
923					PendingRotation::<T>::put(RotationState::AwaitingEnactment);
924					true
925				},
926				RotationState::AwaitingEnactment => {
927					PendingRotation::<T>::kill();
928					false
929				},
930				RotationState::Idle => false,
931			};
932
933			let Some(external_set) = Self::external_validator_set() else {
934				// Nothing is returned, so nothing is recorded. Without a stored set there is
935				// nothing to remove, but a set that no longer decodes leaves its collators behind.
936				DrawnCollators::<T>::kill();
937				Self::deposit_event(Event::NothingToDraw);
938				return None;
939			};
940			let (era, external_len) = (external_set.era, external_set.validators.len() as u32);
941
942			// Drawn and filtered at the rotation, which pallet-session weighs as the whole block,
943			// since the key reads may not fit the weight of the message or report that delivers
944			// the set.
945			let collators: Vec<_> = match new_external {
946				// a new set or cap: draw again, from the validators with keys.
947				true => Self::draw_collators(external_set, MaxCollators::<T>::get().limit()),
948				// nothing new: the last draw, without those that removed their keys since.
949				false => match DrawnCollators::<T>::get() {
950					Some(prev) => prev
951						.collators
952						.into_iter()
953						.filter(T::ValidatorRegistration::is_registered)
954						.collect(),
955					None => {
956						Self::deposit_event(Event::Unexpected(UnexpectedKind::NoPreviousDrawSet));
957						return None;
958					},
959				},
960			};
961			// At most the length of the set, which is bounded by `MaxValidators`.
962			let collators = BoundedVec::truncate_from(collators);
963
964			Self::deposit_event(Event::CollatorsDrawn {
965				era,
966				external_len,
967				drawn_len: collators.len() as u32,
968				new_external,
969			});
970			DrawnCollators::<T>::put(EraCollators { era, collators: collators.clone() });
971			Some(collators.into_inner())
972		}
973
974		fn start_session(_: SessionIndex) {}
975
976		fn end_session(_: SessionIndex) {}
977	}
978
979	impl<T: Config> ShouldEndSession<BlockNumberFor<T>> for Pallet<T> {
980		fn should_end_session(now: BlockNumberFor<T>) -> bool {
981			PendingRotation::<T>::get() != RotationState::Idle ||
982				T::PeriodicSession::should_end_session(now)
983		}
984	}
985
986	impl<T: Config> pallet_authorship::EventHandler<T::AccountId, BlockNumberFor<T>> for Pallet<T> {
987		/// Counts the block for `author` in [`AuthoredBlocks`].
988		fn note_author(author: T::AccountId) {
989			frame_system::Pallet::<T>::register_extra_weight_unchecked(
990				T::WeightInfo::note_author(),
991				DispatchClass::Mandatory,
992			);
993			AuthoredBlocks::<T>::mutate(author, |blocks| blocks.saturating_inc());
994		}
995	}
996
997	impl<T: Config> OnSystemEvent for Pallet<T> {
998		fn on_validation_data(_: &PersistedValidationData) {}
999
1000		fn on_validation_code_applied() {}
1001
1002		/// Caches the relay chain randomness of one epoch ago in [`EpochRandomness`].
1003		///
1004		/// A proof that shows the key absent caches a zero value. A proof that lacks the trie nodes
1005		/// of the key, or holds a value that does not decode, panics and so makes the block
1006		/// invalid.
1007		fn on_relay_state_proof(relay_state_proof: &RelayChainStateProof) -> Weight {
1008			let randomness = match relay_state_proof
1009				.read_entry::<[u8; 32]>(well_known_keys::ONE_EPOCH_AGO_RANDOMNESS, None)
1010			{
1011				Ok(randomness) => randomness,
1012				// No randomness on the relay chain, as before its first epoch change, is cached as
1013				// the zero value a draw without randomness uses.
1014				Err(RelayProofError::ReadEntry(ReadEntryErr::Absent)) => {
1015					log::debug!(
1016						target: crate::LOG_TARGET,
1017						"the relay chain state proof shows no epoch randomness, caching a zero value"
1018					);
1019					[0; 32]
1020				},
1021				Err(RelayProofError::ReadEntry(
1022					error @ (ReadEntryErr::Proof | ReadEntryErr::Decode),
1023				)) => panic!(
1024					"Invalid relay chain epoch randomness in the relay chain state proof: {error:?}"
1025				),
1026				// `read_entry` returns only `ReadEntry` errors.
1027				Err(error) => panic!("Invalid relay chain state proof: {error:?}"),
1028			};
1029			if EpochRandomness::<T>::get() != Some(randomness) {
1030				EpochRandomness::<T>::put(randomness);
1031			}
1032			T::WeightInfo::on_relay_state_proof()
1033		}
1034	}
1035}