@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/dlob/DLOB.d.ts

@@ -5,9 +5,9 @@
  * Used by keeper bots to identify the best maker orders to match against taker fills.
  *
  * Key types:
- *   {@link DLOBNode}        — a single order node with price/size/user info (DLOBNode.ts)
- *   {@link DLOBSubscriber}  — subscribes to on-chain accounts and keeps the DLOB live (DLOBSubscriber.ts)
- *   {@link NodeList}        — sorted linked list of DLOBNodes per side/market (NodeList.ts)
+ *   `DLOBNode`        — a single order node with price/size/user info (DLOBNode.ts)
+ *   `DLOBSubscriber`  — subscribes to on-chain accounts and keeps the DLOB live (DLOBSubscriber.ts)
+ *   `NodeList`        — sorted linked list of DLOBNodes per side/market (NodeList.ts)
  *   `orderBookLevels.ts`    — aggregated L2/L3 book level construction for quoting
  */
 import { NodeList } from './NodeList';
@@ -20,11 +20,14 @@ import { SlotSubscriber } from '../slot/SlotSubscriber';
 import { UserMap } from '../userMap/userMap';
 import { PublicKey } from '@solana/web3.js';
 import { L2OrderBook, L2OrderBookGenerator, L3OrderBook } from './orderBookLevels';
+/** An on-chain order paired with the pubkey of its owning `User` account. */
 export type DLOBOrder = {
     user: PublicKey;
     order: Order;
 };
+/** A list of `DLOBOrder`s, e.g. the flattened output of `DLOB.getDLOBOrders`. */
 export type DLOBOrders = DLOBOrder[];
