@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/math/auction.ts

@@ -17,10 +17,11 @@ import {
 import { getVariant, OrderBitFlag, PerpMarketAccount } from '../types';
 import { getPerpMarketTierNumber } from './tiers';
 import { MMOraclePriceData } from '../oracles/types';
-import { isLowRiskForAmm } from './orders';
+import { isLowRiskForAmm, standardizePrice } from './orders';
 import { getOracleValidity } from './oracles';
-import { isOperationPaused } from './exchangeStatus';
+import { isAmmDrawdownPause, isOperationPaused } from './exchangeStatus';
 
+/** True if `order`'s auction has run its full `auctionDuration` (in slots) as of `slot`, or the order has no auction (`auctionDuration === 0`). */
 export function isAuctionComplete(order: Order, slot: number): boolean {
 	if (order.auctionDuration === 0) {
 		return true;
@@ -29,6 +30,27 @@ export function isAuctionComplete(order: Order, slot: number): boolean {
 	return new BN(slot).sub(order.slot).gt(new BN(order.auctionDuration));
 }
 
+/**
+ * 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 function isFallbackAvailableLiquiditySource(
 	order: Order,
 	mmOraclePriceData: MMOraclePriceData,
@@ -41,7 +63,22 @@ export function isFallbackAvailableLiquiditySource(
 		return false;
 	}
 
-	// TODO: include too much drawdown check & mm oracle volatility
+	if (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 = getOracleValidity(
 		market!,
@@ -77,35 +114,52 @@ export function 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.
  */
 export function getAuctionPrice(
 	order: Order,
 	slot: number,
-	oraclePrice: BN
+	oraclePrice: BN,
+	tickSize: BN = ONE
 ): BN {
 	if (
 		isOneOfVariant(order.orderType, ['market', 'triggerLimit']) ||
 		(isVariant(order.orderType, 'triggerMarket') &&
 			(order.bitFlags & OrderBitFlag.OracleTriggerMarket) === 0)
 	) {
-		return getAuctionPriceForFixedAuction(order, slot);
+		return getAuctionPriceForFixedAuction(order, slot, tickSize);
 	} else if (isVariant(order.orderType, 'limit')) {
 		if (order.oraclePriceOffset != null && !order.oraclePriceOffset.eq(ZERO)) {
-			return getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice);
+			return getAuctionPriceForOracleOffsetAuction(
+				order,
+				slot,
+				oraclePrice,
+				tickSize
+			);
 		} else {
-			return getAuctionPriceForFixedAuction(order, slot);
+			return getAuctionPriceForFixedAuction(order, slot, tickSize);
 		}
 	} else if (
 		isVariant(order.orderType, 'oracle') ||
 		(isVariant(order.orderType, 'triggerMarket') &&
 			(order.bitFlags & OrderBitFlag.OracleTriggerMarket) !== 0)
 	) {
-		return getAuctionPriceForOracleOffsetAuction(order, slot, oraclePrice);
+		return getAuctionPriceForOracleOffsetAuction(
+			order,
+			slot,
+			oraclePrice,
+			tickSize
+		);
 	} else {
 		throw Error(
 			`Cant get auction price for order type ${getVariant(order.orderType)}`
@@ -113,14 +167,29 @@ export function getAuctionPrice(
 	}
 }
 
-export function getAuctionPriceForFixedAuction(order: Order, slot: number): 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 function getAuctionPriceForFixedAuction(
+	order: Order,
+	slot: number,
+	tickSize: BN = ONE
+): BN {
 	const slotsElapsed = new BN(slot).sub(order.slot);
 
 	const deltaDenominator = new BN(order.auctionDuration);
 	const deltaNumerator = BN.min(slotsElapsed, deltaDenominator);
 
 	if (deltaDenominator.eq(ZERO)) {
-		return order.auctionEndPrice;
+		return standardizePrice(order.auctionEndPrice, tickSize, order.direction);
 	}
 
 	let priceDelta;
@@ -143,20 +212,27 @@ export function getAuctionPriceForFixedAuction(order: Order, slot: number): BN {
 		price = order.auctionStartPrice.sub(priceDelta);
 	}
 
-	return price;
+	return standardizePrice(price, tickSize, order.direction);
 }
 
 /**
- *
- * @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).
  */
 export function getAuctionPriceForOracleOffsetAuction(
 	order: Order,
 	slot: number,
-	oraclePrice: BN
+	oraclePrice: BN,
+	tickSize: BN = ONE
 ): BN {
 	const slotsElapsed = new BN(slot).sub(order.slot);
 
@@ -164,7 +240,8 @@ export function getAuctionPriceForOracleOffsetAuction(
 	const deltaNumerator = BN.min(slotsElapsed, deltaDenominator);
 
 	if (deltaDenominator.eq(ZERO)) {
-		return BN.max(oraclePrice.add(order.auctionEndPrice), ONE);
+		const price = BN.max(oraclePrice.add(order.auctionEndPrice), tickSize);
+		return standardizePrice(price, tickSize, order.direction);
 	}
 
 	let priceOffsetDelta;
@@ -187,9 +264,25 @@ export function getAuctionPriceForOracleOffsetAuction(
 		priceOffset = order.auctionStartPrice.sub(priceOffsetDelta);
 	}
 
-	return BN.max(oraclePrice.add(priceOffset), ONE);
+	const price = BN.max(oraclePrice.add(priceOffset), tickSize);
+	return standardizePrice(price, tickSize, order.direction);
 }
 
+/**
+ * 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 function deriveOracleAuctionParams({
 	direction,
 	oraclePrice,
@@ -241,9 +334,18 @@ export function 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).
  */
 export function getTriggerAuctionStartPrice(params: {
 	perpMarket: PerpMarketAccount;
@@ -335,9 +437,16 @@ export function getTriggerAuctionStartPrice(params: {
 }
 
 /**
- *
- * @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 function getTriggerAuctionStartAndExecutionPrice(params: {
 	perpMarket: PerpMarketAccount;

package/src/math/bankruptcy.ts

@@ -1,8 +1,44 @@
 import { ZERO } from '../constants/numericConstants';
 import { hasOpenOrders } from './position';
-import { isVariant } from '../types';
+import { isVariant, PerpPosition, PositionFlag } from '../types';
 import { User } from '../user';
 
+/**
+ * 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: PerpPosition
+): boolean {
+	// defensive ?? ZERO matches user.ts's reads of this field (see its `//TODO remove ? later`)
+	if ((position.isolatedPositionScaledBalance ?? ZERO).gt(ZERO)) {
+		return false;
+	}
+
+	return (
+		position.baseAssetAmount.eq(ZERO) &&
+		position.quoteAssetAmount.lt(ZERO) &&
+		!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.
+ */
 export function isUserBankrupt(user: User): boolean {
 	const userAccount = user.getUserAccountOrThrow();
 	let hasLiability = false;
@@ -18,6 +54,11 @@ export function isUserBankrupt(user: User): boolean {
 	}
 
 	for (const position of userAccount.perpPositions) {
+		// Isolated perp positions are handled by isIsolatedPositionBankrupt
+		if (user.isPerpPositionIsolated(position)) {
+			continue;
+		}
+
 		if (
 			!position.baseAssetAmount.eq(ZERO) ||
 			position.quoteAssetAmount.gt(ZERO) ||
@@ -33,3 +74,65 @@ export function isUserBankrupt(user: User): boolean {
 
 	return hasLiability;
 }
+
+/**
+ * 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 function isIsolatedPositionBankrupt(
+	user: User,
+	marketIndex: number
+): boolean {
+	const position = user.getPerpPositionOrThrow(marketIndex);
+
+	if (!user.isPerpPositionIsolated(position)) {
+		throw new Error(
+			`Perp position ${marketIndex} is not an isolated position (InvalidPerpPosition)`
+		);
+	}
+
+	return isIsolatedPositionEconomicallyBankrupt(position);
+}
+
+/**
+ * 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 function hasIsolatedMarginBankrupt(user: User): boolean {
+	const userAccount = user.getUserAccountOrThrow();
+	for (const position of userAccount.perpPositions) {
+		if (!user.isPerpPositionIsolated(position)) {
+			continue;
+		}
+		if (
+			(position.positionFlag & PositionFlag.Bankruptcy) !== 0 ||
+			isIsolatedPositionEconomicallyBankrupt(position)
+		) {
+			return true;
+		}
+	}
+	return false;
+}

package/src/math/builder.ts

@@ -1,4 +1,5 @@
 import { PublicKey } from '@solana/web3.js';
+import { BN } from '../isomorphic/anchor';
 import {
 	OrderParams,
 	ReferrerStatus,
@@ -7,10 +8,35 @@ import {
 	UserStatsAccount,
 } from '../types';
 
+const BUILDER_FEE_TENTH_BPS_DENOMINATOR = new BN(100_000);
+
 /**
- * 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 function calculateBuilderFee(
+	quoteAssetAmount: BN,
+	builderFeeTenthBps: number
+): BN {
+	return quoteAssetAmount
+		.mul(new BN(builderFeeTenthBps))
+		.div(BUILDER_FEE_TENTH_BPS_DENOMINATOR);
+}
+
+/**
+ * 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 function isBuilderReferral(
 	userStats: Pick<UserStatsAccount, 'referrerStatus'>
@@ -19,9 +45,13 @@ export function isBuilderReferral(
 }
 
 /**
- * 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 function escrowHasReferrer(
 	escrow: Pick<RevenueShareEscrowAccount, 'referrer'>
@@ -30,8 +60,12 @@ export function escrowHasReferrer(
 }
 
 /**
- * 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 function hasBuilderParams(
 	orderParams: Pick<OrderParams, 'builderIdx' | 'builderFeeTenthBps'>
@@ -45,20 +79,52 @@ export function hasBuilderParams(
 }
 
 const FLAG_IS_OPEN = 0x01;
+/**
+ * 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 function isBuilderOrderOpen(order: RevenueShareOrder): boolean {
 	return (order.bitFlags & FLAG_IS_OPEN) !== 0;
 }
 
 const FLAG_IS_COMPLETED = 0x02;
+/**
+ * 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 function isBuilderOrderCompleted(order: RevenueShareOrder): boolean {
 	return (order.bitFlags & FLAG_IS_COMPLETED) !== 0;
 }
 
 const FLAG_IS_REFERRAL = 0x04;
+/**
+ * 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 function isBuilderOrderReferral(order: RevenueShareOrder): boolean {
 	return (order.bitFlags & FLAG_IS_REFERRAL) !== 0;
 }
 
+/**
+ * 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 function isBuilderOrderAvailable(order: RevenueShareOrder): boolean {
 	return !isBuilderOrderOpen(order) && !isBuilderOrderCompleted(order);
 }

package/src/math/conversion.ts

@@ -1,6 +1,19 @@
 import { BN } from '../isomorphic/anchor';
 import { PRICE_PRECISION } from '../constants/numericConstants';
 
+/**
+ * Converts a fixed-point `BN` into a human-readable JS `number` by dividing out `precision`.
+ * Correctly handles negative `bigNumber` values: `bn.js`'s `.div()`/`.mod()` truncate toward
+ * zero (matching JS `%` semantics), so the whole and fractional parts recombine with consistent
+ * sign without needing separate negative-number handling. Precision beyond what a JS `number`
+ * (IEEE-754 double) can represent exactly may be lost — this is a display/estimation helper, not
+ * for further on-chain-precision math.
+ *
+ * @param {BN} bigNumber - The value to convert; `null`/`undefined` return 0 (a `BN` instance for
+ *   zero is still an object and thus truthy, so it falls through to the normal division below)
+ * @param {BN} [precision] - The fixed-point precision to divide out; defaults to `PRICE_PRECISION` (1e6)
+ * @return {number} The value as a JS number, in the same units `precision` represents one whole unit of
+ */
 export const convertToNumber = (
 	bigNumber: BN,
 	precision: BN = PRICE_PRECISION
@@ -12,6 +25,14 @@ export const convertToNumber = (
 	);
 };
 
+/**
+ * Converts a human-readable JS `number` into a fixed-point `BN` scaled by `precision`. The
+ * fractional part is rounded (`Math.round`) to the nearest unit of `precision`, not truncated.
+ *
+ * @param {number} value - The human-readable value to convert
+ * @param {BN} precision - The fixed-point precision to scale by (e.g. `QUOTE_PRECISION`, `BASE_PRECISION`)
+ * @return {BN} `value` scaled by `precision`
+ */
 export function convertToBN(value: number, precision: BN): BN {
 	// Get the whole part using Math.floor
 	const wholePart = Math.floor(value);