Staking rewards distribution

pallets/pooled-staking/Cargo.toml

@@ -12,6 +12,7 @@ targets = [ "x86_64-unknown-linux-gnu" ]
 [dependencies]
 log = { workspace = true }
 serde = { workspace = true, optional = true }
+tp-core = { workspace = true }
 
 # Substrate
 frame-benchmarking = { workspace = true, optional = true }
@@ -44,6 +45,7 @@ std = [
 	"serde",
 	"sp-runtime/std",
 	"sp-std/std",
+	"tp-core/std",
 ]
 runtime-benchmarks = [ "frame-benchmarking" ]
 try-runtime = [ "frame-support/try-runtime" ]

pallets/pooled-staking/src/benchmarking.rs

@@ -525,6 +525,64 @@ mod benchmarks {
         Ok(())
     }
 
+    #[benchmark]
+    fn distribute_rewards() -> Result<(), BenchmarkError> {
+        const USER_SEED: u32 = 1;
+
+        let source_stake = min_candidate_stk::<T>() * 10u32.into();
+
+        let (caller, _deposit_amount) =
+            create_funded_user::<T>("caller", USER_SEED, source_stake * 2u32.into());
+
+        T::EligibleCandidatesFilter::make_candidate_eligible(&caller, true);
+
+        PooledStaking::<T>::request_delegate(
+            RawOrigin::Signed(caller.clone()).into(),
+            caller.clone(),
+            TargetPool::AutoCompounding,
+            source_stake,
+        )?;
+        PooledStaking::<T>::request_delegate(
+            RawOrigin::Signed(caller.clone()).into(),
+            caller.clone(),
+            TargetPool::ManualRewards,
+            source_stake,
+        )?;
+
+        let timer = T::JoiningRequestTimer::now();
+
+        T::JoiningRequestTimer::skip_to_elapsed();
+
+        PooledStaking::<T>::execute_pending_operations(
+            RawOrigin::Signed(caller.clone()).into(),
+            vec![
+                PendingOperationQuery {
+                    delegator: caller.clone(),
+                    operation: JoiningAutoCompounding {
+                        candidate: caller.clone(),
+                        at: timer.clone(),
+                    },
+                },
+                PendingOperationQuery {
+                    delegator: caller.clone(),
+                    operation: JoiningManualRewards {
+                        candidate: caller.clone(),
+                        at: timer.clone(),
+                    },
+                },
+            ],
+        )?;
+
+        T::Currency::mint_into(&T::StakingAccount::get(), source_stake).unwrap();
+
+        #[block]
+        {
+            crate::pools::distribute_rewards::<T>(&caller, source_stake)?;
+        }
+
+        Ok(())
+    }
+
     impl_benchmark_test_suite!(
         PooledStaking,
         crate::mock::ExtBuilder::default().build(),

pallets/pooled-staking/src/lib.rs

@@ -567,4 +567,13 @@ pub mod pallet {
             .map(|x| x.0)
         }
     }
+
+    impl<T: Config> tp_core::DistributeRewards<Candidate<T>, T::Balance> for Pallet<T> {
+        fn distribute_rewards(
+            candidate: Candidate<T>,
+            rewards: T::Balance,
+        ) -> DispatchResultWithPostInfo {
+            pools::distribute_rewards::<T>(&candidate, rewards)
+        }
+    }
 }

pallets/pooled-staking/src/pools.rs

@@ -16,11 +16,16 @@
 
 use {
     crate::{
+        candidate::Candidates,
         traits::{ErrAdd, ErrMul, ErrSub, MulDiv},
-        Candidate, Config, Delegator, Error, Pools, PoolsKey, Shares, Stake,
+        Candidate, Config, Delegator, Error, Event, Pallet, Pools, PoolsKey, Shares, Stake,
     },
     core::marker::PhantomData,
-    frame_support::ensure,
+    frame_support::{
+        ensure,
+        pallet_prelude::DispatchResultWithPostInfo,
+        traits::{fungible::Mutate, tokens::Preservation},
+    },
     sp_core::Get,
     sp_runtime::traits::{CheckedAdd, CheckedDiv, Zero},
 };