+/** The full set of sorted `NodeList`s the DLOB maintains for one market, one per order category and side. */
 export type MarketNodeLists = {
     restingLimit: {
         ask: NodeList<'restingLimit'>;
@@ -59,144 +62,560 @@ type OrderBookCallback = () => void;
  * Currently used in functions that rely on getBestNode
  */
 export type DLOBFilterFcn = (node: DLOBNode) => boolean;
+/** A taker node paired with the maker node(s) it should be filled against. `makerNodes` is empty when the fill is expected to route through fallback (e.g. vAMM) liquidity or is an expiration/cancellation rather than a maker match. */
 export type NodeToFill = {
     node: DLOBNode;
     makerNodes: DLOBNode[];
 };
+/** A trigger order whose `triggerPrice` has been crossed and is ready to be triggered on-chain. */
 export type NodeToTrigger = {
     node: TriggerOrderNode;
 };
+/**
+ * In-memory order book. Indexes every open order it is given into per-market, per-side sorted
+ * `NodeList`s (see `MarketNodeLists`), and provides the crossing/fill-finding logic
+ * (`findNodesToFill`) and aggregated book views (`getL2`/`getL3`) that keepers and clients use to
+ * predict and drive on-chain fills. A `DLOB` instance is normally built once per slot (e.g. via
+ * `initFromUserMap`) rather than mutated indefinitely, since state changes (`insertOrder`,
+ * `delete`) must be paired with the caller's own bookkeeping of what's already been applied.
+ */
 export declare class DLOB {
+    /** Order signatures (`getOrderSignature`) currently open, keyed by market type (`'perp'`/`'spot'`). */
     openOrders: Map<MarketTypeStr, Set<string>>;
+    /** Every market's `MarketNodeLists`, keyed by market type then market index. */
     orderLists: Map<MarketTypeStr, Map<number, MarketNodeLists>>;
+    /** The highest slot `updateRestingLimitOrders` has processed; used to skip redundant re-promotion of taking→resting orders when called with a slot that's already been seen. */
     maxSlotForRestingLimitOrders: number;
+    /** Set to `true` once `initFromUserMap` has successfully populated this instance; `initFromUserMap` is then a no-op. */
     initialized: boolean;
+    /** Constructs an empty, uninitialized `DLOB` with no orders. Call `initFromUserMap` (or `insertOrder`/`insertSignedMsgOrder`) to populate it. */
     constructor();
     private init;
     private getOpenOrdersForMarketType;
     private getOrderListsForMarketType;
     private tryGetMarketNodeLists;
     private getMarketNodeLists;
+    /** Empties every order list and resets the DLOB to its freshly-constructed (uninitialized) state, including `maxSlotForRestingLimitOrders` and `initialized`. */
     clear(): void;
     /**
-     * initializes a new DLOB instance
+     * Populates this DLOB from every open order across every user in `userMap`. For reduce-only
+     * orders, the fillable amount is capped via `calculateOrderBaseAssetAmount` against the
+     * user's existing perp position for that market, rather than trusting the order's full
+     * stated `baseAssetAmount`. No-ops (returns `false` immediately) if this instance has already
+     * been initialized — call `clear()` first to rebuild from scratch.
      *
-     * @returns a promise that resolves when the DLOB is initialized
+     * @param userMap map of all users' accounts to index orders from
+     * @param slot slot orders are inserted at, used to classify taking vs. resting limit orders
+     * @returns `true` if this call performed initialization, `false` if it was already initialized
      */
     initFromUserMap(userMap: UserMap, slot: number): Promise<boolean>;
+    /**
+     * Inserts a single on-chain order into the appropriate `NodeList` for its market/side/type.
+     * No-ops if the order's status isn't `open`, or if its `orderType` isn't one of the
+     * DLOB-supported types (`market`, `limit`, `triggerMarket`, `triggerLimit`, `oracle`).
+     * Lazily creates the market's `MarketNodeLists` (via `addOrderList`) on first insert for that
+     * market. Which list the order lands in (taking vs. resting limit, floating, market, or
+     * inactive trigger) is decided by `getListForOnChainOrder`.
+     *
+     * @param order the on-chain order to insert
+     * @param userAccount base58 pubkey string of the order's owner
+     * @param slot current slot, used to classify taking vs. resting limit orders
+     * @param baseAssetAmount remaining fillable base amount, BASE_PRECISION (1e9) — for
+     *   reduce-only orders this should be the position-capped amount (see
+     *   `calculateOrderBaseAssetAmount`), not the raw `order.baseAssetAmount`
+     * @param onInsert optional callback invoked after a successful insert
+     */
     insertOrder(order: Order, userAccount: string, slot: number, baseAssetAmount: BN, onInsert?: OrderBookCallback): void;
+    /**
+     * Inserts an off-chain signed-message order (not yet landed on-chain) into the market's
+     * `signedMsg` bid/ask list, unconditionally (no status/order-type filtering, unlike
+     * `insertOrder`). Lazily creates the market's `MarketNodeLists` on first insert.
+     *
+     * @param order the signed-message order to insert
+     * @param userAccount base58 pubkey string of the order's owner
+     * @param baseAssetAmount remaining fillable base amount, BASE_PRECISION (1e9); defaults to `order.baseAssetAmount`
+     * @param onInsert optional callback invoked after insert
+     */
     insertSignedMsgOrder(order: Order, userAccount: string, baseAssetAmount?: BN, onInsert?: OrderBookCallback): void;
+    /** Creates and registers an empty `MarketNodeLists` (all six order categories, both sides) for `marketIndex`, overwriting any existing lists for that market. */
     addOrderList(marketType: MarketTypeStr, marketIndex: number): void;
+    /**
+     * Removes an order from whichever `NodeList` it currently lives in. No-ops if the order's
+     * status isn't `open`. First calls `updateRestingLimitOrders(slot)` so a taking-limit order
+     * that has since become a resting-limit order is looked up (and removed from) the correct
+     * list.
+     *
+     * @param order the order to remove
+     * @param userAccount pubkey of the order's owner
+     * @param slot current slot, used to resolve which list the order is currently in
+     * @param onDelete optional callback invoked after a successful delete
+     */
     delete(order: Order, userAccount: PublicKey, slot: number, onDelete?: OrderBookCallback): void;
+    /**
+     * Determines which `NodeList` an order belongs in, given its current state and the slot:
+     * a trigger order (`triggerMarket`/`triggerLimit`) that hasn't fired yet goes in
+     * `trigger.above`/`trigger.below`; a market/oracle-type order goes in `market`; a limit order
+     * with a non-zero `oraclePriceOffset` goes in `floatingLimit`; otherwise a limit order goes in
+     * `restingLimit` once its auction is complete or it's post-only (per `isRestingLimitOrder`),
+     * and in `takingLimit` while still auctioning.
+     *
+     * @param order the order to classify
+     * @param slot current slot, used to evaluate `isRestingLimitOrder`
+     * @returns the matching `NodeList`, or `undefined` if the order's market has no `MarketNodeLists` registered yet (e.g. `insertOrder`/`addOrderList` hasn't been called for it)
+     */
     getListForOnChainOrder(order: Order, slot: number): NodeList<any> | undefined;
     private getListForOnChainOrderOrThrow;
+    /**
+     * Promotes any `takingLimit` orders across all perp and spot markets whose auction has since
+     * completed (per `isRestingLimitOrder`) into their market's `restingLimit` list. No-ops if
+     * `slot` is not newer than the last slot this was called with (`maxSlotForRestingLimitOrders`),
+     * so it is cheap to call defensively before any read that depends on resting-limit state
+     * being current (most getters here do so internally).
+     *
+     * @param slot current slot
+     */
     updateRestingLimitOrders(slot: number): void;
+    /** Does the `takingLimit` → `restingLimit` promotion (see `updateRestingLimitOrders`) for every market of one market type. */
     updateRestingLimitOrdersForMarketType(slot: number, marketTypeStr: MarketTypeStr): void;
+    /**
+     * Looks up an order by id/owner across every `NodeList` in the DLOB (perp and spot, all
+     * categories/sides) via `getNodeLists`. O(number of lists); prefer a narrower lookup (e.g.
+     * `NodeList.get`) if you already know the order's market/type.
+     *
+     * @param orderId the order's id (unique per user account)
+     * @param userAccount pubkey of the order's owner
+     * @returns the matching `Order`, or `undefined` if not found in any list
+     */
     getOrder(orderId: number, userAccount: PublicKey): Order | undefined;
+    /**
+     * Top-level entry point for keepers: finds every node in one market that is currently
+     * fillable, combining four sources — crossing resting-limit orders
+     * (`findRestingLimitOrderNodesToFill`), taking (still-auctioning) orders that cross a maker or
+     * fallback price (`findTakingNodesToFill`), expired orders to cancel/settle
+     * (`findExpiredNodesToFill`), and unfillable reduce-only orders below the step size to cancel
+     * (`findUnfillableReduceOnlyOrdersToCancel`). Returns `[]` immediately if fills are paused for
+     * this market (`fillPaused`). The market's `orderTickSize` is read from `marketAccount` and
+     * threaded through to every price comparison below so all crossing checks agree with on-chain
+     * price standardization.
+     *
+     * @param marketIndex the market to scan
+     * @param fallbackBid best available non-DLOB bid (e.g. vAMM), PRICE_PRECISION (1e6); `undefined` disables fallback-bid crossing checks
+     * @param fallbackAsk best available non-DLOB ask (e.g. vAMM), PRICE_PRECISION (1e6); `undefined` disables fallback-ask crossing checks
+     * @param slot current slot
+     * @param ts current unix timestamp (seconds), used to find expired orders
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`; determines whether `oraclePriceData`/`marketAccount` are typed as spot or perp
+     * @param oraclePriceData oracle price data for the market (`MMOraclePriceData` for perp, `OraclePriceData` for spot)
+     * @param stateAccount global protocol state, used for pause checks and fee-tier maker rebates
+     * @param marketAccount the market's account, used for `orderTickSize`/`orderStepSize` and pause checks
+     * @returns deduplicated `NodeToFill`s (see `mergeNodesToFill`) merging resting-limit and taking-order matches, plus expired and cancel-eligible nodes appended
+     */
     findNodesToFill<T extends MarketType>(marketIndex: number, fallbackBid: BN | undefined, fallbackAsk: BN | undefined, slot: number, ts: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
     } ? OraclePriceData : MMOraclePriceData, stateAccount: StateAccount, marketAccount: T extends {
         spot: unknown;
     } ? SpotMarketAccount : PerpMarketAccount): NodeToFill[];
+    /**
+     * Reads the tier-0 maker rebate fraction (`makerRebateNumerator / makerRebateDenominator`)
+     * for a market from `stateAccount`'s perp/spot fee structure, then scales the numerator up by
+     * the market's `feeAdjustment` percentage if one is set. Used by `findRestingLimitOrderNodesToFill`
+     * to size the buffer added to fallback prices so fallback fills aren't triggered by rebate-sized
+     * noise.
+     *
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param stateAccount global protocol state holding the perp/spot fee tier tables
+     * @param marketAccount the specific market, whose optional `feeAdjustment` (percent) scales the rebate
+     * @returns the rebate as a numerator/denominator pair (unitless fraction, not a fixed-point BN)
+     */
     getMakerRebate(marketType: MarketType, stateAccount: StateAccount, marketAccount: PerpMarketAccount | SpotMarketAccount): {
         makerRebateNumerator: number;
         makerRebateDenominator: number;
     };
+    /**
+     * Merges two `NodeToFill` arrays (typically resting-limit crossings and taking-order
+     * crossings for the same market/pass) by taker order signature, concatenating `makerNodes`
+     * for any taker that appears in both — e.g. an order that both crosses a resting maker and
+     * separately crosses fallback liquidity ends up as one `NodeToFill` with both maker sources.
+     *
+     * @param restingLimitOrderNodesToFill fills found via resting-limit crossing
+     * @param takingOrderNodesToFill fills found via taking-order crossing
+     * @returns one `NodeToFill` per distinct taker order, with all matched maker nodes combined
+     */
     mergeNodesToFill(restingLimitOrderNodesToFill: NodeToFill[], takingOrderNodesToFill: NodeToFill[]): NodeToFill[];
+    /**
+     * Finds resting-limit-order fills for a market: resting bids/asks that cross each other
+     * (`findCrossingRestingLimitOrders`), plus resting asks that cross the fallback bid and
+     * resting bids that cross the fallback ask (each skipped entirely if the AMM is paused).
+     * The fallback price on each side is tightened by the maker rebate before comparing, so a
+     * maker order priced exactly at the rebate-adjusted fallback isn't spuriously flagged as
+     * crossing (`fallbackBidWithBuffer = fallbackBid - fallbackBid * makerRebateNumerator / makerRebateDenominator`,
+     * and symmetrically for the ask).
+     *
+     * @param marketIndex the market to scan
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market
+     * @param isAmmPaused if true, skips fallback-crossing checks (only maker-vs-maker crossings are returned)
+     * @param stateAccount global protocol state, forwarded to fallback-availability checks
+     * @param marketAccount the market's account, forwarded to fallback-availability checks
+     * @param makerRebateNumerator numerator of the maker rebate fraction (see `getMakerRebate`)
+     * @param makerRebateDenominator denominator of the maker rebate fraction (see `getMakerRebate`)
+     * @param fallbackAsk best available non-DLOB ask, PRICE_PRECISION (1e6); `undefined` skips fallback-ask crossing
+     * @param fallbackBid best available non-DLOB bid, PRICE_PRECISION (1e6); `undefined` skips fallback-bid crossing
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6), threaded into every price comparison; omit to fall back to no rounding
+     * @returns `NodeToFill`s for maker-crossing-maker and maker-crossing-fallback matches
+     */
     findRestingLimitOrderNodesToFill<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
     } ? OraclePriceData : MMOraclePriceData, isAmmPaused: boolean, stateAccount: StateAccount, marketAccount: T extends {
         spot: unknown;
-    } ? SpotMarketAccount : PerpMarketAccount, makerRebateNumerator: number, makerRebateDenominator: number, fallbackAsk: BN | undefined, fallbackBid: BN | undefined): NodeToFill[];
+    } ? SpotMarketAccount : PerpMarketAccount, makerRebateNumerator: number, makerRebateDenominator: number, fallbackAsk: BN | undefined, fallbackBid: BN | undefined, tickSize?: BN): NodeToFill[];
+    /**
+     * Finds fills for taking (still-auctioning) orders: taking asks crossing resting bids or the
+     * fallback bid, and taking bids crossing resting asks or the fallback ask
+     * (`findTakingNodesCrossingMakerNodes` / `findNodesCrossingFallbackLiquidity`). Fallback
+     * crossing checks are skipped entirely when `isAmmPaused`. For spot markets, a taking order is
+     * only allowed to cross the opposite fallback price if doing so wouldn't also require crossing
+     * beyond the *other* fallback price (see the inline `fallbackBid`/`fallbackAsk` guards) —
+     * this prevents a taking order from routing through DLOB makers priced worse than the AMM.
+     *
+     * @param marketIndex the market to scan
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market
+     * @param isAmmPaused if true, skips fallback-crossing checks
+     * @param state global protocol state, forwarded to fallback-availability checks
+     * @param marketAccount the market's account, forwarded to fallback-availability checks
+     * @param fallbackAsk best available non-DLOB ask, PRICE_PRECISION (1e6); `undefined` skips ask-side fallback crossing
+     * @param fallbackBid best available non-DLOB bid, PRICE_PRECISION (1e6); `undefined` skips bid-side fallback crossing
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6), threaded into every price comparison; omit to fall back to no rounding
+     * @returns `NodeToFill`s for taking orders that cross a resting maker or fallback liquidity
+     */
     findTakingNodesToFill<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
     } ? OraclePriceData : MMOraclePriceData, isAmmPaused: boolean, state: StateAccount, marketAccount: T extends {
         spot: unknown;
-    } ? SpotMarketAccount : PerpMarketAccount, fallbackAsk: BN | undefined, fallbackBid?: BN | undefined): NodeToFill[];
+    } ? SpotMarketAccount : PerpMarketAccount, fallbackAsk: BN | undefined, fallbackBid?: BN | undefined, tickSize?: BN): NodeToFill[];
+    /**
+     * Walks `takerNodeGenerator` (taking bids or asks, sorted by arrival slot) against a fresh
+     * maker-side generator (built per taker via `makerNodeGeneratorFn`, e.g.
+     * `getRestingLimitBids`) and records a `NodeToFill` for every taker/maker pair that
+     * `doesCross` accepts, skipping same-user matches. For each match this method also **mutates
+     * DLOB state**: it applies the simulated fill to both the maker's and taker's order lists
+     * (via `NodeList.update`) so subsequent iterations see updated `baseAssetAmountFilled` and a
+     * taker stops matching once fully filled. Because maker nodes (sorted by price) are scanned
+     * in order, `doesCross` returning false breaks out of the maker loop entirely — this is
+     * correct for resting-limit makers but relies on the maker generator being price-sorted, not
+     * time-sorted.
+     *
+     * @param marketIndex the market being scanned (used only to route signed-message taker fills into the right list)
+     * @param slot current slot, forwarded to price lookups
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market
+     * @param takerNodeGenerator taking orders to check, e.g. from `getTakingAsks`/`getTakingBids`
+     * @param makerNodeGeneratorFn factory invoked once per taker to get a fresh maker-side generator, e.g. `getRestingLimitBids`/`getRestingLimitAsks`
+     * @param doesCross given the taker's price (`undefined` if it has none, e.g. still mid-auction) and the maker's price, returns whether they cross
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6), threaded into all price lookups
+     * @returns one `NodeToFill` per matched taker/maker pair (a taker matched against multiple makers yields multiple entries, each with one maker)
+     */
     findTakingNodesCrossingMakerNodes<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
     } ? OraclePriceData : MMOraclePriceData, takerNodeGenerator: Generator<DLOBNode>, makerNodeGeneratorFn: (marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData) => Generator<DLOBNode>, doesCross: (takerPrice: BN | undefined, makerPrice: BN) => boolean): NodeToFill[];
