@waterx/sdk 2.1.0 → 2.4.0

package/dist/src/user/credit.d.ts

@@ -10,7 +10,8 @@
  *     `enqueueWithdrawal` parks a FIFO `Queue<CREDIT>` entry.
  *   - Keeper drains the queue via `executeWithdrawalWormhole` /
  *     `executeWithdrawalNative` (caller must be on the executor allowlist).
- *   - PSM: `custodyMint` / `custodyBurn` against the native `CustodyVault`.
+ *   - PSM: `custodyMint` against the native `CustodyVault` (direct burn was
+ *     removed — audit L03/M14; redeem via the withdraw queue path above).
  *
  * Every builder that emits a hot potato returns its argument so the caller
  * (or the high-level `tx-builders.ts` wrappers) can pair + consume it in the
@@ -55,6 +56,12 @@ export declare function routeWormhole(client: WaterXClient, tx: Transaction, par
 export interface RouteNativeParams {
     /** Fully-qualified backing asset Move type `T` (e.g. via `client.getNativeAsset`). */
     assetType: string;
+    /**
+     * Minimum `Coin<T>` the user will accept after the native burn fee;
+     * `execute_native` aborts `EOutputBelowMin` if a later fee change would
+     * deliver less (audit M15). Defaults to `0` (opt out).
+     */
+    minOutput?: bigint | number;
 }
 /** Build `withdrawal_queue::route_native<T>`. Returns the `extra_data` argument. */
 export declare function routeNative(client: WaterXClient, tx: Transaction, params: RouteNativeParams): TransactionArgument;
@@ -120,16 +127,3 @@ export interface CustodyMintParams {
  * {@link consumeCreditDeposit}).
  */
 export declare function custodyMint(client: WaterXClient, tx: Transaction, params: CustodyMintParams): TransactionArgument;
-export interface CustodyBurnParams {
-    /** wxa account ID the burned CREDIT belongs to (cap / fee key). */
-    accountId: string;
-    /** `Coin<CREDIT>` to burn. */
-    creditCoin: TransactionArgument;
-    assetType: string;
-    creditType?: string;
-}
-/**
- * Build `native_custody::custody_vault::burn<T, CREDIT>`. Returns the
- * resulting `Coin<T>` argument.
- */
-export declare function custodyBurn(client: WaterXClient, tx: Transaction, params: CustodyBurnParams): TransactionArgument;

package/dist/src/user/credit.js

@@ -10,14 +10,16 @@
  *     `enqueueWithdrawal` parks a FIFO `Queue<CREDIT>` entry.
  *   - Keeper drains the queue via `executeWithdrawalWormhole` /
  *     `executeWithdrawalNative` (caller must be on the executor allowlist).
- *   - PSM: `custodyMint` / `custodyBurn` against the native `CustodyVault`.
+ *   - PSM: `custodyMint` against the native `CustodyVault` (direct burn was
+ *     removed — audit L03/M14; redeem via the withdraw queue path above).
  *
  * Every builder that emits a hot potato returns its argument so the caller
  * (or the high-level `tx-builders.ts` wrappers) can pair + consume it in the
  * same PTB.
  */
 import { fromHex } from "@mysten/bcs";
-import { burn as custodyBurnCall, mint as custodyMintCall, } from "../generated/native_custody/custody_vault.js";
+import { normalizeStructTag } from "@mysten/sui/utils";
+import { mint as custodyMintCall } from "../generated/native_custody/custody_vault.js";
 import { requestWithdraw as requestWithdrawCall } from "../generated/waterx_account/account.js";
 import { consumeDepositDirect } from "../generated/waterx_account/direct_rule.js";
 import { enqueue as enqueueCall, executeNative as executeNativeCall, executeWormhole as executeWormholeCall, routeNative as routeNativeCall, routeWormhole as routeWormholeCall, } from "../generated/withdrawal_queue/withdrawal_queue.js";
@@ -45,7 +47,7 @@ function toEvmAddressBytes(input, field) {
     return bytes;
 }
 function creditTypeOf(client, override) {
-    return override ?? client.creditType();
+    return normalizeStructTag(override ?? client.creditType());
 }
 // Required-ID accessors: the credit/bridge package entries carry their
 // shared object ids only after the relevant deploy phase has run, so each
@@ -143,7 +145,8 @@ export function routeWormhole(client, tx, params) {
 export function routeNative(client, tx, params) {
     const out = routeNativeCall({
         package: queuePkg(client),
-        typeArguments: [params.assetType],
+        arguments: { minOutput: BigInt(params.minOutput ?? 0n) },
+        typeArguments: [normalizeStructTag(params.assetType)],
     })(tx);
     return out;
 }
@@ -213,7 +216,7 @@ export function executeWithdrawalNative(client, tx, params) {
             vault: tx.object(custodyVaultId(client)),
             creditRegistry: tx.object(creditRegistryId(client)),
         },
-        typeArguments: [params.assetType, creditTypeOf(client, params.creditType)],
+        typeArguments: [normalizeStructTag(params.assetType), creditTypeOf(client, params.creditType)],
     })(tx);
 }
 /**
@@ -232,24 +235,7 @@ export function custodyMint(client, tx, params) {
             assetCoin: params.assetCoin,
             extraData: toBytes(params.extraData ?? new Uint8Array()),
         },
-        typeArguments: [params.assetType, creditTypeOf(client, params.creditType)],
+        typeArguments: [normalizeStructTag(params.assetType), creditTypeOf(client, params.creditType)],
     })(tx);
     return req;
 }
-/**
- * Build `native_custody::custody_vault::burn<T, CREDIT>`. Returns the
- * resulting `Coin<T>` argument.
- */
-export function custodyBurn(client, tx, params) {
-    const out = custodyBurnCall({
-        package: custodyPkg(client),
-        arguments: {
-            vault: tx.object(custodyVaultId(client)),
-            registry: tx.object(creditRegistryId(client)),
-            accountId: params.accountId,
-            creditCoin: params.creditCoin,
-        },
-        typeArguments: [params.assetType, creditTypeOf(client, params.creditType)],
-    })(tx);
-    return out;
-}

