Adds target approvals buffering below a threshold (#5168)

This PR adds target stake updates buffering to `stake-tracker`. It
exposes a configuration that defines a threshold below which the target
score *should not* be updated automatically in the target list. The
`Config::ScoreStrictUpdateThreshold` defines said threshold. If a target
stake update is below the threshold, the stake update is buffered in the
`UnsettledTargetScore` storage map while the target list is not
affected. Multiple approvals updates can be buffered for the same
target. Calling `Call::settle` will setttle the buffered approvals tally
for a given target. Setting `Config::ScoreStrictUpdateThreshold` to
`None` disables the stake approvals buffering.

- [x] benchmarks
- [x] `try-state` checks considering the unsettled score
- [x] docs

---------

Co-authored-by: command-bot <>

polkadot/runtime/westend/src/lib.rs

@@ -590,6 +590,7 @@ parameter_types! {
 	pub const TargetBagThresholds: &'static [u128] = &bag_thresholds::TARGET_THRESHOLDS;
 
 	pub const VoterUpdateMode: pallet_stake_tracker::VoterUpdateMode = pallet_stake_tracker::VoterUpdateMode::Lazy;
+	pub const ScoreStrictUpdateThreshold: Option<u128> = Some(10);
 }
 
 type VoterBagsListInstance = pallet_bags_list::Instance1;
@@ -616,6 +617,8 @@ impl pallet_stake_tracker::Config for Runtime {
 	type VoterList = VoterList;
 	type TargetList = TargetList;
 	type VoterUpdateMode = VoterUpdateMode;
+	type ScoreStrictUpdateThreshold = ScoreStrictUpdateThreshold;
+	type WeightInfo = pallet_stake_tracker::weights::SubstrateWeight<Runtime>;
 }
 
 pallet_staking_reward_curve::build! {
@@ -667,6 +670,8 @@ impl pallet_staking::Config for Runtime {
 	type GenesisElectionProvider = onchain::OnChainExecution<OnChainSeqPhragmen>;
 	type VoterList = VoterList;
 	type TargetList = TargetList;
+	#[cfg(any(feature = "try-runtime", test))]
+	type TargetUnsettledApprovals = pallet_stake_tracker::UnsettledTargetScores<Self>;
 	type NominationsQuota = pallet_staking::FixedNominationsQuota<{ MaxNominations::get() }>;
 	type MaxUnlockingChunks = frame_support::traits::ConstU32<32>;
 	type HistoryDepth = frame_support::traits::ConstU32<84>;

substrate/bin/node/runtime/src/lib.rs

@@ -697,6 +697,8 @@ impl pallet_staking::Config for Runtime {
 	type GenesisElectionProvider = onchain::OnChainExecution<OnChainSeqPhragmen>;
 	type VoterList = VoterList;
 	type TargetList = TargetList;
+	#[cfg(any(feature = "try-runtime", test))]
+	type TargetUnsettledApprovals = pallet_stake_tracker::UnsettledTargetScores<Self>;
 	type NominationsQuota = pallet_staking::FixedNominationsQuota<MAX_QUOTA_NOMINATIONS>;
 	type MaxUnlockingChunks = ConstU32<32>;
 	type MaxControllersInDeprecationBatch = MaxControllersInDeprecationBatch;
@@ -709,6 +711,8 @@ impl pallet_staking::Config for Runtime {
 
 parameter_types! {
 	pub const VoterUpdateMode: pallet_stake_tracker::VoterUpdateMode = pallet_stake_tracker::VoterUpdateMode::Lazy;
+	// disables the lazy approvals update.
+	pub const ScoreStrictUpdateThreshold: Option<u128> = None;
 }
 
 impl pallet_stake_tracker::Config for Runtime {
@@ -717,6 +721,8 @@ impl pallet_stake_tracker::Config for Runtime {
 	type VoterList = VoterList;
 	type TargetList = TargetList;
 	type VoterUpdateMode = VoterUpdateMode;
+	type ScoreStrictUpdateThreshold = ScoreStrictUpdateThreshold;
+	type WeightInfo = pallet_stake_tracker::weights::SubstrateWeight<Runtime>;
 }
 
 impl pallet_fast_unstake::Config for Runtime {
@@ -2646,6 +2652,7 @@ mod benches {
 		[pallet_session, SessionBench::<Runtime>]
 		[pallet_society, Society]
 		[pallet_staking, Staking]
+		[pallet_stake_tracker, StakeTracker]
 		[pallet_state_trie_migration, StateTrieMigration]
 		[pallet_sudo, Sudo]
 		[frame_system, SystemBench::<Runtime>]

substrate/frame/delegated-staking/src/mock.rs

@@ -110,6 +110,8 @@ impl pallet_staking::Config for Runtime {
 	type GenesisElectionProvider = Self::ElectionProvider;
 	type VoterList = pallet_staking::UseNominatorsAndValidatorsMap<Self>;
 	type TargetList = TargetBagsList;
+	#[cfg(any(feature = "try-runtime", test))]
+	type TargetUnsettledApprovals = pallet_stake_tracker::UnsettledTargetScores<Self>;
 	type EventListeners = (StakeTracker, Pools, DelegatedStaking);
 }
 
@@ -129,6 +131,7 @@ impl pallet_bags_list::Config<TargetBagsListInstance> for Runtime {
 
 parameter_types! {
 	pub static VoterUpdateMode: pallet_stake_tracker::VoterUpdateMode = pallet_stake_tracker::VoterUpdateMode::Lazy;
+	pub static ScoreStrictUpdateThreshold: Option<u128> = None;
 }
 
 impl pallet_stake_tracker::Config for Runtime {
@@ -137,6 +140,8 @@ impl pallet_stake_tracker::Config for Runtime {
 	type VoterList = pallet_staking::UseNominatorsAndValidatorsMap<Self>;
 	type TargetList = TargetBagsList;
 	type VoterUpdateMode = VoterUpdateMode;
+	type ScoreStrictUpdateThreshold = ScoreStrictUpdateThreshold;
+	type WeightInfo = ();
 }
 
 parameter_types! {

substrate/frame/election-provider-multi-phase/test-staking-e2e/src/mock.rs

@@ -256,6 +256,7 @@ impl pallet_bags_list::Config<TargetBagsListInstance> for Runtime {
 
 parameter_types! {
 	pub static UpdateMode: VoterUpdateMode = VoterUpdateMode::Lazy;
+	pub static ScoreStrictUpdateThreshold: Option<u128> = None;
 }
 
 impl pallet_stake_tracker::Config for Runtime {
@@ -264,6 +265,8 @@ impl pallet_stake_tracker::Config for Runtime {
 	type VoterList = VoterBagsList;
 	type TargetList = TargetBagsList;
 	type VoterUpdateMode = UpdateMode;
+	type ScoreStrictUpdateThreshold = ScoreStrictUpdateThreshold;
+	type WeightInfo = ();
 }
 
 pub struct BalanceToU256;
@@ -330,6 +333,8 @@ impl pallet_staking::Config for Runtime {
 	type VoterList = VoterBagsList;
 	type NominationsQuota = pallet_staking::FixedNominationsQuota<MAX_QUOTA_NOMINATIONS>;
 	type TargetList = TargetBagsList;
+	#[cfg(any(feature = "try-runtime", test))]
+	type TargetUnsettledApprovals = pallet_stake_tracker::UnsettledTargetScores<Self>;
 	type MaxUnlockingChunks = MaxUnlockingChunks;
 	type EventListeners = (StakeTracker, Pools);
 	type WeightInfo = pallet_staking::weights::SubstrateWeight<Runtime>;

substrate/frame/nomination-pools/src/mock.rs

@@ -174,6 +174,10 @@ impl sp_staking::StakingInterface for StakingMock {
 		Ok(())
 	}
 
+	fn validate(who: &Self::AccountId) -> sp_runtime::DispatchResult {
+		unimplemented!()
+	}
+
 	fn nominate(_: &Self::AccountId, nominations: Vec<Self::AccountId>) -> DispatchResult {
 		Nominations::set(&Some(nominations));
 		Ok(())

substrate/frame/nomination-pools/test-delegate-stake/src/mock.rs

@@ -108,6 +108,7 @@ impl pallet_staking::Config for Runtime {
 
 parameter_types! {
 	pub static VoterUpdateMode: pallet_stake_tracker::VoterUpdateMode = pallet_stake_tracker::VoterUpdateMode::Lazy;
+	pub static ScoreStrictUpdateThreshold: Option<u128> = None;
 }
 
 impl pallet_stake_tracker::Config for Runtime {
@@ -116,6 +117,8 @@ impl pallet_stake_tracker::Config for Runtime {
 	type VoterList = VoterList;
 	type TargetList = pallet_staking::UseValidatorsMap<Self>;
 	type VoterUpdateMode = VoterUpdateMode;
+	type ScoreStrictUpdateThreshold = ScoreStrictUpdateThreshold;
+	type WeightInfo = ();
 }
 
 parameter_types! {

substrate/frame/nomination-pools/test-transfer-stake/src/mock.rs

@@ -100,6 +100,7 @@ impl pallet_staking::Config for Runtime {
 
 parameter_types! {
 	pub static VoterUpdateMode: pallet_stake_tracker::VoterUpdateMode = pallet_stake_tracker::VoterUpdateMode::Lazy;
+	pub static ScoreStrictUpdateThreshold: Option<u128> = None;
 }
 
 impl pallet_stake_tracker::Config for Runtime {
@@ -108,6 +109,8 @@ impl pallet_stake_tracker::Config for Runtime {
 	type VoterList = VoterList;
 	type TargetList = pallet_staking::UseValidatorsMap<Self>;
 	type VoterUpdateMode = VoterUpdateMode;
+	type ScoreStrictUpdateThreshold = ScoreStrictUpdateThreshold;
+	type WeightInfo = ();
 }
 
 parameter_types! {

substrate/frame/staking/src/benchmarking.rs

@@ -22,6 +22,7 @@ use crate::{migrations::v13_stake_tracker as v13, ConfigOp, Pallet as Staking};
 use testing_utils::*;
 
 use codec::Decode;
+use frame_benchmarking::v2::*;
 use frame_election_provider_support::{bounds::DataProviderBounds, SortedListProvider};
 use frame_support::{
 	assert_ok,
@@ -31,18 +32,13 @@ use frame_support::{
 	traits::{Currency, Get, Imbalance, UnfilteredDispatchable},
 	weights::WeightMeter,
 };
+use frame_system::RawOrigin;
 use sp_runtime::{
 	traits::{Bounded, One, StaticLookup, TrailingZeroInput, Zero},
 	Perbill, Percent, Saturating,
 };
 use sp_staking::{currency_to_vote::CurrencyToVote, SessionIndex, StakingInterface};
 
-pub use frame_benchmarking::v1::{
-	account, impl_benchmark_test_suite, whitelist_account, whitelisted_caller, BenchmarkError,
-};
-use frame_benchmarking::v2::*;
-use frame_system::RawOrigin;
-
 const SEED: u32 = 0;
 const MAX_SPANS: u32 = 100;
 const MAX_SLASHES: u32 = 1000;

substrate/frame/staking/src/mock.rs

@@ -356,6 +356,8 @@ impl OnStakingUpdate<AccountId, Balance> for EventTracker {
 
 parameter_types! {
 	pub static VoterUpdateMode: pallet_stake_tracker::VoterUpdateMode = pallet_stake_tracker::VoterUpdateMode::Lazy;
+	// disables the lazy approvals update.
+	pub static ScoreStrictUpdateThreshold: Option<u128> = None;
 }
 
 impl pallet_stake_tracker::Config for Test {
@@ -364,6 +366,8 @@ impl pallet_stake_tracker::Config for Test {
 	type VoterList = VoterBagsList;
 	type TargetList = TargetBagsList;
 	type VoterUpdateMode = VoterUpdateMode;
+	type ScoreStrictUpdateThreshold = ScoreStrictUpdateThreshold;
+	type WeightInfo = ();
 }
 
 // Disabling threshold for `UpToLimitDisablingStrategy`
@@ -386,6 +390,8 @@ impl crate::pallet::pallet::Config for Test {
 	type GenesisElectionProvider = Self::ElectionProvider;
 	type VoterList = VoterBagsList;
 	type TargetList = TargetBagsList;
+	#[cfg(any(feature = "try-runtime", test))]
+	type TargetUnsettledApprovals = pallet_stake_tracker::UnsettledTargetScores<Self>;
 	type NominationsQuota = WeightedNominationsQuota<16>;
 	type MaxUnlockingChunks = MaxUnlockingChunks;
 	type HistoryDepth = HistoryDepth;
@@ -559,6 +565,11 @@ impl ExtBuilder {
 		MaxWinners::set(max);
 		self
 	}
+	pub fn stake_tracker_update_threshold(self, threshold: Option<u128>) -> Self {
+		ScoreStrictUpdateThreshold::set(threshold);
+		self
+	}
+
 	fn build(self) -> sp_io::TestExternalities {
 		sp_tracing::try_init_simple();
 		let mut storage = frame_system::GenesisConfig::<Test>::default().build_storage().unwrap();

substrate/frame/staking/src/pallet/impls.rs

@@ -1993,6 +1993,11 @@ impl<T: Config> StakingInterface for Pallet<T> {
 		Self::nominate(RawOrigin::Signed(ctrl).into(), targets)
 	}
 
+	fn validate(who: &Self::AccountId) -> DispatchResult {
+		let ctrl = Self::bonded(who).ok_or(Error::<T>::NotStash)?;
+		Self::validate(RawOrigin::Signed(ctrl).into(), Default::default())
+	}
+
 	fn desired_validator_count() -> u32 {
 		ValidatorCount::<T>::get()
 	}
@@ -2521,6 +2526,8 @@ impl<T: Config> Pallet<T> {
 	///   (active_validators + idle_validators + dangling_targets_score_with_score).
 	pub fn do_try_state_approvals() -> Result<(), sp_runtime::TryRuntimeError> {
 		use alloc::collections::{btree_map::BTreeMap, btree_set::BTreeSet};
+		use pallet_stake_tracker::StakeImbalance;
+
 		let mut approvals_map: BTreeMap<T::AccountId, T::CurrencyBalance> = BTreeMap::new();
 
 		// build map of approvals stakes from the `Nominators` storage map POV.
@@ -2585,6 +2592,19 @@ impl<T: Config> Pallet<T> {
 			}
 		}
 
+		// sync up current unsettled score to target's approvals.
+		for (target, imbalance) in T::TargetUnsettledApprovals::get().into_iter() {
+			if let Some(approvals) = approvals_map.get_mut(&target) {
+				match imbalance {
+					StakeImbalance::Positive(score) => *approvals -= score,
+					StakeImbalance::Negative(score) => *approvals += score,
+					StakeImbalance::Zero => (),
+				}
+			} else {
+				return Err("unsettled approval not in the target list".into());
+			}
+		}
+
 		let mut mismatch_approvals = 0;
 
 		// compare calculated approvals per target with target list state.

substrate/frame/staking/src/pallet/mod.rs

@@ -268,6 +268,19 @@ pub mod pallet {
 		#[pallet::no_default]
 		type TargetList: SortedListProvider<Self::AccountId, Score = BalanceOf<Self>>;
 
+		/// Getter for unsettled approvals scores of targets in stake-tracker. Only used for
+		/// testing and try-state.
+		#[cfg(any(feature = "try-runtime", test))]
+		#[pallet::no_default]
+		type TargetUnsettledApprovals: TypedGet<
+			Type = Vec<(
+				Self::AccountId,
+				pallet_stake_tracker::StakeImbalance<
+					<Self::TargetList as SortedListProvider<Self::AccountId>>::Score,
+				>,
+			)>,
+		>;
+
 		/// The maximum number of `unlocking` chunks a [`StakingLedger`] can
 		/// have. Effectively determines how many unique eras a staker may be
 		/// unbonding in.

substrate/frame/staking/src/tests.rs

@@ -7853,6 +7853,7 @@ mod stake_tracker {
 	use super::*;
 	use frame_election_provider_support::ScoreProvider;
 	use pallet_bags_list::Event as BagsEvent;
+	use pallet_stake_tracker::StakeImbalance;
 	use sp_staking::{StakingAccount::*, StakingInterface};
 
 	// keep tests clean;
@@ -8720,6 +8721,42 @@ mod stake_tracker {
 			);
 		})
 	}
+
+	#[test]
+	fn try_state_with_unsettled_score_works() {
+		ExtBuilder::default()
+			.stake_tracker_update_threshold(Some(50))
+			.try_state(true)
+			.build_and_execute(|| {
+				assert_eq!(Staking::status(&11), Ok(StakerStatus::Validator));
+				assert_eq!(TargetBagsList::score(&11), 1500);
+
+				assert_ok!(Staking::bond(
+					RuntimeOrigin::signed(90),
+					4000,
+					RewardDestination::Staked
+				));
+				assert_ok!(Staking::nominate(RuntimeOrigin::signed(90), vec![11]));
+
+				let vote_weight = Staking::weight_of(&90);
+
+				// confirm that vote weight of new nominator is lower than threshold.
+				assert!((vote_weight as u128) < ScoreStrictUpdateThreshold::get().unwrap());
+
+				// approvals of 42 did not updatee with nomination because new bond's vote weight
+				// was below the upadte threshold.
+				assert_eq!(TargetBagsList::score(&11), 1500);
+
+				// unsettled score map has been updated.
+				assert_eq!(
+					pallet_stake_tracker::UnsettledTargetScores::<Test>::get(),
+					vec![(11, StakeImbalance::Positive(vote_weight as u128))]
+				);
+
+				// he try-state checks takes into consideration the unsetttled score.
+				assert!(Staking::do_try_state(System::block_number()).is_ok());
+			})
+	}
 }
 
 mod ledger {
@@ -9318,7 +9355,8 @@ mod ledger_recovery {
 			assert_eq!(Balances::balance_locked(crate::STAKING_ID, &333), lock_333_before); // OK
 			assert_eq!(Bonded::<Test>::get(&333), Some(444)); // OK
 			assert!(Payee::<Test>::get(&333).is_some()); // OK
-											 // however, ledger associated with its controller was killed.
+
+			// however, ledger associated with its controller was killed.
 			assert!(Ledger::<Test>::get(&444).is_none()); // NOK
 
 			// side effects on 444 - ledger, bonded, payee, lock should be completely removed.

substrate/frame/staking/stake-tracker/Cargo.toml

@@ -19,6 +19,7 @@ codec = { features = [
 
 scale-info = { features = ["derive", "serde"], workspace = true }
 
+sp-std = { workspace = true }
 sp-runtime = { features = ["serde"], workspace = true }
 sp-staking = { features = ["serde"], workspace = true }
 
@@ -56,6 +57,7 @@ std = [
 	"sp-runtime/std",
 	"sp-runtime/std",
 	"sp-staking/std",
+	"sp-std/std",
 	"sp-tracing/std",
 ]