+    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn, tickSize?: BN) => Generator<DLOBNode>, doesCross: (takerPrice: BN | undefined, makerPrice: BN) => boolean, tickSize?: BN): NodeToFill[];
+    /**
+     * Scans `nodeGenerator` for nodes that both cross the fallback price (`doesCross`, evaluated
+     * against each node's `getLimitPrice`, or crossing unconditionally if the node has no limit
+     * price) and have fallback liquidity actually available to fill against. For spot markets,
+     * post-only orders are skipped (they can never take against the AMM) and fallback liquidity
+     * is always considered available; for perp markets, availability additionally requires
+     * `isFallbackAvailableLiquiditySource` (broadly: the order's auction is complete and the
+     * oracle is valid enough for AMM fills). Does not mutate any order state — unlike
+     * `findTakingNodesCrossingMakerNodes`, fallback fills are expected to be sized/settled
+     * on-chain rather than simulated here.
+     *
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param slot current slot
+     * @param oraclePriceData oracle price data for the market
+     * @param nodeGenerator candidate nodes to check, e.g. resting-limit or taking orders
+     * @param doesCross given a node's limit price (`undefined` if it has none), returns whether it crosses the fallback price
+     * @param state global protocol state, used by the perp fallback-availability check
+     * @param marketAccount the market's account, used by the perp fallback-availability check
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6), used to resolve each node's limit price
+     * @returns `NodeToFill`s with an empty `makerNodes` array (the fill is expected to route through fallback liquidity, not a DLOB maker)
+     */
     findNodesCrossingFallbackLiquidity<T extends MarketType>(marketType: T, slot: number, oraclePriceData: T extends {
         spot: unknown;
     } ? OraclePriceData : MMOraclePriceData, nodeGenerator: Generator<DLOBNode>, doesCross: (nodePrice: BN | undefined) => boolean, state: StateAccount, marketAccount: T extends {
         spot: unknown;
-    } ? SpotMarketAccount : PerpMarketAccount): NodeToFill[];
+    } ? SpotMarketAccount : PerpMarketAccount, tickSize?: BN): NodeToFill[];
+    /**
+     * Finds orders in a market that are eligible to be expired: any non-trigger, non-TIF-limit
+     * order whose `maxTs` (plus a 25-second buffer for limit orders, via `isOrderExpired`) has
+     * passed the given timestamp. Also proactively removes (not just reports) signed-message
+     * orders whose auction window (`order.slot + order.auctionDuration`) has passed `slot`, since
+     * those never landed on-chain and have no on-chain expiration to wait for.
+     *
+     * @param marketIndex the market to scan
+     * @param ts current unix timestamp (seconds)
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param slot current slot; required if the market has any signed-message orders (throws otherwise)
+     * @returns `NodeToFill`s (with empty `makerNodes`) for orders ready to expire
+     * @throws if a signed-message order is present and `slot` was not provided
+     */
     findExpiredNodesToFill(marketIndex: number, ts: number, marketType: MarketType, slot?: BN): NodeToFill[];
