@velocity-exchange/sdk 0.3.0 → 0.4.0

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

@@ -1,65 +1,136 @@
 import { BN } from '../isomorphic/anchor';
 import { MarketTypeStr, Order } from '../types';
 import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
+/**
+ * Picks the oracle price data shape a `DLOBNode` needs to compute its limit price for a given
+ * market type: `OraclePriceData` for spot markets, `MMOraclePriceData` (which layers in the
+ * market-maker oracle) for perp markets.
+ */
 export type NodeOraclePriceData<T extends MarketTypeStr = MarketTypeStr> = T extends 'spot' ? OraclePriceData : MMOraclePriceData;
+/**
+ * A single order sitting in the DLOB, indexed by one of the sorted `NodeList`s. Wraps one
+ * on-chain `Order` plus DLOB-local bookkeeping (fill progress, sort key) used by
+ * `DLOB`'s crossing/fill-finding and L2/L3 book construction.
+ */
 export interface DLOBNode {
-    getPrice<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number): BN | undefined;
-    getPriceOrThrow<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number): BN;
+    /**
+     * Computes the node's current limit price, or `undefined` if it has none right now (e.g. a
+     * market/auction order still mid-auction with no fallback price, or an unset oracle-offset
+     * order below the tick floor). Callers that can tolerate "no price" (market orders crossing
+     * on a taker/maker basis, fallback-liquidity checks) should use this; callers that require a
+     * price to proceed should use `getPriceOrThrow` instead.
+     *
+     * @param oraclePriceData current oracle price data for the node's market (price in
+     *   PRICE_PRECISION, 1e6)
+     * @param slot current slot, used to resolve auction/oracle-offset pricing
+     * @param tickSize market's order tick size, PRICE_PRECISION (1e6); when omitted this
+     *   effectively rounds to the smallest price unit (no meaningful rounding) — pass the
+     *   market's `orderTickSize` to match on-chain price standardization
+     * @returns limit price, PRICE_PRECISION (1e6), or `undefined` if the node has no price yet
+     */
+    getPrice<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number, tickSize?: BN): BN | undefined;
+    /**
+     * Same as `getPrice`, but throws instead of returning `undefined` when the node has no limit
+     * price. Use this wherever a missing price would be a bug (e.g. iterating resting limit
+     * orders, which always have a determinable price once the auction is complete).
+     *
+     * @param oraclePriceData current oracle price data for the node's market (price in
+     *   PRICE_PRECISION, 1e6)
+     * @param slot current slot, used to resolve auction/oracle-offset pricing
+     * @param tickSize market's order tick size, PRICE_PRECISION (1e6); defaults to no rounding
+     *   if omitted
+     * @returns limit price, PRICE_PRECISION (1e6)
+     * @throws if the underlying order has no limit price at this slot
+     */
+    getPriceOrThrow<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number, tickSize?: BN): BN;
+    /** True for synthetic vAMM liquidity nodes (not backed by an on-chain `Order`); always `false` for `OrderNode` subclasses. */
     isVammNode(): boolean;
+    /** The on-chain order this node mirrors, or `undefined` for non-order (e.g. vAMM) nodes. */
     order: Order | undefined;
+    /** True once `order.baseAssetAmountFilled` equals `order.baseAssetAmount` (fully filled). */
     isBaseFilled(): boolean;
+    /** DLOB-local flag set by crossing/fill-finding once this node has been matched in the current pass, so it isn't matched twice. */
     haveFilled: boolean;
+    /** Base58 pubkey string of the `User` account that owns this order, or `undefined` if not applicable. */
     userAccount: string | undefined;
+    /** True if this order arrived as an off-chain signed message (not yet landed on-chain) rather than a resting on-chain order. */
     isSignedMsg: boolean | undefined;
+    /** Remaining base asset amount tracked by this node, BASE_PRECISION (1e9); defaults to `order.baseAssetAmount` if not overridden at insert time. */
     baseAssetAmount: BN;
 }
