Newer
Older
// Copyright (C) 2021 Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! Collator Selection pallet.
//!
//! A pallet to manage collators in a parachain.
//!
//! ## Overview
//!
//! The Collator Selection pallet manages the collators of a parachain. **Collation is _not_ a
//! secure activity** and this pallet does not implement any game-theoretic mechanisms to meet BFT
//! safety assumptions of the chosen set.
//!
//! ## Terminology
//!
//! - Collator: A parachain block producer.
//! - Bond: An amount of `Balance` _reserved_ for candidate registration.
//! - Invulnerable: An account guaranteed to be in the collator set.
//!
//! ## Implementation
//!
//! The final `Collators` are aggregated from two individual lists:
//!
//! 1. [`Invulnerables`]: a set of collators appointed by governance. These accounts will always be
//! collators.
//! 2. [`Candidates`]: these are *candidates to the collation task* and may or may not be elected as
//! a final collator.
//!
//! The current implementation resolves congestion of [`Candidates`] in a first-come-first-serve
//! manner.
//!
//! Candidates will not be allowed to get kicked or `leave_intent` if the total number of collators
//! would fall below `MinEligibleCollators`. This is to ensure that some collators will always
//! exist, i.e. someone is eligible to produce a block.
//! ### Rewards
//!
//! The Collator Selection pallet maintains an on-chain account (the "Pot"). In each block, the
//! collator who authored it receives:
//!
//! - Half the value of the Pot.
//! - Half the value of the transaction fees within the block. The other half of the transaction
//! fees are deposited into the Pot.
//!
//! To initiate rewards, an ED needs to be transferred to the pot address.
//!
//! Note: Eventually the Pot distribution may be modified as discussed in
//! [this issue](https://github.com/paritytech/statemint/issues/21#issuecomment-810481073).
#![cfg_attr(not(feature = "std"), no_std)]
pub use pallet::*;
#[cfg(test)]
mod mock;
#[cfg(test)]
mod tests;
#[cfg(feature = "runtime-benchmarks")]
mod benchmarking;
pub mod migration;
const LOG_TARGET: &str = "runtime::collator-selection";
pub use crate::weights::WeightInfo;
use core::ops::Div;
dispatch::{DispatchClass, DispatchResultWithPostInfo},
traits::{AccountIdConversion, CheckedSub, Saturating, Zero},
},
traits::{
Currency, EnsureOrigin, ExistenceRequirement::KeepAlive, ReservableCurrency,
ValidatorRegistration,
BoundedVec, DefaultNoBound, PalletId,
use frame_system::{pallet_prelude::*, Config as SystemConfig};
/// The current storage version.
const STORAGE_VERSION: StorageVersion = StorageVersion::new(1);
type BalanceOf<T> =
<<T as Config>::Currency as Currency<<T as SystemConfig>::AccountId>>::Balance;
/// A convertor from collators id. Since this pallet does not have stash/controller, this is
/// just identity.
pub struct IdentityCollator;
impl<T> sp_runtime::traits::Convert<T, Option<T>> for IdentityCollator {
fn convert(t: T) -> Option<T> {
Some(t)
}
}
/// Configure the pallet by specifying the parameters and types on which it depends.
#[pallet::config]
pub trait Config: frame_system::Config {
/// Overarching event type.
type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;
/// The currency mechanism.
type Currency: ReservableCurrency<Self::AccountId>;
/// Origin that can dictate updating parameters of this pallet.
type UpdateOrigin: EnsureOrigin<Self::RuntimeOrigin>;
/// Account Identifier from which the internal Pot is generated.
type PotId: Get<PalletId>;
/// Maximum number of candidates that we should have.
///
/// This does not take into account the invulnerables.
type MaxCandidates: Get<u32>;
/// Minimum number eligible collators. Should always be greater than zero. This includes
/// Invulnerable collators. This ensures that there will always be one collator who can
/// produce a block.
type MinEligibleCollators: Get<u32>;
/// Maximum number of invulnerables.
type MaxInvulnerables: Get<u32>;
// Will be kicked if block is not produced in threshold.
type KickThreshold: Get<Self::BlockNumber>;
/// A stable ID for a validator.
type ValidatorId: Member + Parameter;
/// A conversion from account ID to validator ID.
///
/// Its cost must be at most one storage read.
type ValidatorIdOf: Convert<Self::AccountId, Option<Self::ValidatorId>>;
/// Validate a user is registered
type ValidatorRegistration: ValidatorRegistration<Self::ValidatorId>;
/// The weight information of this pallet.
type WeightInfo: WeightInfo;
}
/// Basic information about a collation candidate.
#[derive(
PartialEq, Eq, Clone, Encode, Decode, RuntimeDebug, scale_info::TypeInfo, MaxEncodedLen,
)]
pub struct CandidateInfo<AccountId, Balance> {
/// Account identifier.
pub who: AccountId,
/// Reserved deposit.
pub deposit: Balance,
}
#[pallet::pallet]
#[pallet::storage_version(STORAGE_VERSION)]
/// The invulnerable, permissioned collators. This list must be sorted.
#[pallet::storage]
#[pallet::getter(fn invulnerables)]
pub type Invulnerables<T: Config> =
StorageValue<_, BoundedVec<T::AccountId, T::MaxInvulnerables>, ValueQuery>;
/// The (community, limited) collation candidates. `Candidates` and `Invulnerables` should be
/// mutually exclusive.
#[pallet::storage]
#[pallet::getter(fn candidates)]
pub type Candidates<T: Config> = StorageValue<
_,
BoundedVec<CandidateInfo<T::AccountId, BalanceOf<T>>, T::MaxCandidates>,
ValueQuery,
>;
/// Last block authored by collator.
#[pallet::storage]
#[pallet::getter(fn last_authored_block)]
pub type LastAuthoredBlock<T: Config> =
StorageMap<_, Twox64Concat, T::AccountId, T::BlockNumber, ValueQuery>;
/// Desired number of candidates.
///
/// This should ideally always be less than [`Config::MaxCandidates`] for weights to be correct.
#[pallet::storage]
#[pallet::getter(fn desired_candidates)]
pub type DesiredCandidates<T> = StorageValue<_, u32, ValueQuery>;
/// Fixed amount to deposit to become a collator.
///
/// When a collator calls `leave_intent` they immediately receive the deposit back.
#[pallet::storage]
#[pallet::getter(fn candidacy_bond)]
pub type CandidacyBond<T> = StorageValue<_, BalanceOf<T>, ValueQuery>;
#[pallet::genesis_config]
#[derive(DefaultNoBound)]
pub struct GenesisConfig<T: Config> {
pub invulnerables: Vec<T::AccountId>,
pub candidacy_bond: BalanceOf<T>,
pub desired_candidates: u32,
}
#[pallet::genesis_build]
impl<T: Config> BuildGenesisConfig for GenesisConfig<T> {
let duplicate_invulnerables = self
.invulnerables
.iter()
.collect::<sp_std::collections::btree_set::BTreeSet<_>>();
assert!(
duplicate_invulnerables.len() == self.invulnerables.len(),
"duplicate invulnerables in genesis."
);
let mut bounded_invulnerables =
BoundedVec::<_, T::MaxInvulnerables>::try_from(self.invulnerables.clone())
.expect("genesis invulnerables are more than T::MaxInvulnerables");
assert!(
T::MaxCandidates::get() >= self.desired_candidates,
"genesis desired_candidates are more than T::MaxCandidates",
);
bounded_invulnerables.sort();
<DesiredCandidates<T>>::put(self.desired_candidates);
<CandidacyBond<T>>::put(self.candidacy_bond);
<Invulnerables<T>>::put(bounded_invulnerables);
}
}
#[pallet::event]
#[pallet::generate_deposit(pub(super) fn deposit_event)]
pub enum Event<T: Config> {
/// New Invulnerables were set.
NewInvulnerables { invulnerables: Vec<T::AccountId> },
/// A new Invulnerable was added.
InvulnerableAdded { account_id: T::AccountId },
/// An Invulnerable was removed.
InvulnerableRemoved { account_id: T::AccountId },
/// The number of desired candidates was set.
NewDesiredCandidates { desired_candidates: u32 },
/// The candidacy bond was set.
NewCandidacyBond { bond_amount: BalanceOf<T> },
/// A new candidate joined.
CandidateAdded { account_id: T::AccountId, deposit: BalanceOf<T> },
/// A candidate was removed.
CandidateRemoved { account_id: T::AccountId },
/// An account was unable to be added to the Invulnerables because they did not have keys
/// registered. Other Invulnerables may have been set.
InvalidInvulnerableSkipped { account_id: T::AccountId },
/// The pallet has too many candidates.
/// Leaving would result in too few candidates.
TooFewEligibleCollators,
/// Account is already a candidate.
/// Account is not a candidate.
/// There are too many Invulnerables.
/// Account is already an Invulnerable.
/// Account is not an Invulnerable.
NotInvulnerable,
/// Account has no associated validator ID.
/// Validator ID is not yet registered.
impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
fn integrity_test() {
assert!(T::MinEligibleCollators::get() > 0, "chain must require at least one collator");
}
}
/// Set the list of invulnerable (fixed) collators. These collators must do some
/// preparation, namely to have registered session keys.
///
/// The call will remove any accounts that have not registered keys from the set. That is,
/// it is non-atomic; the caller accepts all `AccountId`s passed in `new` _individually_ as
/// acceptable Invulnerables, and is not proposing a _set_ of new Invulnerables.
///
/// This call does not maintain mutual exclusivity of `Invulnerables` and `Candidates`. It
/// is recommended to use a batch of `add_invulnerable` and `remove_invulnerable` instead.
/// A `batch_all` can also be used to enforce atomicity. If any candidates are included in
/// `new`, they should be removed with `remove_invulnerable_candidate` after execution.
///
/// Must be called by the `UpdateOrigin`.
#[pallet::call_index(0)]
#[pallet::weight(T::WeightInfo::set_invulnerables(new.len() as u32))]
pub fn set_invulnerables(origin: OriginFor<T>, new: Vec<T::AccountId>) -> DispatchResult {
omadoyeabraham
committed
// don't wipe out the collator set
if new.is_empty() {
omadoyeabraham
committed
ensure!(
Candidates::<T>::decode_len().unwrap_or_default() >=
T::MinEligibleCollators::get() as usize,
Error::<T>::TooFewEligibleCollators
omadoyeabraham
committed
);
}
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
// Will need to check the length again when putting into a bounded vec, but this
// prevents the iterator from having too many elements.
ensure!(
new.len() as u32 <= T::MaxInvulnerables::get(),
Error::<T>::TooManyInvulnerables
);
let mut new_with_keys = Vec::new();
// check if the invulnerables have associated validator keys before they are set
for account_id in &new {
// don't let one unprepared collator ruin things for everyone.
let validator_key = T::ValidatorIdOf::convert(account_id.clone());
match validator_key {
Some(key) => {
// key is not registered
if !T::ValidatorRegistration::is_registered(&key) {
Self::deposit_event(Event::InvalidInvulnerableSkipped {
account_id: account_id.clone(),
});
continue
}
// else condition passes; key is registered
},
// key does not exist
None => {
Self::deposit_event(Event::InvalidInvulnerableSkipped {
account_id: account_id.clone(),
});
continue
},
}
new_with_keys.push(account_id.clone());
}
// should never fail since `new_with_keys` must be equal to or shorter than `new`
let mut bounded_invulnerables =
BoundedVec::<_, T::MaxInvulnerables>::try_from(new_with_keys)
.map_err(|_| Error::<T>::TooManyInvulnerables)?;
// Invulnerables must be sorted for removal.
bounded_invulnerables.sort();
<Invulnerables<T>>::put(&bounded_invulnerables);
Self::deposit_event(Event::NewInvulnerables {
invulnerables: bounded_invulnerables.to_vec(),
});
Ok(())
/// Set the ideal number of non-invulnerable collators. If lowering this number, then the
/// number of running collators could be higher than this figure. Aside from that edge case,
/// there should be no other way to have more candidates than the desired number.
///
/// The origin for this call must be the `UpdateOrigin`.
#[pallet::call_index(1)]
#[pallet::weight(T::WeightInfo::set_desired_candidates())]
pub fn set_desired_candidates(
origin: OriginFor<T>,
max: u32,
) -> DispatchResultWithPostInfo {
T::UpdateOrigin::ensure_origin(origin)?;
// we trust origin calls, this is just a for more accurate benchmarking
if max > T::MaxCandidates::get() {
log::warn!("max > T::MaxCandidates; you might need to run benchmarks again");
Self::deposit_event(Event::NewDesiredCandidates { desired_candidates: max });
///
/// The origin for this call must be the `UpdateOrigin`.
#[pallet::call_index(2)]
#[pallet::weight(T::WeightInfo::set_candidacy_bond())]
pub fn set_candidacy_bond(
origin: OriginFor<T>,
bond: BalanceOf<T>,
) -> DispatchResultWithPostInfo {
Self::deposit_event(Event::NewCandidacyBond { bond_amount: bond });
/// Register this account as a collator candidate. The account must (a) already have
/// registered session keys and (b) be able to reserve the `CandidacyBond`.
///
/// This call is not available to `Invulnerable` collators.
#[pallet::call_index(3)]
#[pallet::weight(T::WeightInfo::register_as_candidate(T::MaxCandidates::get()))]
pub fn register_as_candidate(origin: OriginFor<T>) -> DispatchResultWithPostInfo {
let who = ensure_signed(origin)?;
// ensure we are below limit.
let length = <Candidates<T>>::decode_len().unwrap_or_default();
ensure!((length as u32) < Self::desired_candidates(), Error::<T>::TooManyCandidates);
ensure!(!Self::invulnerables().contains(&who), Error::<T>::AlreadyInvulnerable);
let validator_key = T::ValidatorIdOf::convert(who.clone())
.ok_or(Error::<T>::NoAssociatedValidatorId)?;
ensure!(
T::ValidatorRegistration::is_registered(&validator_key),
Error::<T>::ValidatorNotRegistered
);
let deposit = Self::candidacy_bond();
// First authored block is current block plus kick threshold to handle session delay
let incoming = CandidateInfo { who: who.clone(), deposit };
let current_count =
<Candidates<T>>::try_mutate(|candidates| -> Result<usize, DispatchError> {
if candidates.iter().any(|candidate| candidate.who == who) {
Err(Error::<T>::AlreadyCandidate)?
} else {
T::Currency::reserve(&who, deposit)?;
candidates.try_push(incoming).map_err(|_| Error::<T>::TooManyCandidates)?;
<LastAuthoredBlock<T>>::insert(
who.clone(),
frame_system::Pallet::<T>::block_number() + T::KickThreshold::get(),
);
Self::deposit_event(Event::CandidateAdded { account_id: who, deposit });
Ok(Some(T::WeightInfo::register_as_candidate(current_count as u32)).into())
}
/// Deregister `origin` as a collator candidate. Note that the collator can only leave on
/// session change. The `CandidacyBond` will be unreserved immediately.
///
/// This call will fail if the total number of candidates would drop below
/// `MinEligibleCollators`.
#[pallet::call_index(4)]
#[pallet::weight(T::WeightInfo::leave_intent(T::MaxCandidates::get()))]
pub fn leave_intent(origin: OriginFor<T>) -> DispatchResultWithPostInfo {
let who = ensure_signed(origin)?;
Self::eligible_collators() > T::MinEligibleCollators::get() as usize,
Error::<T>::TooFewEligibleCollators
// Do remove their last authored block.
let current_count = Self::try_remove_candidate(&who, true)?;
Ok(Some(T::WeightInfo::leave_intent(current_count as u32)).into())
}
/// Add a new account `who` to the list of `Invulnerables` collators. `who` must have
/// registered session keys. If `who` is a candidate, they will be removed.
///
/// The origin for this call must be the `UpdateOrigin`.
#[pallet::call_index(5)]
#[pallet::weight(T::WeightInfo::add_invulnerable(
T::MaxInvulnerables::get().saturating_sub(1),
T::MaxCandidates::get()
))]
pub fn add_invulnerable(
origin: OriginFor<T>,
who: T::AccountId,
) -> DispatchResultWithPostInfo {
T::UpdateOrigin::ensure_origin(origin)?;
// ensure `who` has registered a validator key
let validator_key = T::ValidatorIdOf::convert(who.clone())
.ok_or(Error::<T>::NoAssociatedValidatorId)?;
ensure!(
T::ValidatorRegistration::is_registered(&validator_key),
Error::<T>::ValidatorNotRegistered
);
<Invulnerables<T>>::try_mutate(|invulnerables| -> DispatchResult {
match invulnerables.binary_search(&who) {
Ok(_) => return Err(Error::<T>::AlreadyInvulnerable)?,
Err(pos) => invulnerables
.try_insert(pos, who.clone())
.map_err(|_| Error::<T>::TooManyInvulnerables)?,
}
Ok(())
})?;
// Error just means `who` wasn't a candidate, which is the state we want anyway. Don't
// remove their last authored block, as they are still a collator.
let _ = Self::try_remove_candidate(&who, false);
Self::deposit_event(Event::InvulnerableAdded { account_id: who });
let weight_used = T::WeightInfo::add_invulnerable(
Invulnerables::<T>::decode_len()
.unwrap_or_default()
.try_into()
.unwrap_or(T::MaxInvulnerables::get().saturating_sub(1)),
Candidates::<T>::decode_len()
.unwrap_or_default()
.try_into()
.unwrap_or(T::MaxCandidates::get()),
);
Ok(Some(weight_used).into())
}
/// Remove an account `who` from the list of `Invulnerables` collators. `Invulnerables` must
/// be sorted.
///
/// The origin for this call must be the `UpdateOrigin`.
#[pallet::call_index(6)]
#[pallet::weight(T::WeightInfo::remove_invulnerable(T::MaxInvulnerables::get()))]
pub fn remove_invulnerable(origin: OriginFor<T>, who: T::AccountId) -> DispatchResult {
T::UpdateOrigin::ensure_origin(origin)?;
Self::eligible_collators() > T::MinEligibleCollators::get() as usize,
Error::<T>::TooFewEligibleCollators
);
<Invulnerables<T>>::try_mutate(|invulnerables| -> DispatchResult {
let pos =
invulnerables.binary_search(&who).map_err(|_| Error::<T>::NotInvulnerable)?;
invulnerables.remove(pos);
Ok(())
})?;
Self::deposit_event(Event::InvulnerableRemoved { account_id: who });
Ok(())
}
/// Get a unique, inaccessible account ID from the `PotId`.
T::PotId::get().into_account_truncating()
/// Return the total number of accounts that are eligible collators (candidates and
/// invulnerables).
fn eligible_collators() -> usize {
Candidates::<T>::decode_len()
.unwrap_or_default()
.saturating_add(Invulnerables::<T>::decode_len().unwrap_or_default())
}
/// Removes a candidate if they exist and sends them back their deposit.
fn try_remove_candidate(
who: &T::AccountId,
remove_last_authored: bool,
) -> Result<usize, DispatchError> {
let current_count =
<Candidates<T>>::try_mutate(|candidates| -> Result<usize, DispatchError> {
let index = candidates
.iter()
.position(|candidate| candidate.who == *who)
.ok_or(Error::<T>::NotCandidate)?;
let candidate = candidates.remove(index);
T::Currency::unreserve(who, candidate.deposit);
if remove_last_authored {
<LastAuthoredBlock<T>>::remove(who.clone())
};
Self::deposit_event(Event::CandidateRemoved { account_id: who.clone() });
}
/// Assemble the current set of candidates and invulnerables into the next collator set.
///
/// This is done on the fly, as frequent as we are told to do so, as the session manager.
pub fn assemble_collators(
candidates: BoundedVec<T::AccountId, T::MaxCandidates>,
) -> Vec<T::AccountId> {
let mut collators = Self::invulnerables().to_vec();
/// Kicks out candidates that did not produce a block in the kick threshold and refunds
/// their deposits.
candidates: BoundedVec<CandidateInfo<T::AccountId, BalanceOf<T>>, T::MaxCandidates>,
) -> BoundedVec<T::AccountId, T::MaxCandidates> {
let now = frame_system::Pallet::<T>::block_number();
let kick_threshold = T::KickThreshold::get();
let min_collators = T::MinEligibleCollators::get();
.into_iter()
.filter_map(|c| {
let last_block = <LastAuthoredBlock<T>>::get(c.who.clone());
let since_last = now.saturating_sub(last_block);
let is_invulnerable = Self::invulnerables().contains(&c.who);
let is_lazy = since_last >= kick_threshold;
if is_invulnerable {
// They are invulnerable. No reason for them to be in Candidates also.
// We don't even care about the min collators here, because an Account
// should not be a collator twice.
let _ = Self::try_remove_candidate(&c.who, false);
None
if Self::eligible_collators() <= min_collators as usize || !is_lazy {
// Either this is a good collator (not lazy) or we are at the minimum
// that the system needs. They get to stay.
Some(c.who)
} else {
// This collator has not produced a block recently enough. Bye bye.
let _ = Self::try_remove_candidate(&c.who, true);
None
.collect::<Vec<_>>()
.try_into()
.expect("filter_map operation can't result in a bounded vec larger than its original; qed")
}
}
/// Keep track of number of authored blocks per authority, uncles are counted as well since
/// they're a valid proof of being online.
impl<T: Config + pallet_authorship::Config>
pallet_authorship::EventHandler<T::AccountId, T::BlockNumber> for Pallet<T>
{
fn note_author(author: T::AccountId) {
let pot = Self::account_id();
// assumes an ED will be sent to pot.
let reward = T::Currency::free_balance(&pot)
.checked_sub(&T::Currency::minimum_balance())
.unwrap_or_else(Zero::zero)
.div(2u32.into());
// `reward` is half of pot account minus ED, this should never fail.
let _success = T::Currency::transfer(&pot, &author, reward, KeepAlive);
debug_assert!(_success.is_ok());
<LastAuthoredBlock<T>>::insert(author, frame_system::Pallet::<T>::block_number());
frame_system::Pallet::<T>::register_extra_weight_unchecked(
T::WeightInfo::note_author(),
DispatchClass::Mandatory,
);
}
}
/// Play the role of the session manager.
impl<T: Config> SessionManager<T::AccountId> for Pallet<T> {
fn new_session(index: SessionIndex) -> Option<Vec<T::AccountId>> {
log::info!(
"assembling new collators for new session {} at #{:?}",
index,
<frame_system::Pallet<T>>::block_number(),
);
let candidates = Self::candidates();
let candidates_len_before = candidates.len();
let active_candidates = Self::kick_stale_candidates(candidates);
let removed = candidates_len_before - active_candidates.len();
let result = Self::assemble_collators(active_candidates);
frame_system::Pallet::<T>::register_extra_weight_unchecked(
T::WeightInfo::new_session(candidates_len_before as u32, removed as u32),
DispatchClass::Mandatory,
);
Some(result)
}
fn start_session(_: SessionIndex) {
// we don't care.
}
fn end_session(_: SessionIndex) {
// we don't care.
}
}
}