@waterx/sdk 4.0.1 → 4.3.0

package/dist/src/utils/math.js

@@ -1,14 +1,85 @@
+/**
+ * Perp / WLP number math: Move-mirroring formulas, the `Float` fixed-point
+ * mirrors the canonical raw estimates need, and the on-chain price encoding.
+ *
+ * ## Validation policy — two tiers, deliberate
+ *
+ * The per-function `@throws` blocks below are INSTANCES of this rule, not a
+ * dozen independent decisions — every tier-1 function carries one. Guards come
+ * from `utils/validate.ts` (`assertFinite` / `assertFiniteNonNegative` /
+ * `assertUnitFraction` / `assertTokenDecimal` / `assertUnsignedBigInt`) and
+ * every message names the offending parameter.
+ *
+ * 1. **MONEY PATH — throws `RangeError`.** The fee bundles
+ *    (`calcRealLiqNetCostUsd`, `calcViewEstLiqFeesUsd`), the liquidation
+ *    estimates (`calcEstLiqPrice`, `calcEstLiqPriceRaw`), collateral and
+ *    withdrawable (`calcEffectiveCollateralUsd`,
+ *    `calcMaxReducibleCollateralUsd`), and the WLP quote / APY surface
+ *    (`calcWlpMintOut`, `calcWlpRedeemOut`, `calcDynamicFeeBps`,
+ *    `annualizedApyFromRatio`, `calcWlpIncentiveApy`). These map garbage onto a
+ *    PLAUSIBLE number — an `Infinity` fee returns 0, indistinguishable from
+ *    "already liquidatable"; a negative fee ADDS to equity — so the input dies
+ *    at the boundary instead of becoming a wrong price on a screen.
+ * 2. **BARE ARITHMETIC — no guards.** Mostly one-line helpers (`calcNotional`,
+ *    `calcFee`, `calcUnrealizedPnl`, `calcLeverage`, `calcTotalTradingFeeRate`,
+ *    `calcFundingRate`, `calcFundingFeeUsd`, `decodeFundingIndexDelta`,
+ *    `calcBorrowRate`, `calcBorrowRateAccrual`, `calcPositionBorrowFee`,
+ *    `calcTokenUtilizationBps`, `annualizeFundingRate`, `calcWlpPrice`), plus
+ *    `calcImpactFeeRate` — NOT a one-liner (a branchy curve with eight early
+ *    returns) but the same category: each of its early returns tests an exact
+ *    zero or an ordering that a NaN never satisfies, so garbage falls straight
+ *    through the branches instead of being absorbed by one. A NaN / Infinity
+ *    input propagates VISIBLY to the output in all of them — there is no
+ *    plausible-looking value for it to hide behind — so a guard would add noise
+ *    and cost without buying safety.
+ *
+ * `rawPrice` sits in neither tier: it is a PARSE, and throws plain `Error` on
+ * malformed input.
+ *
+ * ### Documented domain zeros
+ * Distinct from garbage: an input that is legitimately zero and has exactly one
+ * honest answer returns it rather than throwing. `sizeInAsset === 0` /
+ * `entryNotional === 0` → `0` (nothing to liquidate); `totalSupply === 0` → `0`
+ * (no shares to price — `calcWlpMintOut` is the deliberate exception, where it
+ * means the bootstrap mint); `intervalMs === 0` / `days <= 0` → `0` (no window
+ * to annualize over); `liquidityAmount === 0` → `0` utilization;
+ * `collateralUsd === 0` → `Infinity` leverage. Each is noted at its function.
+ */
 import { BPS_SCALE, DOUBLE_SCALE, FLOAT_SCALE, MS_PER_YEAR } from "../constants.js";
+import { assertFinite, assertFiniteNonNegative, assertTokenDecimal, assertUnitFraction, assertUnsignedBigInt, } from "./validate.js";
 // ======== On-chain encoding ========
+const DECIMAL_USD_RE = /^(\d+)(?:\.(\d+))?$/;
 /**
  * Convert a human-readable USD price to the raw 1e9-scaled `u128` value
  * that on-chain `Float`-typed parameters expect.
+ *
+ * Use for **tx-build** price args only (`acceptablePrice` / `triggerPrice` /
+ * size args). Do NOT use for the view-read params `basePriceUsd` /
+ * `collateralPriceUsd` on `perp/fetch` (`getPosition`, `getMarketPositions`,
+ * `getOrder`, …) — those take WHOLE-DOLLAR integer USD (the Move view applies
+ * `float::from` internally; a 1e9-scaled value inflates pnl/notional-derived
+ * fields by 1e9).
+ *
+ * Precision: see {@link RawPriceInput}. The `number` path rounds through f64
+ * and is exact only below ≈ $9,007,199; an {@link ExactDecimalUsd} string
+ * parses digits directly onto the 1e9 grid without touching f64. This bites
+ * hardest on `triggerPrice`, which is an EXACT order-book key: a raw value off
+ * by one unit silently fails the order lookup.
  */
 export function rawPrice(usd) {
-    const n = typeof usd === "string" ? Number(usd) : usd;
-    if (!Number.isFinite(n))
+    if (typeof usd === "string") {
+        const match = DECIMAL_USD_RE.exec(usd.trim());
+        if (!match)
+            throw new Error(`Invalid USD price: ${usd}`);
+        const [, whole, frac = ""] = match;
+        if (frac.length > 9) {
+            throw new Error(`Invalid USD price: ${usd} — more than 9 decimal places cannot be represented on the 1e9 grid`);
+        }
+        return BigInt(whole) * FLOAT_SCALE + BigInt(frac.padEnd(9, "0") || "0");
+    }
+    if (!Number.isFinite(usd))
         throw new Error(`Invalid USD price: ${usd}`);
-    return BigInt(Math.round(n * Number(FLOAT_SCALE)));
+    return BigInt(Math.round(usd * Number(FLOAT_SCALE)));
 }
 // ======== Basic position math ========
 /** Notional value in USD: sizeInAsset × price. */