+/**
+ * Base class for all order-backed DLOB nodes. Holds a defensive copy of the on-chain `Order`
+ * plus a `sortValue` (the field each `NodeList` sorts on) computed by the concrete subclass's
+ * `getSortValue`. Concrete subclasses (`RestingLimitOrderNode`, `TakingLimitOrderNode`, etc.)
+ * only differ in which `Order` field they sort by and which `NodeList` bucket they belong to.
+ */
 export declare abstract class OrderNode implements DLOBNode {
     order: Order;
     userAccount: string;
+    /** The value this node is sorted by within its `NodeList`; set from `getSortValue(order)` at construction and not auto-updated on order changes. */
     sortValue: BN;
     haveFilled: boolean;
     haveTrigger: boolean;
     baseAssetAmount: BN;
     isSignedMsg: boolean;
+    /**
+     * @param order on-chain order to wrap; a shallow copy is stored so DLOB mutations don't alias the caller's object
+     * @param userAccount base58 pubkey string of the order's owner
+     * @param baseAssetAmount remaining base amount to track, BASE_PRECISION (1e9); defaults to `order.baseAssetAmount` (used for reduce-only orders where the fillable amount is smaller than the order's stated size)
+     * @param isSignedMsg whether this node represents an off-chain signed-message order rather than a resting on-chain order; defaults to `false`
+     */
     constructor(order: Order, userAccount: string, baseAssetAmount?: BN, isSignedMsg?: boolean);
+    /** Returns the field of `order` this node type sorts on within its `NodeList` (e.g. price, slot, trigger price, or oracle offset). */
     abstract getSortValue(order: Order): BN;
+    /** Builds a one-line human-readable summary of the order (id, side, size, price, trigger) for `NodeList.print`/`printTop` debugging output. */
     getLabel(): string;
-    getPrice<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number): BN | undefined;
-    getPriceOrThrow<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number): BN;
+    /** See `DLOBNode.getPrice`. Delegates to `getLimitPrice`, which resolves auction, oracle-offset, and fixed-price orders in that priority. */
+    getPrice<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number, tickSize?: BN): BN | undefined;
+    /** See `DLOBNode.getPriceOrThrow`. @throws if `getPrice` returns `undefined` for this order. */
+    getPriceOrThrow<T extends MarketTypeStr>(oraclePriceData: NodeOraclePriceData<T>, slot: number, tickSize?: BN): BN;
+    /** True once the wrapped order's `baseAssetAmountFilled` equals its `baseAssetAmount` (BASE_PRECISION, 1e9). */
     isBaseFilled(): boolean;
+    /** Always `false` — order-backed nodes are never vAMM nodes. */
     isVammNode(): boolean;
 }
+/** A limit order whose auction has not yet completed (still crossable as a taker); sorted ascending by `order.slot` (arrival order) within its `NodeList`. Promoted to a `RestingLimitOrderNode` once its auction completes or it settles as post-only, via `DLOB.updateRestingLimitOrders`. */
 export declare class TakingLimitOrderNode extends OrderNode {
     next?: TakingLimitOrderNode;
     previous?: TakingLimitOrderNode;
     getSortValue(order: Order): BN;
 }
+/** A limit order with a fixed (non-oracle-relative) price whose auction has completed, or that is post-only; sorted by `order.price` (PRICE_PRECISION, 1e6) — ascending for asks, descending for bids. This is the DLOB's standard resting maker order. */
 export declare class RestingLimitOrderNode extends OrderNode {
     next?: RestingLimitOrderNode;
     previous?: RestingLimitOrderNode;
     getSortValue(order: Order): BN;
 }
+/** A resting limit order priced relative to the oracle (`oraclePriceOffset != 0`); sorted by `order.oraclePriceOffset` (PRICE_PRECISION, 1e6, signed) rather than an absolute price, since its effective price moves with the oracle. */
 export declare class FloatingLimitOrderNode extends OrderNode {
     next?: FloatingLimitOrderNode;
     previous?: FloatingLimitOrderNode;
     getSortValue(order: Order): BN;
 }
+/** A market order (or an order otherwise treated as market/oracle-priced); sorted ascending by `order.slot` (arrival order) since market orders have no fixed price to sort by. */
 export declare class MarketOrderNode extends OrderNode {
     next?: MarketOrderNode;
     previous?: MarketOrderNode;
     getSortValue(order: Order): BN;
 }
