rewards improvements (#760)

* added reward pool example in python

* cleaned up python

* cleaned up tests

* starting prove

* spelling

* prove of rewards maths

* claim single reward

* fmt

* more code reuse in rewards

* Update rewards/README.md

Co-authored-by: zqhxuyuan <[email protected]>

* Update rewards/README.md

Co-authored-by: zqhxuyuan <[email protected]>

* Update rewards/README.md

Co-authored-by: zqhxuyuan <[email protected]>

* Update rewards/README.md

Co-authored-by: zqhxuyuan <[email protected]>

* Update rewards/README.md

Co-authored-by: zqhxuyuan <[email protected]>

* fixed clippy

Co-authored-by: zqhxuyuan <[email protected]>

Author: dzmitry-lahoda

rewards/README.md

@@ -6,7 +6,7 @@ This module exposes capabilities for staking rewards.
 
 ### Single asset algorithm
 
-If to consider single pool with single reward asset, generally it will behave as next:
+If consider a single pool with a single reward asset, generally it will behave as next:
 
 ```python
 from collections import defaultdict
@@ -23,10 +23,10 @@ def inflate(pool, user_share):
 
 def add_share(pool, users, user, user_share):
     # virtually we add more rewards, but claim they were claimed by user
-    # so until `rewards` grows, users will not be able to claim more than zero
+    # so until `rewards` grows, user will not be able to claim more than zero
     to_withdraw = inflate(pool, user_share)
-    pool["rewards"] = pool["rewards"] +  to_withdraw
-    pool["withdrawn_rewards"] = pool["withdrawn_rewards"] +  to_withdraw
+    pool["rewards"] = pool["rewards"] + to_withdraw
+    pool["withdrawn_rewards"] = pool["withdrawn_rewards"] + to_withdraw
     pool["shares"] += user_share
     user = users[user]
     user["shares"] += user_share
@@ -43,3 +43,31 @@ def claim_rewards(pool, users, user):
     user["withdrawn_rewards"] += to_withdraw
     return to_withdraw
 ```
+
+### Prove
+
+We want to prove that when a new share is added, it does not dilute previous rewards.
+
+The user who adds a share after the reward is accumulated, will not get any part of the previous reward.
+
+Let $R_n$ be the amount of the current reward asset.
+
+Let $s_i$ be the stake of any specific user our of $m$ total users.
+
+User current reward share equals $$r_i = R_n * ({s_i} / {\sum_{i=1}^m s_i}) $$
+
+User $m + 1$ brings his share, so $$r_i' = R_n * ({s_i} / {\sum_{i=1}^{m+1} s_i}) $$
+
+$r_i > r_i'$, so the original share was diluted and a new user can claim the share of existing users.
+
+What if we increase $R_n$ by $\delta_R$ so that original users get the same share.
+
+We get:
+
+$$ R_n * ({s_i} / {\sum_{i=1}^m s_i}) = ({R_n + \delta_R}) * ({s_i} / {\sum_{i=1}^{m+1} s_i})$$
+
+After easy to do algebraic simplification we get
+
+$$ \delta_R = R_n * ({s_m}/{\sum_{i=1}^{m} s_i}) $$
+
+So for new share we increase reward pool. To compensate for that $\delta_R$ amount is marked as withdrawn from pool by new user.

rewards/src/lib.rs

@@ -272,34 +272,92 @@ impl<T: Config> Pallet<T> {
 					let total_shares = U256::from(pool_info.total_shares.to_owned().saturated_into::<u128>());
 					pool_info.rewards.iter_mut().for_each(
 						|(reward_currency, (total_reward, total_withdrawn_reward))| {
-							let withdrawn_reward = withdrawn_rewards.get(reward_currency).copied().unwrap_or_default();
-
-							let total_reward_proportion: T::Balance =
-								U256::from(share.to_owned().saturated_into::<u128>())
-									.saturating_mul(U256::from(total_reward.to_owned().saturated_into::<u128>()))
-									.checked_div(total_shares)
-									.unwrap_or_default()
-									.as_u128()
-									.unique_saturated_into();
-
-							let reward_to_withdraw = total_reward_proportion
-								.saturating_sub(withdrawn_reward)
-								.min(total_reward.saturating_sub(*total_withdrawn_reward));
-
-							if reward_to_withdraw.is_zero() {
-								return;
-							}
-
-							*total_withdrawn_reward = total_withdrawn_reward.saturating_add(reward_to_withdraw);
-							withdrawn_rewards
-								.insert(*reward_currency, withdrawn_reward.saturating_add(reward_to_withdraw));
-
-							// pay reward to `who`
-							T::Handler::payout(who, pool, *reward_currency, reward_to_withdraw);
+							Self::claim_one(
+								withdrawn_rewards,
+								*reward_currency,
+								share,
+								total_reward,
+								total_shares,
+								total_withdrawn_reward,
+								who,
+								pool,
+							);
 						},
 					);
 				});
 			}
 		});
 	}
