@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/browser/dlob/NodeList.js

@@ -3,22 +3,53 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeList = exports.getOrderSignature = void 0;
 const types_1 = require("../types");
 const DLOBNode_1 = require("./DLOBNode");
+/**
+ * Builds the key used to identify an order uniquely across a user's orders: `"{userAccount}-{orderId}"`.
+ * Used as the map key in `NodeList.nodeMap` and to de-duplicate/merge fills in `DLOB`.
+ *
+ * @param orderId the order's `orderId` (unique per user account, not globally)
+ * @param userAccount base58 pubkey string of the order's owner
+ * @returns a string uniquely identifying the order within the DLOB
+ */
 function getOrderSignature(orderId, userAccount) {
     return `${userAccount.toString()}-${orderId.toString()}`;
 }
 exports.getOrderSignature = getOrderSignature;
+/**
+ * A sorted, doubly-linked list of one order-node type (e.g. resting-limit asks) for one
+ * market/side. Insertion walks the list from `head` to find the correct sorted position — O(n)
+ * per insert — trading insert speed for cheap best-of-book access (`head`) and cheap iteration.
+ * Backed by a `Map` (`nodeMap`) keyed by `getOrderSignature` for O(1) lookup/update/removal by
+ * order id.
+ */
 class NodeList {
+    /**
+     * @param nodeType which `DLOBNodeMap` node subclass this list holds
+     * @param sortDirection `'asc'` or `'desc'` — the direction new nodes are ordered from `head`
+     */
     constructor(nodeType, sortDirection) {
         this.nodeType = nodeType;
         this.sortDirection = sortDirection;
+        /** Number of nodes currently in the list. */
         this.length = 0;
+        /** Nodes keyed by `getOrderSignature(orderId, userAccount)` for O(1) has/get/update/remove. */
         this.nodeMap = new Map();
     }
+    /** Empties the list: clears `head`, resets `length` to 0, and clears `nodeMap`. */
     clear() {
         this.head = undefined;
         this.length = 0;
         this.nodeMap.clear();
     }
+    /**
+     * Inserts an order into its sorted position. No-ops if the order's status is not `open`, or
+     * if an order with the same signature (`userAccount` + `orderId`) is already present.
+     *
+     * @param order on-chain order to insert (ignored if not `open`)
+     * @param marketType the order's market type, passed through to `createNode`
+     * @param userAccount base58 pubkey string of the order's owner
+     * @param baseAssetAmount remaining base amount to track on the node, BASE_PRECISION (1e9); defaults to `order.baseAssetAmount`
+     */
     insert(order, marketType, userAccount, baseAssetAmount) {
         if (!(0, types_1.isVariant)(order.status, 'open')) {
             return;
@@ -53,6 +84,15 @@ class NodeList {
         currentNode.next = newNode;
         newNode.previous = currentNode;
     }
+    /**
+     * Whether `newNode` should be spliced in immediately before `currentNode` given the list's
+     * `sortDirection`. Ties on `sortValue` are broken by earlier `order.slot` (arrival order)
+     * going first, regardless of sort direction.
+     *
+     * @param currentNode the node being compared against
+     * @param newNode the node being inserted
+     * @returns true if `newNode` sorts strictly before `currentNode`
+     */
     prependNode(currentNode, newNode) {
         const currentOrder = currentNode.order;
         const newOrder = newNode.order;
@@ -68,6 +108,15 @@ class NodeList {
             return newOrderSortPrice.gt(currentOrderSortPrice);
         }
     }
+    /**
+     * Updates the existing node's order in place (e.g. after a partial fill changes
+     * `baseAssetAmountFilled`) and resets `haveFilled` to `false`. No-ops if the order isn't in
+     * this list. Note: this does **not** re-sort the node, so it must not be used to change the
+     * node's `sortValue` field (price/slot/trigger price) — remove and re-insert instead.
+     *
+     * @param order the order's new state
+     * @param userAccount base58 pubkey string of the order's owner
+     */
     update(order, userAccount) {
         const orderId = getOrderSignature(order.orderId, userAccount);
         const node = this.nodeMap.get(orderId);
@@ -76,6 +125,13 @@ class NodeList {
             node.haveFilled = false;
         }
     }
+    /**
+     * Unlinks and removes the node matching `order`/`userAccount` from the list. No-ops if the
+     * order isn't present.
+     *
+     * @param order the order to remove (matched by `orderId`)
+     * @param userAccount base58 pubkey string of the order's owner
+     */
     remove(order, userAccount) {
         const orderId = getOrderSignature(order.orderId, userAccount);
         const node = this.nodeMap.get(orderId);
@@ -95,6 +151,7 @@ class NodeList {
             this.length--;
         }
     }
+    /** Yields every node from `head` to tail, in the list's sorted order. A fresh generator is created on each call, so concurrent iteration is safe as long as the list isn't mutated mid-iteration. */
     *getGenerator() {
         let node = this.head;
         while (node !== undefined) {
@@ -102,12 +159,20 @@ class NodeList {
             node = node.next;
         }
     }
+    /** Returns whether an order with this `orderId`/`userAccount` signature is present in the list. */
     has(order, userAccount) {
         return this.nodeMap.has(getOrderSignature(order.orderId, userAccount));
     }
+    /**
+     * Looks up a node directly by its precomputed `getOrderSignature` string.
+     *
+     * @param orderSignature signature as produced by `getOrderSignature`
+     * @returns the matching node, or `undefined` if not present
+     */
     get(orderSignature) {
         return this.nodeMap.get(orderSignature);
     }
+    /** Debug helper: logs every node's `getLabel()` output to the console, in sorted order. */
     print() {
         let currentNode = this.head;
         while (currentNode !== undefined) {
@@ -115,6 +180,7 @@ class NodeList {
             currentNode = currentNode.next;
         }
     }
+    /** Debug helper: logs the sort direction and the `head` node's `getLabel()` output (or `'---'` if the list is empty). */
     printTop() {
         if (this.head) {
             console.log(this.sortDirection.toUpperCase(), this.head.getLabel());

package/lib/browser/dlob/orderBookLevels.d.ts

@@ -4,44 +4,122 @@ import { PerpMarketAccount } from '../types';
 import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
 import { PublicKey } from '@solana/web3.js';
 type liquiditySource = 'vamm' | 'dlob' | 'indicative';
+/**
+ * A single aggregated price level of an L2 order book: one price with the combined size of all
+ * orders resting at (or grouped into) that price, broken down by originating liquidity source.
+ */
 export type L2Level = {
+    /** Level price, PRICE_PRECISION (1e6). */
     price: BN;
+    /** Total size resting at this price, BASE_PRECISION (1e9). */
     size: BN;
+    /** Size contributed by each liquidity source (`'vamm'`, `'dlob'`, `'indicative'`), BASE_PRECISION (1e9). Sources with no contribution are omitted rather than zero. */
     sources: {
         [key in liquiditySource]?: BN;
     };
 };
+/** Aggregated (price, size) view of a market's book, as produced by `DLOB.getL2`. */
 export type L2OrderBook = {
+    /** Ask levels, ordered from best (lowest price) to worst. */
     asks: L2Level[];
+    /** Bid levels, ordered from best (highest price) to worst. */
     bids: L2Level[];
+    /** Slot the book was computed at, if the caller supplied one. */
     slot?: number;
 };
+/** Supplies fallback (non-DLOB) L2 liquidity — e.g. the vAMM — to be merged into `DLOB.getL2`'s output. See `getVammL2Generator`. */
 export interface L2OrderBookGenerator {
+    /** Yields ask levels best-first (ascending price). */
     getL2Asks(): Generator<L2Level>;
+    /** Yields bid levels best-first (descending price). */
     getL2Bids(): Generator<L2Level>;
 }
+/** A single unaggregated order in an L3 (order-by-order) book view, as produced by `DLOB.getL3`. */
 export type L3Level = {
+    /** Order's limit price, PRICE_PRECISION (1e6). */
     price: BN;
+    /** Order's remaining (unfilled) size, BASE_PRECISION (1e9). */
     size: BN;
+    /** Pubkey of the order's owning `User` account. */
     maker: PublicKey;
+    /** The order's `orderId` (unique per maker, not globally). */
     orderId: number;
 };
+/** Unaggregated, order-by-order view of a market's resting liquidity, as produced by `DLOB.getL3`. Does not include fallback (e.g. vAMM) liquidity. */
 export type L3OrderBook = {
+    /** Individual resting ask orders, ordered from best (lowest price) to worst. */
     asks: L3Level[];
+    /** Individual resting bid orders, ordered from best (highest price) to worst. */
     bids: L3Level[];
+    /** Slot the book was computed at, if the caller supplied one. */
     slot?: number;
 };
+/**
+ * Default top-of-book quote notional breakpoints ($500/$1000/$2000/$5000, QUOTE_PRECISION 1e6)
+ * used by `getVammL2Generator` to produce tighter, more granular vAMM levels near the top of the
+ * book for non-major markets before falling back to evenly sized levels for the remaining depth.
+ */
 export declare const DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS: BN[];
+/**
+ * Same as `DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS` but sized for deeper/more liquid "majors" markets
+ * ($5000/$10000/$20000/$50000, QUOTE_PRECISION 1e6). `DLOBSubscriber.getL2` selects this set for
+ * `marketIndex < 3`.
+ */
 export declare const MAJORS_TOP_OF_BOOK_QUOTE_AMOUNTS: BN[];
 /**
- * Get an {@link Generator<L2Level>} generator from a {@link Generator<DLOBNode>}
- * @param dlobNodes e.g. {@link DLOB#getRestingLimitAsks} or {@link DLOB#getRestingLimitBids}
- * @param oraclePriceData
- * @param slot
+ * Converts a generator of individual `DLOBNode`s (already sorted best-first, e.g. from
+ * `DLOB.getRestingLimitAsks`/`getRestingLimitBids`) into a generator of `L2Level`s — one level
+ * per node, not yet merged by price (merging/deduping happens in `createL2Levels`). Nodes with
+ * no order or with zero remaining size are skipped. A node owned by the well-known indicative
+ * quotes pubkey is tagged as `sources.indicative` instead of `sources.dlob`.
+ *
+ * @param dlobNodes sorted node generator, e.g. `DLOB.getRestingLimitAsks` or `DLOB.getRestingLimitBids`
+ * @param oraclePriceData oracle price data used to resolve each node's limit price
+ * @param slot current slot, used to resolve each node's limit price
+ * @param tickSize market order tick size, PRICE_PRECISION (1e6); passed through to `DLOBNode.getPriceOrThrow`
+ * @returns a generator of `L2Level`s, one per DLOB node with remaining size
+ * @throws if any yielded node has no resolvable limit price (via `getPriceOrThrow`)
+ */
+export declare function getL2GeneratorFromDLOBNodes(dlobNodes: Generator<DLOBNode>, oraclePriceData: OraclePriceData, slot: number, tickSize?: BN): Generator<L2Level>;
+/**
+ * Merges multiple already-sorted `L2Level` generators (e.g. DLOB liquidity plus one or more
+ * fallback sources) into a single sorted generator, using a k-way merge. Does not merge/dedupe
+ * levels that land on the same price across generators — see `createL2Levels` for that.
+ *
+ * @param l2LevelGenerators generators to merge, each already sorted in the desired final order
+ * @param compare returns true if `a` should be yielded before `b` (e.g. `a.price.lt(b.price)` for asks)
+ * @returns a single generator yielding levels in the order defined by `compare`
  */
-export declare function getL2GeneratorFromDLOBNodes(dlobNodes: Generator<DLOBNode>, oraclePriceData: OraclePriceData, slot: number): Generator<L2Level>;
 export declare function mergeL2LevelGenerators(l2LevelGenerators: Generator<L2Level>[], compare: (a: L2Level, b: L2Level) => boolean): Generator<L2Level>;
+/**
+ * Materializes a sorted `L2Level` generator into an array, merging consecutive levels that share
+ * the same price (summing size and per-source sizes) and capping the result at `depth` distinct
+ * price levels.
+ *
+ * @param generator sorted level generator, e.g. output of `mergeL2LevelGenerators`
+ * @param depth maximum number of distinct price levels to return
+ * @returns up to `depth` merged `L2Level`s
+ */
 export declare function createL2Levels(generator: Generator<L2Level>, depth: number): L2Level[];
+/**
+ * Builds an `L2OrderBookGenerator` that synthesizes vAMM (virtual AMM) liquidity levels for a
+ * perp market, for use as fallback liquidity in `DLOB.getL2`. Simulates walking the AMM's
+ * spread-adjusted reserves outward from the mid price on each side, standardizing prices to the
+ * market's `orderTickSize` and sizes to its `orderStepSize`. Returns zero liquidity on a side
+ * entirely if AMM fills are paused (`PerpOperation.AMM_FILL`) or if that side's open liquidity is
+ * less than 2x the market's `minOrderSize`.
+ *
+ * @param marketAccount perp market whose AMM reserves/config drive the simulated levels
+ * @param mmOraclePriceData market-maker oracle price data used to reprice the AMM before walking it
+ * @param numOrders total number of levels to generate per side (including any top-of-book levels)
+ * @param now unix timestamp (seconds) used for spread-reserve calculation; defaults to the current time
+ * @param topOfBookQuoteAmounts quote-notional breakpoints (QUOTE_PRECISION, 1e6) used to size the
+ *   first levels more granularly near the top of book — see `DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS` /
+ *   `MAJORS_TOP_OF_BOOK_QUOTE_AMOUNTS`; defaults to `[]` (all levels evenly sized)
+ * @param latestSlot most recent known slot, improves spread-reserve accuracy when provided; optional
+ * @returns a generator pair (`getL2Bids`/`getL2Asks`) yielding vAMM `L2Level`s, best price first,
+ *   each tagged with `sources.vamm`
+ */
 export declare function getVammL2Generator({ marketAccount, mmOraclePriceData, numOrders, now, topOfBookQuoteAmounts, latestSlot, }: {
     marketAccount: PerpMarketAccount;
     mmOraclePriceData: MMOraclePriceData;
@@ -50,6 +128,17 @@ export declare function getVammL2Generator({ marketAccount, mmOraclePriceData, n
     topOfBookQuoteAmounts?: BN[];
     latestSlot?: BN;
 }): L2OrderBookGenerator;
+/**
+ * Re-buckets an `L2OrderBook`'s levels onto a coarser price grid ("grouping"), summing size and
+ * per-source sizes of levels that land in the same bucket, and truncating each side to `depth`
+ * levels. Bids are standardized down (grouped toward the taker-friendly direction for longs),
+ * asks standardized up, matching on-chain price standardization semantics.
+ *
+ * @param l2 the ungrouped order book, e.g. from `DLOB.getL2`
+ * @param grouping price bucket size, PRICE_PRECISION (1e6) — must be a multiple of the market's tick size to produce valid on-chain prices
+ * @param depth maximum number of levels to keep per side after grouping
+ * @returns a new `L2OrderBook` with grouped bids/asks (does not mutate `l2`)
+ */
 export declare function groupL2(l2: L2OrderBook, grouping: BN, depth: number): L2OrderBook;
 /**
  * The purpose of this function is uncross the L2 orderbook by modifying the bid/ask price at the top of the book
@@ -60,14 +149,18 @@ export declare function groupL2(l2: L2OrderBook, grouping: BN, depth: number): L
  * - it will not uncross the user's liquidity
  * - it does the uncrossing by "shifting" the crossing liquidity to the nearest uncrossed levels. Thus the output liquidity maintains the same total size.
  *
- * @param bids
- * @param asks
- * @param oraclePrice
- * @param oracleTwap5Min
- * @param markTwap5Min
- * @param grouping
- * @param userBids
- * @param userAsks
+ * No-ops (returns `bids`/`asks` unchanged) if either side is empty, or if the top of book is
+ * already uncrossed (`bids[0].price < asks[0].price`).
+ *
+ * @param bids bid levels, PRICE_PRECISION (1e6) prices, best (highest) first
+ * @param asks ask levels, PRICE_PRECISION (1e6) prices, best (lowest) first
+ * @param oraclePrice current oracle price, PRICE_PRECISION (1e6)
+ * @param oracleTwap5Min 5-minute oracle price TWAP, PRICE_PRECISION (1e6)
+ * @param markTwap5Min 5-minute mark price TWAP, PRICE_PRECISION (1e6); `markTwap5Min - oracleTwap5Min` estimates the market's premium/discount to oracle, used as the reference point crossing liquidity is shifted around
+ * @param grouping minimum price gap to enforce between the shifted bid/ask, PRICE_PRECISION (1e6)
+ * @param userBids set of bid price strings (`BN.toString()`) belonging to the requesting user, which are left untouched rather than shifted
+ * @param userAsks set of ask price strings (`BN.toString()`) belonging to the requesting user, which are left untouched rather than shifted
+ * @returns new `bids`/`asks` arrays with crossing levels shifted apart by at least `grouping`; total size per side is preserved
  */
 export declare function uncrossL2(bids: L2Level[], asks: L2Level[], oraclePrice: BN, oracleTwap5Min: BN, markTwap5Min: BN, grouping: BN, userBids: Set<string>, userAsks: Set<string>): {
     bids: L2Level[];

package/lib/browser/dlob/orderBookLevels.js

@@ -7,12 +7,22 @@ const amm_1 = require("../math/amm");
 const exchangeStatus_1 = require("../math/exchangeStatus");
 const types_1 = require("../types");
 const orders_1 = require("../math/orders");
+/**
+ * Default top-of-book quote notional breakpoints ($500/$1000/$2000/$5000, QUOTE_PRECISION 1e6)
+ * used by `getVammL2Generator` to produce tighter, more granular vAMM levels near the top of the
+ * book for non-major markets before falling back to evenly sized levels for the remaining depth.
+ */
 exports.DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS = [
     new anchor_1.BN(500).mul(numericConstants_1.QUOTE_PRECISION),
     new anchor_1.BN(1000).mul(numericConstants_1.QUOTE_PRECISION),
     new anchor_1.BN(2000).mul(numericConstants_1.QUOTE_PRECISION),
     new anchor_1.BN(5000).mul(numericConstants_1.QUOTE_PRECISION),
 ];
+/**
+ * Same as `DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS` but sized for deeper/more liquid "majors" markets
+ * ($5000/$10000/$20000/$50000, QUOTE_PRECISION 1e6). `DLOBSubscriber.getL2` selects this set for
+ * `marketIndex < 3`.
+ */
 exports.MAJORS_TOP_OF_BOOK_QUOTE_AMOUNTS = [
     new anchor_1.BN(5000).mul(numericConstants_1.QUOTE_PRECISION),
     new anchor_1.BN(10000).mul(numericConstants_1.QUOTE_PRECISION),
@@ -21,12 +31,20 @@ exports.MAJORS_TOP_OF_BOOK_QUOTE_AMOUNTS = [
 ];
 const INDICATIVE_QUOTES_PUBKEY = 'inDNdu3ML4vG5LNExqcwuCQtLcCU8KfK5YM2qYV3JJz';
 /**
- * Get an {@link Generator<L2Level>} generator from a {@link Generator<DLOBNode>}
- * @param dlobNodes e.g. {@link DLOB#getRestingLimitAsks} or {@link DLOB#getRestingLimitBids}
- * @param oraclePriceData
- * @param slot
+ * Converts a generator of individual `DLOBNode`s (already sorted best-first, e.g. from
+ * `DLOB.getRestingLimitAsks`/`getRestingLimitBids`) into a generator of `L2Level`s — one level
+ * per node, not yet merged by price (merging/deduping happens in `createL2Levels`). Nodes with
+ * no order or with zero remaining size are skipped. A node owned by the well-known indicative
+ * quotes pubkey is tagged as `sources.indicative` instead of `sources.dlob`.
+ *
+ * @param dlobNodes sorted node generator, e.g. `DLOB.getRestingLimitAsks` or `DLOB.getRestingLimitBids`
+ * @param oraclePriceData oracle price data used to resolve each node's limit price
+ * @param slot current slot, used to resolve each node's limit price
+ * @param tickSize market order tick size, PRICE_PRECISION (1e6); passed through to `DLOBNode.getPriceOrThrow`
+ * @returns a generator of `L2Level`s, one per DLOB node with remaining size
+ * @throws if any yielded node has no resolvable limit price (via `getPriceOrThrow`)
  */
-function* getL2GeneratorFromDLOBNodes(dlobNodes, oraclePriceData, slot) {
+function* getL2GeneratorFromDLOBNodes(dlobNodes, oraclePriceData, slot, tickSize) {
     for (const dlobNode of dlobNodes) {
         if (!dlobNode.order) {
             continue;
@@ -37,7 +55,7 @@ function* getL2GeneratorFromDLOBNodes(dlobNodes, oraclePriceData, slot) {
         }
         yield {
             size,
-            price: dlobNode.getPriceOrThrow(oraclePriceData, slot),
+            price: dlobNode.getPriceOrThrow(oraclePriceData, slot, tickSize),
             sources: dlobNode.userAccount == INDICATIVE_QUOTES_PUBKEY
                 ? { indicative: size }
                 : {
@@ -47,6 +65,15 @@ function* getL2GeneratorFromDLOBNodes(dlobNodes, oraclePriceData, slot) {
     }
 }
 exports.getL2GeneratorFromDLOBNodes = getL2GeneratorFromDLOBNodes;
+/**
+ * Merges multiple already-sorted `L2Level` generators (e.g. DLOB liquidity plus one or more
+ * fallback sources) into a single sorted generator, using a k-way merge. Does not merge/dedupe
+ * levels that land on the same price across generators — see `createL2Levels` for that.
+ *
+ * @param l2LevelGenerators generators to merge, each already sorted in the desired final order
+ * @param compare returns true if `a` should be yielded before `b` (e.g. `a.price.lt(b.price)` for asks)
+ * @returns a single generator yielding levels in the order defined by `compare`
+ */
 function* mergeL2LevelGenerators(l2LevelGenerators, compare) {
     const generators = l2LevelGenerators.map((generator) => {
         return {
@@ -77,6 +104,15 @@ function* mergeL2LevelGenerators(l2LevelGenerators, compare) {
     } while (next !== undefined);
 }
 exports.mergeL2LevelGenerators = mergeL2LevelGenerators;
+/**
+ * Materializes a sorted `L2Level` generator into an array, merging consecutive levels that share
+ * the same price (summing size and per-source sizes) and capping the result at `depth` distinct
+ * price levels.
+ *
+ * @param generator sorted level generator, e.g. output of `mergeL2LevelGenerators`
+ * @param depth maximum number of distinct price levels to return
+ * @returns up to `depth` merged `L2Level`s
+ */
 function createL2Levels(generator, depth) {
     const levels = [];
     for (const level of generator) {
@@ -105,6 +141,25 @@ function createL2Levels(generator, depth) {
     return levels;
 }
 exports.createL2Levels = createL2Levels;
+/**
+ * Builds an `L2OrderBookGenerator` that synthesizes vAMM (virtual AMM) liquidity levels for a
+ * perp market, for use as fallback liquidity in `DLOB.getL2`. Simulates walking the AMM's
+ * spread-adjusted reserves outward from the mid price on each side, standardizing prices to the
+ * market's `orderTickSize` and sizes to its `orderStepSize`. Returns zero liquidity on a side
+ * entirely if AMM fills are paused (`PerpOperation.AMM_FILL`) or if that side's open liquidity is
+ * less than 2x the market's `minOrderSize`.
+ *
+ * @param marketAccount perp market whose AMM reserves/config drive the simulated levels
+ * @param mmOraclePriceData market-maker oracle price data used to reprice the AMM before walking it
+ * @param numOrders total number of levels to generate per side (including any top-of-book levels)
+ * @param now unix timestamp (seconds) used for spread-reserve calculation; defaults to the current time
+ * @param topOfBookQuoteAmounts quote-notional breakpoints (QUOTE_PRECISION, 1e6) used to size the
+ *   first levels more granularly near the top of book — see `DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS` /
+ *   `MAJORS_TOP_OF_BOOK_QUOTE_AMOUNTS`; defaults to `[]` (all levels evenly sized)
+ * @param latestSlot most recent known slot, improves spread-reserve accuracy when provided; optional
+ * @returns a generator pair (`getL2Bids`/`getL2Asks`) yielding vAMM `L2Level`s, best price first,
+ *   each tagged with `sources.vamm`
+ */
 function getVammL2Generator({ marketAccount, mmOraclePriceData, numOrders, now = new anchor_1.BN(Math.floor(Date.now() / 1000)), topOfBookQuoteAmounts = [], latestSlot, }) {
     const updatedAmm = (0, amm_1.calculateUpdatedAMM)(marketAccount.amm, mmOraclePriceData);
     const paused = (0, exchangeStatus_1.isOperationPaused)(marketAccount.pausedOperations, types_1.PerpOperation.AMM_FILL);
@@ -184,6 +239,17 @@ function getVammL2Generator({ marketAccount, mmOraclePriceData, numOrders, now =
     };
 }
 exports.getVammL2Generator = getVammL2Generator;
+/**
+ * Re-buckets an `L2OrderBook`'s levels onto a coarser price grid ("grouping"), summing size and
+ * per-source sizes of levels that land in the same bucket, and truncating each side to `depth`
+ * levels. Bids are standardized down (grouped toward the taker-friendly direction for longs),
+ * asks standardized up, matching on-chain price standardization semantics.
+ *
+ * @param l2 the ungrouped order book, e.g. from `DLOB.getL2`
+ * @param grouping price bucket size, PRICE_PRECISION (1e6) — must be a multiple of the market's tick size to produce valid on-chain prices
+ * @param depth maximum number of levels to keep per side after grouping
+ * @returns a new `L2OrderBook` with grouped bids/asks (does not mutate `l2`)
+ */
 function groupL2(l2, grouping, depth) {
     return {
         bids: groupL2Levels(l2.bids, grouping, types_1.PositionDirection.LONG, depth),
@@ -271,14 +337,18 @@ const mergeByPrice = (bidsOrAsks) => {
  * - it will not uncross the user's liquidity
  * - it does the uncrossing by "shifting" the crossing liquidity to the nearest uncrossed levels. Thus the output liquidity maintains the same total size.
  *
- * @param bids
- * @param asks
- * @param oraclePrice
- * @param oracleTwap5Min
- * @param markTwap5Min
- * @param grouping
- * @param userBids
- * @param userAsks
+ * No-ops (returns `bids`/`asks` unchanged) if either side is empty, or if the top of book is
+ * already uncrossed (`bids[0].price < asks[0].price`).
+ *
+ * @param bids bid levels, PRICE_PRECISION (1e6) prices, best (highest) first
+ * @param asks ask levels, PRICE_PRECISION (1e6) prices, best (lowest) first
+ * @param oraclePrice current oracle price, PRICE_PRECISION (1e6)
+ * @param oracleTwap5Min 5-minute oracle price TWAP, PRICE_PRECISION (1e6)
+ * @param markTwap5Min 5-minute mark price TWAP, PRICE_PRECISION (1e6); `markTwap5Min - oracleTwap5Min` estimates the market's premium/discount to oracle, used as the reference point crossing liquidity is shifted around
+ * @param grouping minimum price gap to enforce between the shifted bid/ask, PRICE_PRECISION (1e6)
+ * @param userBids set of bid price strings (`BN.toString()`) belonging to the requesting user, which are left untouched rather than shifted
+ * @param userAsks set of ask price strings (`BN.toString()`) belonging to the requesting user, which are left untouched rather than shifted
+ * @returns new `bids`/`asks` arrays with crossing levels shifted apart by at least `grouping`; total size per side is preserved
  */
 function uncrossL2(bids, asks, oraclePrice, oracleTwap5Min, markTwap5Min, grouping, userBids, userAsks) {
     // If there are no bids or asks, there is nothing to center

package/lib/browser/dlob/types.d.ts

@@ -1,18 +1,33 @@
 import { DLOB } from './DLOB';
 import { VelocityClient } from '../velocityClient';
+/** Configuration for constructing a `DLOBSubscriber`. */
 export type DLOBSubscriptionConfig = {
+    /** Client used to resolve market accounts/oracle data for `getL2`/`getL3`. Required — the constructor throws if omitted. */
     velocityClient?: VelocityClient;
+    /** Provides the `DLOB` snapshot to poll, e.g. built from a `UserMap`. */
     dlobSource: DLOBSource;
+    /** Provides the current slot used both to request the next `DLOB` snapshot and to price orders when serving `getL2`/`getL3`. */
     slotSource: SlotSource;
+    /** Polling interval in milliseconds between calls to `dlobSource.getDLOB`. */
     updateFrequency: number;
 };
+/** Events emitted by `DLOBSubscriber`'s `eventEmitter`. */
 export interface DLOBSubscriberEvents {
+    /** Fired after each successful periodic `DLOB` refresh, with the newly fetched `DLOB`. */
     update: (dlob: DLOB) => void;
+    /** Fired if a periodic refresh's `dlobSource.getDLOB` call throws. */
     error: (e: Error) => void;
 }
+/** Supplies a fresh `DLOB` snapshot on demand, e.g. built from a `UserMap` of on-chain user accounts. */
 export interface DLOBSource {
+    /**
+     * @param slot slot to build/tag the returned `DLOB` snapshot at
+     * @returns a promise resolving to a populated `DLOB`
+     */
     getDLOB(slot: number): Promise<DLOB>;
 }
+/** Supplies the current slot, e.g. backed by a `SlotSubscriber`. */
 export interface SlotSource {
+    /** @returns the most recently observed slot. */
     getSlot(): number;
 }

package/lib/browser/events/eventList.d.ts

@@ -5,6 +5,11 @@ declare class Node<Type extends EventType, Event extends EventMap[Type]> {
     prev?: Node<Type, Event> | undefined;
     constructor(event: Event, next?: Node<Type, Event> | undefined, prev?: Node<Type, Event> | undefined);
 }
+/**
+ * Fixed-capacity, sorted doubly-linked list of decoded events for a single
+ * `EventType`, used internally by `EventSubscriber` to retain the most
+ * recent `maxSize` events per type in the configured order.
+ */
 export declare class EventList<Type extends EventType> {
     eventType: Type;
     maxSize: number;
@@ -13,9 +18,18 @@ export declare class EventList<Type extends EventType> {
     size: number;
     head?: Node<Type, EventMap[Type]>;
     tail?: Node<Type, EventMap[Type]>;
+    /**
+     * @param eventType The `EventType` this list holds.
+     * @param maxSize Max events retained; once exceeded, the tail (least-recent per `sortFn`/`orderDirection`) is evicted.
+     * @param sortFn Comparator determining insertion order (see `getSortFn`).
+     * @param orderDirection Whether `'less than'` per `sortFn` sorts toward the head (`'asc'`) or tail (`'desc'`).
+     */
     constructor(eventType: Type, maxSize: number, sortFn: SortFn, orderDirection: EventSubscriptionOrderDirection);
+    /** Inserts `event` in sorted position (per `sortFn`/`orderDirection`), evicting the tail if this pushes the list over `maxSize`. */
     insert(event: EventMap[Type]): void;
+    /** Removes the tail node (the least-recent event per the list's order) and decrements `size`. No-ops on an empty list. */
     detach(): void;
+    /** Materializes the list into a plain array, in current sort order. Allocates a new array — prefer iterating the list directly for hot paths. */
     toArray(): EventMap[Type][];
     [Symbol.iterator](): Generator<EventMap[Type], void, unknown>;
 }

package/lib/browser/events/eventList.js

@@ -8,7 +8,18 @@ class Node {
         this.prev = prev;
     }
 }
+/**
+ * Fixed-capacity, sorted doubly-linked list of decoded events for a single
+ * `EventType`, used internally by `EventSubscriber` to retain the most
+ * recent `maxSize` events per type in the configured order.
+ */
 class EventList {
+    /**
+     * @param eventType The `EventType` this list holds.
+     * @param maxSize Max events retained; once exceeded, the tail (least-recent per `sortFn`/`orderDirection`) is evicted.
+     * @param sortFn Comparator determining insertion order (see `getSortFn`).
+     * @param orderDirection Whether `'less than'` per `sortFn` sorts toward the head (`'asc'`) or tail (`'desc'`).
+     */
     constructor(eventType, maxSize, sortFn, orderDirection) {
         this.eventType = eventType;
         this.maxSize = maxSize;
@@ -16,6 +27,7 @@ class EventList {
         this.orderDirection = orderDirection;
         this.size = 0;
     }
+    /** Inserts `event` in sorted position (per `sortFn`/`orderDirection`), evicting the tail if this pushes the list over `maxSize`. */
     insert(event) {
         this.size++;
         const newNode = new Node(event);
@@ -50,6 +62,7 @@ class EventList {
             this.detach();
         }
     }
+    /** Removes the tail node (the least-recent event per the list's order) and decrements `size`. No-ops on an empty list. */
     detach() {
         const node = this.tail;
         if (node === undefined) {
@@ -69,6 +82,7 @@ class EventList {
         }
         this.size--;
     }
+    /** Materializes the list into a plain array, in current sort order. Allocates a new array — prefer iterating the list directly for hot paths. */
     toArray() {
         return Array.from(this);
     }