package/dist/src/user/custody.d.ts

@@ -1,15 +1,16 @@
 /**
  * Builders for `native_custody::custody_vault` — the Sui-native PSM that
  * mints the protocol CREDIT CoinType 1:1 against backing stable assets `T`
- * (CCTP USDC, USDT, …) and burns it back the other way.
+ * (CCTP USDC, USDT, …).
  *
  * `mintCredit` / `mintCreditFromRequest` return a `DepositRequest<CREDIT>`
  * hot potato — it must be consumed in the same PTB by the deposit policy
  * registered for CREDIT (the canonical policy is `direct_rule::DirectRule`).
  * `mintCreditToAccount` chains that consume for you.
  *
- * `burnCredit` returns the redeemed `Coin<T>`; the caller decides where it
- * goes (transfer, fold back into a wxa account, …).
+ * There is no direct burn builder: the contract removed witness-free
+ * `custody_vault::burn` (audit L03/M14). CREDIT redemption routes through
+ * requestCreditWithdraw -> enqueueWithdrawal -> keeper executeWithdrawalNative.
  *
  * Requires `waterx_credit` + `native_custody` in the loaded config — both
  * are optional in `WaterXConfig` since not every deployment ships the
@@ -54,18 +55,3 @@ export declare function mintCreditFromRequest(client: WaterXClient, tx: Transact
  * Assumes CREDIT's deposit policy is `DirectRule` (the canonical setup).
  */
 export declare function mintCreditToAccount(client: WaterXClient, tx: Transaction, params: MintCreditParams): void;
-export interface BurnCreditParams {
-    /** wxa account ID the burned CREDIT belongs to (burn-cap + partner-fee key). */
-    accountId: string;
-    /** `Coin<CREDIT>` to redeem. */
-    creditCoin: TransactionArgument;
-    /** Fully-qualified backing-asset Move type `T` to redeem into. */
-    assetType: string;
-    /** CREDIT CoinType. Defaults to `client.creditType()`. */
-    creditType?: string;
-}
-/**
- * Build `custody_vault::burn<T, CREDIT>`. Returns the redeemed `Coin<T>`
- * argument for the caller to forward.
- */
-export declare function burnCredit(client: WaterXClient, tx: Transaction, params: BurnCreditParams): TransactionArgument;

