PhragMMS election. (#6685)

* Revamp npos-elections and implement phragmms * Update primitives/npos-elections/src/phragmms.rs * Fix build * Some review grumbles * Add some stuff for remote testing * fix some of the grumbles. * Add remote testing stuff. * Cleanup * fix docs * Update primitives/arithmetic/src/rational.rs Co-authored-by: Dan Forbes <dan@danforbes.dev> * Small config change * Better handling of approval_stake == 0 * Final touhces. * Clean fuzzer a bit * Clean fuzzer a bit * Update primitives/npos-elections/src/balancing.rs Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com> * Fix fuzzer. * Better api for normalize * Add noramlize_up * A large number of small fixes. * make it merge ready * Fix warns * bump * Fix fuzzers a bit. * Fix warns as well. * Fix more tests. Co-authored-by: Dan Forbes <dan@danforbes.dev> Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>
2026-07-25 03:35:43 +00:00 · 2020-09-23 10:16:10 +02:00
parent ecdc94420e
commit 313f86ec23
32 changed files with 2074 additions and 914 deletions
@@ -1,58 +1,109 @@
 // This file is part of Substrate.

-// Copyright (C) 2019-2020 Parity Technologies (UK) Ltd.
-// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2019-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
+// 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
+//  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.
+// 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.

 //! A set of election algorithms to be used with a substrate runtime, typically within the staking
-//! sub-system. Notable implementation include
+//! sub-system. Notable implementation include:
 //!
 //! - [`seq_phragmen`]: Implements the Phragmén Sequential Method. An un-ranked, relatively fast
 //!   election method that ensures PJR, but does not provide a constant factor approximation of the
 //!   maximin problem.
-//! - [`balance_solution`]: Implements the star balancing algorithm. This iterative process can
-//!   increase a solutions score, as described in [`evaluate_support`].
+//! - [`phragmms`]: Implements a hybrid approach inspired by Phragmén which is executed faster but
+//!   it can achieve a constant factor approximation of the maximin problem, similar to that of the
+//!   MMS algorithm.
+//! - [`balance_solution`]: Implements the star balancing algorithm. This iterative process can push
+//!   a solution toward being more `balances`, which in turn can increase its score.
+//!
+//! ### Terminology
+//!
+//! This crate uses context-independent words, not to be confused with staking. This is because the
+//! election algorithms of this crate, while designed for staking, can be used in other contexts as
+//! well.
+//!
+//! `Voter`: The entity casting some votes to a number of `Targets`. This is the same as `Nominator`
+//! in the context of staking. `Target`: The entities eligible to be voted upon. This is the same as
+//! `Validator` in the context of staking. `Edge`: A mapping from a `Voter` to a `Target`.
+//!
+//! The goal of an election algorithm is to provide an `ElectionResult`. A data composed of:
+//! - `winners`: A flat list of identifiers belonging to those who have won the election, usually
+//!   ordered in some meaningful way. They are zipped with their total backing stake.
+//! - `assignment`: A mapping from each voter to their winner-only targets, zipped with a ration
+//!   denoting the amount of support given to that particular target.
+//!
+//! ```rust
+//! # use sp_npos_elections::*;
+//! # use sp_runtime::Perbill;
+//! // the winners.
+//! let winners = vec![(1, 100), (2, 50)];
+//! let assignments = vec![
+//!     // A voter, giving equal backing to both 1 and 2.
+//!     Assignment {
+//! 		who: 10,
+//! 		distribution: vec![(1, Perbill::from_percent(50)), (2, Perbill::from_percent(50))],
+//! 	},
+//!     // A voter, Only backing 1.
+//!     Assignment { who: 20, distribution: vec![(1, Perbill::from_percent(100))] },
+//! ];
+//!
+//! // the combination of the two makes the election result.
+//! let election_result = ElectionResult { winners, assignments };
+//!
+//! ```
+//!
+//! The `Assignment` field of the election result is voter-major, i.e. it is from the perspective of
+//! the voter. The struct that represents the opposite is called a `Support`. This struct is usually
+//! accessed in a map-like manner, i.e. keyed vy voters, therefor it is stored as a mapping called
+//! `SupportMap`.
+//!
+//! Moreover, the support is built from absolute backing values, not ratios like the example above.
+//! A struct similar to `Assignment` that has stake value instead of ratios is called an
+//! `StakedAssignment`.
+//!
 //!
 //! More information can be found at: https://arxiv.org/abs/2004.12990

 #![cfg_attr(not(feature = "std"), no_std)]

-use sp_std::{prelude::*, collections::btree_map::BTreeMap, fmt::Debug, cmp::Ordering, convert::TryFrom};
+use sp_std::{
+	prelude::*, collections::btree_map::BTreeMap, fmt::Debug, cmp::Ordering, rc::Rc, cell::RefCell,
+};
 use sp_arithmetic::{
 	PerThing, Rational128, ThresholdOrd, InnerOf, Normalizable,
-	helpers_128bit::multiply_by_rational,
-	traits::{Zero, Saturating, Bounded, SaturatedConversion},
+	traits::{Zero, Bounded},
 };

-#[cfg(test)]
-mod mock;
-#[cfg(test)]
-mod tests;
 #[cfg(feature = "std")]
 use serde::{Serialize, Deserialize};
 #[cfg(feature = "std")]
 use codec::{Encode, Decode};

+#[cfg(test)]
+mod mock;
+#[cfg(test)]
+mod tests;
+
+mod phragmen;
+mod balancing;
+mod phragmms;
 mod node;
 mod reduce;
 mod helpers;

-// re-export reduce stuff.
 pub use reduce::reduce;
-
-// re-export the helpers.
 pub use helpers::*;
+pub use phragmen::*;
+pub use phragmms::*;
+pub use balancing::*;

 // re-export the compact macro, with the dependencies of the macro.
 #[doc(hidden)]
@@ -91,8 +142,8 @@ impl<T: Clone + Eq + Default + Ord + Debug + codec::Codec> IdentifierT for T {}
 /// The errors that might occur in the this crate and compact.
 #[derive(Debug, Eq, PartialEq)]
 pub enum Error {
-	/// While going from compact to staked, the stake of all the edges has gone above the
-	/// total and the last stake cannot be assigned.
+	/// While going from compact to staked, the stake of all the edges has gone above the total and
+	/// the last stake cannot be assigned.
 	CompactStakeOverflow,
 	/// The compact type has a voter who's number of targets is out of bound.
 	CompactTargetOverflow,
@@ -115,57 +166,159 @@ pub type ElectionScore = [ExtendedBalance; 3];
 /// A winner, with their respective approval stake.
 pub type WithApprovalOf<A> = (A, ExtendedBalance);

-/// 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 pointer to a candidate struct with interior mutability.
+pub type CandidatePtr<A> = Rc<RefCell<Candidate<A>>>;

 /// A candidate entity for the election.
-#[derive(Clone, Default, Debug)]
-struct Candidate<AccountId> {
+#[derive(Debug, Clone, Default)]
+pub struct Candidate<AccountId> {
 	/// Identifier.
 	who: AccountId,
-	/// Intermediary value used to sort candidates.
+	/// Score of the candidate.
+	///
+	/// Used differently in seq-phragmen and max-score.
 	score: Rational128,
-	/// Sum of the stake of this candidate based on received votes.
+	/// Approval stake of the candidate. Merely the sum of all the voter's stake who approve this
+	/// candidate.
 	approval_stake: ExtendedBalance,
-	/// Flag for being elected.
+	/// The final stake of this candidate. Will be equal to a subset of approval stake.
+	backed_stake: ExtendedBalance,
+	/// True if this candidate is already elected in the current election.
 	elected: bool,
+	/// The round index at which this candidate was elected.
+	round: usize,
+}
+
+/// A vote being casted by a [`Voter`] to a [`Candidate`] is an `Edge`.
+#[derive(Clone, Default)]
+pub struct Edge<AccountId> {
+	/// Identifier of the target.
+	///
+	/// This is equivalent of `self.candidate.borrow().who`, yet it helps to avoid double borrow
+	/// errors of the candidate pointer.
+	who: AccountId,
+	/// Load of this edge.
+	load: Rational128,
+	/// Pointer to the candidate.
+	candidate: CandidatePtr<AccountId>,
+	/// The weight (i.e. stake given to `who`) of this edge.
+	weight: ExtendedBalance,
+}
+
+#[cfg(feature = "std")]
+impl<A: IdentifierT> sp_std::fmt::Debug for Edge<A> {
+	fn fmt(&self, f: &mut sp_std::fmt::Formatter<'_>) -> sp_std::fmt::Result {
+		write!(f, "Edge({:?}, weight = {:?})", self.who, self.weight)
+	}
 }

 /// A voter entity.
-#[derive(Clone, Default, Debug)]
-struct Voter<AccountId> {
+#[derive(Clone, Default)]
+pub struct Voter<AccountId> {
 	/// Identifier.
 	who: AccountId,
-	/// List of candidates proposed by this voter.
+	/// List of candidates approved 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 of the voter.
 	load: Rational128,
 }

-/// A candidate being backed by a voter.
-#[derive(Clone, Default, Debug)]
-struct Edge<AccountId> {
-	/// Identifier.
-	who: AccountId,
-	/// Load of this vote.
-	load: Rational128,
-	/// Index of the candidate stored in the 'candidates' vector.
-	candidate_index: usize,
+#[cfg(feature = "std")]
+impl<A: IdentifierT> std::fmt::Debug for Voter<A> {
+	fn fmt(&self, f: &mut sp_std::fmt::Formatter<'_>) -> sp_std::fmt::Result {
+		write!(f, "Voter({:?}, budget = {}, edges = {:?})", self.who, self.budget, self.edges)
+	}
+}
+
+impl<AccountId: IdentifierT> Voter<AccountId> {
+	/// Returns none if this voter does not have any non-zero distributions.
+	///
+	/// Note that this might create _un-normalized_ assignments, due to accuracy loss of `P`. Call
+	/// site might compensate by calling `normalize()` on the returned `Assignment` as a
+	/// post-precessing.
+	pub fn into_assignment<P: PerThing>(self) -> Option<Assignment<AccountId, P>>
+	where
+		ExtendedBalance: From<InnerOf<P>>,
+	{
+		let who = self.who;
+		let budget = self.budget;
+		let distribution = self.edges.into_iter().filter_map(|e| {
+			let per_thing = P::from_rational_approximation(e.weight, budget);
+			// trim zero edges.
+			if per_thing.is_zero() { None } else { Some((e.who, per_thing)) }
+		}).collect::<Vec<_>>();
+
+		if distribution.len() > 0 {
+			Some(Assignment { who, distribution })
+		} else {
+			None
+		}
+	}
+
+	/// Try and normalize the votes of self.
+	///
+	/// If the normalization is successful then `Ok(())` is returned.
+	///
+	/// Note that this will not distinguish between elected and unelected edges. Thus, it should
+	/// only be called on a voter who has already been reduced to only elected edges.
+	///
+	/// ### Errors
+	///
+	/// This will return only if the internal `normalize` fails. This can happen if the sum of the
+	/// weights exceeds `ExtendedBalance::max_value()`.
+	pub fn try_normalize(&mut self) -> Result<(), &'static str> {
+		let edge_weights = self.edges.iter().map(|e| e.weight).collect::<Vec<_>>();
+		edge_weights.normalize(self.budget).map(|normalized| {
+			// here we count on the fact that normalize does not change the order.
+			for (edge, corrected) in self.edges.iter_mut().zip(normalized.into_iter()) {
+				let mut candidate = edge.candidate.borrow_mut();
+				// first, subtract the incorrect weight
+				candidate.backed_stake = candidate.backed_stake.saturating_sub(edge.weight);
+				edge.weight = corrected;
+				// Then add the correct one again.
+				candidate.backed_stake = candidate.backed_stake.saturating_add(edge.weight);
+			}
+		})
+	}
+
+	/// Same as [`try_normalize`] but the normalization is only limited between elected edges.
+	pub fn try_normalize_elected(&mut self) -> Result<(), &'static str> {
+		let elected_edge_weights = self
+			.edges
+			.iter()
+			.filter_map(|e| if e.candidate.borrow().elected { Some(e.weight) } else { None })
+			.collect::<Vec<_>>();
+		elected_edge_weights.normalize(self.budget).map(|normalized| {
+			// here we count on the fact that normalize does not change the order, and that vector
+			// iteration is deterministic.
+			for (edge, corrected) in self
+				.edges
+				.iter_mut()
+				.filter(|e| e.candidate.borrow().elected)
+				.zip(normalized.into_iter())
+			{
+				let mut candidate = edge.candidate.borrow_mut();
+				// first, subtract the incorrect weight
+				candidate.backed_stake = candidate.backed_stake.saturating_sub(edge.weight);
+				edge.weight = corrected;
+				// Then add the correct one again.
+				candidate.backed_stake = candidate.backed_stake.saturating_add(edge.weight);
+			}
+		})
+	}
 }

 /// Final result of the election.
 #[derive(Debug)]
-pub struct ElectionResult<AccountId, T: PerThing> {
+pub struct ElectionResult<AccountId, P: PerThing> {
 	/// 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<WithApprovalOf<AccountId>>,
-	/// 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<Assignment<AccountId, T>>,
+	/// 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<Assignment<AccountId, P>>,
 }

 /// A voter's stake assignment among a set of targets, represented as ratios.
@@ -184,8 +337,8 @@ where
 {
 	/// Convert from a ratio assignment into one with absolute values aka. [`StakedAssignment`].
 	///
-	/// It needs `stake` which is the total budget of the voter. If `fill` is set to true,
-	/// it _tries_ to ensure that all the potential rounding errors are compensated and the
+	/// It needs `stake` which is the total budget of the voter. If `fill` is set to true, it
+	/// _tries_ to ensure that all the potential rounding errors are compensated and the
 	/// distribution's sum is exactly equal to the total budget, by adding or subtracting the
 	/// remainder from the last distribution.
 	///
@@ -219,6 +372,13 @@ where
 	/// Try and normalize this assignment.
 	///
 	/// If `Ok(())` is returned, then the assignment MUST have been successfully normalized to 100%.
+	///
+	/// ### Errors
+	///
+	/// This will return only if the internal `normalize` fails. This can happen if sum of
+	/// `self.distribution.map(|p| p.deconstruct())` fails to fit inside `UpperOf<P>`. A user of
+	/// this crate may statically assert that this can never happen and safely `expect` this to
+	/// return `Ok`.
 	pub fn try_normalize(&mut self) -> Result<(), &'static str> {
 		self.distribution
 			.iter()
@@ -289,9 +449,9 @@ impl<AccountId> StakedAssignment<AccountId> {
 	///
 	/// NOTE: current implementation of `.normalize` is almost safe to `expect()` upon. The only
 	/// error case is when the input cannot fit in `T`, or the sum of input cannot fit in `T`.
-	/// Sadly, both of these are dependent upon the implementation of `VoteLimit`, i.e. the limit
-	/// of edges per voter which is enforced from upstream. Hence, at this crate, we prefer
-	/// returning a result and a use the name prefix `try_`.
+	/// Sadly, both of these are dependent upon the implementation of `VoteLimit`, i.e. the limit of
+	/// edges per voter which is enforced from upstream. Hence, at this crate, we prefer returning a
+	/// result and a use the name prefix `try_`.
 	pub fn try_normalize(&mut self, stake: ExtendedBalance) -> Result<(), &'static str> {
 		self.distribution
 			.iter()
@@ -317,8 +477,8 @@ impl<AccountId> StakedAssignment<AccountId> {
 ///
 /// This complements the [`ElectionResult`] and is needed to run the balancing post-processing.
 ///
-/// This, at the current version, resembles the `Exposure` defined in the Staking pallet, yet
-/// they do not necessarily have to be the same.
+/// This, at the current version, resembles the `Exposure` defined in the Staking pallet, yet they
+/// do not necessarily have to be the same.
 #[derive(Default, Debug)]
 #[cfg_attr(feature = "std", derive(Serialize, Deserialize, Eq, PartialEq))]
 pub struct Support<AccountId> {
@@ -331,228 +491,12 @@ pub struct Support<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.
-///
-/// 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 seq_phragmen<AccountId, R>(
-	candidate_count: usize,
-	minimum_candidate_count: usize,
-	initial_candidates: Vec<AccountId>,
-	initial_voters: Vec<(AccountId, VoteWeight, Vec<AccountId>)>,
-) -> Option<ElectionResult<AccountId, R>> where
-	AccountId: Default + Ord + Clone,
-	R: PerThing,
-{
-	// return structures
-	let mut elected_candidates: Vec<(AccountId, ExtendedBalance)>;
-	let mut assigned: Vec<Assignment<AccountId, R>>;
-
-	// 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, voter_stake, votes)| {
-		let mut edges: Vec<Edge<AccountId>> = Vec::with_capacity(votes.len());
-		for v in votes {
-			if edges.iter().any(|e| e.who == v) {
-				// duplicate edge.
-				continue;
-			}
-			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(voter_stake.into());
-				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: voter_stake.into(),
-			load: Rational128::zero(),
-		}
-	}));
-
-
-	// we have already checked that we have more candidates than minimum_candidate_count.
-	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_else(|_| 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 = Assignment {
-			who: n.who.clone(),
-			..Default::default()
-		};
-		for e in &mut n.edges {
-			if elected_candidates.iter().position(|(ref c, _)| *c == e.who).is_some() {
-				let per_bill_parts: R::Inner =
-				{
-					if n.load == e.load {
-						// Full support. No need to calculate.
-						R::ACCURACY
-					} else {
-						if e.load.d() == n.load.d() {
-							// return e.load / n.load.
-							let desired_scale: u128 = R::ACCURACY.saturated_into();
-							let parts = multiply_by_rational(
-								desired_scale,
-								e.load.n(),
-								n.load.n(),
-							)
-							// If result cannot fit in u128. Not much we can do about it.
-							.unwrap_or_else(|_| Bounded::max_value());
-
-							TryFrom::try_from(parts)
-								// If the result cannot fit into R::Inner. Defensive only. This can
-								// never happen. `desired_scale * e / n`, where `e / n < 1` always
-								// yields a value smaller than `desired_scale`, which will fit into
-								// R::Inner.
-								.unwrap_or_else(|_| Bounded::max_value())
-						} else {
-							// defensive only. Both edge and voter loads are built from
-							// scores, hence MUST have the same denominator.
-							Zero::zero()
-						}
-					}
-				};
-				let per_thing = R::from_parts(per_bill_parts);
-				assignment.distribution.push((e.who.clone(), per_thing));
-			}
-		}
-
-		let len = assignment.distribution.len();
-		if len > 0 {
-			// To ensure an assertion indicating: no stake from the voter going to waste,
-			// we add a minimal post-processing to equally assign all of the leftover stake ratios.
-			let vote_count: R::Inner = len.saturated_into();
-			let accuracy = R::ACCURACY;
-			let mut sum: R::Inner = Zero::zero();
-			assignment.distribution.iter().for_each(|a| sum = sum.saturating_add(a.1.deconstruct()));
-
-			let diff = accuracy.saturating_sub(sum);
-			let diff_per_vote = (diff / vote_count).min(accuracy);
-
-			if !diff_per_vote.is_zero() {
-				for i in 0..len {
-					let current_ratio = assignment.distribution[i % len].1;
-					let next_ratio = current_ratio
-						.saturating_add(R::from_parts(diff_per_vote));
-					assignment.distribution[i % len].1 = next_ratio;
-				}
-			}
-
-			// `remainder` is set to be less than maximum votes of a voter (currently 16).
-			// safe to cast it to usize.
-			let remainder = diff - diff_per_vote * vote_count;
-			for i in 0..remainder.saturated_into::<usize>() {
-				let current_ratio = assignment.distribution[i % len].1;
-				let next_ratio = current_ratio.saturating_add(R::from_parts(1u8.into()));
-				assignment.distribution[i % len].1 = next_ratio;
-			}
-			assigned.push(assignment);
-		}
-	}
-
-	Some(ElectionResult {
-		winners: elected_candidates,
-		assignments: assigned,
-	})
-}
-
 /// Build the support map from the given election result. It maps a flat structure like
 ///
 /// ```nocompile
 /// assignments: vec![
-/// 	voter1, vec![(candidate1, w11), (candidate2, w12)],
-/// 	voter2, vec![(candidate1, w21), (candidate2, w22)]
+///     voter1, vec![(candidate1, w11), (candidate2, w12)],
+///     voter2, vec![(candidate1, w21), (candidate2, w22)]
 /// ]
 /// ```
 ///
@@ -560,16 +504,16 @@ pub fn seq_phragmen<AccountId, R>(
 ///
 /// ```nocompile
 ///  SupportMap {
-/// 	candidate1: Support {
-/// 		own:0,
-/// 		total: w11 + w21,
-/// 		others: vec![(candidate1, w11), (candidate2, w21)]
-///		},
-/// 	candidate2: Support {
-/// 		own:0,
-/// 		total: w12 + w22,
-/// 		others: vec![(candidate1, w12), (candidate2, w22)]
-///		},
+///     candidate1: Support {
+///         own:0,
+///         total: w11 + w21,
+///         others: vec![(candidate1, w11), (candidate2, w21)]
+///     },
+///     candidate2: Support {
+///         own:0,
+///         total: w12 + w22,
+///         others: vec![(candidate1, w12), (candidate2, w22)]
+///     },
 /// }
 /// ```
 ///
@@ -581,10 +525,9 @@ pub fn seq_phragmen<AccountId, R>(
 pub fn build_support_map<AccountId>(
 	winners: &[AccountId],
 	assignments: &[StakedAssignment<AccountId>],
-) -> (SupportMap<AccountId>, u32) where
-	AccountId: Default + Ord + Clone,
+) -> Result<SupportMap<AccountId>, AccountId> where
+	AccountId: IdentifierT,
 {
-	let mut errors = 0;
 	// Initialize the support of each candidate.
 	let mut supports = <SupportMap<AccountId>>::new();
 	winners
@@ -598,11 +541,11 @@ pub fn build_support_map<AccountId>(
 				support.total = support.total.saturating_add(*weight_extended);
 				support.voters.push((who.clone(), *weight_extended));
 			} else {
-				errors = errors.saturating_add(1);
+				return Err(c.clone())
 			}
 		}
 	}
-	(supports, errors)
+	Ok(supports)
 }

 /// Evaluate a support map. The returned tuple contains:
@@ -631,8 +574,8 @@ pub fn evaluate_support<AccountId>(
 	[min_support, sum, sum_squared]
 }

-/// Compares two sets of election scores based on desirability and returns true if `this` is
-/// better than `that`.
+/// Compares two sets of election scores based on desirability and returns true if `this` is better
+/// than `that`.
 ///
 /// Evaluation is done in a lexicographic manner, and if each element of `this` is `that * epsilon`
 /// greater or less than `that`.
@@ -665,139 +608,55 @@ pub fn is_score_better<P: PerThing>(this: ElectionScore, that: ElectionScore, ep
 	}
 }

-/// Performs balancing 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.
+/// Converts raw inputs to types used in this crate.
 ///
-/// Returns the number of iterations that were preformed.
-///
-/// - `assignments`: exactly the same as the output of [`seq_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.
-pub fn balance_solution<AccountId>(
-	assignments: &mut Vec<StakedAssignment<AccountId>>,
-	supports: &mut SupportMap<AccountId>,
-	tolerance: ExtendedBalance,
-	iterations: usize,
-) -> usize where AccountId: Ord + Clone {
-	if iterations == 0 { return 0; }
+/// This will perform some cleanup that are most often important:
+/// - It drops any votes that are pointing to non-candidates.
+/// - It drops duplicate targets within a voter.
+pub(crate) fn setup_inputs<AccountId: IdentifierT>(
+	initial_candidates: Vec<AccountId>,
+	initial_voters: Vec<(AccountId, VoteWeight, Vec<AccountId>)>,
+) -> (Vec<CandidatePtr<AccountId>>, Vec<Voter<AccountId>>) {
+	// used to cache and access candidates index.
+	let mut c_idx_cache = BTreeMap::<AccountId, usize>::new();

-	let mut i = 0 ;
-	loop {
-		let mut max_diff = 0;
-		for assignment in assignments.iter_mut() {
-			let voter_budget = assignment.total();
-			let StakedAssignment { who, distribution } =  assignment;
-			let diff = do_balancing(
-				who,
-				voter_budget,
-				distribution,
-				supports,
-				tolerance,
-			);
-			if diff > max_diff { max_diff = diff; }
-		}
+	let candidates = initial_candidates
+		.into_iter()
+		.enumerate()
+		.map(|(idx, who)| {
+			c_idx_cache.insert(who.clone(), idx);
+			Rc::new(RefCell::new(Candidate { who, ..Default::default() }))
+		})
+		.collect::<Vec<CandidatePtr<AccountId>>>();

-		i += 1;
-		if max_diff <= tolerance || i >= iterations {
-			break i;
-		}
-	}
-}
-
-/// actually perform balancing. same interface is `balance_solution`. Just called in loops with a check for
-/// maximum difference.
-fn do_balancing<AccountId>(
-	voter: &AccountId,
-	budget: ExtendedBalance,
-	elected_edges: &mut Vec<(AccountId, ExtendedBalance)>,
-	support_map: &mut SupportMap<AccountId>,
-	tolerance: ExtendedBalance
-) -> ExtendedBalance where AccountId: Ord + Clone {
-	// Nothing to do. This voter had nothing useful.
-	// Defensive only. Assignment list should always be populated. 1 might happen for self vote.
-	if elected_edges.is_empty() || elected_edges.len() == 1 { 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.voters.retain(|i_support| i_support.0 != *voter);
-		}
-		e.1 = 0;
-	});
-
-	elected_edges.sort_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;
+	let voters = initial_voters.into_iter().map(|(who, voter_stake, votes)| {
+		let mut edges: Vec<Edge<AccountId>> = Vec::with_capacity(votes.len());
+		for v in votes {
+			if edges.iter().any(|e| e.who == v) {
+				// duplicate edge.
+				continue;
 			}
-			cumulative_stake = cumulative_stake.saturating_add(stake);
+			if let Some(idx) = c_idx_cache.get(&v) {
+				// This candidate is valid + already cached.
+				let mut candidate = candidates[*idx].borrow_mut();
+				candidate.approval_stake =
+					candidate.approval_stake.saturating_add(voter_stake.into());
+				edges.push(
+					Edge {
+						who: v.clone(),
+						candidate: Rc::clone(&candidates[*idx]),
+						..Default::default()
+					}
+				);
+			} // else {} would be wrong votes. We don't really care about it.
 		}
-		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.voters.push((voter.clone(), e.1));
+		Voter {
+			who,
+			edges: edges,
+			budget: voter_stake.into(),
+			load: Rational128::zero(),
 		}
-	});
+	}).collect::<Vec<_>>();

-	difference
+	(candidates, voters,)
 }