remove OnStakerSlash replace with OnStakingEvents (#14527)

* remove 'OnStakerSlash', replace with 'OnStakingEvents'

* fix other features in pallets

* small fixes

* fix docs

* fix docs

* fix docs

* Update primitives/staking/src/lib.rs

Co-authored-by: Gonçalo Pestana <g6pestana@gmail.com>

---------

Co-authored-by: Gonçalo Pestana <g6pestana@gmail.com>

substrate/primitives/staking/src/currency_to_vote.rs

@@ -0,0 +1,101 @@
+// This file is part of Substrate.
+
+// Copyright (C) 2019-2022 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.
+
+use sp_runtime::{
+	traits::{UniqueSaturatedFrom, UniqueSaturatedInto},
+	SaturatedConversion,
+};
+
+/// A trait similar to `Convert` to convert values from `B` an abstract balance type
+/// into u64 and back from u128. (This conversion is used in election and other places where complex
+/// calculation over balance type is needed)
+///
+/// Total issuance of the currency is passed in, but an implementation of this trait may or may not
+/// use it.
+///
+/// # WARNING
+///
+/// the total issuance being passed in implies that the implementation must be aware of the fact
+/// that its values can affect the outcome. This implies that if the vote value is dependent on the
+/// total issuance, it should never ber written to storage for later re-use.
+pub trait CurrencyToVote<B> {
+	/// Convert balance to u64.
+	fn to_vote(value: B, issuance: B) -> u64;
+
+	/// Convert u128 to balance.
+	fn to_currency(value: u128, issuance: B) -> B;
+}
+
+/// An implementation of `CurrencyToVote` tailored for chain's that have a balance type of u128.
+///
+/// The factor is the `(total_issuance / u64::MAX).max(1)`, represented as u64. Let's look at the
+/// important cases:
+///
+/// If the chain's total issuance is less than u64::MAX, this will always be 1, which means that
+/// the factor will not have any effect. In this case, any account's balance is also less. Thus,
+/// both of the conversions are basically an `as`; Any balance can fit in u64.
+///
+/// If the chain's total issuance is more than 2*u64::MAX, then a factor might be multiplied and
+/// divided upon conversion.
+pub struct U128CurrencyToVote;
+
+impl U128CurrencyToVote {
+	fn factor(issuance: u128) -> u128 {
+		(issuance / u64::MAX as u128).max(1)
+	}
+}
+
+impl CurrencyToVote<u128> for U128CurrencyToVote {
+	fn to_vote(value: u128, issuance: u128) -> u64 {
+		(value / Self::factor(issuance)).saturated_into()
+	}
+
+	fn to_currency(value: u128, issuance: u128) -> u128 {
+		value.saturating_mul(Self::factor(issuance))
+	}
+}
+
+/// A naive implementation of `CurrencyConvert` that simply saturates all conversions.
+///
+/// # Warning
+///
+/// This is designed to be used mostly for testing. Use with care, and think about the consequences.
+pub struct SaturatingCurrencyToVote;
+
+impl<B: UniqueSaturatedInto<u64> + UniqueSaturatedFrom<u128>> CurrencyToVote<B>
+	for SaturatingCurrencyToVote
+{
+	fn to_vote(value: B, _: B) -> u64 {
+		value.unique_saturated_into()
+	}
+
+	fn to_currency(value: u128, _: B) -> B {
+		B::unique_saturated_from(value)
+	}
+}
+
+#[cfg(feature = "std")]
+impl<B: UniqueSaturatedInto<u64> + UniqueSaturatedFrom<u128>> CurrencyToVote<B> for () {
+	fn to_vote(value: B, issuance: B) -> u64 {
+		SaturatingCurrencyToVote::to_vote(value, issuance)
+	}
+
+	/// Convert u128 to balance.
+	fn to_currency(value: u128, issuance: B) -> B {
+		SaturatingCurrencyToVote::to_currency(value, issuance)
+	}
+}

substrate/primitives/staking/src/lib.rs

@@ -20,13 +20,17 @@
 //! A crate which contains primitives that are useful for implementation that uses staking
 //! approaches in general. Definitions related to sessions, slashing, etc go here.
 
+use crate::currency_to_vote::CurrencyToVote;
+use codec::{FullCodec, MaxEncodedLen};
 use scale_info::TypeInfo;
 use sp_core::RuntimeDebug;
-use sp_runtime::{DispatchError, DispatchResult};
-use sp_std::{collections::btree_map::BTreeMap, vec::Vec};
+use sp_runtime::{DispatchError, DispatchResult, Saturating};
+use sp_std::{collections::btree_map::BTreeMap, ops::Sub, vec::Vec};
 
 pub mod offence;
 
+pub mod currency_to_vote;
+
 /// Simple index type with which we can count sessions.
 pub type SessionIndex = u32;
 
@@ -45,32 +49,9 @@ pub enum StakerStatus<AccountId> {
 	Nominator(Vec<AccountId>),
 }
 
-/// Trait describing something that implements a hook for any operations to perform when a staker is
-/// slashed.
-pub trait OnStakerSlash<AccountId, Balance> {
-	/// A hook for any operations to perform when a staker is slashed.
-	///
-	/// # Arguments
-	///
-	/// * `stash` - The stash of the staker whom the slash was applied to.
-	/// * `slashed_active` - The new bonded balance of the staker after the slash was applied.
-	/// * `slashed_unlocking` - A map of slashed eras, and the balance of that unlocking chunk after
-	///   the slash is applied. Any era not present in the map is not affected at all.
-	fn on_slash(
-		stash: &AccountId,
-		slashed_active: Balance,
-		slashed_unlocking: &BTreeMap<EraIndex, Balance>,
-	);
-}
-
-impl<AccountId, Balance> OnStakerSlash<AccountId, Balance> for () {
-	fn on_slash(_: &AccountId, _: Balance, _: &BTreeMap<EraIndex, Balance>) {
-		// Nothing to do here
-	}
-}
-
 /// A struct that reflects stake that an account has in the staking system. Provides a set of
 /// methods to operate on it's properties. Aimed at making `StakingInterface` more concise.
+#[derive(RuntimeDebug, Clone, Copy, Eq, PartialEq, Default)]
 pub struct Stake<Balance> {
 	/// The total stake that `stash` has in the staking system. This includes the
 	/// `active` stake, and any funds currently in the process of unbonding via
@@ -87,16 +68,88 @@ pub struct Stake<Balance> {
 	pub active: Balance,
 }
 
+/// A generic staking event listener.
+///
+/// Note that the interface is designed in a way that the events are fired post-action, so any
+/// pre-action data that is needed needs to be passed to interface methods. The rest of the data can
+/// be retrieved by using `StakingInterface`.
+#[impl_trait_for_tuples::impl_for_tuples(10)]
+pub trait OnStakingUpdate<AccountId, Balance> {
+	/// Fired when the stake amount of someone updates.
+	///
+	/// This is effectively any changes to the bond amount, such as bonding more funds, and
+	/// unbonding.
+	fn on_stake_update(_who: &AccountId, _prev_stake: Option<Stake<Balance>>) {}
+
+	/// Fired when someone sets their intention to nominate.
+	///
+	/// This should never be fired for existing nominators.
+	fn on_nominator_add(_who: &AccountId) {}
+
+	/// Fired when an existing nominator updates their nominations.
+	///
+	/// Note that this is not fired when a nominator changes their stake. For that,
+	/// `on_stake_update` should be used, followed by querying whether `who` was a validator or a
+	/// nominator.
+	fn on_nominator_update(_who: &AccountId, _prev_nominations: Vec<AccountId>) {}
+
+	/// Fired when someone removes their intention to nominate, either due to chill or validating.
+	///
+	/// The set of nominations at the time of removal is provided as it can no longer be fetched in
+	/// any way.
+	fn on_nominator_remove(_who: &AccountId, _nominations: Vec<AccountId>) {}
+
+	/// Fired when someone sets their intention to validate.
+	///
+	/// Note validator preference changes are not communicated, but could be added if needed.
+	fn on_validator_add(_who: &AccountId) {}
+
+	/// Fired when an existing validator updates their preferences.
+	///
+	/// Note validator preference changes are not communicated, but could be added if needed.
+	fn on_validator_update(_who: &AccountId) {}
+
+	/// Fired when someone removes their intention to validate, either due to chill or nominating.
+	fn on_validator_remove(_who: &AccountId) {}
+
+	/// Fired when someone is fully unstaked.
+	fn on_unstake(_who: &AccountId) {}
+
+	/// Fired when a staker is slashed.
+	///
+	/// * `stash` - The stash of the staker whom the slash was applied to.
+	/// * `slashed_active` - The new bonded balance of the staker after the slash was applied.
+	/// * `slashed_unlocking` - A map of slashed eras, and the balance of that unlocking chunk after
+	///   the slash is applied. Any era not present in the map is not affected at all.
+	fn on_slash(
+		_stash: &AccountId,
+		_slashed_active: Balance,
+		_slashed_unlocking: &BTreeMap<EraIndex, Balance>,
+	) {
+	}
+}
+
 /// A generic representation of a staking implementation.
 ///
 /// This interface uses the terminology of NPoS, but it is aims to be generic enough to cover other
 /// implementations as well.
 pub trait StakingInterface {
 	/// Balance type used by the staking system.
-	type Balance: PartialEq;
+	type Balance: Sub<Output = Self::Balance>
+		+ Ord
+		+ PartialEq
+		+ Default
+		+ Copy
+		+ MaxEncodedLen
+		+ FullCodec
+		+ TypeInfo
+		+ Saturating;
 
-	/// AccountId type used by the staking system
-	type AccountId;
+	/// AccountId type used by the staking system.
+	type AccountId: Clone + sp_std::fmt::Debug;
+
+	/// Means of converting Currency to VoteWeight.
+	type CurrencyToVote: CurrencyToVote<Self::Balance>;
 
 	/// The minimum amount required to bond in order to set nomination intentions. This does not
 	/// necessarily mean the nomination will be counted in an election, but instead just enough to
@@ -195,8 +248,12 @@ pub trait StakingInterface {
 	/// Return the status of the given staker, `None` if not staked at all.
 	fn status(who: &Self::AccountId) -> Result<StakerStatus<Self::AccountId>, DispatchError>;
 
+	/// Checks whether or not this is a validator account.
+	fn is_validator(who: &Self::AccountId) -> bool {
+		Self::status(who).map(|s| matches!(s, StakerStatus::Validator)).unwrap_or(false)
+	}
+
 	/// Get the nominations of a stash, if they are a nominator, `None` otherwise.
-	#[cfg(feature = "runtime-benchmarks")]
 	fn nominations(who: &Self::AccountId) -> Option<Vec<Self::AccountId>> {
 		match Self::status(who) {
 			Ok(StakerStatus::Nominator(t)) => Some(t),