@waterx/sdk 3.0.1 → 3.0.3

package/dist/cjs/src/unified-client.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Umbrella WaterX SDK client — the main entry point.
+ *
+ * Exposes three namespaces over the two product-line sub-clients:
+ *
+ *   const client = await WaterXClient.create({ network: "TESTNET" });
+ *   client.account.createAccount(tx, { alias });   // -> shared waterx_account + funding
+ *   client.perp.placeOrderRequest(tx, params);     // -> perp builder
+ *   client.predict.placeOrder(tx, params);         // -> prediction builder
+ *
+ * `client.perp` **is** the `PerpClient` instance with the perp builder/view
+ * methods grafted on, and `client.predict` **is** the `PredictClient` instance
+ * likewise — so signing & execution live on the same object
+ * (`client.perp.signAndExecuteTransaction(...)`) right next to the builders.
+ * There are no separate `.perpClient` / `.predictClient` accessors.
+ *
+ * `client.account` is a thin namespace (no own client) bound to the perp
+ * sub-client: the perp config carries the shared `waterx_account` registry plus
+ * the bridge / native_custody / withdrawal_queue / credit_registry that the
+ * credit & custody builders read. `waterx_account` is one shared on-chain object,
+ * so an account created here serves both lines — except when the two lines target
+ * different networks (`opts.perp.network !== opts.predict.network`), where
+ * `client.account` follows the perp line; split-network callers should reach the
+ * predict line's generic account builders via the `prediction` namespace directly.
+ *
+ * Each namespace method forwards to the existing free-function builder with the
+ * line's client pre-bound as the first argument; builders are build-only (they
+ * return / mutate a `Transaction`), so frontend wallet flows and multi-step Pyth
+ * injection keep working.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaterXClient = void 0;
+// Unified account namespace: generic waterx_account framework + funding (credit + custody).
+const accountOps = __importStar(require("./account/index.js"));
+const perpReferral = __importStar(require("./account/referral.js"));
+const client_ts_1 = require("./perp/client.js");
+// Perp builder/view modules (every export takes the client as its first arg).
+const perpFetch = __importStar(require("./perp/fetch.js"));
+const perpTx = __importStar(require("./perp/tx-builders.js"));
+// Perp-only user builders — account/credit/custody are excluded here; they live
+// under `client.account`. trading / order / wlp / staking / referral only.
+const perpOrder = __importStar(require("./perp/user/order.js"));
+const perpStaking = __importStar(require("./perp/user/staking.js"));
+const perpTrading = __importStar(require("./perp/user/trading.js"));
+const perpWlp = __importStar(require("./perp/user/wlp.js"));
+// Prediction-specific account ops (need the prediction package; NOT generic account).
+const account_ts_1 = require("./prediction/account.js");
+const predAdmin = __importStar(require("./prediction/admin.js"));
+const client_ts_2 = require("./prediction/client.js");
+const predFetch = __importStar(require("./prediction/fetch.js"));
+const predGift = __importStar(require("./prediction/gift.js"));
+const predOps = __importStar(require("./prediction/prediction.js"));
+const tx_builders_ts_1 = require("./prediction/tx-builders.js");
+/**
+ * Exports from the spread builder/view modules that are NOT client-first — their
+ * first argument is not the line client, so they must not become bound facade
+ * methods (binding would pass the client where a value is expected). This is the
+ * single source of truth shared by the runtime (skip) and the type (`Omit`).
+ * Keep in sync by auditing `export function` first-params across the spread modules.
+ */
+const NON_CLIENT_FIRST = [
+    "extractReturnBytes",
+    // gift.ts — pure crypto / URL helpers (first arg is not PredictClient)
+    "base64UrlNoPadEncode",
+    "base64UrlNoPadDecode",
+    "generateGiftSeed",
+    "encodeGiftUrl",
+    "parseGiftUrl",
+    "deriveGiftKeypair",
+    "buildGiftClaimMessage",
+    "signGiftClaim",
+];
+const NON_CLIENT_FIRST_SET = new Set(NON_CLIENT_FIRST);
+function bindClient(client, ns) {
+    const out = {};
+    for (const key of Object.keys(ns)) {
+        if (NON_CLIENT_FIRST_SET.has(key))
+            continue; // not client-first → not a facade method
+        const value = ns[key];
+        out[key] =
+            typeof value === "function"
+                ? (...args) => value(client, ...args)
+                : value;
+    }
+    return out;
+}
+// Prediction-specific account ops kept on `client.predict` (generic account ops
+// moved to `client.account`).
+const predAccountSpecific = {
+    setDelegatePredictionPermission: account_ts_1.setDelegatePredictionPermission,
+    whitelistPredictionProtocol: account_ts_1.whitelistPredictionProtocol,
+    allowPredictionProtocolAsset: account_ts_1.allowPredictionProtocolAsset,
+    disallowPredictionProtocolAsset: account_ts_1.disallowPredictionProtocolAsset,
+};
+// Frozen, reused for both the runtime binding and the public module types.
+const perpOps = {
+    ...perpTrading,
+    ...perpOrder,
+    ...perpWlp,
+    ...perpStaking,
+    ...perpReferral,
+    ...perpTx,
+    ...perpFetch,
+};
+const predictOps = { ...predAccountSpecific, ...predAdmin, ...predOps, ...predFetch, ...predGift };
+class WaterXClient {
+    /** Shared account namespace (`client.account.createAccount(tx, params)`) — perp-backed. */
+    account;
+    /**
+     * Perp sub-client **with** the perp builders/views grafted on
+     * (`client.perp.placeOrderRequest(...)`, `client.perp.signAndExecuteTransaction(...)`).
+     */
+    perp;
+    /**
+     * Prediction sub-client **with** the prediction builders/views grafted on
+     * (`client.predict.placeOrder(...)`, `client.predict.signAndExecuteTransaction(...)`).
+     */
+    predict;
+    /**
+     * Async prediction builder: optional consolidate + `placeOrder`.
+     * Uses the perp client for the sweep and the predict client for the bet leg.
+     */
+    buildPredictPlaceOrderTx(params) {
+        return (0, tx_builders_ts_1.buildPlaceOrderTx)(this.perp, this.predict, params);
+    }
+    /**
+     * Async prediction builder: optional consolidate + `batchClaim`.
+     */
+    buildPredictBatchClaimTx(params) {
+        return (0, tx_builders_ts_1.buildBatchClaimTx)(this.perp, this.predict, params);
+    }
+    constructor(perpClient, predictClient) {
+        // Graft the bound builders onto the sub-client instances. No builder name
+        // collides with the client's own (transport/config) methods — enforced by the
+        // "graft guard" unit test (disjoint from the prototype chain), not just a
+        // comment. The instances stay `instanceof PerpClient` / `PredictClient`, so
+        // signing/config methods work.
+        this.perp = Object.assign(perpClient, bindClient(perpClient, perpOps));
+        this.predict = Object.assign(predictClient, bindClient(predictClient, predictOps));
+        this.account = bindClient(perpClient, accountOps);
+    }
+    /**
+     * Combine two pre-built line clients (advanced — full control over each).
+     * Note: this grafts the bound builder methods onto the provided client
+     * instances in place.
+     */
+    static fromClients(perpClient, predictClient) {
+        return new WaterXClient(perpClient, predictClient);
+    }
+    /**
+     * Async factory — loads each line's deployment config (from the canonical
+     * `waterx-config` JSON) and returns a ready client. Each line can target a
+     * different network via `opts.perp.network` / `opts.predict.network`.
+     */
+    static async create(opts = {}) {
+        const baseNetwork = opts.network ?? "TESTNET";
+        const { network: perpNetwork, ...perpRest } = opts.perp ?? {};
+        const { network: predictNetwork, ...predictRest } = opts.predict ?? {};
+        const resolvedPerpNetwork = perpNetwork ?? baseNetwork;
+        const resolvedPredictNetwork = predictNetwork ?? baseNetwork;
+        if (resolvedPerpNetwork !== resolvedPredictNetwork) {
+            // `client.account` always follows the perp line (see the class header).
+            // On a split-network setup a caller reaching for `client.account.*` would
+            // silently build against the perp deployment — warn so it isn't a surprise.
+            console.warn(`[WaterXClient] split-network: perp=${resolvedPerpNetwork} predict=${resolvedPredictNetwork}. ` +
+                `client.account follows the perp line (${resolvedPerpNetwork}); reach the predict line's ` +
+                `generic account builders via the prediction namespace directly.`);
+        }
+        const perpClient = await client_ts_1.PerpClient.create(resolvedPerpNetwork, {
+            grpcUrl: opts.grpcUrl,
+            configUrl: opts.configUrl,
+            cache: opts.cache,
+            ...perpRest,
+        });
+        const predictClient = await client_ts_2.PredictClient.create(resolvedPredictNetwork, {
+            grpcUrl: opts.grpcUrl,
+            configUrl: opts.configUrl,
+            cache: opts.cache,
+            ...predictRest,
+        });
+        return new WaterXClient(perpClient, predictClient);
+    }
+}
+exports.WaterXClient = WaterXClient;

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