+/** A trigger (stop-loss/take-profit) order that has not yet fired; sorted by `order.triggerPrice` (PRICE_PRECISION, 1e6) — ascending in the "above" list, descending in the "below" list — so `DLOB.findNodesToTrigger` can stop scanning as soon as the trigger price is no longer crossed. */
 export declare class TriggerOrderNode extends OrderNode {
     next?: TriggerOrderNode;
     previous?: TriggerOrderNode;
     getSortValue(order: Order): BN;
 }
+/** An order that arrived as an off-chain signed message and has not yet landed on-chain; always constructed with `isSignedMsg = true`. Sorted ascending by `order.slot`. */
 export declare class SignedMsgOrderNode extends OrderNode {
     next?: SignedMsgOrderNode;
     previous?: SignedMsgOrderNode;
     constructor(order: Order, userAccount: string, baseAssetAmount?: BN);
     getSortValue(order: Order): BN;
 }
+/** Maps each `DLOBNodeType` key to its concrete `OrderNode` subclass; used to type `NodeList<T>` and `createNode`'s return value. */
 export type DLOBNodeMap = {
     restingLimit: RestingLimitOrderNode;
     takingLimit: TakingLimitOrderNode;
@@ -68,5 +139,16 @@ export type DLOBNodeMap = {
     trigger: TriggerOrderNode;
     signedMsg: SignedMsgOrderNode;
 };
+/** The discriminant used to pick which `NodeList` (and thus sort order) an order belongs in. */
 export type DLOBNodeType = 'signedMsg' | 'restingLimit' | 'takingLimit' | 'floatingLimit' | 'market' | ('trigger' & keyof DLOBNodeMap);
+/**
+ * Constructs the concrete `OrderNode` subclass for a given `DLOBNodeType`.
+ *
+ * @param nodeType which node subclass to build; determines the node's sort key (see `DLOBNodeMap`)
+ * @param order on-chain order to wrap (copied, not mutated)
+ * @param userAccount base58 pubkey string of the order's owner
+ * @param baseAssetAmount remaining base amount to track, BASE_PRECISION (1e9); defaults to `order.baseAssetAmount`
+ * @returns a new node instance of the type matching `nodeType`
+ * @throws if `nodeType` is not one of the known `DLOBNodeType` values
+ */
 export declare function createNode<T extends DLOBNodeType>(nodeType: T, order: Order, userAccount: string, baseAssetAmount?: BN): DLOBNodeMap[T];

package/lib/browser/dlob/DLOBNode.js

@@ -6,7 +6,19 @@ const orders_1 = require("../math/orders");
 const types_1 = require("../types");
 const conversion_1 = require("../math/conversion");
 const NodeList_1 = require("./NodeList");
+/**
+ * Base class for all order-backed DLOB nodes. Holds a defensive copy of the on-chain `Order`
+ * plus a `sortValue` (the field each `NodeList` sorts on) computed by the concrete subclass's
+ * `getSortValue`. Concrete subclasses (`RestingLimitOrderNode`, `TakingLimitOrderNode`, etc.)
+ * only differ in which `Order` field they sort by and which `NodeList` bucket they belong to.
+ */
 class OrderNode {
+    /**
+     * @param order on-chain order to wrap; a shallow copy is stored so DLOB mutations don't alias the caller's object
+     * @param userAccount base58 pubkey string of the order's owner
+     * @param baseAssetAmount remaining base amount to track, BASE_PRECISION (1e9); defaults to `order.baseAssetAmount` (used for reduce-only orders where the fillable amount is smaller than the order's stated size)
+     * @param isSignedMsg whether this node represents an off-chain signed-message order rather than a resting on-chain order; defaults to `false`
+     */
     constructor(order, userAccount, baseAssetAmount, isSignedMsg = false) {
         this.haveFilled = false;
         this.haveTrigger = false;
@@ -17,6 +29,7 @@ class OrderNode {
         this.baseAssetAmount = baseAssetAmount !== null && baseAssetAmount !== void 0 ? baseAssetAmount : order.baseAssetAmount;
         this.isSignedMsg = isSignedMsg;
     }
+    /** Builds a one-line human-readable summary of the order (id, side, size, price, trigger) for `NodeList.print`/`printTop` debugging output. */
     getLabel() {
         let msg = `Order ${(0, NodeList_1.getOrderSignature)(this.order.orderId, this.userAccount)}`;
         msg += ` ${(0, types_1.isVariant)(this.order.direction, 'long') ? 'LONG' : 'SHORT'} `;
@@ -30,48 +43,57 @@ class OrderNode {
         }
         return msg;
     }
-    getPrice(oraclePriceData, slot) {
-        return (0, orders_1.getLimitPrice)(this.order, oraclePriceData, slot);
+    /** See `DLOBNode.getPrice`. Delegates to `getLimitPrice`, which resolves auction, oracle-offset, and fixed-price orders in that priority. */
+    getPrice(oraclePriceData, slot, tickSize) {
+        return (0, orders_1.getLimitPrice)(this.order, oraclePriceData, slot, undefined, tickSize);
     }
-    getPriceOrThrow(oraclePriceData, slot) {
-        const price = this.getPrice(oraclePriceData, slot);
+    /** See `DLOBNode.getPriceOrThrow`. @throws if `getPrice` returns `undefined` for this order. */
+    getPriceOrThrow(oraclePriceData, slot, tickSize) {
+        const price = this.getPrice(oraclePriceData, slot, tickSize);
         if (price === undefined) {
             throw new Error(`OrderNode.getPrice: order ${this.order.orderId} has no limit price`);
         }
         return price;
     }
+    /** True once the wrapped order's `baseAssetAmountFilled` equals its `baseAssetAmount` (BASE_PRECISION, 1e9). */
     isBaseFilled() {
         return this.order.baseAssetAmountFilled.eq(this.order.baseAssetAmount);
     }
+    /** Always `false` — order-backed nodes are never vAMM nodes. */
     isVammNode() {
         return false;
     }
 }
 exports.OrderNode = OrderNode;
+/** A limit order whose auction has not yet completed (still crossable as a taker); sorted ascending by `order.slot` (arrival order) within its `NodeList`. Promoted to a `RestingLimitOrderNode` once its auction completes or it settles as post-only, via `DLOB.updateRestingLimitOrders`. */
 class TakingLimitOrderNode extends OrderNode {
     getSortValue(order) {
         return order.slot;
     }
 }
 exports.TakingLimitOrderNode = TakingLimitOrderNode;
+/** A limit order with a fixed (non-oracle-relative) price whose auction has completed, or that is post-only; sorted by `order.price` (PRICE_PRECISION, 1e6) — ascending for asks, descending for bids. This is the DLOB's standard resting maker order. */
 class RestingLimitOrderNode extends OrderNode {
     getSortValue(order) {
         return order.price;
     }
 }
 exports.RestingLimitOrderNode = RestingLimitOrderNode;
+/** A resting limit order priced relative to the oracle (`oraclePriceOffset != 0`); sorted by `order.oraclePriceOffset` (PRICE_PRECISION, 1e6, signed) rather than an absolute price, since its effective price moves with the oracle. */
 class FloatingLimitOrderNode extends OrderNode {
     getSortValue(order) {
         return order.oraclePriceOffset;
     }
 }
 exports.FloatingLimitOrderNode = FloatingLimitOrderNode;
+/** A market order (or an order otherwise treated as market/oracle-priced); sorted ascending by `order.slot` (arrival order) since market orders have no fixed price to sort by. */
 class MarketOrderNode extends OrderNode {
     getSortValue(order) {
         return order.slot;
     }
 }
 exports.MarketOrderNode = MarketOrderNode;
+/** A trigger (stop-loss/take-profit) order that has not yet fired; sorted by `order.triggerPrice` (PRICE_PRECISION, 1e6) — ascending in the "above" list, descending in the "below" list — so `DLOB.findNodesToTrigger` can stop scanning as soon as the trigger price is no longer crossed. */
 class TriggerOrderNode extends OrderNode {
     getSortValue(order) {
         return order.triggerPrice;
@@ -79,6 +101,7 @@ class TriggerOrderNode extends OrderNode {
 }
 exports.TriggerOrderNode = TriggerOrderNode;
 // We'll use the signedMsg uuid for the order id since it's not yet on-chain
+/** An order that arrived as an off-chain signed message and has not yet landed on-chain; always constructed with `isSignedMsg = true`. Sorted ascending by `order.slot`. */
 class SignedMsgOrderNode extends OrderNode {
     constructor(order, userAccount, baseAssetAmount) {
         super(order, userAccount, baseAssetAmount, true);
@@ -88,6 +111,16 @@ class SignedMsgOrderNode extends OrderNode {
     }
 }
 exports.SignedMsgOrderNode = SignedMsgOrderNode;
+/**
+ * Constructs the concrete `OrderNode` subclass for a given `DLOBNodeType`.
+ *
+ * @param nodeType which node subclass to build; determines the node's sort key (see `DLOBNodeMap`)
+ * @param order on-chain order to wrap (copied, not mutated)
+ * @param userAccount base58 pubkey string of the order's owner
+ * @param baseAssetAmount remaining base amount to track, BASE_PRECISION (1e9); defaults to `order.baseAssetAmount`
+ * @returns a new node instance of the type matching `nodeType`
+ * @throws if `nodeType` is not one of the known `DLOBNodeType` values
+ */
 function createNode(nodeType, order, userAccount, baseAssetAmount) {
     switch (nodeType) {
         case 'floatingLimit':

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

@@ -7,28 +7,50 @@ import { VelocityClient } from '../velocityClient';
 import { MarketType } from '../types';
 import { L2OrderBook, L2OrderBookGenerator, L3OrderBook } from './orderBookLevels';
 import { BN } from '../isomorphic/anchor';
+/**
+ * Keeps a `DLOB` snapshot fresh on a timer and exposes convenience `getL2`/`getL3` accessors that
+ * resolve market name/index/type and oracle price data via `velocityClient` so callers don't have
+ * to. Until `subscribe()` resolves at least once, `getDLOB()`/`getL2`/`getL3` operate on an empty
+ * `DLOB`.
+ */
 export declare class DLOBSubscriber {
     velocityClient: VelocityClient;
     dlobSource: DLOBSource;
     slotSource: SlotSource;
+    /** Polling interval in milliseconds between `DLOB` refreshes. */
     updateFrequency: number;
+    /** Handle of the active polling timer, or `undefined` before `subscribe()`/after `unsubscribe()`. */
     intervalId?: ReturnType<typeof setTimeout>;
+    /** The current `DLOB` snapshot; replaced wholesale on each refresh rather than mutated. */
     dlob: DLOB;
+    /** Emits `'update'` after each successful refresh and `'error'` if a refresh throws. */
     eventEmitter: StrictEventEmitter<EventEmitter, DLOBSubscriberEvents>;
+    /** @throws if `config.velocityClient` is not provided. */
     constructor(config: DLOBSubscriptionConfig);
+    /**
+     * Fetches an initial `DLOB` snapshot (awaited before returning) and then starts a timer that
+     * refreshes it every `updateFrequency` ms, emitting `'update'` on success or `'error'` if the
+     * fetch throws. No-ops if already subscribed.
+     */
     subscribe(): Promise<void>;
+    /** Fetches a new `DLOB` snapshot at the current slot (from `slotSource`) via `dlobSource.getDLOB` and replaces `this.dlob`. */
     updateDLOB(): Promise<void>;
+    /** @returns the most recently fetched `DLOB` snapshot (empty until the first successful `subscribe()`/`updateDLOB()`). */
     getDLOB(): DLOB;
     /**
-     * Get the L2 order book for a given market.
+     * Get the L2 (aggregated price/size) order book for a given market, using the current
+     * `DLOB` snapshot and the current slot from `slotSource`.
      *
-     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, marketIndex and marketType must be provided.
-     * @param marketIndex
-     * @param marketType
-     * @param depth Number of orders to include in the order book. Defaults to 10.
-     * @param includeVamm Whether to include the VAMM orders in the order book. Defaults to false. If true, creates vAMM generator {@link getVammL2Generator} and adds it to fallbackL2Generators.
-     * @param fallbackL2Generators L2 generators for fallback liquidity e.g. vAMM {@link getVammL2Generator}
-     * @param latestSlot Latest slot observed via slot subscriber or similar for accuarate vamm quotes (if including the vAMM).
+     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, `marketIndex` and `marketType` must both be provided.
+     * @param marketIndex market index; ignored if `marketName` is provided
+     * @param marketType market type; ignored if `marketName` is provided
+     * @param depth number of price levels to include per side; defaults to 10
+     * @param includeVamm whether to synthesize and merge in vAMM liquidity (perp markets only) via `getVammL2Generator`; defaults to `false`. Throws if `true` and `fallbackL2Generators` is non-empty.
+     * @param numVammOrders number of vAMM levels to generate per side when `includeVamm` is true; defaults to `depth`
+     * @param fallbackL2Generators additional non-DLOB liquidity sources to merge in, e.g. `getVammL2Generator`'s output; defaults to `[]`
+     * @param latestSlot latest observed slot (e.g. from a `SlotSubscriber`), used for more accurate vAMM spread-reserve quotes when `includeVamm` is true; optional
+     * @returns the merged `L2OrderBook` (bids/asks with sizes, BASE_PRECISION 1e9, and prices, PRICE_PRECISION 1e6)
+     * @throws if `marketName` doesn't resolve to a known market, if neither `marketName` nor both `marketIndex`/`marketType` are given, or if `includeVamm` is combined with a non-empty `fallbackL2Generators`
      */
     getL2({ marketName, marketIndex, marketType, depth, includeVamm, numVammOrders, fallbackL2Generators, latestSlot, }: {
         marketName?: string;
@@ -41,16 +63,21 @@ export declare class DLOBSubscriber {
         latestSlot?: BN;
     }): L2OrderBook;
     /**
-     * Get the L3 order book for a given market.
+     * Get the L3 (individual resting order) book for a given market, using the current `DLOB`
+     * snapshot and the current slot from `slotSource`. Does not include fallback (e.g. vAMM)
+     * liquidity.
      *
-     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, marketIndex and marketType must be provided.
-     * @param marketIndex
-     * @param marketType
+     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, `marketIndex` and `marketType` must both be provided.
+     * @param marketIndex market index; ignored if `marketName` is provided
+     * @param marketType market type; ignored if `marketName` is provided
+     * @returns the `L3OrderBook` (per-order price/size/maker/orderId, prices PRICE_PRECISION 1e6, sizes BASE_PRECISION 1e9)
+     * @throws if `marketName` doesn't resolve to a known market, or if neither `marketName` nor both `marketIndex`/`marketType` are given
      */
     getL3({ marketName, marketIndex, marketType, }: {
         marketName?: string;
         marketIndex?: number;
         marketType?: MarketType;
     }): L3OrderBook;
+    /** Stops the periodic refresh timer, if running. Safe to call when not subscribed. */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/dlob/DLOBSubscriber.js

@@ -5,7 +5,14 @@ const DLOB_1 = require("./DLOB");
 const events_1 = require("events");
 const types_1 = require("../types");
 const orderBookLevels_1 = require("./orderBookLevels");
+/**
+ * Keeps a `DLOB` snapshot fresh on a timer and exposes convenience `getL2`/`getL3` accessors that
+ * resolve market name/index/type and oracle price data via `velocityClient` so callers don't have
+ * to. Until `subscribe()` resolves at least once, `getDLOB()`/`getL2`/`getL3` operate on an empty
+ * `DLOB`.
+ */
 class DLOBSubscriber {
+    /** @throws if `config.velocityClient` is not provided. */
     constructor(config) {
         const velocityClient = config.velocityClient;
         if (!velocityClient) {
@@ -18,6 +25,11 @@ class DLOBSubscriber {
         this.dlob = new DLOB_1.DLOB();
         this.eventEmitter = new events_1.EventEmitter();
     }
+    /**
+     * Fetches an initial `DLOB` snapshot (awaited before returning) and then starts a timer that
+     * refreshes it every `updateFrequency` ms, emitting `'update'` on success or `'error'` if the
+     * fetch throws. No-ops if already subscribed.
+     */
     async subscribe() {
         if (this.intervalId) {
             return;
@@ -33,22 +45,28 @@ class DLOBSubscriber {
             }
         }, this.updateFrequency);
     }
+    /** Fetches a new `DLOB` snapshot at the current slot (from `slotSource`) via `dlobSource.getDLOB` and replaces `this.dlob`. */
     async updateDLOB() {
         this.dlob = await this.dlobSource.getDLOB(this.slotSource.getSlot());
     }
+    /** @returns the most recently fetched `DLOB` snapshot (empty until the first successful `subscribe()`/`updateDLOB()`). */
     getDLOB() {
         return this.dlob;
     }
     /**
-     * Get the L2 order book for a given market.
+     * Get the L2 (aggregated price/size) order book for a given market, using the current
+     * `DLOB` snapshot and the current slot from `slotSource`.
      *
-     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, marketIndex and marketType must be provided.
-     * @param marketIndex
-     * @param marketType
-     * @param depth Number of orders to include in the order book. Defaults to 10.
-     * @param includeVamm Whether to include the VAMM orders in the order book. Defaults to false. If true, creates vAMM generator {@link getVammL2Generator} and adds it to fallbackL2Generators.
-     * @param fallbackL2Generators L2 generators for fallback liquidity e.g. vAMM {@link getVammL2Generator}
-     * @param latestSlot Latest slot observed via slot subscriber or similar for accuarate vamm quotes (if including the vAMM).
+     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, `marketIndex` and `marketType` must both be provided.
+     * @param marketIndex market index; ignored if `marketName` is provided
+     * @param marketType market type; ignored if `marketName` is provided
+     * @param depth number of price levels to include per side; defaults to 10
+     * @param includeVamm whether to synthesize and merge in vAMM liquidity (perp markets only) via `getVammL2Generator`; defaults to `false`. Throws if `true` and `fallbackL2Generators` is non-empty.
+     * @param numVammOrders number of vAMM levels to generate per side when `includeVamm` is true; defaults to `depth`
+     * @param fallbackL2Generators additional non-DLOB liquidity sources to merge in, e.g. `getVammL2Generator`'s output; defaults to `[]`
+     * @param latestSlot latest observed slot (e.g. from a `SlotSubscriber`), used for more accurate vAMM spread-reserve quotes when `includeVamm` is true; optional
+     * @returns the merged `L2OrderBook` (bids/asks with sizes, BASE_PRECISION 1e9, and prices, PRICE_PRECISION 1e6)
+     * @throws if `marketName` doesn't resolve to a known market, if neither `marketName` nor both `marketIndex`/`marketType` are given, or if `includeVamm` is combined with a non-empty `fallbackL2Generators`
      */
     getL2({ marketName, marketIndex, marketType, depth = 10, includeVamm = false, numVammOrders, fallbackL2Generators = [], latestSlot, }) {
         if (marketName) {
@@ -91,9 +109,11 @@ class DLOBSubscriber {
                 oraclePriceData,
                 slot: this.slotSource.getSlot(),
                 fallbackL2Generators: fallbackL2Generators,
+                tickSize: perpMarketAccount.orderTickSize,
             });
         }
         const oraclePriceData = this.velocityClient.getOracleDataForSpotMarket(marketIndex);
+        const spotMarketAccount = this.velocityClient.getSpotMarketAccountOrThrow(marketIndex);
         return this.dlob.getL2({
             marketIndex,
             marketType: types_1.MarketType.SPOT,
@@ -101,14 +121,19 @@ class DLOBSubscriber {
             oraclePriceData,
             slot: this.slotSource.getSlot(),
             fallbackL2Generators: fallbackL2Generators,
+            tickSize: spotMarketAccount.orderTickSize,
         });
     }
     /**
-     * Get the L3 order book for a given market.
+     * Get the L3 (individual resting order) book for a given market, using the current `DLOB`
+     * snapshot and the current slot from `slotSource`. Does not include fallback (e.g. vAMM)
+     * liquidity.
      *
-     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, marketIndex and marketType must be provided.
-     * @param marketIndex
-     * @param marketType
+     * @param marketName e.g. "SOL-PERP" or "SOL". If not provided, `marketIndex` and `marketType` must both be provided.
+     * @param marketIndex market index; ignored if `marketName` is provided
+     * @param marketType market type; ignored if `marketName` is provided
+     * @returns the `L3OrderBook` (per-order price/size/maker/orderId, prices PRICE_PRECISION 1e6, sizes BASE_PRECISION 1e9)
+     * @throws if `marketName` doesn't resolve to a known market, or if neither `marketName` nor both `marketIndex`/`marketType` are given
      */
     getL3({ marketName, marketIndex, marketType, }) {
         if (marketName) {
@@ -127,21 +152,26 @@ class DLOBSubscriber {
         const isPerp = (0, types_1.isVariant)(marketType, 'perp');
         if (isPerp) {
             const oraclePriceData = this.velocityClient.getMMOracleDataForPerpMarket(marketIndex);
+            const perpMarketAccount = this.velocityClient.getPerpMarketAccountOrThrow(marketIndex);
             return this.dlob.getL3({
                 marketIndex,
                 marketType: types_1.MarketType.PERP,
                 oraclePriceData,
                 slot: this.slotSource.getSlot(),
+                tickSize: perpMarketAccount.orderTickSize,
             });
         }
         const oraclePriceData = this.velocityClient.getOracleDataForSpotMarket(marketIndex);
+        const spotMarketAccount = this.velocityClient.getSpotMarketAccountOrThrow(marketIndex);
         return this.dlob.getL3({
             marketIndex,
             marketType: types_1.MarketType.SPOT,
             oraclePriceData,
             slot: this.slotSource.getSlot(),
+            tickSize: spotMarketAccount.orderTickSize,
         });
     }
+    /** Stops the periodic refresh timer, if running. Safe to call when not subscribed. */
     async unsubscribe() {
         if (this.intervalId) {
             clearInterval(this.intervalId);

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

@@ -1,26 +1,95 @@
 import { MarketTypeStr, Order } from '../types';
 import { DLOBNode, DLOBNodeMap } from './DLOBNode';
 import { BN } from '../isomorphic/anchor';
+/** Ordering of a `NodeList`'s sort key: `'asc'` for ascending (e.g. asks, lowest price first), `'desc'` for descending (e.g. bids, highest price first). */
 export type SortDirection = 'asc' | 'desc';
+/**
+ * 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
+ */
 export declare function getOrderSignature(orderId: number, userAccount: string): string;
+/** Implemented by anything that can produce a fresh `Generator<DLOBNode>` over its nodes, e.g. `NodeList` itself. */
 export interface DLOBNodeGenerator {
     getGenerator(): Generator<DLOBNode>;
 }
+/**
+ * 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.
+ */
 export declare class NodeList<NodeType extends keyof DLOBNodeMap> implements DLOBNodeGenerator {
     private nodeType;
     private sortDirection;
+    /** The best (first-sorted) node in the list, or `undefined` if empty. For a `'desc'`-sorted bid list this is the highest bid; for `'asc'`-sorted ask list, the lowest ask. */
     head?: DLOBNodeMap[NodeType];
+    /** Number of nodes currently in the list. */
     length: number;
+    /** Nodes keyed by `getOrderSignature(orderId, userAccount)` for O(1) has/get/update/remove. */
     nodeMap: Map<string, DLOBNodeMap[NodeType]>;
+    /**
+     * @param nodeType which `DLOBNodeMap` node subclass this list holds
+     * @param sortDirection `'asc'` or `'desc'` — the direction new nodes are ordered from `head`
+     */
     constructor(nodeType: NodeType, sortDirection: SortDirection);
+    /** Empties the list: clears `head`, resets `length` to 0, and clears `nodeMap`. */
     clear(): void;
+    /**
+     * 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: Order, marketType: MarketTypeStr, userAccount: string, baseAssetAmount?: BN): void;
+    /**
+     * 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: DLOBNodeMap[NodeType], newNode: DLOBNodeMap[NodeType]): boolean;
+    /**
+     * 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: Order, userAccount: string): void;
+    /**
+     * 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: Order, userAccount: string): void;
+    /** 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(): Generator<DLOBNode>;
+    /** Returns whether an order with this `orderId`/`userAccount` signature is present in the list. */
     has(order: Order, userAccount: string): boolean;
+    /**
+     * 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: string): DLOBNodeMap[NodeType] | undefined;
+    /** Debug helper: logs every node's `getLabel()` output to the console, in sorted order. */
     print(): void;
+    /** Debug helper: logs the sort direction and the `head` node's `getLabel()` output (or `'---'` if the list is empty). */
     printTop(): void;
 }