From 45765aea64911efb9beec0e71f1f6f39a273d4e0 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Sat, 19 Oct 2024 22:07:09 -0300 Subject: [PATCH 01/23] chore(docs): mathspec v1 --- docs/MathSpec.md | 263 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 docs/MathSpec.md diff --git a/docs/MathSpec.md b/docs/MathSpec.md new file mode 100644 index 0000000..c922e69 --- /dev/null +++ b/docs/MathSpec.md @@ -0,0 +1,263 @@ +# Mathematical Specification of Staking Protocol +> [!attention] All values in this document are expressed as unsigned integers. +## Constants +### Helper Constants +- $T_{DAY} = \pu{86400 \mathrm{s}}$ + Seconds in one day. +- $T_{YEAR} = \lfloor365.242190 \times T_{DAY}\rfloor = \pu{31556925 \mathrm{s}}$ + Seconds in one mean tropical year. +- $SCALE_{FACTOR} = \pu{1 \times 10^{18} \mathrm{(1)}}$ + Scaling factor to maintain precision in calculations (dimensionless). +### Multiplier Points +- $T_{RATE} = \pu{12 \mathrm{s}}$ + The accrue rate period of time over which multiplier points are calculated. +- $MP_{APY} = \pu{100\%}$ + Annual percentage yield for multiplier points. +- $M_{MAX} = \pu{4 \mathrm{(1)}}$ + Maximum multiplier allowed for $\hat{mp}_\mathcal{A}$ (dimensionless). +### Thresholds +- $A_{MIN} = \lceil\tfrac{T_{YEAR}}{(T_{RATE} \times \frac{MP_{APY}}{100})}\rceil = \pu{2629744 \mathrm{tokens}}$ + Minimal value to generate 1 multiplier point in the accrue rate period ($T_{RATE}$). + ($A_{MIN} \propto T_{RATE}$) +- $T_{MIN} = 90 \times T_{DAY} = \pu{7776000 \mathrm{s}}$ + Minimum lockup period, equivalent to 90 days. + - $T_{MAX_{YEARS}} = \pu{4 \mathrm{years}}$ + Maximum years of lockup period. +- $T_{MAX} = T_{MAX_{YEARS}} \times T_{YEAR} = \pu{126230400 \mathrm{s}}$ + Maximum lockup period in seconds. +## Variables +### System and User Parameters +- $\Delta a\rightarrow$ = Amount Difference + Difference in amount, can be either reduced or increased depending on context. +- $\Delta t\rightarrow$ Time Difference of last accrual. + The time difference defined as: + $$ + \Delta t = t_{now} - t_{last}, \quad \text{where} \; \Delta t > T_{RATE} + $$ +- $t_{lock}\rightarrow$ = Time Lock Duration + A user-defined duration for which $a_{bal}$ remains locked. +- $t_{now}\rightarrow$ = Time Now + The current timestamp seconds since the Unix epoch (January 1, 1970). +- $t_{lock, \Delta}\rightarrow$ = Time Lock Remaining Duration + Seconds $a_{bal}$ remains locked, expressed as: + $$ + \begin{aligned} + &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ \small\text{ where: }\normalsize\quad & t_{lock, \Delta} = 0\;\text{ or }\;T_{MIN} \le t_{lock, \Delta} \le T_{MAX}\end{aligned}$$ +### State Related +- $a_{bal}\rightarrow$ = Amount of Balance + Amount of tokens in balance, where $a_{bal} \ge A_{MIN}$. +- $t_{lock,end}\rightarrow$ = Time Lock End + Timestamp marking the end of the lock period, it state can be defined as: $$t_{lock,end} = \max(t_{now}, t_{lock,end}) + t_{lock}$$ The value of $t_{lock,end}$ can be updated only within the functions: + - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; + - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; +- $t_{last}\rightarrow$ Time of Accrual + Timestamp of the last accrued time, it state can be defined as:$$t_{last} = t_{now}$$The value of $t_{last}$ can is updated by all functions that change state: + - $f^{accrue}(\tiny\mathbb{Account}\normalsize, a_{bal},\Delta t)$, + - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; + - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; + - $\mathcal{f}^{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a)$; +- $mp_\mathcal{M}\rightarrow$ Maximum Multiplier Points + Maximum value that $mp_\Sigma$ can reach. + Relates as $mp_\mathcal{M} \propto a_{bal} \cdot (t_{lock} + M_{MAX})$. + Altered by functions that change the account state: + - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; + - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; + - $\mathcal{f}^{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a)$. + + It's state can be expressed as the following state changes: + 1. Increase in balance and lock: $$ + \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) + \end{aligned} + $$ + 2. Increase in balance only: $$ + \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) \end{aligned} + $$ + 3. Increase in lock only: $$ + \begin{aligned} mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{B}(a_{bal}, t_{lock}) \end{aligned} + $$ + 4. Decrease in balance: $$ + \begin{aligned} mp_\mathcal{M} &= mp_\mathcal{M} - mp_\mathcal{R}(mp_\mathcal{M}, a_{bal}, \Delta a) \end{aligned} + $$ +- $mp_{\Sigma}\rightarrow$ Total Multiplier Points + Altered by all functions that change state: + - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; + - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; + - $\mathcal{f}^{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a)$; + - $f^{accrue}(\tiny\mathbb{Account}\normalsize, a_{bal},\Delta t)$. + + The state can be expressed as the following state changes: + $$ + mp_{\Sigma} \longrightarrow mp_{\Sigma} \pm + \begin{cases} + \begin{aligned} + & min(mp_\mathcal{M} - mp_\Sigma, \\ + & \quad mp_\mathcal{A}(a_{bal},\, \Delta t)) + \end{aligned} & \text{for every} \; T_{RATE}, \\ + \begin{aligned} + & 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} & \Rightarrow a_{bal} \uparrow \land \; t_{lock,end} \uparrow, \\ + \begin{aligned} + & mp_\mathcal{B}(\Delta a, t_{lock, \Delta}) \\ + & \quad + mp_\mathcal{I}(\Delta a) + \end{aligned} & \Rightarrow a_{bal} \uparrow, \\ + mp_\mathcal{B}(a_{bal}, t_{lock}) & \Rightarrow t_{lock,end} \uparrow, \\ + -mp_\mathcal{R}(mp_{\Sigma}, a_{bal}, \Delta a) & \Rightarrow a_{bal} \downarrow \\ + \end{cases} + $$ +- $\small\mathbb{Account}\normalsize\rightarrow$ Account storage schema + Defined as following: + $$ + \small \mathbb{Account} \normalsize \coloneqq \left\{ + \begin{aligned} + a_{bal} & : \small\text{balance}, \\ \normalsize + t_{lock,end} & : \small\text{lock end}, \\ \normalsize + t_{last} & : \small\text{last accrual}, \\ \normalsize + mp_\Sigma & : \small\text{total MPs}, \\ \normalsize + mp_\mathcal{M} & : \small\text{maximum MPs} + \end{aligned} \right\} + $$ +- $\small\mathbb{System}\normalsize\rightarrow$ System storage schema + Defined as following: + $$ + \small \mathbb{System} \normalsize \coloneqq \left\{ + \begin{aligned} + \tiny\mathbb{Account}\mathrm{[\,]}\normalsize & : \small\text{accounts}, \\ \normalsize + a_{bal} & : \small\text{total staked}, \\ \normalsize + mp_\Sigma & : \small\text{MP supply}, \\ \normalsize + mp_\mathcal{M} & : \small\text{MP supply max} + + \end{aligned} \right\} + $$ +$\mathbb{Account} = \{ a_{bal}, t_{lock,end}, t_{last}, mp_\Sigma, mp_\mathcal{M} \}$$\Delta t_{lock} = \max(t_{lock,end}, t_{now}) - t_{now} \quad \text{where} \quad 0 \leq \Delta t_{lock} \leq T_{MAX} \quad \text{or} \quad \Delta t_{lock} = 0$ +$ +## Pure Mathematical Functions +>[!info] This function definitions represent direct mathematical input -> output methods, which don't change state. +### Definition: $\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. +$$ +\boxed{\begin{equation}\mathcal{f}{mp_\mathcal{I}}(\Delta a) = \Delta a\end{equation}} +$$ +Where +- **$\Delta a$**: Represents the change in balance. +--- +### Definition: $\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 $MP_{APY}$. +$$ +\boxed{ +\begin{equation} +\mathcal{f}mp_\mathcal{A}(a_{bal}, \Delta t) = \dfrac{a_{bal} \times \Delta t \times MP_{APY}}{100 \times T_{YEAR}} +\end{equation} +} +$$ +Where +- **$a_{bal}$**: Represents the current account balance. +- **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the same time units as the year (typically days or months). +- **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference **$\Delta t$**. +- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance grows over a year. +--- +### Definition: $\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 accrued multiplier points function $\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. +$$ +\begin{aligned} + &\;\mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock}) \\ + &\boxed{\begin{equation}\mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{100 \times T_{YEAR}}\end{equation}} +\end{aligned} +$$ +Where: +- **$\Delta a$**: Represents the amount of the balance that is locked. +- **$t_{lock}$**: The duration for which the balance **$\Delta a$** is locked, measured in units of seconds. +- **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a fraction of a full year. +- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate applied to the locked balance. +--- +### Definition: $\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$**. +$$ +\boxed{\begin{equation}\mathcal{f}{mp_\mathcal{R}}(mp, a_{bal}, \Delta a) = \dfrac{mp \times \Delta a}{ a_{bal}}\end{equation}} +$$ + Where: + - **$mp$**: Represents the current multiplier points. + - **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. + - **$\Delta a$**: The amount of balance being removed or deducted. +--- +## 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. +### Definition: $\mathcal{f}_{stake}(\tiny\mathbb{Account}\normalsize,\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}$. +#### Steps +1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): $$\Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}$$ +2. Verify Constraints: + - Ensure new balance ($a_{bal}$ + $\Delta a$) meets the minimum amount ($A_{MIN}$): $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a > A_{MIN}$$ + - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits ($T_{MIN}$ and $T_{MAX}$):$$\Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX}$$ +3. Accrue Existing Multiplier Points (MPs): + - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. +4. Calculate Increased Bonus MPs ($\Delta \hat{mp}_\mathcal{B}$) for the Increased Balance ($\Delta a$) and Increased Lock Period ($t_{lock}$): + - For the new amount ($\Delta a$) with the New Remaining Lock Period ($\Delta t_{lock}$): $$\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 ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal}$): $$\Delta \hat{mp}_\mathcal{B} = \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock})$$ +5. Calculate Increased Maximum MPs ($\Delta mp_\mathcal{M}$): $$\Delta mp_\mathcal{M} = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR})$$ +6. Calculate Increased Total MPs ($\Delta mp_\Sigma$): $$\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B}$$ +7. Update account state + - Update account maximum MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}$$ + - Update account total MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma$$ + - Update account balance: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a$$ + - Update account lock end time: $$\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock}$$ +8. Update system state + - Update system maximum MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}$$ + - Update system total MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma$$ + - Update system total staked amount: $$\tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} + \Delta a$$ +--- +### Definition: $\mathcal{f}_{lock}(\tiny\mathbb{Account}\normalsize, t_{lock}) \longrightarrow$ Increase Lock +> [!info] Equivalent to $\mathcal{f}_{stake}(\tiny\mathbb{Account}\normalsize,0, t_{lock})$ + +_Purpose:_ Allows a user to lock the $\tiny\mathbb{Account}\normalsize _\cdot a_{bal}$ with a lock duration $t_{lock}$. +#### Steps +1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): $$\Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}$$ +2. Verify Constraints: + - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits:$$\Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX}$$ +3. Accrue Existing Multiplier Points (MPs): + - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. +4. Calculate Bonus MPs for the Increased Lock Period: $$\Delta \hat{mp}_\mathcal{B} = mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock})$$ +5. Update account state: + - Update maximum MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} + \Delta \hat{mp}_\mathcal{B}$$ + - Update total MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{B}$$ + - Update lock end time: $$\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock}$$ +6. Update system state: + - Update system maximum MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{B}$$ + - Update system total MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\mathcal{B}$$ + +--- +### Definition: $\mathcal{f}_{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a) \longrightarrow$ Unstake Amount Unlocked +1. Verify constraints: + - Ensure the account is not locked: $$\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} < t_{now}$$ + - Ensure that account have enough balance: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} > \Delta a$$ + - Ensure that new balance ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a$) will be zero or more than minimum allowed: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a = 0\;\lor\; \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a > A_{MIN}$$ +2. Accrue Existing Multiplier Points (MPs): + - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. +3. Calculate reduced amounts: + - For maximum MPs: $$\Delta mp_\mathcal{M} =\mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M}, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a)$$ + - For total MPs: $$\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a)$$ +4. Update account state: + - Update maximum MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}$$ + - Update total MPs:$$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma$$ + - Update balance: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a$$ +5. Update system state: + - Update system maximum MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}$$ + - Update system total MPs:$$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma$$ + - Update system total staked amount:$$\tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} - \Delta a$$ +--- +### Definition: $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize) \longrightarrow$ Accrue Multiplier Points +1. Calculate the time period since last accrual:$$\Delta t = t_{now} - \tiny\mathbb{Account}\normalsize _\cdot t_{last}$$ +2. Verify constraints: + - Ensure the accrual period is greater than the minimum rate period:$$\Delta t > T_{RATE}$$ +4. Calculate accrued MP for the accrual period:$$\Delta \hat{mp}_\mathcal{A} = min(\mathcal{f}mp_\mathcal{A}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal},\Delta t) ,\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma)$$ +5. Update account state: + - Update total MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A}$$ + - Update last accrual time: $$\tiny\mathbb{Account}\normalsize _\cdot t_{last} = \tiny\mathbb{Account}\normalsize _\cdot t_{now}$$ +6. Update system state: + - Update system total MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A}$$ +--- From 0e025f0206e957e3d10d636df40613e0dbf994cc Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Sun, 20 Oct 2024 12:09:00 -0300 Subject: [PATCH 02/23] chore(MathSpec.md): small fix in constant values, try fixing formatting to github display it fine --- docs/MathSpec.md | 277 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 218 insertions(+), 59 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index c922e69..13cb716 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -23,7 +23,7 @@ Minimum lockup period, equivalent to 90 days. - $T_{MAX_{YEARS}} = \pu{4 \mathrm{years}}$ Maximum years of lockup period. -- $T_{MAX} = T_{MAX_{YEARS}} \times T_{YEAR} = \pu{126230400 \mathrm{s}}$ +- $T_{MAX} = T_{MAX_{YEARS}} \times T_{YEAR} = \pu{126227700 \mathrm{s}}$ Maximum lockup period in seconds. ## Variables ### System and User Parameters @@ -42,16 +42,25 @@ Seconds $a_{bal}$ remains locked, expressed as: $$ \begin{aligned} - &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ \small\text{ where: }\normalsize\quad & t_{lock, \Delta} = 0\;\text{ or }\;T_{MIN} \le t_{lock, \Delta} \le T_{MAX}\end{aligned}$$ + &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ \small\text{ where: }\normalsize\quad & t_{lock, \Delta} = 0\;\text{ or }\;T_{MIN} \le t_{lock, \Delta} \le T_{MAX}\end{aligned} + $$ ### State Related - $a_{bal}\rightarrow$ = Amount of Balance Amount of tokens in balance, where $a_{bal} \ge A_{MIN}$. - $t_{lock,end}\rightarrow$ = Time Lock End - Timestamp marking the end of the lock period, it state can be defined as: $$t_{lock,end} = \max(t_{now}, t_{lock,end}) + t_{lock}$$ The value of $t_{lock,end}$ can be updated only within the functions: + Timestamp marking the end of the lock period, it state can be defined as: + $$ + t_{lock,end} = \max(t_{now}, t_{lock,end}) + t_{lock} + $$ + The value of $t_{lock,end}$ can be updated only within the functions: - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; - $t_{last}\rightarrow$ Time of Accrual - Timestamp of the last accrued time, it state can be defined as:$$t_{last} = t_{now}$$The value of $t_{last}$ can is updated by all functions that change state: + Timestamp of the last accrued time, it state can be defined as: + $$ + t_{last} = t_{now} + $$ + The value of $t_{last}$ is updated by all functions that change state: - $f^{accrue}(\tiny\mathbb{Account}\normalsize, a_{bal},\Delta t)$, - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; @@ -65,7 +74,8 @@ - $\mathcal{f}^{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a)$. It's state can be expressed as the following state changes: - 1. Increase in balance and lock: $$ + 1. Increase in balance and lock: + $$ \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}) \\ @@ -73,15 +83,22 @@ &\quad + mp_\mathcal{I}(\Delta a) \end{aligned} $$ - 2. Increase in balance only: $$ - \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) \end{aligned} + 2. Increase in balance only: + $$ + \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) + \end{aligned} + $$ + 3. Increase in lock only: $$ - 3. Increase in lock only: $$ - \begin{aligned} mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{B}(a_{bal}, t_{lock}) \end{aligned} + mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{B}(a_{bal}, t_{lock}) + $$ + 4. Decrease in balance: + $$ + mp_\mathcal{M} &= mp_\mathcal{M} - mp_\mathcal{R}(mp_\mathcal{M}, a_{bal}, \Delta a) $$ - 4. Decrease in balance: $$ - \begin{aligned} mp_\mathcal{M} &= mp_\mathcal{M} - mp_\mathcal{R}(mp_\mathcal{M}, a_{bal}, \Delta a) \end{aligned} - $$ - $mp_{\Sigma}\rightarrow$ Total Multiplier Points Altered by all functions that change state: - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; @@ -134,25 +151,33 @@ \end{aligned} \right\} $$ -$\mathbb{Account} = \{ a_{bal}, t_{lock,end}, t_{last}, mp_\Sigma, mp_\mathcal{M} \}$$\Delta t_{lock} = \max(t_{lock,end}, t_{now}) - t_{now} \quad \text{where} \quad 0 \leq \Delta t_{lock} \leq T_{MAX} \quad \text{or} \quad \Delta t_{lock} = 0$ -$ + +--- + ## Pure Mathematical Functions >[!info] This function definitions represent direct mathematical input -> output methods, which don't change state. + ### Definition: $\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. $$ -\boxed{\begin{equation}\mathcal{f}{mp_\mathcal{I}}(\Delta a) = \Delta a\end{equation}} +\boxed{ + \begin{equation} + \mathcal{f}{mp_\mathcal{I}}(\Delta a) = \Delta a + \end{equation} +} $$ Where - **$\Delta a$**: Represents the change in balance. + --- + ### Definition: $\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 $MP_{APY}$. $$ \boxed{ -\begin{equation} -\mathcal{f}mp_\mathcal{A}(a_{bal}, \Delta t) = \dfrac{a_{bal} \times \Delta t \times MP_{APY}}{100 \times T_{YEAR}} -\end{equation} + \begin{equation} + \mathcal{f}mp_\mathcal{A}(a_{bal}, \Delta t) = \dfrac{a_{bal} \times \Delta t \times MP_{APY}}{100 \times T_{YEAR}} + \end{equation} } $$ Where @@ -160,13 +185,19 @@ Where - **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the same time units as the year (typically days or months). - **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference **$\Delta t$**. - **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance grows over a year. + --- + ### Definition: $\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 accrued multiplier points function $\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. $$ \begin{aligned} &\;\mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock}) \\ - &\boxed{\begin{equation}\mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{100 \times T_{YEAR}}\end{equation}} + &\boxed{ + \begin{equation} + \mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{100 \times T_{YEAR}} + \end{equation} + } \end{aligned} $$ Where: @@ -178,86 +209,214 @@ Where: ### Definition: $\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$**. $$ -\boxed{\begin{equation}\mathcal{f}{mp_\mathcal{R}}(mp, a_{bal}, \Delta a) = \dfrac{mp \times \Delta a}{ a_{bal}}\end{equation}} +\boxed{ + \begin{equation} + \mathcal{f}{mp_\mathcal{R}}(mp, a_{bal}, \Delta a) = \dfrac{mp \times \Delta a}{ a_{bal}} + \end{equation} +} $$ Where: - **$mp$**: Represents the current multiplier points. - **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. - **$\Delta a$**: The amount of balance being removed or deducted. + --- + ## 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. ### Definition: $\mathcal{f}_{stake}(\tiny\mathbb{Account}\normalsize,\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}$. #### Steps -1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): $$\Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}$$ +1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): + $$ + \Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now} + $$ 2. Verify Constraints: - - Ensure new balance ($a_{bal}$ + $\Delta a$) meets the minimum amount ($A_{MIN}$): $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a > A_{MIN}$$ - - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits ($T_{MIN}$ and $T_{MAX}$):$$\Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX}$$ + - Ensure new balance ($a_{bal}$ + $\Delta a$) meets the minimum amount ($A_{MIN}$): + $$ + \tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a > A_{MIN} + $$ + - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits ($T_{MIN}$ and $T_{MAX}$): + $$ + \Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX} + $$ 3. Accrue Existing Multiplier Points (MPs): - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. 4. Calculate Increased Bonus MPs ($\Delta \hat{mp}_\mathcal{B}$) for the Increased Balance ($\Delta a$) and Increased Lock Period ($t_{lock}$): - - For the new amount ($\Delta a$) with the New Remaining Lock Period ($\Delta t_{lock}$): $$\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 ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal}$): $$\Delta \hat{mp}_\mathcal{B} = \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock})$$ -5. Calculate Increased Maximum MPs ($\Delta mp_\mathcal{M}$): $$\Delta mp_\mathcal{M} = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR})$$ -6. Calculate Increased Total MPs ($\Delta mp_\Sigma$): $$\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B}$$ + - For the new amount ($\Delta a$) with the New Remaining Lock Period ($\Delta t_{lock}$): + $$ + \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 ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal}$): + $$ + \Delta \hat{mp}_\mathcal{B} = \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock}) + $$ +5. Calculate Increased Maximum MPs ($\Delta mp_\mathcal{M}$): + $$ + \Delta mp_\mathcal{M} = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) + $$ +6. Calculate Increased Total MPs ($\Delta mp_\Sigma$): + $$ + \Delta mp_\Sigma = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B} + $$ 7. Update account state - - Update account maximum MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}$$ - - Update account total MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma$$ - - Update account balance: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a$$ - - Update account lock end time: $$\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock}$$ + - Update account maximum MPs: + $$ + \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} + $$ + - Update account total MPs: + $$ + \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma + $$ + - Update account balance: + $$ + \tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a + $$ + - Update account lock end time: + $$ + \tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} + $$ 8. Update system state - - Update system maximum MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M}$$ - - Update system total MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma$$ - - Update system total staked amount: $$\tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} + \Delta a$$ + - Update system maximum MPs: + $$ + \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} + $$ + - Update system total MPs: + $$ + \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma + $$ + - Update system total staked amount: + $$ + \tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} + \Delta a + $$ + --- + ### Definition: $\mathcal{f}_{lock}(\tiny\mathbb{Account}\normalsize, t_{lock}) \longrightarrow$ Increase Lock > [!info] Equivalent to $\mathcal{f}_{stake}(\tiny\mathbb{Account}\normalsize,0, t_{lock})$ _Purpose:_ Allows a user to lock the $\tiny\mathbb{Account}\normalsize _\cdot a_{bal}$ with a lock duration $t_{lock}$. #### Steps -1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): $$\Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now}$$ +1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): + $$ + \Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now} + $$ 2. Verify Constraints: - - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits:$$\Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX}$$ + - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits: + $$ + \Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX} + $$ 3. Accrue Existing Multiplier Points (MPs): - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. -4. Calculate Bonus MPs for the Increased Lock Period: $$\Delta \hat{mp}_\mathcal{B} = mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock})$$ +4. Calculate Bonus MPs for the Increased Lock Period: + $$ + \Delta \hat{mp}_\mathcal{B} = mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock}) + $$ 5. Update account state: - - Update maximum MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} + \Delta \hat{mp}_\mathcal{B}$$ - - Update total MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{B}$$ - - Update lock end time: $$\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock}$$ + - Update maximum MPs: + $$ + \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} + \Delta \hat{mp}_\mathcal{B} + $$ + - Update total MPs: + $$ + \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{B} + $$ + - Update lock end time: + $$ + \tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} + $$ 6. Update system state: - - Update system maximum MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{B}$$ - - Update system total MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\mathcal{B}$$ + - Update system maximum MPs: + $$ + \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{B} + $$ + - Update system total MPs: + $$ + \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\mathcal{B} + $$ --- + ### Definition: $\mathcal{f}_{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a) \longrightarrow$ Unstake Amount Unlocked 1. Verify constraints: - - Ensure the account is not locked: $$\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} < t_{now}$$ - - Ensure that account have enough balance: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} > \Delta a$$ - - Ensure that new balance ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a$) will be zero or more than minimum allowed: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a = 0\;\lor\; \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a > A_{MIN}$$ + - Ensure the account is not locked: + $$ + \tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} < t_{now} + $$ + - Ensure that account have enough balance: + $$ + \tiny\mathbb{Account}\normalsize _\cdot a_{bal} > \Delta a + $$ + - Ensure that new balance ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a$) will be zero or more than minimum allowed: + $$ + \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a = 0\;\lor\; \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a > A_{MIN} + $$ 2. Accrue Existing Multiplier Points (MPs): - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. 3. Calculate reduced amounts: - - For maximum MPs: $$\Delta mp_\mathcal{M} =\mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M}, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a)$$ - - For total MPs: $$\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a)$$ + - For maximum MPs: + $$ + \Delta mp_\mathcal{M} =\mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M}, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a) + $$ + - For total MPs: + $$ + \Delta mp_\Sigma = \mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a) + $$ 4. Update account state: - - Update maximum MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}$$ - - Update total MPs:$$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma$$ - - Update balance: $$\tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a$$ + - Update maximum MPs: + $$ + \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M} + $$ + - Update total MPs: + $$ + \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma + $$ + - Update balance: + $$ + \tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a + $$ 5. Update system state: - - Update system maximum MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M}$$ - - Update system total MPs:$$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma$$ - - Update system total staked amount:$$\tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} - \Delta a$$ + - Update system maximum MPs: + $$ + \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M} + $$ + - Update system total MPs: + $$ + \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma + $$ + - Update system total staked amount: + $$ + \tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} - \Delta a + $$ + --- + ### Definition: $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize) \longrightarrow$ Accrue Multiplier Points -1. Calculate the time period since last accrual:$$\Delta t = t_{now} - \tiny\mathbb{Account}\normalsize _\cdot t_{last}$$ +1. Calculate the time period since last accrual: + $$ + \Delta t = t_{now} - \tiny\mathbb{Account}\normalsize _\cdot t_{last} + $$ 2. Verify constraints: - - Ensure the accrual period is greater than the minimum rate period:$$\Delta t > T_{RATE}$$ -4. Calculate accrued MP for the accrual period:$$\Delta \hat{mp}_\mathcal{A} = min(\mathcal{f}mp_\mathcal{A}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal},\Delta t) ,\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma)$$ + - Ensure the accrual period is greater than the minimum rate period: + $$ + \Delta t > T_{RATE} + $$ +4. Calculate accrued MP for the accrual period: + $$ + \Delta \hat{mp}_\mathcal{A} = min(\mathcal{f}mp_\mathcal{A}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal},\Delta t) ,\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma) + $$ 5. Update account state: - - Update total MPs: $$\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A}$$ - - Update last accrual time: $$\tiny\mathbb{Account}\normalsize _\cdot t_{last} = \tiny\mathbb{Account}\normalsize _\cdot t_{now}$$ + - Update total MPs: + $$ + \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A} + $$ + - Update last accrual time: + $$ + \tiny\mathbb{Account}\normalsize _\cdot t_{last} = \tiny\mathbb{Account}\normalsize _\cdot t_{now} + $$ 6. Update system state: - - Update system total MPs: $$\tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A}$$ + - Update system total MPs: + $$ + \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A} + $$ --- From 7d197910588c55f2da1439ccb75bbdc5d9c1bf0b Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Sun, 20 Oct 2024 15:43:43 -0300 Subject: [PATCH 03/23] chore(MathSpec.md) fix formatting --- docs/MathSpec.md | 901 ++++++++++++++++++++++++++++------------------- 1 file changed, 541 insertions(+), 360 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 13cb716..d76a41b 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -1,164 +1,212 @@ -# Mathematical Specification of Staking Protocol +## Mathematical Specification of Staking Protocol + > [!attention] All values in this document are expressed as unsigned integers. -## Constants -### Helper Constants -- $T_{DAY} = \pu{86400 \mathrm{s}}$ - Seconds in one day. -- $T_{YEAR} = \lfloor365.242190 \times T_{DAY}\rfloor = \pu{31556925 \mathrm{s}}$ - Seconds in one mean tropical year. -- $SCALE_{FACTOR} = \pu{1 \times 10^{18} \mathrm{(1)}}$ - Scaling factor to maintain precision in calculations (dimensionless). -### Multiplier Points -- $T_{RATE} = \pu{12 \mathrm{s}}$ - The accrue rate period of time over which multiplier points are calculated. -- $MP_{APY} = \pu{100\%}$ - Annual percentage yield for multiplier points. -- $M_{MAX} = \pu{4 \mathrm{(1)}}$ - Maximum multiplier allowed for $\hat{mp}_\mathcal{A}$ (dimensionless). -### Thresholds -- $A_{MIN} = \lceil\tfrac{T_{YEAR}}{(T_{RATE} \times \frac{MP_{APY}}{100})}\rceil = \pu{2629744 \mathrm{tokens}}$ - Minimal value to generate 1 multiplier point in the accrue rate period ($T_{RATE}$). - ($A_{MIN} \propto T_{RATE}$) -- $T_{MIN} = 90 \times T_{DAY} = \pu{7776000 \mathrm{s}}$ - Minimum lockup period, equivalent to 90 days. - - $T_{MAX_{YEARS}} = \pu{4 \mathrm{years}}$ - Maximum years of lockup period. -- $T_{MAX} = T_{MAX_{YEARS}} \times T_{YEAR} = \pu{126227700 \mathrm{s}}$ - Maximum lockup period in seconds. -## Variables -### System and User Parameters -- $\Delta a\rightarrow$ = Amount Difference - Difference in amount, can be either reduced or increased depending on context. -- $\Delta t\rightarrow$ Time Difference of last accrual. - The time difference defined as: - $$ - \Delta t = t_{now} - t_{last}, \quad \text{where} \; \Delta t > T_{RATE} - $$ -- $t_{lock}\rightarrow$ = Time Lock Duration - A user-defined duration for which $a_{bal}$ remains locked. -- $t_{now}\rightarrow$ = Time Now - The current timestamp seconds since the Unix epoch (January 1, 1970). -- $t_{lock, \Delta}\rightarrow$ = Time Lock Remaining Duration - Seconds $a_{bal}$ remains locked, expressed as: - $$ - \begin{aligned} - &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ \small\text{ where: }\normalsize\quad & t_{lock, \Delta} = 0\;\text{ or }\;T_{MIN} \le t_{lock, \Delta} \le T_{MAX}\end{aligned} - $$ -### State Related -- $a_{bal}\rightarrow$ = Amount of Balance - Amount of tokens in balance, where $a_{bal} \ge A_{MIN}$. -- $t_{lock,end}\rightarrow$ = Time Lock End - Timestamp marking the end of the lock period, it state can be defined as: - $$ - t_{lock,end} = \max(t_{now}, t_{lock,end}) + t_{lock} - $$ - The value of $t_{lock,end}$ can be updated only within the functions: - - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; - - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; -- $t_{last}\rightarrow$ Time of Accrual - Timestamp of the last accrued time, it state can be defined as: - $$ - t_{last} = t_{now} - $$ - The value of $t_{last}$ is updated by all functions that change state: - - $f^{accrue}(\tiny\mathbb{Account}\normalsize, a_{bal},\Delta t)$, - - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; - - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; - - $\mathcal{f}^{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a)$; -- $mp_\mathcal{M}\rightarrow$ Maximum Multiplier Points - Maximum value that $mp_\Sigma$ can reach. - Relates as $mp_\mathcal{M} \propto a_{bal} \cdot (t_{lock} + M_{MAX})$. - Altered by functions that change the account state: - - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; - - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; - - $\mathcal{f}^{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a)$. - - It's state can be expressed as the following state changes: - 1. Increase in balance and lock: - $$ - \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) - \end{aligned} - $$ - 2. Increase in balance only: - $$ - \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) - \end{aligned} - $$ - 3. Increase in lock only: - $$ - mp_\mathcal{M} &= mp_\mathcal{M} + mp_\mathcal{B}(a_{bal}, t_{lock}) - $$ - 4. Decrease in balance: - $$ - mp_\mathcal{M} &= mp_\mathcal{M} - mp_\mathcal{R}(mp_\mathcal{M}, a_{bal}, \Delta a) - $$ -- $mp_{\Sigma}\rightarrow$ Total Multiplier Points - Altered by all functions that change state: - - $\mathcal{f}^{stake}(\tiny\mathbb{Account}\normalsize, \Delta a, \Delta t_{lock})$; - - $\mathcal{f}^{lock}(\tiny\mathbb{Account}\normalsize, \Delta t_{lock})$; - - $\mathcal{f}^{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a)$; - - $f^{accrue}(\tiny\mathbb{Account}\normalsize, a_{bal},\Delta t)$. - - The state can be expressed as the following state changes: - $$ - mp_{\Sigma} \longrightarrow mp_{\Sigma} \pm - \begin{cases} - \begin{aligned} - & min(mp_\mathcal{M} - mp_\Sigma, \\ - & \quad mp_\mathcal{A}(a_{bal},\, \Delta t)) - \end{aligned} & \text{for every} \; T_{RATE}, \\ - \begin{aligned} - & 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} & \Rightarrow a_{bal} \uparrow \land \; t_{lock,end} \uparrow, \\ - \begin{aligned} - & mp_\mathcal{B}(\Delta a, t_{lock, \Delta}) \\ - & \quad + mp_\mathcal{I}(\Delta a) - \end{aligned} & \Rightarrow a_{bal} \uparrow, \\ - mp_\mathcal{B}(a_{bal}, t_{lock}) & \Rightarrow t_{lock,end} \uparrow, \\ - -mp_\mathcal{R}(mp_{\Sigma}, a_{bal}, \Delta a) & \Rightarrow a_{bal} \downarrow \\ - \end{cases} - $$ -- $\small\mathbb{Account}\normalsize\rightarrow$ Account storage schema - Defined as following: - $$ - \small \mathbb{Account} \normalsize \coloneqq \left\{ - \begin{aligned} - a_{bal} & : \small\text{balance}, \\ \normalsize - t_{lock,end} & : \small\text{lock end}, \\ \normalsize - t_{last} & : \small\text{last accrual}, \\ \normalsize - mp_\Sigma & : \small\text{total MPs}, \\ \normalsize - mp_\mathcal{M} & : \small\text{maximum MPs} - \end{aligned} \right\} - $$ -- $\small\mathbb{System}\normalsize\rightarrow$ System storage schema - Defined as following: - $$ - \small \mathbb{System} \normalsize \coloneqq \left\{ - \begin{aligned} - \tiny\mathbb{Account}\mathrm{[\,]}\normalsize & : \small\text{accounts}, \\ \normalsize - a_{bal} & : \small\text{total staked}, \\ \normalsize - mp_\Sigma & : \small\text{MP supply}, \\ \normalsize - mp_\mathcal{M} & : \small\text{MP supply max} - - \end{aligned} \right\} - $$ + +### Constants + +| Symbol | Source | Value | Unit | Description | +| ----------------- | ------------------------------------------------------------------- | ----------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- | +| $T_{DAY}$ | | 86400 | seconds | One day. | +| $T_{YEAR}$ | $\lfloor365.242190 \times T_{DAY}\rfloor$ | 31556925 | seconds | One (mean) tropical year. | +| $SCALE_{FACTOR}$ | | $\pu{1 \times 10^{18}}$ | (1) | Scaling factor to maintain precision in calculations. | +| $T_{RATE}$ | (minimal blocktime) | 12 | seconds | The accrue rate period of time over which multiplier points are calculated. | +| $MP_{APY}$ | | $\pu{100\%}$ | percent | Annual percentage yield for multiplier points. | +| $M_{MAX}$ | | $\pu{4 \mathrm{(1)}}$ | (1) | Maximum multiplier points to be accrued. | +| $A_{MIN}$ | $\lceil\tfrac{T_{YEAR} \times 100}{T_{RATE} \times MP_{APY}}\rceil$ | 2629744 | tokens per period | Minimal value to generate 1 multiplier point in the accrue rate period ($T_{RATE}$). ($A_{MIN} \propto T_{RATE}$) | +| $T_{MIN}$ | $90 \times T_{DAY}$ | 7776000 | seconds | Minimum lockup period, equivalent to 90 days. | +| $T_{MAX_{YEARS}}$ | | 4 | years | Maximum of lockup period (in years). | +| $T_{MAX}$ | $T_{MAX_{YEARS}} \times T_{YEAR}$ | 126227700 | seconds | Maximum of lockup period. | + +### Variables + +#### System and User Parameters + +##### $\Delta a\rightarrow$ Amount Difference + +Difference in amount, can be either reduced or increased depending on context. + +##### $\Delta t\rightarrow$ Time Difference of Last Accrual + +The time difference defined as: + +$$ +\Delta t = t_{now} - t_{last}, \quad \text{where} \Delta t > T_{RATE} +$$ + +##### $t_{lock}\rightarrow$ Time Lock Duration + +A user-defined duration for which $a_{bal}$ remains locked. + +##### $t_{now}\rightarrow$ Time Now + +The current timestamp seconds since the Unix epoch (January 1, 1970). + +##### $t_{lock, \Delta}\rightarrow$ Time Lock Remaining Duration + +Seconds $a_{bal}$ remains locked, expressed as: + +$$ +\begin{align} &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ +\text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le T_{MAX}\end{align} +$$ + +#### State Related + +##### $a_{bal}\rightarrow$ Amount of Balance + +Amount of tokens in balance, where $a_{bal} \ge A_{MIN}$. + +##### $t_{lock,end}\rightarrow$ Time Lock End + +Timestamp marking the end of the lock period, it state can be defined as: + +$$ +t_{lock,end} = \max(t_{now}, t_{lock,end}) + t_{lock} +$$ + +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})$; + +##### $t_{last}\rightarrow$ Time of Accrual + +Timestamp of the last accrued time, it state can be defined as: + +$$ +t_{last} = t_{now} +$$ + +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)$; + +##### $mp_\mathcal{M}\rightarrow$ Maximum Multiplier Points + +Maximum value that $mp_\Sigma$ can reach. + +Relates as $mp_\mathcal{M} \propto a_{bal} \cdot (t_{lock} + M_{MAX})$. + +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)$. + +It's state can be expressed as the following state changes: + +###### Increase in Balance and Lock + +$$ +\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) +\end{aligned} +$$ + +###### Increase in Balance only + +$$ +\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) +\end{aligned} +$$ + +###### Increase in Lock only + +$$ +mp_\mathcal{M} = mp_\mathcal{M} + mp_\mathcal{B}(a_{bal}, t_{lock}) +$$ + +###### Decrease in Balance + +$$ +mp_\mathcal{M} = mp_\mathcal{M} - mp_\mathcal{R}(mp_\mathcal{M}, a_{bal}, \Delta a) +$$ + +##### $mp_{\Sigma}\rightarrow$ Total Multiplier Points + +Altered by all functions that change 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)$; +- $f^{accrue}(\mathbb{Account}, a_{bal},\Delta t)$. + +The state can be expressed as the following state changes: + +$$ +mp_{\Sigma} \longrightarrow mp_{\Sigma} \pm +\begin{cases} +\begin{aligned} +& min(mp_\mathcal{M} - mp_\Sigma, \\ +& \quad mp_\mathcal{A}(a_{bal}, \Delta t)) +\end{aligned} & \text{for every} T_{RATE}, \\ +\begin{aligned} +& 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} & \Rightarrow a_{bal} \uparrow \land t_{lock,end} \uparrow, \\ +\begin{aligned} +& mp_\mathcal{B}(\Delta a, t_{lock, \Delta}) \\ +& \quad + mp_\mathcal{I}(\Delta a) +\end{aligned} & \Rightarrow a_{bal} \uparrow, \\ +mp_\mathcal{B}(a_{bal}, t_{lock}) & \Rightarrow t_{lock,end} \uparrow, \\ +-mp_\mathcal{R}(mp_{\Sigma}, a_{bal}, \Delta a) & \Rightarrow a_{bal} \downarrow \\ +\end{cases} +$$ + +##### $\mathbb{Account}\rightarrow$ Account Storage Schema + +Defined as following: + +$$ +\begin{gather} +\mathbb{Account} \\ +\overbrace{\begin{align} +a_{bal} & : \text{balance}, \\ +t_{lock,end} & : \text{lock end}, \\ +t_{last} & : \text{last accrual}, \\ +mp_\Sigma & : \text{total MPs}, \\ +mp_\mathcal{M} & : \text{maximum MPs} +\end{align}} +\end{gather} +$$ + +##### $\mathbb{System}\rightarrow$ System Storage Schema + +Defined as following: + +$$ +\begin{gather} + \mathbb{System} \\ +\overbrace{\begin{align} +\mathbb{Account}\mathrm{[]} & : \text{accounts}, \\ +a_{bal} & : \text{total staked}, \\ +mp_\Sigma & : \text{MP supply}, \\ +mp_\mathcal{M} & : \text{MP supply max} +\end{align}} +\end{gather} +$$ --- -## Pure Mathematical Functions ->[!info] This function definitions represent direct mathematical input -> output methods, which don't change state. +### Pure Mathematical Functions + +> [!info] This function definitions represent direct mathematical input -> output methods, which don't change state. + +#### Definition: $\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. -### Definition: $\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. $$ \boxed{ \begin{equation} @@ -166,13 +214,18 @@ $$ \end{equation} } $$ -Where + +Where + - **$\Delta a$**: Represents the change in balance. --- -### Definition: $\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 $MP_{APY}$. +#### Definition: $\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 $MP_{APY}$. + $$ \boxed{ \begin{equation} @@ -180,19 +233,28 @@ $$ \end{equation} } $$ + Where + - **$a_{bal}$**: Represents the current account balance. -- **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the same time units as the year (typically days or months). -- **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference **$\Delta t$**. -- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance grows over a year. +- **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the + same time units as the year (typically days or months). +- **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference + **$\Delta t$**. +- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance + grows over a year. --- -### Definition: $\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 accrued multiplier points function $\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. +#### Definition: $\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 accrued multiplier points function +$\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. + $$ \begin{aligned} - &\;\mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock}) \\ + &\mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock}) \\ &\boxed{ \begin{equation} \mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{100 \times T_{YEAR}} @@ -200,14 +262,24 @@ $$ } \end{aligned} $$ + Where: + - **$\Delta a$**: Represents the amount of the balance that is locked. - **$t_{lock}$**: The duration for which the balance **$\Delta a$** is locked, measured in units of seconds. -- **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a fraction of a full year. -- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate applied to the locked balance. +- **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a + fraction of a full year. +- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate + applied to the locked balance. + --- -### Definition: $\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$**. + +#### Definition: $\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$**. + $$ \boxed{ \begin{equation} @@ -215,208 +287,317 @@ $$ \end{equation} } $$ - Where: - - **$mp$**: Represents the current multiplier points. - - **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. - - **$\Delta a$**: The amount of balance being removed or deducted. + +Where: + +- **$mp$**: Represents the current multiplier points. +- **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. +- **$\Delta a$**: The amount of balance being removed or deducted. --- -## 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. -### Definition: $\mathcal{f}_{stake}(\tiny\mathbb{Account}\normalsize,\Delta a, t_{lock}) \longrightarrow$ Stake Amount With Lock +### 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. + +#### Definition: $\mathcal{f}^{stake}(\mathbb{Account},\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}$. -#### Steps -1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): - $$ - \Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now} - $$ -2. Verify Constraints: - - Ensure new balance ($a_{bal}$ + $\Delta a$) meets the minimum amount ($A_{MIN}$): - $$ - \tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a > A_{MIN} - $$ - - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits ($T_{MIN}$ and $T_{MAX}$): - $$ - \Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX} - $$ -3. Accrue Existing Multiplier Points (MPs): - - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. -4. Calculate Increased Bonus MPs ($\Delta \hat{mp}_\mathcal{B}$) for the Increased Balance ($\Delta a$) and Increased Lock Period ($t_{lock}$): - - For the new amount ($\Delta a$) with the New Remaining Lock Period ($\Delta t_{lock}$): - $$ - \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 ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal}$): - $$ - \Delta \hat{mp}_\mathcal{B} = \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock}) - $$ -5. Calculate Increased Maximum MPs ($\Delta mp_\mathcal{M}$): - $$ - \Delta mp_\mathcal{M} = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B} + \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) - $$ -6. Calculate Increased Total MPs ($\Delta mp_\Sigma$): - $$ - \Delta mp_\Sigma = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}_\mathcal{B} - $$ -7. Update account state - - Update account maximum MPs: - $$ - \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} - $$ - - Update account total MPs: - $$ - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma - $$ - - Update account balance: - $$ - \tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} + \Delta a - $$ - - Update account lock end time: - $$ - \tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - $$ -8. Update system state - - Update system maximum MPs: - $$ - \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} - $$ - - Update system total MPs: - $$ - \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\Sigma - $$ - - Update system total staked amount: - $$ - \tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} + \Delta a - $$ + +##### Steps + +###### 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} +$$ + +###### Verify Constraints + +Ensure new balance ($a_{bal}$ + $\Delta a$) meets the minimum amount ($A_{MIN}$): + +$$ +\mathbb{Account} \cdot a_{bal} + \Delta a > A_{MIN} +$$ + +###### Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within Allowed Limits + +$$ +\Delta t_{lock} = 0 \lor T_{MIN} \le \Delta t_{lock} \le T_{MAX} +$$ + +###### Accrue Existing Multiplier Points (MPs) + +Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. + +###### Calculate Increased Bonus MPs + +For the new amount ($\Delta a$) with the New Remaining Lock Period ($\Delta t_{lock}$): + +$$ +\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}$): + +$$ +\Delta \hat{mp}^\mathcal{B} = \Delta \hat{mp}^\mathcal{B} + \mathcal{f}mp_\mathcal{B}(\mathbb{Account} \cdot a_{bal}, t_{lock}) +$$ + +###### Calculate Increased Maximum MPs ($\Delta mp_\mathcal{M}$) + +$$ +\Delta mp_\mathcal{M} = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}^\mathcal{B} + \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) +$$ + +###### Calculate Increased Total MPs ($\Delta mp_\Sigma$) + +$$ +\Delta mp_\Sigma = \mathcal{f}mp_\mathcal{I}(\Delta a) + \Delta \hat{mp}^\mathcal{B} +$$ + +###### Update account State + +Maximum MPs: + +$$ +\mathbb{Account} \cdot mp_\mathcal{M} = \mathbb{Account}\cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} +$$ + +Total MPs: + +$$ +\mathbb{Account} \cdot mp_\Sigma = \mathbb{Account} \cdot mp_\Sigma + \Delta mp_\Sigma +$$ + +Balance: + +$$ +\mathbb{Account} \cdot a_{bal} = \mathbb{Account} \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} +$$ + +###### Update System State + +Maximum MPs: + +$$ +\mathbb{System} \cdot mp_\mathcal{M} = \mathbb{System} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} +$$ + +Total MPs: + +$$ +\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma + \Delta mp_\Sigma +$$ + +Total staked amount: + +$$ +\mathbb{System} \cdot a_{bal} = \mathbb{System} \cdot a_{bal} + \Delta a +$$ --- -### Definition: $\mathcal{f}_{lock}(\tiny\mathbb{Account}\normalsize, t_{lock}) \longrightarrow$ Increase Lock -> [!info] Equivalent to $\mathcal{f}_{stake}(\tiny\mathbb{Account}\normalsize,0, t_{lock})$ - -_Purpose:_ Allows a user to lock the $\tiny\mathbb{Account}\normalsize _\cdot a_{bal}$ with a lock duration $t_{lock}$. -#### Steps -1. Calculate the New Remaining Lock Period ($\Delta t_{lock}$): - $$ - \Delta t_{lock} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - t_{now} - $$ -2. Verify Constraints: - - Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits: - $$ - \Delta t_{lock} = 0\;\lor\;T_{MIN} \le \Delta t_{lock} \le T_{MAX} - $$ -3. Accrue Existing Multiplier Points (MPs): - - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. -4. Calculate Bonus MPs for the Increased Lock Period: - $$ - \Delta \hat{mp}_\mathcal{B} = mp_\mathcal{B}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal}, t_{lock}) - $$ -5. Update account state: - - Update maximum MPs: - $$ - \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} + \Delta \hat{mp}_\mathcal{B} - $$ - - Update total MPs: - $$ - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{B} - $$ - - Update lock end time: - $$ - \tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} = max(\tiny\mathbb{Account}\normalsize _\cdot t_{lock,end}, t_{now}) + t_{lock} - $$ -6. Update system state: - - Update system maximum MPs: - $$ - \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} + \Delta mp_\mathcal{B} - $$ - - Update system total MPs: - $$ - \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta mp_\mathcal{B} - $$ +#### Definition: $\mathcal{f}^{lock}(\mathbb{Account}, t_{lock}) \longrightarrow$ Increase Lock + +> [!info] Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ + +_Purpose:_ Allows a user to lock the $\mathbb{Account} \cdot a_{bal}$ with a lock duration $t_{lock}$. + +##### Steps + +###### 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} +$$ + +###### Verify Constraints + +Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within allowed limits: + +$$ +\Delta t_{lock} = 0 \lor T_{MIN} \le \Delta t_{lock} \le T_{MAX} +$$ + +###### Accrue Existing Multiplier Points (MPs) + +Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. + +###### Calculate Bonus MPs for the Increased Lock Period + +$$ +\Delta \hat{mp}^\mathcal{B} = mp_\mathcal{B}(\mathbb{Account} \cdot a_{bal}, t_{lock}) +$$ + +###### Update account State + +Maximum MPs: + +$$ +\mathbb{Account} \cdot mp_\mathcal{M} = \mathbb{Account} \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} +$$ + +Lock end time: + +$$ +\mathbb{Account} \cdot t_{lock,end} = max(\mathbb{Account} \cdot t_{lock,end}, t_{now}) + t_{lock} +$$ + +###### Update System State + +Maximum MPs: + +$$ +\mathbb{System} \cdot mp_\mathcal{M} = \mathbb{System} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{B} +$$ + +Total MPs: + +$$ +\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma + \Delta mp_\mathcal{B} +$$ --- -### Definition: $\mathcal{f}_{unstake}(\tiny\mathbb{Account}\normalsize, \Delta a) \longrightarrow$ Unstake Amount Unlocked -1. Verify constraints: - - Ensure the account is not locked: - $$ - \tiny\mathbb{Account}\normalsize _\cdot t_{lock,end} < t_{now} - $$ - - Ensure that account have enough balance: - $$ - \tiny\mathbb{Account}\normalsize _\cdot a_{bal} > \Delta a - $$ - - Ensure that new balance ($\tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a$) will be zero or more than minimum allowed: - $$ - \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a = 0\;\lor\; \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a > A_{MIN} - $$ -2. Accrue Existing Multiplier Points (MPs): - - Call the $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize)$ function to update MPs and last accrual time. -3. Calculate reduced amounts: - - For maximum MPs: - $$ - \Delta mp_\mathcal{M} =\mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M}, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a) - $$ - - For total MPs: - $$ - \Delta mp_\Sigma = \mathcal{f}mp_\mathcal{R}(\tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma, \tiny\mathbb{Account}\normalsize _\cdot a_{bal}, \Delta a) - $$ -4. Update account state: - - Update maximum MPs: - $$ - \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M} - $$ - - Update total MPs: - $$ - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma - $$ - - Update balance: - $$ - \tiny\mathbb{Account}\normalsize _\cdot a_{bal} = \tiny\mathbb{Account}\normalsize _\cdot a_{bal} - \Delta a - $$ -5. Update system state: - - Update system maximum MPs: - $$ - \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} = \tiny\mathbb{System}\normalsize _\cdot mp_\mathcal{M} - \Delta mp_\mathcal{M} - $$ - - Update system total MPs: - $$ - \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma - \Delta mp_\Sigma - $$ - - Update system total staked amount: - $$ - \tiny\mathbb{System}\normalsize _\cdot a_{bal} = \tiny\mathbb{System}\normalsize _\cdot a_{bal} - \Delta a - $$ +#### Definition: $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a) \longrightarrow$ Unstake Amount Unlocked + +##### Verify Constraints + +Ensure the account is not locked: + +$$ +\mathbb{Account} \cdot t_{lock,end} < t_{now} +$$ + +Ensure that account have enough balance: + +$$ +\mathbb{Account} \cdot a_{bal} > \Delta a +$$ + +Ensure that new balance ($\mathbb{Account} \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} +$$ + +##### Accrue Existing Multiplier Points (MPs) + +Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. + +##### Calculate Reduced Amounts + +Maximum MPs: + +$$ +\Delta mp_\mathcal{M} =\mathcal{f}mp_\mathcal{R}(\mathbb{Account} \cdot mp_\mathcal{M}, \mathbb{Account} \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) +$$ + +##### Update account State + +Maximum MPs: + +$$ +\mathbb{Account} \cdot mp_\mathcal{M} = \mathbb{Account} \cdot mp_\mathcal{M} - \Delta mp_\mathcal{M} +$$ + +Total MPs: + +$$ +\mathbb{Account} \cdot mp_\Sigma = \mathbb{Account} \cdot mp_\Sigma - \Delta mp_\Sigma +$$ + +Balance: + +$$ +\mathbb{Account} \cdot a_{bal} = \mathbb{Account} \cdot a_{bal} - \Delta a +$$ + +##### Update System State + +Maximum MPs: + +$$ +\mathbb{System} \cdot mp_\mathcal{M} = \mathbb{System} \cdot mp_\mathcal{M} - \Delta mp_\mathcal{M} +$$ + +Total MPs: + +$$ +\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma - \Delta mp_\Sigma +$$ + +Total staked amount: + +$$ +\mathbb{System} \cdot a_{bal} = \mathbb{System} \cdot a_{bal} - \Delta a +$$ --- -### Definition: $\mathcal{f}_{accrue}(\tiny\mathbb{Account}\normalsize) \longrightarrow$ Accrue Multiplier Points -1. Calculate the time period since last accrual: - $$ - \Delta t = t_{now} - \tiny\mathbb{Account}\normalsize _\cdot t_{last} - $$ -2. Verify constraints: - - Ensure the accrual period is greater than the minimum rate period: - $$ - \Delta t > T_{RATE} - $$ -4. Calculate accrued MP for the accrual period: - $$ - \Delta \hat{mp}_\mathcal{A} = min(\mathcal{f}mp_\mathcal{A}(\tiny\mathbb{Account}\normalsize _\cdot a_{bal},\Delta t) ,\tiny\mathbb{Account}\normalsize _\cdot mp_\mathcal{M} - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma) - $$ -5. Update account state: - - Update total MPs: - $$ - \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{Account}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A} - $$ - - Update last accrual time: - $$ - \tiny\mathbb{Account}\normalsize _\cdot t_{last} = \tiny\mathbb{Account}\normalsize _\cdot t_{now} - $$ -6. Update system state: - - Update system total MPs: - $$ - \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma = \tiny\mathbb{System}\normalsize _\cdot mp_\Sigma + \Delta \hat{mp}_\mathcal{A} - $$ +#### Definition: $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points + +##### Calculate the time Period since Last Accrual + +$$ +\Delta t = t_{now} - \mathbb{Account} \cdot t_{last} +$$ + +##### Verify Constraints + +Ensure the accrual period is greater than the minimum rate period: + +$$ +\Delta t > T_{RATE} +$$ + +##### 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) +$$ + +##### Update account State + +Total MPs: + +$$ +\mathbb{Account} \cdot mp_\Sigma = \mathbb{Account} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{A} +$$ + +Last accrual time: + +$$ +\mathbb{Account} \cdot t_{last} = \mathbb{Account} \cdot t_{now} +$$ + +##### Update System State + +Total MPs: + +$$ +\mathbb{System} \cdot mp_\Sigma = \mathbb{System} \cdot mp_\Sigma + \Delta \hat{mp}^\mathcal{A} +$$ + --- From 1a2edd790fd13850a24eeab948ef20ab8bcecb91 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Sun, 20 Oct 2024 17:46:03 -0300 Subject: [PATCH 04/23] chore(MathSpec.md): improve readability --- docs/MathSpec.md | 128 ++++++++++++++++++++++++++--------------------- 1 file changed, 70 insertions(+), 58 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index d76a41b..3aca0e1 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -25,6 +25,8 @@ Difference in amount, can be either reduced or increased depending on context. +--- + ##### $\Delta t\rightarrow$ Time Difference of Last Accrual The time difference defined as: @@ -33,14 +35,23 @@ $$ \Delta t = t_{now} - t_{last}, \quad \text{where} \Delta t > T_{RATE} $$ +--- + + ##### $t_{lock}\rightarrow$ Time Lock Duration A user-defined duration for which $a_{bal}$ remains locked. +--- + + ##### $t_{now}\rightarrow$ Time Now The current timestamp seconds since the Unix epoch (January 1, 1970). +--- + + ##### $t_{lock, \Delta}\rightarrow$ Time Lock Remaining Duration Seconds $a_{bal}$ remains locked, expressed as: @@ -50,12 +61,16 @@ $$ \text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le T_{MAX}\end{align} $$ +--- + #### State Related ##### $a_{bal}\rightarrow$ Amount of Balance Amount of tokens in balance, where $a_{bal} \ge A_{MIN}$. +--- + ##### $t_{lock,end}\rightarrow$ Time Lock End Timestamp marking the end of the lock period, it state can be defined as: @@ -69,6 +84,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})$; +--- + ##### $t_{last}\rightarrow$ Time of Accrual Timestamp of the last accrued time, it state can be defined as: @@ -84,6 +101,8 @@ The value of $t_{last}$ is updated by all functions that change state: - $\mathcal{f}^{lock}(\mathbb{Account}, \Delta t_{lock})$; - $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a)$; +--- + ##### $mp_\mathcal{M}\rightarrow$ Maximum Multiplier Points Maximum value that $mp_\Sigma$ can reach. @@ -101,21 +120,21 @@ It's state can be expressed as the following state changes: ###### Increase in Balance and Lock $$ -\begin{aligned} +\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) +&\quad + mp_\mathcal{I}(\Delta a) \end{aligned} $$ ###### Increase in Balance only $$ -\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) +\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) \end{aligned} $$ @@ -131,6 +150,8 @@ $$ mp_\mathcal{M} = mp_\mathcal{M} - mp_\mathcal{R}(mp_\mathcal{M}, a_{bal}, \Delta a) $$ +--- + ##### $mp_{\Sigma}\rightarrow$ Total Multiplier Points Altered by all functions that change state: @@ -143,26 +164,28 @@ Altered by all functions that change state: The state can be expressed as the following state changes: $$ -mp_{\Sigma} \longrightarrow mp_{\Sigma} \pm +mp_{\Sigma} \longrightarrow mp_{\Sigma} \pm \begin{cases} -\begin{aligned} +\begin{aligned} & min(mp_\mathcal{M} - mp_\Sigma, \\ -& \quad mp_\mathcal{A}(a_{bal}, \Delta t)) -\end{aligned} & \text{for every} T_{RATE}, \\ +& \quad mp_\mathcal{A}(a_{bal}, \Delta t)) +\end{aligned} & \text{for every} T_{RATE}, \\ \begin{aligned} -& mp_\mathcal{B}(\Delta a,t_{lock, \Delta} + t_{lock}) \\ +& 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} & \Rightarrow a_{bal} \uparrow \land t_{lock,end} \uparrow, \\ +& \quad + mp_\mathcal{I}(\Delta a) +\end{aligned} & \Rightarrow a_{bal} \uparrow \land t_{lock,end} \uparrow, \\ \begin{aligned} & mp_\mathcal{B}(\Delta a, t_{lock, \Delta}) \\ -& \quad + mp_\mathcal{I}(\Delta a) +& \quad + mp_\mathcal{I}(\Delta a) \end{aligned} & \Rightarrow a_{bal} \uparrow, \\ -mp_\mathcal{B}(a_{bal}, t_{lock}) & \Rightarrow t_{lock,end} \uparrow, \\ +mp_\mathcal{B}(a_{bal}, t_{lock}) & \Rightarrow t_{lock,end} \uparrow, \\ -mp_\mathcal{R}(mp_{\Sigma}, a_{bal}, \Delta a) & \Rightarrow a_{bal} \downarrow \\ \end{cases} $$ +--- + ##### $\mathbb{Account}\rightarrow$ Account Storage Schema Defined as following: @@ -170,30 +193,32 @@ Defined as following: $$ \begin{gather} \mathbb{Account} \\ -\overbrace{\begin{align} -a_{bal} & : \text{balance}, \\ -t_{lock,end} & : \text{lock end}, \\ -t_{last} & : \text{last accrual}, \\ -mp_\Sigma & : \text{total MPs}, \\ -mp_\mathcal{M} & : \text{maximum MPs} -\end{align}} -\end{gather} +\overbrace{\begin{align} +a_{bal} & : \text{balance}, \\ +t_{lock,end} & : \text{lock end}, \\ +t_{last} & : \text{last accrual}, \\ +mp_\Sigma & : \text{total MPs}, \\ +mp_\mathcal{M} & : \text{maximum MPs} +\end{align}} +\end{gather} $$ +--- + ##### $\mathbb{System}\rightarrow$ System Storage Schema Defined as following: $$ \begin{gather} - \mathbb{System} \\ -\overbrace{\begin{align} -\mathbb{Account}\mathrm{[]} & : \text{accounts}, \\ + \mathbb{System} \\ +\overbrace{\begin{align} +\mathbb{Account}\mathrm{[]} & : \text{accounts}, \\ a_{bal} & : \text{total staked}, \\ -mp_\Sigma & : \text{MP supply}, \\ -mp_\mathcal{M} & : \text{MP supply max} +mp_\Sigma & : \text{MP supply}, \\ +mp_\mathcal{M} & : \text{MP supply max} \end{align}} -\end{gather} +\end{gather} $$ --- @@ -204,8 +229,7 @@ $$ #### Definition: $\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 (**MPs**) based on the balance change $\Delta a$. The result is equal to the amount of balance added. $$ \boxed{ @@ -223,8 +247,7 @@ Where #### Definition: $\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 $MP_{APY}$. +Calculates the accrued multiplier points (**MPs**) over a time period **$\Delta t$**, based on the account balance **$a_{bal}$** and the annual percentage yield $MP_{APY}$. $$ \boxed{ @@ -237,20 +260,15 @@ $$ Where - **$a_{bal}$**: Represents the current account balance. -- **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the - same time units as the year (typically days or months). -- **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference - **$\Delta t$**. -- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance - grows over a year. +- **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the same time units as the year (typically days or months). +- **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference **$\Delta t$**. +- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance grows over a year. --- #### Definition: $\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 accrued multiplier points function -$\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. +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 accrued multiplier points function $\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. $$ \begin{aligned} @@ -267,18 +285,14 @@ Where: - **$\Delta a$**: Represents the amount of the balance that is locked. - **$t_{lock}$**: The duration for which the balance **$\Delta a$** is locked, measured in units of seconds. -- **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a - fraction of a full year. -- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate - applied to the locked balance. +- **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a fraction of a full year. +- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate applied to the locked balance. --- #### Definition: $\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 (**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$**. $$ \boxed{ @@ -288,19 +302,17 @@ $$ } $$ -Where: + Where: -- **$mp$**: Represents the current multiplier points. -- **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. -- **$\Delta a$**: The amount of balance being removed or deducted. + - **$mp$**: Represents the current multiplier points. + - **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. + - **$\Delta a$**: The amount of balance being removed or deducted. --- ### 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{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. #### Definition: $\mathcal{f}^{stake}(\mathbb{Account},\Delta A, t_{lock}) \longrightarrow$ Stake Amount With Lock @@ -562,7 +574,7 @@ $$ $$ \Delta t = t_{now} - \mathbb{Account} \cdot t_{last} -$$ +$$ ##### Verify Constraints @@ -576,7 +588,7 @@ $$ $$ \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) -$$ +$$ ##### Update account State From 6885f608084b6873a36f7020d66d6a09d98f032d Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 21 Oct 2024 11:35:41 -0300 Subject: [PATCH 05/23] chore(MathSpec.md): Add missing details, change MP Total Variable spec to be more descriptive instead a big formula --- docs/MathSpec.md | 168 ++++++++++++++++++++++++++++------------------- 1 file changed, 102 insertions(+), 66 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 3aca0e1..d84b7d2 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -29,6 +29,8 @@ Difference in amount, can be either reduced or increased depending on context. ##### $\Delta t\rightarrow$ Time Difference of Last Accrual +--- + The time difference defined as: $$ @@ -73,7 +75,7 @@ Amount of tokens in balance, where $a_{bal} \ge A_{MIN}$. ##### $t_{lock,end}\rightarrow$ Time Lock End -Timestamp marking the end of the lock period, it state can be defined as: +Timestamp marking the end of the lock period, its state can be defined as: $$ t_{lock,end} = \max(t_{now}, t_{lock,end}) + t_{lock} @@ -88,7 +90,7 @@ The value of $t_{lock,end}$ can be updated only within the functions: ##### $t_{last}\rightarrow$ Time of Accrual -Timestamp of the last accrued time, it state can be defined as: +Timestamp of the last accrued time, its state can be defined as: $$ t_{last} = t_{now} @@ -120,21 +122,21 @@ It's state can be expressed as the following state changes: ###### Increase in Balance and Lock $$ -\begin{aligned} +\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) +&\quad + mp_\mathcal{I}(\Delta a) \end{aligned} $$ ###### Increase in Balance only $$ -\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) +\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) \end{aligned} $$ @@ -163,25 +165,38 @@ Altered by all functions that change state: 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) +$$ + +###### Increase in Balance and Lock + $$ -mp_{\Sigma} \longrightarrow mp_{\Sigma} \pm -\begin{cases} -\begin{aligned} -& min(mp_\mathcal{M} - mp_\Sigma, \\ -& \quad mp_\mathcal{A}(a_{bal}, \Delta t)) -\end{aligned} & \text{for every} T_{RATE}, \\ -\begin{aligned} -& 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} & \Rightarrow a_{bal} \uparrow \land t_{lock,end} \uparrow, \\ \begin{aligned} -& mp_\mathcal{B}(\Delta a, t_{lock, \Delta}) \\ -& \quad + mp_\mathcal{I}(\Delta a) -\end{aligned} & \Rightarrow a_{bal} \uparrow, \\ -mp_\mathcal{B}(a_{bal}, t_{lock}) & \Rightarrow t_{lock,end} \uparrow, \\ --mp_\mathcal{R}(mp_{\Sigma}, a_{bal}, \Delta a) & \Rightarrow a_{bal} \downarrow \\ -\end{cases} +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} +$$ + +###### Increase in Balance only + +$$ +mp_{\Sigma} = mp_{\Sigma} + mp_\mathcal{B}(\Delta a, t_{lock, \Delta}) + mp_\mathcal{I}(\Delta a) +$$ + +###### Increase in Lock only + +$$ +mp_{\Sigma} = mp_{\Sigma} + mp_\mathcal{B}(a_{bal}, t_{lock}) +$$ + +###### Decrease in Balance + +$$ +mp_{\Sigma} = mp_{\Sigma} - mp_\mathcal{R}(mp_{\Sigma}, a_{bal}, \Delta a) $$ --- @@ -193,14 +208,14 @@ Defined as following: $$ \begin{gather} \mathbb{Account} \\ -\overbrace{\begin{align} -a_{bal} & : \text{balance}, \\ -t_{lock,end} & : \text{lock end}, \\ -t_{last} & : \text{last accrual}, \\ -mp_\Sigma & : \text{total MPs}, \\ -mp_\mathcal{M} & : \text{maximum MPs} -\end{align}} -\end{gather} +\overbrace{\begin{align} +a_{bal} & : \text{balance}, \\ +t_{lock,end} & : \text{lock end}, \\ +t_{last} & : \text{last accrual}, \\ +mp_\Sigma & : \text{total MPs}, \\ +mp_\mathcal{M} & : \text{maximum MPs} +\end{align}} +\end{gather} $$ --- @@ -211,14 +226,14 @@ Defined as following: $$ \begin{gather} - \mathbb{System} \\ -\overbrace{\begin{align} -\mathbb{Account}\mathrm{[]} & : \text{accounts}, \\ + \mathbb{System} \\ +\overbrace{\begin{align} +\mathbb{Account}\mathrm{[]} & : \text{accounts}, \\ a_{bal} & : \text{total staked}, \\ -mp_\Sigma & : \text{MP supply}, \\ -mp_\mathcal{M} & : \text{MP supply max} +mp_\Sigma & : \text{MP supply}, \\ +mp_\mathcal{M} & : \text{MP supply max} \end{align}} -\end{gather} +\end{gather} $$ --- @@ -229,7 +244,8 @@ $$ #### Definition: $\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 (**MPs**) based on the balance change $\Delta a$. The result is equal to the +amount of balance added. $$ \boxed{ @@ -247,7 +263,8 @@ Where #### Definition: $\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 $MP_{APY}$. +Calculates the accrued multiplier points (**MPs**) over a time period **$\Delta t$**, based on the account balance +**$a_{bal}$** and the annual percentage yield $MP_{APY}$. $$ \boxed{ @@ -260,15 +277,20 @@ $$ Where - **$a_{bal}$**: Represents the current account balance. -- **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the same time units as the year (typically days or months). -- **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference **$\Delta t$**. -- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance grows over a year. +- **$\Delta t$**: The time difference or the duration over which the multiplier points are accrued, expressed in the + same time units as the year (typically days or months). +- **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference + **$\Delta t$**. +- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance + grows over a year. --- #### Definition: $\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 accrued multiplier points function $\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. +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 accrued multiplier points function +$\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. $$ \begin{aligned} @@ -285,14 +307,18 @@ Where: - **$\Delta a$**: Represents the amount of the balance that is locked. - **$t_{lock}$**: The duration for which the balance **$\Delta a$** is locked, measured in units of seconds. -- **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a fraction of a full year. -- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate applied to the locked balance. +- **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a + fraction of a full year. +- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate + applied to the locked balance. --- #### Definition: $\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 (**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$**. $$ \boxed{ @@ -302,17 +328,19 @@ $$ } $$ - Where: +Where: - - **$mp$**: Represents the current multiplier points. - - **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. - - **$\Delta a$**: The amount of balance being removed or deducted. +- **$mp$**: Represents the current multiplier points. +- **$a_{bal}$**: The total account balance before the removal of **$\Delta a$**. +- **$\Delta a$**: The amount of balance being removed or deducted. --- ### 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{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. #### Definition: $\mathcal{f}^{stake}(\mathbb{Account},\Delta A, t_{lock}) \longrightarrow$ Stake Amount With Lock @@ -488,7 +516,11 @@ $$ #### Definition: $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a) \longrightarrow$ Unstake Amount Unlocked -##### Verify Constraints +Purpose: Allows a user to unstake an amount $\Delta a$. + +##### Steps + +###### Verify Constraints Ensure the account is not locked: @@ -508,11 +540,11 @@ $$ \mathbb{Account} \cdot a_{bal} - \Delta a = 0 \lor \mathbb{Account} \cdot a_{bal} - \Delta a > A_{MIN} $$ -##### Accrue Existing Multiplier Points (MPs) +###### Accrue Existing Multiplier Points (MPs) Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. -##### Calculate Reduced Amounts +###### Calculate Reduced Amounts Maximum MPs: @@ -526,7 +558,7 @@ $$ \Delta mp_\Sigma = \mathcal{f}mp_\mathcal{R}(\mathbb{Account} \cdot mp_\Sigma, \mathbb{Account} \cdot a_{bal}, \Delta a) $$ -##### Update account State +###### Update account State Maximum MPs: @@ -546,7 +578,7 @@ $$ \mathbb{Account} \cdot a_{bal} = \mathbb{Account} \cdot a_{bal} - \Delta a $$ -##### Update System State +###### Update System State Maximum MPs: @@ -570,13 +602,17 @@ $$ #### Definition: $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points -##### Calculate the time Period since Last Accrual +Purpose: Accrue multiplier points (MPs) for the account based on the elapsed time since the last accrual. + +##### Steps + +###### Calculate the time Period since Last Accrual $$ \Delta t = t_{now} - \mathbb{Account} \cdot t_{last} -$$ +$$ -##### Verify Constraints +###### Verify Constraints Ensure the accrual period is greater than the minimum rate period: @@ -584,13 +620,13 @@ $$ \Delta t > T_{RATE} $$ -##### Calculate Accrued MP for the Accrual Period +###### 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) -$$ +$$ -##### Update account State +###### Update account State Total MPs: @@ -601,10 +637,10 @@ $$ Last accrual time: $$ -\mathbb{Account} \cdot t_{last} = \mathbb{Account} \cdot t_{now} +\mathbb{Account} \cdot t_{last} = t_{now} $$ -##### Update System State +###### Update System State Total MPs: From 45386911d0f0e75850af3e77f3e59b52ad50b11f Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 21 Oct 2024 11:36:47 -0300 Subject: [PATCH 06/23] chore(MathSpec.md): Run prettier --- docs/MathSpec.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index d84b7d2..ac0756c 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -39,21 +39,18 @@ $$ --- - ##### $t_{lock}\rightarrow$ Time Lock Duration A user-defined duration for which $a_{bal}$ remains locked. --- - ##### $t_{now}\rightarrow$ Time Now The current timestamp seconds since the Unix epoch (January 1, 1970). --- - ##### $t_{lock, \Delta}\rightarrow$ Time Lock Remaining Duration Seconds $a_{bal}$ remains locked, expressed as: From a8e17b745b3637ec94a9339c8d2829b7dfc22c86 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Tue, 22 Oct 2024 00:12:47 -0300 Subject: [PATCH 07/23] chore(MathSpec.md): fix order of call accrue from other functions + add storage access diagram --- docs/MathSpec.md | 124 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 112 insertions(+), 12 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index ac0756c..77f2c6a 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -2,6 +2,8 @@ > [!attention] All values in this document are expressed as unsigned integers. +### Summary + ### Constants | Symbol | Source | Value | Unit | Description | @@ -343,8 +345,46 @@ affecting either the system as a whole and the individual account states. _Purpose:_ Allows a user to stake an amount $\Delta a$ with an optional lock duration $t_{lock}$. +```mermaid +--- +title: Stake Storage Access Flowchart +--- +flowchart LR + BonusMP{{Bonus MP}} + InitialMP{{Initial MP}} + + Balance + LockEnd[Lock End] + TotalMP[Total MPs] + MaxMP[Maximum\nMPs] + + FBonusMP{Calc\nBonus MP} + FMaxMP{Calc Max\nAccrue MP} + M_MAX([MAX\nMULTIPLIER]) + %% Stake Process + + %% Update Flow + Balance --> InitialMP + Balance --> FMaxMP + M_MAX --> FMaxMP + InitialMP --> TotalMP + InitialMP --> MaxMP + + BonusMP --> TotalMP + BonusMP --> MaxMP + FMaxMP --> MaxMP + + LockEnd --> FBonusMP + Balance --> FBonusMP + FBonusMP --> BonusMP +``` + ##### Steps +###### Accrue Existing Multiplier Points (MPs) + +Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. + ###### Calculate the New Remaining Lock Period ($\Delta t_{lock}$) $$ @@ -365,10 +405,6 @@ $$ \Delta t_{lock} = 0 \lor T_{MIN} \le \Delta t_{lock} \le T_{MAX} $$ -###### Accrue Existing Multiplier Points (MPs) - -Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. - ###### Calculate Increased Bonus MPs For the new amount ($\Delta a$) with the New Remaining Lock Period ($\Delta t_{lock}$): @@ -449,8 +485,29 @@ $$ _Purpose:_ Allows a user to lock the $\mathbb{Account} \cdot a_{bal}$ with a lock duration $t_{lock}$. +```mermaid +--- +title: Lock Storage Access Flowchart +--- +flowchart LR + BonusMP{{Bonus MP}} + LockEnd[Lock End] + TotalMP[Total MPs] + MaxMP[Maximum\nMPs] + FBonusMP{Calc\nBonus MP} + BonusMP --> TotalMP + BonusMP --> MaxMP + LockEnd --> FBonusMP + Balance --> FBonusMP + FBonusMP --> BonusMP +``` + ##### Steps +###### Accrue Existing Multiplier Points (MPs) + +Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. + ###### Calculate the New Remaining Lock Period ($\Delta t_{lock}$) $$ @@ -465,10 +522,6 @@ $$ \Delta t_{lock} = 0 \lor T_{MIN} \le \Delta t_{lock} \le T_{MAX} $$ -###### Accrue Existing Multiplier Points (MPs) - -Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. - ###### Calculate Bonus MPs for the Increased Lock Period $$ @@ -515,8 +568,32 @@ $$ Purpose: Allows a user to unstake an amount $\Delta a$. +```mermaid +--- +title: Unstake Storage Access Flowchart +--- +flowchart LR + Balance + TotalMP[Total MPs] + MaxMP[Maximum\nMPs] + + FReduceMP{Calc\nReduced MP} + + %% Unstake Process + TotalMP --> FReduceMP + MaxMP --> FReduceMP + Balance --> FReduceMP + FReduceMP --> Balance + FReduceMP --> TotalMP + FReduceMP --> MaxMP +``` + ##### Steps +###### Accrue Existing Multiplier Points (MPs) + +Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. + ###### Verify Constraints Ensure the account is not locked: @@ -537,10 +614,6 @@ $$ \mathbb{Account} \cdot a_{bal} - \Delta a = 0 \lor \mathbb{Account} \cdot a_{bal} - \Delta a > A_{MIN} $$ -###### Accrue Existing Multiplier Points (MPs) - -Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ function to update MPs and last accrual time. - ###### Calculate Reduced Amounts Maximum MPs: @@ -601,6 +674,33 @@ $$ Purpose: Accrue multiplier points (MPs) for the account based on the elapsed time since the last accrual. +```mermaid +--- +title: Accrue Storage Access Flowchart +--- +flowchart LR + + + + + AccruedMP{{Accrued MP}} + + Balance + LastMint[Last Mint] + TotalMP[Total MPs] --> MAX{max} + MaxMP[Maximum\nMPs] --> MAX + FAccruedMP{Calc\nAccrued MP} + %% Update Flow + + NOW((NOW)) --> FAccruedMP + FAccruedMP --> LastMint + LastMint --> FAccruedMP + Balance --> FAccruedMP + FAccruedMP --> AccruedMP + AccruedMP --> MAX + MAX --> TotalMP +``` + ##### Steps ###### Calculate the time Period since Last Accrual From 9e5a0b85b91946265e22e309ff927ac4e2213851 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Tue, 22 Oct 2024 00:15:40 -0300 Subject: [PATCH 08/23] Remove \n from diagrams --- docs/MathSpec.md | 37 ++++++++++--------------------------- 1 file changed, 10 insertions(+), 27 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 77f2c6a..83ae573 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -352,28 +352,21 @@ title: Stake Storage Access Flowchart flowchart LR BonusMP{{Bonus MP}} InitialMP{{Initial MP}} - Balance LockEnd[Lock End] TotalMP[Total MPs] - MaxMP[Maximum\nMPs] - - FBonusMP{Calc\nBonus MP} - FMaxMP{Calc Max\nAccrue MP} - M_MAX([MAX\nMULTIPLIER]) - %% Stake Process - - %% Update Flow + MaxMP[Maximum MPs] + FBonusMP{Calc Bonus MP} + FMaxMP{Calc Max Accrue MP} + M_MAX([MAX MULTIPLIER]) Balance --> InitialMP Balance --> FMaxMP M_MAX --> FMaxMP InitialMP --> TotalMP InitialMP --> MaxMP - BonusMP --> TotalMP BonusMP --> MaxMP FMaxMP --> MaxMP - LockEnd --> FBonusMP Balance --> FBonusMP FBonusMP --> BonusMP @@ -493,8 +486,8 @@ flowchart LR BonusMP{{Bonus MP}} LockEnd[Lock End] TotalMP[Total MPs] - MaxMP[Maximum\nMPs] - FBonusMP{Calc\nBonus MP} + MaxMP[Maximum MPs] + FBonusMP{Calc Bonus MP} BonusMP --> TotalMP BonusMP --> MaxMP LockEnd --> FBonusMP @@ -575,11 +568,8 @@ title: Unstake Storage Access Flowchart flowchart LR Balance TotalMP[Total MPs] - MaxMP[Maximum\nMPs] - - FReduceMP{Calc\nReduced MP} - - %% Unstake Process + MaxMP[Maximum MPs] + FReduceMP{Calc Reduced MP} TotalMP --> FReduceMP MaxMP --> FReduceMP Balance --> FReduceMP @@ -679,19 +669,12 @@ Purpose: Accrue multiplier points (MPs) for the account based on the elapsed tim title: Accrue Storage Access Flowchart --- flowchart LR - - - - AccruedMP{{Accrued MP}} - Balance LastMint[Last Mint] TotalMP[Total MPs] --> MAX{max} - MaxMP[Maximum\nMPs] --> MAX - FAccruedMP{Calc\nAccrued MP} - %% Update Flow - + MaxMP[Maximum MPs] --> MAX + FAccruedMP{Calc Accrued MP} NOW((NOW)) --> FAccruedMP FAccruedMP --> LastMint LastMint --> FAccruedMP From e7477b11ad990aa35c1e50c37e67ac22e8de0cd7 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Wed, 30 Oct 2024 08:55:54 -0300 Subject: [PATCH 09/23] Fix callouts --- docs/MathSpec.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 83ae573..c3c3e41 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -1,6 +1,7 @@ ## Mathematical Specification of Staking Protocol -> [!attention] All values in this document are expressed as unsigned integers. +> [!IMPORTANT] +> All values in this document are expressed as unsigned integers. ### Summary @@ -239,7 +240,8 @@ $$ ### Pure Mathematical Functions -> [!info] This function definitions represent direct mathematical input -> output methods, which don't change state. +> [!NOTE] +> This function definitions represent direct mathematical input -> output methods, which don't change state. #### Definition: $\mathcal{f}{mp_\mathcal{I}}(\Delta a) \longrightarrow$ Initial Multiplier Points @@ -474,7 +476,8 @@ $$ #### Definition: $\mathcal{f}^{lock}(\mathbb{Account}, t_{lock}) \longrightarrow$ Increase Lock -> [!info] Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ +> [!NOTE] +> Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ _Purpose:_ Allows a user to lock the $\mathbb{Account} \cdot a_{bal}$ with a lock duration $t_{lock}$. From 25c69662468f0f5d36e4c8b3f035d38bb5098dc3 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Wed, 30 Oct 2024 10:30:35 -0300 Subject: [PATCH 10/23] chore(MathSpec.md): add view functions --- docs/MathSpec.md | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index c3c3e41..3c4670d 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -1,7 +1,6 @@ ## Mathematical Specification of Staking Protocol -> [!IMPORTANT] -> All values in this document are expressed as unsigned integers. +> [!IMPORTANT] All values in this document are expressed as unsigned integers. ### Summary @@ -240,8 +239,7 @@ $$ ### Pure Mathematical Functions -> [!NOTE] -> This function definitions represent direct mathematical input -> output methods, which don't change state. +> [!NOTE] This function definitions represent direct mathematical input -> output methods, which don't change state. #### Definition: $\mathcal{f}{mp_\mathcal{I}}(\Delta a) \longrightarrow$ Initial Multiplier Points @@ -476,8 +474,7 @@ $$ #### Definition: $\mathcal{f}^{lock}(\mathbb{Account}, t_{lock}) \longrightarrow$ Increase Lock -> [!NOTE] -> Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ +> [!NOTE] Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ _Purpose:_ Allows a user to lock the $\mathbb{Account} \cdot a_{bal}$ with a lock duration $t_{lock}$. @@ -732,3 +729,34 @@ $$ $$ --- + +### View Functions + +#### Maximum Total Multiplier Points + +> [!NOTE] The maximum total multiplier points that can be generated for a determined amount of balance and lock +> duration. + +$\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) + \mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) + \mathcal{f}mp_\mathcal{I}(\Delta a)$ +$\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \left(\dfrac{\Delta a \times (M_{MAX} \times T_{YEAR}) \times MP_{APY}}{T_{YEAR} \times 100}\right) + \left( \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{T_{YEAR} \times 100} \right)+ \Delta a$ + +$$ +\boxed{\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \dfrac{\Delta a \times MP_{APY}}{100} \times \left(M_{MAX} + \dfrac{t_{lock}}{T_{YEAR}}\right) + \Delta a} +$$ + +#### Absolute Maximum Multiplier Points + +The absolute maximum multiplier points that some balance could have, using the maximum lock time and maximum accrual +period. This can be used to limit the extension on the lock time. + +$$ +mp_\mathcal{M}^{abs} = a_{bal} + \left( \dfrac{a_{bal} \times T_{max} \times MP_{APY}}{T_{YEAR} \times 100} \right) + a_{bal} \times M_{max} +$$ + +#### Locked Time ($t_{lock}$) + +> [!CAUTION] This value is estimated and can be incorrect due precision loss, rounding up mostly helps with this but +> it's not guaranteed. + +Estimates the time an account set as locked time. This can be used to limit the extension on the lock time. +$\hat{\mathcal{f}}\tilde{t}_{lock}(mp_\mathcal{M}, a_{bal}) \approx \left\lceil\dfrac{( mp_\mathcal{M} - a_{bal} \times (M_{max} + 1)) \times T_{YEAR} \times 100 }{ a_{bal} \times MP_{APY}}\right\rceil$ From 8b3129fcd9154e012eb8469dc8c2bc14007fc890 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Wed, 30 Oct 2024 11:36:49 -0300 Subject: [PATCH 11/23] chore(MathSpec.md): Fix MP_APY formula on locked time estimate --- docs/MathSpec.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 3c4670d..f352621 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -759,4 +759,9 @@ $$ > it's not guaranteed. Estimates the time an account set as locked time. This can be used to limit the extension on the lock time. -$\hat{\mathcal{f}}\tilde{t}_{lock}(mp_\mathcal{M}, a_{bal}) \approx \left\lceil\dfrac{( mp_\mathcal{M} - a_{bal} \times (M_{max} + 1)) \times T_{YEAR} \times 100 }{ a_{bal} \times MP_{APY}}\right\rceil$ + +$$ +\begin{align} +\hat{\mathcal{f}}\tilde{t}_{\text{lock}}(mp_{\mathcal{M}}, a_{\text{bal}}) &\approx \left\lceil \frac{(mp_{\mathcal{M}} - a_{\text{bal}}) \times 100 \times T_{\text{YEAR}}}{a_{\text{bal}} \times MP_{\text{APY}}} - M_{\text{MAX}} \times T_{\text{YEAR}} \right\rceil +\end{align} +$$ From 6fd3875bd38aab72cf76c5c9f7ac9dcecc8bc0e0 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Thu, 31 Oct 2024 11:57:54 -0300 Subject: [PATCH 12/23] chore(MathSpec.md): Add verification for absolute maximum multiplier points in stake and lock. --- docs/MathSpec.md | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index f352621..3de8743 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -392,7 +392,7 @@ $$ \mathbb{Account} \cdot a_{bal} + \Delta a > A_{MIN} $$ -###### Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within Allowed Limits +Ensure the New Remaining Lock Period ($\Delta t_{lock}$) is within Allowed Limits $$ \Delta t_{lock} = 0 \lor T_{MIN} \le \Delta t_{lock} \le T_{MAX} @@ -424,6 +424,15 @@ $$ \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: + +$$ +\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} \le a_{bal} \times \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) +$$ + ###### Update account State Maximum MPs: @@ -521,6 +530,15 @@ $$ \Delta \hat{mp}^\mathcal{B} = mp_\mathcal{B}(\mathbb{Account} \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: + +$$ +\mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B} \le a_{bal} \times \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) +$$ + ###### Update account State Maximum MPs: @@ -750,7 +768,7 @@ The absolute maximum multiplier points that some balance could have, using the m period. This can be used to limit the extension on the lock time. $$ -mp_\mathcal{M}^{abs} = a_{bal} + \left( \dfrac{a_{bal} \times T_{max} \times MP_{APY}}{T_{YEAR} \times 100} \right) + a_{bal} \times M_{max} +mp_\mathcal{M} = a_{bal} \times \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) $$ #### Locked Time ($t_{lock}$) @@ -765,3 +783,11 @@ $$ \hat{\mathcal{f}}\tilde{t}_{\text{lock}}(mp_{\mathcal{M}}, a_{\text{bal}}) &\approx \left\lceil \frac{(mp_{\mathcal{M}} - a_{\text{bal}}) \times 100 \times T_{\text{YEAR}}}{a_{\text{bal}} \times MP_{\text{APY}}} - M_{\text{MAX}} \times T_{\text{YEAR}} \right\rceil \end{align} $$ + +#### Remaining Time Lock Allowed to Increase + +Retrieves how much time lock can be incrased + +$$ +t_{lock}^{max,rem} = \left( \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) - \dfrac{mp_{\mathcal{M}}}{a_{bal}} \right) \times \dfrac{100 \times T_{YEAR}}{MP_{APY}} +$$ From efd037594896ee6183dedf4284dbb610d778c187 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Thu, 31 Oct 2024 12:07:59 -0300 Subject: [PATCH 13/23] chore(MathSpeck.md): grammar correction --- docs/MathSpec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 3de8743..ba701dc 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -786,7 +786,7 @@ $$ #### Remaining Time Lock Allowed to Increase -Retrieves how much time lock can be incrased +Retrieves how much time lock can be increased $$ t_{lock}^{max,rem} = \left( \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) - \dfrac{mp_{\mathcal{M}}}{a_{bal}} \right) \times \dfrac{100 \times T_{YEAR}}{MP_{APY}} From 7fdd7e6c3d72994d391f3ada1d635a8a48d4a0d7 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 4 Nov 2024 12:45:09 -0300 Subject: [PATCH 14/23] chore(MathSpec.md): add ignore for prettier on GitHub Callouts --- docs/MathSpec.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index ba701dc..5dfd52e 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -1,6 +1,8 @@ ## Mathematical Specification of Staking Protocol -> [!IMPORTANT] All values in this document are expressed as unsigned integers. + +> [!IMPORTANT] +> All values in this document are expressed as unsigned integers. ### Summary @@ -239,7 +241,9 @@ $$ ### Pure Mathematical Functions -> [!NOTE] This function definitions represent direct mathematical input -> output methods, which don't change state. + +> [!NOTE] +> This function definitions represent direct mathematical input -> output methods, which don't change state. #### Definition: $\mathcal{f}{mp_\mathcal{I}}(\Delta a) \longrightarrow$ Initial Multiplier Points @@ -483,7 +487,9 @@ $$ #### Definition: $\mathcal{f}^{lock}(\mathbb{Account}, t_{lock}) \longrightarrow$ Increase Lock -> [!NOTE] Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ + +> [!NOTE] +> Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ _Purpose:_ Allows a user to lock the $\mathbb{Account} \cdot a_{bal}$ with a lock duration $t_{lock}$. @@ -752,8 +758,9 @@ $$ #### Maximum Total Multiplier Points -> [!NOTE] The maximum total multiplier points that can be generated for a determined amount of balance and lock -> duration. + +> [!NOTE] +> The maximum total multiplier points that can be generated for a determined amount of balance and lock duration. $\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) + \mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) + \mathcal{f}mp_\mathcal{I}(\Delta a)$ $\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \left(\dfrac{\Delta a \times (M_{MAX} \times T_{YEAR}) \times MP_{APY}}{T_{YEAR} \times 100}\right) + \left( \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{T_{YEAR} \times 100} \right)+ \Delta a$ @@ -773,8 +780,9 @@ $$ #### Locked Time ($t_{lock}$) -> [!CAUTION] This value is estimated and can be incorrect due precision loss, rounding up mostly helps with this but -> it's not guaranteed. + +> [!CAUTION] +> This value is estimated and can be incorrect due precision loss, rounding up mostly helps with this but it's not guaranteed. Estimates the time an account set as locked time. This can be used to limit the extension on the lock time. From f5abcf43db7a8f7d1e71a7be8ad4f9dfc55e8514 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 11 Nov 2024 12:01:19 -0300 Subject: [PATCH 15/23] chore(MathSpec.md): implement MPY, and revisit view formulas --- docs/MathSpec.md | 103 ++++++++++++++++++++++++++++------------------- 1 file changed, 61 insertions(+), 42 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 5dfd52e..cda1d58 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -8,18 +8,19 @@ ### Constants -| Symbol | Source | Value | Unit | Description | -| ----------------- | ------------------------------------------------------------------- | ----------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- | -| $T_{DAY}$ | | 86400 | seconds | One day. | -| $T_{YEAR}$ | $\lfloor365.242190 \times T_{DAY}\rfloor$ | 31556925 | seconds | One (mean) tropical year. | -| $SCALE_{FACTOR}$ | | $\pu{1 \times 10^{18}}$ | (1) | Scaling factor to maintain precision in calculations. | -| $T_{RATE}$ | (minimal blocktime) | 12 | seconds | The accrue rate period of time over which multiplier points are calculated. | -| $MP_{APY}$ | | $\pu{100\%}$ | percent | Annual percentage yield for multiplier points. | -| $M_{MAX}$ | | $\pu{4 \mathrm{(1)}}$ | (1) | Maximum multiplier points to be accrued. | -| $A_{MIN}$ | $\lceil\tfrac{T_{YEAR} \times 100}{T_{RATE} \times MP_{APY}}\rceil$ | 2629744 | tokens per period | Minimal value to generate 1 multiplier point in the accrue rate period ($T_{RATE}$). ($A_{MIN} \propto T_{RATE}$) | -| $T_{MIN}$ | $90 \times T_{DAY}$ | 7776000 | seconds | Minimum lockup period, equivalent to 90 days. | -| $T_{MAX_{YEARS}}$ | | 4 | years | Maximum of lockup period (in years). | -| $T_{MAX}$ | $T_{MAX_{YEARS}} \times T_{YEAR}$ | 126227700 | seconds | Maximum of lockup period. | +| Symbol | Source | Value | Unit | Description | +| --------------------------- | ----------------------------------------------------------------------- | ----------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- | +| $SCALE_{FACTOR}$ | | $\pu{1 \times 10^{18}}$ | (1) | Scaling factor to maintain precision in calculations. | +| $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_{\text{MAX}} \times \mathtt{APY})$ | 900 | percent | Multiplier points absolute maximum percentage yield | +| $T_{RATE}$ | (minimal blocktime) | 12 | seconds | | +| $T_{DAY}$ | | 86400 | seconds | One day. | +| $T_{YEAR}$ | $\lfloor365.242190 \times T_{DAY}\rfloor$ | 31556925 | seconds | One (mean) tropical year. | +| $A_{MIN}$ | $\lceil\tfrac{T_{YEAR} \times 100}{T_{RATE} \times \mathtt{APY}}\rceil$ | 2629744 | tokens per period | Minimal value to generate 1 multiplier point in the accrue rate period ($T_{RATE}$). ($A_{MIN} \propto T_{RATE}$) | +| $T_{MIN}$ | $90 \times T_{DAY}$ | 7776000 | seconds | Minimum lockup period, equivalent to 90 days. | +| $T_{MAX}$ | $M_{MAX} \times T_{YEAR}$ | 126227700 | seconds | Maximum of lockup period. | ### Variables @@ -61,7 +62,7 @@ Seconds $a_{bal}$ remains locked, expressed as: $$ \begin{align} &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ -\text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le T_{MAX}\end{align} +\text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le (M_{MAX} \times T_{YEAR})\end{align} $$ --- @@ -110,7 +111,7 @@ The value of $t_{last}$ is updated by all functions that change state: Maximum value that $mp_\Sigma$ can reach. -Relates as $mp_\mathcal{M} \propto a_{bal} \cdot (t_{lock} + M_{MAX})$. +Relates as $mp_\mathcal{M} \propto a_{bal} \cdot (t_{lock} + \mathsf{MPY})$. Altered by functions that change the account state: @@ -267,12 +268,12 @@ Where #### Definition: $\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 $MP_{APY}$. +**$a_{bal}$** and the annual percentage yield $\mathtt{APY}$. $$ \boxed{ \begin{equation} - \mathcal{f}mp_\mathcal{A}(a_{bal}, \Delta t) = \dfrac{a_{bal} \times \Delta t \times MP_{APY}}{100 \times T_{YEAR}} + \mathcal{f}mp_\mathcal{A}(a_{bal}, \Delta t) = \dfrac{a_{bal} \times \Delta t \times \mathtt{APY}}{100 \times T_{YEAR}} \end{equation} } $$ @@ -284,7 +285,7 @@ Where same time units as the year (typically days or months). - **$T_{YEAR}$**: A constant representing the duration of a full year, used to normalize the time difference **$\Delta t$**. -- **$MP_{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance +- **$\mathtt{APY}$**: The Annual Percentage Yield (APY) expressed as a percentage, which determines how much the balance grows over a year. --- @@ -300,7 +301,7 @@ $$ &\mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock}) \\ &\boxed{ \begin{equation} - \mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{100 \times T_{YEAR}} + \mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) = \dfrac{\Delta a \times t_{lock} \times \mathtt{APY}}{100 \times T_{YEAR}} \end{equation} } \end{aligned} @@ -312,8 +313,8 @@ Where: - **$t_{lock}$**: The duration for which the balance **$\Delta a$** is locked, measured in units of seconds. - **$T_{YEAR}$**: A constant representing the length of a year, used to normalize the lock period **$t_{lock}$** as a fraction of a full year. -- **$MP_{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest rate - applied to the locked balance. +- **$\mathtt{APY}$**: The Annual Percentage Yield (APY), expressed as a percentage, which indicates the yearly interest + rate applied to the locked balance. --- @@ -434,7 +435,7 @@ Ensure the New Maximum MPs ($\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\ Maximum MPs: $$ -\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} \le a_{bal} \times \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) +\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} \le \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} $$ ###### Update account State @@ -542,7 +543,9 @@ Ensure the New Maximum MPs ($\mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat Absolute Maximum MPs: $$ -\mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B} \le a_{bal} \times \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) +\mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B} \le \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} + + $$ ###### Update account State @@ -754,48 +757,64 @@ $$ --- -### View Functions +### Support Functions #### Maximum Total Multiplier Points - -> [!NOTE] -> The maximum total multiplier points that can be generated for a determined amount of balance and lock duration. +The maximum total multiplier points that can be generated for a determined amount of balance and lock duration. -$\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \mathcal{f}mp_\mathcal{A}(\Delta a, M_{MAX} \times T_{YEAR}) + \mathcal{f}mp_\mathcal{B}(\Delta a, t_{lock}) + \mathcal{f}mp_\mathcal{I}(\Delta a)$ -$\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \left(\dfrac{\Delta a \times (M_{MAX} \times T_{YEAR}) \times MP_{APY}}{T_{YEAR} \times 100}\right) + \left( \dfrac{\Delta a \times t_{lock} \times MP_{APY}}{T_{YEAR} \times 100} \right)+ \Delta a$ +$$ +\boxed{\hat{\mathcal{f}}mp_{\mathcal{M}}(a_{bal}, t_{\text{lock}}) = a_{bal} + \frac{a_{bal} \times \mathtt{APY} \times \left( M_{\text{MAX}} \times T_{\text{YEAR}} + t_{\text{lock}} \right)}{100 \times T_{\text{YEAR}}}} +$$ + +#### Maximum Accrued Multiplier Points + +The maximum multiplier points that can be accrued over time for a determined amount of balance. $$ -\boxed{\hat{\mathcal{f}}mp_\mathcal{M}(\Delta a, t_{lock}) = \dfrac{\Delta a \times MP_{APY}}{100} \times \left(M_{MAX} + \dfrac{t_{lock}}{T_{YEAR}}\right) + \Delta a} +\boxed{\hat{\mathcal{f}}mp_\Sigma^{max}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}}{100}} $$ -#### Absolute Maximum Multiplier Points +#### Maximum Absolute Multiplier Points -The absolute maximum multiplier points that some balance could have, using the maximum lock time and maximum accrual -period. This can be used to limit the extension on the lock time. +The absolute maximum multiplier points that some balance could have, which is the sum of the bonus with maximum lockup +time and the maximum accrued multiplier points. $$ -mp_\mathcal{M} = a_{bal} \times \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) +\boxed{\hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100}} $$ #### Locked Time ($t_{lock}$) - -> [!CAUTION] -> This value is estimated and can be incorrect due precision loss, rounding up mostly helps with this but it's not guaranteed. +> [!CAUTION] If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an +> approximation. -Estimates the time an account set as locked time. This can be used to limit the extension on the lock time. +Estimates the time an account set as locked time. $$ -\begin{align} -\hat{\mathcal{f}}\tilde{t}_{\text{lock}}(mp_{\mathcal{M}}, a_{\text{bal}}) &\approx \left\lceil \frac{(mp_{\mathcal{M}} - a_{\text{bal}}) \times 100 \times T_{\text{YEAR}}}{a_{\text{bal}} \times MP_{\text{APY}}} - M_{\text{MAX}} \times T_{\text{YEAR}} \right\rceil -\end{align} +\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{YEAR}} \times M_{\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 Allowed to Increase -Retrieves how much time lock can be increased +> [!CAUTION] If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an +> approximation. + +Retrieves how much time lock can be increased for an account. $$ -t_{lock}^{max,rem} = \left( \left( 1 + \dfrac{T_{MAX_{YEAR}} \times MP_{APY}}{100} + M_{MAX} \right) - \dfrac{mp_{\mathcal{M}}}{a_{bal}} \right) \times \dfrac{100 \times T_{YEAR}}{MP_{APY}} +\boxed{ + \begin{equation} + t_{lock}^{rem}(a_{bal},mp_\mathcal{M}) \approx \frac{(\frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} - mp_\mathcal{M})\times T_{YEAR}}{a_{bal}} + \end{equation} +} $$ From 315ff9951e942d61305057879faac0771e5c6908 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 11 Nov 2024 12:30:03 -0300 Subject: [PATCH 16/23] chore(MathSpec.md): fix mess made by linter. --- docs/MathSpec.md | 66 +++++++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index cda1d58..227ce80 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -61,8 +61,10 @@ The current timestamp seconds since the Unix epoch (January 1, 1970). Seconds $a_{bal}$ remains locked, expressed as: $$ -\begin{align} &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ -\text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le (M_{MAX} \times T_{YEAR})\end{align} +\begin{align} + &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ + \text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le (M_{MAX} \times T_{YEAR}) +\end{align} $$ --- @@ -125,10 +127,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} $$ @@ -136,9 +138,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} $$ @@ -170,16 +172,16 @@ 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} $$ @@ -209,14 +211,16 @@ Defined as following: $$ \begin{gather} -\mathbb{Account} \\ -\overbrace{\begin{align} -a_{bal} & : \text{balance}, \\ -t_{lock,end} & : \text{lock end}, \\ -t_{last} & : \text{last accrual}, \\ -mp_\Sigma & : \text{total MPs}, \\ -mp_\mathcal{M} & : \text{maximum MPs} -\end{align}} + \mathbb{Account} \\ + \overbrace{ + \begin{align} + a_{bal} & : \text{balance}, \\ + t_{lock,end} & : \text{lock end}, \\ + t_{last} & : \text{last accrual}, \\ + mp_\Sigma & : \text{total MPs}, \\ + mp_\mathcal{M} & : \text{maximum MPs} + \end{align} + } \end{gather} $$ @@ -228,13 +232,15 @@ Defined as following: $$ \begin{gather} - \mathbb{System} \\ -\overbrace{\begin{align} -\mathbb{Account}\mathrm{[]} & : \text{accounts}, \\ -a_{bal} & : \text{total staked}, \\ -mp_\Sigma & : \text{MP supply}, \\ -mp_\mathcal{M} & : \text{MP supply max} -\end{align}} + \mathbb{System} \\ + \overbrace{ + \begin{align} + \mathbb{Account}\mathrm{[]} & : \text{accounts}, \\ + a_{bal} & : \text{total staked}, \\ + mp_\Sigma & : \text{MP supply}, \\ + mp_\mathcal{M} & : \text{MP supply max} + \end{align} + } \end{gather} $$ @@ -490,7 +496,7 @@ $$ > [!NOTE] -> Equivalent to $\mathcal{f}_{stake}(\mathbb{Account},0, t_{lock})$ +> Equivalent to calling stake function with amount 0. _Purpose:_ Allows a user to lock the $\mathbb{Account} \cdot a_{bal}$ with a lock duration $t_{lock}$. @@ -544,8 +550,6 @@ Absolute Maximum MPs: $$ \mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B} \le \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} - - $$ ###### Update account State From 5c884e7a3c99fa6f0f93ea3e89562b5adbc2f3e8 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 11 Nov 2024 12:33:54 -0300 Subject: [PATCH 17/23] chore(MathSpec.md): fix other problem caused by linter --- docs/MathSpec.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 227ce80..d71bbc3 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -768,7 +768,9 @@ $$ The maximum total multiplier points that can be generated for a determined amount of balance and lock duration. $$ -\boxed{\hat{\mathcal{f}}mp_{\mathcal{M}}(a_{bal}, t_{\text{lock}}) = a_{bal} + \frac{a_{bal} \times \mathtt{APY} \times \left( M_{\text{MAX}} \times T_{\text{YEAR}} + t_{\text{lock}} \right)}{100 \times T_{\text{YEAR}}}} +\boxed{ + \hat{\mathcal{f}}mp_{\mathcal{M}}(a_{bal}, t_{\text{lock}}) = a_{bal} + \frac{a_{bal} \times \mathtt{APY} \times \left( M_{\text{MAX}} \times T_{\text{YEAR}} + t_{\text{lock}} \right)}{100 \times T_{\text{YEAR}}} +} $$ #### Maximum Accrued Multiplier Points @@ -776,7 +778,9 @@ $$ The maximum multiplier points that can be accrued over time for a determined amount of balance. $$ -\boxed{\hat{\mathcal{f}}mp_\Sigma^{max}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}}{100}} +\boxed{ + \hat{\mathcal{f}}mp_\Sigma^{max}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}}{100} +} $$ #### Maximum Absolute Multiplier Points @@ -785,12 +789,16 @@ The absolute maximum multiplier points that some balance could have, which is th time and the maximum accrued multiplier points. $$ -\boxed{\hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100}} +\boxed{ + \hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} +} $$ #### Locked Time ($t_{lock}$) -> [!CAUTION] If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an + +> [!CAUTION] +> If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an > approximation. Estimates the time an account set as locked time. @@ -810,7 +818,9 @@ Where: #### Remaining Time Lock Allowed to Increase -> [!CAUTION] If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an + +> [!CAUTION] +> If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an > approximation. Retrieves how much time lock can be increased for an account. From ff516c66e0dc9828c6d316dd77c20cf60af6f83e Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 11 Nov 2024 12:36:08 -0300 Subject: [PATCH 18/23] chore(MathSpec.md): try fix github interpretation of latex --- docs/MathSpec.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index d71bbc3..099350b 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -805,9 +805,7 @@ 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{YEAR}} \times M_{\text{MAX}} - \end{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{YEAR}} \times M_{\text{MAX}} } $$ @@ -827,8 +825,6 @@ Retrieves how much time lock can be increased for an account. $$ \boxed{ - \begin{equation} - t_{lock}^{rem}(a_{bal},mp_\mathcal{M}) \approx \frac{(\frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} - mp_\mathcal{M})\times T_{YEAR}}{a_{bal}} - \end{equation} + t_{lock}^{rem}(a_{bal},mp_\mathcal{M}) \approx \frac{(\frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} - mp_\mathcal{M})\times T_{YEAR}}{a_{bal}} } $$ From d3c1a35344ca2ecf90266aa250725ca1a236fd7f Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 11 Nov 2024 12:48:47 -0300 Subject: [PATCH 19/23] chore(MathSpec.md): adapt latex to work with github --- docs/MathSpec.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 099350b..dcf3bc3 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -14,7 +14,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_{\text{MAX}} \times \mathtt{APY})$ | 900 | percent | Multiplier points absolute maximum percentage yield | +| $\mathsf{MPY}^\mathit{abs}$ | $100 + (2 \times M_{MAX} \times \mathtt{APY})$ | 900 | percent | Multiplier points absolute maximum percentage yield | | $T_{RATE}$ | (minimal blocktime) | 12 | seconds | | | $T_{DAY}$ | | 86400 | seconds | One day. | | $T_{YEAR}$ | $\lfloor365.242190 \times T_{DAY}\rfloor$ | 31556925 | seconds | One (mean) tropical year. | @@ -441,7 +441,7 @@ Ensure the New Maximum MPs ($\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\ Maximum MPs: $$ -\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} \le \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} +\mathbb{Account} \cdot mp_\mathcal{M} + \Delta mp_\mathcal{M} \le \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100} $$ ###### Update account State @@ -549,7 +549,7 @@ Ensure the New Maximum MPs ($\mathbb{Account} \cdot mp_\mathcal{M} + \Delta \hat 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{Account} \cdot mp_\mathcal{M} + \Delta \hat{mp}^\mathcal{B} \le \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100} $$ ###### Update account State @@ -769,7 +769,7 @@ The maximum total multiplier points that can be generated for a determined amoun $$ \boxed{ - \hat{\mathcal{f}}mp_{\mathcal{M}}(a_{bal}, t_{\text{lock}}) = a_{bal} + \frac{a_{bal} \times \mathtt{APY} \times \left( M_{\text{MAX}} \times T_{\text{YEAR}} + t_{\text{lock}} \right)}{100 \times T_{\text{YEAR}}} + \hat{\mathcal{f}}mp_{\mathcal{M}}(a_{bal}, t_{lock}) = a_{bal} + \frac{a_{bal} \times \mathtt{APY} \times \left( M_{MAX} \times T_{YEAR} + t_{lock} \right)}{100 \times T_{YEAR}} } $$ @@ -790,7 +790,7 @@ time and the maximum accrued multiplier points. $$ \boxed{ - \hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} + \hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100} } $$ @@ -805,7 +805,9 @@ Estimates the time an account set as locked time. $$ \boxed{ - \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{YEAR}} \times M_{\text{MAX}} + \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_{YEAR} \times M_{MAX} + \end{equation} } $$ @@ -825,6 +827,8 @@ Retrieves how much time lock can be increased for an account. $$ \boxed{ - t_{lock}^{rem}(a_{bal},mp_\mathcal{M}) \approx \frac{(\frac{a_{bal} \times \mathsf{MPY}_\mathit{abs}}{100} - mp_\mathcal{M})\times T_{YEAR}}{a_{bal}} + \begin{equation} + t_{lock}^{rem}(a_{bal},mp_\mathcal{M}) \approx \frac{(\frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100} - mp_\mathcal{M})\times T_{YEAR}}{a_{bal}} + \end{equation} } $$ From 79100fccee16808b774370b4c41d2fc5689d314c Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 25 Nov 2024 12:30:51 -0300 Subject: [PATCH 20/23] chore(MathSpec.md): add support functions, add links --- docs/MathSpec.md | 119 ++++++++++++++++++++++++++++++----------------- 1 file changed, 77 insertions(+), 42 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index dcf3bc3..ace6d59 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -13,12 +13,13 @@ | $SCALE_{FACTOR}$ | | $\pu{1 \times 10^{18}}$ | (1) | Scaling factor to maintain precision in calculations. | | $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 | -| $T_{RATE}$ | (minimal blocktime) | 12 | seconds | | +| $\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. | +| $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. | | $A_{MIN}$ | $\lceil\tfrac{T_{YEAR} \times 100}{T_{RATE} \times \mathtt{APY}}\rceil$ | 2629744 | tokens per period | Minimal value to generate 1 multiplier point in the accrue rate period ($T_{RATE}$). ($A_{MIN} \propto T_{RATE}$) | +| $A_{MAX}$ | $\frac{2^{256} - 1}{\text{APY} \times T_{\text{RATE}}}$ | | tokens per period | Maximum value to not overflow unsigned integer of 256 bits. | | $T_{MIN}$ | $90 \times T_{DAY}$ | 7776000 | seconds | Minimum lockup period, equivalent to 90 days. | | $T_{MAX}$ | $M_{MAX} \times T_{YEAR}$ | 126227700 | seconds | Maximum of lockup period. | @@ -61,10 +62,8 @@ The current timestamp seconds since the Unix epoch (January 1, 1970). Seconds $a_{bal}$ remains locked, expressed as: $$ -\begin{align} - &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ - \text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le (M_{MAX} \times T_{YEAR}) -\end{align} +\begin{align} &t_{lock, \Delta} = max(t_{lock,end},t_{now}) - t_{now} \\ +\text{ where: }\quad & t_{lock, \Delta} = 0\text{ or }T_{MIN} \le t_{lock, \Delta} \le (M_{MAX} \times T_{YEAR})\end{align} $$ --- @@ -162,10 +161,10 @@ $$ Altered by all functions that change 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)$; -- $f^{accrue}(\mathbb{Account}, a_{bal},\Delta t)$. +- [[#$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]]. The state can be expressed as the following state changes: @@ -252,7 +251,7 @@ $$ > [!NOTE] > This function definitions represent direct mathematical input -> output methods, which don't change state. -#### Definition: $\mathcal{f}{mp_\mathcal{I}}(\Delta a) \longrightarrow$ Initial Multiplier Points +#### $\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. @@ -271,7 +270,7 @@ Where --- -#### Definition: $\mathcal{f}{mp_\mathcal{A}}(a_{bal}, \Delta t) \longrightarrow$ Accrue Multiplier Points +#### $\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}$. @@ -296,11 +295,10 @@ Where --- -#### Definition: $\mathcal{f}{mp_\mathcal{B}}(\Delta A, t_{lock}) \longrightarrow$ Bonus Multiplier Points +#### $\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 accrued multiplier points function -$\mathcal{f}mp_\mathcal{A}(\Delta a, t_{lock})$ but specifically applied in the context of a locked balance. +**$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}$]]. $$ \begin{aligned} @@ -324,7 +322,7 @@ Where: --- -#### Definition: $\mathcal{f}{mp_\mathcal{R}}(mp, a_{bal}, \Delta a) \longrightarrow$ Reduce Multiplier Points +#### $\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, @@ -352,7 +350,7 @@ These function definitions represent methods that modify the state of both **$\m **$\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. -#### Definition: $\mathcal{f}^{stake}(\mathbb{Account},\Delta A, t_{lock}) \longrightarrow$ Stake Amount With Lock +#### $\mathcal{f}^{stake}(\mathbb{Account},\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}$. @@ -387,14 +385,13 @@ flowchart LR ###### Accrue Existing Multiplier Points (MPs) -Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ 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} $$ - ###### Verify Constraints Ensure new balance ($a_{bal}$ + $\Delta a$) meets the minimum amount ($A_{MIN}$): @@ -409,6 +406,7 @@ $$ \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}$): @@ -435,6 +433,7 @@ $$ \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 @@ -492,7 +491,7 @@ $$ --- -#### Definition: $\mathcal{f}^{lock}(\mathbb{Account}, t_{lock}) \longrightarrow$ Increase Lock +#### $\mathcal{f}^{lock}(\mathbb{Account}, t_{lock}) \longrightarrow$ Increase Lock > [!NOTE] @@ -521,7 +520,7 @@ flowchart LR ###### Accrue Existing Multiplier Points (MPs) -Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ 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}$) @@ -588,7 +587,7 @@ $$ --- -#### Definition: $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a) \longrightarrow$ Unstake Amount Unlocked +#### $\mathcal{f}^{unstake}(\mathbb{Account}, \Delta a) \longrightarrow$ Unstake Amount Unlocked Purpose: Allows a user to unstake an amount $\Delta a$. @@ -613,7 +612,7 @@ flowchart LR ###### Accrue Existing Multiplier Points (MPs) -Call the $\mathcal{f}_{accrue}(\mathbb{Account})$ 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 @@ -691,7 +690,7 @@ $$ --- -#### Definition: $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points +#### $\mathcal{f}^{accrue}(\mathbb{Account}) \longrightarrow$ Accrue Multiplier Points Purpose: Accrue multiplier points (MPs) for the account based on the elapsed time since the last accrual. @@ -769,55 +768,91 @@ The maximum total multiplier points that can be generated for a determined amoun $$ \boxed{ - \hat{\mathcal{f}}mp_{\mathcal{M}}(a_{bal}, t_{lock}) = a_{bal} + \frac{a_{bal} \times \mathtt{APY} \times \left( M_{MAX} \times T_{YEAR} + t_{lock} \right)}{100 \times T_{YEAR}} + \begin{equation} + \hat{\mathcal{f}}mp_{\mathcal{M}}(a_{bal}, t_{\text{lock}}) = a_{bal} + \frac{a_{bal} \times \mathtt{APY} \times \left( T_{\text{MAX}} + t_{\text{lock}} \right)}{100 \times T_{\text{YEAR}}} + \end{equation} } $$ + #### 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}$ $$ \boxed{ - \hat{\mathcal{f}}mp_\Sigma^{max}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}}{100} + \begin{equation} + \hat{\mathcal{f}}mp_{A}^{max}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}}{100} + \end{equation} } $$ - #### Maximum Absolute Multiplier Points -The absolute maximum multiplier points that some balance could have, which is the sum of the bonus with maximum lockup -time 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{ - \hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100} + \begin{equation} + \hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) = \frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100} + \end{equation} } $$ -#### Locked Time ($t_{lock}$) - -> [!CAUTION] -> If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an -> approximation. +#### Retrieve Bonus Multiplier Points +Returns the Bonus Multiplier Points from the Maximum Multiplier Points and Balance. + +$$ +\boxed{ +\begin{equation} +\hat{\mathcal{f}}\hat{mp}^\mathcal{B}(mp_\mathcal{M}, a_{bal}) = mp_\mathcal{M} - \left(a_{\text{bal}} + \hat{\mathcal{f}}mp_{A}^{max}(a_{bal}) \right) +\end{equation} +} +$$ + + +#### Retrieve Accrued Multiplier Points +Returns the accrued multiplier points from Total Multiplier Points, Maximum Multiplier Points and Balance. -Estimates the time an account set as locked time. +$$ +\boxed{ +\begin{equation} +\hat{\mathcal{f}}\hat{mp}^\mathcal{A}(mp_\Sigma, mp_\mathcal{M}, a_{bal}) = mp_\Sigma + \hat{\mathcal{f}}mp_{A}^{max}(a_{bal}) - mp_\mathcal{M} +\end{equation} +} +$$ + +#### Time to Accrue Multiplier Points +Retrieves how much seconds to a certain $a_{bal}$ would reach a certain $mp$ $$ \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_{YEAR} \times M_{MAX} + 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}$) + +> [!CAUTION] +> Use for reference only. If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, the result may be an approximation. -Where: +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}} + \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 Allowed to Increase - +#### Remaining Time Lock Available to Increase > [!CAUTION] > If implemented with integers, for $a_{bal} < T_{YEAR}$, due precision loss, this values will be an @@ -828,7 +863,7 @@ Retrieves how much time lock can be increased for an account. $$ \boxed{ \begin{equation} - t_{lock}^{rem}(a_{bal},mp_\mathcal{M}) \approx \frac{(\frac{a_{bal} \times \mathsf{MPY}^\mathit{abs}}{100} - mp_\mathcal{M})\times T_{YEAR}}{a_{bal}} + t_{rem}^{lock}(a_{bal},mp_\mathcal{M}) \approx \frac{\left(\hat{\mathcal{f}}mp_\mathcal{M}^\mathit{abs}(a_{bal}) - mp_\mathcal{M}\right)\times T_{YEAR}}{a_{bal}} \end{equation} } $$ From 33c0431ec2cf0123a54218e02677552cd7c77e00 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Mon, 9 Dec 2024 12:18:57 -0300 Subject: [PATCH 21/23] docs(ScalableRewardDistribution): WIP Specification of the Scalable Reward Distribution --- docs/ScalableRewardDistribution.md | 216 +++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 docs/ScalableRewardDistribution.md diff --git a/docs/ScalableRewardDistribution.md b/docs/ScalableRewardDistribution.md new file mode 100644 index 0000000..ab30de7 --- /dev/null +++ b/docs/ScalableRewardDistribution.md @@ -0,0 +1,216 @@ +### Reward Distribution Formulas + + +> [!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. + From 624bf803e24aebdcde8e546c7392282efdf30f2a Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Sat, 21 Dec 2024 00:54:15 -0300 Subject: [PATCH 22/23] chore(MathSpec.md): Merge ScalableRewardDistribution.md with MathSpec, fix formatting for GitHub Markdown --- docs/MathSpec.md | 409 +++++++++++++++++++++-------- docs/ScalableRewardDistribution.md | 216 --------------- 2 files changed, 302 insertions(+), 323 deletions(-) delete mode 100644 docs/ScalableRewardDistribution.md diff --git a/docs/MathSpec.md b/docs/MathSpec.md index ace6d59..44e4da1 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -1,3 +1,5 @@ +## Table of Contents + ## Mathematical Specification of Staking Protocol @@ -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 @@ -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 > [!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}$) + > [!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 + -> [!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. diff --git a/docs/ScalableRewardDistribution.md b/docs/ScalableRewardDistribution.md deleted file mode 100644 index ab30de7..0000000 --- a/docs/ScalableRewardDistribution.md +++ /dev/null @@ -1,216 +0,0 @@ -### Reward Distribution Formulas - - -> [!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. - From ac49a4af5d7073d9f92a63f67ed0e58f9eccbbc3 Mon Sep 17 00:00:00 2001 From: Ricardo Guilherme Schmidt <3esmit@gmail.com> Date: Sat, 21 Dec 2024 01:13:56 -0300 Subject: [PATCH 23/23] chore(MathSpec.md): Lint write --- docs/MathSpec.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/MathSpec.md b/docs/MathSpec.md index 44e4da1..6b13ade 100644 --- a/docs/MathSpec.md +++ b/docs/MathSpec.md @@ -965,9 +965,9 @@ $$ #### 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 = 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{