@waterx/sdk 4.0.1 → 4.3.0

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

@@ -1,8 +1,96 @@
+/**
+ * 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.
+ */
+/**
+ * A USD price as a plain decimal STRING (`"95000"` / `"95000.5"`) — the EXACT
+ * mode of `rawPrice`.
+ *
+ * The digits are parsed straight onto the 1e9 grid with no f64 round-trip, so
+ * the conversion is digit-exact at any magnitude (up to 9 decimal places;
+ * `rawPrice` throws on malformed input, a leading `-`, scientific notation, or
+ * >9 decimals, which the grid cannot represent).
+ *
+ * Prefer this mode for any price that is an EXACT KEY rather than a bound —
+ * above all `triggerPrice`, where a raw value off by a single 1e-9 unit
+ * silently fails the order-book lookup.
+ */
+export type ExactDecimalUsd = string;
+/**
+ * Accepted input to `rawPrice`, in two DELIBERATELY different modes:
+ *
+ * - `number` — LOSSY above the f64 cliff. Exact only while `usd × 1e9` stays
+ *   within 2^53 (i.e. below ≈ $9,007,199), and even below that a non-binary
+ *   fraction rounds to the nearest representable double before scaling.
+ *   Fine for slippage bounds (`acceptablePrice`), where ±1 raw unit is noise.
+ * - {@link ExactDecimalUsd} (`string`) — digit-exact at any magnitude. Use for
+ *   exact order-book keys (`triggerPrice`).
+ *
+ * The union is NOT "either works": picking `number` for an exact key is the
+ * documented footgun this alias exists to surface at the call site.
+ */
+export type RawPriceInput = number | ExactDecimalUsd;
 /**
  * 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 declare function rawPrice(usd: number | string): bigint;
+export declare function rawPrice(usd: RawPriceInput): bigint;
 /** Notional value in USD: sizeInAsset × price. */
 export declare function calcNotional(sizeInAsset: number, price: number): number;
 /** Trading fee in USD: notional × feeRate. */