package/dist/src/user/custody.js

@@ -1,20 +1,22 @@
 /**
  * Builders for `native_custody::custody_vault` — the Sui-native PSM that
  * mints the protocol CREDIT CoinType 1:1 against backing stable assets `T`
- * (CCTP USDC, USDT, …) and burns it back the other way.
+ * (CCTP USDC, USDT, …).
  *
  * `mintCredit` / `mintCreditFromRequest` return a `DepositRequest<CREDIT>`
  * hot potato — it must be consumed in the same PTB by the deposit policy
  * registered for CREDIT (the canonical policy is `direct_rule::DirectRule`).
  * `mintCreditToAccount` chains that consume for you.
  *
- * `burnCredit` returns the redeemed `Coin<T>`; the caller decides where it
- * goes (transfer, fold back into a wxa account, …).
+ * There is no direct burn builder: the contract removed witness-free
+ * `custody_vault::burn` (audit L03/M14). CREDIT redemption routes through
+ * requestCreditWithdraw -> enqueueWithdrawal -> keeper executeWithdrawalNative.
  *
  * Requires `waterx_credit` + `native_custody` in the loaded config — both
  * are optional in `WaterXConfig` since not every deployment ships the
  * credit pipeline.
  */
+import { normalizeStructTag } from "@mysten/sui/utils";
 import * as custody from "../generated/native_custody/custody_vault.js";
 import { consumeDepositDirect } from "../generated/waterx_account/direct_rule.js";
 function requireCredit(client) {
@@ -48,7 +50,10 @@ export function mintCredit(client, tx, params) {
             assetCoin: params.assetCoin,
             extraData: Array.from(params.extraData ?? new Uint8Array()),
         },
-        typeArguments: [params.assetType, params.creditType ?? client.creditType()],
+        typeArguments: [
+            normalizeStructTag(params.assetType),
+            normalizeStructTag(params.creditType ?? client.creditType()),
+        ],
     })(tx);
     return req;
 }
@@ -68,7 +73,10 @@ export function mintCreditFromRequest(client, tx, params) {
             accountRegistry: tx.object(client.config.packages.waterx_account.account_registry),
             depositRequest: params.depositRequest,
         },
-        typeArguments: [params.assetType, params.creditType ?? client.creditType()],
+        typeArguments: [
+            normalizeStructTag(params.assetType),
+            normalizeStructTag(params.creditType ?? client.creditType()),
+        ],
     })(tx);
     return req;
 }
@@ -88,25 +96,6 @@ export function mintCreditToAccount(client, tx, params) {
             registry: tx.object(client.config.packages.waterx_account.account_registry),
             req: req,
         },
-        typeArguments: [params.creditType ?? client.creditType()],
+        typeArguments: [normalizeStructTag(params.creditType ?? client.creditType())],
     })(tx);
 }
-/**
- * Build `custody_vault::burn<T, CREDIT>`. Returns the redeemed `Coin<T>`
- * argument for the caller to forward.
- */
-export function burnCredit(client, tx, params) {
-    const credit = requireCredit(client);
-    const nc = requireCustody(client);
-    const [coin] = custody.burn({
-        package: nc.published_at,
-        arguments: {
-            vault: tx.object(nc.vault),
-            registry: tx.object(credit.credit_registry),
-            accountId: params.accountId,
-            creditCoin: params.creditCoin,
-        },
-        typeArguments: [params.assetType, params.creditType ?? client.creditType()],
-    })(tx);
-    return coin;
-}