@@ -30,9 +101,81 @@ export function calcLeverage(sizeUsd, collateralUsd) {
     return sizeUsd / collateralUsd;
 }
 /**
- * Estimated liquidation price.
+ * Net fee cost (USD) of the REAL liquidation check — a plain SIGNED sum:
+ *
+ *   netCostUsd = borrowFeeUsd + openFeeUsd + closingFeeUsd + fundingFeeUsd
+ *
+ * `fundingFeeUsd` is SIGNED cost-positive, and the result MAY BE NEGATIVE
+ * when funding income exceeds the other fees. That is deliberate:
+ * `position.move::is_liquidatable` credits funding income IN FULL — income
+ * first pays down any accumulated deficit, and the remainder is added back to
+ * remaining equity — so the linearized equity model is a plain signed sum
+ * with no floor. Flooring at 0 here would understate an income-rich
+ * position's equity and show a liq price closer to spot than the real check.
+ *
+ * Three-way Move-semantics relationship (verified against the Move sources
+ * 2026-07-30):
+ * - the REAL liquidation check, `position.move::is_liquidatable`
+ *   (waterx_perp): deducts borrow + open + CLOSING fee and credits funding
+ *   income in full (deficit first, remainder back to equity) — exactly this
+ *   function's signed sum;
+ * - the view estimate, `view.move::calculate_est_liq_price`
+ *   (waterx_perp_view): OMITS the closing fee AND floors its fee bundle at 0
+ *   (`Float.saturating_sub` — Float is unsigned) — see `calcViewEstLiqFeesUsd`
+ *   and the op-exact `calcEstLiqPriceRaw`;
+ * - SDK `calcEffectiveCollateralUsd` does NOT credit funding income at all:
+ *   it mirrors the withdrawable-collateral checks
+ *   (`calculate_effective_collateral_amount` in `trading.move`), not the
+ *   liquidation inequality.
+ * Do not "fix" any of the three to match another.
+ *
+ * @throws RangeError when borrow/open/closing fees are not finite `>= 0`
+ *   numbers, or `fundingFeeUsd` is not finite.
+ */
+export function calcRealLiqNetCostUsd(fees) {
+    assertFiniteNonNegative("fees.borrowFeeUsd", fees.borrowFeeUsd);
+    assertFiniteNonNegative("fees.openFeeUsd", fees.openFeeUsd);
+    assertFiniteNonNegative("fees.closingFeeUsd", fees.closingFeeUsd);
+    assertFinite("fees.fundingFeeUsd", fees.fundingFeeUsd);
+    return fees.borrowFeeUsd + fees.openFeeUsd + fees.closingFeeUsd + fees.fundingFeeUsd;
+}
+/**
+ * Fee bundle (USD) of the VIEW estimate `view.move::calculate_est_liq_price`:
+ *
+ *   viewFeesUsd = max(0, borrowFeeUsd + openFeeUsd + fundingFeeUsd)
+ *
+ * Mirrors the view's unsigned Float arithmetic: funding income is credited
+ * via `Float.saturating_sub`, so the bundle FLOORS AT 0 — income beyond the
+ * other fees is discarded by the view. There is deliberately NO
+ * `closingFeeUsd` field: the view omits the close-fee term, and this shape
+ * makes it structurally impossible to include one. For the REAL liquidation
+ * check's semantics use `calcRealLiqNetCostUsd`; for chain-bit-identical
+ * output use `calcEstLiqPriceRaw`.
+ *
+ * Exported on purpose even though `calcEstLiqPriceRaw` covers the chain-exact
+ * path: this is the VIEW-model counterpart of `calcRealLiqNetCostUsd`, for
+ * consumers that need the view's fee bundle as a Number (mirroring what the
+ * view displays) rather than the full raw price. The two-API split is what makes
+ * the REAL and VIEW models impossible to confuse — do not fold it away.
+ *
+ * @throws RangeError when borrow/open fees are not finite `>= 0` numbers, or
+ *   `fundingFeeUsd` is not finite.
+ */
+export function calcViewEstLiqFeesUsd(fees) {
+    assertFiniteNonNegative("fees.borrowFeeUsd", fees.borrowFeeUsd);
+    assertFiniteNonNegative("fees.openFeeUsd", fees.openFeeUsd);
+    assertFinite("fees.fundingFeeUsd", fees.fundingFeeUsd);
+    return Math.max(0, fees.borrowFeeUsd + fees.openFeeUsd + fees.fundingFeeUsd);
+}
+/**
+ * Estimated liquidation price — Number (f64) UI convenience.
  *
- * Matches `calculate_est_liq_price` in `waterx_perp_view/sources/view.move`:
+ * An approximation for display. The CANONICAL implementation is
+ * `calcEstLiqPriceRaw` (BigInt fixed-point, op-for-op mirror of
+ * `calculate_est_liq_price` in `waterx_perp_view/sources/view.move`); use that
+ * wherever exact parity with the on-chain `est_liq_price` matters.
+ *
+ * Same linear model as the view:
  *   maintenance = maintenanceMarginRate × (size × spotPrice)   ← uses current notional
  *   ratio       = (collateralUsd − totalFeesUsd − maintenance) / (size × avgPrice)
  *   long:  liq  = avgPrice × (1 − ratio)
@@ -40,10 +183,40 @@ export function calcLeverage(sizeUsd, collateralUsd) {
  *
  * Returns 0 when the position is already liquidatable or has no size.
  *
- * @param totalFeesUsd  Sum of all accrued fees in USD: borrow + trading + net funding.
+ * Fees — pass EITHER:
+ * - `fees`: the structured bundle, matching the REAL liquidation check
+ *   (`position.move::is_liquidatable`). `totalFeesUsd` is derived via
+ *   `calcRealLiqNetCostUsd` — a SIGNED sum including the closing fee, with
+ *   funding income credited IN FULL, so a caller structurally cannot omit a
+ *   term or mis-handle income. A negative net cost ADDS to the remaining
+ *   margin, pushing the estimate FARTHER from spot. Takes precedence when
+ *   both are given; or
+ * - `totalFeesUsd`: a pre-computed number (back-compat path) — the caller
+ *   owns the fee model.
+ * NOTE the deliberate model difference vs the on-chain VIEW: the view both
+ * floors its fee bundle at 0 and omits the close fee (`calcViewEstLiqFeesUsd`
+ * / `calcEstLiqPriceRaw`); the `fees` path here matches the REAL check.
+ *
+ * @throws RangeError when sizeInAsset / avgPrice / spotPrice / collateralUsd
+ *   are not finite `>= 0` numbers, when `maintenanceMarginRate` is not finite
+ *   inside `[0, 1]`, or when `totalFeesUsd` is not finite.
+ *   (`sizeInAsset === 0` stays a documented domain case returning 0.)
  */
 export function calcEstLiqPrice(params) {
-    const { isLong, avgPrice, sizeInAsset, collateralUsd, maintenanceMarginRate, spotPrice, totalFeesUsd, } = params;
+    const { isLong, avgPrice, sizeInAsset, collateralUsd, maintenanceMarginRate, spotPrice } = params;
+    assertFiniteNonNegative("sizeInAsset", sizeInAsset);
+    assertFiniteNonNegative("avgPrice", avgPrice);
+    assertFiniteNonNegative("spotPrice", spotPrice);
+    assertFiniteNonNegative("collateralUsd", collateralUsd);
+    assertUnitFraction("maintenanceMarginRate", maintenanceMarginRate);
+    let totalFeesUsd;
+    if (params.fees !== undefined) {
+        totalFeesUsd = calcRealLiqNetCostUsd(params.fees);
+    }
+    else {
+        totalFeesUsd = params.totalFeesUsd ?? 0;
+        assertFinite("totalFeesUsd", totalFeesUsd);
+    }
     if (sizeInAsset === 0)
         return 0;
     const entryNotional = sizeInAsset * avgPrice;
@@ -59,6 +232,118 @@ export function calcEstLiqPrice(params) {
     }
     return avgPrice * (1 + ratio);
 }