+    /**
+     * Finds reduce-only orders across every category/side in a market whose remaining
+     * `baseAssetAmount` (as tracked on the node, not necessarily the order's original size) has
+     * dropped below the market's minimum step size — meaning the order can never be filled again
+     * and should be canceled by a keeper rather than left to linger.
+     *
+     * @param marketIndex the market to scan
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param stepSize market's minimum order step size, BASE_PRECISION (1e9)
+     * @returns `NodeToFill`s (with empty `makerNodes`) for reduce-only orders that should be canceled
+     */
     findUnfillableReduceOnlyOrdersToCancel(marketIndex: number, marketType: MarketType, stepSize: BN): NodeToFill[];
+    /**
+     * Yields taking (still-auctioning) bid nodes for a market — market-bid orders, taking-limit
+     * bids, and signed-message bids not yet resting — merged in arrival order (earliest `slot`
+     * first, via `getBestNode`). Calls `updateRestingLimitOrders(slot)` first so a signed-message
+     * order that has since become a resting-limit order is excluded here.
+     *
+     * @param marketIndex the market to scan
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param slot current slot
+     * @param oraclePriceData oracle price data for the market (unused for the ordering itself, forwarded to `getBestNode`)
+     * @param filterFcn optional predicate; nodes it rejects are skipped and not yielded
+     * @returns a generator of taking bid nodes, or an empty generator if the market has no `MarketNodeLists`
+     */
     getTakingBids<T extends MarketType>(marketIndex: number, marketType: T, slot: number, oraclePriceData: T extends {
         spot: unknown;
     } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn): Generator<DLOBNode>;
