Expand description
Validator Collators pallet.
Stores the validator set announced by the chain that runs pallet-staking-async, typically
Asset Hub, and offers it as a session manager, so the relay-chain validators of the current era
collate on a system parachain.
§Overview
The announcing chain sends the active validator set of each era, tagged with the era index of
pallet-staking-async.
This pallet stores the latest set, received through set_validators from Config::SetOrigin
or from another pallet through Pallet::receive_validator_set. It rejects a set whose era
is not newer than the stored one, or that has more validators than Config::MaxValidators.
The pallet is a [pallet_session::SessionManager]. At every session rotation it returns the
stored validators that have registered local session keys, checked with
Config::ValidatorRegistration, and records the returned list in DrawnCollators. The
runtime may combine this pallet with pallet-collator-selection through
[pallet_session::UnionSessionManager], so invulnerables and candidates keep collating next to
the validators.
MaxCollators optionally caps how many validators are returned. Governance can start with a
low cap and raise it in steps, or lower it again, to roll out validator collators gradually.
The pallet draws the validators at random at the first forced rotation after a set
arrives or the cap changes, and returns them until the next draw. The draw shuffles the whole
set with a seed made of the genesis hash, the era and the relay chain epoch randomness cached in
EpochRandomness, then keeps the first validators with registered keys up to the cap. Every
validator with keys has the same chance to be drawn in each era. A cap change draws again from
the stored set, so the drawn validators can change. Every draw takes its seed from the
randomness cached at the time of the draw. The seed includes the genesis hash, so each chain
draws independently from the same set. A drawn validator that removes its keys is dropped at
the next rotation and its place stays empty, and a validator that registers keys after the draw
waits, until the next set or cap change. Each set, so each era, gets a new draw, which is
enacted at the second forced rotation with no notice, so a validator with keys must already
run a synced collator node to collate when drawn.
Until governance sets it, the cap is Config::DefaultMaxCollators.
The pallet implements [cumulus_pallet_parachain_system::OnSystemEvent]. The runtime must
include it in the OnSystemEvent of cumulus-pallet-parachain-system, alone or in a tuple
with other handlers, to keep EpochRandomness up to date from the relay chain state proof.
The runtime should also return the keys of Pallet::relay_keys_to_prove from
KeyToIncludeInRelayProof, so collators
include the randomness key in the proof.
The draw runs in the session rotation, before the block’s own proof is processed, so it uses
the value cached by the previous block.
A block whose proof lacks the trie nodes of the randomness key, or holds a value that does not
decode, is invalid. A proof that shows the key absent, as before the relay chain’s first epoch
change, caches the zero value a draw without randomness uses.
Without the OnSystemEvent wiring, every draw uses a zero randomness value and logs an error.
The stored set is the one staking elected for the era. The relay chain enacts only the elected validators with relay-chain session keys, and each system chain returns only those with keys registered there, so a returned collator is not necessarily an active relay-chain validator.
The pallet is also a [pallet_session::ShouldEndSession]. Pallet-session queues a new set at
one rotation and enacts it at the next. When a set arrives, or the cap changes while a set is
stored, the pallet forces two rotations in the following two blocks, so the change is in force
without waiting for the regular period. The regular rotations given by
Config::PeriodicSession continue as before.
The returned validators author blocks like any collator, so a pallet-collator-selection event
handler pays them from its pot and records them in LastAuthoredBlock.
The pallet is also a pallet_authorship::EventHandler and counts the blocks each author
produces in AuthoredBlocks. At a report-time, it removes the counts of the authors outside
the stored set, and hands the counts of the others to Config::BlockReporter in one call. The
reporter delivers them to the chain that runs pallet-staking-async + points-convertor, where
they become era points. A report has at most one entry per validator of the stored set, and the
pallet’s integrity_test checks that Config::MaxValidators entries fit the reporter’s
ReportAuthoredBlocks::max_message_size, so a full report is never too large to send and is
not split. If the reporter rejects it, the counts of ONLY the currently stored validators are
kept for the next report, so AuthoredBlocks never holds more than the stored set plus the
authors since the last report. Without a stored set every count is dropped.
A report runs in every block whose number is a multiple of ReportPeriod, and once per
stored set shortly before the expected end of its era. The pallet records the arrival time of
each set in ExternalSetReceivedAt, from Config::UnixTime, and expects the era to end
ExpectedEraDuration after it. The early report runs in the first block at or after
ReportMargin before that end, so that in a normal era the counts reach the chain that runs
pallet-staking-async before the era rotates. The margin used is at most
Config::MaxReportMargin and at most half of ExpectedEraDuration. The early report
removes ExternalSetReceivedAt and is not retried: if the reporter rejects it, its counts go
out with the next ReportPeriod report. The periodic report also covers eras that end earlier
or later than expected, a set that never arrives, and the time before the first set arrives. If
both reports fall in the same block, the pallet reports once.
A runtime must configure pallet-collator-selection’s KickThreshold to exceed a full Aura
round of the merged list, Config::MaxValidators plus the invulnerables and candidates, times
the blocks the chain produces per Aura slot. Otherwise bonded candidates are kicked as stale
between their slots. Config::MaxValidators rather than the cap is the bound, since the cap
can be raised or removed without a runtime upgrade.
§TODO
- Dropping validators that author no blocks for a session, judged among the drawn validators under a cap.
- (Only if a need is established) Propagating relay-chain offences to the collator set.
- Under a cap, revisit the redraw period and notice once operators have run collators. A draw per era without notice is the first step, with operators expected to run a synced collator node all the time. Options: redraw every few eras or sessions, keep a drawn validator for several eras while it stays in the active set, and announce the drawn validators before they collate so they can sync a node. Open points: the time a node needs to sync, and refilling the place of a drawn validator that leaves the active set, which needs notice too.
Re-exports§
pub use pallet::*;
Modules§
- migrations
- Storage migrations of the pallet.
- pallet
- The
palletmodule in each FRAME pallet hosts the most important items needed to construct this pallet. - weights
- Default weights for
pallet_validator_collators.
Traits§
- Report
Authored Blocks - Delivers the block counts of one report.