@@ -361,6 +366,34 @@ impl<T: Config> ManualRewards<T> {
         Ok(Stake(diff.err_mul(&shares.0)?))
     }
 
+    /// Increase the rewards of the ManualRewards pool with best effort.
+    /// Returns the actual amount distributed (after rounding).
+    pub fn increase_rewards(
+        candidate: &Candidate<T>,
+        rewards: Stake<T::Balance>,
+    ) -> Result<Stake<T::Balance>, Error<T>> {
+        let Shares(supply) = Self::shares_supply(&candidate);
+        if supply.is_zero() {
+            return Ok(Stake(Zero::zero()));
+        }
+
+        let rewards_per_share = rewards
+            .0
+            .checked_div(&supply)
+            .ok_or(Error::<T>::InconsistentState)?;
+        if rewards_per_share.is_zero() {
+            return Ok(Stake(Zero::zero()));
+        }
+
+        let rewards = rewards_per_share.err_mul(&supply)?;
+
+        let counter = Pools::<T>::get(candidate, &PoolsKey::ManualRewardsCounter);
+        let counter = counter.err_add(&rewards_per_share)?;
+        Pools::<T>::set(candidate, &PoolsKey::ManualRewardsCounter, counter);
+
+        Ok(Stake(rewards))
+    }
+
     pub fn claim_rewards(
         candidate: &Candidate<T>,
         delegator: &Delegator<T>,
@@ -396,3 +429,133 @@ impl<T: Config> ManualRewards<T> {
         Ok(Stake(rewards))
     }
 }