@@ -12,9 +100,89 @@ export declare function calcUnrealizedPnl(isLong: boolean, entryPrice: number, s
 /** Position leverage = notional / collateralUsd. Returns Infinity when collateral is zero. */
 export declare function calcLeverage(sizeUsd: number, collateralUsd: number): number;
 /**
- * Estimated liquidation price.
+ * Accrued-fee inputs for the REAL-model liquidation estimate — see
+ * `calcRealLiqNetCostUsd` for the rule and the Move-semantics note.
+ *
+ * `fundingFeeUsd` is SIGNED, cost-positive: > 0 the position owes funding,
+ * < 0 is funding income (a genuine equity credit, applied in full).
+ */
+export type LiqFeeBundle = {
+    borrowFeeUsd: number;
+    openFeeUsd: number;
+    closingFeeUsd: number;
+    /** SIGNED, cost-positive: > 0 owed, < 0 income (credits equity in full). */
+    fundingFeeUsd: number;
+};
+/**
+ * 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 declare function calcRealLiqNetCostUsd(fees: LiqFeeBundle): number;
+/**
+ * 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 declare function calcViewEstLiqFeesUsd(fees: {
+    borrowFeeUsd: number;
+    openFeeUsd: number;
+    /** SIGNED, cost-positive: > 0 owed, < 0 income (bundle floors at 0). */
+    fundingFeeUsd: number;
+}): number;
+/**
+ * Estimated liquidation price — Number (f64) UI convenience.
+ *
+ * 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.
  *
- * Matches `calculate_est_liq_price` in `waterx_perp_view/sources/view.move`:
+ * Same linear model as the view:
  *   maintenance = maintenanceMarginRate × (size × spotPrice)   ← uses current notional
  *   ratio       = (collateralUsd − totalFeesUsd − maintenance) / (size × avgPrice)
  *   long:  liq  = avgPrice × (1 − ratio)
@@ -22,7 +190,24 @@ export declare function calcLeverage(sizeUsd: number, collateralUsd: number): nu
  *
  * 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 declare function calcEstLiqPrice(params: {
     isLong: boolean;
@@ -31,8 +216,74 @@ export declare function calcEstLiqPrice(params: {
     collateralUsd: number;
     maintenanceMarginRate: number;
     spotPrice: number;
+} & ({
     totalFeesUsd: number;
-}): number;
+    fees?: LiqFeeBundle;
+} | {
+    totalFeesUsd?: number;
+    fees: LiqFeeBundle;
+})): number;
+/**
+ * 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 declare function calcEstLiqPriceRaw(params: {
+    isLong: boolean;
+    /** `PositionData.size` — raw 1e9-scaled Float value. */
+    sizeRaw: bigint;
+    /** `PositionData.average_price` — raw 1e9-scaled Float value. */
+    avgPriceRaw: bigint;
+    /** `PositionData.collateral_amount` — raw collateral token units. */
+    collateralAmountRaw: bigint;
+    /** `PositionData.collateral_decimal`. */
+    collateralDecimal: number;
+    /** Whole-dollar u64 base price — the exact value passed to the view (pre `float::from`). */
+    basePriceUsd: bigint;
+    /** Whole-dollar u64 collateral price — the exact value passed to the view (pre `float::from`). */
+    collateralPriceUsd: bigint;
+    /** `MarketData.maintenance_margin` — raw 1e9-scaled Float value. */
+    maintenanceMarginRaw: bigint;
+    /** `PositionData.borrow_fee` (accrued + unrealized, pre-combined by the view) — raw collateral units. */
+    borrowFeeRaw: bigint;
+    /** `PositionData.funding_fee_positive` — true when the position owes funding. */
+    fundingSign: boolean;
+    /** `PositionData.funding_fee` magnitude — raw collateral units. */
+    fundingFeeRaw: bigint;
+    /** `PositionData.unrealized_trading_fee` (open fee) — raw collateral units. */
+    tradingFeeRaw: bigint;
+}): bigint;
 /**
  * Effective (fee-adjusted) collateral in USD.
  *
@@ -53,9 +304,11 @@ export declare 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 declare function calcEffectiveCollateralUsd(params: {
     grossCollateralUsd: number;
@@ -101,6 +354,16 @@ export declare 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 declare function calcMaxReducibleCollateralUsd(params: {
     grossCollateralUsd: number;
@@ -192,8 +455,11 @@ export declare function calcBorrowRate(utilizationBps: number, rate0: number, ra
 /**
  * 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 declare function calcBorrowRateAccrual(borrowRate: number, elapsedMs: number, intervalMs: number): number;
 /**
@@ -220,19 +486,22 @@ export declare function annualizeFundingRate(rate: number, intervalMs: number):
  * 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 declare function annualizedApyFromRatio(ratio: number, days: number): number;
 /**
  * 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 declare function calcWlpIncentiveApy(apr: number): number;
 /**
@@ -248,12 +517,21 @@ export declare function calcWlpPrice(tvlUsd: number, totalSupply: number, lpDeci
  *
  * 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 declare function calcWlpMintOut(netDepositUsd: number, tvlUsd: number, totalSupply: number, lpDecimals: number): number;
 /**
@@ -262,11 +540,21 @@ export declare function calcWlpMintOut(netDepositUsd: number, tvlUsd: number, to
  * 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 declare function calcWlpRedeemOut(lpAmount: number, tvlUsd: number, totalSupply: number, tokenPriceUsd: number, tokenDecimals: number): number;
 /**
@@ -275,7 +563,8 @@ export declare function calcWlpRedeemOut(lpAmount: number, tvlUsd: number, total
  * 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.
@@ -283,5 +572,8 @@ export declare function calcWlpRedeemOut(lpAmount: number, tvlUsd: number, total
  * @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 declare function calcDynamicFeeBps(tokenValueUsd: number, tvlUsd: number, operationValueUsd: number, targetWeightBps: number, baseFeeBps: number, isDeposit: boolean): number;