APR Calculation

The Annual Percentage Rate (APR) maps an NFT's level to a base reward rate using a configurable polynomial. It is the primary reward driver — larger denominations (higher levels) earn proportionally more.

Polynomial Evaluation

The APR is computed via Polynomials.eval3(), a three-term polynomial evaluator that combines linear scaling with power-law exponentiation:

$$\text{eval3}(x,[a_0,a_1,a_2,a_3])={(\frac{x\times a_2}{a_1}+a_0)}^{a_3/256}$$

Where the four coefficients are stored as uint256[] in _apr[id]:

Index	Name	Role	Default
array[0]	add	Additive constant (also carries dynamic scalar)	0
array[1]	div	Divisor (never zero)	3
array[2]	mul	Multiplier (never zero)	3{,}375{,}000
array[3]	exp	Exponent numerator (root fixed at 256)	256

The full APR derivation in MoeTreasury.aprTargetOf() at MoeTreasury.sol:265-269:

function aprTargetOf(uint256 nftId, uint256[] memory array) private view returns (uint256) {
    uint256 rate = Polynomial({array: array}).eval3(_ppt.levelOf(nftId));
    uint256 base = Power.raise(1e6, array[array.length - 1]);
    return Math.mulDiv(rate, 1e6, base);
}

The base normalization divides by $\text{Power.raise}({10}^6,\text{exp})=({10}^6{)}^{\text{exp}/256}$. When exp = 256, this simplifies to ${10}^6$, and the normalization has no net effect (multiply and divide cancel). For exp $\neq$ 256, the normalization adjusts the output scale to keep results in PPM.

The Power Library

Exponentiation is handled by Power.raise(n, exp) at Power.sol:10-15:

function raise(uint256 n, uint256 exp) internal pure returns (uint256) {
    require(exp >= 128, InvalidExponentTooSmall(exp));
    require(exp <= 512, InvalidExponentTooLarge(exp));
    UD60x18 p = pow(ud(n * 1e18), ud(exp * 3906250e9));
    return p.intoUint256() / 1e18;
}

This computes $n^{\text{exp}/256}$ using PRB Math's pow() function. The key scaling:

$$\text{raise}(n,e)=\lfloor \frac{\text{pow}(n\times {10}^{18},e\times 3.906250\times {10}^9)}{{10}^{18}}\rfloor$$

The constant $\mathrm{3,906,250}\times {10}^9=\frac{1}{256}\times {10}^{18}$ converts the exponent from a numerator-over-256 representation to UD60x18 fixed-point. The root is always 256 — the exponent numerator $e$ determines the actual power.

Exponent Constraints

$$128\le e\le 512$$

$e$	Effective exponent	Interpretation
128	$n^{0.5}$	Square root — concave
256	$n^{1.0}$	Linear — proportional
384	$n^{1.5}$	Convex — accelerating
512	$n^{2.0}$	Quadratic — strongly accelerating

Exponents below 128 would produce sub-square-root curves (impractical for reward design). Exponents above 512 risk overflow in 256-bit fixed-point arithmetic.

Accuracy

PRB Math's pow() operates on UD60x18 (60.18-bit fixed-point), providing 18 decimal digits of precision. The result is truncated to uint256 by flooring after division, introducing at most 1 wei of error per evaluation. The error is negligible for reward calculations where values are in PPM (${10}^{-6}$ scale).

Parameter Space

Linear Configuration (Default)

With the simplified parameters [0, 256, 1, 256]:

$$\begin{array}{rl}\text{ratio}& =\frac{x\times 1}{256}=\frac{x}{256}\\ \text{result}& =\text{Power.raise}(\frac{x}{256}+0,256)={\left(\frac{x}{256}\right)}^{256/256}=\frac{x}{256}\end{array}$$

The APR normalization then multiplies by ${10}^6$ and divides by $\text{raise}({10}^6,256)={10}^6$, giving an effective APR of $x/256$ PPM. Level 30 yields:

$$\text{APR}(30)=\frac{30}{256}\text{ PPM}\approx 0.117\text{ PPM}=0.0000117\mathrm{\%}$$

This is a deliberately conservative base rate — the actual deployed parameters scale values into the range where reward accumulation is meaningful over months and years.

Production Configuration

The deployed contract uses [0, 3, 3375000, 256]:

$$\begin{array}{rl}\text{ratio}& =\frac{x\times \mathrm{3,375,000}}{3}=x\times \mathrm{1,125,000}\\ \text{result}& =\text{Power.raise}(x\times \mathrm{1,125,000},256)=x\times \mathrm{1,125,000}\end{array}$$

Normalized by ${10}^6$:

$$\text{APR}(x)=\frac{x\times \mathrm{1,125,000}\times {10}^6}{{10}^6}=x\times \mathrm{1,125,000}\text{ PPM}$$

For level 30: $\text{APR}(30)=\mathrm{33,750,000}\text{ PPM}=33.75\mathrm{\%}$ annual rate times age fraction.

Concave, Linear, and Convex Curves

The add, div, mul, and exp parameters give the protocol broad control over rate curves:

Concave (Sub-linear)

[1000, 256, 50, 128] — square root shape, diminishing marginal returns:

