@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/math/auction.d.ts

@@ -2,25 +2,85 @@ import { Order, PositionDirection, StateAccount } from '../types';
 import { BN } from '../isomorphic/anchor';
 import { PerpMarketAccount } from '../types';
 import { MMOraclePriceData } from '../oracles/types';
+/** True if `order`'s auction has run its full `auctionDuration` (in slots) as of `slot`, or the order has no auction (`auctionDuration === 0`). */
 export declare function isAuctionComplete(order: Order, slot: number): boolean;
+/**
+ * True if the AMM is currently a permitted fallback liquidity source for `order`, mirroring the
+ * program's `amm_fill_gates_ok` (`state/perp_market.rs`) — the hard gates that suppress all AMM
+ * fills (standalone and JIT), not the auction-timing gates JIT bypasses, and not price/size (see
+ * `calculateBaseAssetAmountForAmmToFulfill` for that). Blocked if `AMM_FILL` is paused, if the
+ * market has too much drawdown, if the MM oracle is too volatile vs the exchange oracle (enabled +
+ * as-recent + >1% price diff — early volatility protection), or if the MM-oracle validity is
+ * `StaleForAMMLowRisk` or worse. If validity is exactly `Valid`, always allowed; otherwise (a
+ * degraded-but-not-stale oracle) only allowed when the order itself is low-risk for the AMM
+ * (`isLowRiskForAmm`) — e.g. it predates the oracle delay, is part of a liquidation, or carries
+ * the safe-trigger flag.
+ * @param order Order to check.
+ * @param mmOraclePriceData Current MM oracle price data — the MM-volatility gate reads its
+ *   `isMMOracleEnabled`/`isMMOracleAsRecent`/`isMMExchangeDiffBpsHigh` flags (populated by
+ *   `VelocityClient.getMMOracleDataForPerpMarket`); when those are absent the gate is skipped.
+ * @param slot Current slot.
+ * @param state Global state, providing oracle guard rails.
+ * @param market Perp market the order is on.
+ * @param isLiquidation Whether the fill is part of a liquidation (relaxes the low-risk check).
+ * @returns `true` if the AMM may currently act as a fallback liquidity source for this order.
+ */
 export declare function isFallbackAvailableLiquiditySource(order: Order, mmOraclePriceData: MMOraclePriceData, slot: number, state: StateAccount, market: PerpMarketAccount, isLiquidation?: boolean): boolean;
 /**
- *
- * @param order
- * @param slot
- * @param oraclePrice Use MMOraclePriceData source for perp orders, OraclePriceData for spot
- * @returns BN
+ * Dispatches to the correct in-progress auction price for `order` based on its order type:
+ * fixed-price auction (`getAuctionPriceForFixedAuction`) for market/triggerLimit/plain-limit
+ * orders, or oracle-offset auction (`getAuctionPriceForOracleOffsetAuction`) for
+ * oracle-pegged limit/oracle/oracle-triggered-market orders. The result is always
+ * standardized to `tickSize`.
+ * @param order Order whose auction price to compute.
+ * @param slot Current slot.
+ * @param oraclePrice Use `MMOraclePriceData` source for perp orders, `OraclePriceData` for spot; PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Auction price at the current slot, PRICE_PRECISION (1e6).
+ * @throws if `order.orderType` doesn't match any known auction pricing path.
+ */
+export declare function getAuctionPrice(order: Order, slot: number, oraclePrice: BN, tickSize?: BN): BN;
+/**
+ * Linearly interpolates between `order.auctionStartPrice` and `order.auctionEndPrice` based
+ * on slots elapsed out of `order.auctionDuration`, then standardizes the result to
+ * `tickSize` in the order's favor (via `standardizePrice`) so every auction tick already
+ * lines up with the market's tick size. Returns the (standardized) end price directly once
+ * the auction is complete or has zero duration.
+ * @param order Order whose fixed-price auction to evaluate.
+ * @param slot Current slot.
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Auction price at the current slot, PRICE_PRECISION (1e6).
+ */
+export declare function getAuctionPriceForFixedAuction(order: Order, slot: number, tickSize?: BN): BN;
+/**
+ * Linearly interpolates the oracle price offset between `order.auctionStartPrice` and
+ * `order.auctionEndPrice` (both offsets from the oracle price, not absolute prices) based on
+ * slots elapsed out of `order.auctionDuration`, adds it to the live `oraclePrice`, floors it
+ * at `tickSize`, then standardizes the result to `tickSize` in the order's favor. Returns the
+ * (standardized, floored) end-offset price directly once the auction is complete or has zero
+ * duration.
+ * @param order Order whose oracle-offset auction to evaluate.
+ * @param slot Current slot.
+ * @param oraclePrice Use `MMOraclePriceData` source for perp orders, `OraclePriceData` for spot; PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Auction price at the current slot, PRICE_PRECISION (1e6).
  */
