pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-05-30 02:21:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Decouple Stkaing and Election - Part1: Support traits (#7908)

Browse Source 
* Base features and traits.

* Fix the build

* Remove unused boxing

* Self review cleanup

* Fix build
This commit is contained in:
Kian Paimani
2021-01-18 10:24:12 +00:00
committed by GitHub
parent c58a2d9a74
commit ced107b355
23 changed files with 925 additions and 341 deletions
Download Patch File Download Diff File Expand all files Collapse all files
substrate/primitives/election-providers/Cargo.toml
+33
View File
@@ -0,0 +1,33 @@
[package]
name = "sp-election-providers"
version = "2.0.0"
authors = ["Parity Technologies <admin@parity.io>"]
edition = "2018"
license = "Apache-2.0"
homepage = "https://substrate.dev"
repository = "https://github.com/paritytech/substrate/"
description = "Primitive election providers"
readme = "README.md"
[package.metadata.docs.rs]
targets = ["x86_64-unknown-linux-gnu"]
[dependencies]
codec = { package = "parity-scale-codec", version = "1.3.4", default-features = false, features = ["derive"] }
sp-std = { version = "2.0.1", default-features = false, path = "../std" }
sp-arithmetic = { version = "2.0.1", default-features = false, path = "../arithmetic" }
sp-npos-elections = { version = "2.0.1", default-features = false, path = "../npos-elections" }
[dev-dependencies]
sp-npos-elections = { version = "2.0.1", path = "../npos-elections" }
sp-runtime = { version = "2.0.1", path = "../runtime" }
[features]
default = ["std"]
runtime-benchmarks = []
std = [
"codec/std",
"sp-std/std",
"sp-npos-elections/std",
"sp-arithmetic/std",
]
substrate/primitives/election-providers/src/lib.rs
+241
View File
@@ -0,0 +1,241 @@
// This file is part of Substrate.
// Copyright (C) 2020 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.
//! 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:
//!
//! ```ignore
//! 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:
//!
//! 1. **Stateless**: Election data is provided, and the election result is immediately ready.
//! 2. **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`]
//! has no parameters. All value and type parameter must be provided by the [`ElectionDataProvider`]
//! trait, even if the election happens immediately.
//!
//! ## Election Data
//!
//! The data associated with an election, essentially what the [`ElectionDataProvider`] must convey
//! is as follows:
//!
//! 1. A list of voters, with their stake.
//! 2. A list of targets (i.e. _candidates_).
//! 3. 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
//!
//! ```rust
//! # use sp_election_providers::*;
//! # use sp_npos_elections::{Support, Assignment};
//!
//! type AccountId = u64;
//! type Balance = u64;
//! type BlockNumber = u32;
//!
//! mod data_provider {
//! use super::*;
//!
//! pub trait Config: Sized {
//! type ElectionProvider: ElectionProvider<
//! AccountId,
//! BlockNumber,
//! DataProvider = Module<Self>,
//! >;
//! }
//!
//! pub struct Module<T: Config>(std::marker::PhantomData<T>);
//!
//! impl<T: Config> ElectionDataProvider<AccountId, BlockNumber> for Module<T> {
//! fn desired_targets() -> u32 {
//! 1
//! }
//! fn voters() -> Vec<(AccountId, VoteWeight, Vec<AccountId>)> {
//! Default::default()
//! }
//! fn targets() -> Vec<AccountId> {
//! vec![10, 20, 30]
//! }
//! fn next_election_prediction(now: BlockNumber) -> BlockNumber {
//! 0
//! }
//! }
//! }
//!
//!
//! mod generic_election_provider {
//! use super::*;
//!
//! pub struct GenericElectionProvider<T: Config>(std::marker::PhantomData<T>);
//!
//! pub trait Config {
//! type DataProvider: ElectionDataProvider<AccountId, BlockNumber>;
//! }
//!
//! impl<T: Config> ElectionProvider<AccountId, BlockNumber> for GenericElectionProvider<T> {
//! type Error = ();
//! type DataProvider = T::DataProvider;
//!
//! fn elect() -> Result<Supports<AccountId>, Self::Error> {
//! Self::DataProvider::targets()
//! .first()
//! .map(|winner| vec![(*winner, Support::default())])
//! .ok_or(())
//! }
//! }
//! }
//!
//! mod runtime {
//! use super::generic_election_provider;
//! use super::data_provider;
//! use super::AccountId;
//!
//! struct Runtime;
//! impl generic_election_provider::Config for Runtime {
//! type DataProvider = data_provider::Module<Runtime>;
//! }
//!
//! impl data_provider::Config for Runtime {
//! type ElectionProvider = generic_election_provider::GenericElectionProvider<Runtime>;
//! }
//!
//! }
//!
//! # fn main() {}
//! ```
#![cfg_attr(not(feature = "std"), no_std)]
pub mod onchain;
use sp_std::{prelude::*, fmt::Debug};
/// Re-export some type as they are used in the interface.
pub use sp_arithmetic::PerThing;
pub use sp_npos_elections::{Assignment, ExtendedBalance, PerThing128, Supports, VoteWeight};
/// Something that can provide the data to an [`ElectionProvider`].
pub trait ElectionDataProvider<AccountId, BlockNumber> {
/// All possible targets for the election, i.e. the candidates.
fn targets() -> Vec<AccountId>;
/// All possible voters for the election.
///
/// Note that if a notion of self-vote exists, it should be represented here.
fn voters() -> Vec<(AccountId, VoteWeight, Vec<AccountId>)>;
/// The number of targets to elect.
fn desired_targets() -> u32;
/// Provide a best effort prediction about when the next election is about to happen.
///
/// In essence, the implementor should predict with this function when it will trigger the
/// [`ElectionProvider::elect`].
///
/// This is only useful for stateful election providers.
fn next_election_prediction(now: BlockNumber) -> BlockNumber;
/// Utility function only to be used in benchmarking scenarios, to be implemented optionally,
/// else a noop.
#[cfg(any(feature = "runtime-benchmarks", test))]
fn put_snapshot(
_voters: Vec<(AccountId, VoteWeight, Vec<AccountId>)>,
_targets: Vec<AccountId>,
) {
}
}
#[cfg(feature = "std")]
impl<AccountId, BlockNumber> ElectionDataProvider<AccountId, BlockNumber> for () {
fn targets() -> Vec<AccountId> {
Default::default()
}
fn voters() -> Vec<(AccountId, VoteWeight, Vec<AccountId>)> {
Default::default()
}
fn desired_targets() -> u32 {
Default::default()
}
fn next_election_prediction(now: BlockNumber) -> BlockNumber {
now
}
}
/// Something that can compute the result of an election and pass it back to the caller.
///
/// This trait only provides an interface to _request_ an election, i.e.
/// [`ElectionProvider::elect`]. That data required for the election need to be passed to the
/// implemented of this trait through [`ElectionProvider::DataProvider`].
pub trait ElectionProvider<AccountId, BlockNumber> {
/// The error type that is returned by the provider.
type Error: Debug;
/// The data provider of the election.
type DataProvider: ElectionDataProvider<AccountId, BlockNumber>;
/// Elect a new set of winners.
///
/// The result is returned in a target major format, namely as vector of supports.
fn elect() -> Result<Supports<AccountId>, Self::Error>;
}
#[cfg(feature = "std")]
impl<AccountId, BlockNumber> ElectionProvider<AccountId, BlockNumber> for () {
type Error = &'static str;
type DataProvider = ();
fn elect() -> Result<Supports<AccountId>, Self::Error> {
Err("<() as ElectionProvider> cannot do anything.")
}
}
substrate/primitives/election-providers/src/onchain.rs
+163
View File
@@ -0,0 +1,163 @@
// This file is part of Substrate.
// Copyright (C) 2020 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.
//! An implementation of [`ElectionProvider`] that does an on-chain sequential phragmen.
use sp_arithmetic::InnerOf;
use crate::{ElectionDataProvider, ElectionProvider};
use sp_npos_elections::*;
use sp_std::{collections::btree_map::BTreeMap, marker::PhantomData, prelude::*};
/// Errors of the on-chain election.
#[derive(Eq, PartialEq, Debug)]
pub enum Error {
/// An internal error in the NPoS elections crate.
NposElections(sp_npos_elections::Error),
}
impl From<sp_npos_elections::Error> for Error {
fn from(e: sp_npos_elections::Error) -> Self {
Error::NposElections(e)
}
}
/// A simple on-chain implementation of the election provider trait.
///
/// This will accept voting data on the fly and produce the results immediately.
///
/// ### Warning
///
/// This can be very expensive to run frequently on-chain. Use with care.
pub struct OnChainSequentialPhragmen<T: Config>(PhantomData<T>);
/// Configuration trait of [`OnChainSequentialPhragmen`].
///
/// Note that this is similar to a pallet traits, but [`OnChainSequentialPhragmen`] is not a pallet.
pub trait Config {
/// The account identifier type.
type AccountId: IdentifierT;
/// The block number type.
type BlockNumber;
/// The accuracy used to compute the election:
type Accuracy: PerThing128;
/// Something that provides the data for election.
type DataProvider: ElectionDataProvider<Self::AccountId, Self::BlockNumber>;
}
impl<T: Config> ElectionProvider<T::AccountId, T::BlockNumber> for OnChainSequentialPhragmen<T>
where
ExtendedBalance: From<InnerOf<T::Accuracy>>,
{
type Error = Error;
type DataProvider = T::DataProvider;
fn elect() -> Result<Supports<T::AccountId>, Self::Error> {
let voters = Self::DataProvider::voters();
let targets = Self::DataProvider::targets();
let desired_targets = Self::DataProvider::desired_targets() as usize;
let mut stake_map: BTreeMap<T::AccountId, VoteWeight> = BTreeMap::new();
voters.iter().for_each(|(v, s, _)| {
stake_map.insert(v.clone(), *s);
});
let stake_of = |w: &T::AccountId| -> VoteWeight {
stake_map.get(w).cloned().unwrap_or_default()
};
let ElectionResult { winners, assignments } =
seq_phragmen::<_, T::Accuracy>(desired_targets, targets, voters, None)
.map_err(Error::from)?;
let staked = assignment_ratio_to_staked_normalized(assignments, &stake_of)?;
let winners = to_without_backing(winners);
to_supports(&winners, &staked).map_err(Error::from)
}
}
#[cfg(test)]
mod tests {
use super::*;
use sp_npos_elections::Support;
use sp_runtime::Perbill;
type AccountId = u64;
type BlockNumber = u32;
struct Runtime;
impl Config for Runtime {
type AccountId = AccountId;
type BlockNumber = BlockNumber;
type Accuracy = Perbill;
type DataProvider = mock_data_provider::DataProvider;
}
type OnChainPhragmen = OnChainSequentialPhragmen<Runtime>;
mod mock_data_provider {
use super::*;
pub struct DataProvider;
impl ElectionDataProvider<AccountId, BlockNumber> for DataProvider {
fn voters() -> Vec<(AccountId, VoteWeight, Vec<AccountId>)> {
vec![
(1, 10, vec![10, 20]),
(2, 20, vec![30, 20]),
(3, 30, vec![10, 30]),
]
}
fn targets() -> Vec<AccountId> {
vec![10, 20, 30]
}
fn desired_targets() -> u32 {
2
}
fn next_election_prediction(_: BlockNumber) -> BlockNumber {
0
}
}
}
#[test]
fn onchain_seq_phragmen_works() {
assert_eq!(
OnChainPhragmen::elect().unwrap(),
vec![
(
10,
Support {
total: 25,
voters: vec![(1, 10), (3, 15)]
}
),
(
30,
Support {
total: 35,
voters: vec![(2, 20), (3, 15)]
}
)
]
);
}
}