The reference math library

Status: Built, runs on simulatorStatus: Built, runs on simulator

The reference math library supplies calculations that can be compared with protocol execution; a correct helper result does not replace the transaction’s other checks.

Follow the arithmetic boundary

Stage 1’s @merces/reference exports income, auction, treasury, vault, status, router, currency-conversion, redemption, and window calculations. Stage 2 exposes selected helpers through @merces/math. Its imported functions retain their Stage 1 identity, and the synchronization check tests that identity against the source pin.

A separate family is ported from Stage 1’s Rust because the TypeScript reference does not provide the curve’s unit-scale operations. Those ports have their own source checks. All interim mechanism math has been retired. The empty interim namespace remains only for synchronization-report compatibility.

Preserve each floor operation

For year-to-date income x, threshold theta, outstanding units N, and the per-unit share rate r_wad, the income helper computes:

$$O(x)=\left\lfloor\frac{r_{\mathrm{wad}}N\max(0,x-\theta)}{W}\right\rfloor$$

Formula

$$P=\left\lfloor\frac{\bigl(O(x)-O(x_{\mathrm{prior}})\bigr)f_{\mathrm{wad}}}{W}\right\rfloor$$

Formula

W is the fixed-point scale and f_wad is the conversion ratio. The current and prior cumulative amounts are each floored before subtraction. Using floating-point arithmetic or moving a floor can change a base-unit result. quarterPayment also refuses decreasing cumulative income.

Illustrative example

Example: reference calculation

The numbers here are computed by Stage 1's reference math from made-up inputs. They are not a forecast.

The fixture moves from $35,000.00 to $60,000.00 against a threshold of $40,000.00. Its computed payment is $1,200.00. This is the report amount before the vault’s later allocation work.

Source: fixture canonical, computed by scripts/sync/steps/fixtures.ts@c70cd2627598dddf6badc4fd2a9749445f203276 at Stage 1 commit bafe1fb.

Use the right comparison

Compare integer inputs and results before formatting for display. Then use parity vectors to test the surrounding sequence, balances, and expected refusals. The proof circuit separately constrains the report arithmetic.

What can go wrong

A copied formula can drift from the pinned helper. A matching payment calculation also says nothing about account eligibility, report evidence, or whether a deployed transaction was accepted. Keep arithmetic parity and integration readiness as separate results.