+// ======== Move Float mirrors (internal) ========
+// `bucket_v2_framework::float` — UNSIGNED u128 fixed-point at 1e9 where every
+// operation truncates via integer division. These mirror exactly the ops
+// `calcEstLiqPriceRaw` needs. Move's overflow aborts are not mirrored: JS
+// BigInt cannot overflow, and an input that would abort on chain has no
+// chain-produced value to be compared against.
+/** `float::from_fraction(n, m)` — `(n × 1e9) / m`, truncating. */
+const floatFromFraction = (n, m) => (n * FLOAT_SCALE) / m;
+/** `float::mul(a, b)` — `(a × b) / 1e9`, truncating. */
+const floatMul = (a, b) => (a * b) / FLOAT_SCALE;
+/** `float::div(a, b)` — `(a × 1e9) / b`, truncating. */
+const floatDiv = (a, b) => (a * FLOAT_SCALE) / b;
+/** `float::saturating_sub(a, b)` — `a − b` floored at 0 (Float is unsigned). */
+const floatSaturatingSub = (a, b) => (a < b ? 0n : a - b);
+/**
+ * `waterx_perp::math::amount_to_usd(amount, decimal, price)` — the exact
+ * two-step composition `from_fraction(amount, 10^decimal).mul(price)`, each
+ * step truncating independently (NOT algebraically merged).
+ */
+const amountToUsdRaw = (amountRaw, pow10, priceRaw) => floatMul(floatFromFraction(amountRaw, pow10), priceRaw);
+/**
+ * `10u64.pow(decimal)` for the whole u64 decimal domain — exhaustive, since the
+ * `collateralDecimal` guard pins it to `[0, 19]` (10^19 < 2^64 ≤ 10^20). Built
+ * once at module load instead of exponentiating per call.
+ */
+const POW10 = Object.freeze(Array.from({ length: 20 }, (_, decimal) => 10n ** BigInt(decimal)));
+/**
+ * Estimated liquidation price — CANONICAL raw fixed-point implementation.
+ *
+ * Op-for-op mirror of `calculate_est_liq_price` in
+ * `waterx_perp_view/sources/view.move` under `bucket_v2_framework::float`
+ * semantics: unsigned 1e9 fixed-point, every `mul` is `(a×b)/1e9` and every
+ * `div` is `(a×1e9)/b` with truncating BigInt division at EACH step,
+ * including `math::amount_to_usd`'s exact composition, the u64 addition of
+ * borrow + open fee BEFORE the USD conversion, and the `saturating_sub`
+ * funding credit (the VIEW model: fee bundle floors at 0, close fee omitted).
+ * Given the same raw inputs the view receives, the result is bit-identical to
+ * the chain's `PositionData.est_liq_price`.
+ *
+ * The Number `calcEstLiqPrice` is a UI convenience approximation of this
+ * canonical form (and its `fees` path models the REAL liquidation check
+ * instead of the view — see `calcRealLiqNetCostUsd`).
+ *
+ * Inputs are the raw on-chain values exactly as the view takes them.
+ * Returns the raw 1e9-scaled u128 price; `0n` = already liquidatable /
+ * zero size (the view's N/A signal).
+ *
+ * Holding a fetched `PositionDataView` row? Use `calcEstLiqPriceRawFromView`
+ * (`perp/liq-view.ts`) instead of hand-mapping its nine raw fields — the adapter
+ * owns that mapping and carries the invariant below on its own signature.
+ *
+ * INVARIANT the signature cannot enforce: `basePriceUsd` / `collateralPriceUsd`
+ * MUST be the same whole-dollar values passed to the `perp/fetch` read that
+ * produced the row whose fields you are feeding in. `PositionDataView` does not
+ * carry the probe prices, so nothing here can check it — feed different prices
+ * and the fee/notional-derived fields were computed against one price while the
+ * estimate is computed against another, and parity with
+ * `PositionData.est_liq_price` silently breaks.
+ *
+ * @throws RangeError when any bigint input is negative or
+ *   `collateralDecimal` is not an integer in `[0, 19]` (u64 `10^decimal`).
+ */
+export function calcEstLiqPriceRaw(params) {
+    const { isLong, sizeRaw, avgPriceRaw, collateralAmountRaw, collateralDecimal, basePriceUsd, collateralPriceUsd, maintenanceMarginRaw, borrowFeeRaw, fundingSign, fundingFeeRaw, tradingFeeRaw, } = params;
+    // One loop so the guard labels cannot drift from the field names.
+    for (const [label, value] of Object.entries({
+        sizeRaw,
+        avgPriceRaw,
+        collateralAmountRaw,
+        basePriceUsd,
+        collateralPriceUsd,
+        maintenanceMarginRaw,
+        borrowFeeRaw,
+        fundingFeeRaw,
+        tradingFeeRaw,
+    })) {
+        assertUnsignedBigInt(label, value);
+    }
+    assertTokenDecimal("collateralDecimal", collateralDecimal);
+    // float::from(u64) — whole dollars onto the 1e9 grid (exact, no truncation).
+    const basePrice = basePriceUsd * FLOAT_SCALE;
+    const collPrice = collateralPriceUsd * FLOAT_SCALE;
+    const pow10 = POW10[collateralDecimal];
+    const entryNotional = floatMul(sizeRaw, avgPriceRaw);
+    // math::amount_to_usd — the exact two-step from_fraction(amount, 10^dec).mul(price),
+    // each step truncating independently (see amountToUsdRaw).
+    const collateralUsd = amountToUsdRaw(collateralAmountRaw, pow10, collPrice);
+    const currentNotional = floatMul(sizeRaw, basePrice);
+    const maintenance = floatMul(maintenanceMarginRaw, currentNotional);
+    // u64 addition BEFORE the conversion — ONE from_fraction over the summed fees,
+    // not two conversions added (the truncation points differ).
+    const accruedFeesUsd = amountToUsdRaw(borrowFeeRaw + tradingFeeRaw, pow10, collPrice);
+    const fundingFeeUsd = amountToUsdRaw(fundingFeeRaw, pow10, collPrice);
+    // owed → add; income → Float.saturating_sub (unsigned: the bundle floors at 0,
+    // so the view DISCARDS income beyond the other fees).
+    const totalFeesUsd = fundingSign
+        ? accruedFeesUsd + fundingFeeUsd
+        : floatSaturatingSub(accruedFeesUsd, fundingFeeUsd);
+    const deductions = totalFeesUsd + maintenance;
+    // The view's early return is `lte` / `eq` — INCLUSIVE: collateral exactly at
+    // deductions is already liquidatable, hence `<=` and `=== 0n` here.
+    if (collateralUsd <= deductions || entryNotional === 0n)
+        return 0n;
+    const marginRemaining = collateralUsd - deductions;
+    const ratio = floatDiv(marginRemaining, entryNotional);
+    if (isLong) {
+        if (ratio >= FLOAT_SCALE)
+            return 0n;
+        return floatMul(avgPriceRaw, FLOAT_SCALE - ratio);
+    }
+    return floatMul(avgPriceRaw, FLOAT_SCALE + ratio);
+}
 /**
  * Effective (fee-adjusted) collateral in USD.
  *
@@ -79,12 +364,19 @@ export function calcEstLiqPrice(params) {
  * @param grossCollateralUsd      Position collateral in USD (`collateral_amount` → USD).
  * @param borrowFeeUsd            `unrealized_borrow_fee` in USD.
  * @param fundingSign             `unrealized_funding_sign` — true when the position owes funding.
- * @param fundingFeeUsd           `unrealized_funding_fee` magnitude in USD.
+ * @param fundingFeeUsd           `unrealized_funding_fee` magnitude in USD (unsigned; sign travels separately).
  * @param tradingFeeUsd           `unrealized_trading_fee` in USD.
  * @param projectedTradingFeeUsd  Closing fee to reserve (0 for a bare collateral withdrawal).
+ * @throws RangeError when any USD input is not a finite `>= 0` number — a
+ *   negative fee would silently ADD to effective collateral.
  */
 export function calcEffectiveCollateralUsd(params) {
     const { grossCollateralUsd, borrowFeeUsd, fundingSign, fundingFeeUsd, tradingFeeUsd, projectedTradingFeeUsd = 0, } = params;
+    assertFiniteNonNegative("grossCollateralUsd", grossCollateralUsd);
+    assertFiniteNonNegative("borrowFeeUsd", borrowFeeUsd);
+    assertFiniteNonNegative("fundingFeeUsd", fundingFeeUsd);
+    assertFiniteNonNegative("tradingFeeUsd", tradingFeeUsd);
+    assertFiniteNonNegative("projectedTradingFeeUsd", projectedTradingFeeUsd);
     const eff = grossCollateralUsd -
         borrowFeeUsd -
         tradingFeeUsd -
@@ -128,9 +420,42 @@ export function calcEffectiveCollateralUsd(params) {
  * @param closingFeeUsd           Full closing fee in USD (`close_fee` → USD).
  * @param collateralPriceUsd      Oracle price of the collateral token (USD per token).
  * @param collateralDecimal       Collateral token decimals — sets the smallest withdraw step.
+ * @throws RangeError when any USD / size / price input is not a finite `>= 0`
+ *   number, when `maintenanceMarginRate` is not finite inside `[0, 1]`, or when
+ *   `collateralDecimal` is not an integer in `[0, 19]` — the same domains
+ *   `calcEstLiqPrice` / `calcEstLiqPriceRaw` enforce. Two of these are the
+ *   reason the whole set is here: a negative fee silently INFLATES the
+ *   withdrawable amount, and a negative `collateralPriceUsd` drops the
+ *   one-raw-unit liquidation back-off to 0 — removing the abort-safety margin
+ *   while still returning a plausible-looking dollar figure.
+ *   (`maxLeverage === 0` → no leverage cap and `collateralPriceUsd === 0` → no
+ *   back-off stay documented domain zeros, not garbage.)
  */
 export function calcMaxReducibleCollateralUsd(params) {
     const { grossCollateralUsd, sizeInAsset, spotPrice, isLong, entryPrice, maxLeverage, maintenanceMarginRate, minCollValueUsd, borrowFeeUsd, tradingFeeUsd, closingFeeUsd, fundingSign, fundingFeeUsd, collateralPriceUsd, collateralDecimal, } = params;
+    // MONEY PATH (see the validation policy at the top of this file): every
+    // numeric input is pinned to the same domains calcEstLiqPrice uses. Fees are
+    // UNSIGNED here — funding's sign travels separately in `fundingSign` — so a
+    // negative one would silently INFLATE the withdrawable amount. One loop so
+    // the guard labels cannot drift from the field names; the grossCollateral /
+    // borrow / trading legs are re-checked inside calcEffectiveCollateralUsd.
+    for (const [label, value] of Object.entries({
+        grossCollateralUsd,
+        sizeInAsset,
+        spotPrice,
+        entryPrice,
+        maxLeverage,
+        minCollValueUsd,
+        borrowFeeUsd,
+        tradingFeeUsd,
+        closingFeeUsd,
+        fundingFeeUsd,
+        collateralPriceUsd,
+    })) {
+        assertFiniteNonNegative(label, value);
+    }
+    assertUnitFraction("maintenanceMarginRate", maintenanceMarginRate);
+    assertTokenDecimal("collateralDecimal", collateralDecimal);
     const notional = sizeInAsset * spotPrice;
     // effLeverage: matches calculate_effective_collateral_amount(..., projectedTradingFee = 0).
     const effLeverage = calcEffectiveCollateralUsd({
@@ -286,8 +611,11 @@ export function calcBorrowRate(utilizationBps, rate0, rate1, rate2, threshold0Bp
 /**
  * Time-weighted borrow rate accrual for a given elapsed period.
  *
- * Matches `calculate_borrow_rate_accrual` in `lp_pool.move`.
- * `elapsedMs / intervalMs` gives the number of completed intervals.
+ * Continuous proration: `rate × elapsedMs / intervalMs`, matching the formula
+ * of `lp_pool.move::calculate_borrow_rate_accrual`
+ * (`borrow_rate.mul_u64(elapsed_ms).div_u64(interval_ms)`) — the contract does
+ * NOT floor to completed intervals; a partial interval accrues pro rata
+ * (verified against the Move source 2026-07-29).
  */
 export function calcBorrowRateAccrual(borrowRate, elapsedMs, intervalMs) {
     if (borrowRate === 0 || elapsedMs === 0 || intervalMs === 0)
@@ -332,13 +660,17 @@ export function annualizeFundingRate(rate, intervalMs) {
  * Annualized APY from a NAV ratio over a given number of days.
  *
  * Compounds `ratio` (WLP price now / WLP price past) to a 365-day return.
- * Returns 0 when the result is not finite (e.g. ratio ≤ 0 or days = 0).
+ * Documented domain cases returning 0: `ratio <= 0` or `days <= 0` (no valid
+ * sample window), and an overflowing compound result.
  *
  * @param ratio  Current NAV divided by past NAV (e.g. 1.05 for 5% growth).
  * @param days   Number of days elapsed between the two NAV samples.
+ * @throws RangeError when `ratio` or `days` is NaN / ±Infinity.
  */
 export function annualizedApyFromRatio(ratio, days) {
-    if (days === 0 || ratio <= 0)
+    assertFinite("ratio", ratio);
+    assertFinite("days", days);
+    if (days <= 0 || ratio <= 0)
         return 0;
     const apy = Math.pow(ratio, 365 / days) - 1;
     return Number.isFinite(apy) ? apy : 0;
@@ -347,11 +679,13 @@ export function annualizedApyFromRatio(ratio, days) {
  * Convert a continuously-compounded incentive APR to APY.
  *
  * Rewards stream via `flow_rate` (continuous compounding), so APY = e^APR − 1.
- * Returns 0 when the result is not finite.
+ * Returns 0 when the compound result overflows to Infinity.
  *
  * @param apr  Time-weighted incentive APR as a decimal fraction (e.g. 0.12 for 12%).
+ * @throws RangeError when `apr` is NaN / ±Infinity.
  */
 export function calcWlpIncentiveApy(apr) {
+    assertFinite("apr", apr);
     const apy = Math.expm1(apr);
     return Number.isFinite(apy) ? apy : 0;
 }
@@ -373,17 +707,32 @@ export function calcWlpPrice(tvlUsd, totalSupply, lpDecimals) {
  *
  * Matches the LP-amount formula in `mint_wlp_with_pricing_tvl` in `lp_pool.move`.
  * Pass `netDepositUsd` (after the dynamic mint fee is deducted).
- * Bootstrap path (totalSupply === 0): lpAmount = netDepositUsd × 10^lpDecimals.
+ *
+ * Bootstrap ($1/share par, `lpAmount = netDepositUsd × 10^lpDecimals`) applies
+ * ONLY to the genuine first mint (`totalSupply === 0`) — exactly like the
+ * chain. When supply is outstanding but the priced TVL has floored to 0 (e.g.
+ * trader unrealized profit ≥ TVL drove the equity `saturating_sub` to 0) the
+ * chain ABORTS `EInvalidBootstrap` rather than par-minting cheap shares that
+ * dilute existing LPs (re-audit F-023); this helper throws `RangeError` in
+ * that state instead of silently par-quoting.
  *
  * @param netDepositUsd  Deposit value in USD after dynamic mint fee.
  * @param tvlUsd         Pool TVL in USD at pricing time.
  * @param totalSupply    Current total WLP supply in raw units.
  * @param lpDecimals     WLP token decimals (6).
+ * @throws RangeError when inputs are not finite `>= 0` numbers, or on the
+ *   `totalSupply > 0 && tvlUsd === 0` state (chain aborts `EInvalidBootstrap`).
  */
 export function calcWlpMintOut(netDepositUsd, tvlUsd, totalSupply, lpDecimals) {
+    assertFiniteNonNegative("netDepositUsd", netDepositUsd);
+    assertFiniteNonNegative("tvlUsd", tvlUsd);
+    assertFiniteNonNegative("totalSupply", totalSupply);
     const scale = Math.pow(10, lpDecimals);
-    if (totalSupply === 0 || tvlUsd === 0)
+    if (totalSupply === 0)
         return Math.floor(netDepositUsd * scale);
+    if (tvlUsd === 0) {
+        throw new RangeError("calcWlpMintOut: totalSupply > 0 with tvlUsd === 0 — the chain aborts EInvalidBootstrap here (par-minting against zero priced TVL dilutes existing LPs; F-023). Retry once the equity snapshot recovers.");
+    }
     return Math.floor((netDepositUsd * totalSupply) / tvlUsd);
 }
 /**
@@ -392,13 +741,27 @@ export function calcWlpMintOut(netDepositUsd, tvlUsd, totalSupply, lpDecimals) {
  * Matches the settlement formula in `settle_redeem_with_pricing_tvl` in `lp_pool.move`.
  * Apply `calcDynamicFeeBps` separately to get the net output.
  *
+ * Chain-divergence notes (display-convenience helper, not settlement-exact):
+ * - `tokenPriceUsd === 0` returns 0 here, but the chain ABORTS (`EZeroPrice`,
+ *   lp_pool.move) — a zero from this helper on that input is a display
+ *   placeholder, not a real quote.
+ * - The burn fee is applied on-chain as
+ *   `float::from_bps(fee_bps).mul_u64(raw_amount).ceil()` — composing this
+ *   helper with `calcDynamicFeeBps` in f64 (which cannot `.ceil()` on the raw
+ *   grid) can drift ±1 raw unit from the settled output.
+ *
  * @param lpAmount       LP tokens being redeemed (raw units).
  * @param tvlUsd         Pool TVL in USD at pricing time.
  * @param totalSupply    Current total WLP supply in raw units.
  * @param tokenPriceUsd  Oracle price of the output token.
  * @param tokenDecimals  Output token decimals.
+ * @throws RangeError when any numeric input is not a finite `>= 0` number.
  */
 export function calcWlpRedeemOut(lpAmount, tvlUsd, totalSupply, tokenPriceUsd, tokenDecimals) {
+    assertFiniteNonNegative("lpAmount", lpAmount);
+    assertFiniteNonNegative("tvlUsd", tvlUsd);
+    assertFiniteNonNegative("totalSupply", totalSupply);
+    assertFiniteNonNegative("tokenPriceUsd", tokenPriceUsd);
     if (totalSupply === 0 || tokenPriceUsd === 0)
         return 0;
     const burnValueUsd = (tvlUsd * lpAmount) / totalSupply;
@@ -410,7 +773,8 @@ export function calcWlpRedeemOut(lpAmount, tvlUsd, totalSupply, tokenPriceUsd, t
  * Matches `calculate_dynamic_fee` in `lp_pool.move`. Returns `baseFeeBps` when
  * the operation moves the token closer to (or does not worsen) its target weight.
  * Adds an additional fee proportional to the average deviation when it moves
- * further away.
+ * further away. Clamped to 100% (`bp_scale`) on both the additional term and
+ * the total, mirroring the on-chain F-039 clamp.
  *
  * @param tokenValueUsd      Current USD value of this token in the pool.
  * @param tvlUsd             Total pool TVL in USD.
@@ -418,8 +782,16 @@ export function calcWlpRedeemOut(lpAmount, tvlUsd, totalSupply, tokenPriceUsd, t
  * @param targetWeightBps    Target allocation weight for this token (bps).
  * @param baseFeeBps         Base mint/burn fee (bps).
  * @param isDeposit          True for mint, false for redeem.
+ * @throws RangeError when any USD / bps input is not a finite `>= 0` number.
+ *   (`tvlUsd` / `operationValueUsd` / `targetWeightBps` of exactly 0 stay
+ *   documented domain cases returning `baseFeeBps` — nothing to deviate from.)
  */
 export function calcDynamicFeeBps(tokenValueUsd, tvlUsd, operationValueUsd, targetWeightBps, baseFeeBps, isDeposit) {
+    assertFiniteNonNegative("tokenValueUsd", tokenValueUsd);
+    assertFiniteNonNegative("tvlUsd", tvlUsd);
+    assertFiniteNonNegative("operationValueUsd", operationValueUsd);
+    assertFiniteNonNegative("targetWeightBps", targetWeightBps);
+    assertFiniteNonNegative("baseFeeBps", baseFeeBps);
     if (tvlUsd === 0 || operationValueUsd === 0 || targetWeightBps === 0)
         return baseFeeBps;
     const targetValue = (tvlUsd * targetWeightBps) / Number(BPS_SCALE);
@@ -439,5 +811,10 @@ export function calcDynamicFeeBps(tokenValueUsd, tvlUsd, operationValueUsd, targ
     if (avgTargetValue === 0)
         return baseFeeBps;
     const additional = Math.floor((avgDiff / avgTargetValue) * baseFeeBps);
-    return baseFeeBps + additional;
+    // F-039 (lp_pool.move::calculate_dynamic_fee): clamp the dynamic fee to 100%.
+    // Both the additional term and the total are capped at bp_scale, mirroring
+    // `(base_fee_bps + additional.min(bp_scale)).min(bp_scale)` — without it the
+    // fee could exceed the operation amount and the on-chain `amount - fee`
+    // subtraction would abort.
+    return Math.min(baseFeeBps + Math.min(additional, Number(BPS_SCALE)), Number(BPS_SCALE));
 }

package/dist/src/utils/validate.d.ts

@@ -0,0 +1,69 @@
+import type { TransactionArgument } from "@mysten/sui/transactions";
+export declare const U64_MAX = 18446744073709551615n;
+/** Validate a u64 param (bigint passthrough with range check; number must be a safe integer >= 0). */
+export declare function toU64(value: bigint | number, label: string): bigint;
+/** Validate a u128 param (bigint passthrough with range check; number must be a safe integer >= 0). */
+export declare function toU128(value: bigint | number, label: string): bigint;
+/**
+ * Validate a u8 param. Returns a `number` (not a bigint) because that is the
+ * shape the generated BCS layer takes at this width.
+ *
+ * Separate from `toU64` on purpose: at u8/u16 the BCS writer already throws on
+ * an out-of-range value, but SILENTLY TRUNCATES a fractional one — so the
+ * fractional case is what this guard exists to catch (see the header note).
+ */
+export declare function toU8(value: number, label: string): number;
+/** Validate a u16 param. Same width caveat as {@link toU8}. */
+export declare function toU16(value: number, label: string): number;
+/** `Option<u64>` param: `null` / `undefined` pass through as `null`, anything else is validated. */
+export declare function toU64OrNull(value: bigint | number | null | undefined, label: string): bigint | null;
+/** `Option<u128>` param: `null` / `undefined` pass through as `null`, anything else is validated. */
+export declare function toU128OrNull(value: bigint | number | null | undefined, label: string): bigint | null;
+/**
+ * u64 param that may instead be a PTB result chained from an earlier command
+ * (e.g. the `lp_amount` returned by `mintWlp`). A `TransactionArgument` passes
+ * through untouched — its value only exists on chain, where Move types it.
+ */
+export declare function toU64Arg(value: bigint | number | TransactionArgument, label: string): bigint | TransactionArgument;
+/** Reject NaN / ±Infinity for a `number` money-path input. */
+export declare function assertFinite(label: string, value: number): void;
+/** Reject NaN / ±Infinity / negative for a `number` money-path input. */
+export declare function assertFiniteNonNegative(label: string, value: number): void;
+/**
+ * Reject anything outside `[0, 1]` for a `number` input that is a FRACTION of a
+ * whole — a maintenance-margin rate above 1 means "maintenance exceeds the
+ * entire notional", which is not a rate the caller can have meant.
+ */
+export declare function assertUnitFraction(label: string, value: number): void;
+/**
+ * Reject a token-decimal outside `[0, 19]` — the domain of the contract's
+ * `10u64.pow(decimal)` (`10^19 < 2^64 <= 10^20`), and the same bound the raw
+ * `POW10` table in `utils/math.ts` is built over.
+ */
+export declare function assertTokenDecimal(label: string, value: number): void;
+/** Reject a negative `bigint` where the on-chain type is unsigned. */
+export declare function assertUnsignedBigInt(label: string, value: bigint): void;
+/**
+ * WHOLE-DOLLAR integer USD price for the `waterx_perp_view` read params
+ * (`80000n` for BTC at $80k). The Move view applies `float::from(...)`
+ * internally — do NOT pass a 1e9-scaled `rawPrice()` value or every
+ * pnl/notional-derived field inflates by 1e9 (`rawPrice()` is for tx-build
+ * args only; the u128 order-book `triggerPrice` key on `getOrder` is the one
+ * view param that still takes that scale). Sub-$1 prices cannot be
+ * represented (u64 whole dollars). The price only bases the
+ * pnl / close-fee / notional-derived fields — `0n` zero-bases them (still
+ * computed with price 0, not skipped).
+ */
+export type WholeDollarUsdPrice = bigint | number;
+/**
+ * Parse a user/env-supplied value into a whole-dollar u64 price
+ * (`WholeDollarUsdPrice`) with NO silent rounding: throws `RangeError` on
+ * fractional, negative, non-finite, non-numeric, or `> u64::MAX` input. If
+ * rounding is ever wanted it must be explicit at the call site
+ * (e.g. `parseWholeDollarU64(Math.round(x))`) — never baked in here.
+ *
+ * The numeric domain (finite → safe integer → non-negative → `<= u64::MAX`) is
+ * `toU64`'s and is NOT restated here; this function only adds the string form,
+ * whose digits parse exactly past the 2^53 f64 cliff.
+ */
+export declare function parseWholeDollarU64(value: string | number): bigint;