Introduce Payees and PayoutDestination with Split variant

frame/fast-unstake/src/mock.rs

@@ -25,7 +25,7 @@ use frame_support::{
 };
 use sp_runtime::{
 	traits::{Convert, IdentityLookup},
-	BuildStorage,
+	BuildStorage, Perbill,
 };
 
 use pallet_staking::{Exposure, IndividualExposure, StakerStatus};
@@ -369,7 +369,7 @@ pub fn create_exposed_nominator(exposed: AccountId, era: u32) {
 	assert_ok!(Staking::bond(
 		RuntimeOrigin::signed(exposed),
 		10,
-		pallet_staking::RewardDestination::Staked
+		pallet_staking::PayoutDestination::Split((Perbill::from_percent(50), exposed))
 	));
 	assert_ok!(Staking::nominate(RuntimeOrigin::signed(exposed), vec![exposed]));
 	// register the exposed one.

frame/fast-unstake/src/tests.rs

@@ -20,9 +20,9 @@
 use super::*;
 use crate::{mock::*, types::*, Event};
 use frame_support::{pallet_prelude::*, testing_prelude::*, traits::Currency};
-use pallet_staking::{CurrentEra, RewardDestination};
+use pallet_staking::{CurrentEra, PayoutDestination};
 
-use sp_runtime::traits::BadOrigin;
+use sp_runtime::{traits::BadOrigin, Perbill};
 use sp_staking::StakingInterface;
 
 #[test]
@@ -815,7 +815,11 @@ mod on_idle {
 
 			// create a new validator that 100% not exposed.
 			Balances::make_free_balance_be(&42, 100 + Deposit::get());
-			assert_ok!(Staking::bond(RuntimeOrigin::signed(42), 10, RewardDestination::Staked));
+			assert_ok!(Staking::bond(
+				RuntimeOrigin::signed(42),
+				10,
+				PayoutDestination::Split((Perbill::from_percent(50), 42))
+			));
 			assert_ok!(Staking::validate(RuntimeOrigin::signed(42), Default::default()));
 
 			// let them register:

frame/nomination-pools/test-staking/src/lib.rs

@@ -25,7 +25,7 @@ use pallet_nomination_pools::{
 	BondedPools, Error as PoolsError, Event as PoolsEvent, LastPoolId, PoolMember, PoolMembers,
 	PoolState,
 };
-use pallet_staking::{CurrentEra, Event as StakingEvent, Payee, RewardDestination};
+use pallet_staking::{CurrentEra, Event as StakingEvent, Payees, PayoutDestination};
 use sp_runtime::traits::Zero;
 
 #[test]
@@ -214,7 +214,7 @@ fn pool_slash_e2e() {
 			]
 		);
 
-		assert_eq!(Payee::<Runtime>::get(POOL1_BONDED), RewardDestination::Account(POOL1_REWARD));
+		assert_eq!(Payees::<Runtime>::get(POOL1_BONDED), PayoutDestination::Deposit(POOL1_REWARD));
 
 		// have two members join
 		assert_ok!(Pools::join(RuntimeOrigin::signed(20), 20, 1));

frame/offences/benchmarking/src/lib.rs

@@ -51,7 +51,7 @@ use pallet_session::{
 use pallet_staking::Event as StakingEvent;
 use pallet_staking::{
 	Config as StakingConfig, Exposure, IndividualExposure, MaxNominationsOf, Pallet as Staking,
-	RewardDestination, ValidatorPrefs,
+	PayoutDestination, ValidatorPrefs,
 };
 
 const SEED: u32 = 0;
@@ -108,15 +108,15 @@ fn bond_amount<T: Config>() -> BalanceOf<T> {
 fn create_offender<T: Config>(n: u32, nominators: u32) -> Result<Offender<T>, &'static str> {
 	let stash: T::AccountId = account("stash", n, SEED);
 	let stash_lookup: LookupSourceOf<T> = T::Lookup::unlookup(stash.clone());
-	let reward_destination = RewardDestination::Staked;
+	let payout_destination = PayoutDestination::Stake;
 	let amount = bond_amount::<T>();
 	// add twice as much balance to prevent the account from being killed.
 	let free_amount = amount.saturating_mul(2u32.into());
 	T::Currency::make_free_balance_be(&stash, free_amount);
 	Staking::<T>::bond(
 		RawOrigin::Signed(stash.clone()).into(),
 		amount,
-		reward_destination.clone(),
+		payout_destination.clone(),
 	)?;
 
 	let validator_prefs =
@@ -134,7 +134,7 @@ fn create_offender<T: Config>(n: u32, nominators: u32) -> Result<Offender<T>, &'
 		Staking::<T>::bond(
 			RawOrigin::Signed(nominator_stash.clone()).into(),
 			amount,
-			reward_destination.clone(),
+			payout_destination.clone(),
 		)?;
 
 		let selected_validators: Vec<LookupSourceOf<T>> = vec![stash_lookup.clone()];

frame/session/benchmarking/src/lib.rs

@@ -34,8 +34,9 @@ use frame_support::{
 use frame_system::{pallet_prelude::BlockNumberFor, RawOrigin};
 use pallet_session::{historical::Pallet as Historical, Pallet as Session, *};
 use pallet_staking::{
-	benchmarking::create_validator_with_nominators, testing_utils::create_validators,
-	MaxNominationsOf, RewardDestination,
+	benchmarking::create_validator_with_nominators,
+	testing_utils::{create_validators, PayoutDestinationOpt},
+	MaxNominationsOf,
 };
 
 const MAX_VALIDATORS: u32 = 1000;
@@ -60,7 +61,7 @@ benchmarks! {
 			MaxNominationsOf::<T>::get(),
 			false,
 			true,
-			RewardDestination::Staked,
+			PayoutDestinationOpt::Stake,
 		)?;
 		let v_controller = pallet_staking::Pallet::<T>::bonded(&v_stash).ok_or("not stash")?;
 
@@ -78,7 +79,7 @@ benchmarks! {
 			MaxNominationsOf::<T>::get(),
 			false,
 			true,
-			RewardDestination::Staked,
+			PayoutDestinationOpt::Stake,
 		)?;
 		let v_controller = pallet_staking::Pallet::<T>::bonded(&v_stash).ok_or("not stash")?;
 		let keys = T::Keys::decode(&mut TrailingZeroInput::zeroes()).unwrap();

frame/staking/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this pallet will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this pallet adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The semantic versioning guarantees cover the interface to the substrate runtime which
+includes this pallet as a dependency. This module will also add storage migrations whenever
+changes require it. Stability with regard to offchain tooling is explicitly excluded from
+this guarantee: For example adding a new field to an in-storage data structure will require
+changes to frontends to properly display it. However, those changes will still be regarded
+as a minor version bump.
+
+## [Unreleased]
+
+### Added
+
+-  Introduce `Payees`` and `PayoutDestination` with `Split` variant, which starts a lazy migration to move existing `Payee` items to a new `Payees` storage item.
+[#14451](https://github.com/paritytech/substrate/pull/14451)

frame/staking/src/benchmarking.rs

@@ -73,17 +73,17 @@ pub fn create_validator_with_nominators<T: Config>(
 	upper_bound: u32,
 	dead_controller: bool,
 	unique_controller: bool,
-	destination: RewardDestination<T::AccountId>,
+	destination_opt: PayoutDestinationOpt<T::AccountId>,
 ) -> Result<(T::AccountId, Vec<(T::AccountId, T::AccountId)>), &'static str> {
 	// Clean up any existing state.
 	clear_validators_and_nominators::<T>();
 	let mut points_total = 0;
 	let mut points_individual = Vec::new();
 
 	let (v_stash, v_controller) = if unique_controller {
-		create_unique_stash_controller::<T>(0, 100, destination.clone(), false)?
+		create_unique_stash_controller::<T>(0, 100, destination_opt.clone(), false)?
 	} else {
-		create_stash_controller::<T>(0, 100, destination.clone())?
+		create_stash_controller::<T>(0, 100, destination_opt.clone())?
 	};
 
 	let validator_prefs =
@@ -100,9 +100,9 @@ pub fn create_validator_with_nominators<T: Config>(
 	// Give the validator n nominators, but keep total users in the system the same.
 	for i in 0..upper_bound {
 		let (n_stash, n_controller) = if !dead_controller {
-			create_stash_controller::<T>(u32::MAX - i, 100, destination.clone())?
+			create_stash_controller::<T>(u32::MAX - i, 100, destination_opt.clone())?
 		} else {
-			create_unique_stash_controller::<T>(u32::MAX - i, 100, destination.clone(), true)?
+			create_unique_stash_controller::<T>(u32::MAX - i, 100, destination_opt.clone(), true)?
 		};
 		if i < n {
 			Staking::<T>::nominate(
@@ -223,10 +223,10 @@ const USER_SEED: u32 = 999666;
 benchmarks! {
 	bond {
 		let stash = create_funded_user::<T>("stash", USER_SEED, 100);
-		let reward_destination = RewardDestination::Staked;
+		let payout_destination = PayoutDestination::Split((Perbill::from_percent(50), stash.clone()));
 		let amount = T::Currency::minimum_balance() * 10u32.into();
 		whitelist_account!(stash);
-	}: _(RawOrigin::Signed(stash.clone()), amount, reward_destination)
+	}: _(RawOrigin::Signed(stash.clone()), amount, payout_destination)
 	verify {
 		assert!(Bonded::<T>::contains_key(stash.clone()));
 		assert!(Ledger::<T>::contains_key(stash));
@@ -466,11 +466,28 @@ benchmarks! {
 
 	set_payee {
 		let (stash, controller) = create_stash_controller::<T>(USER_SEED, 100, Default::default())?;
-		assert_eq!(Payee::<T>::get(&stash), RewardDestination::Staked);
+		assert_eq!(Payees::<T>::get(&stash), PayoutDestination::Stake);
+
+		// Payee should exist to be migrated on `update_payee`.
+		Payee::<T>::insert(&stash,RewardDestination::Staked);
+
+		whitelist_account!(controller);
+	}: _(RawOrigin::Signed(controller.clone()), PayoutDestination::Split((Perbill::from_percent(50), controller.clone())))
+	verify {
+		assert!(!Payee::<T>::contains_key(&stash));
+		assert_eq!(Payees::<T>::get(&stash), PayoutDestination::Split((Perbill::from_percent(50), controller.clone())));
+	}
+
+	update_payee {
+		let (stash, controller) = create_stash_controller::<T>(USER_SEED, 100, Default::default())?;
+		// Payee should exist to be migrated on `update_payee`.
+		Payee::<T>::insert(&stash,RewardDestination::Staked);
+		Payees::<T>::remove(&stash);
+		assert!(!Payees::<T>::contains_key(&stash));
 		whitelist_account!(controller);
-	}: _(RawOrigin::Signed(controller), RewardDestination::Controller)
+	}: _(RawOrigin::Signed(stash.clone()), controller)
 	verify {
-		assert_eq!(Payee::<T>::get(&stash), RewardDestination::Controller);
+		assert_eq!(Payees::<T>::get(&stash), PayoutDestination::Stake);
 	}
 
 	set_controller {
@@ -559,9 +576,10 @@ benchmarks! {
 			T::MaxNominatorRewardedPerValidator::get() as u32,
 			true,
 			true,
-			RewardDestination::Controller,
+			PayoutDestinationOpt::Split((Perbill::from_percent(50), PayoutSplitOpt::Controller)),
 		)?;
 
+		let validator_controller = <Bonded<T>>::get(&validator).unwrap();
 		let current_era = CurrentEra::<T>::get().unwrap();
 		// set the commission for this particular era as well.
 		<ErasValidatorPrefs<T>>::insert(current_era, validator.clone(), <Staking<T>>::validators(&validator));
@@ -593,7 +611,7 @@ benchmarks! {
 			T::MaxNominatorRewardedPerValidator::get() as u32,
 			false,
 			true,
-			RewardDestination::Staked,
+			PayoutDestinationOpt::Split((Perbill::from_percent(50), PayoutSplitOpt::Stash)),
 		)?;
 
 		let current_era = CurrentEra::<T>::get().unwrap();
@@ -910,7 +928,7 @@ benchmarks! {
 
 		// Create a validator with a commission of 50%
 		let (stash, controller) =
-			create_stash_controller::<T>(1, 1, RewardDestination::Staked)?;
+			create_stash_controller::<T>(1, 1, Default::default())?;
 		let validator_prefs =
 			ValidatorPrefs { commission: Perbill::from_percent(50), ..Default::default() };
 		Staking::<T>::validate(RawOrigin::Signed(controller).into(), validator_prefs)?;
@@ -990,7 +1008,7 @@ mod tests {
 				<<Test as Config>::MaxNominatorRewardedPerValidator as Get<_>>::get(),
 				false,
 				false,
-				RewardDestination::Staked,
+				PayoutDestinationOpt::Stake,
 			)
 			.unwrap();
 
@@ -1020,7 +1038,7 @@ mod tests {
 				<<Test as Config>::MaxNominatorRewardedPerValidator as Get<_>>::get(),
 				false,
 				false,
-				RewardDestination::Staked,
+				PayoutDestinationOpt::Stake,
 			)
 			.unwrap();
 

frame/staking/src/lib.rs

@@ -387,7 +387,34 @@ impl<AccountId: Ord> Default for EraRewardPoints<AccountId> {
 	}
 }
 
+/// The payout destination for an account.
+///
+/// NOTE: Being lazily migrated to. Logic pertaining to this enum will be introduced to `set_payee`
+/// and payout logic in a future update, and will replace `RewardDestination`, once all records have
+/// been lazily migrated to this enum.
+#[derive(PartialEq, Eq, Copy, Clone, Encode, Decode, RuntimeDebug, TypeInfo, MaxEncodedLen)]
+pub enum PayoutDestination<AccountId> {
+	/// Payout goes into the stash account and is added to bond.
+	Stake,
+	/// Deposit the specified percentage of payout to the specified account as free balance, and
+	/// pay the rest into the stash account and add to bond. 0% and 100% should be disallowed and
+	/// handled as `Stake` and `Deposit` respectively.
+	Split((Perbill, AccountId)),
+	/// Deposit payout as free balance to an account.
+	Deposit(AccountId),
+	/// Receive no payout.
+	Forgo,
+}
+
+impl<AccountId> Default for PayoutDestination<AccountId> {
+	fn default() -> Self {
+		PayoutDestination::Stake
+	}
+}
+
 /// A destination account for payment.
+/// NOTE: Being lazily migrated and deprecated in favour of `PayoutDestination`.
+/// Tracking at <https://github.com/paritytech/substrate/issues/14438>
 #[derive(PartialEq, Eq, Copy, Clone, Encode, Decode, RuntimeDebug, TypeInfo, MaxEncodedLen)]
 pub enum RewardDestination<AccountId> {
 	/// Pay into the stash account, increasing the amount at stake accordingly.
@@ -402,12 +429,28 @@ pub enum RewardDestination<AccountId> {
 	None,
 }
 
-impl<AccountId> Default for RewardDestination<AccountId> {
+impl<AccountId: Clone> Default for RewardDestination<AccountId> {
 	fn default() -> Self {
 		RewardDestination::Staked
 	}
 }
 
+impl<AccountId: Clone> RewardDestination<AccountId> {
+	fn to_payout_destination(
+		&self,
+		stash: AccountId,
+		controller: AccountId,
+	) -> PayoutDestination<AccountId> {
+		match self {
+			RewardDestination::Staked => PayoutDestination::Stake,
+			RewardDestination::Stash => PayoutDestination::Deposit(stash),
+			RewardDestination::Controller => PayoutDestination::Deposit(controller),
+			RewardDestination::Account(a) => PayoutDestination::Deposit(a.clone()),
+			RewardDestination::None => PayoutDestination::Forgo,
+		}
+	}
+}
+
 /// Preference of what happens regarding validation.
 #[derive(PartialEq, Eq, Clone, Encode, Decode, RuntimeDebug, TypeInfo, Default, MaxEncodedLen)]
 pub struct ValidatorPrefs {