+
+	pub fn claim_reward(who: &T::AccountId, pool: &T::PoolId, reward_currency: T::CurrencyId) {
+		SharesAndWithdrawnRewards::<T>::mutate_exists(pool, who, |maybe_share_withdrawn| {
+			if let Some((share, withdrawn_rewards)) = maybe_share_withdrawn {
+				if share.is_zero() {
+					return;
+				}
+
+				PoolInfos::<T>::mutate(pool, |pool_info| {
+					let total_shares = U256::from(pool_info.total_shares.to_owned().saturated_into::<u128>());
+					if let Some((total_reward, total_withdrawn_reward)) = pool_info.rewards.get_mut(&reward_currency) {
+						Self::claim_one(
+							withdrawn_rewards,
+							reward_currency,
+							share,
+							total_reward,
+							total_shares,
+							total_withdrawn_reward,
+							who,
+							pool,
+						);
+					}
+				});
+			}
+		});
+	}
+
+	#[allow(clippy::too_many_arguments)] // just we need to have all these to do the stuff
+	fn claim_one(
+		withdrawn_rewards: &mut BTreeMap<T::CurrencyId, T::Balance>,
+		reward_currency: T::CurrencyId,
+		share: &mut T::Share,
+		total_reward: &mut T::Balance,
+		total_shares: U256,
+		total_withdrawn_reward: &mut T::Balance,
+		who: &T::AccountId,
+		pool: &T::PoolId,
+	) {
+		let withdrawn_reward = withdrawn_rewards.get(&reward_currency).copied().unwrap_or_default();
+		let reward_to_withdraw = Self::reward_to_withdraw(
+			share,
+			total_reward,
+			total_shares,
+			withdrawn_reward,
+			total_withdrawn_reward,
+		);
+		if !reward_to_withdraw.is_zero() {
+			*total_withdrawn_reward = total_withdrawn_reward.saturating_add(reward_to_withdraw);
+			withdrawn_rewards.insert(reward_currency, withdrawn_reward.saturating_add(reward_to_withdraw));
+
+			// pay reward to `who`
+			T::Handler::payout(who, pool, reward_currency, reward_to_withdraw);
+		}
+	}
+
+	fn reward_to_withdraw(
+		share: &mut T::Share,
+		total_reward: &mut T::Balance,
+		total_shares: U256,
+		withdrawn_reward: T::Balance,
+		total_withdrawn_reward: &mut T::Balance,
+	) -> T::Balance {
+		let total_reward_proportion: T::Balance = U256::from(share.to_owned().saturated_into::<u128>())
+			.saturating_mul(U256::from(total_reward.to_owned().saturated_into::<u128>()))
+			.checked_div(total_shares)
+			.unwrap_or_default()
+			.as_u128()
+			.unique_saturated_into();
+		total_reward_proportion
+			.saturating_sub(withdrawn_reward)
+			.min(total_reward.saturating_sub(*total_withdrawn_reward))
+	}
 }

rewards/src/tests.rs

@@ -507,3 +507,26 @@ fn share_to_zero_removes_storage() {
 		assert_eq!(SharesAndWithdrawnRewards::<Runtime>::contains_key(DOT_POOL, BOB), false);
 	});
 }
+
+#[test]
+fn claim_single_reward() {
+	ExtBuilder::default().build().execute_with(|| {
+		assert_eq!(RewardsModule::pool_infos(DOT_POOL), PoolInfo::default());
+
+		RewardsModule::add_share(&ALICE, &DOT_POOL, 100);
+
+		assert_ok!(RewardsModule::accumulate_reward(&DOT_POOL, NATIVE_COIN, 100));
+		assert_ok!(RewardsModule::accumulate_reward(&DOT_POOL, STABLE_COIN, 200));
+		RewardsModule::claim_reward(&ALICE, &DOT_POOL, STABLE_COIN);
+
+		assert_eq!(
+			RewardsModule::pool_infos(DOT_POOL),
+			PoolInfo {
+				total_shares: 100,
+				rewards: vec![(NATIVE_COIN, (100, 0)), (STABLE_COIN, (200, 200))]
+					.into_iter()
+					.collect(),
+			}
+		);
+	});
+}