@@ -0,0 +1,11 @@
+import type { WaterXConfig } from "../perp/config.ts";
+/** Returns all registered market tickers (e.g. "BTCUSD") from waterx-config. */
+export declare function getMarketTickers(config: WaterXConfig): string[];
+/**
+ * Returns WLP pool-token tickers that also have a registered pyth_rule feed —
+ * the canonical testnet config keys `pool_tokens` by coin symbol (e.g. `"USD"`)
+ * while `pyth_rule.feeds` is keyed by oracle ticker (e.g. `"USDCUSD"`), so a
+ * naive `Object.keys(pool_tokens)` blows up at `refreshOraclePrices` for any
+ * key without a feed. Filter so the auto-refresh path stays tolerant.
+ */
+export declare function getCollateralAssets(config: WaterXConfig): string[];

package/dist/cjs/src/utils/config.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMarketTickers = getMarketTickers;
+exports.getCollateralAssets = getCollateralAssets;
+/** Returns all registered market tickers (e.g. "BTCUSD") from waterx-config. */
+function getMarketTickers(config) {
+    return Object.keys(config.packages.waterx_perp.markets);
+}
+/**
+ * Returns WLP pool-token tickers that also have a registered pyth_rule feed —
+ * the canonical testnet config keys `pool_tokens` by coin symbol (e.g. `"USD"`)
+ * while `pyth_rule.feeds` is keyed by oracle ticker (e.g. `"USDCUSD"`), so a
+ * naive `Object.keys(pool_tokens)` blows up at `refreshOraclePrices` for any
+ * key without a feed. Filter so the auto-refresh path stays tolerant.
+ */
+function getCollateralAssets(config) {
+    const feeds = config.packages.pyth_rule?.feeds ?? {};
+    return Object.keys(config.packages.wlp.pool_tokens).filter((t) => feeds[t] !== undefined);
+}

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;