@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/node/math/oracles.js

@@ -1,10 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMultipleBetweenOracleSources = exports.getNewOracleConfPct = exports.calculateLiveOracleStd = exports.calculateLiveOracleTwap = exports.isOracleTooDivergent = exports.isOracleValid = exports.getOracleValidity = exports.getMaxConfidenceIntervalMultiplier = exports.oraclePriceBands = void 0;
+exports.getMultipleBetweenOracleSources = exports.getNewOracleConfPct = exports.calculateLiveOracleStd = exports.calculateLiveOracleTwap = exports.isMarkOracleTooDivergent = exports.isOracleTooDivergent = exports.isOracleValid = exports.getOracleValidity = exports.getMaxConfidenceIntervalMultiplier = exports.oraclePriceBands = void 0;
 const types_1 = require("../types");
 const numericConstants_1 = require("../constants/numericConstants");
 const assert_1 = require("../assert/assert");
 const anchor_1 = require("../isomorphic/anchor");
+/**
+ * Computes a generic sanity band around the oracle price, sized by the gap between the
+ * market's initial and maintenance margin ratios (a wider margin gap allows a wider band).
+ * This is a coarse UI/client-side sanity check, not the exact on-chain price-band gate —
+ * order and settlement price-divergence checks on-chain compare the 5-min oracle TWAP
+ * spread via `isMarkOracleTooDivergent`/`isOracleTooDivergent` instead.
+ * @param market Perp market whose `marginRatioInitial`/`marginRatioMaintenance` (MARGIN_PRECISION, 1e4) set the band width.
+ * @param oraclePriceData Must provide `price`, PRICE_PRECISION (1e6).
+ * @returns `[lowerBound, upperBound]`, both PRICE_PRECISION (1e6).
+ */
 function oraclePriceBands(market, oraclePriceData) {
     const maxPercentDiff = market.marginRatioInitial - market.marginRatioMaintenance;
     const offset = oraclePriceData.price
@@ -14,6 +24,14 @@ function oraclePriceBands(market, oraclePriceData) {
     return [oraclePriceData.price.sub(offset), oraclePriceData.price.add(offset)];
 }
 exports.oraclePriceBands = oraclePriceBands;
+/**
+ * Returns the per-market multiplier applied to `confidenceIntervalMaxSize` when checking
+ * oracle confidence-interval validity, mirroring `PerpMarket::get_max_confidence_interval_multiplier`.
+ * Riskier contract tiers tolerate a wider oracle confidence interval before being flagged
+ * invalid: 1x for tier A/B, 2x for tier C, 10x for Speculative, 50x for HighlySpeculative and Isolated.
+ * @param market Perp market whose `contractTier` selects the multiplier.
+ * @returns Unitless multiplier (dimensionless BN).
+ */
 function getMaxConfidenceIntervalMultiplier(market) {
     let maxConfidenceIntervalMultiplier;
     if ((0, types_1.isVariant)(market.contractTier, 'a')) {
@@ -34,6 +52,23 @@ function getMaxConfidenceIntervalMultiplier(market) {
     return maxConfidenceIntervalMultiplier;
 }
 exports.getMaxConfidenceIntervalMultiplier = getMaxConfidenceIntervalMultiplier;
+/**
+ * Classifies an oracle reading's validity for `market`, mirroring `oracle_validity` in
+ * `programs/velocity/src/math/oracle.rs`. Checks are evaluated in severity order and the
+ * first failing check wins: non-positive price, too volatile vs the oracle TWAP
+ * (`tooVolatileRatio`), confidence interval too wide (scaled by
+ * `getMaxConfidenceIntervalMultiplier`), stale for margin use, insufficient oracle data
+ * points, then stale for AMM use (low-risk or immediate, gated by the market's
+ * `oracleLowRiskSlotDelayOverride`/`oracleSlotDelayOverride`). Returns `OracleValidity.Valid`
+ * only if none of these trip. Callers typically gate on the returned enum via
+ * `isOracleValidForAction`-style helpers rather than comparing directly.
+ * @param market Perp market providing contract tier, oracle source, and stale-slot overrides.
+ * @param oraclePriceData Oracle reading to validate (`price`/`confidence` PRICE_PRECISION 1e6, `slot`).
+ * @param oracleGuardRails Protocol-wide validity thresholds (`state.oracleGuardRails`).
+ * @param slot Current slot, used to compute oracle delay.
+ * @param oracleStalenessBuffer Extra slots subtracted from the raw oracle delay before staleness checks (default 5) to absorb normal reporting lag.
+ * @returns The most severe `OracleValidity` classification that applies.
+ */
 function getOracleValidity(market, oraclePriceData, oracleGuardRails, slot, oracleStalenessBuffer = numericConstants_1.FIVE) {
     const isNonPositive = oraclePriceData.price.lte(numericConstants_1.ZERO);
     const isTooVolatile = anchor_1.BN.max(oraclePriceData.price, market.marketStats.historicalOracleData.lastOraclePriceTwap)
@@ -85,6 +120,19 @@ function getOracleValidity(market, oraclePriceData, oracleGuardRails, slot, orac
     }
 }
 exports.getOracleValidity = getOracleValidity;
+/**
+ * Simplified, AMM-fill-oriented validity check: `true` only if the oracle has sufficient
+ * data points, is not stale (vs `slotsBeforeStaleForAmm`), has a positive price, isn't too
+ * volatile vs the market's oracle TWAP, and its confidence interval isn't too wide. Unlike
+ * `getOracleValidity` this does not distinguish "stale for margin" or "low risk" tiers — it
+ * is a single valid/invalid gate specifically for whether the AMM may fill against this
+ * price.
+ * @param market Perp market providing the oracle TWAP and contract tier for the confidence multiplier.
+ * @param oraclePriceData Oracle reading to validate (`price`/`confidence` PRICE_PRECISION 1e6).
+ * @param oracleGuardRails Protocol-wide validity thresholds.
+ * @param slot Current slot, used to compute oracle staleness.
+ * @returns `true` if the oracle is valid for an AMM-only fill.
+ */
 function isOracleValid(market, oraclePriceData, oracleGuardRails, slot) {
     // checks if oracle is valid for an AMM only fill
     const stats = market.marketStats;
@@ -110,6 +158,16 @@ function isOracleValid(market, oraclePriceData, oracleGuardRails, slot) {
         isConfidenceTooLarge);
 }
 exports.isOracleValid = isOracleValid;
+/**
+ * True when the live oracle price has diverged from the market's 5-minute oracle TWAP by
+ * more than the configured threshold (with a 50% safety floor). Distinct from
+ * `isMarkOracleTooDivergent`, which compares mark (reserve) price to the same TWAP instead
+ * of the live oracle price to itself — this catches an oracle feed itself jumping abruptly.
+ * @param marketStats Market stats providing `historicalOracleData.lastOraclePriceTwap5Min`, PRICE_PRECISION (1e6).
+ * @param oraclePriceData Live oracle reading (`price`, PRICE_PRECISION 1e6).
+ * @param oracleGuardRails Protocol-wide guard rails; uses `priceDivergence.oracleTwap5MinPercentDivergence`, PERCENTAGE_PRECISION (1e6).
+ * @returns `true` if the oracle-vs-TWAP spread exceeds the divergence threshold.
+ */
 function isOracleTooDivergent(marketStats, oraclePriceData, oracleGuardRails) {
     const oracleSpreadPct = oraclePriceData.price
         .sub(marketStats.historicalOracleData.lastOraclePriceTwap5Min)
@@ -120,6 +178,34 @@ function isOracleTooDivergent(marketStats, oraclePriceData, oracleGuardRails) {
     return tooDivergent;
 }
 exports.isOracleTooDivergent = isOracleTooDivergent;
+/**
+ * True when `|priceSpreadPct|` exceeds the configured mark/oracle divergence threshold,
+ * with a 10% safety floor. Mirrors `is_mark_oracle_too_divergent` in
+ * `programs/velocity/src/math/oracle.rs` — a pure decision helper used both to block
+ * funding-rate updates (`block_operation`) and to reject orders/settlement when the market
+ * has moved too far from its 5-minute oracle TWAP (`validate_market_within_price_band`,
+ * which calls this once with the mark-vs-TWAP spread and once with the oracle-vs-TWAP
+ * spread, blocking on whichever is more divergent).
+ * @param priceSpreadPct Mark (or oracle) price spread vs the 5-minute oracle TWAP, PERCENTAGE_PRECISION (1e6, signed).
+ * @param oracleGuardRails Protocol-wide guard rails; uses `priceDivergence.markOraclePercentDivergence`, PERCENTAGE_PRECISION (1e6).
+ * @returns `true` if the spread exceeds `max(markOraclePercentDivergence, 10%)`.
+ */
+function isMarkOracleTooDivergent(priceSpreadPct, oracleGuardRails) {
+    const maxDivergence = anchor_1.BN.max(oracleGuardRails.priceDivergence.markOraclePercentDivergence, numericConstants_1.PERCENTAGE_PRECISION.div(numericConstants_1.TEN));
+    return priceSpreadPct.abs().gt(maxDivergence);
+}
+exports.isMarkOracleTooDivergent = isMarkOracleTooDivergent;
+/**
+ * Projects the oracle TWAP forward to `now` without requiring an on-chain update,
+ * time-weighting the stored TWAP against the live oracle price clamped to within 1/3 of the
+ * current TWAP (so a single outlier tick can't swing the live estimate too far). Uses the
+ * 5-minute TWAP field when `period` equals `FIVE_MINUTE`, otherwise the funding-period (hourly) TWAP field.
+ * @param histOracleData Market's historical oracle data (TWAP fields, PRICE_PRECISION 1e6, and their last-update timestamp).
+ * @param oraclePriceData Live oracle reading (`price`, PRICE_PRECISION 1e6).
+ * @param now Current unix timestamp (seconds).
+ * @param period TWAP window length in seconds — pass `FIVE_MINUTE` for the 5-minute TWAP, otherwise the funding period is assumed.
+ * @returns Live-projected oracle TWAP, PRICE_PRECISION (1e6).
+ */
 function calculateLiveOracleTwap(histOracleData, oraclePriceData, now, period) {
     let oracleTwap = undefined;
     if (period.eq(numericConstants_1.FIVE_MINUTE)) {
@@ -141,6 +227,15 @@ function calculateLiveOracleTwap(histOracleData, oraclePriceData, now, period) {
     return newOracleTwap;
 }
 exports.calculateLiveOracleTwap = calculateLiveOracleTwap;
+/**
+ * Live-projected oracle price standard deviation, combining the live oracle price's
+ * deviation from the freshly-projected 1hr and 5min TWAPs with the decayed stored
+ * `marketStats.oracleStd`. Feeds `calculateVolSpreadBN`'s volatility-based spread component.
+ * @param marketStats Market stats providing `historicalOracleData`, `fundingPeriod`, and the stored `oracleStd`.
+ * @param oraclePriceData Live oracle reading (`price`, PRICE_PRECISION 1e6).
+ * @param now Current unix timestamp (seconds).
+ * @returns Live oracle price standard deviation, PRICE_PRECISION (1e6).
+ */
 function calculateLiveOracleStd(marketStats, oraclePriceData, now) {
     const sinceLastUpdate = anchor_1.BN.max(numericConstants_1.ONE, now.sub(marketStats.historicalOracleData.lastOraclePriceTwapTs));
     const sinceStart = anchor_1.BN.max(numericConstants_1.ZERO, marketStats.fundingPeriod.sub(sinceLastUpdate));
@@ -151,6 +246,18 @@ function calculateLiveOracleStd(marketStats, oraclePriceData, now) {
     return oracleStd;
 }
 exports.calculateLiveOracleStd = calculateLiveOracleStd;
+/**
+ * Live-projected oracle confidence interval as a fraction of `reservePrice`, floored by a
+ * decaying lower bound derived from the market's last stored confidence (so confidence
+ * can't be understated immediately after a stale update — it decays back down over ~20
+ * seconds). Feeds the volatility-spread and quote calculations that need a current
+ * confidence estimate without waiting for the next on-chain refresh.
+ * @param marketStats Market stats providing `lastOracleConfPct` and `historicalOracleData`'s last-update timestamp.
+ * @param oraclePriceData Live oracle reading; uses `confidence`, PRICE_PRECISION (1e6).
+ * @param reservePrice AMM reserve (mark) price used to express confidence as a fraction, PRICE_PRECISION (1e6).
+ * @param now Current unix timestamp (seconds).
+ * @returns Oracle confidence as a fraction of price, BID_ASK_SPREAD_PRECISION (1e6).
+ */
 function getNewOracleConfPct(marketStats, oraclePriceData, reservePrice, now) {
     const confInterval = oraclePriceData.confidence || numericConstants_1.ZERO;
     const sinceLastUpdate = anchor_1.BN.max(numericConstants_1.ZERO, now.sub(marketStats.historicalOracleData.lastOraclePriceTwapTs));
@@ -166,6 +273,16 @@ function getNewOracleConfPct(marketStats, oraclePriceData, reservePrice, now) {
     return confIntervalPctResult;
 }
 exports.getNewOracleConfPct = getNewOracleConfPct;
+/**
+ * Returns the scale factor to convert a price quoted under `firstOracleSource` into the
+ * equivalent price under `secondOracleSource`, for the Pyth Lazer "scaled" variants
+ * (`pythLazer1K`/`pythLazer1M` report a price 1,000x/1,000,000x smaller than `pythLazer` for
+ * high-priced assets). Returns `{1, 1}` (no conversion) for any other source pair.
+ * @param firstOracleSource Oracle source the input price is denominated in.
+ * @param secondOracleSource Oracle source to convert the price into.
+ * @returns `{ numerator, denominator }` such that `price * numerator / denominator` converts between sources.
+ * @throws if either source is a removed Pyth-pull variant (`pythPull`, `pyth1KPull`, `pyth1MPull`, `pythStableCoinPull`).
+ */
 function getMultipleBetweenOracleSources(firstOracleSource, secondOracleSource) {
     if ((0, types_1.isOneOfVariant)(firstOracleSource, [
         'pythPull',

package/lib/node/math/orders.d.ts

@@ -1,31 +1,139 @@
 import { PerpMarketAccount, AMM, MarketStats, Order, PositionDirection, MarketTypeStr, StateAccount } from '../types';
 import { BN } from '../isomorphic/anchor';
 import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
+/** Rounds `baseAssetAmount` down to the nearest multiple of `stepSize` (always truncates toward zero — never rounds up), matching the on-chain order/fill step-size standardization. @param baseAssetAmount Amount to round, BASE_PRECISION (1e9). @param stepSize Market's order step size, BASE_PRECISION (1e9). @returns Amount rounded down to a `stepSize` multiple, BASE_PRECISION (1e9). */
 export declare function standardizeBaseAssetAmount(baseAssetAmount: BN, stepSize: BN): BN;
+/**
+ * Rounds `price` to a multiple of `tickSize`, rounding in the direction that's conservative
+ * for the order's side: down for a long (never overpay past the tick) and up for a short
+ * (never undersell past the tick). Used across auction pricing and limit-price derivation so
+ * every price the SDK produces already lines up with the market's `orderTickSize` before it
+ * reaches the program, avoiding the on-chain tick-size rejection this standardization fix
+ * addresses. A `tickSize <= 0` (unset/no constraint) or `price == 0` passes through
+ * unchanged.
+ * @param price Price to standardize, PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Non-positive means "no tick constraint."
+ * @param direction Order side; determines rounding direction.
+ * @returns `price` rounded to the nearest tick in the conservative direction, PRICE_PRECISION (1e6).
+ */
 export declare function standardizePrice(price: BN, tickSize: BN, direction: PositionDirection): BN;
-export declare function getLimitPrice<T extends MarketTypeStr>(order: Order, oraclePriceData: T extends 'spot' ? OraclePriceData : MMOraclePriceData, slot: number, fallbackPrice?: BN): BN | undefined;
+/**
+ * Resolves an order's effective limit price at the current slot, standardized to
+ * `tickSize`: the in-progress auction price while the auction hasn't completed, the
+ * oracle-offset price for oracle-pegged orders, the order's fixed `price` if set, or
+ * `fallbackPrice` (also standardized) for a market order with no price/offset/auction.
+ * @param order Order to price.
+ * @param oraclePriceData Oracle price source — use `MMOraclePriceData` for perp orders, `OraclePriceData` for spot.
+ * @param slot Current slot, used to evaluate auction progress.
+ * @param fallbackPrice Price to return for a market order with no auction/offset/fixed price (e.g. a mark or oracle price), PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Limit price, PRICE_PRECISION (1e6); `undefined` if the order has no resolvable price and no `fallbackPrice` was given.
+ */
+export declare function getLimitPrice<T extends MarketTypeStr>(order: Order, oraclePriceData: T extends 'spot' ? OraclePriceData : MMOraclePriceData, slot: number, fallbackPrice?: BN, tickSize?: BN): BN | undefined;
+/** True if the order has any way to resolve a limit price right now: a fixed `price`, a nonzero oracle offset, or an auction still in progress. */
 export declare function hasLimitPrice(order: Order, slot: number): boolean;
+/** True if the order still has an active (incomplete) auction with a nonzero start or end price. */
 export declare function hasAuctionPrice(order: Order, slot: number): boolean;
+/**
+ * True if the AMM is currently a fillable liquidity source for `order` — either it's
+ * expired (always fillable to clean up), or the AMM has fillable size at the order's limit
+ * price AND is an allowed liquidity source right now (`isFallbackAvailableLiquiditySource`,
+ * which gates on oracle validity and low-risk-for-AMM classification).
+ * @param order Order to check.
+ * @param market Perp market the order is on.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param slot Current slot.
+ * @param ts Current unix timestamp (seconds), used for expiry.
+ * @param state Global state, providing oracle guard rails and paused-operations flags.
+ * @returns `true` if the AMM may currently fill this order.
+ */
 export declare function isFillableByVAMM(order: Order, market: PerpMarketAccount, mmOraclePriceData: MMOraclePriceData, slot: number, ts: number, state: StateAccount): boolean;
+/**
+ * True if filling `order` against the AMM is considered low-risk even when the MM oracle
+ * isn't fully valid, approximating `Order::is_low_risk_for_amm` in
+ * `programs/velocity/src/state/user.rs`. Always false for spot orders. True when the order
+ * was placed at or before the MM oracle's slot (so it can't be exploiting oracle staleness),
+ * during liquidation, or when the order carries the `SafeTriggerOrder` bit flag.
+ * @param order Order to check.
+ * @param mmOraclePriceData Current MM oracle price data, used for its `slot`.
+ * @param isLiquidation Whether the fill is part of a liquidation (always low-risk if so).
+ * @returns `true` if the order is low-risk for an AMM fill under a degraded oracle.
+ */
 export declare function isLowRiskForAmm(order: Order, mmOraclePriceData: MMOraclePriceData, isLiquidation?: boolean): boolean;
+/**
+ * Calculates how much of `order` the AMM can currently fill, capped by both the order's
+ * limit price (via `calculateBaseAssetAmountToFillUpToLimitPrice`, standardized to
+ * `market.orderTickSize`) and the AMM's own max fillable size
+ * (`calculateMaxBaseAssetAmountFillable`). Returns zero for a not-yet-triggered
+ * trigger order. Prices against `calculateUpdatedAMM` (i.e. the repegged/curve-updated AMM
+ * state), not the raw stored reserves.
+ * @param order Order to evaluate.
+ * @param market Perp market the order is on.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param slot Current slot.
+ * @returns Fillable base asset amount, BASE_PRECISION (1e9).
+ */
 export declare function calculateBaseAssetAmountForAmmToFulfill(order: Order, market: PerpMarketAccount, mmOraclePriceData: MMOraclePriceData, slot: number): BN;
+/**
+ * Calculates how much base asset the AMM can trade against `order` without crossing its
+ * limit price, adjusting the limit by one tick in the order's favor (so the AMM never fills
+ * exactly at the boundary) before asking `calculateMaxBaseAssetAmountToTrade` how much
+ * inventory the AMM has at that price. Returns zero if the AMM would only trade in the
+ * opposite direction from the order. Caps the result at the order's unfilled remainder.
+ * @param order Order being filled.
+ * @param amm AMM state to trade against.
+ * @param marketStats Market stats needed to compute spread reserves.
+ * @param orderStepSize Market's order step size, BASE_PRECISION (1e9), used to standardize the result.
+ * @param orderTickSize Market's order tick size, PRICE_PRECISION (1e6), used to adjust the limit price by one tick.
+ * @param limitPrice Order's limit price, PRICE_PRECISION (1e6).
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @returns Fillable base asset amount up to the limit price, BASE_PRECISION (1e9).
+ */
 export declare function calculateBaseAssetAmountToFillUpToLimitPrice(order: Order, amm: AMM, marketStats: MarketStats, orderStepSize: BN, orderTickSize: BN, limitPrice: BN, mmOraclePriceData: MMOraclePriceData): BN;
+/**
+ * True if `order.maxTs` has passed as of `ts`. Never true for trigger orders, non-`open`
+ * orders, or orders with no expiry (`maxTs == 0`).
+ * @param order Order to check.
+ * @param ts Current unix timestamp (seconds).
+ * @param enforceBuffer If true, extends `maxTs` by `bufferSeconds` before comparing, but only for limit orders (default false) — gives resting limit orders a grace period before being treated as expired.
+ * @param bufferSeconds Grace period in seconds applied when `enforceBuffer` is true (default 15).
+ * @returns `true` if the order has expired.
+ */
 export declare function isOrderExpired(order: Order, ts: number, enforceBuffer?: boolean, bufferSeconds?: number): boolean;
+/** True if `order.orderType` is `market`, `triggerMarket`, or `oracle`. */
 export declare function isMarketOrder(order: Order): boolean;
+/** True if `order.orderType` is `limit` or `triggerLimit`. */
 export declare function isLimitOrder(order: Order): boolean;
+/** True if the order requires a trigger condition to fire before it becomes fillable (`triggerMarket`/`triggerLimit`). */
 export declare function mustBeTriggered(order: Order): boolean;
+/** True if a trigger order's condition has already fired (`triggeredAbove`/`triggeredBelow`). */
 export declare function isTriggered(order: Order): boolean;
+/** True if a limit order currently rests on the book — i.e. it's `postOnly`, or its auction (if any) has completed. Always false for non-limit orders. */
 export declare function isRestingLimitOrder(order: Order, slot: number): boolean;
+/** True if the order was submitted via the signed-message (swift/off-chain relay) path (`OrderBitFlag.SignedMessage`). */
 export declare function isSignedMsgOrder(order: Order): boolean;
+/** True if the order carries a builder-fee attribution (`OrderBitFlag.HasBuilder`) — the associated builder is entitled to a fee cut on fill. */
 export declare function hasBuilder(order: Order): boolean;
+/**
+ * Resolves the effective base asset amount for a reduce-only order: caps it so the order
+ * can't flip the position through zero (a reduce-only long can close at most the existing
+ * short, and vice versa). Non-reduce-only orders pass through `order.baseAssetAmount`
+ * unchanged.
+ * @param order Order to resolve.
+ * @param existingBaseAssetAmount Current position size before this order fills, BASE_PRECISION (1e9, signed).
+ * @returns Effective base asset amount, BASE_PRECISION (1e9).
+ */
 export declare function calculateOrderBaseAssetAmount(order: Order, existingBaseAssetAmount: BN): BN;
 /**
- * Invert the size-premium liability weight: given a target margin ratio (liability weight),
- * return the max `size` (AMM_RESERVE_PRECISION units) that still yields <= target.
- *
- * Returns:
- * - BN size (>=0) if bounded
- * - null if impossible (target < liabilityWeight) OR imfFactor == 0 (unbounded)
+ * Inverts `calculateSizePremiumLiabilityWeight` via binary search: given a target margin ratio
+ * (liability weight), finds the largest position `size` whose size-premium-adjusted liability
+ * weight is still `<= target`. Used to size down an order/position to stay under a margin-ratio
+ * target as size grows (the on-chain weight increases with `sqrt(size)` via `imfFactor`).
+ * @param target Target (max acceptable) liability weight, MARGIN_PRECISION (1e4).
+ * @param imfFactor Market's initial-margin-fraction scaling factor, SPOT_MARKET_IMF_PRECISION-scaled.
+ * @param liabilityWeight Market's base (zero-size) liability weight, MARGIN_PRECISION (1e4).
+ * @param market Perp market providing `maxOpenInterest` as a final cap on the result.
+ * @returns Max size, AMM_RESERVE_PRECISION (1e9), capped at `market.maxOpenInterest` (a zero `maxOpenInterest` means uncapped, per on-chain convention); `null` if `target < liabilityWeight` (impossible) or `imfFactor` is zero (weight is size-invariant, so no size bounds it).
  */
 export declare function maxSizeForTargetLiabilityWeightBN(target: BN, imfFactor: BN, liabilityWeight: BN, market: PerpMarketAccount): BN | null;
 //# sourceMappingURL=orders.d.ts.map

package/lib/node/math/orders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../src/math/orders.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"orders.d.ts","sourceRoot":"","sources":["../../../src/math/orders.ts"],"names":[],"mappings":"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"}

package/lib/node/math/orders.js

@@ -7,14 +7,33 @@ const anchor_1 = require("../isomorphic/anchor");
 const auction_1 = require("./auction");
 const amm_1 = require("./amm");
 const margin_1 = require("./margin");
+/** Rounds `baseAssetAmount` down to the nearest multiple of `stepSize` (always truncates toward zero — never rounds up), matching the on-chain order/fill step-size standardization. @param baseAssetAmount Amount to round, BASE_PRECISION (1e9). @param stepSize Market's order step size, BASE_PRECISION (1e9). @returns Amount rounded down to a `stepSize` multiple, BASE_PRECISION (1e9). */
 function standardizeBaseAssetAmount(baseAssetAmount, stepSize) {
     const remainder = baseAssetAmount.mod(stepSize);
     return baseAssetAmount.sub(remainder);
 }
 exports.standardizeBaseAssetAmount = standardizeBaseAssetAmount;
+/**
+ * Rounds `price` to a multiple of `tickSize`, rounding in the direction that's conservative
+ * for the order's side: down for a long (never overpay past the tick) and up for a short
+ * (never undersell past the tick). Used across auction pricing and limit-price derivation so
+ * every price the SDK produces already lines up with the market's `orderTickSize` before it
+ * reaches the program, avoiding the on-chain tick-size rejection this standardization fix
+ * addresses. A `tickSize <= 0` (unset/no constraint) or `price == 0` passes through
+ * unchanged.
+ * @param price Price to standardize, PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Non-positive means "no tick constraint."
+ * @param direction Order side; determines rounding direction.
+ * @returns `price` rounded to the nearest tick in the conservative direction, PRICE_PRECISION (1e6).
+ */
 function standardizePrice(price, tickSize, direction) {
     if (price.eq(numericConstants_1.ZERO)) {
-        console.log('price is zero');
+        return price;
+    }
+    // A non-positive tick size means "no tick constraint" (e.g. unset markets);
+    // on-chain markets always have tick_size >= 1, but guard against a zero
+    // divisor rather than throwing.
+    if (tickSize.lte(numericConstants_1.ZERO)) {
         return price;
     }
     const remainder = price.mod(tickSize);
@@ -29,38 +48,79 @@ function standardizePrice(price, tickSize, direction) {
     }
 }
 exports.standardizePrice = standardizePrice;
-function getLimitPrice(order, oraclePriceData, slot, fallbackPrice) {
+/**
+ * Resolves an order's effective limit price at the current slot, standardized to
+ * `tickSize`: the in-progress auction price while the auction hasn't completed, the
+ * oracle-offset price for oracle-pegged orders, the order's fixed `price` if set, or
+ * `fallbackPrice` (also standardized) for a market order with no price/offset/auction.
+ * @param order Order to price.
+ * @param oraclePriceData Oracle price source — use `MMOraclePriceData` for perp orders, `OraclePriceData` for spot.
+ * @param slot Current slot, used to evaluate auction progress.
+ * @param fallbackPrice Price to return for a market order with no auction/offset/fixed price (e.g. a mark or oracle price), PRICE_PRECISION (1e6).
+ * @param tickSize Market's order tick size, PRICE_PRECISION (1e6). Defaults to `ONE` (no effective standardization).
+ * @returns Limit price, PRICE_PRECISION (1e6); `undefined` if the order has no resolvable price and no `fallbackPrice` was given.
+ */
+function getLimitPrice(order, oraclePriceData, slot, fallbackPrice, tickSize = numericConstants_1.ONE) {
     if (hasAuctionPrice(order, slot)) {
-        return (0, auction_1.getAuctionPrice)(order, slot, oraclePriceData.price);
+        return (0, auction_1.getAuctionPrice)(order, slot, oraclePriceData.price, tickSize);
     }
     else if (!order.oraclePriceOffset.eq(numericConstants_1.ZERO)) {
-        return anchor_1.BN.max(oraclePriceData.price.add(order.oraclePriceOffset), numericConstants_1.ONE);
+        const limitPrice = anchor_1.BN.max(oraclePriceData.price.add(order.oraclePriceOffset), tickSize);
+        return standardizePrice(limitPrice, tickSize, order.direction);
     }
     else if (order.price.eq(numericConstants_1.ZERO)) {
-        return fallbackPrice;
+        return fallbackPrice === undefined
+            ? undefined
+            : standardizePrice(fallbackPrice, tickSize, order.direction);
     }
     else {
         return order.price;
     }
 }
 exports.getLimitPrice = getLimitPrice;
+/** True if the order has any way to resolve a limit price right now: a fixed `price`, a nonzero oracle offset, or an auction still in progress. */
 function hasLimitPrice(order, slot) {
     return (order.price.gt(numericConstants_1.ZERO) ||
         !order.oraclePriceOffset.eq(numericConstants_1.ZERO) ||
         !(0, auction_1.isAuctionComplete)(order, slot));
 }
 exports.hasLimitPrice = hasLimitPrice;
+/** True if the order still has an active (incomplete) auction with a nonzero start or end price. */
 function hasAuctionPrice(order, slot) {
     return (!(0, auction_1.isAuctionComplete)(order, slot) &&
         (!order.auctionStartPrice.eq(numericConstants_1.ZERO) || !order.auctionEndPrice.eq(numericConstants_1.ZERO)));
 }
 exports.hasAuctionPrice = hasAuctionPrice;
+/**
+ * True if the AMM is currently a fillable liquidity source for `order` — either it's
+ * expired (always fillable to clean up), or the AMM has fillable size at the order's limit
+ * price AND is an allowed liquidity source right now (`isFallbackAvailableLiquiditySource`,
+ * which gates on oracle validity and low-risk-for-AMM classification).
+ * @param order Order to check.
+ * @param market Perp market the order is on.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param slot Current slot.
+ * @param ts Current unix timestamp (seconds), used for expiry.
+ * @param state Global state, providing oracle guard rails and paused-operations flags.
+ * @returns `true` if the AMM may currently fill this order.
+ */
 function isFillableByVAMM(order, market, mmOraclePriceData, slot, ts, state) {
     return (((0, auction_1.isFallbackAvailableLiquiditySource)(order, mmOraclePriceData, slot, state, market) &&
         calculateBaseAssetAmountForAmmToFulfill(order, market, mmOraclePriceData, slot).gt(numericConstants_1.ZERO)) ||
         isOrderExpired(order, ts));
 }
 exports.isFillableByVAMM = isFillableByVAMM;
+/**
+ * True if filling `order` against the AMM is considered low-risk even when the MM oracle
+ * isn't fully valid, approximating `Order::is_low_risk_for_amm` in
+ * `programs/velocity/src/state/user.rs`. Always false for spot orders. True when the order
+ * was placed at or before the MM oracle's slot (so it can't be exploiting oracle staleness),
+ * during liquidation, or when the order carries the `SafeTriggerOrder` bit flag.
+ * @param order Order to check.
+ * @param mmOraclePriceData Current MM oracle price data, used for its `slot`.
+ * @param isLiquidation Whether the fill is part of a liquidation (always low-risk if so).
+ * @returns `true` if the order is low-risk for an AMM fill under a degraded oracle.
+ */
 function isLowRiskForAmm(order, mmOraclePriceData, isLiquidation) {
     if ((0, types_1.isVariant)(order.marketType, 'spot')) {
         return false;
@@ -71,11 +131,24 @@ function isLowRiskForAmm(order, mmOraclePriceData, isLiquidation) {
         (order.bitFlags & types_1.OrderBitFlag.SafeTriggerOrder) !== 0);
 }
 exports.isLowRiskForAmm = isLowRiskForAmm;
+/**
+ * Calculates how much of `order` the AMM can currently fill, capped by both the order's
+ * limit price (via `calculateBaseAssetAmountToFillUpToLimitPrice`, standardized to
+ * `market.orderTickSize`) and the AMM's own max fillable size
+ * (`calculateMaxBaseAssetAmountFillable`). Returns zero for a not-yet-triggered
+ * trigger order. Prices against `calculateUpdatedAMM` (i.e. the repegged/curve-updated AMM
+ * state), not the raw stored reserves.
+ * @param order Order to evaluate.
+ * @param market Perp market the order is on.
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @param slot Current slot.
+ * @returns Fillable base asset amount, BASE_PRECISION (1e9).
+ */
 function calculateBaseAssetAmountForAmmToFulfill(order, market, mmOraclePriceData, slot) {
     if (mustBeTriggered(order) && !isTriggered(order)) {
         return numericConstants_1.ZERO;
     }
-    const limitPrice = getLimitPrice(order, mmOraclePriceData, slot);
+    const limitPrice = getLimitPrice(order, mmOraclePriceData, slot, undefined, market.orderTickSize);
     let baseAssetAmount;
     const updatedAMM = (0, amm_1.calculateUpdatedAMM)(market.amm, mmOraclePriceData);
     if (limitPrice !== undefined) {
@@ -88,6 +161,21 @@ function calculateBaseAssetAmountForAmmToFulfill(order, market, mmOraclePriceDat
     return anchor_1.BN.min(maxBaseAssetAmount, baseAssetAmount);
 }
 exports.calculateBaseAssetAmountForAmmToFulfill = calculateBaseAssetAmountForAmmToFulfill;
+/**
+ * Calculates how much base asset the AMM can trade against `order` without crossing its
+ * limit price, adjusting the limit by one tick in the order's favor (so the AMM never fills
+ * exactly at the boundary) before asking `calculateMaxBaseAssetAmountToTrade` how much
+ * inventory the AMM has at that price. Returns zero if the AMM would only trade in the
+ * opposite direction from the order. Caps the result at the order's unfilled remainder.
+ * @param order Order being filled.
+ * @param amm AMM state to trade against.
+ * @param marketStats Market stats needed to compute spread reserves.
+ * @param orderStepSize Market's order step size, BASE_PRECISION (1e9), used to standardize the result.
+ * @param orderTickSize Market's order tick size, PRICE_PRECISION (1e6), used to adjust the limit price by one tick.
+ * @param limitPrice Order's limit price, PRICE_PRECISION (1e6).
+ * @param mmOraclePriceData Current MM oracle price data.
+ * @returns Fillable base asset amount up to the limit price, BASE_PRECISION (1e9).
+ */
 function calculateBaseAssetAmountToFillUpToLimitPrice(order, amm, marketStats, orderStepSize, orderTickSize, limitPrice, mmOraclePriceData) {
     const adjustedLimitPrice = (0, types_1.isVariant)(order.direction, 'long')
         ? limitPrice.sub(orderTickSize)
@@ -109,6 +197,15 @@ function isSameDirection(firstDirection, secondDirection) {
     return (((0, types_1.isVariant)(firstDirection, 'long') && (0, types_1.isVariant)(secondDirection, 'long')) ||
         ((0, types_1.isVariant)(firstDirection, 'short') && (0, types_1.isVariant)(secondDirection, 'short')));
 }
+/**
+ * True if `order.maxTs` has passed as of `ts`. Never true for trigger orders, non-`open`
+ * orders, or orders with no expiry (`maxTs == 0`).
+ * @param order Order to check.
+ * @param ts Current unix timestamp (seconds).
+ * @param enforceBuffer If true, extends `maxTs` by `bufferSeconds` before comparing, but only for limit orders (default false) — gives resting limit orders a grace period before being treated as expired.
+ * @param bufferSeconds Grace period in seconds applied when `enforceBuffer` is true (default 15).
+ * @returns `true` if the order has expired.
+ */
 function isOrderExpired(order, ts, enforceBuffer = false, bufferSeconds = 15) {
     if (mustBeTriggered(order) ||
         !(0, types_1.isVariant)(order.status, 'open') ||
@@ -125,18 +222,22 @@ function isOrderExpired(order, ts, enforceBuffer = false, bufferSeconds = 15) {
     return new anchor_1.BN(ts).gt(maxTs);
 }
 exports.isOrderExpired = isOrderExpired;
+/** True if `order.orderType` is `market`, `triggerMarket`, or `oracle`. */
 function isMarketOrder(order) {
     return (0, types_1.isOneOfVariant)(order.orderType, ['market', 'triggerMarket', 'oracle']);
 }
 exports.isMarketOrder = isMarketOrder;
+/** True if `order.orderType` is `limit` or `triggerLimit`. */
 function isLimitOrder(order) {
     return (0, types_1.isOneOfVariant)(order.orderType, ['limit', 'triggerLimit']);
 }
 exports.isLimitOrder = isLimitOrder;
+/** True if the order requires a trigger condition to fire before it becomes fillable (`triggerMarket`/`triggerLimit`). */
 function mustBeTriggered(order) {
     return (0, types_1.isOneOfVariant)(order.orderType, ['triggerMarket', 'triggerLimit']);
 }
 exports.mustBeTriggered = mustBeTriggered;
+/** True if a trigger order's condition has already fired (`triggeredAbove`/`triggeredBelow`). */
 function isTriggered(order) {
     return (0, types_1.isOneOfVariant)(order.triggerCondition, [
         'triggeredAbove',
@@ -144,6 +245,7 @@ function isTriggered(order) {
     ]);
 }
 exports.isTriggered = isTriggered;
+/** True if a limit order currently rests on the book — i.e. it's `postOnly`, or its auction (if any) has completed. Always false for non-limit orders. */
 function isRestingLimitOrder(order, slot) {
     if (!isLimitOrder(order)) {
         return false;
@@ -151,16 +253,25 @@ function isRestingLimitOrder(order, slot) {
     return order.postOnly || (0, auction_1.isAuctionComplete)(order, slot);
 }
 exports.isRestingLimitOrder = isRestingLimitOrder;
-const FLAG_IS_SIGNED_MSG = 0x01;
+/** True if the order was submitted via the signed-message (swift/off-chain relay) path (`OrderBitFlag.SignedMessage`). */
 function isSignedMsgOrder(order) {
-    return (order.bitFlags & FLAG_IS_SIGNED_MSG) !== 0;
+    return (order.bitFlags & types_1.OrderBitFlag.SignedMessage) !== 0;
 }
 exports.isSignedMsgOrder = isSignedMsgOrder;
-const FLAG_HAS_BUILDER = 0x10;
+/** True if the order carries a builder-fee attribution (`OrderBitFlag.HasBuilder`) — the associated builder is entitled to a fee cut on fill. */
 function hasBuilder(order) {
-    return (order.bitFlags & FLAG_HAS_BUILDER) !== 0;
+    return (order.bitFlags & types_1.OrderBitFlag.HasBuilder) !== 0;
 }
 exports.hasBuilder = hasBuilder;
+/**
+ * Resolves the effective base asset amount for a reduce-only order: caps it so the order
+ * can't flip the position through zero (a reduce-only long can close at most the existing
+ * short, and vice versa). Non-reduce-only orders pass through `order.baseAssetAmount`
+ * unchanged.
+ * @param order Order to resolve.
+ * @param existingBaseAssetAmount Current position size before this order fills, BASE_PRECISION (1e9, signed).
+ * @returns Effective base asset amount, BASE_PRECISION (1e9).
+ */
 function calculateOrderBaseAssetAmount(order, existingBaseAssetAmount) {
     if (!order.reduceOnly) {
         return order.baseAssetAmount;
@@ -175,12 +286,15 @@ function calculateOrderBaseAssetAmount(order, existingBaseAssetAmount) {
 exports.calculateOrderBaseAssetAmount = calculateOrderBaseAssetAmount;
 // ---------- inverse ----------
 /**
- * Invert the size-premium liability weight: given a target margin ratio (liability weight),
- * return the max `size` (AMM_RESERVE_PRECISION units) that still yields <= target.
- *
- * Returns:
- * - BN size (>=0) if bounded
- * - null if impossible (target < liabilityWeight) OR imfFactor == 0 (unbounded)
+ * Inverts `calculateSizePremiumLiabilityWeight` via binary search: given a target margin ratio
+ * (liability weight), finds the largest position `size` whose size-premium-adjusted liability
+ * weight is still `<= target`. Used to size down an order/position to stay under a margin-ratio
+ * target as size grows (the on-chain weight increases with `sqrt(size)` via `imfFactor`).
+ * @param target Target (max acceptable) liability weight, MARGIN_PRECISION (1e4).
+ * @param imfFactor Market's initial-margin-fraction scaling factor, SPOT_MARKET_IMF_PRECISION-scaled.
+ * @param liabilityWeight Market's base (zero-size) liability weight, MARGIN_PRECISION (1e4).
+ * @param market Perp market providing `maxOpenInterest` as a final cap on the result.
+ * @returns Max size, AMM_RESERVE_PRECISION (1e9), capped at `market.maxOpenInterest` (a zero `maxOpenInterest` means uncapped, per on-chain convention); `null` if `target < liabilityWeight` (impossible) or `imfFactor` is zero (weight is size-invariant, so no size bounds it).
  */
 function maxSizeForTargetLiabilityWeightBN(target, imfFactor, liabilityWeight, market) {
     if (target.lt(liabilityWeight))
@@ -212,9 +326,10 @@ function maxSizeForTargetLiabilityWeightBN(target, imfFactor, liabilityWeight, m
             hi = mid.sub(numericConstants_1.ONE);
         }
     }
-    // cap at max OI
+    // cap at max OI. A maxOpenInterest of 0 means no configured cap (unlimited),
+    // matching the on-chain convention — do not treat it as a hard cap of 0.
     const maxOpenInterest = market.maxOpenInterest;
-    if (lo.gt(maxOpenInterest)) {
+    if (!maxOpenInterest.isZero() && lo.gt(maxOpenInterest)) {
         return maxOpenInterest;
     }
     return lo;