+    /** Same as `getTakingBids`, but for the ask side. */
     getTakingAsks<T extends MarketType>(marketIndex: number, marketType: T, slot: number, oraclePriceData: T extends {
         spot: unknown;
     } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn): Generator<DLOBNode>;
+    /** Filters a `signedMsg` `NodeList`'s nodes by an arbitrary predicate — used to split signed-message orders into "still taking" vs. "now resting" subsets based on `isRestingLimitOrder`. */
     protected signedMsgGenerator(signedMsgOrderList: NodeList<'signedMsg'>, filter: (x: DLOBNode) => boolean): Generator<DLOBNode>;
+    /**
+     * K-way-merges multiple node generators (e.g. one per order category feeding one side of the
+     * book) into a single generator ordered by `compareFcn`, skipping nodes that are already
+     * fully filled (`isBaseFilled`) or rejected by `filterFcn`. This is the shared core behind
+     * `getTakingBids`/`getTakingAsks`/`getRestingLimitBids`/`getRestingLimitAsks`/`getBids`/`getAsks`
+     * — each just supplies a different `generatorList` and `compareFcn`.
+     *
+     * @param generatorList the node generators to merge; each must already be sorted per `compareFcn`
+     * @param oraclePriceData oracle price data, forwarded to `compareFcn`
+     * @param slot current slot, forwarded to `compareFcn`
+     * @param compareFcn returns true if `bestDLOBNode` should be preferred over `currentDLOBNode`
+     * @param filterFcn optional predicate; nodes it rejects are advanced past and not yielded
+     * @returns a single generator yielding the merged, filtered, non-fully-filled nodes in `compareFcn` order
+     */
     protected getBestNode<T extends MarketTypeStr>(generatorList: Array<Generator<DLOBNode>>, oraclePriceData: T extends 'spot' ? OraclePriceData : MMOraclePriceData, slot: number, compareFcn: (bestDLOBNode: DLOBNode, currentDLOBNode: DLOBNode, slot: number, oraclePriceData: T extends 'spot' ? OraclePriceData : MMOraclePriceData) => boolean, filterFcn?: DLOBFilterFcn): Generator<DLOBNode>;
+    /**
+     * Yields resting-limit ask nodes for a market — `restingLimit`, `floatingLimit`, and any
+     * `signedMsg` asks that have become resting — merged best-price-first (lowest ask price
+     * first, ties broken by `getBestNode`'s underlying comparator). Calls
+     * `updateRestingLimitOrders(slot)` first. `tickSize` is threaded into every price comparison
+     * via `DLOBNode.getPriceOrThrow`, so pass the market's `orderTickSize` to match on-chain
+     * price standardization — omitting it defaults to no rounding (tick of 1).
+     *
+     * @param marketIndex the market to scan
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market; required for spot markets (throws if missing)
+     * @param filterFcn optional predicate; nodes it rejects are skipped
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns a generator of resting-limit ask nodes, best price first
+     * @throws if `marketType` is spot and `oraclePriceData` is not provided; also throws (via `getPriceOrThrow`) if any node has no resolvable limit price
+     */
     getRestingLimitAsks<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn): Generator<DLOBNode>;
