Expand description
Primitive traits for providing election functionality.
This crate provides two traits that could interact to enable extensible election functionality within FRAME pallets.
Something that will provide the functionality of election will implement
ElectionProvider
, whilst needing an associated ElectionProvider::DataProvider
, which
needs to be fulfilled by an entity implementing ElectionDataProvider
. Most often, the data
provider is the receiver of the election, resulting in a diagram as below:
ElectionDataProvider
<------------------------------------------+
| |
v |
+-----+----+ +------+---+
| | | |
pallet-do-election | | | | pallet-needs-election
| | | |
| | | |
+-----+----+ +------+---+
| ^
| |
+------------------------------------------+
ElectionProvider
It could also be possible that a third party pallet (C), provides the data of election to an election provider (B), which then passes the election result to another pallet (A).
§Election Types
Typically, two types of elections exist:
- Stateless: Election data is provided, and the election result is immediately ready.
- Stateful: Election data is is queried ahead of time, and the election result might be ready some number of blocks in the future.
To accommodate both type of elections in one trait, the traits lean toward stateful
election, as it is more general than the stateless. This is why ElectionProvider::elect
does not receive election data as an input. All value and type parameter must be provided by the
ElectionDataProvider
trait, even if the election happens immediately.
§Multi-page election support
Both ElectionDataProvider
and ElectionProvider
traits are parameterized by page,
supporting an election to be performed over multiple pages. This enables the
ElectionDataProvider
implementor to provide all the election data over multiple pages.
Similarly ElectionProvider::elect
is parameterized by page index.
§Election Data
The data associated with an election, essentially what the ElectionDataProvider
must convey
is as follows:
- A list of voters, with their stake.
- A list of targets (i.e. candidates).
- A number of desired targets to be elected (i.e. winners)
In addition to that, the ElectionDataProvider
must also hint ElectionProvider
at when
the next election might happen (ElectionDataProvider::next_election_prediction
). A stateless
election provider would probably ignore this. A stateful election provider can use this to
prepare the election result in advance.
Nonetheless, an ElectionProvider
shan’t rely on this and should preferably provide some
means of fallback election as well, in case the elect
was called immaturely early.
§Example
type AccountId = u64;
type Balance = u64;
type BlockNumber = u32;
mod data_provider_mod {
use super::*;
pub trait Config: Sized {
type ElectionProvider: ElectionProvider<
AccountId = AccountId,
BlockNumber = BlockNumber,
DataProvider = Pallet<Self>,
>;
}
pub struct Pallet<T: Config>(std::marker::PhantomData<T>);
impl<T: Config> ElectionDataProvider for Pallet<T> {
type AccountId = AccountId;
type BlockNumber = BlockNumber;
type MaxVotesPerVoter = ConstU32<100>;
fn desired_targets() -> data_provider::Result<u32> {
Ok(1)
}
fn electing_voters(bounds: DataProviderBounds, _page: PageIndex)
-> data_provider::Result<Vec<VoterOf<Self>>>
{
Ok(Default::default())
}
fn electable_targets(bounds: DataProviderBounds, _page: PageIndex) -> data_provider::Result<Vec<AccountId>> {
Ok(vec![10, 20, 30])
}
fn next_election_prediction(now: BlockNumber) -> BlockNumber {
0
}
}
}
mod generic_election_provider {
use super::*;
use sp_runtime::traits::Zero;
pub struct GenericElectionProvider<T: Config>(std::marker::PhantomData<T>);
pub trait Config {
type DataProvider: ElectionDataProvider<AccountId=AccountId, BlockNumber = BlockNumber>;
type MaxWinnersPerPage: Get<u32>;
type MaxBackersPerWinner: Get<u32>;
type Pages: Get<u32>;
}
impl<T: Config> ElectionProvider for GenericElectionProvider<T> {
type AccountId = AccountId;
type BlockNumber = BlockNumber;
type Error = &'static str;
type MaxBackersPerWinner = T::MaxBackersPerWinner;
type MaxWinnersPerPage = T::MaxWinnersPerPage;
type Pages = T::Pages;
type DataProvider = T::DataProvider;
fn elect(page: PageIndex) -> Result<BoundedSupportsOf<Self>, Self::Error> {
unimplemented!()
}
fn ongoing() -> bool {
unimplemented!()
}
}
}
mod runtime {
use frame_support::parameter_types;
use super::generic_election_provider;
use super::data_provider_mod;
use super::AccountId;
parameter_types! {
pub static MaxWinnersPerPage: u32 = 10;
pub static MaxBackersPerWinner: u32 = 20;
pub static Pages: u32 = 2;
}
struct Runtime;
impl generic_election_provider::Config for Runtime {
type DataProvider = data_provider_mod::Pallet<Runtime>;
type MaxWinnersPerPage = MaxWinnersPerPage;
type MaxBackersPerWinner = MaxBackersPerWinner;
type Pages = Pages;
}
impl data_provider_mod::Config for Runtime {
type ElectionProvider = generic_election_provider::GenericElectionProvider<Runtime>;
}
}
Re-exports§
pub use bounds::DataProviderBounds;
pub use traits::NposSolution;
pub use weights::WeightInfo;
Modules§
- Types and helpers to define and handle election bounds.
- Types that are used by the data provider trait.
- An implementation of
ElectionProvider
that uses anNposSolver
to do the election. As the name suggests, this is meant to be used onchain. Given how heavy the calculations are, please be careful when using it onchain. - Traits for the election operations.
- Autogenerated weights for pallet_election_provider_support_benchmarking
Macros§
- Re-export the solution generation macro. Generates a struct to store the election result in a small/compact way. This can encode a structure which is the equivalent of a
sp_npos_elections::Assignment<_>
. - Enable/disable the given code depending on
feature = "runtime-benchmarks"
being enabled for the crate or not. - Enable/disable the given code depending on
any(feature = "runtime-benchmarks", feature = "std")
being enabled for the crate or not.
Structs§
- A voter’s stake assignment among a set of targets, represented as ratios.
- Utility struct to group parameters for the balancing algorithm.
- A bounded vector of supports. Bounded equivalent to
sp_npos_elections::Supports
. - A bounded vector of
BoundedSupport
. - A bounded vector.
- Final result of the election.
- The
IndexAssignment
type is an intermediate between the assignments list (&[Assignment<T>]
) andSolutionOf<T>
. - An election provider that does nothing whatsoever.
- A wrapper for [
sp_npos_elections::phragmms()
] that implementsNposSolver
. See the documentation of [sp_npos_elections::phragmms()
] for more info. - A quick and dirty solver, that produces a valid but probably worthless election result, but is fast.
- A wrapper for [
sp_npos_elections::seq_phragmen
] that implementsNposSolver
. See the documentation of [sp_npos_elections::seq_phragmen
] for more info. - A structure to demonstrate the election result from the perspective of the candidate, i.e. how much support each candidate is receiving.
Enums§
- The errors that might occur in this crate and
frame-election-provider-solution-type
.
Traits§
- Trait that allows zero-copy read of value-references from slices in LE format.
- Something that can provide the data to an
ElectionProvider
. - Something that can compute the result of an election and pass it back to the caller in a paged way.
- Trait that allows zero-copy write of value-references to slices in LE format.
- A trait for querying a single value from a type.
- an aggregator trait for a generic type of a voter/target identifier. This usually maps to substrate’s account id.
- A (almost) marker trait that signifies an election provider as working synchronously. i.e. being instant.
- Items implementing
MaxEncodedLen
have a statically known maximum encoded size. - Something that can compute the result to an NPoS solution.
- Re-export some type as they are used in the interface. Something that implements a fixed point ration with an arbitrary granularity
X
, as parts perX
. - Aggregator trait for a PerThing that can be multiplied by u128 (ExtendedBalance).
- Something that can provide the
Score
of an account. Similar toElectionProvider
andElectionDataProvider
, this should typically be implementing by whoever is supposed to useSortedListProvider
. - A utility trait for something to implement
ElectionDataProvider
in a sensible way. - Try and build yourself from another
BoundedSupports
with a different set of types.
Type Aliases§
- Same as
BoundedSupports
but parameterized by anElectionProvider
. - A type in which performing operations on vote weights are safe.
- A type alias for
IndexAssignment
made fromNposSolution
. - A page index for the multi-block elections pagination.
- A target-major representation of the the election outcome.
- A type which is used in the API of this crate as a numeric weight of a vote, most often the stake of the voter. It is always converted to
ExtendedBalance
for computation. - A voter, at the level of abstraction of this crate.
- Same as
Voter
, but parameterized by anElectionDataProvider
.
Derive Macros§
- Derive
parity_scale_codec::Decode
for struct and enum. - derive
Default
but do no bound any generic. Docs are atframe_support::DefaultNoBound
. - Derive
parity_scale_codec::Encode
andparity_scale_codec::EncodeLike
for struct and enum. - Derive
parity_scale_codec::MaxEncodedLen
for struct and enum.