@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/dlob/DLOBNode.ts

@@ -10,36 +10,96 @@ import { MMOraclePriceData, OraclePriceData } from '../oracles/types';
 import { convertToNumber } from '../math/conversion';
 import { getOrderSignature } from './NodeList';
 
+/**
+ * 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 {
+	/**
+	 * 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
+		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
+		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 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 = false;
 	haveTrigger = false;
 	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,
@@ -54,8 +114,10 @@ export abstract class OrderNode implements DLOBNode {
 		this.isSignedMsg = isSignedMsg;
 	}
 
+	/** 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. */
 	public getLabel(): string {
 		let msg = `Order ${getOrderSignature(
 			this.order.orderId,
@@ -83,18 +145,28 @@ export abstract class OrderNode implements DLOBNode {
 		return msg;
 	}
 
+	/** 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
+		slot: number,
+		tickSize?: BN
 	): BN | undefined {
-		return getLimitPrice<T>(this.order, oraclePriceData, slot);
+		return getLimitPrice<T>(
+			this.order,
+			oraclePriceData,
+			slot,
+			undefined,
+			tickSize
+		);
 	}
 
+	/** See `DLOBNode.getPriceOrThrow`. @throws if `getPrice` returns `undefined` for this order. */
 	getPriceOrThrow<T extends MarketTypeStr>(
 		oraclePriceData: NodeOraclePriceData<T>,
-		slot: number
+		slot: number,
+		tickSize?: BN
 	): BN {
-		const price = this.getPrice<T>(oraclePriceData, slot);
+		const price = this.getPrice<T>(oraclePriceData, slot, tickSize);
 		if (price === undefined) {
 			throw new Error(
 				`OrderNode.getPrice: order ${this.order.orderId} has no limit price`
@@ -103,15 +175,18 @@ export abstract class OrderNode implements DLOBNode {
 		return price;
 	}
 
+	/** True once the wrapped order's `baseAssetAmountFilled` equals its `baseAssetAmount` (BASE_PRECISION, 1e9). */
 	isBaseFilled(): boolean {
 		return this.order.baseAssetAmountFilled.eq(this.order.baseAssetAmount);
 	}
 
+	/** Always `false` — order-backed nodes are never vAMM nodes. */
 	isVammNode(): boolean {
 		return false;
 	}
 }
 
+/** 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 class TakingLimitOrderNode extends OrderNode {
 	next?: TakingLimitOrderNode;
 	previous?: TakingLimitOrderNode;
@@ -121,6 +196,7 @@ export class TakingLimitOrderNode extends OrderNode {
 	}
 }
 
+/** 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 class RestingLimitOrderNode extends OrderNode {
 	next?: RestingLimitOrderNode;
 	previous?: RestingLimitOrderNode;
@@ -130,6 +206,7 @@ export class RestingLimitOrderNode extends OrderNode {
 	}
 }
 
+/** 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 class FloatingLimitOrderNode extends OrderNode {
 	next?: FloatingLimitOrderNode;
 	previous?: FloatingLimitOrderNode;
@@ -139,6 +216,7 @@ export class FloatingLimitOrderNode extends OrderNode {
 	}
 }
 
+/** 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 class MarketOrderNode extends OrderNode {
 	next?: MarketOrderNode;
 	previous?: MarketOrderNode;
@@ -148,6 +226,7 @@ export class MarketOrderNode extends OrderNode {
 	}
 }
 
+/** 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 class TriggerOrderNode extends OrderNode {
 	next?: TriggerOrderNode;
 	previous?: TriggerOrderNode;
@@ -158,6 +237,7 @@ export class TriggerOrderNode extends OrderNode {
 }
 
 // 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`. */
 export class SignedMsgOrderNode extends OrderNode {
 	next?: SignedMsgOrderNode;
 	previous?: SignedMsgOrderNode;
@@ -171,6 +251,7 @@ export class SignedMsgOrderNode extends OrderNode {
 	}
 }
 
+/** 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;
@@ -180,6 +261,7 @@ export type DLOBNodeMap = {
 	signedMsg: SignedMsgOrderNode;
 };
 
+/** The discriminant used to pick which `NodeList` (and thus sort order) an order belongs in. */
 export type DLOBNodeType =
 	| 'signedMsg'
 	| 'restingLimit'
@@ -188,6 +270,16 @@ export type DLOBNodeType =
 	| '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 function createNode<T extends DLOBNodeType>(
 	nodeType: T,
 	order: Order,

package/src/dlob/DLOBSubscriber.ts

@@ -19,14 +19,25 @@ import {
 } 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 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. */
 	public eventEmitter: StrictEventEmitter<EventEmitter, DLOBSubscriberEvents>;
+	/** @throws if `config.velocityClient` is not provided. */
 	constructor(config: DLOBSubscriptionConfig) {
 		const velocityClient = config.velocityClient;
 		if (!velocityClient) {
@@ -40,6 +51,11 @@ export class DLOBSubscriber {
 		this.eventEmitter = new 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.
+	 */
 	public async subscribe(): Promise<void> {
 		if (this.intervalId) {
 			return;
@@ -60,24 +76,30 @@ export class DLOBSubscriber {
 		}, this.updateFrequency);
 	}
 
+	/** Fetches a new `DLOB` snapshot at the current slot (from `slotSource`) via `dlobSource.getDLOB` and replaces `this.dlob`. */
 	async updateDLOB(): Promise<void> {
 		this.dlob = await this.dlobSource.getDLOB(this.slotSource.getSlot());
 	}
 
+	/** @returns the most recently fetched `DLOB` snapshot (empty until the first successful `subscribe()`/`updateDLOB()`). */
 	public getDLOB(): DLOB {
 		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`
 	 */
 	public getL2({
 		marketName,
@@ -151,11 +173,14 @@ export 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,
@@ -164,15 +189,20 @@ export 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
 	 */
 	public getL3({
 		marketName,
@@ -203,26 +233,33 @@ export class DLOBSubscriber {
 		if (isPerp) {
 			const oraclePriceData =
 				this.velocityClient.getMMOracleDataForPerpMarket(marketIndex);
+			const perpMarketAccount =
+				this.velocityClient.getPerpMarketAccountOrThrow(marketIndex);
 
 			return this.dlob.getL3({
 				marketIndex,
 				marketType: 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: MarketType.SPOT,
 			oraclePriceData,
 			slot: this.slotSource.getSlot(),
+			tickSize: spotMarketAccount.orderTickSize,
 		});
 	}
 
+	/** Stops the periodic refresh timer, if running. Safe to call when not subscribed. */
 	public async unsubscribe(): Promise<void> {
 		if (this.intervalId) {
 			clearInterval(this.intervalId);

package/src/dlob/NodeList.ts

@@ -2,8 +2,17 @@ import { isVariant, MarketTypeStr, Order } from '../types';
 import { createNode, 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 function getOrderSignature(
 	orderId: number,
 	userAccount: string
@@ -11,28 +20,53 @@ export function getOrderSignature(
 	return `${userAccount.toString()}-${orderId.toString()}`;
 }
 
+/** 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 class NodeList<NodeType extends keyof DLOBNodeMap>
 	implements DLOBNodeGenerator
 {
+	/** 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 = 0;
+	/** Nodes keyed by `getOrderSignature(orderId, userAccount)` for O(1) has/get/update/remove. */
 	nodeMap = new 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(
 		private nodeType: NodeType,
 		private sortDirection: SortDirection
 	) {}
 
+	/** Empties the list: clears `head`, resets `length` to 0, and clears `nodeMap`. */
 	public 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`
+	 */
 	public insert(
 		order: Order,
 		marketType: MarketTypeStr,
@@ -87,6 +121,15 @@ export class NodeList<NodeType extends keyof DLOBNodeMap>
 		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: DLOBNodeMap[NodeType],
 		newNode: DLOBNodeMap[NodeType]
@@ -108,6 +151,15 @@ export class NodeList<NodeType extends keyof DLOBNodeMap>
 		}
 	}
 
+	/**
+	 * 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
+	 */
 	public update(order: Order, userAccount: string): void {
 		const orderId = getOrderSignature(order.orderId, userAccount);
 		const node = this.nodeMap.get(orderId);
@@ -117,6 +169,13 @@ export class NodeList<NodeType extends keyof DLOBNodeMap>
 		}
 	}
 
+	/**
+	 * 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
+	 */
 	public remove(order: Order, userAccount: string): void {
 		const orderId = getOrderSignature(order.orderId, userAccount);
 		const node = this.nodeMap.get(orderId);
@@ -141,6 +200,7 @@ export class NodeList<NodeType extends keyof DLOBNodeMap>
 		}
 	}
 
+	/** 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> {
 		let node = this.head;
 		while (node !== undefined) {
@@ -149,14 +209,22 @@ export class NodeList<NodeType extends keyof DLOBNodeMap>
 		}
 	}
 
+	/** Returns whether an order with this `orderId`/`userAccount` signature is present in the list. */
 	public has(order: Order, userAccount: string): boolean {
 		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
+	 */
 	public get(orderSignature: string): DLOBNodeMap[NodeType] | undefined {
 		return this.nodeMap.get(orderSignature);
 	}
 
+	/** Debug helper: logs every node's `getLabel()` output to the console, in sorted order. */
 	public print(): void {
 		let currentNode = this.head;
 		while (currentNode !== undefined) {
@@ -165,6 +233,7 @@ export class NodeList<NodeType extends keyof DLOBNodeMap>
 		}
 	}
 
+	/** Debug helper: logs the sort direction and the `head` node's `getLabel()` output (or `'---'` if the list is empty). */
 	public printTop(): void {
 		if (this.head) {
 			console.log(this.sortDirection.toUpperCase(), this.head.getLabel());