-export declare function getAuctionPrice(order: Order, slot: number, oraclePrice: BN): BN;
-export declare function getAuctionPriceForFixedAuction(order: Order, slot: number): BN;
+export declare function getAuctionPriceForOracleOffsetAuction(order: Order, slot: number, oraclePrice: BN, tickSize?: BN): BN;
 /**
- *
- * @param order
- * @param slot
- * @param oraclePrice Use MMOraclePriceData source for perp orders, OraclePriceData for spot
- * @returns
+ * Converts absolute auction start/end prices (and a desired limit price) into the
+ * oracle-offset form the program expects for oracle-pegged orders: offsets from the current
+ * oracle price rather than absolute prices. Derives `oraclePriceOffset` from `limitPrice -
+ * oraclePrice` when both are nonzero, falling back to `auctionEndPrice - oraclePrice` (±1,
+ * biased away from the oracle in the order's direction) otherwise. Optionally clamps the
+ * absolute start/end prices to `auctionPriceCaps` before converting.
+ * @param direction Order side; determines the ±1 bias when deriving a fallback offset.
+ * @param oraclePrice Current oracle price, PRICE_PRECISION (1e6).
+ * @param auctionStartPrice Desired absolute auction start price, PRICE_PRECISION (1e6).
+ * @param auctionEndPrice Desired absolute auction end price, PRICE_PRECISION (1e6).
+ * @param limitPrice Desired absolute limit price (0 to derive the offset purely from `auctionEndPrice`), PRICE_PRECISION (1e6).
+ * @param auctionPriceCaps Optional `{ min, max }` bounds (PRICE_PRECISION 1e6) to clamp the absolute start/end prices to before converting to offsets.
+ * @returns `auctionStartPrice`/`auctionEndPrice` as oracle offsets, and `oraclePriceOffset` for the limit price — all PRICE_PRECISION (1e6), relative to `oraclePrice`.
  */