+
+/// Perform rewards distribution for the provided candidate.
+///
+/// The pallet considered that it already posses the rewards in its account,
+/// and it is the responsibility of the caller to transfer or mint the currency
+/// to the staking pallet account.
+///
+/// Rewards are split using `RewardsCollatorCommission` between the candidate
+/// and all the delegators (including the candidate self-delegation). For each,
+/// the rewards are then split according to the value of all the ManualRewards
+/// and AutoCompounding shares.
+///
+/// As candidate rewards will give increase the candidate auto compounding
+/// self-delegation, the delegator rewards are distributed first. ManualRewards
+/// pool rewards are first distributed by increasing the pool counter, which may
+/// result in some rounding. As distributing the AutoCompounding pool rewards
+/// consists of simply increasing `AutoCompoundingSharesTotalStaked`, it is not
+/// subject to rounding and it can absorb the rounding dust from ManualRewards
+/// reward distribution.
+///
+/// Then it is time to distribute the candidate dedicated rewards. For
+/// AutoCompounding, it is as if the candidate received the rewards then
+/// self-delegated (instantly). It is thus implemented by creating new
+/// AutoCompounding shares. This can lead to some rounding, which will be
+/// absorbed in the ManualRewards distribution, which simply consist of
+/// transfering the funds to the candidate account.
+pub fn distribute_rewards<T: Config>(
+    candidate: &Candidate<T>,
+    rewards: T::Balance,
+) -> DispatchResultWithPostInfo {
+    let candidate_manual_rewards = distribute_rewards_inner::<T>(candidate, rewards)?;
+
+    if !candidate_manual_rewards.is_zero() {
+        T::Currency::transfer(
+            &T::StakingAccount::get(),
+            &candidate,
+            candidate_manual_rewards,
+            Preservation::Preserve,
+        )?;
+    }
+
+    Ok(().into())
+}
+
+fn distribute_rewards_inner<T: Config>(
+    candidate: &Candidate<T>,
+    rewards: T::Balance,
+) -> Result<T::Balance, Error<T>> {
+    // `RewardsCollatorCommission` is a `Perbill` so we're not worried about overflow.
+    let candidate_rewards = T::RewardsCollatorCommission::get() * rewards;
+    let delegators_rewards = rewards.err_sub(&candidate_rewards)?;
+
+    let Stake(auto_total_stake) = AutoCompounding::<T>::total_staked(candidate);
+    let Stake(manual_total_stake) = ManualRewards::<T>::total_staked(candidate);
+    let combined_total_stake = auto_total_stake.err_add(&manual_total_stake)?;
+
+    let candidate_manual_stake = if manual_total_stake.is_zero() {
+        Zero::zero()
+    } else {
+        ManualRewards::<T>::computed_stake(candidate, candidate)?.0
+    };
+
+    // Distribute delegators ManualRewards rewards, it implies some rounding.
+    let delegators_manual_rewards = if manual_total_stake.is_zero() {
+        Zero::zero()
+    } else {
+        let rewards = delegators_rewards.mul_div(manual_total_stake, combined_total_stake)?;
+        ManualRewards::<T>::increase_rewards(&candidate, Stake(rewards))?.0
+    };
+
+    // Distribute delegators AutoCompounding rewards with dust from ManualRewards.
+    // If there is no auto compounding stake but auto compounding rewards it
+    // means it comes from manual rewards rounding. Having non-zero total stake
+    // with 0 share supply will cause issues, so in this case we distribute this
+    // dust as candidate manual rewards.
+    let delegators_auto_rewards = delegators_rewards.err_sub(&delegators_manual_rewards)?;
+    let (delegators_auto_rewards, delegators_auto_dust) = if !auto_total_stake.is_zero() {
+        AutoCompounding::<T>::share_stake_among_holders(candidate, Stake(delegators_auto_rewards))?;
+        (delegators_auto_rewards, Zero::zero())
+    } else {
+        (Zero::zero(), delegators_auto_rewards)
+    };
+
+    // Distribute candidate AutoCompounding rewards, it implies some rounding.
+    let candidate_auto_rewards = if auto_total_stake.is_zero() {
+        Zero::zero()
+    } else {
+        'a: {
+            let candidate_auto_stake =
+                AutoCompounding::<T>::computed_stake(candidate, candidate)?.0;
+            let candidate_combined_stake = candidate_manual_stake.err_add(&candidate_auto_stake)?;
+
+            if candidate_combined_stake.is_zero() {
+                break 'a Zero::zero();
+            }
+
+            let rewards =
+                candidate_rewards.mul_div(candidate_auto_stake, candidate_combined_stake)?;
+            let new_shares = AutoCompounding::<T>::stake_to_shares(candidate, Stake(rewards))?;
+
+            if new_shares.0.is_zero() {
+                break 'a Zero::zero();
+            }
+
+            AutoCompounding::<T>::add_shares(candidate, candidate, new_shares)?.0
+        }
+    };
+
+    // Distribute candidate ManualRewards rewards with dust from AutoCompounding.
+    // The amount is returned by the function and will be transfered to the candidate account.
+    let candidate_manual_rewards = candidate_rewards
+        .err_sub(&candidate_auto_rewards)?
+        .err_add(&delegators_auto_dust)?;
+
+    let additional_stake = delegators_auto_rewards.err_add(&candidate_auto_rewards)?;
+    Candidates::<T>::add_total_stake(candidate, &Stake(additional_stake))?;
+
+    Pallet::<T>::deposit_event(Event::<T>::RewardedCollator {
+        collator: candidate.clone(),
+        auto_compounding_rewards: candidate_auto_rewards,
+        manual_claim_rewards: candidate_manual_rewards,
+    });
+    Pallet::<T>::deposit_event(Event::<T>::RewardedDelegators {
+        collator: candidate.clone(),
+        auto_compounding_rewards: delegators_auto_rewards,
+        manual_claim_rewards: delegators_manual_rewards,
+    });
+
+    Ok(candidate_manual_rewards)
+}

pallets/pooled-staking/src/tests/mod.rs

@@ -18,6 +18,7 @@ mod candidates;
 mod delegator_flow;
 mod manual_rewards;
 mod rebalance;
+mod rewards;
 
 use {
     crate::{