add parameter contraints

tips/TIP-0040/constraints.md

@@ -0,0 +1,187 @@
+# Parameters constraints
+
+Due to the use of fixed point arithmetics, some contraints on the rewards parameters are needed to prevent overflowing of the variables used for the calculations.
+
+## Constraints on the Mana Supply
+
+The first and most straighforward contraint is that the total maximum theoretical Mana in the system should not use more than $\text{Bits Count}$ bits.
+
+Let's start by calculating the Mana in the system generated by holding tokens $\text{Mana Holders}(n)$ until epoch $n$.
+
+$$
+ \text{Mana Holders}(n)=\frac{\text{Token Supply}*\text{Generation Rate}}{1-\text{Decay per Epoch}}* 2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}} (1-\text{Decay per Epoch}^{n+1})
+$$
+with $\text{Decay per Epoch}=\text{Decay per Year}^{\frac{\text{Seconds per Epoch}}{\text{Seconds per Year}}}$.
+
+The maximum Mana in the system generated by holding tokens $\text{Max Mana Holders}$ is equivalent to the potential Mana generated by an output holding $\text{Token Supply}$ IOTA coins until epoch $n$, for $n$ large enough. This results:
+
+$$
+\begin{align*}
+\text{Max Mana Holders} = \frac{\text{Token Supply}*\text{Generation Rate}}{1-\text{Decay per Epoch}}2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}}
+\end{align*}
+$$
+
+We denote by $\text{Max Reward Rate}(n) = \text{Max to Target Ratio} * \text{Target Rewards Rate}(n)$ the theoretical maximum reward distributed at epoch $n$.
+In the case of fixed or top stakers based committees, the actual reward distributed per epoch is at most $\text{Target Rewards Rate}(n)$, i.e., $\text{Max to Target Ratio} = 1$.
+For random committees, see [Random committees](#random-committees).
+
+### Mana Supply in the bootstrapping Phase
+
+In the bootstrapping Phase, the target reward decreases each epoch until reaching $\text{Final Target Rewards Rate}$.
+The maximum amount of Mana distributed as rewards until epoch $n$ is:
+
+$$
+\sum_{i=1}^{n} \text{Decay}(\text{Max Reward Rate}(i),n-i)
+$$
+
+Since $\text{Max Reward Rate}(i)$ is proportional to the epoch target reward, this is equivalent to
+
+$$
+\begin{align*}
+&\sum_{i=1}^{n} \text{Decay}(\text{Decay}(\text{Max Reward Rate}(1),i-1),n-i)\\
+=&n \text{Decay}(\text{Max Reward Rate}(1),n-1)\\
+=&n \text{Decay per Epoch}^{n-1}  \text{Max Reward Rate}(1)
+\end{align*}
+$$
+
+<!---
+the function above is increasing if $m\leq \frac{-1}{\log(\text{Decay per Epoch})}$ and decreasing otherwise (i.e., it is a concave function). However, since the `Bootstrapping Duration` is set such that $\text{Bootstrapping Duration in Years}*\text{Decay per Year}=1$, we have that $\text{Bootstrapping Duration in Years} = \frac{1}{\text{Decay per Year}}<\frac{-1}{\log(\text{Decay per Year})}$, whenever $\text{Decay per year}>0.57$. Then, the maximum amount of Mana distributed as rewards in the bootstrapping Phase is achieved at `Bootstrapping Duration`, i.e., the maximum is
+
+$$
+\begin{align*}
+\frac{\text{Epochs per year}}{\text{Decay per Year}} \text{Max to Target Ratio}*\text{Final Target Rewards Rate}
+\end{align*}
+$$
+-->
+
+the function above is increasing if $n\leq \frac{-1}{\log(\text{Decay per Epoch})}$ and decreasing otherwise (i.e., it is a concave function). However, since the $\text{Bootstrapping Duration}$ is set such that $\text{Bootstrapping Duration in Years}*\text{Beta per Year}=1$, we have that $\text{Bootstrapping Duration in Years} = \frac{1}{\text{Beta per Year}}=\frac{-1}{\log(\text{Decay per Year})}$. Then, the maximum amount of Mana distributed as rewards in the bootstrapping Phase is achieved at $\text{Bootstrapping Duration}$, i.e., the maximum is
+
+$$
+\begin{align*}
+&\text{Max Mana Supply Bootstrapping}\\
+&=\frac{1}{-\log(\text{Decay per Epoch})}* \text{Max to Target Ratio}*\text{Final Target Rewards Rate}
+\end{align*}
+$$
+
+By definition, we have that $\text{Final Target Rewards Rate}$ is
+
+$$
+\begin{align*}
+&\text{Final Target Rewards Rate}=\text{Token Supply}*\text{Reward To Generation Ratio}\\
+*&\text{Generation Rate}*2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}}
+\end{align*}
+$$
+
+Then, the Maximum Mana supply in the bootstrapping phase is
+
+<!---
+$$
+\begin{align*}
+&\text{Token Supply}*\text{Generation Rate}*2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}}\\
+&*\left(\text{Reward To Generation Ratio}\right.\\
+&*\frac{\text{Epochs per year}}{\text{Decay per Year}} \text{Max to Target Ratio}\\
++&\left.\frac{1}{1-\text{Decay per Epoch}}\right)\\
+&\leq \text{Token Supply}*\text{Generation Rate}*2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}}\\
+&\frac{1+\text{Reward To Generation Ratio}*\text{Max to Target Ratio}}{1-\text{Decay per Epoch}}
+\end{align*}
+$$
+-->
+
+$$
+\begin{align*}
+&\text{Max Mana Supply Bootstrapping}\\
+&=\text{Token Supply}*\text{Generation Rate}*2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}}\\
+&\left(\text{Reward To Generation Ratio}*\frac{1}{-\log(\text{Decay per Epoch})}* \text{Max to Target Ratio}\right.\\
++&\left.\frac{1}{1-\text{Decay per Epoch}}\right)\\
+&\leq \text{Token Supply}*\text{Generation Rate}*2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}}\\
+&\frac{1+\text{Reward To Generation Ratio}*\text{Max to Target Ratio}}{1-\text{Decay per Epoch}}
+\end{align*}
+$$
+
+### Mana Supply after the bootstrapping Phase
+
+By construction, $\text{Final Target Rewards Rate}$ is such that the target reward per epoch is $\text{Reward To Generation Ratio}$ times the generation by holding tokens in that epoch.
+
+Then, we have that the total Mana in the system will never be larger than $\text{Max Mana Holders} (1 + \text{Max to Target Ratio} * \text{Reward To Generation Ratio})$, i.e. the Mana circulating Supply will be always smaller than :
+
+$$
+\begin{align*}
+&\text{Max Mana Supply}\\
+&=\text{Token Supply}*\text{Generation Rate}*2^{\text{Slots per Epoch Exp}-\text{Generation Rate Exp}}\\
+&\frac{1+\text{Reward To Generation Ratio}*\text{Max to Target Ratio}}{1-\text{Decay per Epoch}}
+\end{align*}
+$$
+
+which is the same bound found for the bootstrapping Phase.
+Thus, the protocol parameters should be set so that the $\text{Max Mana Supply}$ above is at most $2^{\text{Bits Count}}-1$.
+
+### Mana Supply for Random committees
+
+In the case of random commitees, we cap the individual pool reward such that no pool will receive more than $\text{Max Pool Reward}(n) = \text{Max Reward Coeff} * \text{Target Rewards Rate}(n)$ per epoch.
+Then, in a single epoch, no more than $\text{Target Committee Size} * \text{Max Reward Coeff} * \text{Target Rewards Rate}(n)$ Mana will be distributed, i.e., in this case, $\text{Max to Target Ratio} = \text{Target Committee Size} * \text{Max Reward Coeff}$.
+Since, in general, $\text{Target Committee Size} * \text{Max Reward Coeff}$ might be larger than 1, we must alredy set proper maximim values for $\text{Max to Target Ratio}$ to prevent overflowing in case of a future change in the committee selection.
+Here, we set $\text{Max to Target Ratio}=20$.
+Note that, for fixed committees, this ratio is naturally respected, without the need to add any type of cap in the rewards.
+However, in the case of a future protocol upgrade such that the committee selection becomes random, a cap respecting a maximum of $\text{Max to Target Ratio}=20$ must be introduced.
+
+## Constraints due to fixed point arithmetics
+
+Additionally to the parameter constraints to prevent the Mana supply from overflowing, other parameter constraints must be introduced to that the function defined in TIP 40 do not overflow using 64 bits variables.
+
+In particular, in this TIP we define the following operations:
+- `Token Supply << Profit Margin Exponent`: this value must be smaller than <code>2<sup>64</sup></code>, 
+- `Pool Coefficient = ((Pool Stake(i) << Pool Coefficient Exponent)/Total Stake) + (Validator Stake(i) << Pool Coefficient Exponent) / Total Validator Stake`:
+Since both `Pool Stake(i)` and `Validator Stake(i)` are at most `Token Supply`, to not overflow the calculation, `Pool Coefficient Exponent` must be such that <code>(Token Supply << Pool Coefficient Exponent)< 2<sup>64</sup></code>.
+`Pool Coefficient` will then use at most `Pool Coefficient Exponent + 1` bits.
+- `res = (Pool Coefficient * Target Rewards Rate(n))>>PoolCoefficientExponent`: this implies that `Pool Coefficient * Target Rewards Rate(n))` must always be smaller than <code>2<sup>64</sup></code>, which is guaranteed by the condition <code>Initial Target Rewards Rate <2<sup>63-Pool Coefficient Exponent</sup></code>.
+- `Pool Reward = ((res * Epoch Performance Factor)/Validation Blocks Per Slot)>>1`: since `res` is at most two times `Initial Target Rewards Rate`, and `Epoch Performance Factor` is at most `Validation Blocks Per Slot <= 32`, this imples that <code>Initial Target Rewards Rate * Validation Blocks Per Slot < 2<sup>63</sup></code>.
+
+- `Profit Margin Factor = (Profit Margin(n) * (Pool Rewards(n) - Fixed Cost(n))) >> Profit Margin Exponent`: this implies that `Initial Target Rewards Rate<2^(64-Profit Margin Exponent) `
+
+## Constraints due to parameter compatibility
+
+To avoid locally calculating the parameters, some of them are provided in the snapshot file, even thought they not are defined independently in the Whitepaper.
+To avoid problems in the parameter setting, we define some sanity checks for these parameters below:
+
+## Lookup Table and Annual Decay
+
+Let `Seconds In An Epoch = Slot Duration In Seconds << Slots Per Epoch Exponent` and `Seconds In A Year = 60 * 60 * 24* 365`.
+Then the epoch duration in years is given by `Epoch Duration In Years = Seconds In An Epoch/Seconds In A Year`.
+Additionally, let `Annual Decay Factor = Annual Decay Factor Percentage/100`.
+
+The entry `Lookup Table(epochDiff)` in the Lookup table relative to `epochDiff` should be such that
+
+`0 <= delta < 1`, where
+
+`delta = (Annual Decay Factor)^(epochDiff*Epoch Duration In Years)*(2**decay Factor Exp) - Lookup Table(epochDiff)`
+
+## Initial and Final rewards
+
+Let `Seconds In An Epoch = Slot Duration In Seconds << Slots Per Epoch Exponent` and `Seconds In A Year = 60 * 60 * 24* 365`.
+Then the epoch duration in years is given by `Epoch Duration In Years = Seconds In An Epoch/Seconds In A Year`.
+The bootstrapping duration in years is, then:
+`Bootstrapping Duration In Years = Epoch Duration In Years * Bootstrapping Duration`
+Additionally, let `Annual Decay Factor = Annual Decay Factor Percentage/100`.
+
+Let `Expected Final Target Rewards Rate = (Total Supply * Reward To Generation Ratio * Generation Rate) >> (Generation Rate Exponent - Slots Per Epoch Exponent)` and `Expected Initial Target Rewards Rate = Final Target Rewards Rate / (Annual Decay Factor ^ Bootstrapping Duration In Years)`.
+
+Then, we need
+
+`0 <= Expected Final Target Rewards Rate - Final Target Rewards Rate < 1`
+and 
+`0 <= Expected Initial Target Rewards Rate - Initial Target Rewards Rate < 1`
+
+## Bootstrapping Duration and Decay
+
+Let `Seconds In An Epoch = Slot Duration In Seconds << Slots Per Epoch Exponent` and `Seconds In A Year = 60 * 60 * 24 * 365`.
+Then the number of epochs in a years is given by `Epochs In An Year = Seconds In A Year/Seconds In An Epoch`.
+Additionally, let `Annual Decay Factor = Annual Decay Factor Percentage/100`.
+Translating this to an exponential decay (as in the Whitepaper), we have that `Beta Per Year = -log(Annual Decay Factor)`.
+
+The bootstrapping duration should be an integer approximation of `Epochs In An Year/Beta Per Year`
+
+## Decay Factor Epoch Sum and Decay
+
+Decay Factor Epoch Sum should be an integer approximation of
+
+`2^Decay Factor Epoch Sum Exponent* Decay per Epoch/(1-Decay per Epoch)`