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}