+    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn, tickSize?: BN): Generator<DLOBNode>;
+    /** Same as `getRestingLimitAsks`, but for the bid side (merged best-price-first, highest bid first). */
     getRestingLimitBids<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn): Generator<DLOBNode>;
+    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn, tickSize?: BN): Generator<DLOBNode>;
     /**
-     * This will look at both the taking and resting limit asks
-     * @param marketIndex
-     * @param fallbackAsk
-     * @param slot
-     * @param marketType
-     * @param oraclePriceData
-     * @param filterFcn
+     * Merges `getTakingAsks` and `getRestingLimitAsks` into a single best-price-first generator
+     * (ties broken by earliest arrival slot). Nodes with no resolvable price (e.g. still
+     * mid-auction) sort as price `0` — i.e. best — since `getPrice` (not `getPriceOrThrow`) is
+     * used here. Unlike `findTakingNodesToFill`/`findNodesToFill`, this does **not** merge in
+     * fallback (e.g. vAMM) liquidity; the `fallbackAsk` parameter is currently unused/reserved.
+     *
+     * @param marketIndex the market to scan
+     * @param fallbackAsk currently unused
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market; required for spot markets (throws if missing)
+     * @param filterFcn optional predicate; nodes it rejects are skipped
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns a generator of all ask nodes (taking + resting-limit), best price first
      */
     getAsks<T extends MarketType>(marketIndex: number, _fallbackAsk: BN | undefined, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn): Generator<DLOBNode>;
+    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn, tickSize?: BN): Generator<DLOBNode>;
     /**
-     * This will look at both the taking and resting limit bids
-     * @param marketIndex
-     * @param fallbackBid
-     * @param slot
-     * @param marketType
-     * @param oraclePriceData
-     * @param filterFcn
+     * Merges `getTakingBids` and `getRestingLimitBids` into a single best-price-first generator
+     * (ties broken by earliest arrival slot). Nodes with no resolvable price sort as `BN_MAX` —
+     * i.e. worst — since a priceless bid shouldn't be preferred over a priced one. Does not merge
+     * in fallback (e.g. vAMM) liquidity; the `fallbackBid` parameter is currently unused/reserved.
+     *
+     * @param marketIndex the market to scan
+     * @param fallbackBid currently unused
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market; required for spot markets (throws if missing)
+     * @param filterFcn optional predicate; nodes it rejects are skipped
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns a generator of all bid nodes (taking + resting-limit), best price first
      */
     getBids<T extends MarketType>(marketIndex: number, _fallbackBid: BN | undefined, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn): Generator<DLOBNode>;
+    } ? OraclePriceData : MMOraclePriceData, filterFcn?: DLOBFilterFcn, tickSize?: BN): Generator<DLOBNode>;
+    /**
+     * Finds pairs of resting-limit asks and bids that cross each other (`bidPrice >= askPrice`),
+     * assigns maker/taker roles via `determineMakerAndTaker` (post-only orders are always makers;
+     * otherwise whichever order's auction finished later is the taker), and simulates the fill by
+     * updating both orders' `baseAssetAmountFilled` in their `NodeList`s so subsequent iterations
+     * see the reduced remaining size. Same-user matches are skipped. Because both ask and bid
+     * generators are price-sorted, the inner loop `break`s as soon as `bidPrice < askPrice` for a
+     * given ask, since no later (worse) bid can cross either.
+     *
+     * @param marketIndex the market to scan
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6), threaded into all price lookups
+     * @returns `NodeToFill`s (taker node + one maker node each) for every crossing pair found
+     */
     findCrossingRestingLimitOrders<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData): NodeToFill[];
+    } ? OraclePriceData : MMOraclePriceData, tickSize?: BN): NodeToFill[];
+    /**
+     * Decides which of a crossing ask/bid pair is the maker and which is the taker: if both are
+     * post-only, they can't be matched (`undefined`); if exactly one is post-only, it's the
+     * maker; otherwise whichever order's auction window (`order.slot + order.auctionDuration`)
+     * ends later is treated as the taker (it "arrived crossing" the earlier order).
+     *
+     * @param askNode the crossing ask node
+     * @param bidNode the crossing bid node
+     * @returns the assigned `{ takerNode, makerNode }`, or `undefined` if both orders are post-only and neither can take
+     */
     determineMakerAndTaker(askNode: DLOBNode, bidNode: DLOBNode): {
         takerNode: DLOBNode;
         makerNode: DLOBNode;
     } | undefined;
+    /**
+     * Gets the best (lowest) resting-limit ask price for a market. Does not consider fallback
+     * (e.g. vAMM) liquidity.
+     *
+     * @param marketIndex the market to query
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns the best ask price, PRICE_PRECISION (1e6), or `undefined` if there are no resting-limit asks
+     */
     getBestAsk<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData): BN | undefined;