-export declare function getAuctionPriceForOracleOffsetAuction(order: Order, slot: number, oraclePrice: BN): BN;
 export declare function deriveOracleAuctionParams({ direction, oraclePrice, auctionStartPrice, auctionEndPrice, limitPrice, auctionPriceCaps, }: {
     direction: PositionDirection;
     oraclePrice: BN;
@@ -37,9 +97,18 @@ export declare function deriveOracleAuctionParams({ direction, oraclePrice, auct
     oraclePriceOffset: BN;
 };
 /**
- *
- * @param params Use OraclePriceData.price for oraclePrice param
- * @returns
+ * Derives a reasonable auction start price for a newly-triggered trigger order, biasing off
+ * the current oracle price by an offset estimated from recent mark/oracle spread (or, if
+ * mark and oracle TWAPs have recently diverged or 24h volume is thin, a coarser
+ * TWAP-fraction fallback scaled by contract tier). Applies a further directional "start
+ * buffer" in bps (tighter for tier A/B markets) so the auction starts slightly aggressive,
+ * then clamps to `limitPrice` if one is given so the auction never starts past the user's
+ * limit.
+ * @param params.perpMarket Market providing TWAP stats and contract tier.
+ * @param params.direction Order side.
+ * @param params.oraclePrice Current oracle price — use `OraclePriceData.price`, PRICE_PRECISION (1e6).
+ * @param params.limitPrice Optional limit price to clamp the start price to, PRICE_PRECISION (1e6).
+ * @returns Auction start price, PRICE_PRECISION (1e6).
  */
 export declare function getTriggerAuctionStartPrice(params: {
     perpMarket: PerpMarketAccount;
@@ -48,9 +117,16 @@ export declare function getTriggerAuctionStartPrice(params: {
     limitPrice?: BN;
 }): BN;
 /**
- *
- * @param params Use OraclePriceData.price for oraclePrice param and MMOraclePriceData.price for mmOraclePrice
- * @returns
+ * Computes both the auction start price (`getTriggerAuctionStartPrice`) and the
+ * corresponding execution price under the (potentially different) live MM oracle price —
+ * i.e. the same start offset re-applied to `mmOraclePrice` instead of `oraclePrice`. Both are
+ * clamped to `limitPrice` if one is given.
+ * @param params.perpMarket Market providing TWAP stats and contract tier.
+ * @param params.direction Order side.
+ * @param params.oraclePrice Current (exchange) oracle price — use `OraclePriceData.price`, PRICE_PRECISION (1e6).
+ * @param params.mmOraclePrice Current MM oracle price — use `MMOraclePriceData.price`, PRICE_PRECISION (1e6).
+ * @param params.limitPrice Optional limit price to clamp both results to, PRICE_PRECISION (1e6).
+ * @returns `startPrice` (auction start under `oraclePrice`) and `executionPrice` (same offset under `mmOraclePrice`), both PRICE_PRECISION (1e6).
  */
 export declare function getTriggerAuctionStartAndExecutionPrice(params: {
     perpMarket: PerpMarketAccount;

package/lib/browser/math/auction.js

@@ -9,6 +9,7 @@ const tiers_1 = require("./tiers");
 const orders_1 = require("./orders");
 const oracles_1 = require("./oracles");
 const exchangeStatus_1 = require("./exchangeStatus");
+/** True if `order`'s auction has run its full `auctionDuration` (in slots) as of `slot`, or the order has no auction (`auctionDuration === 0`). */
 function isAuctionComplete(order, slot) {
     if (order.auctionDuration === 0) {
         return true;
@@ -16,11 +17,44 @@ function isAuctionComplete(order, slot) {
     return new anchor_1.BN(slot).sub(order.slot).gt(new anchor_1.BN(order.auctionDuration));
 }
 exports.isAuctionComplete = isAuctionComplete;
+/**
+ * True if the AMM is currently a permitted fallback liquidity source for `order`, mirroring the
+ * program's `amm_fill_gates_ok` (`state/perp_market.rs`) — the hard gates that suppress all AMM
+ * fills (standalone and JIT), not the auction-timing gates JIT bypasses, and not price/size (see
+ * `calculateBaseAssetAmountForAmmToFulfill` for that). Blocked if `AMM_FILL` is paused, if the
+ * market has too much drawdown, if the MM oracle is too volatile vs the exchange oracle (enabled +
+ * as-recent + >1% price diff — early volatility protection), or if the MM-oracle validity is
+ * `StaleForAMMLowRisk` or worse. If validity is exactly `Valid`, always allowed; otherwise (a
+ * degraded-but-not-stale oracle) only allowed when the order itself is low-risk for the AMM
+ * (`isLowRiskForAmm`) — e.g. it predates the oracle delay, is part of a liquidation, or carries
+ * the safe-trigger flag.
+ * @param order Order to check.
+ * @param mmOraclePriceData Current MM oracle price data — the MM-volatility gate reads its
+ *   `isMMOracleEnabled`/`isMMOracleAsRecent`/`isMMExchangeDiffBpsHigh` flags (populated by
+ *   `VelocityClient.getMMOracleDataForPerpMarket`); when those are absent the gate is skipped.
+ * @param slot Current slot.
+ * @param state Global state, providing oracle guard rails.
+ * @param market Perp market the order is on.
+ * @param isLiquidation Whether the fill is part of a liquidation (relaxes the low-risk check).
+ * @returns `true` if the AMM may currently act as a fallback liquidity source for this order.
+ */
 function isFallbackAvailableLiquiditySource(order, mmOraclePriceData, slot, state, market, isLiquidation) {
     if ((0, exchangeStatus_1.isOperationPaused)(market.pausedOperations, types_1.PerpOperation.AMM_FILL)) {
         return false;
     }
-    // TODO: include too much drawdown check & mm oracle volatility
+    if ((0, exchangeStatus_1.isAmmDrawdownPause)(market)) {
+        return false;
+    }
+    // MM-oracle volatility gate (M15): mirrors `amm_fill_gates_ok`'s
+    // `mm_oracle_not_too_volatile`. We already use safe MM oracle data, but the AMM isn't
+    // available if we *could* have used the MM oracle yet fell back due to a >1% price diff —
+    // early volatility protection. Only applies when the MM oracle is enabled and at least as
+    // recent as the exchange oracle; skipped when those flags weren't populated.
+    if (mmOraclePriceData.isMMOracleEnabled &&
+        mmOraclePriceData.isMMOracleAsRecent &&
+        mmOraclePriceData.isMMExchangeDiffBpsHigh) {
+        return false;
+    }
     const oracleValidity = (0, oracles_1.getOracleValidity)(market, {
         price: mmOraclePriceData.price,
         slot: mmOraclePriceData.slot,
@@ -43,42 +77,59 @@ function isFallbackAvailableLiquiditySource(order, mmOraclePriceData, slot, stat
 }
 exports.isFallbackAvailableLiquiditySource = isFallbackAvailableLiquiditySource;
 /**
- *
- * @param order
- * @param slot
- * @param oraclePrice Use MMOraclePriceData source for perp orders, OraclePriceData for spot
- * @returns BN
+ * Dispatches to the correct in-progress auction price for `order` based on its order type:
+ * fixed-price auction (`getAuctionPriceForFixedAuction`) for market/triggerLimit/plain-limit
+ * orders, or oracle-offset auction (`getAuctionPriceForOracleOffsetAuction`) for
+ * oracle-pegged limit/oracle/oracle-triggered-market orders. The result is always
+ * standardized to `tickSize`.
+ * @param order Order whose auction price to compute.
+ * @param slot Current slot.
+ * @param oraclePrice Use `MMOraclePriceData` source for perp orders, `OraclePriceData` for spot; PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Auction price at the current slot, PRICE_PRECISION (1e6).
+ * @throws if `order.orderType` doesn't match any known auction pricing path.
  */
-function getAuctionPrice(order, slot, oraclePrice) {
+function getAuctionPrice(order, slot, oraclePrice, tickSize = numericConstants_1.ONE) {
     if ((0, types_1.isOneOfVariant)(order.orderType, ['market', 'triggerLimit']) ||
         ((0, types_1.isVariant)(order.orderType, 'triggerMarket') &&
             (order.bitFlags & types_2.OrderBitFlag.OracleTriggerMarket) === 0)) {
-        return getAuctionPriceForFixedAuction(order, slot);
+        return getAuctionPriceForFixedAuction(order, slot, tickSize);
     }
     else if ((0, types_1.isVariant)(order.orderType, 'limit')) {
         if (order.oraclePriceOffset != null && !order.oraclePriceOffset.eq(numericConstants_1.ZERO)) {
-            return getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice);
+            return getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice, tickSize);
         }
         else {
-            return getAuctionPriceForFixedAuction(order, slot);
+            return getAuctionPriceForFixedAuction(order, slot, tickSize);
         }
     }
     else if ((0, types_1.isVariant)(order.orderType, 'oracle') ||
         ((0, types_1.isVariant)(order.orderType, 'triggerMarket') &&
             (order.bitFlags & types_2.OrderBitFlag.OracleTriggerMarket) !== 0)) {
-        return getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice);
+        return getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice, tickSize);
     }
     else {
         throw Error(`Cant get auction price for order type ${(0, types_2.getVariant)(order.orderType)}`);
     }
 }
 exports.getAuctionPrice = getAuctionPrice;
-function getAuctionPriceForFixedAuction(order, slot) {
+/**
+ * Linearly interpolates between `order.auctionStartPrice` and `order.auctionEndPrice` based
+ * on slots elapsed out of `order.auctionDuration`, then standardizes the result to
+ * `tickSize` in the order's favor (via `standardizePrice`) so every auction tick already
+ * lines up with the market's tick size. Returns the (standardized) end price directly once
+ * the auction is complete or has zero duration.
+ * @param order Order whose fixed-price auction to evaluate.
+ * @param slot Current slot.
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Auction price at the current slot, PRICE_PRECISION (1e6).
+ */
+function getAuctionPriceForFixedAuction(order, slot, tickSize = numericConstants_1.ONE) {
     const slotsElapsed = new anchor_1.BN(slot).sub(order.slot);
     const deltaDenominator = new anchor_1.BN(order.auctionDuration);
     const deltaNumerator = anchor_1.BN.min(slotsElapsed, deltaDenominator);
     if (deltaDenominator.eq(numericConstants_1.ZERO)) {
-        return order.auctionEndPrice;
+        return (0, orders_1.standardizePrice)(order.auctionEndPrice, tickSize, order.direction);
     }
     let priceDelta;
     if ((0, types_1.isVariant)(order.direction, 'long')) {
@@ -100,22 +151,29 @@ function getAuctionPriceForFixedAuction(order, slot) {
     else {
         price = order.auctionStartPrice.sub(priceDelta);
     }
-    return price;
+    return (0, orders_1.standardizePrice)(price, tickSize, order.direction);
 }
 exports.getAuctionPriceForFixedAuction = getAuctionPriceForFixedAuction;
 /**
- *
- * @param order
- * @param slot
- * @param oraclePrice Use MMOraclePriceData source for perp orders, OraclePriceData for spot
- * @returns
+ * Linearly interpolates the oracle price offset between `order.auctionStartPrice` and
+ * `order.auctionEndPrice` (both offsets from the oracle price, not absolute prices) based on
+ * slots elapsed out of `order.auctionDuration`, adds it to the live `oraclePrice`, floors it
+ * at `tickSize`, then standardizes the result to `tickSize` in the order's favor. Returns the
+ * (standardized, floored) end-offset price directly once the auction is complete or has zero
+ * duration.
+ * @param order Order whose oracle-offset auction to evaluate.
+ * @param slot Current slot.
+ * @param oraclePrice Use `MMOraclePriceData` source for perp orders, `OraclePriceData` for spot; PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Auction price at the current slot, PRICE_PRECISION (1e6).
  */
-function getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice) {
+function getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice, tickSize = numericConstants_1.ONE) {
     const slotsElapsed = new anchor_1.BN(slot).sub(order.slot);
     const deltaDenominator = new anchor_1.BN(order.auctionDuration);
     const deltaNumerator = anchor_1.BN.min(slotsElapsed, deltaDenominator);
     if (deltaDenominator.eq(numericConstants_1.ZERO)) {
-        return anchor_1.BN.max(oraclePrice.add(order.auctionEndPrice), numericConstants_1.ONE);
+        const price = anchor_1.BN.max(oraclePrice.add(order.auctionEndPrice), tickSize);
+        return (0, orders_1.standardizePrice)(price, tickSize, order.direction);
     }
     let priceOffsetDelta;
     if ((0, types_1.isVariant)(order.direction, 'long')) {
@@ -137,9 +195,25 @@ function getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice) {
     else {
         priceOffset = order.auctionStartPrice.sub(priceOffsetDelta);
     }
-    return anchor_1.BN.max(oraclePrice.add(priceOffset), numericConstants_1.ONE);
+    const price = anchor_1.BN.max(oraclePrice.add(priceOffset), tickSize);
+    return (0, orders_1.standardizePrice)(price, tickSize, order.direction);
 }
 exports.getAuctionPriceForOracleOffsetAuction = getAuctionPriceForOracleOffsetAuction;
+/**
+ * Converts absolute auction start/end prices (and a desired limit price) into the
+ * oracle-offset form the program expects for oracle-pegged orders: offsets from the current
+ * oracle price rather than absolute prices. Derives `oraclePriceOffset` from `limitPrice -
+ * oraclePrice` when both are nonzero, falling back to `auctionEndPrice - oraclePrice` (±1,
+ * biased away from the oracle in the order's direction) otherwise. Optionally clamps the
+ * absolute start/end prices to `auctionPriceCaps` before converting.
+ * @param direction Order side; determines the ±1 bias when deriving a fallback offset.
+ * @param oraclePrice Current oracle price, PRICE_PRECISION (1e6).
+ * @param auctionStartPrice Desired absolute auction start price, PRICE_PRECISION (1e6).
+ * @param auctionEndPrice Desired absolute auction end price, PRICE_PRECISION (1e6).
+ * @param limitPrice Desired absolute limit price (0 to derive the offset purely from `auctionEndPrice`), PRICE_PRECISION (1e6).
+ * @param auctionPriceCaps Optional `{ min, max }` bounds (PRICE_PRECISION 1e6) to clamp the absolute start/end prices to before converting to offsets.
+ * @returns `auctionStartPrice`/`auctionEndPrice` as oracle offsets, and `oraclePriceOffset` for the limit price — all PRICE_PRECISION (1e6), relative to `oraclePrice`.
+ */
 function deriveOracleAuctionParams({ direction, oraclePrice, auctionStartPrice, auctionEndPrice, limitPrice, auctionPriceCaps, }) {
     let oraclePriceOffset;
     if (limitPrice.eq(numericConstants_1.ZERO) || oraclePrice.eq(numericConstants_1.ZERO)) {
@@ -165,9 +239,18 @@ function deriveOracleAuctionParams({ direction, oraclePrice, auctionStartPrice,
 }
 exports.deriveOracleAuctionParams = deriveOracleAuctionParams;
 /**
- *
- * @param params Use OraclePriceData.price for oraclePrice param
- * @returns
+ * Derives a reasonable auction start price for a newly-triggered trigger order, biasing off
+ * the current oracle price by an offset estimated from recent mark/oracle spread (or, if
+ * mark and oracle TWAPs have recently diverged or 24h volume is thin, a coarser
+ * TWAP-fraction fallback scaled by contract tier). Applies a further directional "start
+ * buffer" in bps (tighter for tier A/B markets) so the auction starts slightly aggressive,
+ * then clamps to `limitPrice` if one is given so the auction never starts past the user's
+ * limit.
+ * @param params.perpMarket Market providing TWAP stats and contract tier.
+ * @param params.direction Order side.
+ * @param params.oraclePrice Current oracle price — use `OraclePriceData.price`, PRICE_PRECISION (1e6).
+ * @param params.limitPrice Optional limit price to clamp the start price to, PRICE_PRECISION (1e6).
+ * @returns Auction start price, PRICE_PRECISION (1e6).
  */
 function getTriggerAuctionStartPrice(params) {
     const { perpMarket, direction, oraclePrice, limitPrice } = params;
@@ -231,9 +314,16 @@ function getTriggerAuctionStartPrice(params) {
 }
 exports.getTriggerAuctionStartPrice = getTriggerAuctionStartPrice;
 /**
- *
- * @param params Use OraclePriceData.price for oraclePrice param and MMOraclePriceData.price for mmOraclePrice
- * @returns
+ * Computes both the auction start price (`getTriggerAuctionStartPrice`) and the
+ * corresponding execution price under the (potentially different) live MM oracle price —
+ * i.e. the same start offset re-applied to `mmOraclePrice` instead of `oraclePrice`. Both are
+ * clamped to `limitPrice` if one is given.
+ * @param params.perpMarket Market providing TWAP stats and contract tier.
+ * @param params.direction Order side.
+ * @param params.oraclePrice Current (exchange) oracle price — use `OraclePriceData.price`, PRICE_PRECISION (1e6).
+ * @param params.mmOraclePrice Current MM oracle price — use `MMOraclePriceData.price`, PRICE_PRECISION (1e6).
+ * @param params.limitPrice Optional limit price to clamp both results to, PRICE_PRECISION (1e6).
+ * @returns `startPrice` (auction start under `oraclePrice`) and `executionPrice` (same offset under `mmOraclePrice`), both PRICE_PRECISION (1e6).
  */
 function getTriggerAuctionStartAndExecutionPrice(params) {
     const { perpMarket, direction, oraclePrice, limitPrice, mmOraclePrice } = params;

package/lib/browser/math/bankruptcy.d.ts

@@ -1,2 +1,48 @@
 import { User } from '../user';
+/**
+ * Determines whether a user's cross-margin book is bankrupt, mirroring
+ * `is_cross_margin_bankrupt` in `programs/velocity/src/math/bankruptcy.rs`. A user is
+ * cross-margin bankrupt when they hold no spot deposits, at least one spot borrow, and
+ * every non-isolated perp position is flat (zero base, non-positive quote, no open orders)
+ * with at least one carrying negative quote (an unpaid perp liability). Isolated perp
+ * positions (`user.isPerpPositionIsolated`) are skipped here — check those individually
+ * with `isIsolatedPositionBankrupt` instead, since they resolve/settle independently of
+ * the cross-margin book.
+ * @param user The `User` account wrapper to evaluate.
+ * @returns `true` if the user's cross-margin collateral is exhausted and they still owe a
+ *   liability (spot borrow or negative perp quote balance); `false` otherwise.
+ */
 export declare function isUserBankrupt(user: User): boolean;
+/**
+ * Determines whether a specific isolated perp position is bankrupt, mirroring
+ * `is_isolated_margin_bankrupt` in `programs/velocity/src/math/bankruptcy.rs`. Isolated
+ * positions carry their own collateral pool (`isolatedPositionScaledBalance`, spot-balance
+ * precision) separate from the user's cross-margin book, so bankruptcy is evaluated
+ * per-market: the position is bankrupt once its isolated collateral is fully drained
+ * (`isolatedPositionScaledBalance == 0`) while it still has a flat base position, a
+ * negative quote balance (unpaid liability), and no open orders.
+ * @param user The `User` account wrapper to evaluate.
+ * @param marketIndex Perp market index of the isolated position to check.
+ * @returns `true` if the isolated position's collateral is exhausted and it still owes a
+ *   liability; `false` otherwise.
+ * @throws if the user has no perp position for `marketIndex` (via `getPerpPositionOrThrow`),
+ *   or if that position is not an isolated position — mirroring the program's
+ *   `get_isolated_perp_position`, which errors `InvalidPerpPosition` on a non-isolated index.
+ */
+export declare function isIsolatedPositionBankrupt(user: User, marketIndex: number): boolean;
+/**
+ * Determines whether the user holds any bankrupt isolated perp position, mirroring the isolated
+ * half of the program's bankruptcy routing. On-chain, a user is routed to bankruptcy resolution
+ * when `is_cross_margin_bankrupt` OR `has_isolated_margin_bankrupt` — and an isolated position
+ * counts as bankrupt either because the program already set `PositionFlag::Bankrupt` on it
+ * (`has_isolated_margin_bankrupt`, the status-flag view) or because it is economically bankrupt
+ * and should enter bankruptcy (`is_isolated_margin_bankrupt`, the balance-derived view). A keeper
+ * must catch both: `User.isBankrupt()` only reads the account-level `UserStatus.BANKRUPT` bit,
+ * which `enter_isolated_margin_bankruptcy` never sets — so without this check an isolated-only
+ * bankruptcy is invisible to `isUserBankrupt` (which deliberately skips isolated positions) and
+ * to `User.isBankrupt()`, and would never be resolved.
+ * @param user The `User` account wrapper to evaluate.
+ * @returns `true` if any isolated perp position is flagged bankrupt on-chain or is economically
+ *   bankrupt now; `false` otherwise.
+ */
+export declare function hasIsolatedMarginBankrupt(user: User): boolean;

package/lib/browser/math/bankruptcy.js

@@ -1,9 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isUserBankrupt = void 0;
+exports.hasIsolatedMarginBankrupt = exports.isIsolatedPositionBankrupt = exports.isUserBankrupt = void 0;
 const numericConstants_1 = require("../constants/numericConstants");
 const position_1 = require("./position");
 const types_1 = require("../types");
+/**
+ * Economic (balance-derived) bankruptcy test for a single isolated perp position, shared by
+ * {@link isIsolatedPositionBankrupt} and {@link hasIsolatedMarginBankrupt}. Mirrors the body of
+ * `is_isolated_margin_bankrupt` in `programs/velocity/src/math/bankruptcy.rs`: the position is
+ * bankrupt once its isolated collateral is fully drained (`isolatedPositionScaledBalance == 0`)
+ * while it still has a flat base position, a negative quote balance (unpaid liability), and no
+ * open orders. The caller is responsible for ensuring `position` is an isolated position.
+ */
+function isIsolatedPositionEconomicallyBankrupt(position) {
+    var _a;
+    // defensive ?? ZERO matches user.ts's reads of this field (see its `//TODO remove ? later`)
+    if (((_a = position.isolatedPositionScaledBalance) !== null && _a !== void 0 ? _a : numericConstants_1.ZERO).gt(numericConstants_1.ZERO)) {
+        return false;
+    }
+    return (position.baseAssetAmount.eq(numericConstants_1.ZERO) &&
+        position.quoteAssetAmount.lt(numericConstants_1.ZERO) &&
+        !(0, position_1.hasOpenOrders)(position));
+}
+/**
+ * Determines whether a user's cross-margin book is bankrupt, mirroring
+ * `is_cross_margin_bankrupt` in `programs/velocity/src/math/bankruptcy.rs`. A user is
+ * cross-margin bankrupt when they hold no spot deposits, at least one spot borrow, and
+ * every non-isolated perp position is flat (zero base, non-positive quote, no open orders)
+ * with at least one carrying negative quote (an unpaid perp liability). Isolated perp
+ * positions (`user.isPerpPositionIsolated`) are skipped here — check those individually
+ * with `isIsolatedPositionBankrupt` instead, since they resolve/settle independently of
+ * the cross-margin book.
+ * @param user The `User` account wrapper to evaluate.
+ * @returns `true` if the user's cross-margin collateral is exhausted and they still owe a
+ *   liability (spot borrow or negative perp quote balance); `false` otherwise.
+ */
 function isUserBankrupt(user) {
     const userAccount = user.getUserAccountOrThrow();
     let hasLiability = false;
@@ -18,6 +49,10 @@ function isUserBankrupt(user) {
         }
     }
     for (const position of userAccount.perpPositions) {
+        // Isolated perp positions are handled by isIsolatedPositionBankrupt
+        if (user.isPerpPositionIsolated(position)) {
+            continue;
+        }
         if (!position.baseAssetAmount.eq(numericConstants_1.ZERO) ||
             position.quoteAssetAmount.gt(numericConstants_1.ZERO) ||
             (0, position_1.hasOpenOrders)(position)) {
@@ -30,3 +65,56 @@ function isUserBankrupt(user) {
     return hasLiability;
 }
 exports.isUserBankrupt = isUserBankrupt;
+/**
+ * Determines whether a specific isolated perp position is bankrupt, mirroring
+ * `is_isolated_margin_bankrupt` in `programs/velocity/src/math/bankruptcy.rs`. Isolated
+ * positions carry their own collateral pool (`isolatedPositionScaledBalance`, spot-balance
+ * precision) separate from the user's cross-margin book, so bankruptcy is evaluated
+ * per-market: the position is bankrupt once its isolated collateral is fully drained
+ * (`isolatedPositionScaledBalance == 0`) while it still has a flat base position, a
+ * negative quote balance (unpaid liability), and no open orders.
+ * @param user The `User` account wrapper to evaluate.
+ * @param marketIndex Perp market index of the isolated position to check.
+ * @returns `true` if the isolated position's collateral is exhausted and it still owes a
+ *   liability; `false` otherwise.
+ * @throws if the user has no perp position for `marketIndex` (via `getPerpPositionOrThrow`),
+ *   or if that position is not an isolated position — mirroring the program's
+ *   `get_isolated_perp_position`, which errors `InvalidPerpPosition` on a non-isolated index.
+ */
+function isIsolatedPositionBankrupt(user, marketIndex) {
+    const position = user.getPerpPositionOrThrow(marketIndex);
+    if (!user.isPerpPositionIsolated(position)) {
+        throw new Error(`Perp position ${marketIndex} is not an isolated position (InvalidPerpPosition)`);
+    }
+    return isIsolatedPositionEconomicallyBankrupt(position);
+}
+exports.isIsolatedPositionBankrupt = isIsolatedPositionBankrupt;
+/**
+ * Determines whether the user holds any bankrupt isolated perp position, mirroring the isolated
+ * half of the program's bankruptcy routing. On-chain, a user is routed to bankruptcy resolution
+ * when `is_cross_margin_bankrupt` OR `has_isolated_margin_bankrupt` — and an isolated position
+ * counts as bankrupt either because the program already set `PositionFlag::Bankrupt` on it
+ * (`has_isolated_margin_bankrupt`, the status-flag view) or because it is economically bankrupt
+ * and should enter bankruptcy (`is_isolated_margin_bankrupt`, the balance-derived view). A keeper
+ * must catch both: `User.isBankrupt()` only reads the account-level `UserStatus.BANKRUPT` bit,
+ * which `enter_isolated_margin_bankruptcy` never sets — so without this check an isolated-only
+ * bankruptcy is invisible to `isUserBankrupt` (which deliberately skips isolated positions) and
+ * to `User.isBankrupt()`, and would never be resolved.
+ * @param user The `User` account wrapper to evaluate.
+ * @returns `true` if any isolated perp position is flagged bankrupt on-chain or is economically
+ *   bankrupt now; `false` otherwise.
+ */
+function hasIsolatedMarginBankrupt(user) {
+    const userAccount = user.getUserAccountOrThrow();
+    for (const position of userAccount.perpPositions) {
+        if (!user.isPerpPositionIsolated(position)) {
+            continue;
+        }
+        if ((position.positionFlag & types_1.PositionFlag.Bankruptcy) !== 0 ||
+            isIsolatedPositionEconomicallyBankrupt(position)) {
+            return true;
+        }
+    }
+    return false;
+}
+exports.hasIsolatedMarginBankrupt = hasIsolatedMarginBankrupt;

package/lib/browser/math/builder.d.ts

@@ -1,22 +1,78 @@
+import { BN } from '../isomorphic/anchor';
 import { OrderParams, RevenueShareEscrowAccount, RevenueShareOrder, UserStatsAccount } from '../types';
 /**
- * True when the user's RevenueShareEscrow was initialized with a referrer.
- * Fills for such users must include the escrow account or the program rejects
- * them with UnableToLoadRevenueShareAccount.
+ * Calculates the builder fee charged on top of the tiered taker/maker fee, mirroring the
+ * program's builder-fee calc. `builderFeeTenthBps` is denominated in tenth-basis-points, i.e.
+ * `10 * builderFeeTenthBps == 1 bp == 0.01%` — the fee fraction is `builderFeeTenthBps / 100_000`.
+ *
+ * @param {BN} quoteAssetAmount - The fill's quote asset amount the fee is charged against,
+ *   QUOTE_PRECISION (1e6)
+ * @param {number} builderFeeTenthBps - The builder fee rate, in tenth-bps (`OrderParams.builderFeeTenthBps`)
+ * @return {BN} The builder fee, QUOTE_PRECISION (1e6)
+ */
+export declare function calculateBuilderFee(quoteAssetAmount: BN, builderFeeTenthBps: number): BN;
+/**
+ * True when the user's `RevenueShareEscrow` was initialized with a referrer.
+ *
+ * @param {Pick<UserStatsAccount, 'referrerStatus'>} userStats - The user's stats account (or a
+ *   pick containing just `referrerStatus`)
+ * @return {boolean} Whether `ReferrerStatus.BuilderReferral` is set in `referrerStatus`. When
+ *   true, fills for this user must include the escrow account as a remaining account or the
+ *   program rejects them with `UnableToLoadRevenueShareAccount`
  */
 export declare function isBuilderReferral(userStats: Pick<UserStatsAccount, 'referrerStatus'>): boolean;
 /**
- * True when the escrow was initialized with a referrer. Referral rewards
- * accrue into such escrows on fills, so fills of the escrow owner's orders
- * must include the escrow account (see `isBuilderReferral`).
+ * True when the escrow was initialized with a referrer (its `referrer` field is not the default
+ * pubkey).
+ *
+ * @param {Pick<RevenueShareEscrowAccount, 'referrer'>} escrow - The revenue share escrow account
+ *   (or a pick containing just `referrer`)
+ * @return {boolean} Whether `escrow.referrer` is set. Referral rewards accrue into such escrows on
+ *   fills, so fills of the escrow owner's orders must include the escrow account (see `isBuilderReferral`)
  */
 export declare function escrowHasReferrer(escrow: Pick<RevenueShareEscrowAccount, 'referrer'>): boolean;
 /**
- * True when the order params carry a builder code (`builderIdx` +
- * `builderFeeTenthBps`).
+ * True when the order params carry a builder code (both `builderIdx` and `builderFeeTenthBps`
+ * are set, i.e. neither `null` nor `undefined`).
+ *
+ * @param {Pick<OrderParams, 'builderIdx' | 'builderFeeTenthBps'>} orderParams - The order params
+ *   (or a pick containing just the builder fields)
+ * @return {boolean} Whether both builder fields are present
  */
 export declare function hasBuilderParams(orderParams: Pick<OrderParams, 'builderIdx' | 'builderFeeTenthBps'>): boolean;
+/**
+ * True if this `RevenueShareOrder` slot is occupied by an active order, mirroring
+ * `RevenueShareOrder::is_open` (`RevenueShareOrderBitFlag::Open`). While open, `orderId` and
+ * `subAccountId` identify the live order this slot is tracking.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the `Open` bit is set in `order.bitFlags`
+ */
 export declare function isBuilderOrderOpen(order: RevenueShareOrder): boolean;
+/**
+ * True if this `RevenueShareOrder` has been filled or canceled and is awaiting settlement into
+ * the builder's account, mirroring `RevenueShareOrder::is_completed`
+ * (`RevenueShareOrderBitFlag::Completed`). Once completed, `orderId`/`subAccountId` are no
+ * longer meaningful and the slot's accrued fees may be merged with other completed orders.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the `Completed` bit is set in `order.bitFlags`
+ */
 export declare function isBuilderOrderCompleted(order: RevenueShareOrder): boolean;
+/**
+ * True if this `RevenueShareOrder` slot instead holds referral rewards pending settlement for a
+ * market (`RevenueShareOrderBitFlag::Referral`), rather than tracking a builder-fee order. When
+ * set, no other bit flag should be set and `builderIdx` is ignored.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the `Referral` bit is set in `order.bitFlags`
+ */
 export declare function isBuilderOrderReferral(order: RevenueShareOrder): boolean;
+/**
+ * True if this `RevenueShareOrder` slot is free to be (re)written — neither open nor completed —
+ * mirroring `RevenueShareOrder::is_available`.
+ *
+ * @param {RevenueShareOrder} order - The revenue share order slot
+ * @return {boolean} Whether the slot can be claimed for a new order
+ */
 export declare function isBuilderOrderAvailable(order: RevenueShareOrder): boolean;