package/dist/src/utils/consolidate-balance.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared probe helpers for {@link appendConsolidateToUsd} and
+ * {@link getSpendableCreditBalance} — one asset list, one gRPC read pattern,
+ * so display totals match what the next async tx-builder would sweep.
+ */
+import type { WaterXClient } from "../client.ts";
+/** CREDIT parked at a wxa account's Sui address (funds accumulator + owned coins). */
+export interface AddressCreditBalance {
+    /** `getBalance.addressBalance` — funds accumulator path. */
+    fundsRaw: bigint;
+    /** Sum of `listCoins` object balances — TTO'd / owned `Coin<CREDIT>` path. */
+    coinsRaw: bigint;
+}
+/** One native-custody backing asset parked at a wxa account's Sui address. */
+export interface ParkedBackingAssetBalance {
+    assetType: string;
+    decimals: number;
+    /** `getBalance.addressBalance` — funds accumulator (`send_funds` path). */
+    fundsRaw: bigint;
+    /** Sum of `listCoins` object balances — TTO'd / owned `Coin<T>` path. */
+    coinsRaw: bigint;
+}
+/** Rescale a u64 raw amount between token decimal precisions (truncates on downscale). */
+export declare function rescaleRawAmount(raw: bigint, fromDecimals: number, toDecimals?: number): bigint;
+/**
+ * Probe every backing asset registered on `native_custody` for non-zero balances
+ * parked at `accountId`'s Sui address. Matches the pre-tx scan inside
+ * {@link appendConsolidateToUsd}.
+ */
+export declare function probeParkedBackingAssets(client: WaterXClient, accountId: string): Promise<ParkedBackingAssetBalance[]>;
+/**
+ * Probe non-zero CREDIT parked at `accountId`'s Sui address. Matches the
+ * address-CREDIT legs inside {@link appendConsolidateAddressCredit}.
+ */
+export declare function probeAddressCreditBalance(client: WaterXClient, accountId: string): Promise<AddressCreditBalance>;
+/** Sum parked backing assets into CREDIT base units at the 1:1 PSM peg. */
+export declare function sumParkedBackingAsCreditRaw(parked: readonly ParkedBackingAssetBalance[], creditDecimals?: number): bigint;

package/dist/src/utils/consolidate-balance.js

