Updates to elections-phragmen and some runtime docs. (#3940)

* minor changes

* Refactors for phragmen-election

* Bump.

* Fix genesis stuff

* Fix rest of the errors

substrate/core/phragmen/src/lib.rs

@@ -290,7 +290,9 @@ pub fn elect<AccountId, Balance, FS, C>(
 		let mut assignment = (n.who.clone(), vec![]);
 		for e in &mut n.edges {
 			if let Some(c) = elected_candidates.iter().cloned().find(|(c, _)| *c == e.who) {
-				if c.0 != n.who {
+				// if self_vote == false, this branch should always be executed as we want to
+				// collect all nominations
+				if c.0 != n.who || !self_vote  {
 					let per_bill_parts =
 					{
 						if n.load == e.load {
@@ -360,6 +362,47 @@ pub fn elect<AccountId, Balance, FS, C>(
 	})
 }
 
+/// 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,
+	assume_self_vote: bool,
+) -> 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()
+		.map(|e| (e, if assume_self_vote { to_votes(stake_of(e)) } else { Zero::zero() } ))
+		.for_each(|(e, s)| {
+			let item = Support { own: s, total: s, ..Default::default() };
+			supports.insert(e.clone(), item);
+		});
+
+	// 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) {
+				// 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.

substrate/core/sr-primitives/src/weights.rs

@@ -14,11 +14,23 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Primitives for transaction weighting.
+//! # Primitives for transaction weighting.
 //!
-//! Each dispatch function within `decl_module!` can have an optional `#[weight = $x]` attribute.
-//! `$x` can be any type that implements the `ClassifyDispatch<T>` and `WeighData<T>` traits. By
-//! default, All transactions are annotated with `#[weight = SimpleDispatchInfo::default()]`.
+//! All dispatchable functions defined in `decl_module!` must provide two trait implementations:
+//!   - [`WeightData`]: To determine the weight of the dispatch.
+//!   - [`ClassifyDispatch`]: To determine the class of the dispatch. See the enum definition for
+//!     more information on dispatch classes.
+//!
+//! Every dispatchable function is responsible for providing this data via an optional `#[weight =
+//! $x]` attribute. In this snipped, `$x` can be any user provided struct that implements the
+//! two aforementioned traits.
+//!
+//! Substrate then bundles then output information of the two traits into [`DispatchInfo`] struct
+//! and provides it by implementing the [`GetDispatchInfo`] for all `Call` variants, and opaque
+//! extrinsic types.
+//!
+//! If no `#[weight]` is defined, the macro automatically injects the `Default` implementation of
+//! the [`SimpleDispatchInfo`].
 //!
 //! Note that the decl_module macro _cannot_ enforce this and will simply fail if an invalid struct
 //! (something that does not  implement `Weighable`) is passed in.
@@ -31,8 +43,24 @@ pub use crate::transaction_validity::TransactionPriority;
 /// Numeric range of a transaction weight.
 pub type Weight = u32;
 
-/// A generalized group of dispatch types. This is only distinguishing normal, user-triggered transactions
-/// (`Normal`) and anything beyond which serves a higher purpose to the system (`Operational`).
+/// Means of weighing some particular kind of data (`T`).
+pub trait WeighData<T> {
+	/// Weigh the data `T` given by `target`. When implementing this for a dispatchable, `T` will be
+	/// a tuple of all arguments given to the function (except origin).
+	fn weigh_data(&self, target: T) -> Weight;
+}
+
+/// Means of classifying a dispatchable function.
+pub trait ClassifyDispatch<T> {
+	/// Classify the dispatch function based on input data `target` of type `T`. When implementing
+	/// this for a dispatchable, `T` will be a tuple of all arguments given to the function (except
+	/// origin).
+	fn classify_dispatch(&self, target: T) -> DispatchClass;
+}
+
+/// A generalized group of dispatch types. This is only distinguishing normal, user-triggered
+/// transactions (`Normal`) and anything beyond which serves a higher purpose to the system
+/// (`Operational`).
 #[derive(PartialEq, Eq, Clone, Copy, RuntimeDebug)]
 pub enum DispatchClass {
 	/// A normal dispatch.
@@ -82,8 +110,8 @@ impl DispatchInfo {
 	}
 }
 
-/// A `Dispatchable` function (aka transaction) that can carry some static information along with it, using the
-/// `#[weight]` attribute.
+/// A `Dispatchable` function (aka transaction) that can carry some static information along with
+/// it, using the `#[weight]` attribute.
 pub trait GetDispatchInfo {
 	/// Return a `DispatchInfo`, containing relevant information of this dispatch.
 	///
@@ -91,18 +119,6 @@ pub trait GetDispatchInfo {
 	fn get_dispatch_info(&self) -> DispatchInfo;
 }
 
-/// Means of weighing some particular kind of data (`T`).
-pub trait WeighData<T> {
-	/// Weigh the data `T` given by `target`.
-	fn weigh_data(&self, target: T) -> Weight;
-}
-
-/// Means of classifying a dispatchable function.
-pub trait ClassifyDispatch<T> {
-	/// Classify the dispatch function based on input data `target` of type `T`.
-	fn classify_dispatch(&self, target: T) -> DispatchClass;
-}
-
 /// Default type used with the `#[weight = x]` attribute in a substrate chain.
 ///
 /// A user may pass in any other type that implements the correct traits. If not, the `Default`
@@ -114,13 +130,9 @@ pub trait ClassifyDispatch<T> {
 ///   - A `Free` variant is equal to `::Fixed(0)`. Note that this does not guarantee inclusion.
 ///   - A `Max` variant is equal to `::Fixed(Weight::max_value())`.
 ///
-/// Based on the final weight value, based on the above variants:
-///   - A _weight-fee_  is deducted.
-///   - The block weight is consumed proportionally.
-///
 /// As for the generalized groups themselves:
 ///   - `Normal` variants will be assigned a priority proportional to their weight. They can only
-///     consume a portion (1/4) of the maximum block resource limits.
+///     consume a portion (defined in the system module) of the maximum block resource limits.
 ///   - `Operational` variants will be assigned the maximum priority. They can potentially consume
 ///     the entire block resource limit.
 #[derive(Clone, Copy)]