@waterx/sdk 3.0.1 → 3.1.0

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

@@ -0,0 +1,287 @@
+/**
+ * Convert a human-readable USD price to the raw 1e9-scaled `u128` value
+ * that on-chain `Float`-typed parameters expect.
+ */
+export declare function rawPrice(usd: number | string): bigint;
+/** Notional value in USD: sizeInAsset × price. */
+export declare function calcNotional(sizeInAsset: number, price: number): number;
+/** Trading fee in USD: notional × feeRate. */
+export declare function calcFee(sizeUsd: number, feeRate: number): number;
+/** Unrealized perp Pnl in USD (before fees). */
+export declare function calcUnrealizedPnl(isLong: boolean, entryPrice: number, spotPrice: number, sizeInAsset: number): number;
+/** Position leverage = notional / collateralUsd. Returns Infinity when collateral is zero. */
+export declare function calcLeverage(sizeUsd: number, collateralUsd: number): number;
+/**
+ * Estimated liquidation price.
+ *
+ * Matches `calculate_est_liq_price` in `waterx_perp_view/sources/view.move`:
+ *   maintenance = maintenanceMarginRate × (size × spotPrice)   ← uses current notional
+ *   ratio       = (collateralUsd − totalFeesUsd − maintenance) / (size × avgPrice)
+ *   long:  liq  = avgPrice × (1 − ratio)
+ *   short: liq  = avgPrice × (1 + ratio)
+ *
+ * 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.
+ */
+export declare function calcEstLiqPrice(params: {
+    isLong: boolean;
+    avgPrice: number;
+    sizeInAsset: number;
+    collateralUsd: number;
+    maintenanceMarginRate: number;
+    spotPrice: number;
+    totalFeesUsd: number;
+}): number;
+/**
+ * Effective (fee-adjusted) collateral in USD.
+ *
+ * Mirrors `calculate_effective_collateral_amount` in `trading.move`: the contract
+ * subtracts accrued borrow + trading fees and, **only when the position owes funding**
+ * (`fundingSign === true`, i.e. `unrealized_funding_sign`), the funding fee too. Funding
+ * *income* (position receives funding, `fundingSign === false`) is NOT added here —
+ * matching the contract's saturating-subtract path. Result clamps at 0.
+ *
+ * This is the collateral the contract actually uses for the max-leverage and
+ * min-collateral checks on `withdraw_collateral` — NOT the gross `collateral_amount`.
+ * Displaying leverage / max-reducible off gross collateral is the common UI bug
+ * (a position shows e.g. 23.3x on gross while the contract sees ~24.9x on effective).
+ *
+ * All inputs are human-readable USD. Convert raw collateral-token fee fields via
+ * `feeUsd = (rawFee / 10 ** collateralDecimal) * collateralPriceUsd`.
+ *
+ * @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 tradingFeeUsd           `unrealized_trading_fee` in USD.
+ * @param projectedTradingFeeUsd  Closing fee to reserve (0 for a bare collateral withdrawal).
+ */
+export declare function calcEffectiveCollateralUsd(params: {
+    grossCollateralUsd: number;
+    borrowFeeUsd: number;
+    fundingSign: boolean;
+    fundingFeeUsd: number;
+    tradingFeeUsd: number;
+    projectedTradingFeeUsd?: number;
+}): number;
+/**
+ * Maximum collateral (in USD) a position can safely withdraw ("最大可减少").
+ *
+ * Reproduces the three post-withdrawal checks in `execute_withdraw_collateral`
+ * (`trading.move`), all evaluated on **effective** (fee-adjusted) collateral, and
+ * returns the smallest allowed withdrawal:
+ *
+ *   (A) max leverage — `notional / (effLeverage − w) ≤ maxLeverage`
+ *   (B) min collateral — `(effLeverage − w) ≥ minCollValueUsd`
+ *   (C) not liquidatable — `(liqRemaining − w) > maintenanceMargin × notional`
+ *
+ * where
+ *   notional      = sizeInAsset × spotPrice
+ *   effLeverage   = effective collateral with projectedTradingFee = 0
+ *                   (the contract's leverage/min-coll checks ignore the closing fee and PnL)
+ *   liqRemaining  = grossCollateralUsd + signedPnl − borrow − trading − closingFee ∓ funding
+ *                   (the contract's `is_liquidatable` boundary; funding income is added back)
+ *
+ * The result is a USD figure (matching the "$X" the UI shows), already aligned so that
+ * converting it to raw collateral units with floor is abort-safe:
+ *   `rawAmount = floor((maxReducibleUsd / collateralPriceUsd) * 10 ** collateralDecimal)`.
+ * The liquidation leg backs off one raw collateral unit because `is_liquidatable` aborts
+ * on `remaining <= maintenance` (inclusive) — the safe withdrawal must leave remaining
+ * *strictly* above maintenance. The leverage (`> max`) and min-collateral (`>=`) checks
+ * are equality-safe on their own and floor-rounding only adds margin, so they need no offset.
+ *
+ * Funding handling is signed (income added, expense subtracted) — a close approximation
+ * of the contract's deficit-aware sequencing, exact whenever the position is solvent
+ * (the only case where a withdrawal can succeed). Clamps at 0.
+ *
+ * @param maxLeverage             Max leverage as a ratio (e.g. 25 for `max_leverage_bps` 250000).
+ * @param maintenanceMarginRate   `maintenance_margin` as a fraction (e.g. 0.01 for 1%).
+ * @param minCollValueUsd         `min_coll_value` in USD (raw scaled value ÷ 1e9).
+ * @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.
+ */
+export declare function calcMaxReducibleCollateralUsd(params: {
+    grossCollateralUsd: number;
+    sizeInAsset: number;
+    spotPrice: number;
+    isLong: boolean;
+    entryPrice: number;
+    maxLeverage: number;
+    maintenanceMarginRate: number;
+    minCollValueUsd: number;
+    borrowFeeUsd: number;
+    tradingFeeUsd: number;
+    closingFeeUsd: number;
+    fundingSign: boolean;
+    fundingFeeUsd: number;
+    collateralPriceUsd: number;
+    collateralDecimal: number;
+}): number;
+/**
+ * Impact fee rate for an order (as a fraction, not bps).
+ *
+ * Matches `calculate_impact_fee` in `trading.move`. Returns 0 when the order
+ * reduces LP risk (new LP exposure ≤ original). Caller adds this to the base
+ * trading fee rate to get the total fee rate.
+ *
+ * @param longOi                Current long open interest in base tokens.
+ * @param shortOi               Current short open interest in base tokens.
+ * @param orderIsLong           Direction of the order.
+ * @param orderSize             Size of the order in base tokens.
+ * @param executionPrice        Execution price (USD per base token).
+ * @param maxImpactFee          Max impact fee rate (e.g. 0.0003).
+ * @param allocatedLpExposureBps Bps of pool TVL allocated as LP exposure cap.
+ * @param poolTvlUsd            Total pool TVL in USD.
+ * @param curvature             Impact fee curve curvature exponent (default 1).
+ * @param scale                 Impact fee curve scale (default 1).
+ */
+export declare function calcImpactFeeRate(params: {
+    longOi: number;
+    shortOi: number;
+    orderIsLong: boolean;
+    orderSize: number;
+    executionPrice: number;
+    maxImpactFee: number;
+    allocatedLpExposureBps: number;
+    poolTvlUsd: number;
+    curvature?: number;
+    scale?: number;
+}): number;
+/** Total trading fee rate = base fee + impact fee. */
+export declare function calcTotalTradingFeeRate(baseFeeRate: number, impactFeeRate: number): number;
+/**
+ * Per-interval funding rate for a market.
+ *
+ * Matches `calculate_funding_rate` in `market_config.move`.
+ * OI values must be in USD (multiply raw OI by base price before calling).
+ *
+ * @returns `{ sign, rate }` where sign=true means longs pay shorts.
+ */
+export declare function calcFundingRate(longOiUsd: number, shortOiUsd: number, basicRate: number, tvlUsd: number): {
+    sign: boolean;
+    rate: number;
+};
+/**
+ * Funding fee in USD for a position over a period.
+ *
+ * Simplified from `calculate_funding_fee` in `position.move` for off-chain estimation.
+ * For exact on-chain accounting use the Double-precision index from `position.move`.
+ *
+ * @param sizeInAsset        Position size in base tokens.
+ * @param deltaIndexUsdPerAsset  Change in cumulative funding index (USD per base token).
+ * @param positionIsLong     Position direction.
+ * @param fundingSignIsLong  True if the current funding interval charges longs.
+ */
+export declare function calcFundingFeeUsd(sizeInAsset: number, deltaIndexUsdPerAsset: number, positionIsLong: boolean, fundingSignIsLong: boolean): number;
+/**
+ * Decode raw Double-precision cumulative funding index delta into USD per base token.
+ *
+ * Raw index values from on-chain use Double scale (1e18). This converts them to
+ * human-readable form (USD per base token) so they can be passed to `calcFundingFeeUsd`.
+ */
+export declare function decodeFundingIndexDelta(rawDelta: bigint): number;
+/**
+ * Per-interval borrow rate using the 3-slope utilization curve.
+ *
+ * Matches `calculate_borrow_rate` in `lp_pool.move`.
+ * Rates are Float values (e.g. 0.000001 per interval).
+ */
+export declare function calcBorrowRate(utilizationBps: number, rate0: number, rate1: number, rate2: number, threshold0Bps: number, threshold1Bps: number): number;
+/**
+ * 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.
+ */
+export declare function calcBorrowRateAccrual(borrowRate: number, elapsedMs: number, intervalMs: number): number;
+/**
+ * Unrealized borrow fee delta for a position (in raw collateral token units).
+ *
+ * Matches `calculate_borrow_fee` in `position.move`.
+ * Returns 0 when cumulative rate has not advanced past the entry index.
+ *
+ * @param borrowReserveAmount   Position's borrow reserve in raw collateral units.
+ * @param cumulativeBorrowRate  Current cumulative borrow rate (Float).
+ * @param entryBorrowIndex      Cumulative borrow rate at position entry (Float).
+ */
+export declare function calcPositionBorrowFee(borrowReserveAmount: number, cumulativeBorrowRate: number, entryBorrowIndex: number): number;
+/** Token utilization in bps: reservedAmount / liquidityAmount × BPS_SCALE. */
+export declare function calcTokenUtilizationBps(reservedAmount: number, liquidityAmount: number): number;
+/**
+ * Annualize a per-interval funding rate.
+ *
+ * @param rate        Per-interval funding rate (e.g. from `calcFundingRate`).
+ * @param intervalMs  Funding interval in milliseconds (e.g. 3_600_000 for 1H).
+ */
+export declare function annualizeFundingRate(rate: number, intervalMs: number): 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).
+ *
+ * @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.
+ */
+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.
+ *
+ * @param apr  Time-weighted incentive APR as a decimal fraction (e.g. 0.12 for 12%).
+ */
+export declare function calcWlpIncentiveApy(apr: number): number;
+/**
+ * WLP share price in USD.
+ *
+ * @param tvlUsd      Total pool TVL in USD (AUM equity).
+ * @param totalSupply Total WLP supply (in raw LP token units).
+ * @param lpDecimals  WLP token decimals (6).
+ */
+export declare function calcWlpPrice(tvlUsd: number, totalSupply: number, lpDecimals: number): number;
+/**
+ * WLP tokens minted for a deposit (post-fee net deposit).
+ *
+ * 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.
+ *
+ * @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).
+ */
+export declare function calcWlpMintOut(netDepositUsd: number, tvlUsd: number, totalSupply: number, lpDecimals: number): number;
+/**
+ * Raw token amount redeemable for a given LP amount (before burn fee).
+ *
+ * Matches the settlement formula in `settle_redeem_with_pricing_tvl` in `lp_pool.move`.
+ * Apply `calcDynamicFeeBps` separately to get the net 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.
+ */
+export declare function calcWlpRedeemOut(lpAmount: number, tvlUsd: number, totalSupply: number, tokenPriceUsd: number, tokenDecimals: number): number;
+/**
+ * Dynamic mint/burn fee in bps based on weight deviation.
+ *
+ * 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.
+ *
+ * @param tokenValueUsd      Current USD value of this token in the pool.
+ * @param tvlUsd             Total pool TVL in USD.
+ * @param operationValueUsd  USD value of the deposit or withdrawal.
+ * @param targetWeightBps    Target allocation weight for this token (bps).
+ * @param baseFeeBps         Base mint/burn fee (bps).
+ * @param isDeposit          True for mint, false for redeem.
+ */
+export declare function calcDynamicFeeBps(tokenValueUsd: number, tvlUsd: number, operationValueUsd: number, targetWeightBps: number, baseFeeBps: number, isDeposit: boolean): number;