feat: add vested multiplier

protocol/0056-REWA-rewards_overview.md

@@ -209,7 +209,7 @@ Let:
 
 - $d_{i}$ be the payout factor for entity $i$
 - $r_{i}$ be the reward metric value for entity $i$
-- $M_{i}$ be the sum of all reward payout multipliers for entity $i$
+- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)).
 - $s_{i}$ be the share of the rewards for entity $i$
 
 $$d_{i}=r_{i} M_{i}$$
@@ -234,7 +234,7 @@ Let:
 - $s_{i}$ be the share of the rewards for entity $i$
 - $k$ be the decay factor specified in the recurring transfer funding the reward
 - $R_{i}$ be the rank of entity $i$
-- $M_{i}$ be the sum of all reward payout multipliers for entity $i$
+- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)).
 
 $$d_{i}=e^{-k R_{i}} M_{i}$$
 
@@ -255,7 +255,7 @@ Let:
 - $B_{i}$ be the total balance in all of the team members accounts (expressed in quantum)
 - $F$ be the network parameter `rewards.teamDistribution.minimumAccountQuantum`
 - $C$ be the network parameter `rewards.teamDistribution.maximumAccountQuantum`
-- $M_{i}$ be the sum of all reward payout multipliers for entity $i$
+- $M_{i}$ be the sum of all reward payout multipliers for entity $i$ (reward payout multipliers include the [activity streak multiplier](./0086-ASPR-activity_streak_program.md#applying-the-activity-reward-multiplier) and [vested rewards multiplier](./0085-RVST-rewards_vesting.md#determining-the-vested-bonus-multiplier)).
 
 $$d_{i} = \begin{cases}
    0 &\text{if } B_{i} < F \\

protocol/0085-RVST-rewards_vesting.md

@@ -8,6 +8,7 @@ The aim of the rewards vesting mechanics is to prevent farming rewards by delayi
 
 - `rewards.vesting.baseRate`: the proportion of rewards in a vesting account which are vested each epoch, value defaults to `0.1` and must be a float strictly greater than 0.
 - `rewards.vesting.minimumTransfer`: the minimum amount (expressed in quantum) which can be vested each epoch, value defaults to 100 and must be an integer greater or equal than `0`.
+- `rewards.vesting.rewardPayoutMultipliers`: is an ordered list of dictionaries defining the requirements and multipliers for each tier.
 
 ## Vesting mechanics
 
@@ -21,6 +22,7 @@ Now, let:
 - $B_{vested}$ be the total quantum amount in the vesting account
 - $r$ be the network parameter `rewards.vesting.baseRate`
 - $a$ be the account owners current [`activity_streak_vesting_multiplier`](./0086-ASPR-activity_streak_program.md#setting-activity-benefits)
+- $b$ be the account owners current [`vested_rewards_vesting_multiplier`](./0086-ASPR-activity_streak_program.md#setting-activity-benefits)
 - $m$ be the network parameter `rewards.vesting.minimumTransfer`
 
 The quantum amount to be transferred from each "vesting" account to the relevant "vested" account is defined as:
@@ -29,6 +31,35 @@ $$T = max(B_{vesting} * r * a, m)$$
 
 When transferring funds from the vesting account to the vested account, a new transfer type should be used, `TRANSFER_TYPE_REWARDS_VESTED`.
 
+## Vested bonus
+
+Once vested rewards are transferred to the vested account, the party will be able to transfer funds to their general account using a normal transfer.
+
+Alternatively, they can leave their rewards in the vested account to receive a multiplier on their reward payout share. The size of this multiplier is dependent on the balance (expressed in quantum) in the vested account before rewards are distributed.
+
+Note, a party will be unable to transfer funds in to the vested account.
+
+### Determining the vested bonus multiplier
+
+Before [distributing rewards](./0056-REWA-rewards_overview.md#distributing-rewards-amongst-entities), each parties `reward_distribution_vested_multiplier` should be set according to the highest tier they qualify for.
+
+```pseudo
+Given:
+    rewards.vesting.benefitTiers: [
+        [
+            {"minimum_quantum_balance": 10000, "reward_multiplier": 1.0},
+            {"minimum_quantum_balance": 100000, "reward_multiplier": 5.0},
+            {"minimum_quantum_balance": 1000000, "reward_multiplier": 10.0},
+        ],
+    ]
+
+And:
+    vested_quantum_balance=145231
+
+Then:
+    reward_distribution_vested_multiplier=5.0
+```
+
 ## APIs
 
 ### Accounts API