+    } ? OraclePriceData : MMOraclePriceData, tickSize?: BN): BN | undefined;
+    /**
+     * Gets the best (highest) resting-limit bid price for a market. Does not consider fallback
+     * (e.g. vAMM) liquidity.
+     *
+     * @param marketIndex the market to query
+     * @param slot current slot
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param oraclePriceData oracle price data for the market
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns the best bid price, PRICE_PRECISION (1e6), or `undefined` if there are no resting-limit bids
+     */
     getBestBid<T extends MarketType>(marketIndex: number, slot: number, marketType: T, oraclePriceData: T extends {
         spot: unknown;
-    } ? OraclePriceData : MMOraclePriceData): BN | undefined;
+    } ? OraclePriceData : MMOraclePriceData, tickSize?: BN): BN | undefined;
+    /**
+     * Yields untriggered trigger orders that would close a position in `direction`: for a `long`
+     * position, short-direction orders in the `trigger.below` list (stop triggers on a price
+     * drop); for a `short` position, long-direction orders in `trigger.above` (stop triggers on a
+     * price rise). Includes both `triggerMarket` and `triggerLimit` order types — see
+     * `getStopLossMarkets`/`getStopLossLimits` to filter to one.
+     *
+     * @param marketIndex the market to scan
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param direction the direction of the position being protected (not the order's own direction)
+     * @returns a generator of stop-loss trigger order nodes
+     */
     getStopLosses(marketIndex: number, marketType: MarketType, direction: PositionDirection): Generator<DLOBNode>;
+    /** Same as `getStopLosses`, filtered to `triggerMarket` orders only. */
     getStopLossMarkets(marketIndex: number, marketType: MarketType, direction: PositionDirection): Generator<DLOBNode>;
+    /** Same as `getStopLosses`, filtered to `triggerLimit` orders only. */
     getStopLossLimits(marketIndex: number, marketType: MarketType, direction: PositionDirection): Generator<DLOBNode>;
+    /**
+     * Yields untriggered trigger orders that would close a position in `direction` for profit:
+     * for a `long` position, short-direction orders in `trigger.above` (take-profit on a price
+     * rise); for a `short` position, long-direction orders in `trigger.below` (take-profit on a
+     * price drop). Includes both `triggerMarket` and `triggerLimit` order types — see
+     * `getTakeProfitMarkets`/`getTakeProfitLimits` to filter to one.
+     *
+     * @param marketIndex the market to scan
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param direction the direction of the position being protected (not the order's own direction)
+     * @returns a generator of take-profit trigger order nodes
+     */
     getTakeProfits(marketIndex: number, marketType: MarketType, direction: PositionDirection): Generator<DLOBNode>;
+    /** Same as `getTakeProfits`, filtered to `triggerMarket` orders only. */
     getTakeProfitMarkets(marketIndex: number, marketType: MarketType, direction: PositionDirection): Generator<DLOBNode>;
+    /** Same as `getTakeProfits`, filtered to `triggerLimit` orders only. */
     getTakeProfitLimits(marketIndex: number, marketType: MarketType, direction: PositionDirection): Generator<DLOBNode>;
+    /**
+     * Finds trigger orders whose condition is now satisfied by `triggerPrice`: `trigger.above`
+     * orders with `triggerPrice > order.triggerPrice`, and `trigger.below` orders with
+     * `triggerPrice < order.triggerPrice`. Both lists are sorted by trigger price with the
+     * nearest-to-triggering order at `head`, so each scan walks from `head` and `break`s at the
+     * first order that isn't (yet) triggered. Returns `[]` immediately if the exchange is paused.
+     *
+     * @param marketIndex the market to scan
+     * @param slot current slot (currently unused by the scan itself, reserved for future use)
+     * @param triggerPrice the price to check trigger conditions against, PRICE_PRECISION (1e6) — typically the current oracle or mark price
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param stateAccount global protocol state, used for the exchange-pause check
+     * @returns `NodeToTrigger`s for every order ready to be triggered on-chain
+     */
     findNodesToTrigger(marketIndex: number, slot: number, triggerPrice: BN, marketType: MarketType, stateAccount: StateAccount): NodeToTrigger[];
+    /**
+     * Debug helper: logs the market's best bid, best ask, and mid price (all resting-limit only,
+     * no fallback liquidity), along with each side's spread to the current oracle price, as a
+     * percentage.
+     *
+     * @param velocityClient client used to resolve market accounts and oracle price data
+     * @param slotSubscriber source of the current slot
+     * @param marketIndex the market to print
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @throws if the market currently has no resting-limit bid or ask (best bid/ask is `undefined`)
+     */
     printTop(velocityClient: VelocityClient, slotSubscriber: SlotSubscriber, marketIndex: number, marketType: MarketType): void;
+    /** Flattens every order across every `NodeList` (perp and spot, all categories/sides) into a single `DLOBOrders` array of `{ user, order }` pairs, in no particular cross-list order. */
     getDLOBOrders(): DLOBOrders;
+    /** Yields every `NodeList` (all ten category/side combinations, per market) across every perp market, then every spot market. Used by `getOrder`/`getDLOBOrders` to walk the entire book. */
     getNodeLists(): Generator<NodeList<DLOBNodeType>>;
     /**
-     * Get an L2 view of the order book for a given market.
+     * Get an L2 (aggregated price/size) view of the order book for a given market: resting-limit
+     * DLOB liquidity merged with any supplied fallback generators (e.g. the vAMM, via
+     * `getVammL2Generator`), then bucketed into up to `depth` levels per side via `createL2Levels`.
+     * Does not include taking (still-auctioning) orders — only resting-limit makers and fallback
+     * liquidity are represented.
      *
-     * @param marketIndex
-     * @param marketType
-     * @param slot
-     * @param oraclePriceData
-     * @param depth how many levels of the order book to return
-     * @param fallbackL2Generators L2 generators for fallback liquidity e.g. vAMM {@link getVammL2Generator}
+     * @param marketIndex the market to build a book for
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param slot current slot, used to resolve resting-limit order prices
+     * @param oraclePriceData oracle price data for the market
+     * @param depth how many price levels of the order book to return, per side
+     * @param fallbackL2Generators additional non-DLOB liquidity sources to merge in, e.g. `getVammL2Generator`'s output; defaults to `[]`
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6), threaded into all DLOB price lookups; defaults to no rounding if omitted
+     * @returns the merged `L2OrderBook`, tagged with the given `slot`
      */
