Reorganising the repository - external renames and moves (#4074)

* Adding first rough ouline of the repository structure * Remove old CI stuff * add title * formatting fixes * move node-exits job's script to scripts dir * Move docs into subdir * move to bin * move maintainence scripts, configs and helpers into its own dir * add .local to ignore * move core->client * start up 'test' area * move test client * move test runtime * make test move compile * Add dependencies rule enforcement. * Fix indexing. * Update docs to reflect latest changes * Moving /srml->/paint * update docs * move client/sr-* -> primitives/ * clean old readme * remove old broken code in rhd * update lock * Step 1. * starting to untangle client * Fix after merge. * start splitting out client interfaces * move children and blockchain interfaces * Move trie and state-machine to primitives. * Fix WASM builds. * fixing broken imports * more interface moves * move backend and light to interfaces * move CallExecutor * move cli off client * moving around more interfaces * re-add consensus crates into the mix * fix subkey path * relieve client from executor * starting to pull out client from grandpa * move is_decendent_of out of client * grandpa still depends on client directly * lemme tests pass * rename srml->paint * Make it compile. * rename interfaces->client-api * Move keyring to primitives. * fixup libp2p dep * fix broken use * allow dependency enforcement to fail * move fork-tree * Moving wasm-builder * make env * move build-script-utils * fixup broken crate depdencies and names * fix imports for authority discovery * fix typo * update cargo.lock * fixing imports * Fix paths and add missing crates * re-add missing crates
2026-06-14 19:11:04 +00:00 · 2019-11-14 21:51:17 +01:00
parent becc3b0a4f
commit 60e5011c72
809 changed files with 7801 additions and 6464 deletions
@@ -0,0 +1,535 @@
+// Copyright 2019 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Rust implementation of the Phragmén election algorithm. This is used in several SRML modules to
+//! optimally distribute the weight of a set of voters among an elected set of candidates. In the
+//! context of staking this is mapped to validators and nominators.
+//!
+//! The algorithm has two phases:
+//!   - Sequential phragmen: performed in [`elect`] function which is first pass of the distribution
+//!     The results are not optimal but the execution time is less.
+//!   - Equalize post-processing: tries to further distribute the weight fairly among candidates.
+//!     Incurs more execution time.
+//!
+//! The main objective of the assignments done by phragmen is to maximize the minimum backed
+//! candidate in the elected set.
+//!
+//! Reference implementation: https://github.com/w3f/consensus
+//! Further details:
+//! https://research.web3.foundation/en/latest/polkadot/NPoS/4.%20Sequential%20Phragm%C3%A9n%E2%80%99s%20method/
+
+#![cfg_attr(not(feature = "std"), no_std)]
+
+use rstd::{prelude::*, collections::btree_map::BTreeMap};
+use sr_primitives::RuntimeDebug;
+use sr_primitives::{helpers_128bit::multiply_by_rational, Perbill, Rational128};
+use sr_primitives::traits::{Zero, Convert, Member, SimpleArithmetic, Saturating, Bounded};
+
+mod mock;
+mod tests;
+
+/// A type in which performing operations on balances and stakes of candidates and voters are safe.
+///
+/// This module's functions expect a `Convert` type to convert all balances to u64. Hence, u128 is
+/// a safe type for arithmetic operations over them.
+///
+/// Balance types converted to `ExtendedBalance` are referred to as `Votes`.
+pub type ExtendedBalance = u128;
+
+/// The denominator used for loads. Since votes are collected as u64, the smallest ratio that we
+/// might collect is `1/approval_stake` where approval stake is the sum of votes. Hence, some number
+/// bigger than u64::max_value() is needed. For maximum accuracy we simply use u128;
+const DEN: u128 = u128::max_value();
+
+/// A candidate entity for phragmen election.
+#[derive(Clone, Default, RuntimeDebug)]
+pub struct Candidate<AccountId> {
+	/// Identifier.
+	pub who: AccountId,
+	/// Intermediary value used to sort candidates.
+	pub score: Rational128,
+	/// Sum of the stake of this candidate based on received votes.
+	approval_stake: ExtendedBalance,
+	/// Flag for being elected.
+	elected: bool,
+}
+
+/// A voter entity.
+#[derive(Clone, Default, RuntimeDebug)]
+pub struct Voter<AccountId> {
+	/// Identifier.
+	who: AccountId,
+	/// List of candidates proposed by this voter.
+	edges: Vec<Edge<AccountId>>,
+	/// The stake of this voter.
+	budget: ExtendedBalance,
+	/// Incremented each time a candidate that this voter voted for has been elected.
+	load: Rational128,
+}
+
+/// A candidate being backed by a voter.
+#[derive(Clone, Default, RuntimeDebug)]
+pub struct Edge<AccountId> {
+	/// Identifier.
+	who: AccountId,
+	/// Load of this vote.
+	load: Rational128,
+	/// Index of the candidate stored in the 'candidates' vector.
+	candidate_index: usize,
+}
+
+/// Means a particular `AccountId` was backed by `Perbill`th of a nominator's stake.
+pub type PhragmenAssignment<AccountId> = (AccountId, Perbill);
+
+/// Means a particular `AccountId` was backed by `ExtendedBalance` of a nominator's stake.
+pub type PhragmenStakedAssignment<AccountId> = (AccountId, ExtendedBalance);
+
+/// Final result of the phragmen election.
+#[derive(RuntimeDebug)]
+pub struct PhragmenResult<AccountId> {
+	/// Just winners zipped with their approval stake. Note that the approval stake is merely the
+	/// sub of their received stake and could be used for very basic sorting and approval voting.
+	pub winners: Vec<(AccountId, ExtendedBalance)>,
+	/// Individual assignments. for each tuple, the first elements is a voter and the second
+	/// is the list of candidates that it supports.
+	pub assignments: Vec<(AccountId, Vec<PhragmenAssignment<AccountId>>)>
+}
+
+/// A structure to demonstrate the phragmen result from the perspective of the candidate, i.e. how
+/// much support each candidate is receiving.
+///
+/// This complements the [`PhragmenResult`] and is needed to run the equalize post-processing.
+///
+/// This, at the current version, resembles the `Exposure` defined in the staking SRML module, yet
+/// they do not necessarily have to be the same.
+#[derive(Default, RuntimeDebug)]
+#[cfg_attr(feature = "std", derive(serde::Serialize, serde::Deserialize))]
+pub struct Support<AccountId> {
+	/// The amount of support as the effect of self-vote.
+	pub own: ExtendedBalance,
+	/// Total support.
+	pub total: ExtendedBalance,
+	/// Support from voters.
+	pub others: Vec<PhragmenStakedAssignment<AccountId>>,
+}
+
+/// A linkage from a candidate and its [`Support`].
+pub type SupportMap<A> = BTreeMap<A, Support<A>>;
+
+/// Perform election based on Phragmén algorithm.
+///
+/// Returns an `Option` the set of winners and their detailed support ratio from each voter if
+/// enough candidates are provided. Returns `None` otherwise.
+///
+/// * `candidate_count`: number of candidates to elect.
+/// * `minimum_candidate_count`: minimum number of candidates to elect. If less candidates exist,
+///   `None` is returned.
+/// * `initial_candidates`: candidates list to be elected from.
+/// * `initial_voters`: voters list.
+/// * `stake_of`: something that can return the stake stake of a particular candidate or voter.
+///
+/// This function does not strip out candidates who do not have any backing stake. It is the
+/// responsibility of the caller to make sure only those candidates who have a sensible economic
+/// value are passed in. From the perspective of this function, a candidate can easily be among the
+/// winner with no backing stake.
+pub fn elect<AccountId, Balance, FS, C>(
+	candidate_count: usize,
+	minimum_candidate_count: usize,
+	initial_candidates: Vec<AccountId>,
+	initial_voters: Vec<(AccountId, Vec<AccountId>)>,
+	stake_of: FS,
+) -> Option<PhragmenResult<AccountId>> where
+	AccountId: Default + Ord + Member,
+	Balance: Default + Copy + SimpleArithmetic,
+	for<'r> FS: Fn(&'r AccountId) -> Balance,
+	C: Convert<Balance, u64> + Convert<u128, Balance>,
+{
+	let to_votes = |b: Balance| <C as Convert<Balance, u64>>::convert(b) as ExtendedBalance;
+
+	// return structures
+	let mut elected_candidates: Vec<(AccountId, ExtendedBalance)>;
+	let mut assigned: Vec<(AccountId, Vec<PhragmenAssignment<AccountId>>)>;
+
+	// used to cache and access candidates index.
+	let mut c_idx_cache = BTreeMap::<AccountId, usize>::new();
+
+	// voters list.
+	let num_voters = initial_candidates.len() + initial_voters.len();
+	let mut voters: Vec<Voter<AccountId>> = Vec::with_capacity(num_voters);
+
+	// Iterate once to create a cache of candidates indexes. This could be optimized by being
+	// provided by the call site.
+	let mut candidates = initial_candidates
+		.into_iter()
+		.enumerate()
+		.map(|(idx, who)| {
+			c_idx_cache.insert(who.clone(), idx);
+			Candidate { who, ..Default::default() }
+		})
+		.collect::<Vec<Candidate<AccountId>>>();
+
+	// early return if we don't have enough candidates
+	if candidates.len() < minimum_candidate_count { return None; }
+
+	// collect voters. use `c_idx_cache` for fast access and aggregate `approval_stake` of
+	// candidates.
+	voters.extend(initial_voters.into_iter().map(|(who, votes)| {
+		let voter_stake = stake_of(&who);
+		let mut edges: Vec<Edge<AccountId>> = Vec::with_capacity(votes.len());
+		for v in votes {
+			if let Some(idx) = c_idx_cache.get(&v) {
+				// This candidate is valid + already cached.
+				candidates[*idx].approval_stake = candidates[*idx].approval_stake
+					.saturating_add(to_votes(voter_stake));
+				edges.push(Edge { who: v.clone(), candidate_index: *idx, ..Default::default() });
+			} // else {} would be wrong votes. We don't really care about it.
+		}
+		Voter {
+			who,
+			edges: edges,
+			budget: to_votes(voter_stake),
+			load: Rational128::zero(),
+		}
+	}));
+
+
+	// we have already checked that we have more candidates than minimum_candidate_count.
+	// run phragmen.
+	let to_elect = candidate_count.min(candidates.len());
+	elected_candidates = Vec::with_capacity(candidate_count);
+	assigned = Vec::with_capacity(candidate_count);
+
+	// main election loop
+	for _round in 0..to_elect {
+		// loop 1: initialize score
+		for c in &mut candidates {
+			if !c.elected {
+				// 1 / approval_stake == (DEN / approval_stake) / DEN. If approval_stake is zero,
+				// then the ratio should be as large as possible, essentially `infinity`.
+				if c.approval_stake.is_zero() {
+					c.score = Rational128::from_unchecked(DEN, 0);
+				} else {
+					c.score = Rational128::from(DEN / c.approval_stake, DEN);
+				}
+			}
+		}
+
+		// loop 2: increment score
+		for n in &voters {
+			for e in &n.edges {
+				let c = &mut candidates[e.candidate_index];
+				if !c.elected && !c.approval_stake.is_zero() {
+					let temp_n = multiply_by_rational(
+						n.load.n(),
+						n.budget,
+						c.approval_stake,
+					).unwrap_or(Bounded::max_value());
+					let temp_d = n.load.d();
+					let temp = Rational128::from(temp_n, temp_d);
+					c.score = c.score.lazy_saturating_add(temp);
+				}
+			}
+		}
+
+		// loop 3: find the best
+		if let Some(winner) = candidates
+			.iter_mut()
+			.filter(|c| !c.elected)
+			.min_by_key(|c| c.score)
+		{
+			// loop 3: update voter and edge load
+			winner.elected = true;
+			for n in &mut voters {
+				for e in &mut n.edges {
+					if e.who == winner.who {
+						e.load = winner.score.lazy_saturating_sub(n.load);
+						n.load = winner.score;
+					}
+				}
+			}
+
+			elected_candidates.push((winner.who.clone(), winner.approval_stake));
+		} else {
+			break
+		}
+	} // end of all rounds
+
+	// update backing stake of candidates and voters
+	for n in &mut voters {
+		let mut assignment = (n.who.clone(), vec![]);
+		for e in &mut n.edges {
+			if elected_candidates.iter().position(|(ref c, _)| *c == e.who).is_some() {
+				let per_bill_parts =
+				{
+					if n.load == e.load {
+						// Full support. No need to calculate.
+						Perbill::accuracy().into()
+					} else {
+						if e.load.d() == n.load.d() {
+							// return e.load / n.load.
+							let desired_scale: u128 = Perbill::accuracy().into();
+							multiply_by_rational(
+								desired_scale,
+								e.load.n(),
+								n.load.n(),
+							).unwrap_or(Bounded::max_value())
+						} else {
+							// defensive only. Both edge and nominator loads are built from
+							// scores, hence MUST have the same denominator.
+							Zero::zero()
+						}
+					}
+				};
+				// safer to .min() inside as well to argue as u32 is safe.
+				let per_thing = Perbill::from_parts(
+					per_bill_parts.min(Perbill::accuracy().into()) as u32
+				);
+				assignment.1.push((e.who.clone(), per_thing));
+			}
+		}
+
+		if assignment.1.len() > 0 {
+			// To ensure an assertion indicating: no stake from the nominator going to waste,
+			// we add a minimal post-processing to equally assign all of the leftover stake ratios.
+			let vote_count = assignment.1.len() as u32;
+			let len = assignment.1.len();
+			let sum = assignment.1.iter()
+				.map(|a| a.1.deconstruct())
+				.sum::<u32>();
+			let accuracy = Perbill::accuracy();
+			let diff = accuracy.checked_sub(sum).unwrap_or(0);
+			let diff_per_vote = (diff / vote_count).min(accuracy);
+
+			if diff_per_vote > 0 {
+				for i in 0..len {
+					let current_ratio = assignment.1[i % len].1;
+					let next_ratio = current_ratio
+						.saturating_add(Perbill::from_parts(diff_per_vote));
+					assignment.1[i % len].1 = next_ratio;
+				}
+			}
+
+			// `remainder` is set to be less than maximum votes of a nominator (currently 16).
+			// safe to cast it to usize.
+			let remainder = diff - diff_per_vote * vote_count;
+			for i in 0..remainder as usize {
+				let current_ratio = assignment.1[i % len].1;
+				let next_ratio = current_ratio.saturating_add(Perbill::from_parts(1));
+				assignment.1[i % len].1 = next_ratio;
+			}
+			assigned.push(assignment);
+		}
+	}
+
+	Some(PhragmenResult {
+		winners: elected_candidates,
+		assignments: assigned,
+	})
+}
+
+/// Build the support map from the given phragmen result.
+pub fn build_support_map<Balance, AccountId, FS, C>(
+	elected_stashes: &Vec<AccountId>,
+	assignments: &Vec<(AccountId, Vec<PhragmenAssignment<AccountId>>)>,
+	stake_of: FS,
+) -> SupportMap<AccountId> where
+	AccountId: Default + Ord + Member,
+	Balance: Default + Copy + SimpleArithmetic,
+	C: Convert<Balance, u64> + Convert<u128, Balance>,
+	for<'r> FS: Fn(&'r AccountId) -> Balance,
+{
+	let to_votes = |b: Balance| <C as Convert<Balance, u64>>::convert(b) as ExtendedBalance;
+	// Initialize the support of each candidate.
+	let mut supports = <SupportMap<AccountId>>::new();
+	elected_stashes
+		.iter()
+		.for_each(|e| { supports.insert(e.clone(), Default::default()); });
+
+	// build support struct.
+	for (n, assignment) in assignments.iter() {
+		for (c, per_thing) in assignment.iter() {
+			let nominator_stake = to_votes(stake_of(n));
+			// AUDIT: it is crucially important for the `Mul` implementation of all
+			// per-things to be sound.
+			let other_stake = *per_thing * nominator_stake;
+			if let Some(support) = supports.get_mut(c) {
+				if c == n {
+					// This is a nomination from `n` to themselves. This will increase both the
+					// `own` and `total` field.
+					debug_assert!(*per_thing == Perbill::one()); // TODO: deal with this: do we want it?
+					support.own = support.own.saturating_add(other_stake);
+					support.total = support.total.saturating_add(other_stake);
+				} else {
+					// This is a nomination from `n` to someone else. Increase `total` and add an entry
+					// inside `others`.
+					// For an astronomically rich validator with more astronomically rich
+					// set of nominators, this might saturate.
+					support.total = support.total.saturating_add(other_stake);
+					support.others.push((n.clone(), other_stake));
+				}
+			}
+		}
+	}
+	supports
+}
+
+/// Performs equalize post-processing to the output of the election algorithm. This happens in
+/// rounds. The number of rounds and the maximum diff-per-round tolerance can be tuned through input
+/// parameters.
+///
+/// No value is returned from the function and the `supports` parameter is updated.
+///
+/// * `assignments`: exactly the same is the output of phragmen.
+/// * `supports`: mutable reference to s `SupportMap`. This parameter is updated.
+/// * `tolerance`: maximum difference that can occur before an early quite happens.
+/// * `iterations`: maximum number of iterations that will be processed.
+/// * `stake_of`: something that can return the stake stake of a particular candidate or voter.
+pub fn equalize<Balance, AccountId, C, FS>(
+	mut assignments: Vec<(AccountId, Vec<PhragmenStakedAssignment<AccountId>>)>,
+	supports: &mut SupportMap<AccountId>,
+	tolerance: ExtendedBalance,
+	iterations: usize,
+	stake_of: FS,
+) where
+	C: Convert<Balance, u64> + Convert<u128, Balance>,
+	for<'r> FS: Fn(&'r AccountId) -> Balance,
+	AccountId: Ord + Clone,
+{
+	// prepare the data for equalise
+	for _i in 0..iterations {
+		let mut max_diff = 0;
+
+		for (voter, assignment) in assignments.iter_mut() {
+			let voter_budget = stake_of(&voter);
+
+			let diff = do_equalize::<_, _, C>(
+				voter,
+				voter_budget,
+				assignment,
+				supports,
+				tolerance,
+			);
+			if diff > max_diff { max_diff = diff; }
+		}
+
+		if max_diff < tolerance {
+			break;
+		}
+	}
+}
+
+/// actually perform equalize. same interface is `equalize`. Just called in loops with a check for
+/// maximum difference.
+fn do_equalize<Balance, AccountId, C>(
+	voter: &AccountId,
+	budget_balance: Balance,
+	elected_edges: &mut Vec<PhragmenStakedAssignment<AccountId>>,
+	support_map: &mut SupportMap<AccountId>,
+	tolerance: ExtendedBalance
+) -> ExtendedBalance where
+	C: Convert<Balance, u64> + Convert<u128, Balance>,
+	AccountId: Ord + Clone,
+{
+	let to_votes = |b: Balance|
+		<C as Convert<Balance, u64>>::convert(b) as ExtendedBalance;
+	let budget = to_votes(budget_balance);
+
+	// Nothing to do. This voter had nothing useful.
+	// Defensive only. Assignment list should always be populated.
+	if elected_edges.is_empty() { return 0; }
+
+	let stake_used = elected_edges
+		.iter()
+		.fold(0 as ExtendedBalance, |s, e| s.saturating_add(e.1));
+
+	let backed_stakes_iter = elected_edges
+		.iter()
+		.filter_map(|e| support_map.get(&e.0))
+		.map(|e| e.total);
+
+	let backing_backed_stake = elected_edges
+		.iter()
+		.filter(|e| e.1 > 0)
+		.filter_map(|e| support_map.get(&e.0))
+		.map(|e| e.total)
+		.collect::<Vec<ExtendedBalance>>();
+
+	let mut difference;
+	if backing_backed_stake.len() > 0 {
+		let max_stake = backing_backed_stake
+			.iter()
+			.max()
+			.expect("vector with positive length will have a max; qed");
+		let min_stake = backed_stakes_iter
+			.min()
+			.expect("iterator with positive length will have a min; qed");
+
+		difference = max_stake.saturating_sub(min_stake);
+		difference = difference.saturating_add(budget.saturating_sub(stake_used));
+		if difference < tolerance {
+			return difference;
+		}
+	} else {
+		difference = budget;
+	}
+
+	// Undo updates to support
+	elected_edges.iter_mut().for_each(|e| {
+		if let Some(support) = support_map.get_mut(&e.0) {
+			support.total = support.total.saturating_sub(e.1);
+			support.others.retain(|i_support| i_support.0 != *voter);
+		}
+		e.1 = 0;
+	});
+
+	elected_edges.sort_unstable_by_key(|e|
+		if let Some(e) = support_map.get(&e.0) { e.total } else { Zero::zero() }
+	);
+
+	let mut cumulative_stake: ExtendedBalance = 0;
+	let mut last_index = elected_edges.len() - 1;
+	let mut idx = 0usize;
+	for e in &mut elected_edges[..] {
+		if let Some(support) = support_map.get_mut(&e.0) {
+			let stake = support.total;
+			let stake_mul = stake.saturating_mul(idx as ExtendedBalance);
+			let stake_sub = stake_mul.saturating_sub(cumulative_stake);
+			if stake_sub > budget {
+				last_index = idx.checked_sub(1).unwrap_or(0);
+				break;
+			}
+			cumulative_stake = cumulative_stake.saturating_add(stake);
+		}
+		idx += 1;
+	}
+
+	let last_stake = elected_edges[last_index].1;
+	let split_ways = last_index + 1;
+	let excess = budget
+		.saturating_add(cumulative_stake)
+		.saturating_sub(last_stake.saturating_mul(split_ways as ExtendedBalance));
+	elected_edges.iter_mut().take(split_ways).for_each(|e| {
+		if let Some(support) = support_map.get_mut(&e.0) {
+			e.1 = (excess / split_ways as ExtendedBalance)
+				.saturating_add(last_stake)
+				.saturating_sub(support.total);
+			support.total = support.total.saturating_add(e.1);
+			support.others.push((voter.clone(), e.1));
+		}
+	});
+
+	difference
+}
@@ -0,0 +1,412 @@
+// Copyright 2019 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Mock file for phragmen.
+
+#![cfg(test)]
+
+use crate::{elect, PhragmenResult, PhragmenAssignment};
+use sr_primitives::{
+	assert_eq_error_rate, Perbill,
+	traits::{Convert, Member, SaturatedConversion}
+};
+use rstd::collections::btree_map::BTreeMap;
+
+pub(crate) struct TestCurrencyToVote;
+impl Convert<Balance, u64> for TestCurrencyToVote {
+	fn convert(x: Balance) -> u64 { x.saturated_into() }
+}
+impl Convert<u128, Balance> for TestCurrencyToVote {
+	fn convert(x: u128) -> Balance { x }
+}
+
+#[derive(Default, Debug)]
+pub(crate) struct _Candidate<A> {
+	who: A,
+	score: f64,
+	approval_stake: f64,
+	elected: bool,
+}
+
+#[derive(Default, Debug)]
+pub(crate) struct _Voter<A> {
+	who: A,
+	edges: Vec<_Edge<A>>,
+	budget: f64,
+	load: f64,
+}
+
+#[derive(Default, Debug)]
+pub(crate) struct _Edge<A> {
+	who: A,
+	load: f64,
+	candidate_index: usize,
+}
+
+#[derive(Default, Debug, PartialEq)]
+pub(crate) struct _Support<A> {
+	pub own: f64,
+	pub total: f64,
+	pub others: Vec<_PhragmenAssignment<A>>,
+}
+
+pub(crate) type _PhragmenAssignment<A> = (A, f64);
+pub(crate) type _SupportMap<A> = BTreeMap<A, _Support<A>>;
+
+pub(crate) type Balance = u128;
+pub(crate) type AccountId = u64;
+
+#[derive(Debug, Clone)]
+pub(crate) struct _PhragmenResult<A: Clone> {
+	pub winners: Vec<(A, Balance)>,
+	pub assignments: Vec<(A, Vec<_PhragmenAssignment<A>>)>
+}
+
+pub(crate) fn auto_generate_self_voters<A: Clone>(candidates: &[A]) -> Vec<(A, Vec<A>)> {
+	candidates.iter().map(|c| (c.clone(), vec![c.clone()])).collect()
+}
+
+pub(crate) fn elect_float<A, FS>(
+	candidate_count: usize,
+	minimum_candidate_count: usize,
+	initial_candidates: Vec<A>,
+	initial_voters: Vec<(A, Vec<A>)>,
+	stake_of: FS,
+) -> Option<_PhragmenResult<A>> where
+	A: Default + Ord + Member + Copy,
+	for<'r> FS: Fn(&'r A) -> Balance,
+{
+	let mut elected_candidates: Vec<(A, Balance)>;
+	let mut assigned: Vec<(A, Vec<_PhragmenAssignment<A>>)>;
+	let mut c_idx_cache = BTreeMap::<A, usize>::new();
+	let num_voters = initial_candidates.len() + initial_voters.len();
+	let mut voters: Vec<_Voter<A>> = Vec::with_capacity(num_voters);
+
+	let mut candidates = initial_candidates
+		.into_iter()
+		.enumerate()
+		.map(|(idx, who)| {
+			c_idx_cache.insert(who.clone(), idx);
+			_Candidate { who, ..Default::default() }
+		})
+		.collect::<Vec<_Candidate<A>>>();
+
+	if candidates.len() < minimum_candidate_count {
+		return None;
+	}
+
+	voters.extend(initial_voters.into_iter().map(|(who, votes)| {
+		let voter_stake = stake_of(&who) as f64;
+		let mut edges: Vec<_Edge<A>> = Vec::with_capacity(votes.len());
+		for v in votes {
+			if let Some(idx) = c_idx_cache.get(&v) {
+				candidates[*idx].approval_stake = candidates[*idx].approval_stake + voter_stake;
+				edges.push(
+					_Edge { who: v.clone(), candidate_index: *idx, ..Default::default() }
+				);
+			}
+		}
+		_Voter {
+			who,
+			edges: edges,
+			budget: voter_stake,
+			load: 0f64,
+		}
+	}));
+
+	let to_elect = candidate_count.min(candidates.len());
+	elected_candidates = Vec::with_capacity(candidate_count);
+	assigned = Vec::with_capacity(candidate_count);
+
+	for _round in 0..to_elect {
+		for c in &mut candidates {
+			if !c.elected {
+				c.score = 1.0 / c.approval_stake;
+			}
+		}
+		for n in &voters {
+			for e in &n.edges {
+				let c = &mut candidates[e.candidate_index];
+				if !c.elected && !(c.approval_stake == 0f64) {
+					c.score += n.budget * n.load / c.approval_stake;
+				}
+			}
+		}
+
+		if let Some(winner) = candidates
+			.iter_mut()
+			.filter(|c| !c.elected)
+			.min_by(|x, y| x.score.partial_cmp(&y.score).unwrap_or(rstd::cmp::Ordering::Equal))
+		{
+			winner.elected = true;
+			for n in &mut voters {
+				for e in &mut n.edges {
+					if e.who == winner.who {
+						e.load = winner.score - n.load;
+						n.load = winner.score;
+					}
+				}
+			}
+
+			elected_candidates.push((winner.who.clone(), winner.approval_stake as Balance));
+		} else {
+			break
+		}
+	}
+
+	for n in &mut voters {
+		let mut assignment = (n.who.clone(), vec![]);
+		for e in &mut n.edges {
+			if let Some(c) = elected_candidates.iter().cloned().map(|(c, _)| c).find(|c| *c == e.who) {
+				if c != n.who {
+					let ratio = e.load / n.load;
+					assignment.1.push((e.who.clone(), ratio));
+				}
+			}
+		}
+		if assignment.1.len() > 0 {
+			assigned.push(assignment);
+		}
+	}
+
+	Some(_PhragmenResult {
+		winners: elected_candidates,
+		assignments: assigned,
+	})
+}
+
+pub(crate) fn equalize_float<A, FS>(
+	mut assignments: Vec<(A, Vec<_PhragmenAssignment<A>>)>,
+	supports: &mut _SupportMap<A>,
+	tolerance: f64,
+	iterations: usize,
+	stake_of: FS,
+) where
+	for<'r> FS: Fn(&'r A) -> Balance,
+	A: Ord + Clone + std::fmt::Debug,
+{
+	for _i in 0..iterations {
+		let mut max_diff = 0.0;
+		for (voter, assignment) in assignments.iter_mut() {
+			let voter_budget = stake_of(&voter);
+			let diff = do_equalize_float(
+				voter,
+				voter_budget,
+				assignment,
+				supports,
+				tolerance,
+			);
+			if diff > max_diff { max_diff = diff; }
+		}
+
+		if max_diff < tolerance {
+			break;
+		}
+	}
+}
+
+pub(crate) fn do_equalize_float<A>(
+	voter: &A,
+	budget_balance: Balance,
+	elected_edges: &mut Vec<_PhragmenAssignment<A>>,
+	support_map: &mut _SupportMap<A>,
+	tolerance: f64
+) -> f64 where
+	A: Ord + Clone,
+{
+	let budget = budget_balance as f64;
+	if elected_edges.is_empty() { return 0.0; }
+
+	let stake_used = elected_edges
+		.iter()
+		.fold(0.0, |s, e| s + e.1);
+
+	let backed_stakes_iter = elected_edges
+		.iter()
+		.filter_map(|e| support_map.get(&e.0))
+		.map(|e| e.total);
+
+	let backing_backed_stake = elected_edges
+		.iter()
+		.filter(|e| e.1 > 0.0)
+		.filter_map(|e| support_map.get(&e.0))
+		.map(|e| e.total)
+		.collect::<Vec<f64>>();
+
+	let mut difference;
+	if backing_backed_stake.len() > 0 {
+		let max_stake = backing_backed_stake
+			.iter()
+			.max_by(|x, y| x.partial_cmp(&y).unwrap_or(rstd::cmp::Ordering::Equal))
+			.expect("vector with positive length will have a max; qed");
+		let min_stake = backed_stakes_iter
+			.min_by(|x, y| x.partial_cmp(&y).unwrap_or(rstd::cmp::Ordering::Equal))
+			.expect("iterator with positive length will have a min; qed");
+
+		difference = max_stake - min_stake;
+		difference = difference + budget - stake_used;
+		if difference < tolerance {
+			return difference;
+		}
+	} else {
+		difference = budget;
+	}
+
+	// Undo updates to support
+	elected_edges.iter_mut().for_each(|e| {
+		if let Some(support) = support_map.get_mut(&e.0) {
+			support.total = support.total - e.1;
+			support.others.retain(|i_support| i_support.0 != *voter);
+		}
+		e.1 = 0.0;
+	});
+
+	// todo: rewrite.
+	elected_edges.sort_unstable_by(|x, y|
+		if let Some(x) = support_map.get(&x.0) {
+			if let Some(y) = support_map.get(&y.0) {
+				x.total.partial_cmp(&y.total).unwrap_or(rstd::cmp::Ordering::Equal)
+			} else {
+				rstd::cmp::Ordering::Equal
+			}
+		} else {
+			rstd::cmp::Ordering::Equal
+		}
+	);
+
+	let mut cumulative_stake = 0.0;
+	let mut last_index = elected_edges.len() - 1;
+	elected_edges.iter_mut().enumerate().for_each(|(idx, e)| {
+		if let Some(support) = support_map.get_mut(&e.0) {
+			let stake = support.total;
+			let stake_mul = stake * (idx as f64);
+			let stake_sub = stake_mul - cumulative_stake;
+			if stake_sub > budget {
+				last_index = idx.checked_sub(1).unwrap_or(0);
+				return
+			}
+			cumulative_stake = cumulative_stake + stake;
+		}
+	});
+
+	let last_stake = elected_edges[last_index].1;
+	let split_ways = last_index + 1;
+	let excess = budget + cumulative_stake - last_stake * (split_ways as f64);
+	elected_edges.iter_mut().take(split_ways).for_each(|e| {
+		if let Some(support) = support_map.get_mut(&e.0) {
+			e.1 = excess / (split_ways as f64) + last_stake - support.total;
+			support.total = support.total + e.1;
+			support.others.push((voter.clone(), e.1));
+		}
+	});
+
+	difference
+}
+
+
+pub(crate) fn create_stake_of(stakes: &[(AccountId, Balance)])
+	-> Box<dyn Fn(&AccountId) -> Balance>
+{
+	let mut storage = BTreeMap::<AccountId, Balance>::new();
+	stakes.iter().for_each(|s| { storage.insert(s.0, s.1); });
+	let stake_of = move |who: &AccountId| -> Balance { storage.get(who).unwrap().to_owned() };
+	Box::new(stake_of)
+}
+
+
+pub fn check_assignments(assignments: Vec<(AccountId, Vec<PhragmenAssignment<AccountId>>)>) {
+	for (_, a) in assignments {
+		let sum: u32 = a.iter().map(|(_, p)| p.deconstruct()).sum();
+		assert_eq_error_rate!(sum, Perbill::accuracy(), 5);
+	}
+}
+
+pub(crate) fn run_and_compare(
+	candidates: Vec<AccountId>,
+	voters: Vec<(AccountId, Vec<AccountId>)>,
+	stake_of: Box<dyn Fn(&AccountId) -> Balance>,
+	to_elect: usize,
+	min_to_elect: usize,
+) {
+	// run fixed point code.
+	let PhragmenResult { winners, assignments } = elect::<_, _, _, TestCurrencyToVote>(
+		to_elect,
+		min_to_elect,
+		candidates.clone(),
+		voters.clone(),
+		&stake_of,
+	).unwrap();
+
+	// run float poc code.
+	let truth_value = elect_float(
+		to_elect,
+		min_to_elect,
+		candidates,
+		voters,
+		&stake_of,
+	).unwrap();
+
+	assert_eq!(winners, truth_value.winners);
+
+	for (nominator, assigned) in assignments.clone() {
+		if let Some(float_assignments) = truth_value.assignments.iter().find(|x| x.0 == nominator) {
+			for (candidate, per_thingy) in assigned {
+				if let Some(float_assignment) = float_assignments.1.iter().find(|x| x.0 == candidate ) {
+					assert_eq_error_rate!(
+						Perbill::from_fraction(float_assignment.1).deconstruct(),
+						per_thingy.deconstruct(),
+						1,
+					);
+				} else {
+					panic!("candidate mismatch. This should never happen.")
+				}
+			}
+		} else {
+			panic!("nominator mismatch. This should never happen.")
+		}
+	}
+
+	check_assignments(assignments);
+}
+
+pub(crate) fn build_support_map<FS>(
+	result: &mut _PhragmenResult<AccountId>,
+	stake_of: FS,
+) -> _SupportMap<AccountId>
+	where for<'r> FS: Fn(&'r AccountId) -> Balance
+{
+	let mut supports = <_SupportMap<AccountId>>::new();
+	result.winners
+		.iter()
+		.map(|(e, _)| (e, stake_of(e) as f64))
+		.for_each(|(e, s)| {
+			let item = _Support { own: s, total: s, ..Default::default() };
+			supports.insert(e.clone(), item);
+		});
+
+	for (n, assignment) in result.assignments.iter_mut() {
+		for (c, r) in assignment.iter_mut() {
+			let nominator_stake = stake_of(n) as f64;
+			let other_stake = nominator_stake * *r;
+			if let Some(support) = supports.get_mut(c) {
+				support.total = support.total + other_stake;
+				support.others.push((n.clone(), other_stake));
+			}
+			*r = other_stake;
+		}
+	}
+	supports
+}
@@ -0,0 +1,356 @@
+// Copyright 2019 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Tests for phragmen.
+
+#![cfg(test)]
+
+use crate::mock::*;
+use crate::{elect, PhragmenResult};
+use support::assert_eq_uvec;
+use sr_primitives::Perbill;
+
+#[test]
+fn float_phragmen_poc_works() {
+	let candidates = vec![1, 2, 3];
+	let voters = vec![
+		(10, vec![1, 2]),
+		(20, vec![1, 3]),
+		(30, vec![2, 3]),
+	];
+	let stake_of = create_stake_of(&[(10, 10), (20, 20), (30, 30), (1, 0), (2, 0), (3, 0)]);
+	let mut phragmen_result = elect_float(2, 2, candidates, voters, &stake_of).unwrap();
+	let winners = phragmen_result.clone().winners;
+	let assignments = phragmen_result.clone().assignments;
+
+	assert_eq_uvec!(winners, vec![(2, 40), (3, 50)]);
+	assert_eq_uvec!(
+		assignments,
+		vec![
+			(10, vec![(2, 1.0)]),
+			(20, vec![(3, 1.0)]),
+			(30, vec![(2, 0.5), (3, 0.5)]),
+		]
+	);
+
+	let mut support_map = build_support_map(&mut phragmen_result, &stake_of);
+
+	assert_eq!(
+		support_map.get(&2).unwrap(),
+		&_Support { own: 0.0, total: 25.0, others: vec![(10u64, 10.0), (30u64, 15.0)]}
+	);
+	assert_eq!(
+		support_map.get(&3).unwrap(),
+		&_Support { own: 0.0, total: 35.0, others: vec![(20u64, 20.0), (30u64, 15.0)]}
+	);
+
+	equalize_float(phragmen_result.assignments, &mut support_map, 0.0, 2, stake_of);
+
+	assert_eq!(
+		support_map.get(&2).unwrap(),
+		&_Support { own: 0.0, total: 30.0, others: vec![(10u64, 10.0), (30u64, 20.0)]}
+	);
+	assert_eq!(
+		support_map.get(&3).unwrap(),
+		&_Support { own: 0.0, total: 30.0, others: vec![(20u64, 20.0), (30u64, 10.0)]}
+	);
+}
+
+#[test]
+fn phragmen_poc_works() {
+	let candidates = vec![1, 2, 3];
+	let voters = vec![
+		(10, vec![1, 2]),
+		(20, vec![1, 3]),
+		(30, vec![2, 3]),
+	];
+
+	let PhragmenResult { winners, assignments } = elect::<_, _, _, TestCurrencyToVote>(
+		2,
+		2,
+		candidates,
+		voters,
+		create_stake_of(&[(10, 10), (20, 20), (30, 30)]),
+	).unwrap();
+
+	assert_eq_uvec!(winners, vec![(2, 40), (3, 50)]);
+	assert_eq_uvec!(
+		assignments,
+		vec![
+			(10, vec![(2, Perbill::from_percent(100))]),
+			(20, vec![(3, Perbill::from_percent(100))]),
+			(30, vec![(2, Perbill::from_percent(100/2)), (3, Perbill::from_percent(100/2))]),
+		]
+	);
+}
+
+#[test]
+fn phragmen_poc_2_works() {
+	let candidates = vec![10, 20, 30];
+	let voters = vec![
+		(2, vec![10, 20, 30]),
+		(4, vec![10, 20, 40]),
+	];
+	let stake_of = create_stake_of(&[
+		(10, 1000),
+		(20, 1000),
+		(30, 1000),
+		(40, 1000),
+		(2, 500),
+		(4, 500),
+	]);
+
+	run_and_compare(candidates, voters, stake_of, 2, 2);
+}
+
+#[test]
+fn phragmen_poc_3_works() {
+	let candidates = vec![10, 20, 30];
+	let voters = vec![
+		(2, vec![10, 20, 30]),
+		(4, vec![10, 20, 40]),
+	];
+	let stake_of = create_stake_of(&[
+		(10, 1000),
+		(20, 1000),
+		(30, 1000),
+		(2, 50),
+		(4, 1000),
+	]);
+
+	run_and_compare(candidates, voters, stake_of, 2, 2);
+}
+
+#[test]
+fn phragmen_accuracy_on_large_scale_only_validators() {
+	// because of this particular situation we had per_u128 and now rational128. In practice, a
+	// candidate can have the maximum amount of tokens, and also supported by the maximum.
+	let candidates = vec![1, 2, 3, 4, 5];
+	let stake_of = create_stake_of(&[
+		(1, (u64::max_value() - 1).into()),
+		(2, (u64::max_value() - 4).into()),
+		(3, (u64::max_value() - 5).into()),
+		(4, (u64::max_value() - 3).into()),
+		(5, (u64::max_value() - 2).into()),
+	]);
+
+	let PhragmenResult { winners, assignments } = elect::<_, _, _, TestCurrencyToVote>(
+		2,
+		2,
+		candidates.clone(),
+		auto_generate_self_voters(&candidates),
+		stake_of,
+	).unwrap();
+
+	assert_eq_uvec!(winners, vec![(1, 18446744073709551614u128), (5, 18446744073709551613u128)]);
+	assert_eq!(assignments.len(), 2);
+	check_assignments(assignments);
+}
+
+#[test]
+fn phragmen_accuracy_on_large_scale_validators_and_nominators() {
+	let candidates = vec![1, 2, 3, 4, 5];
+	let mut voters = vec![
+		(13, vec![1, 3, 5]),
+		(14, vec![2, 4]),
+	];
+	voters.extend(auto_generate_self_voters(&candidates));
+	let stake_of = create_stake_of(&[
+		(1,  (u64::max_value() - 1).into()),
+		(2,  (u64::max_value() - 4).into()),
+		(3,  (u64::max_value() - 5).into()),
+		(4,  (u64::max_value() - 3).into()),
+		(5,  (u64::max_value() - 2).into()),
+		(13, (u64::max_value() - 10).into()),
+		(14, u64::max_value().into()),
+	]);
+
+	let PhragmenResult { winners, assignments } = elect::<_, _, _, TestCurrencyToVote>(
+		2,
+		2,
+		candidates,
+		voters,
+		stake_of,
+	).unwrap();
+
+	assert_eq_uvec!(winners, vec![(2, 36893488147419103226u128), (1, 36893488147419103219u128)]);
+	assert_eq!(
+		assignments,
+		vec![
+			(13, vec![(1, Perbill::one())]),
+			(14, vec![(2, Perbill::one())]),
+			(1, vec![(1, Perbill::one())]),
+			(2, vec![(2, Perbill::one())]),
+		]
+	);
+	check_assignments(assignments);
+}
+
+#[test]
+fn phragmen_accuracy_on_small_scale_self_vote() {
+	let candidates = vec![40, 10, 20, 30];
+	let voters = auto_generate_self_voters(&candidates);
+	let stake_of = create_stake_of(&[
+		(40, 0),
+		(10, 1),
+		(20, 2),
+		(30, 1),
+	]);
+
+	let PhragmenResult { winners, assignments: _ } = elect::<_, _, _, TestCurrencyToVote>(
+		3,
+		3,
+		candidates,
+		voters,
+		stake_of,
+	).unwrap();
+
+	assert_eq_uvec!(winners, vec![(20, 2), (10, 1), (30, 1)]);
+}
+
+#[test]
+fn phragmen_accuracy_on_small_scale_no_self_vote() {
+	let candidates = vec![40, 10, 20, 30];
+	let voters = vec![
+		(1, vec![10]),
+		(2, vec![20]),
+		(3, vec![30]),
+		(4, vec![40]),
+	];
+	let stake_of = create_stake_of(&[
+		(40, 1000), // don't care
+		(10, 1000), // don't care
+		(20, 1000), // don't care
+		(30, 1000), // don't care
+		(4, 0),
+		(1, 1),
+		(2, 2),
+		(3, 1),
+	]);
+
+	let PhragmenResult { winners, assignments: _ } = elect::<_, _, _, TestCurrencyToVote>(
+		3,
+		3,
+		candidates,
+		voters,
+		stake_of,
+	).unwrap();
+
+	assert_eq_uvec!(winners, vec![(20, 2), (10, 1), (30, 1)]);
+}
+
+#[test]
+fn phragmen_large_scale_test() {
+	let candidates = vec![2, 4, 6, 8, 10, 12, 14, 16 ,18, 20, 22, 24];
+	let mut voters = vec![
+		(50, vec![2, 4, 6, 8, 10, 12, 14, 16 ,18, 20, 22, 24]),
+	];
+	voters.extend(auto_generate_self_voters(&candidates));
+	let stake_of = create_stake_of(&[
+		(2,  1),
+		(4,  100),
+		(6,  1000000),
+		(8,  100000000001000),
+		(10, 100000000002000),
+		(12, 100000000003000),
+		(14, 400000000000000),
+		(16, 400000000001000),
+		(18, 18000000000000000),
+		(20, 20000000000000000),
+		(22, 500000000000100000),
+		(24, 500000000000200000),
+		(50, 990000000000000000),
+	]);
+
+	let PhragmenResult { winners, assignments } = elect::<_, _, _, TestCurrencyToVote>(
+		2,
+		2,
+		candidates,
+		voters,
+		stake_of,
+	).unwrap();
+
+	assert_eq_uvec!(winners, vec![(24, 1490000000000200000u128), (22, 1490000000000100000u128)]);
+	check_assignments(assignments);
+}
+
+#[test]
+fn phragmen_large_scale_test_2() {
+	let nom_budget: u64 = 1_000_000_000_000_000_000;
+	let c_budget: u64 = 4_000_000;
+
+	let candidates = vec![2, 4];
+	let mut voters = vec![(50, vec![2, 4])];
+	voters.extend(auto_generate_self_voters(&candidates));
+
+	let stake_of = create_stake_of(&[
+		(2,  c_budget.into()),
+		(4,  c_budget.into()),
+		(50, nom_budget.into()),
+	]);
+
+	let PhragmenResult { winners, assignments } = elect::<_, _, _, TestCurrencyToVote>(
+		2,
+		2,
+		candidates,
+		voters,
+		stake_of,
+	).unwrap();
+
+	assert_eq_uvec!(winners, vec![(2, 1000000000004000000u128), (4, 1000000000004000000u128)]);
+	assert_eq!(
+		assignments,
+		vec![
+			(50, vec![(2, Perbill::from_parts(500000001)), (4, Perbill::from_parts(499999999))]),
+			(2, vec![(2, Perbill::one())]),
+			(4, vec![(4, Perbill::one())]),
+		],
+	);
+	check_assignments(assignments);
+}
+
+#[test]
+fn phragmen_linear_equalize() {
+	let candidates = vec![11, 21, 31, 41, 51, 61, 71];
+	let voters = vec![
+		(2, vec![11]),
+		(4, vec![11, 21]),
+		(6, vec![21, 31]),
+		(8, vec![31, 41]),
+		(110, vec![41, 51]),
+		(120, vec![51, 61]),
+		(130, vec![61, 71]),
+	];
+	let stake_of = create_stake_of(&[
+		(11, 1000),
+		(21, 1000),
+		(31, 1000),
+		(41, 1000),
+		(51, 1000),
+		(61, 1000),
+		(71, 1000),
+
+		(2, 2000),
+		(4, 1000),
+		(6, 1000),
+		(8, 1000),
+		(110, 1000),
+		(120, 1000),
+		(130, 1000),
+	]);
+
+	run_and_compare(candidates, voters, stake_of, 2, 2);
+}