@@ -0,0 +1,89 @@
+import { COLLATERAL_DECIMALS } from "../constants.js";
+/** Rescale a u64 raw amount between token decimal precisions (truncates on downscale). */
+export function rescaleRawAmount(raw, fromDecimals, toDecimals = COLLATERAL_DECIMALS) {
+    if (fromDecimals === toDecimals)
+        return raw;
+    if (fromDecimals < toDecimals) {
+        return raw * 10n ** BigInt(toDecimals - fromDecimals);
+    }
+    return raw / 10n ** BigInt(fromDecimals - toDecimals);
+}
+/**
+ * Probe every backing asset registered on `native_custody` for non-zero balances
+ * parked at `accountId`'s Sui address. Matches the pre-tx scan inside
+ * {@link appendConsolidateToUsd}.
+ */
+export async function probeParkedBackingAssets(client, accountId) {
+    if (!client.config.packages.native_custody?.vault)
+        return [];
+    if (!client.config.packages.waterx_credit?.credit_type)
+        return [];
+    const out = [];
+    for (const asset of client.getNativeAssets()) {
+        const bal = (await client.getBalance({
+            owner: accountId,
+            coinType: asset.type,
+        }));
+        const fundsRaw = BigInt(bal.balance?.addressBalance ?? "0");
+        const coins = (await client.listCoins({
+            owner: accountId,
+            coinType: asset.type,
+        }));
+        let coinsRaw = 0n;
+        for (const coin of coins.objects ?? []) {
+            coinsRaw += BigInt(coin.balance ?? "0");
+        }
+        if (fundsRaw > 0n || coinsRaw > 0n) {
+            out.push({
+                assetType: asset.type,
+                decimals: asset.decimal,
+                fundsRaw,
+                coinsRaw,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Probe non-zero CREDIT parked at `accountId`'s Sui address. Matches the
+ * address-CREDIT legs inside {@link appendConsolidateAddressCredit}.
+ */
+export async function probeAddressCreditBalance(client, accountId) {
+    if (!client.config.packages.waterx_credit?.credit_type) {
+        return { fundsRaw: 0n, coinsRaw: 0n };
+    }
+    const creditType = client.creditType();
+    let fundsRaw = 0n;
+    let coinsRaw = 0n;
+    try {
+        const bal = (await client.getBalance({
+            owner: accountId,
+            coinType: creditType,
+        }));
+        fundsRaw = BigInt(bal.balance?.addressBalance ?? "0");
+    }
+    catch {
+        // ignore — treat as zero parked funds
+    }
+    try {
+        const coins = (await client.listCoins({
+            owner: accountId,
+            coinType: creditType,
+        }));
+        for (const coin of coins.objects ?? []) {
+            coinsRaw += BigInt(coin.balance ?? "0");
+        }
+    }
+    catch {
+        // ignore — treat as zero owned coins
+    }
+    return { fundsRaw, coinsRaw };
+}
+/** Sum parked backing assets into CREDIT base units at the 1:1 PSM peg. */
+export function sumParkedBackingAsCreditRaw(parked, creditDecimals = COLLATERAL_DECIMALS) {
+    let sum = 0n;
+    for (const row of parked) {
+        sum += rescaleRawAmount(row.fundsRaw + row.coinsRaw, row.decimals, creditDecimals);
+    }
+    return sum;
+}

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

@@ -33,6 +33,92 @@ export declare function calcEstLiqPrice(params: {
     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).
  *

package/dist/src/utils/math.js

@@ -59,6 +59,106 @@ export function calcEstLiqPrice(params) {
     }
     return avgPrice * (1 + ratio);
 }
+/**
+ * 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 function calcEffectiveCollateralUsd(params) {
+    const { grossCollateralUsd, borrowFeeUsd, fundingSign, fundingFeeUsd, tradingFeeUsd, projectedTradingFeeUsd = 0, } = params;
+    const eff = grossCollateralUsd -
+        borrowFeeUsd -
+        tradingFeeUsd -
+        projectedTradingFeeUsd -
+        (fundingSign ? fundingFeeUsd : 0);
+    return Math.max(0, eff);
+}
+/**
+ * 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 function calcMaxReducibleCollateralUsd(params) {
+    const { grossCollateralUsd, sizeInAsset, spotPrice, isLong, entryPrice, maxLeverage, maintenanceMarginRate, minCollValueUsd, borrowFeeUsd, tradingFeeUsd, closingFeeUsd, fundingSign, fundingFeeUsd, collateralPriceUsd, collateralDecimal, } = params;
+    const notional = sizeInAsset * spotPrice;
+    // effLeverage: matches calculate_effective_collateral_amount(..., projectedTradingFee = 0).
+    const effLeverage = calcEffectiveCollateralUsd({
+        grossCollateralUsd,
+        borrowFeeUsd,
+        fundingSign,
+        fundingFeeUsd,
+        tradingFeeUsd,
+    });
+    // (A) max leverage and (B) min collateral, both bounded by effLeverage. Both checks
+    // pass at equality (`leverage_bps > max` / `collateral >= min`), so no offset needed.
+    const leverageHeadroom = maxLeverage > 0 ? effLeverage - notional / maxLeverage : effLeverage;
+    const minCollHeadroom = effLeverage - minCollValueUsd;
+    // (C) is_liquidatable: aborts on `remaining <= maintenance`, so the post-withdrawal
+    // remaining must stay STRICTLY above maintenance. Back off one raw collateral unit (the
+    // smallest withdrawable step) so the floored raw amount can never land on equality.
+    const signedPnl = calcUnrealizedPnl(isLong, entryPrice, spotPrice, sizeInAsset);
+    const liqRemaining = grossCollateralUsd +
+        signedPnl -
+        borrowFeeUsd -
+        tradingFeeUsd -
+        closingFeeUsd -
+        (fundingSign ? fundingFeeUsd : -fundingFeeUsd);
+    const maintenanceUsd = maintenanceMarginRate * notional;
+    const oneRawUnitUsd = collateralPriceUsd > 0 ? collateralPriceUsd / 10 ** collateralDecimal : 0;
+    const liquidationHeadroom = liqRemaining - maintenanceUsd - oneRawUnitUsd;
+    return Math.max(0, Math.min(leverageHeadroom, minCollHeadroom, liquidationHeadroom));
+}
 // ======== Impact fee ========
 /**
  * Cost integral used by the impact fee curve (internal helper).

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

@@ -46,20 +46,55 @@ export declare function updatePythPrices(tx: Transaction, client: WaterXClient,
     packageId: string;
 }): Promise<string[]>;
 /**
- * For a given ticker, build the collector → feed → aggregate chain that
- * refreshes the on-chain `Oracle` aggregator for that ticker.
+ * Aggregate one ticker's price into the shared `Oracle`: build a collector, feed
+ * every rule the ticker is configured for, then `aggregate`. The fed rule set must
+ * match the on-chain weighted set for the ticker — `aggregator::remove_outliers`
+ * aborts `EMissingPriceSource` if a weighted rule is missing from the collector:
  *
- * Caller must have first called `buildPythPriceUpdateCalls` /
- * `updatePythPrices` so the corresponding `PriceInfoObject` is fresh.
+ * - **Pyth** — fed when `priceInfoObjectId` is supplied (i.e. the ticker has a
+ *   `pyth_rule.feeds` entry). Caller must run the Pyth update first so the
+ *   `PriceInfoObject` is fresh.
+ * - **Supra** — fed alongside Pyth when supra is enabled + wired (abstains on-chain
+ *   for symbols it has no pair for).
+ * - **Constant** — fed when the ticker is a constant ticker
+ *   ({@link WaterXClient.isConstantTicker}).
+ *
+ * "Dual-feed" (Pyth + Constant) and "constant-only" are not special cases — they
+ * fall out of which rules the ticker is in: a constant ticker that also has a Pyth
+ * feed gets both; one with no Pyth feed (no `priceInfoObjectId`) gets constant only.
+ * Throws if no rule applies to the ticker.
+ */
+export declare function aggregateTicker(tx: Transaction, client: WaterXClient, args: {
+    ticker: string;
+    priceInfoObjectId?: string;
+}): void;
+/**
+ * Thin wrapper over {@link aggregateTicker} for a Pyth-fed ticker. Kept for
+ * back-compat (e.g. WLP mint builds). Caller must run the Pyth update first.
  */
 export declare function aggregateTickerWithPyth(tx: Transaction, client: WaterXClient, args: {
     ticker: string;
     priceInfoObjectId: string;
 }): void;
 /**
- * Refresh multiple tickers via Pyth in one PTB. Updates Pyth on-chain
- * first (one accumulator), then runs the collector → feed → aggregate
- * cycle for each ticker.
+ * {@link aggregateTicker} for a **constant-only** ticker (no Pyth update needed —
+ * the price comes from the on-chain `constant_rule::Config`).
+ *
+ * Throws if the ticker ALSO has a `pyth_rule.feeds` entry (a dual-feed transition
+ * ticker): feeding only the constant leg would leave the still-weighted Pyth rule
+ * absent from the collector and abort `aggregate` with `EMissingPriceSource`. Such
+ * tickers must go through {@link aggregateTicker} with a `priceInfoObjectId` (or
+ * {@link refreshOraclePrices}), which feeds both.
+ */
+export declare function aggregateTickerWithConstant(tx: Transaction, client: WaterXClient, args: {
+    ticker: string;
+}): void;
+/**
+ * Refresh multiple tickers in one PTB. For each ticker {@link aggregateTicker}
+ * feeds whichever rules it is configured for (Pyth if it has a `pyth_rule.feeds`
+ * entry, Supra when enabled, Constant when it's a constant ticker). Tickers with a
+ * Pyth feed are updated on-chain via one shared Pyth accumulator first; the rest
+ * (constant-only) skip Pyth entirely.
  */
 export declare function refreshOraclePrices(tx: Transaction, client: WaterXClient, tickers: string[], opts?: {
     cache?: PythCache;