Implements a % cap on staking rewards from era inflation

prdoc/pr_1660.prdoc

@@ -0,0 +1,12 @@
+title: Implements a percentage cap on staking rewards from era inflation
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      The `pallet-staking` exposes a new perbill configuration, `MaxStakersRewards`, which caps the
+      amount of era inflation that is distributed to the stakers. The remainder of the era
+      inflation is minted directly into `T::RewardRemainder` account. This allows the runtime to be
+      configured to assign a minimum inflation value per era to a specific account (e.g. treasury).
+
+crates: 
+ - name: pallet-staking 

substrate/frame/staking/src/benchmarking.rs

@@ -948,6 +948,13 @@ benchmarks! {
 		assert_eq!(MinCommission::<T>::get(), Perbill::from_percent(100));
 	}
 
+	set_max_staked_rewards {
+		let treasury_fraction = Percent::max_value();
+	}: _(RawOrigin::Root, treasury_fraction)
+	verify {
+		assert_eq!(MaxStakedRewards::<T>::get(), Some(Percent::from_parts(100)));
+	}
+
 	impl_benchmark_test_suite!(
 		Staking,
 		crate::mock::ExtBuilder::default().has_stakers(true),

substrate/frame/staking/src/lib.rs

@@ -202,6 +202,12 @@
 //! ```nocompile
 //! remaining_payout = max_yearly_inflation * total_tokens / era_per_year - staker_payout
 //! ```
+//!
+//! Note, however, that it is possible to set a cap on the total `staker_payout` for the era through
+//! the `MaxStakersRewards` storage type. The `era_payout` implementor must ensure that the
+//! `max_payout = remaining_payout + (staker_payout * max_stakers_rewards)`. The excess payout that
+//! is not allocated for stakers is the era remaining reward.
+//!
 //! The remaining reward is send to the configurable end-point [`Config::RewardRemainder`].
 //!
 //! ### Reward Calculation
@@ -903,8 +909,10 @@ impl<Balance: Default> EraPayout<Balance> for () {
 /// Adaptor to turn a `PiecewiseLinear` curve definition into an `EraPayout` impl, used for
 /// backwards compatibility.
 pub struct ConvertCurve<T>(sp_std::marker::PhantomData<T>);
-impl<Balance: AtLeast32BitUnsigned + Clone, T: Get<&'static PiecewiseLinear<'static>>>
-	EraPayout<Balance> for ConvertCurve<T>
+impl<Balance, T> EraPayout<Balance> for ConvertCurve<T>
+where
+	Balance: AtLeast32BitUnsigned + Clone + Copy,
+	T: Get<&'static PiecewiseLinear<'static>>,
 {
 	fn era_payout(
 		total_staked: Balance,
@@ -918,7 +926,7 @@ impl<Balance: AtLeast32BitUnsigned + Clone, T: Get<&'static PiecewiseLinear<'sta
 			// Duration of era; more than u64::MAX is rewarded as u64::MAX.
 			era_duration_millis,
 		);
-		let rest = max_payout.saturating_sub(validator_payout.clone());
+		let rest = max_payout.saturating_sub(validator_payout);
 		(validator_payout, rest)
 	}
 }

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

@@ -36,7 +36,7 @@ use frame_system::{pallet_prelude::BlockNumberFor, RawOrigin};
 use pallet_session::historical;
 use sp_runtime::{
 	traits::{Bounded, Convert, One, SaturatedConversion, Saturating, StaticLookup, Zero},
-	Perbill,
+	Perbill, Percent,
 };
 use sp_staking::{
 	currency_to_vote::CurrencyToVote,
@@ -506,9 +506,18 @@ impl<T: Config> Pallet<T> {
 				.saturated_into::<u64>();
 			let staked = Self::eras_total_stake(&active_era.index);
 			let issuance = T::Currency::total_issuance();
+
 			let (validator_payout, remainder) =
 				T::EraPayout::era_payout(staked, issuance, era_duration);
 
+			let total_payout = validator_payout.saturating_add(remainder);
+			let max_staked_rewards =
+				MaxStakedRewards::<T>::get().unwrap_or(Percent::from_percent(100));
+
+			// apply cap to validators payout and add difference to remainder.
+			let validator_payout = validator_payout.min(max_staked_rewards * total_payout);
+			let remainder = total_payout.saturating_sub(validator_payout);
+
 			Self::deposit_event(Event::<T>::EraPaid {
 				era_index: active_era.index,
 				validator_payout,

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

@@ -564,6 +564,12 @@ pub mod pallet {
 	#[pallet::getter(fn force_era)]
 	pub type ForceEra<T> = StorageValue<_, Forcing, ValueQuery>;
 
+	/// Maximum staked rewards, i.e. the percentage of the era inflation that
+	/// is used for stake rewards.
+	/// See [Era payout](./index.html#era-payout).
+	#[pallet::storage]
+	pub type MaxStakedRewards<T> = StorageValue<_, Percent, OptionQuery>;
+
 	/// The percentage of the slash that is distributed to reporters.
 	///
 	/// The rest of the slashed value is handled by the `Slash`.
@@ -1970,6 +1976,15 @@ pub mod pallet {
 			}
 			Ok(Some(T::WeightInfo::deprecate_controller_batch(controllers.len() as u32)).into())
 		}
+
+		/// Sets the fraction of the maximum staked rewards of the era's inflation.
+		#[pallet::call_index(29)]
+		#[pallet::weight(T::WeightInfo::set_max_staked_rewards())]
+		pub fn set_max_staked_rewards(origin: OriginFor<T>, new: Percent) -> DispatchResult {
+			T::AdminOrigin::ensure_origin(origin)?;
+			MaxStakedRewards::<T>::put(new);
+			Ok(())
+		}
 	}
 }
 

substrate/frame/staking/src/tests.rs

@@ -1739,6 +1739,63 @@ fn rebond_emits_right_value_in_event() {
 	});
 }
 
+#[test]
+fn max_staked_rewards_default_works() {
+	ExtBuilder::default().build_and_execute(|| {
+		assert_eq!(<MaxStakedRewards<Test>>::get(), None);
+
+		let default_stakers_payout = current_total_payout_for_duration(reward_time_per_era());
+		assert!(default_stakers_payout > 0);
+		start_active_era(1);
+
+		// the final stakers reward is the same as the reward before applied the cap.
+		assert_eq!(ErasValidatorReward::<Test>::get(0).unwrap(), default_stakers_payout);
+
+		// which is the same behaviour if the `MaxStakedRewards` is set to 100%.
+		<MaxStakedRewards<Test>>::set(Some(Percent::from_parts(100)));
+
+		let default_stakers_payout = current_total_payout_for_duration(reward_time_per_era());
+		assert_eq!(ErasValidatorReward::<Test>::get(0).unwrap(), default_stakers_payout);
+	})
+}
+
+#[test]
+fn max_staked_rewards_works() {
+	ExtBuilder::default().nominate(true).build_and_execute(|| {
+		let max_staked_rewards = 10;
+
+		<MaxStakedRewards<Test>>::set(Some(Percent::from_percent(max_staked_rewards)));
+		assert_eq!(<MaxStakedRewards<Test>>::get(), Some(Percent::from_percent(10)));
+
+		// check validators account state.
+		assert_eq!(Session::validators().len(), 2);
+		assert!(Session::validators().contains(&11) & Session::validators().contains(&21));
+		// balance of the mock treasury account is 0
+		assert_eq!(RewardRemainderUnbalanced::get(), 0);
+
+		let max_stakers_payout = current_total_payout_for_duration(reward_time_per_era());
+
+		start_active_era(1);
+
+		let treasury_payout = RewardRemainderUnbalanced::get();
+		let validators_payout = ErasValidatorReward::<Test>::get(0).unwrap();
+		let total_payout = treasury_payout + validators_payout;
+
+		// max stakers payout (without max staked rewards cap applied) is larger than the final
+		// validator rewards. The final payment and remainder should be adjusted by redestributing
+		// the era inflation to apply the cap...
+		assert!(max_stakers_payout > validators_payout);
+
+		// .. which means that the final validator payout is 10% of the total payout..
+		assert_eq!(validators_payout, Percent::from_percent(max_staked_rewards) * total_payout);
+		// .. and the remainder 90% goes to the treasury.
+		assert_eq!(
+			treasury_payout,
+			Percent::from_percent(100 - max_staked_rewards) * (treasury_payout + validators_payout)
+		);
+	})
+}
+
 #[test]
 fn reward_to_stake_works() {
 	ExtBuilder::default()
@@ -6363,6 +6420,23 @@ fn set_min_commission_works_with_admin_origin() {
 	})
 }
 
+#[test]
+fn set_max_staked_rewards_with_admin_origin_works() {
+	ExtBuilder::default().build_and_execute(|| {
+		assert_eq!(MaxStakedRewards::<Test>::get(), None);
+
+		// root can set the max staked rewards.
+		assert_ok!(Staking::set_max_staked_rewards(RuntimeOrigin::root(), Percent::from_parts(10)));
+		assert_eq!(MaxStakedRewards::<Test>::get(), Some(Percent::from_parts(10)));
+
+		// non priviledged origin cannot set max staked rewards.
+		assert_noop!(
+			Staking::set_max_staked_rewards(RuntimeOrigin::signed(2), Percent::from_parts(15)),
+			BadOrigin
+		);
+	})
+}
+
 #[test]
 fn can_page_exposure() {
 	let mut others: Vec<IndividualExposure<AccountId, Balance>> = vec![];