$$\text{APR}(x)\propto \sqrt{\frac{50x}{256}+1000}$$

Higher levels still earn more in absolute terms, but the rate of increase slows, favoring mid-tier staking.

Linear

[0, 256, 100, 256] — proportional:

$$\text{APR}(x)=\frac{100x}{256}\text{ PPM}$$

Each additional level adds the same rate increment.

Convex (Super-linear)

[0, 256, 1, 512] — quadratic, accelerating returns:

$$\text{APR}(x)={\left(\frac{x}{256}\right)}^2\text{ PPM}$$

Strongly incentivizes high-level staking; level 90 earns $81\times$ what level 10 earns (relative to a linear curve).

APR by Level

Using the production parameters $[0,3,\mathrm{3,375,000},256]$, the raw eval3 output and normalized APR for selected levels:

Level	$\ell$	$\text{eval3}(\ell )$	$\text{APR}(\ell )$ (PPM)	As Percentage
0	0	0	0	0%
9	9	10,125,000	10,125,000	10.125%
21	21	23,625,000	23,625,000	23.625%
30	30	33,750,000	33,750,000	33.750%
45	45	50,625,000	50,625,000	50.625%
60	60	67,500,000	67,500,000	67.500%
90	90	101,250,000	101,250,000	101.250%

Note: these are annualized rates. Actual rewards accrue per-second, so a stake held for 1 day at level 30 yields:

$$R=\frac{\mathrm{33,750,000}\times \mathrm{86,400}\times {10}^{48}}{{10}^6\times \mathrm{3,155,760,000}}\approx \text{(small fraction of denomination)}$$

The CENTURY denominator ($\mathrm{3,155,760,000}$ seconds) spreads the annual rate across ~100 years of seconds, making per-day rewards tiny in percentage terms but meaningful for large denominations over long durations.

Dynamic Scalar Integration

The additive constant array[0] is not static — it is recomputed by refreshRates() based on per-level share distribution:

_apr[id][0] = _scalar(APR_MUL, sum, bins, shares[i]);

Where _scalar computes:

$${\text{add}}_{\ell }=\frac{\text{mul}\times \text{sum}}{\text{bins}\times {\text{share}}_{\ell }}$$

• $\text{sum}$: total denomination staked across all active levels
• $\text{bins}$: number of active levels (non-zero shares)
• ${\text{share}}_{\ell }$: denomination staked at level $\ell$

When share is below the per-bin average, add exceeds mul, boosting the APR. When above average, add is reduced. Levels with zero shares get add = 0 (cleared) or add = 0, div = APR_DIV (default parameters).

This scalar folds into the APR calculation as:

$$\text{APR}(\ell )\propto \frac{\ell \times \text{mul}}{\text{div}}+\text{add}$$

When div is set to type(uint256).max (as refreshRates() does for active levels), the level-dependence is effectively disabled and only the scalar add matters — all levels at the same share level earn identical base rates modulated purely by the share distribution.

Rpp Constraints

Parameter changes via setAPR() are gated by Rpp.checkArray() and Rpp.checkValue():

Array Validation (Rpp.sol:13-19)

function checkArray(uint256[] memory array) internal pure {
    require(array.length == 4, InvalidArrayLength(array.length));
    require(array[1] > 0, InvalidArrayIndex(1));  // div non-zero
    require(array[2] > 0, InvalidArrayIndex(2));  // mul non-zero
}

Value Change Validation (Rpp.sol:24-34)

For both the per-level rate and the mean rate:

$$0.5\le \frac{\text{next}}{\text{last}}\le 2.0$$

When transitioning from zero (last == 0), the new value must not exceed 1e6 (for rate) or APR_MUL (for mean):

function checkValue(uint256 next, uint256 last, uint256 unit) internal pure {
    if (next < last) {
        require(last <= 2 * next, TooSmall(next, last));
    }
    if (next > last && last > 0) {
        require(next <= 2 * last, TooLarge(next, last));
    }
    if (next > last && last == 0) {
        require(next <= unit, TooLarge(next, last));
    }
}

Timing Validation (Rpp.sol:39-43)

At least 1 month (2,628,000 seconds) must elapse between consecutive setAPR() calls for the same NFT id:

function checkStamp(uint256 next, uint256 last) internal pure {
    if (last > 0) {
        require(next > Constant.MONTH + last, TooQuick(next, last));
    }
}

The stamp is recorded as block.timestamp in the integrator's last item (accessed via the "S" meta key). This meta entry allows the integrator to track both the rate history and the governance-change history in the same data structure.

Invariants

1. APR is always non-negative: eval3 operates on unsigned integers; the addend cannot be negative (Solidity uint256)
2. APR(0) = add: At level zero, ratio = 0, so APR(0) = Power.raise(add, exp) normalized
3. APR monotonicity: With add ≥ 0, mul > 0, exp ≥ 128, $\text{APR}({\ell }_2)\ge \text{APR}({\ell }_1)$ for ${\ell }_2>{\ell }_1$
4. Rate changes are time-weighted: The integrator smooths transitions; no instantaneous rate jumps affect existing stakers
5. Only governance can change parameters: setAPR() is gated by APR_ROLE