-    getL2<T extends MarketType>({ marketIndex, marketType, slot, oraclePriceData, depth, fallbackL2Generators, }: {
+    getL2<T extends MarketType>({ marketIndex, marketType, slot, oraclePriceData, depth, fallbackL2Generators, tickSize, }: {
         marketIndex: number;
         marketType: T;
         slot: number;
@@ -205,35 +624,47 @@ export declare class DLOB {
         } ? OraclePriceData : MMOraclePriceData;
         depth: number;
         fallbackL2Generators?: L2OrderBookGenerator[];
+        tickSize?: BN;
     }): L2OrderBook;
     /**
-     * Get an L3 view of the order book for a given market. Does not include fallback liquidity sources
+     * Get an L3 (individual resting order) view of the order book for a given market. Only
+     * resting-limit orders are included — no taking orders and no fallback (e.g. vAMM) liquidity.
      *
-     * @param marketIndex
-     * @param marketType
-     * @param slot
-     * @param oraclePriceData
+     * @param marketIndex the market to build a book for
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param slot current slot, used to resolve resting-limit order prices
+     * @param oraclePriceData oracle price data for the market
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns the `L3OrderBook`, tagged with the given `slot`
      */
-    getL3<T extends MarketType>({ marketIndex, marketType, slot, oraclePriceData, }: {
+    getL3<T extends MarketType>({ marketIndex, marketType, slot, oraclePriceData, tickSize, }: {
         marketIndex: number;
         marketType: T;
         slot: number;
         oraclePriceData: T extends {
             spot: unknown;
         } ? OraclePriceData : MMOraclePriceData;
+        tickSize?: BN;
     }): L3OrderBook;
     private estimateFillExactBaseAmountInForSide;
     /**
+     * Estimates the quote amount that would be filled for a given base amount, walking
+     * resting-limit asks (for a `long`/buy) or bids (for a `short`/sell) from best price outward
+     * and summing `price * size` until `baseAmount` is consumed. Does not include fallback (e.g.
+     * vAMM) liquidity or taking orders, and does not mutate any order state — this is a read-only
+     * estimate, not a simulated fill.
      *
-     * @param param.marketIndex the index of the market
-     * @param param.marketType the type of the market
-     * @param param.baseAmount the base amount in to estimate
-     * @param param.orderDirection the direction of the trade
-     * @param param.slot current slot for estimating dlob node price
-     * @param param.oraclePriceData the oracle price data
-     * @returns the estimated quote amount filled: QUOTE_PRECISION
+     * @param marketIndex the market to estimate against
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param baseAmount the base amount to fill, BASE_PRECISION (1e9)
+     * @param orderDirection direction of the hypothetical taker order (`long` walks asks, `short` walks bids)
+     * @param slot current slot, used to resolve resting-limit order prices
+     * @param oraclePriceData oracle price data for the market
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns the estimated quote amount filled, QUOTE_PRECISION (1e6); if resting liquidity is thinner than `baseAmount`, the result silently reflects only the liquidity that was actually walked (no error/flag for partial fill), and is `0` if there is no resting liquidity on that side at all
+     * @throws if `orderDirection` is neither `long` nor `short`
      */
-    estimateFillWithExactBaseAmount<T extends MarketType>({ marketIndex, marketType, baseAmount, orderDirection, slot, oraclePriceData, }: {
+    estimateFillWithExactBaseAmount<T extends MarketType>({ marketIndex, marketType, baseAmount, orderDirection, slot, oraclePriceData, tickSize, }: {
         marketIndex: number;
         marketType: T;
         baseAmount: BN;
@@ -242,8 +673,25 @@ export declare class DLOB {
         oraclePriceData: T extends {
             spot: unknown;
         } ? OraclePriceData : MMOraclePriceData;
+        tickSize?: BN;
     }): BN;
-    getBestMakers<T extends MarketType>({ marketIndex, marketType, direction, slot, oraclePriceData, numMakers, }: {
+    /**
+     * Collects the pubkeys of up to `numMakers` distinct makers currently resting best-priced on
+     * one side of the book — bids for a `long` taker, asks for a `short` taker — in best-price
+     * order. Used to pick candidate maker accounts to pass as `remaining_accounts` when
+     * submitting a fill instruction. A maker with multiple resting orders at different prices
+     * only counts once toward `numMakers`.
+     *
+     * @param marketIndex the market to scan
+     * @param marketType `MarketType.PERP` or `MarketType.SPOT`
+     * @param direction direction of the taker order being matched (`long` collects bid-side makers, `short` collects ask-side makers)
+     * @param slot current slot, used to resolve resting-limit order prices
+     * @param oraclePriceData oracle price data for the market
+     * @param numMakers maximum number of distinct maker pubkeys to return
+     * @param tickSize market order tick size, PRICE_PRECISION (1e6); defaults to no rounding if omitted
+     * @returns up to `numMakers` distinct maker `PublicKey`s, best price first
+     */
+    getBestMakers<T extends MarketType>({ marketIndex, marketType, direction, slot, oraclePriceData, numMakers, tickSize, }: {
         marketIndex: number;
         marketType: T;
         direction: PositionDirection;
@@ -252,6 +700,7 @@ export declare class DLOB {
             spot: unknown;
         } ? OraclePriceData : MMOraclePriceData;
         numMakers: number;
+        tickSize?: BN;
     }): PublicKey[];
 }
 export {};