vacp2p/staking-reward-streamer
1
0
Fork 0
mirror of https://github.com/vacp2p/staking-reward-streamer.git synced 2026-01-09 21:18:01 -05:00
Code Issues Packages Projects Releases Wiki Activity

chore(MathSpec.md): Merge ScalableRewardDistribution.md with MathSpec, fix formatting for GitHub Markdown

Browse Source
This commit is contained in:
Ricardo Guilherme Schmidt
2024-12-21 00:54:15 -03:00
parent 33c0431ec2
commit 624bf803e2
2 changed files with 302 additions and 323 deletions
Download Patch File Download Diff File Expand all files Collapse all files

409
docs/MathSpec.md
View File

@@ -1,3 +1,5 @@
## Table of Contents
## Mathematical Specification of Staking Protocol
<!-- prettier-ignore -->
@@ -14,7 +16,7 @@
| $M_{MAX}$ | | $\pu{4 \mathrm{(1)}}$ | (1) | Maximum multiplier of annual percentage yield. |
| $\mathtt{APY}$ | | 100 | percent | Annual percentage yield for multiplier points. |
| $\mathsf{MPY}$ | $M_{MAX} \times \mathtt{APY}$ | 400 | percent | Multiplier points accrued maximum percentage yield. |
| $\mathsf{MPY}^\mathit{abs}$ | $100 + (2 \times M_{MAX} \times \mathtt{APY})$ | 900 | percent | Multiplier points absolute maximum percentage yield. |
| $\mathsf{MPY}^\mathit{abs}$ | $100 + (2 \times M_{\text{MAX}} \times \mathtt{APY})$ | 900 | percent | Multiplier points absolute maximum percentage yield. |
| $T_{RATE}$ | (minimal blocktime) | 12 | seconds | The accrue rate period of time over which multiplier points are calculated. |
| $T_{DAY}$ | | 86400 | seconds | One day. |
| $T_{YEAR}$ | $\lfloor365.242190 \times T_{DAY}\rfloor$ | 31556925 | seconds | One (mean) tropical year. |
@@ -86,8 +88,8 @@ $$
The value of $t_{lock,end}$ can be updated only within the functions:
- $\mathcal{f}^{stake}(\mathbb{Account}, \Delta a, \Delta t_{lock})$;
- $\mathcal{f}^{lock}(\mathbb{Account}, \Delta t_{lock})$;
- $\mathcal{f}^{stake}(\mathbb{Acc}, \Delta a, \Delta t_{lock})$;
- $\mathcal{f}^{lock}(\mathbb{Acc}, \Delta t_{lock})$;
---
@@ -101,10 +103,10 @@ $$
The value of $t_{last}$ is updated by all functions that change state:
- $f^{accrue}(\mathbb{Account}, a_{bal},\Delta t)$,
- $\mathcal{f}^{stake}(\mathbb{Account}, \Delta a, \Delta t_{lock})$;
- $\mathcal{f}^{lock}(\mathbb{Account}, \Delta t_{lock})$;
- $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a)$;
- $f^{accrue}(\mathbb{Acc}, a_{bal},\Delta t)$,
- $\mathcal{f}^{stake}(\mathbb{Acc}, \Delta a, \Delta t_{lock})$;
- $\mathcal{f}^{lock}(\mathbb{Acc}, \Delta t_{lock})$;
- $\mathcal{f}^{unstake}(\mathbb{Acc}, \Delta a)$;
---
@@ -116,9 +118,9 @@ Relates as $mp_\mathcal{M} \propto a_{bal} \cdot (t_{lock} + \mathsf{MPY})$.
Altered by functions that change the account state:
- $\mathcal{f}^{stake}(\mathbb{Account}, \Delta a, \Delta t_{lock})$;
- $\mathcal{f}^{lock}(\mathbb{Account}, \Delta t_{lock})$;
- $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a)$.
- $\mathcal{f}^{stake}(\mathbb{Acc}, \Delta a, \Delta t_{lock})$;
- $\mathcal{f}^{lock}(\mathbb{Acc}, \Delta t_{lock})$;
- $\mathcal{f}^{unstake}(\mathbb{Acc}, \Delta a)$.
It's state can be expressed as the following state changes:
@@ -126,10 +128,10 @@ It's state can be expressed as the following state changes:
$$
\begin{aligned}
mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) \\
&\quad + mp_\mathcal{B}(\Delta a, t_{lock,\Delta} + t_{lock}) \\
&\quad + mp_\mathcal{B}(a_{bal}, t_{lock}) \\
&\quad + mp_\mathcal{I}(\Delta a)
mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) \\
&\quad + mp_\mathcal{B}(\Delta a, t_{lock,\Delta} + t_{lock}) \\
&\quad + mp_\mathcal{B}(a_{bal}, t_{lock}) \\
&\quad + mp_\mathcal{I}(\Delta a)
\end{aligned}
$$
@@ -137,9 +139,9 @@ $$
$$
\begin{aligned}
mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) \\
&\quad + mp_\mathcal{B}(\Delta a, t_{lock,\Delta}) \\
&\quad + mp_\mathcal{I}(\Delta a)
mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) \\
&\quad + mp_\mathcal{B}(\Delta a, t_{lock,\Delta}) \\
&\quad + mp_\mathcal{I}(\Delta a)
\end{aligned}
$$
@@ -161,26 +163,26 @@ $$
Altered by all functions that change state:
- [[#$mathcal{f} {stake}( mathbb{Account}, Delta a, t_{lock}) longrightarrow$ Stake Amount With Lock]]
- [[#$ mathcal{f} {lock}( mathbb{Account}, t_{lock}) longrightarrow$ Increase Lock]];
- [[#$ mathcal{f} {unstake}( mathbb{Account}, Delta a) longrightarrow$ Unstake Amount Unlocked]];
- [[#$ mathcal{f} {accrue}( mathbb{Account}) longrightarrow$ Accrue Multiplier Points]].
- $\mathcal{f}^{stake}( \mathbb{Acc}, Delta a, t_{lock}) \longrightarrow$ Stake Amount With Lock
- $\mathcal{f}^{lock}(\mathbb{Acc}, t_{lock}) \longrightarrow$ Increase Lock;
- $\mathcal{f}^{unstake}( \mathbb{Acc}, Delta a)\longrightarrow$ Unstake Amount Unlocked;
- $\mathcal{f}^{accrue}(\mathbb{Acc}) \longrightarrow$ Accrue Multiplier Points.
The state can be expressed as the following state changes:
###### For every $T_{RATE}$
$$
mp_{\Sigma} = min(\mathcal{f}mp_\mathcal{A}(a_{bal},\Delta t) ,mp_\mathcal{M} - mp_\Sigma)
mp_{\Sigma} = min(\mathcal{f}mp_\mathcal{A}(a_{bal},\Delta t), mp_\mathcal{M} - mp_\Sigma)
$$
###### Increase in Balance and Lock
$$
\begin{aligned}
mp_{\Sigma} &= mp_{\Sigma} + mp_\mathcal{B}(\Delta a, t_{lock, \Delta} + t_{lock}) \\
&\quad + mp_\mathcal{B}(a_{bal}, t_{lock}) \\
&\quad + mp_\mathcal{I}(\Delta a)
mp_{\Sigma} &= mp_{\Sigma} + mp_\mathcal{B}(\Delta a, t_{lock, \Delta} + t_{lock}) \\
&\quad + mp_\mathcal{B}(a_{bal}, t_{lock}) \\
&\quad + mp_\mathcal{I}(\Delta a)
\end{aligned}
$$
@@ -204,13 +206,13 @@ $$
---
##### $\mathbb{Account}\rightarrow$ Account Storage Schema
##### $\mathbb{Acc}\rightarrow$ Account Storage Schema
Defined as following:
$$
\begin{gather}
\mathbb{Account} \\
\mathbb{Acc} \\
\overbrace{
\begin{align}
a_{bal} & : \text{balance}, \\
@@ -225,16 +227,30 @@ $$
---
##### $\mathbb{Acc} \cdot W \rightarrow$ Account Weight
The **account weight** for an individual account $j$ combines its staked balance and accumulated Multiplier Points. This
weight determines the proportion of rewards the account is entitled to.
$$
\mathbb{Acc} \cdot W = \mathbb{Acc} \cdot a_{\text{bal}} + \mathbb{Acc} \cdot mp_{\Sigma}
$$
Where:
- $\mathbb{Acc} \cdot a_{\text{bal}}$: Staked balance of account $j$.
- $\mathbb{Acc} \cdot mp_{\Sigma}$: Total Multiplier Points of account $j$.
##### $\mathbb{System}\rightarrow$ System Storage Schema
Defined as following:
$$
\begin{gather}
\mathbb{System} \\
\mathbb{Sys} \\
\overbrace{
\begin{align}
\mathbb{Account}\mathrm{[]} & : \text{accounts}, \\
\mathbb{Acc}\mathrm{[]} & : \text{accounts}, \\
a_{bal} & : \text{total staked}, \\
mp_\Sigma & : \text{MP supply}, \\
mp_\mathcal{M} & : \text{MP supply max}
@@ -245,6 +261,40 @@ $$
---
##### $\mathbb{Sys} \cdot W \rightarrow$ Total Weight
The **total weight** of the system is the aggregate of all staked tokens and Multiplier Points (MP) across all accounts.
It serves as the denominator in reward distribution calculations.
$$
\mathbb{Sys} \cdot W = \mathbb{Sys} \cdot a_{\text{bal}} + \mathbb{Sys} \cdot mp_{\Sigma}
$$
Where:
- $\mathbb{Sys} \cdot a_{\text{bal}}$: Total tokens staked in the system.
- $\mathbb{Sys} \cdot mp_{\Sigma}$: Total Multiplier Points accumulated in the system.
---
##### $R_i \rightarrow$ Cumulative Reward Index
The **reward index** represents the cumulative rewards distributed per unit of total weight (staked balance plus
Multiplier Points) in the system. It is a crucial component for calculating individual rewards.
$$
R_i = R_i + \left( \frac{R_{\text{new}} \times SCALE_{FACTOR}}{\mathbb{Sys} \cdot W} \right)
$$
Where:
- $R_{\text{new}}$: The amount of new rewards added to the system.
- $\mathbb{Sys} \cdot W$: The total weight in the system, calculated as the sum of all staked balances and total
Multiplier Points.
- $SCALE_{FACTOR}$: Scaling factor to maintain precision.
---
### Pure Mathematical Functions
<!-- prettier-ignore -->
@@ -253,8 +303,8 @@ $$
#### $\mathcal{f}{mp_\mathcal{I}}(\Delta a) \longrightarrow$ Initial Multiplier Points
Calculates the initial multiplier points (**MPs**) based on the balance change $\Delta a$. The result is equal to the
amount of balance added.
Calculates the initial multiplier points based on the balance change $\Delta a$. The result is equal to the amount of
balance added.
$$
\boxed{
@@ -272,8 +322,8 @@ Where
#### $\mathcal{f}{mp_\mathcal{A}}(a_{bal}, \Delta t) \longrightarrow$ Accrue Multiplier Points
Calculates the accrued multiplier points (**MPs**) over a time period **$\Delta t$**, based on the account balance
**$a_{bal}$** and the annual percentage yield $\mathtt{APY}$.
Calculates the accrued multiplier points over a time period **$\Delta t$**, based on the account balance **$a_{bal}$**
and the annual percentage yield $\mathtt{APY}$.
$$
\boxed{
@@ -297,8 +347,9 @@ Where
#### $\mathcal{f}{mp_\mathcal{B}}(\Delta a, t_{lock}) \longrightarrow$ Bonus Multiplier Points
Calculates the bonus multiplier points (**MPs**) earned when a balance **$\Delta a$** is locked for a specified duration
**$t_{lock}$**. It is equivalent to the [[#$ mathcal{f}{mp_ mathcal{A}}(a_{bal}, Delta t) longrightarrow$ Accrue Multiplier Points]] but specifically applied in the context of a locked balance, using [[#$ Delta t rightarrow$ Time Difference of Last Accrual|$\Delta t$]] as [[#$t_{lock} rightarrow$ Time Lock Duration|$t_{lock}$]].
Calculates the bonus multiplier points earned when a balance **$\Delta a$** is locked for a specified duration
$t_{lock}$. It is equivalent to the $\mathcal{f}{mp_\mathcal{A}}(a_{bal}, \Delta t) \longrightarrow$ Accrue Multiplier
Points but specifically applied in the context of a locked balance, using $\Delta t$ as $t_{lock}$.
$$
\begin{aligned}
@@ -324,9 +375,9 @@ Where:
#### $\mathcal{f}{mp_\mathcal{R}}(mp, a_{bal}, \Delta a) \longrightarrow$ Reduce Multiplier Points
Calculates the reduction in multiplier points (**MPs**) when a portion of the balance **$\Delta a$** is removed from the
total balance **$a_{bal}$**. The reduction is proportional to the ratio of the removed balance to the total balance,
applied to the current multiplier points **$mp$**.
Calculates the reduction in multiplier points when a portion of the balance **$\Delta a$** is removed from the total
balance **$a_{bal}$**. The reduction is proportional to the ratio of the removed balance to the total balance, applied
to the current multiplier points **$mp$**.
$$
\boxed{
@@ -346,11 +397,11 @@ Where:
### State Functions
These function definitions represent methods that modify the state of both **$\mathbb{System}$** and
**$\mathbb{Account}$**. They perform various pure mathematical operations to implement the specified state changes,
affecting either the system as a whole and the individual account states.
These function definitions represent methods that modify the state of both **$\mathbb{System}$** and **$\mathbb{Acc}$**.
They perform various pure mathematical operations to implement the specified state changes, affecting either the system
as a whole and the individual account states.
#### $\mathcal{f}^{stake}(\mathbb{Account},\Delta a, t_{lock}) \longrightarrow$ Stake Amount With Lock
#### $\mathcal{f}^{stake}(\mathbb{Acc},\Delta a, t_{lock}) \longrightarrow$ Stake Amount With Lock
_Purpose:_ Allows a user to stake an amount $\Delta a$ with an optional lock duration $t_{lock}$.
@@ -385,19 +436,21 @@ flowchart LR
###### Accrue Existing Multiplier Points (MPs)
Call the [[#$ mathcal{f} {accrue}( mathbb{Account}) longrightarrow$ Accrue Multiplier Points]] function to update MPs and last accrual time.
Call the $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points function to update MPs and
last accrual time.
###### Calculate the New Remaining Lock Period ($\Delta t_{lock}$)
$$
\Delta t_{lock} = max(\mathbb{Account} \cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}
\Delta t_{lock} = max(\mathbb{Acc} \cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}
$$
###### Verify Constraints
Ensure new balance ($a_{bal}$ + $\Delta a$) meets the minimum amount ($A_{MIN}$):
$$
\mathbb{Account} \cdot a_{bal} + \Delta a > A_{MIN}
\mathbb{Acc} \cdot a_{bal} + \Delta a > A_{MIN}
$$
Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within Allowed Limits
@@ -406,7 +459,6 @@ $$
\Delta t_{lock} = 0 \lor T_{MIN} \le \Delta t_{lock} \le T_{MAX}
$$
###### Calculate Increased Bonus MPs
For the new amount ($\Delta a$) with the New Remaining Lock Period ($\Delta t_{lock}$):
@@ -415,10 +467,10 @@ $$
\Delta \hat{mp}^\mathcal{B} = \mathcal{f}mp_\mathcal{B}(\Delta a, \Delta t_{lock})
$$
For extending the lock ($t_{lock}$) on the existing balance ($\mathbb{Account} \cdot a_{bal}$):
For extending the lock ($t_{lock}$) on the existing balance ($\mathbb{Acc} \cdot a_{bal}$):
$$
\Delta \hat{mp}^\mathcal{B} = \Delta \hat{mp}^\mathcal{B} + \mathcal{f}mp_\mathcal{B}(\mathbb{Account} \cdot a_{bal}, t_{lock})
\Delta \hat{mp}^\mathcal{B} = \Delta \hat{mp}^\mathcal{B} + \mathcal{f}mp_\mathcal{B}(\mathbb{Acc} \cdot a_{bal}, t_{lock})
$$
###### Calculate Increased Maximum MPs ($\Delta mp_\mathcal{M}$)
@@ -433,14 +485,13 @@ $$
\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}^\mathcal{B}
$$
###### Verify Constraints
Ensure the New Maximum MPs ($\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}$) is within the Absolute
Maximum MPs:
Ensure the New Maximum MPs ($\mathbb{Acc} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}$) is within the Absolute Maximum
MPs:
$$
\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} \le \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100}
\mathbb{Acc} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} \le \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100}
$$
###### Update account State
@@ -448,25 +499,25 @@ $$
Maximum MPs:
$$
\mathbb{Account} \cdot mp_\mathcal{M} = \mathbb{Account}\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}
\mathbb{Acc} \cdot mp_\mathcal{M} = \mathbb{Acc}\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}
$$
Total MPs:
$$
\mathbb{Account} \cdot mp_\Sigma = \mathbb{Account} \cdot mp_\Sigma + \Delta mp_\Sigma
\mathbb{Acc} \cdot mp_\Sigma = \mathbb{Acc} \cdot mp_\Sigma + \Delta mp_\Sigma
$$
Balance:
$$
\mathbb{Account} \cdot a_{bal} = \mathbb{Account} \cdot a_{bal} + \Delta a
\mathbb{Acc} \cdot a_{bal} = \mathbb{Acc} \cdot a_{bal} + \Delta a
$$
Lock end time:
$$
\mathbb{Account} \cdot t_{lock,end} = max(\mathbb{Account} \cdot t_{lock,end}, t_{now}) + t_{lock}
\mathbb{Acc} \cdot t_{lock,end} = max(\mathbb{Acc} \cdot t_{lock,end}, t_{now}) + t_{lock}
$$
###### Update System State
@@ -474,30 +525,33 @@ $$
Maximum MPs:
$$
\mathbb{System} \cdot mp_\mathcal{M} = \mathbb{System} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}
\mathbb{Sys} \cdot mp_\mathcal{M} = \mathbb{Sys} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}
$$
Total MPs:
$$
\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma + \Delta mp_\Sigma
\mathbb{Sys} \cdot mp_\Sigma = \mathbb{Sys} \cdot mp_\Sigma + \Delta mp_\Sigma
$$
Total staked amount:
$$
\mathbb{System} \cdot a_{bal} = \mathbb{System} \cdot a_{bal} + \Delta a
\mathbb{Sys} \cdot a_{bal} = \mathbb{Sys} \cdot a_{bal} + \Delta a
$$
---
#### $\mathcal{f}^{lock}(\mathbb{Account}, t_{lock}) \longrightarrow$ Increase Lock
#### $\mathcal{f}^{lock}(\mathbb{Acc}, t_{lock}) \longrightarrow$ Increase Lock
<!-- prettier-ignore -->
> [!NOTE]
> Equivalent to calling stake function with amount 0.
> Equivalent to:
> ```math
> \mathcal{f}_{stake}(\mathbb{Acc},0, t_{lock})
> ```
_Purpose:_ Allows a user to lock the $\mathbb{Account} \cdot a_{bal}$ with a lock duration $t_{lock}$.
_Purpose:_ Allows a user to lock the $\mathbb{Acc} \cdot a_{bal}$ with a lock duration $t_{lock}$.
```mermaid
---
@@ -520,12 +574,13 @@ flowchart LR
###### Accrue Existing Multiplier Points (MPs)
Call the [[#$ mathcal{f} {accrue}( mathbb{Account}) longrightarrow$ Accrue Multiplier Points]] function to update MPs and last accrual time.
Call the $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points function to update MPs and
last accrual time.
###### Calculate the New Remaining Lock Period ($\Delta t_{lock}$)
$$
\Delta t_{lock} = max(\mathbb{Account} \cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}
\Delta t_{lock} = max(\mathbb{Acc} \cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}
$$
###### Verify Constraints
@@ -539,16 +594,16 @@ $$
###### Calculate Bonus MPs for the Increased Lock Period
$$
\Delta \hat{mp}^\mathcal{B} = mp_\mathcal{B}(\mathbb{Account} \cdot a_{bal}, t_{lock})
\Delta \hat{mp}^\mathcal{B} = mp_\mathcal{B}(\mathbb{Acc} \cdot a_{bal}, t_{lock})
$$
###### Verify Constraints
Ensure the New Maximum MPs ($\mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B}$) is within the
Absolute Maximum MPs:
Ensure the New Maximum MPs ($\mathbb{Acc} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B}$) is within the Absolute
Maximum MPs:
$$
\mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B} \le \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100}
\mathbb{Acc} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B} \le \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100}
$$
###### Update account State
@@ -556,19 +611,19 @@ $$
Maximum MPs:
$$
\mathbb{Account} \cdot mp_\mathcal{M} = \mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B}
\mathbb{Acc} \cdot mp_\mathcal{M} = \mathbb{Acc} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B}
$$
Total MPs:
$$
\mathbb{Account} \cdot mp_\Sigma = \mathbb{Account} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{B}
\mathbb{Acc} \cdot mp_\Sigma = \mathbb{Acc} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{B}
$$
Lock end time:
$$
\mathbb{Account} \cdot t_{lock,end} = max(\mathbb{Account} \cdot t_{lock,end}, t_{now}) + t_{lock}
\mathbb{Acc} \cdot t_{lock,end} = max(\mathbb{Acc} \cdot t_{lock,end}, t_{now}) + t_{lock}
$$
###### Update System State
@@ -576,18 +631,18 @@ $$
Maximum MPs:
$$
\mathbb{System} \cdot mp_\mathcal{M} = \mathbb{System} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{B}
\mathbb{Sys} \cdot mp_\mathcal{M} = \mathbb{Sys} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{B}
$$
Total MPs:
$$
\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma + \Delta mp_\mathcal{B}
\mathbb{Sys} \cdot mp_\Sigma = \mathbb{Sys} \cdot mp_\Sigma + \Delta mp_\mathcal{B}
$$
---
#### $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a) \longrightarrow$ Unstake Amount Unlocked
#### $\mathcal{f}^{unstake}(\mathbb{Acc}, \Delta a) \longrightarrow$ Unstake Amount Unlocked
Purpose: Allows a user to unstake an amount $\Delta a$.
@@ -612,26 +667,27 @@ flowchart LR
###### Accrue Existing Multiplier Points (MPs)
Call the [[#$ mathcal{f} {accrue}( mathbb{Account}) longrightarrow$ Accrue Multiplier Points]] function to update MPs and last accrual time.
Call the $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points function to update MPs and
last accrual time.
###### Verify Constraints
Ensure the account is not locked:
$$
\mathbb{Account} \cdot t_{lock,end} < t_{now}
\mathbb{Acc} \cdot t_{lock,end} < t_{now}
$$
Ensure that account have enough balance:
$$
\mathbb{Account} \cdot a_{bal} > \Delta a
\mathbb{Acc} \cdot a_{bal} > \Delta a
$$
Ensure that new balance ($\mathbb{Account} \cdot a_{bal} - \Delta a$) will be zero or more than minimum allowed:
Ensure that new balance ($\mathbb{Acc} \cdot a_{bal} - \Delta a$) will be zero or more than minimum allowed:
$$
\mathbb{Account} \cdot a_{bal} - \Delta a = 0 \lor \mathbb{Account} \cdot a_{bal} - \Delta a > A_{MIN}
\mathbb{Acc} \cdot a_{bal} - \Delta a = 0 \lor \mathbb{Acc} \cdot a_{bal} - \Delta a > A_{MIN}
$$
###### Calculate Reduced Amounts
@@ -639,13 +695,13 @@ $$
Maximum MPs:
$$
\Delta mp_\mathcal{M} =\mathcal{f}mp_\mathcal{R}(\mathbb{Account} \cdot mp_\mathcal{M}, \mathbb{Account} \cdot a_{bal}, \Delta a)
\Delta mp_\mathcal{M} =\mathcal{f}mp_\mathcal{R}(\mathbb{Acc} \cdot mp_\mathcal{M}, \mathbb{Acc} \cdot a_{bal}, \Delta a)
$$
Total MPs:
$$
\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{R}(\mathbb{Account} \cdot mp_\Sigma, \mathbb{Account} \cdot a_{bal}, \Delta a)
\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{R}(\mathbb{Acc} \cdot mp_\Sigma, \mathbb{Acc} \cdot a_{bal}, \Delta a)
$$
###### Update account State
@@ -653,19 +709,19 @@ $$
Maximum MPs:
$$
\mathbb{Account} \cdot mp_\mathcal{M} = \mathbb{Account} \cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}
\mathbb{Acc} \cdot mp_\mathcal{M} = \mathbb{Acc} \cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}
$$
Total MPs:
$$
\mathbb{Account} \cdot mp_\Sigma = \mathbb{Account} \cdot mp_\Sigma - \Delta mp_\Sigma
\mathbb{Acc} \cdot mp_\Sigma = \mathbb{Acc} \cdot mp_\Sigma - \Delta mp_\Sigma
$$
Balance:
$$
\mathbb{Account} \cdot a_{bal} = \mathbb{Account} \cdot a_{bal} - \Delta a
\mathbb{Acc} \cdot a_{bal} = \mathbb{Acc} \cdot a_{bal} - \Delta a
$$
###### Update System State
@@ -673,24 +729,24 @@ $$
Maximum MPs:
$$
\mathbb{System} \cdot mp_\mathcal{M} = \mathbb{System} \cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}
\mathbb{Sys} \cdot mp_\mathcal{M} = \mathbb{Sys} \cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}
$$
Total MPs:
$$
\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma - \Delta mp_\Sigma
\mathbb{Sys} \cdot mp_\Sigma = \mathbb{Sys} \cdot mp_\Sigma - \Delta mp_\Sigma
$$
Total staked amount:
$$
\mathbb{System} \cdot a_{bal} = \mathbb{System} \cdot a_{bal} - \Delta a
\mathbb{Sys} \cdot a_{bal} = \mathbb{Sys} \cdot a_{bal} - \Delta a
$$
---
#### $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points
#### $\mathcal{f}^{accrue}(\mathbb{Acc}) \longrightarrow$ Accrue Multiplier Points
Purpose: Accrue multiplier points (MPs) for the account based on the elapsed time since the last accrual.
@@ -719,7 +775,7 @@ flowchart LR
###### Calculate the time Period since Last Accrual
$$
\Delta t = t_{now} - \mathbb{Account} \cdot t_{last}
\Delta t = t_{now} - \mathbb{Acc} \cdot t_{last}
$$
###### Verify Constraints
@@ -733,7 +789,7 @@ $$
###### Calculate Accrued MP for the Accrual Period
$$
\Delta \hat{mp}^\mathcal{A} = min(\mathcal{f}mp_\mathcal{A}(\mathbb{Account} \cdot a_{bal},\Delta t) ,\mathbb{Account} \cdot mp_\mathcal{M} - \mathbb{Account} \cdot mp_\Sigma)
\Delta \hat{mp}^\mathcal{A} = min(\mathcal{f}mp_\mathcal{A}(\mathbb{Acc} \cdot a_{bal},\Delta t) ,\mathbb{Acc} \cdot mp_\mathcal{M} - \mathbb{Acc} \cdot mp_\Sigma)
$$
###### Update account State
@@ -741,13 +797,13 @@ $$
Total MPs:
$$
\mathbb{Account} \cdot mp_\Sigma = \mathbb{Account} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{A}
\mathbb{Acc} \cdot mp_\Sigma = \mathbb{Acc} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{A}
$$
Last accrual time:
$$
\mathbb{Account} \cdot t_{last} = t_{now}
\mathbb{Acc} \cdot t_{last} = t_{now}
$$
###### Update System State
@@ -755,11 +811,144 @@ $$
Total MPs:
$$
\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{A}
\mathbb{Sys} \cdot mp_\Sigma = \mathbb{Sys} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{A}
$$
---
#### Reward Index Update
The **reward index** is updated whenever new rewards are added to the system. This update ensures that rewards are
accurately tracked and distributed based on the current total weight.
1. **Calculate New Rewards:**
$$
R_{\text{new}} = R_{\text{bal}} - R_{\text{accounted}}
$$
Where:
- $R_{\text{bal}}$: Current balance of reward tokens in the contract.
- $R_{\text{accounted}}$: Total rewards that have already been accounted for.
2. **Update Reward Index:**
$$
R_i = R_i + \left( \frac{R_\text{new} \times SCALE_{FACTOR}}{\mathbb{Sys} \cdot W} \right)
$$
3. **Account for Distributed Rewards:**
$$
R_\text{accounted} = R_\text{accounted} + R_\text{new}
$$
---
#### Reward Calculation for Accounts
Each account's rewards are calculated based on the difference between the current reward index and the account's last
recorded reward index. This ensures that rewards are distributed proportionally and accurately.
1. **Calculate Reward Index Difference:**
$$
\Delta \mathbb{Acc} \cdot R_i = \mathbb{Sys} \cdot R_i - \mathbb{Acc} \cdot R_i
$$
2. **Calculate Reward for Account $j$:**
$$
\text{reward}^j = \frac{\mathbb{Acc} \cdot W \times \Delta \mathbb{Acc} \cdot R_i}{SCALE_{FACTOR}}
$$
3. **Update Account Reward Index:**
$$
\mathbb{Acc} \cdot R_i = R_i
$$
---
#### Distribute Rewards
When distributing rewards to an account, ensure that the reward does not exceed the contract's available balance. Adjust
the accounted rewards accordingly to maintain consistency.
1. **Determine Transfer Amount:**
$$
\text{amount} = \min(\text{reward}^j, R_{\text{bal}})
$$
1. **Adjust Accounted Rewards:**
$$
R_{\text{accounted}} = R_{\text{accounted}} - \text{amount}
$$
3. **Transfer Reward Tokens:**
$$
\text{RewardToken.transfer}(j, \text{amount})
$$
#### Reward Calculation
At any given point, the **total reward** accumulated by an account $j$ is calculated as follows:
$$
\text{reward}^j = \frac{(\mathbb{Acc} \cdot a_{\text{bal}} + \mathbb{Acc} \cdot mp_{\Sigma}) \times (R_i - \mathbb{Acc} \cdot R_i)}{SCALE_{FACTOR}}
$$
This formula ensures that rewards are distributed proportionally based on both the staked tokens and the accrued
Multiplier Points, adjusted by the changes in the global reward index since the last reward calculation for the account.
---
#### $\mathcal{f}^{\text{updateRewardIndex}}(\mathbb{Sys}) \longrightarrow$ Update Reward Index
Calculates and updates the global reward index based on newly added rewards and the current total weight in the system.
$$
\boxed{
\begin{equation}
\mathcal{f}^{\text{updateRewardIndex}}(\mathbb{Sys}) = R_i + \left( \frac{R_{\text{new}} \times SCALE_{FACTOR}}{\mathbb{Sys} \cdot W} \right)
\end{equation}
}
$$
Where:
- $R_{\text{new}}$: Calculated as $R_{\text{bal}} - R_{\text{accounted}}$.
- $\mathbb{Sys} \cdot W$: Defined as $\mathbb{Sys} \cdot a_{\text{bal}} + \mathbb{Sys} \cdot mp_{\Sigma}$.
---
#### $\mathcal{f}^{\text{calculateReward}}(\mathbb{Acc} \cdot a_{\text{bal}}, \mathbb{Acc} \cdot mp_{\Sigma}, R_i, \mathbb{Acc} \cdot R_i) \longrightarrow$ Calculate Account Reward
Calculates the reward for an account $j$ based on its staked balance, Multiplier Points, and the change in the global
reward index.
$$
\boxed{
\begin{equation}
\mathcal{f}^{\text{calculateReward}}(\mathbb{Acc} \cdot a_{\text{bal}}, \mathbb{Acc} \cdot mp_{\Sigma}, R_i, \mathbb{Acc} \cdot R_i) = \frac{(\mathbb{Acc} \cdot a_{\text{bal}} + \mathbb{Acc} \cdot mp_{\Sigma}) \times (R_i - \mathbb{Acc} \cdot R_i)}{SCALE_{FACTOR}}
\end{equation}
}
$$
Where:
- $\mathbb{Acc} \cdot a_{\text{bal}}$: Staked balance of account $j$.
- $\mathbb{Acc} \cdot mp_{\Sigma}$: Total Multiplier Points of account $j$.
- $R_i$: Current cumulative reward index.
- $\mathbb{Acc} \cdot R_i$: Reward index at the last update for account $j$.
- $SCALE_{FACTOR}$: Scaling factor to maintain precision.
---
### Support Functions
#### Maximum Total Multiplier Points
@@ -774,11 +963,11 @@ $$
}
$$
#### Maximum Accrued Multiplier Points
The maximum multiplier points that can be accrued over time for a determined amount of balance.
It's [[#$ mathcal{f}{mp_ mathcal{A}}(a_{bal}, Delta t) longrightarrow$ Accrue Multiplier Points]] using [[#$ Delta t rightarrow$ Time Difference of Last Accrual|$\Delta t$]] $= M_{MAX} \times T_{YEAR}$
The maximum multiplier points that can be accrued over time for a determined amount of balance.
It's $\mathcal{f}{mp_\mathcal{A}}(a_{bal}, Delta t) \longrightarrow$ Accrue Multiplier Points
using $\Delta t = M_{MAX} \times T_{YEAR}$
$$
\boxed{
@@ -787,9 +976,11 @@ $$
\end{equation}
}
$$
#### Maximum Absolute Multiplier Points
The absolute maximum multiplier points that some balance could have, which is the sum of the maximum lockup time bonus and the maximum accrued multiplier points.
The absolute maximum multiplier points that some balance could have, which is the sum of the maximum lockup time bonus
and the maximum accrued multiplier points.
$$
\boxed{
@@ -799,8 +990,8 @@ $$
}
$$
#### Retrieve Bonus Multiplier Points
Returns the Bonus Multiplier Points from the Maximum Multiplier Points and Balance.
$$
@@ -811,10 +1002,9 @@ $$
}
$$
#### Retrieve Accrued Multiplier Points
Returns the accrued multiplier points from Total Multiplier Points, Maximum Multiplier Points and Balance.
Returns the accrued multiplier points from Total Multiplier Points, Maximum Multiplier Points and Balance.
$$
\boxed{
@@ -825,38 +1015,43 @@ $$
$$
#### Time to Accrue Multiplier Points
Retrieves how much seconds to a certain $a_{bal}$ would reach a certain $mp$
$$
\boxed{
\begin{equation}
t_{rem}(a_{bal},mp_{target}) = \frac{mp_{target} \times 100 \times T_{YEAR}}{a_{bal} \times \mathtt{APY}}
t_{rem}(a_{bal},mp_ {target}) = \frac{mp_{target} \times 100 \times T_{YEAR}}{a_{bal} \times \mathtt{APY}}
\end{equation}
}
$$
#### Locked Time ($t_{lock}$)
<!-- prettier-ignore -->
> [!CAUTION]
> Use for reference only. If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, the result may be an approximation.
Estimates the time an account set as locked time.
Estimates the time an account set as locked time.
$$
\boxed{
\begin{equation}
\hat{\mathcal{f}}\tilde{t}_{lock}(mp_{\mathcal{M}}, a_{bal}) \approx \left\lceil \frac{(mp_{\mathcal{M}} - a_{bal}) \times 100 \times T_{YEAR}}{a_{bal} \times \mathtt{APY}}\right\rceil - T_{\text{MAX}}
\hat{\mathcal{f}}\tilde{t}_ {lock}(mp_{\mathcal{M}}, a_{bal}) \approx \left\lceil \frac{(mp_{\mathcal{M}} - a_{bal}) \times 100 \times T_{YEAR}}{a_{bal} \times \mathtt{APY}}\right\rceil - T_{\text{MAX}}
\end{equation}
}
$$
Where:
- $mp_{\mathcal{M}}$: Maximum multiplier points calculated the $a_{bal}$
- $a_{bal}$: Account balance used to calculate the $mp_{\mathcal{M}}$
#### Remaining Time Lock Available to Increase
<!-- prettier-ignore -->
> [!CAUTION]
> If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an
> approximation.
> [!CAUTION]
> Use for reference only. If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, the result may be an approximation.
Retrieves how much time lock can be increased for an account.

216
docs/ScalableRewardDistribution.md
View File

@@ -1,216 +0,0 @@
### Reward Distribution Formulas
<!-- prettier-ignore -->
> [!IMPORTANT]
> All formulas in this section are integral to understanding the reward distribution mechanism within the staking protocol. They ensure accurate and fair allocation of rewards based on staked balances and Multiplier Points (MP).
---
#### Definitions
##### $R_i \rightarrow$ Cumulative Reward Index
The **reward index** represents the cumulative rewards distributed per unit of total weight (staked balance plus Multiplier Points) in the system. It is a crucial component for calculating individual rewards.
$$
R_i = R_i + \left( \frac{R_{new} \times \text{SCALE\_FACTOR}}{W_\mathbb{System}} \right)
$$
Where:
- **$R_{new}$**: The amount of new rewards added to the system.
- **$W_\mathbb{System}$**: The total weight in the system, calculated as the sum of all staked balances and total Multiplier Points.
- **$\text{SCALE\_FACTOR}$**: Scaling factor to maintain precision.
---
##### $W_\mathbb{System} \rightarrow$ Total Weight
The **total weight** of the system is the aggregate of all staked tokens and Multiplier Points (MP) across all accounts. It serves as the denominator in reward distribution calculations.
$$
W_\mathbb{System} = \mathbb{System}\cdot a_{\text{bal}} + \mathbb{System}\cdot mp_{\Sigma}
$$
Where:
- **$\mathbb{System}\cdot a_{\text{bal}}$**: Total tokens staked in the system.
- **$\mathbb{System}\cdot mp_{\Sigma}$**: Total Multiplier Points accumulated in the system.
---
##### $\mathbb{Account}\cdot W \rightarrow$ Account Weight
The **account weight** for an individual account $j$ combines its staked balance and accumulated Multiplier Points. This weight determines the proportion of rewards the account is entitled to.
$$
\mathbb{Account}\cdot W = \mathbb{Account}\cdot a_{bal} + \mathbb{Account}\cdot mp_{\Sigma}
$$
Where:
- **$\mathbb{Account}\cdot a_{bal}$**: Staked balance of account $j$.
- **$\mathbb{Account}\cdot mp_{\Sigma}$**: Total Multiplier Points of account $j$.
---
#### Reward Index Update
The **reward index** is updated whenever new rewards are added to the system. This update ensures that rewards are accurately tracked and distributed based on the current total weight.
1. **Calculate New Rewards:**
$$
R_{new} = R_{bal} - R_{accounted}
$$
Where:
- **$R_{bal}$**: Current balance of reward tokens in the contract.
- **$R_{accounted}$**: Total rewards that have already been accounted for.
2. **Update Reward Index:**
$$
R_i = R_i + \left( \frac{R_{new} \times \text{SCALE\_FACTOR}}{W_\mathbb{System}} \right)
$$
3. **Account for Distributed Rewards:**
$$
R_{accounted} = R_{accounted} + R_{new}
$$
---
#### Reward Calculation for Accounts
Each account's rewards are calculated based on the difference between the current reward index and the account's last recorded reward index. This ensures that rewards are distributed proportionally and accurately.
1. **Calculate Reward Index Difference:**
$$
\Delta \mathbb{Account}\cdot R_i = \mathbb{System}\cdot R_i - \mathbb{Account}\cdot R_i
$$
2. **Calculate Reward for Account $j$:**
$$
\text{reward}_j = \frac{\mathbb{Account}\cdot W \times \Delta \mathbb{Account}\cdot R_i}{\text{SCALE\_FACTOR}}
$$
3. **Update Account Reward Index:**
$$
\mathbb{Account}\cdot R_i = R_i
$$
---
#### Distribute Rewards
When distributing rewards to an account, ensure that the reward does not exceed the contract's available balance. Adjust the accounted rewards accordingly to maintain consistency.
1. **Determine Transfer Amount:**
$$
\text{amount} = \min(\text{reward}_j, R_{bal})
$$
2. **Adjust Accounted Rewards:**
$$
R_{accounted} = R_{accounted} - \text{amount}
$$
3. **Transfer Reward Tokens:**
$$
\text{REWARD\_TOKEN.transfer}(j, \text{amount})
$$
---
#### Multiplier Points (MP) Accrual
Multiplier Points (MP) enhance the staking power of participants, allowing them to earn greater rewards based on their staked amounts and lockup durations.
##### Accrue Multiplier Points for an Account
Multiplier Points accrue over time based on the staked balance and the predefined annual MP rate.
$$
\Delta mp_j = \frac{\Delta t \times \mathbb{Account}\cdot a_{bal} \times \text{MP\_RATE\_PER\_YEAR}}{365 \times \text{T\_DAY} \times \text{SCALE\_FACTOR}}
$$
Where:
- **$\Delta t$**: Time elapsed since the last MP accrual.
- **$\mathbb{Account}\cdot a_{bal}$**: Staked balance of account $j$.
- **$\text{MP\_RATE\_PER\_YEAR}$**: Annual rate at which MP accrue.
Accrued MP is capped by the account's maximum MP:
$$
\Delta mp_j = \min\left( \Delta mp_j, mp_{\mathcal{M},j} - \mathbb{Account}\cdot mp_{\Sigma} \right)
$$
Update the account's MP:
$$
\mathbb{Account}\cdot mp_{\Sigma} = \mathbb{Account}\cdot mp_{\Sigma} + \Delta mp_j
$$
---
#### Summary of Reward Calculation
At any given point, the **total reward** accumulated by an account $j$ is calculated as follows:
$$
\text{reward}_j = \frac{(\mathbb{Account}\cdot a_{bal} + \mathbb{Account}\cdot mp_{\Sigma}) \times (R_i - \mathbb{Account}\cdot R_i)}{\text{SCALE\_FACTOR}}
$$
This formula ensures that rewards are distributed proportionally based on both the staked tokens and the accrued Multiplier Points, adjusted by the changes in the global reward index since the last reward calculation for the account.
---
#### $\mathcal{f}^{\text{updateRewardIndex}}(\mathbb{System}) \longrightarrow$ Update Reward Index
Calculates and updates the global reward index based on newly added rewards and the current total weight in the system.
$$
\boxed{
\begin{equation}
\mathcal{f}^{\text{updateRewardIndex}}(\mathbb{System}) = R_i + \left( \frac{R_{new} \times \text{SCALE\_FACTOR}}{W_\mathbb{System}} \right)
\end{equation}
}
$$
Where:
- **$R_{new}$**: Calculated as $R_{bal} - R_{accounted}$.
- **$W_\mathbb{System}$**: Defined as $\mathbb{System}\cdot a_{\text{bal}} + \mathbb{System}\cdot mp_{\Sigma}$.
---
#### $\mathcal{f}^{\text{calculateReward}}(\mathbb{Account}\cdot a_{bal}, \mathbb{Account}\cdot mp_{\Sigma}, R_i, \mathbb{Account}\cdot R_i) \longrightarrow$ Calculate Account Reward
Calculates the reward for an account $j$ based on its staked balance, Multiplier Points, and the change in the global reward index.
$$
\boxed{
\begin{equation}
\mathcal{f}^{\text{calculateReward}}(\mathbb{Account}\cdot a_{bal}, \mathbb{Account}\cdot mp_{\Sigma}, R_i, \mathbb{Account}\cdot R_i) = \frac{(\mathbb{Account}\cdot a_{bal} + \mathbb{Account}\cdot mp_{\Sigma}) \times (R_i - \mathbb{Account}\cdot R_i)}{\text{SCALE\_FACTOR}}
\end{equation}
}
$$
Where:
- **$\mathbb{Account}\cdot a_{bal}$**: Staked balance of account $j$.
- **$\mathbb{Account}\cdot mp_{\Sigma}$**: Total Multiplier Points of account $j$.
- **$R_i$**: Current cumulative reward index.
- **$\mathbb{Account}\cdot R_i$**: Reward index at the last update for account $j$.
- **$\text{SCALE\_FACTOR}$**: Scaling factor to maintain precision.