@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/dlob/DLOB.js

@@ -8,9 +8,9 @@ exports.DLOB = void 0;
  * 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
  */
 const NodeList_1 = require("./NodeList");
@@ -43,11 +43,24 @@ function getUserAccountOrThrow(node) {
     }
     return node.userAccount;
 }
+/**
+ * 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.
+ */
 class DLOB {
+    /** Constructs an empty, uninitialized `DLOB` with no orders. Call `initFromUserMap` (or `insertOrder`/`insertSignedMsgOrder`) to populate it. */
     constructor() {
+        /** Order signatures (`getOrderSignature`) currently open, keyed by market type (`'perp'`/`'spot'`). */
         this.openOrders = new Map();
+        /** Every market's `MarketNodeLists`, keyed by market type then market index. */
         this.orderLists = new Map();
+        /** 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. */
         this.maxSlotForRestingLimitOrders = 0;
+        /** Set to `true` once `initFromUserMap` has successfully populated this instance; `initFromUserMap` is then a no-op. */
         this.initialized = false;
         this.init();
     }
@@ -82,6 +95,7 @@ class DLOB {
         }
         return marketNodeLists;
     }
+    /** Empties every order list and resets the DLOB to its freshly-constructed (uninitialized) state, including `maxSlotForRestingLimitOrders` and `initialized`. */
     clear() {
         for (const openOrders of this.openOrders.values()) {
             openOrders.clear();
@@ -101,9 +115,15 @@ class DLOB {
         this.init();
     }
     /**
-     * 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
      */
     async initFromUserMap(userMap, slot) {
         var _a;
@@ -127,6 +147,22 @@ class DLOB {
         this.initialized = true;
         return true;
     }
+    /**
+     * 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, userAccount, slot, baseAssetAmount, onInsert) {
         var _a;
         if (!(0, types_1.isVariant)(order.status, 'open')) {
@@ -147,6 +183,16 @@ class DLOB {
             onInsert();
         }
     }
+    /**
+     * 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, userAccount, baseAssetAmount, onInsert) {
         const marketType = (0, types_1.getVariant)(order.marketType);
         const marketIndex = order.marketIndex;
@@ -160,6 +206,7 @@ class DLOB {
             onInsert();
         }
     }
+    /** Creates and registers an empty `MarketNodeLists` (all six order categories, both sides) for `marketIndex`, overwriting any existing lists for that market. */
     addOrderList(marketType, marketIndex) {
         this.getOrderListsForMarketType(marketType).set(marketIndex, {
             restingLimit: {
@@ -188,6 +235,17 @@ class DLOB {
             },
         });
     }
+    /**
+     * 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, userAccount, slot, onDelete) {
         var _a;
         if (!(0, types_1.isVariant)(order.status, 'open')) {
@@ -199,6 +257,18 @@ class DLOB {
             onDelete();
         }
     }
+    /**
+     * 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, slot) {
         const isInactiveTriggerOrder = (0, orders_1.mustBeTriggered)(order) && !(0, orders_1.isTriggered)(order);
         const marketType = (0, types_1.getVariant)(order.marketType);
@@ -233,6 +303,15 @@ class DLOB {
         }
         return list;
     }
+    /**
+     * 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) {
         if (slot <= this.maxSlotForRestingLimitOrders) {
             return;
@@ -241,6 +320,7 @@ class DLOB {
         this.updateRestingLimitOrdersForMarketType(slot, 'perp');
         this.updateRestingLimitOrdersForMarketType(slot, 'spot');
     }
+    /** Does the `takingLimit` → `restingLimit` promotion (see `updateRestingLimitOrders`) for every market of one market type. */
     updateRestingLimitOrdersForMarketType(slot, marketTypeStr) {
         for (const [_, nodeLists] of this.getOrderListsForMarketType(marketTypeStr)) {
             const nodesToUpdate = [];
@@ -271,6 +351,15 @@ class DLOB {
             }
         }
     }
+    /**
+     * 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, userAccount) {
         const orderSignature = (0, NodeList_1.getOrderSignature)(orderId, userAccount.toString());
         for (const nodeList of this.getNodeLists()) {
@@ -281,14 +370,38 @@ class DLOB {
         }
         return 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(marketIndex, fallbackBid, fallbackAsk, slot, ts, marketType, oraclePriceData, stateAccount, marketAccount) {
         if ((0, exchangeStatus_1.fillPaused)(stateAccount, marketAccount)) {
             return [];
         }
         const isAmmPaused = (0, exchangeStatus_1.ammPaused)(stateAccount, marketAccount);
+        const tickSize = marketAccount
+            .orderTickSize;
         const { makerRebateNumerator, makerRebateDenominator } = this.getMakerRebate(marketType, stateAccount, marketAccount);
-        const takingOrderNodesToFill = this.findTakingNodesToFill(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, stateAccount, marketAccount, fallbackAsk, fallbackBid);
-        const restingLimitOrderNodesToFill = this.findRestingLimitOrderNodesToFill(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, stateAccount, marketAccount, makerRebateNumerator, makerRebateDenominator, fallbackAsk, fallbackBid);
+        const takingOrderNodesToFill = this.findTakingNodesToFill(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, stateAccount, marketAccount, fallbackAsk, fallbackBid, tickSize);
+        const restingLimitOrderNodesToFill = this.findRestingLimitOrderNodesToFill(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, stateAccount, marketAccount, makerRebateNumerator, makerRebateDenominator, fallbackAsk, fallbackBid, tickSize);
         // get expired market nodes
         const expiredNodesToFill = this.findExpiredNodesToFill(marketIndex, ts, marketType, new anchor_1.BN(slot));
         const stepSize = (0, types_1.isVariant)(marketType, 'perp')
@@ -299,6 +412,18 @@ class DLOB {
             .concat(expiredNodesToFill)
             .concat(cancelReduceOnlyNodesToFill);
     }
+    /**
+     * 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, stateAccount, marketAccount) {
         let makerRebateNumerator;
         let makerRebateDenominator;
@@ -321,6 +446,16 @@ class DLOB {
         }
         return { makerRebateNumerator, makerRebateDenominator };
     }
+    /**
+     * 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, takingOrderNodesToFill) {
         const mergedNodesToFill = new Map();
         const mergeNodesToFillHelper = (nodesToFillArray) => {
@@ -343,41 +478,85 @@ class DLOB {
         mergeNodesToFillHelper(takingOrderNodesToFill);
         return Array.from(mergedNodesToFill.values());
     }
-    findRestingLimitOrderNodesToFill(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, stateAccount, marketAccount, makerRebateNumerator, makerRebateDenominator, fallbackAsk, fallbackBid) {
+    /**
+     * 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(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, stateAccount, marketAccount, makerRebateNumerator, makerRebateDenominator, fallbackAsk, fallbackBid, tickSize) {
         const nodesToFill = new Array();
-        const crossingNodes = this.findCrossingRestingLimitOrders(marketIndex, slot, marketType, oraclePriceData);
+        const crossingNodes = this.findCrossingRestingLimitOrders(marketIndex, slot, marketType, oraclePriceData, tickSize);
         for (const crossingNode of crossingNodes) {
             nodesToFill.push(crossingNode);
         }
         if (fallbackBid && !isAmmPaused) {
-            const askGenerator = this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData);
+            const askGenerator = this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize);
             const fallbackBidWithBuffer = fallbackBid.sub(fallbackBid.muln(makerRebateNumerator).divn(makerRebateDenominator));
             const asksCrossingFallback = this.findNodesCrossingFallbackLiquidity(marketType, slot, oraclePriceData, askGenerator, (askPrice) => {
                 if (askPrice === undefined) {
                     throw new Error('Resting limit ask must have a limit price');
                 }
                 return askPrice.lte(fallbackBidWithBuffer);
-            }, stateAccount, marketAccount);
+            }, stateAccount, marketAccount, tickSize);
             for (const askCrossingFallback of asksCrossingFallback) {
                 nodesToFill.push(askCrossingFallback);
             }
         }
         if (fallbackAsk && !isAmmPaused) {
-            const bidGenerator = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData);
+            const bidGenerator = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize);
             const fallbackAskWithBuffer = fallbackAsk.add(fallbackAsk.muln(makerRebateNumerator).divn(makerRebateDenominator));
             const bidsCrossingFallback = this.findNodesCrossingFallbackLiquidity(marketType, slot, oraclePriceData, bidGenerator, (bidPrice) => {
                 if (bidPrice === undefined) {
                     throw new Error('Resting limit bid must have a limit price');
                 }
                 return bidPrice.gte(fallbackAskWithBuffer);
-            }, stateAccount, marketAccount);
+            }, stateAccount, marketAccount, tickSize);
             for (const bidCrossingFallback of bidsCrossingFallback) {
                 nodesToFill.push(bidCrossingFallback);
             }
         }
         return nodesToFill;
     }
-    findTakingNodesToFill(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, state, marketAccount, fallbackAsk, fallbackBid) {
+    /**
+     * 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(marketIndex, slot, marketType, oraclePriceData, isAmmPaused, state, marketAccount, fallbackAsk, fallbackBid, tickSize) {
         const nodesToFill = new Array();
         let takingOrderGenerator = this.getTakingAsks(marketIndex, marketType, slot, oraclePriceData);
         const takingAsksCrossingBids = this.findTakingNodesCrossingMakerNodes(marketIndex, slot, marketType, oraclePriceData, takingOrderGenerator, this.getRestingLimitBids.bind(this), (takerPrice, makerPrice) => {
@@ -390,7 +569,7 @@ class DLOB {
                 }
             }
             return takerPrice === undefined || takerPrice.lte(makerPrice);
-        });
+        }, tickSize);
         for (const takingAskCrossingBid of takingAsksCrossingBids) {
             nodesToFill.push(takingAskCrossingBid);
         }
@@ -398,7 +577,7 @@ class DLOB {
             takingOrderGenerator = this.getTakingAsks(marketIndex, marketType, slot, oraclePriceData);
             const takingAsksCrossingFallback = this.findNodesCrossingFallbackLiquidity(marketType, slot, oraclePriceData, takingOrderGenerator, (takerPrice) => {
                 return takerPrice === undefined || takerPrice.lte(fallbackBid);
-            }, state, marketAccount);
+            }, state, marketAccount, tickSize);
             for (const takingAskCrossingFallback of takingAsksCrossingFallback) {
                 nodesToFill.push(takingAskCrossingFallback);
             }
@@ -414,7 +593,7 @@ class DLOB {
                 }
             }
             return takerPrice === undefined || takerPrice.gte(makerPrice);
-        });
+        }, tickSize);
         for (const takingBidToFill of takingBidsToFill) {
             nodesToFill.push(takingBidToFill);
         }
@@ -422,25 +601,47 @@ class DLOB {
             takingOrderGenerator = this.getTakingBids(marketIndex, marketType, slot, oraclePriceData);
             const takingBidsCrossingFallback = this.findNodesCrossingFallbackLiquidity(marketType, slot, oraclePriceData, takingOrderGenerator, (takerPrice) => {
                 return takerPrice === undefined || takerPrice.gte(fallbackAsk);
-            }, state, marketAccount);
+            }, state, marketAccount, tickSize);
             for (const marketBidCrossingFallback of takingBidsCrossingFallback) {
                 nodesToFill.push(marketBidCrossingFallback);
             }
         }
         return nodesToFill;
     }
-    findTakingNodesCrossingMakerNodes(marketIndex, slot, marketType, oraclePriceData, takerNodeGenerator, makerNodeGeneratorFn, doesCross) {
+    /**
+     * 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(marketIndex, slot, marketType, oraclePriceData, takerNodeGenerator, makerNodeGeneratorFn, doesCross, tickSize) {
         const nodesToFill = new Array();
         for (const takerNode of takerNodeGenerator) {
-            const makerNodeGenerator = makerNodeGeneratorFn(marketIndex, slot, marketType, oraclePriceData);
+            const makerNodeGenerator = makerNodeGeneratorFn(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize);
             for (const makerNode of makerNodeGenerator) {
                 // Can't match orders from the same user
                 const sameUser = takerNode.userAccount === makerNode.userAccount;
                 if (sameUser) {
                     continue;
                 }
-                const makerPrice = makerNode.getPriceOrThrow(oraclePriceData, slot);
-                const takerPrice = takerNode.getPrice(oraclePriceData, slot);
+                const makerPrice = makerNode.getPriceOrThrow(oraclePriceData, slot, tickSize);
+                const takerPrice = takerNode.getPrice(oraclePriceData, slot, tickSize);
                 const ordersCross = doesCross(takerPrice, makerPrice);
                 if (!ordersCross) {
                     // market orders aren't sorted by price, they are sorted by time, so we need to traverse
@@ -481,7 +682,28 @@ class DLOB {
         }
         return nodesToFill;
     }
-    findNodesCrossingFallbackLiquidity(marketType, slot, oraclePriceData, nodeGenerator, doesCross, state, marketAccount) {
+    /**
+     * 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(marketType, slot, oraclePriceData, nodeGenerator, doesCross, state, marketAccount, tickSize) {
         var _a;
         const nodesToFill = new Array();
         let nextNode = nodeGenerator.next();
@@ -492,7 +714,7 @@ class DLOB {
                 continue;
             }
             const nodeOrder = getOrderOrThrow(node);
-            const nodePrice = (0, orders_1.getLimitPrice)(nodeOrder, oraclePriceData, slot);
+            const nodePrice = (0, orders_1.getLimitPrice)(nodeOrder, oraclePriceData, slot, undefined, tickSize);
             // order crosses if there is no limit price or it crosses fallback price
             const crosses = doesCross(nodePrice);
             // fallback is available if auction is complete or it's a spot order
@@ -508,6 +730,20 @@ class DLOB {
         }
         return nodesToFill;
     }
+    /**
+     * 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, ts, marketType, slot) {
         const nodesToFill = new Array();
         const marketTypeStr = (0, types_1.getVariant)(marketType);
@@ -573,6 +809,17 @@ class DLOB {
         }
         return nodesToFill;
     }
+    /**
+     * 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, marketType, stepSize) {
         const nodesToFill = new Array();
         const marketTypeStr = (0, types_1.getVariant)(marketType);
@@ -609,6 +856,19 @@ class DLOB {
         }
         return nodesToFill;
     }
+    /**
+     * 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(marketIndex, marketType, slot, oraclePriceData, filterFcn) {
         const marketTypeStr = (0, types_1.getVariant)(marketType);
         const orderLists = this.tryGetMarketNodeLists(marketTypeStr, marketIndex);
@@ -625,6 +885,7 @@ class DLOB {
             return getOrderOrThrow(bestNode).slot.lt(getOrderOrThrow(currentNode).slot);
         }, filterFcn);
     }
+    /** Same as `getTakingBids`, but for the ask side. */
     *getTakingAsks(marketIndex, marketType, slot, oraclePriceData, filterFcn) {
         const marketTypeStr = (0, types_1.getVariant)(marketType);
         const orderLists = this.tryGetMarketNodeLists(marketTypeStr, marketIndex);
@@ -641,6 +902,7 @@ class DLOB {
             return getOrderOrThrow(bestNode).slot.lt(getOrderOrThrow(currentNode).slot);
         }, filterFcn);
     }
+    /** 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`. */
     *signedMsgGenerator(signedMsgOrderList, filter) {
         for (const signedMsgOrder of signedMsgOrderList.getGenerator()) {
             if (filter(signedMsgOrder)) {
@@ -648,6 +910,20 @@ class DLOB {
             }
         }
     }
+    /**
+     * 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
+     */
     *getBestNode(generatorList, oraclePriceData, slot, compareFcn, filterFcn) {
         const generators = generatorList.map((generator) => {
             return {
@@ -688,7 +964,24 @@ class DLOB {
             }
         }
     }
-    *getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, filterFcn) {
+    /**
+     * 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(marketIndex, slot, marketType, oraclePriceData, filterFcn, tickSize) {
         if ((0, types_1.isVariant)(marketType, 'spot') && !oraclePriceData) {
             throw new Error('Must provide OraclePriceData to get spot asks');
         }
@@ -705,11 +998,12 @@ class DLOB {
         ];
         yield* this.getBestNode(generatorList, oraclePriceData, slot, (bestNode, currentNode, slot, oraclePriceData) => {
             return bestNode
-                .getPriceOrThrow(oraclePriceData, slot)
-                .lt(currentNode.getPriceOrThrow(oraclePriceData, slot));
+                .getPriceOrThrow(oraclePriceData, slot, tickSize)
+                .lt(currentNode.getPriceOrThrow(oraclePriceData, slot, tickSize));
         }, filterFcn);
     }
-    *getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, filterFcn) {
+    /** Same as `getRestingLimitAsks`, but for the bid side (merged best-price-first, highest bid first). */
+    *getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, filterFcn, tickSize) {
         if ((0, types_1.isVariant)(marketType, 'spot') && !oraclePriceData) {
             throw new Error('Must provide OraclePriceData to get spot bids');
         }
@@ -726,31 +1020,38 @@ class DLOB {
         ];
         yield* this.getBestNode(generatorList, oraclePriceData, slot, (bestNode, currentNode, slot, oraclePriceData) => {
             return bestNode
-                .getPriceOrThrow(oraclePriceData, slot)
-                .gt(currentNode.getPriceOrThrow(oraclePriceData, slot));
+                .getPriceOrThrow(oraclePriceData, slot, tickSize)
+                .gt(currentNode.getPriceOrThrow(oraclePriceData, slot, tickSize));
         }, filterFcn);
     }
     /**
-     * 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(marketIndex, _fallbackAsk, slot, marketType, oraclePriceData, filterFcn) {
+    *getAsks(marketIndex, _fallbackAsk, slot, marketType, oraclePriceData, filterFcn, tickSize) {
         if ((0, types_1.isVariant)(marketType, 'spot') && !oraclePriceData) {
             throw new Error('Must provide OraclePriceData to get spot asks');
         }
         const generatorList = [
             this.getTakingAsks(marketIndex, marketType, slot, oraclePriceData),
-            this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData),
+            this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize),
         ];
         yield* this.getBestNode(generatorList, oraclePriceData, slot, (bestNode, currentNode, slot, oraclePriceData) => {
             var _a, _b;
-            const bestNodePrice = (_a = bestNode.getPrice(oraclePriceData, slot)) !== null && _a !== void 0 ? _a : numericConstants_1.ZERO;
-            const currentNodePrice = (_b = currentNode.getPrice(oraclePriceData, slot)) !== null && _b !== void 0 ? _b : numericConstants_1.ZERO;
+            const bestNodePrice = (_a = bestNode.getPrice(oraclePriceData, slot, tickSize)) !== null && _a !== void 0 ? _a : numericConstants_1.ZERO;
+            const currentNodePrice = (_b = currentNode.getPrice(oraclePriceData, slot, tickSize)) !== null && _b !== void 0 ? _b : numericConstants_1.ZERO;
             if (bestNodePrice.eq(currentNodePrice)) {
                 return getOrderOrThrow(bestNode).slot.lt(getOrderOrThrow(currentNode).slot);
             }
@@ -758,39 +1059,61 @@ class DLOB {
         }, filterFcn);
     }
     /**
-     * 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(marketIndex, _fallbackBid, slot, marketType, oraclePriceData, filterFcn) {
+    *getBids(marketIndex, _fallbackBid, slot, marketType, oraclePriceData, filterFcn, tickSize) {
         if ((0, types_1.isVariant)(marketType, 'spot') && !oraclePriceData) {
             throw new Error('Must provide OraclePriceData to get spot bids');
         }
         const generatorList = [
             this.getTakingBids(marketIndex, marketType, slot, oraclePriceData),
-            this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData),
+            this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize),
         ];
         yield* this.getBestNode(generatorList, oraclePriceData, slot, (bestNode, currentNode, slot, oraclePriceData) => {
             var _a, _b;
-            const bestNodePrice = (_a = bestNode.getPrice(oraclePriceData, slot)) !== null && _a !== void 0 ? _a : numericConstants_1.BN_MAX;
-            const currentNodePrice = (_b = currentNode.getPrice(oraclePriceData, slot)) !== null && _b !== void 0 ? _b : numericConstants_1.BN_MAX;
+            const bestNodePrice = (_a = bestNode.getPrice(oraclePriceData, slot, tickSize)) !== null && _a !== void 0 ? _a : numericConstants_1.BN_MAX;
+            const currentNodePrice = (_b = currentNode.getPrice(oraclePriceData, slot, tickSize)) !== null && _b !== void 0 ? _b : numericConstants_1.BN_MAX;
             if (bestNodePrice.eq(currentNodePrice)) {
                 return getOrderOrThrow(bestNode).slot.lt(getOrderOrThrow(currentNode).slot);
             }
             return bestNodePrice.gt(currentNodePrice);
         }, filterFcn);
     }
-    findCrossingRestingLimitOrders(marketIndex, slot, marketType, oraclePriceData) {
+    /**
+     * 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(marketIndex, slot, marketType, oraclePriceData, tickSize) {
         const nodesToFill = new Array();
-        for (const askNode of this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData)) {
-            const bidGenerator = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData);
+        for (const askNode of this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize)) {
+            const bidGenerator = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize);
             for (const bidNode of bidGenerator) {
-                const bidPrice = bidNode.getPriceOrThrow(oraclePriceData, slot);
-                const askPrice = askNode.getPriceOrThrow(oraclePriceData, slot);
+                const bidPrice = bidNode.getPriceOrThrow(oraclePriceData, slot, tickSize);
+                const askPrice = askNode.getPriceOrThrow(oraclePriceData, slot, tickSize);
                 // orders don't cross
                 if (bidPrice.lt(askPrice)) {
                     break;
@@ -831,6 +1154,16 @@ class DLOB {
         }
         return nodesToFill;
     }
+    /**
+     * 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, bidNode) {
         const askOrder = getOrderOrThrow(askNode);
         const bidOrder = getOrderOrThrow(bidNode);
@@ -864,20 +1197,54 @@ class DLOB {
             };
         }
     }
-    getBestAsk(marketIndex, slot, marketType, oraclePriceData) {
-        const bestAsk = this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData).next().value;
+    /**
+     * 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(marketIndex, slot, marketType, oraclePriceData, tickSize) {
+        const bestAsk = this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize).next().value;
         if (bestAsk) {
-            return bestAsk.getPrice(oraclePriceData, slot);
+            return bestAsk.getPrice(oraclePriceData, slot, tickSize);
         }
         return undefined;
     }
-    getBestBid(marketIndex, slot, marketType, oraclePriceData) {
-        const bestBid = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData).next().value;
+    /**
+     * 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(marketIndex, slot, marketType, oraclePriceData, tickSize) {
+        const bestBid = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize).next().value;
         if (bestBid) {
-            return bestBid.getPrice(oraclePriceData, slot);
+            return bestBid.getPrice(oraclePriceData, slot, tickSize);
         }
         return 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, marketType, direction) {
         const marketTypeStr = (0, types_1.getVariant)(marketType);
         const marketNodeLists = this.getMarketNodeLists(marketTypeStr, marketIndex);
@@ -896,6 +1263,7 @@ class DLOB {
             }
         }
     }
+    /** Same as `getStopLosses`, filtered to `triggerMarket` orders only. */
     *getStopLossMarkets(marketIndex, marketType, direction) {
         for (const node of this.getStopLosses(marketIndex, marketType, direction)) {
             if ((0, types_1.isVariant)(getOrderOrThrow(node).orderType, 'triggerMarket')) {
@@ -903,6 +1271,7 @@ class DLOB {
             }
         }
     }
+    /** Same as `getStopLosses`, filtered to `triggerLimit` orders only. */
     *getStopLossLimits(marketIndex, marketType, direction) {
         for (const node of this.getStopLosses(marketIndex, marketType, direction)) {
             if ((0, types_1.isVariant)(getOrderOrThrow(node).orderType, 'triggerLimit')) {
@@ -910,6 +1279,18 @@ class DLOB {
             }
         }
     }
+    /**
+     * 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, marketType, direction) {
         const marketTypeStr = (0, types_1.getVariant)(marketType);
         const marketNodeLists = this.getMarketNodeLists(marketTypeStr, marketIndex);
@@ -928,6 +1309,7 @@ class DLOB {
             }
         }
     }
+    /** Same as `getTakeProfits`, filtered to `triggerMarket` orders only. */
     *getTakeProfitMarkets(marketIndex, marketType, direction) {
         for (const node of this.getTakeProfits(marketIndex, marketType, direction)) {
             if ((0, types_1.isVariant)(getOrderOrThrow(node).orderType, 'triggerMarket')) {
@@ -935,6 +1317,7 @@ class DLOB {
             }
         }
     }
+    /** Same as `getTakeProfits`, filtered to `triggerLimit` orders only. */
     *getTakeProfitLimits(marketIndex, marketType, direction) {
         for (const node of this.getTakeProfits(marketIndex, marketType, direction)) {
             if ((0, types_1.isVariant)(getOrderOrThrow(node).orderType, 'triggerLimit')) {
@@ -942,6 +1325,20 @@ class DLOB {
             }
         }
     }
+    /**
+     * 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, slot, triggerPrice, marketType, stateAccount) {
         var _a;
         if ((0, exchangeStatus_1.exchangePaused)(stateAccount)) {
@@ -983,6 +1380,17 @@ class DLOB {
         }
         return nodesToTrigger;
     }
+    /**
+     * 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, slotSubscriber, marketIndex, marketType) {
         if ((0, types_1.isVariant)(marketType, 'perp')) {
             const slot = slotSubscriber.getSlot();
@@ -1031,6 +1439,7 @@ class DLOB {
             console.log(`  Bid`, (0, conversion_1.convertToNumber)(bestBid, numericConstants_1.PRICE_PRECISION).toFixed(3), `(${bidSpread.toFixed(4)}%)`);
         }
     }
+    /** 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() {
         const dlobOrders = [];
         for (const nodeList of this.getNodeLists()) {
@@ -1043,6 +1452,7 @@ class DLOB {
         }
         return 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() {
         for (const [_, nodeLists] of this.getOrderListsForMarketType('perp')) {
             yield nodeLists.restingLimit.bid;
@@ -1070,17 +1480,23 @@ class DLOB {
         }
     }
     /**
-     * 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({ marketIndex, marketType, slot, oraclePriceData, depth, fallbackL2Generators = [], }) {
-        const makerAskL2LevelGenerator = (0, orderBookLevels_1.getL2GeneratorFromDLOBNodes)(this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData), oraclePriceData, slot);
+    getL2({ marketIndex, marketType, slot, oraclePriceData, depth, fallbackL2Generators = [], tickSize, }) {
+        const makerAskL2LevelGenerator = (0, orderBookLevels_1.getL2GeneratorFromDLOBNodes)(this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize), oraclePriceData, slot, tickSize);
         const fallbackAskGenerators = fallbackL2Generators.map((fallbackL2Generator) => {
             return fallbackL2Generator.getL2Asks();
         });
@@ -1088,7 +1504,7 @@ class DLOB {
             return a.price.lt(b.price);
         });
         const asks = (0, orderBookLevels_1.createL2Levels)(askL2LevelGenerator, depth);
-        const makerBidGenerator = (0, orderBookLevels_1.getL2GeneratorFromDLOBNodes)(this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData), oraclePriceData, slot);
+        const makerBidGenerator = (0, orderBookLevels_1.getL2GeneratorFromDLOBNodes)(this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize), oraclePriceData, slot, tickSize);
         const fallbackBidGenerators = fallbackL2Generators.map((fallbackOrders) => {
             return fallbackOrders.getL2Bids();
         });
@@ -1103,31 +1519,34 @@ class DLOB {
         };
     }
     /**
-     * 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({ marketIndex, marketType, slot, oraclePriceData, }) {
+    getL3({ marketIndex, marketType, slot, oraclePriceData, tickSize, }) {
         const bids = [];
         const asks = [];
-        const restingAsks = this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData);
+        const restingAsks = this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize);
         for (const ask of restingAsks) {
             const askOrder = getOrderOrThrow(ask);
             asks.push({
-                price: ask.getPriceOrThrow(oraclePriceData, slot),
+                price: ask.getPriceOrThrow(oraclePriceData, slot, tickSize),
                 size: askOrder.baseAssetAmount.sub(askOrder.baseAssetAmountFilled),
                 maker: new web3_js_1.PublicKey(getUserAccountOrThrow(ask)),
                 orderId: askOrder.orderId,
             });
         }
-        const restingBids = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData);
+        const restingBids = this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize);
         for (const bid of restingBids) {
             const bidOrder = getOrderOrThrow(bid);
             bids.push({
-                price: bid.getPriceOrThrow(oraclePriceData, slot),
+                price: bid.getPriceOrThrow(oraclePriceData, slot, tickSize),
                 size: bidOrder.baseAssetAmount.sub(bidOrder.baseAssetAmountFilled),
                 maker: new web3_js_1.PublicKey(getUserAccountOrThrow(bid)),
                 orderId: bidOrder.orderId,
@@ -1139,11 +1558,11 @@ class DLOB {
             slot,
         };
     }
-    estimateFillExactBaseAmountInForSide(baseAmountIn, oraclePriceData, slot, dlobSide) {
+    estimateFillExactBaseAmountInForSide(baseAmountIn, oraclePriceData, slot, dlobSide, tickSize) {
         let runningSumQuote = numericConstants_1.ZERO;
         let runningSumBase = numericConstants_1.ZERO;
         for (const side of dlobSide) {
-            const price = side.getPriceOrThrow(oraclePriceData, slot); //side.order.quoteAssetAmount.div(side.order.baseAssetAmount);
+            const price = side.getPriceOrThrow(oraclePriceData, slot, tickSize); //side.order.quoteAssetAmount.div(side.order.baseAssetAmount);
             const sideOrder = getOrderOrThrow(side);
             const baseAmountRemaining = sideOrder.baseAssetAmount.sub(sideOrder.baseAssetAmountFilled);
             if (runningSumBase.add(baseAmountRemaining).gt(baseAmountIn)) {
@@ -1162,29 +1581,52 @@ class DLOB {
             .div(numericConstants_1.BASE_PRECISION.mul(numericConstants_1.PRICE_PRECISION));
     }
     /**
+     * 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({ marketIndex, marketType, baseAmount, orderDirection, slot, oraclePriceData, }) {
+    estimateFillWithExactBaseAmount({ marketIndex, marketType, baseAmount, orderDirection, slot, oraclePriceData, tickSize, }) {
         if ((0, types_1.isVariant)(orderDirection, 'long')) {
-            return this.estimateFillExactBaseAmountInForSide(baseAmount, oraclePriceData, slot, this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData));
+            return this.estimateFillExactBaseAmountInForSide(baseAmount, oraclePriceData, slot, this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize), tickSize);
         }
         else if ((0, types_1.isVariant)(orderDirection, 'short')) {
-            return this.estimateFillExactBaseAmountInForSide(baseAmount, oraclePriceData, slot, this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData));
+            return this.estimateFillExactBaseAmountInForSide(baseAmount, oraclePriceData, slot, this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize), tickSize);
         }
         throw new Error(`Invalid order direction ${(0, types_1.getVariant)(orderDirection)}: must be long or short`);
     }
-    getBestMakers({ 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({ marketIndex, marketType, direction, slot, oraclePriceData, numMakers, tickSize, }) {
         const makers = new Map();
         const generator = (0, types_1.isVariant)(direction, 'long')
-            ? this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData)
-            : this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData);
+            ? this.getRestingLimitBids(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize)
+            : this.getRestingLimitAsks(marketIndex, slot, marketType, oraclePriceData, undefined, tickSize);
         for (const node of generator) {
             const userAccount = getUserAccountOrThrow(node);
             if (!makers.has(userAccount)) {