@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/dlob/orderBookLevels.ts

@@ -28,36 +28,64 @@ import { standardizeBaseAssetAmount, standardizePrice } from '../math/orders';
 
 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 const DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS = [
 	new BN(500).mul(QUOTE_PRECISION),
 	new BN(1000).mul(QUOTE_PRECISION),
@@ -65,6 +93,11 @@ export const DEFAULT_TOP_OF_BOOK_QUOTE_AMOUNTS = [
 	new BN(5000).mul(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`.
+ */
 export const MAJORS_TOP_OF_BOOK_QUOTE_AMOUNTS = [
 	new BN(5000).mul(QUOTE_PRECISION),
 	new BN(10000).mul(QUOTE_PRECISION),
@@ -75,15 +108,24 @@ export const 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`)
  */
 export function* getL2GeneratorFromDLOBNodes(
 	dlobNodes: Generator<DLOBNode>,
 	oraclePriceData: OraclePriceData,
-	slot: number
+	slot: number,
+	tickSize?: BN
 ): Generator<L2Level> {
 	for (const dlobNode of dlobNodes) {
 		if (!dlobNode.order) {
@@ -99,7 +141,7 @@ export function* getL2GeneratorFromDLOBNodes(
 
 		yield {
 			size,
-			price: dlobNode.getPriceOrThrow(oraclePriceData, slot),
+			price: dlobNode.getPriceOrThrow(oraclePriceData, slot, tickSize),
 			sources:
 				dlobNode.userAccount == INDICATIVE_QUOTES_PUBKEY
 					? { indicative: size }
@@ -110,6 +152,15 @@ export function* 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`
+ */
 export function* mergeL2LevelGenerators(
 	l2LevelGenerators: Generator<L2Level>[],
 	compare: (a: L2Level, b: L2Level) => boolean
@@ -151,6 +202,15 @@ export function* mergeL2LevelGenerators(
 	} while (next !== undefined);
 }
 
+/**
+ * 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 function createL2Levels(
 	generator: Generator<L2Level>,
 	depth: number
@@ -182,6 +242,25 @@ export function createL2Levels(
 	return levels;
 }
 
+/**
+ * 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 function getVammL2Generator({
 	marketAccount,
 	mmOraclePriceData,
@@ -320,6 +399,17 @@ export function 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`)
+ */
 export function groupL2(
 	l2: L2OrderBook,
 	grouping: BN,
@@ -428,14 +518,18 @@ const mergeByPrice = (bidsOrAsks: L2Level[]) => {
  * - 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 function uncrossL2(
 	bids: L2Level[],

package/src/dlob/types.ts

@@ -1,22 +1,37 @@
 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/src/events/eventList.ts

@@ -13,11 +13,22 @@ class Node<Type extends EventType, Event extends EventMap[Type]> {
 	) {}
 }
 
+/**
+ * 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 class EventList<Type extends EventType> {
 	size = 0;
 	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'`).
+	 */
 	public constructor(
 		public eventType: Type,
 		public maxSize: number,
@@ -25,6 +36,7 @@ export class EventList<Type extends EventType> {
 		private orderDirection: EventSubscriptionOrderDirection
 	) {}
 
+	/** Inserts `event` in sorted position (per `sortFn`/`orderDirection`), evicting the tail if this pushes the list over `maxSize`. */
 	public insert(event: EventMap[Type]): void {
 		this.size++;
 		const newNode = new Node(event);
@@ -66,6 +78,7 @@ export class EventList<Type extends EventType> {
 		}
 	}
 
+	/** Removes the tail node (the least-recent event per the list's order) and decrements `size`. No-ops on an empty list. */
 	detach(): void {
 		const node = this.tail;
 		if (node === undefined) {
@@ -86,6 +99,7 @@ export class EventList<Type extends EventType> {
 		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(): EventMap[Type][] {
 		return Array.from(this);
 	}

package/src/events/eventSubscriber.ts

@@ -1,11 +1,6 @@
-/**
- * EventSubscriber — streams and parses Velocity program events from transaction logs.
- *
- * Decodes all program events (OrderActionRecord, DepositRecord, LiquidationRecord,
- * FundingPaymentRecord, etc.) from `state/events.rs` into typed TypeScript objects.
- * Supports WebSocket and polling log providers; events are surfaced via an EventEmitter.
- * See `events/types.ts` for the full event type union and `events/parse.ts` for log parsing.
- */
+// EventSubscriber — see the class doc below for behavior. This module also
+// wires together the LogProvider implementations (websocket/polling/events-server);
+// see `events/types.ts` for the full event type union and `events/parse.ts` for log parsing.
 import { Connection, PublicKey, TransactionSignature } from '@solana/web3.js';
 import { Program } from '../isomorphic/anchor';
 import {
@@ -34,9 +29,34 @@ import { getSortFn } from './sort';
 import { parseLogs } from './parse';
 import { EventsServerLogProvider } from './eventsServerLogProvider';
 
+/**
+ * EventSubscriber — streams and decodes Velocity program events from
+ * transaction logs (all records emitted via `emit!` from `state/events.rs`:
+ * `DepositRecord`, `OrderActionRecord`, `LiquidationRecord`,
+ * `FundingPaymentRecord`, etc. — see `EventMap` for the full set), via a
+ * pluggable `LogProvider` (websocket, polling, or the Velocity events server),
+ * and surfaces them both through per-type `EventList`s and a `'newEvent'`
+ * `eventEmitter`.
+ *
+ * Ordering and dedup: each decoded event is tagged with `slot` and a
+ * `txSigIndex` (its position among decoded events within the same
+ * transaction); the per-event-type `EventList`s use these to sort either by
+ * blockchain order (slot, then `txSigIndex`) or by client arrival order, per
+ * `EventSubscriptionOptions.orderBy`. Whole transactions are deduped by
+ * signature via an internal LRU (`TxEventCache`, sized by `options.maxTx`):
+ * a transaction already in the cache is skipped entirely on a subsequent
+ * delivery from the *same* log provider, which protects against a
+ * websocket/polling provider redelivering the same tx. Events pushed by the
+ * events-server provider bypass this cache (it dedups upstream and supplies
+ * an authoritative `txSigIndex`). Event names are also normalized from the
+ * `@coral-xyz/anchor` 0.32+ camelCase IDL form back to the PascalCase used by
+ * `EventType`/`EventMap` before being matched against the subscribed types.
+ */
 export class EventSubscriber {
 	private address: PublicKey;
 	private eventListMap: Map<EventType, EventList<EventType>>;
+	/** Case-insensitive lookup from decoded (camelCase) IDL event names to subscribed `EventType` keys. */
+	private eventTypeByLowercaseName = new Map<string, EventType>();
 	private txEventCache: TxEventCache;
 	private awaitTxPromises = new Map<string, Promise<void>>();
 	private awaitTxResolver = new Map<string, () => void>();
@@ -56,6 +76,11 @@ export class EventSubscriber {
 		return this._logProvider;
 	}
 
+	/**
+	 * @param connection RPC connection used by the polling/websocket log providers and by `fetchPreviousTx`.
+	 * @param program Anchor `Program` whose IDL coder decodes event logs (see `parse.ts`).
+	 * @param options Subscription options; merged over `DefaultEventSubscriptionOptions` so any field left unset uses the default.
+	 */
 	public constructor(
 		private connection: Connection,
 		private program: Program,
@@ -85,6 +110,7 @@ export class EventSubscriber {
 		return this.options.eventTypes;
 	}
 
+	/** The `LogProviderType` currently in use. May differ from the configured type after a fallback failover (see `updateFallbackProviderType`). */
 	get currentProviderType() {
 		return this._currentProviderType;
 	}
@@ -170,6 +196,7 @@ export class EventSubscriber {
 					orderDir
 				)
 			);
+			this.eventTypeByLowercaseName.set(eventType.toLowerCase(), eventType);
 		}
 	}
 
@@ -200,6 +227,19 @@ export class EventSubscriber {
 		this._currentProviderType = nextProviderType;
 	}
 
+	/**
+	 * Starts streaming events via the configured `LogProvider`. Idempotent —
+	 * returns `true` immediately if already subscribed. (Re)initializes the
+	 * per-event-type `EventList`s, so any events retained from a prior
+	 * subscribe/unsubscribe cycle are discarded. For streaming providers
+	 * (websocket, events-server), also wires up automatic failover: if the
+	 * provider emits more than `maxReconnectAttempts` (default `Infinity`,
+	 * i.e. never) reconnect attempts, the subscriber tears down and
+	 * reinitializes with the next provider in the fallback chain
+	 * (events-server → websocket → polling; polling has no further fallback).
+	 * Does not itself backfill history — call `fetchPreviousTx` for that.
+	 * @returns `true` once subscribed, or `false` if an error occurred while starting the subscription (logged to console, not thrown).
+	 */
 	public async subscribe(): Promise<boolean> {
 		try {
 			if (this.logProvider.isSubscribed()) {
@@ -319,6 +359,16 @@ export class EventSubscriber {
 		this.txEventCache.add(txSig, wrappedEvents);
 	}
 
+	/**
+	 * Backfills historical events by walking transactions for `address` via
+	 * `getSignaturesForAddress`/`getTransaction`, newest-first, until either
+	 * `options.untilTx` is reached or `options.maxTx` transactions have been
+	 * fetched. Each fetched transaction is decoded and inserted into the
+	 * event lists exactly like a live update, so `newEvent` fires for
+	 * backfilled events too. No-ops if neither `untilTx` is set nor
+	 * `fetchMax` is true — the subscriber does not backfill by default.
+	 * @param fetchMax If true, backfill up to `maxTx` transactions even without an `untilTx` cutoff.
+	 */
 	public async fetchPreviousTx(fetchMax?: boolean): Promise<void> {
 		if (!this.options.untilTx && !fetchMax) {
 			return;
@@ -354,6 +404,13 @@ export class EventSubscriber {
 		}
 	}
 
+	/**
+	 * Stops the log provider and clears all in-memory state: the per-event-type
+	 * `EventList`s, the `TxEventCache`, and any pending `awaitTx` promises
+	 * (which are left unresolved/unrejected — callers awaiting a tx signature
+	 * across an unsubscribe will hang).
+	 * @returns Whatever the underlying `LogProvider.unsubscribe` returns.
+	 */
 	public async unsubscribe(): Promise<boolean> {
 		this.eventListMap.clear();
 		this.txEventCache.clear();
@@ -374,16 +431,16 @@ export class EventSubscriber {
 		const events = parseLogs(this.program, logs);
 		let runningEventIndex = 0;
 		for (const event of events) {
-			// @coral-xyz/anchor 0.32+ converts IDL names to camelCase; normalize
-			// back to PascalCase so EventType keys remain consistent.
-			const pascalName =
-				event.name.charAt(0).toUpperCase() + event.name.slice(1);
-			// @ts-ignore
-			const expectRecordType = this.eventListMap.has(pascalName);
-			if (expectRecordType) {
+			// @coral-xyz/anchor 0.32+ converts IDL names to camelCase; match
+			// case-insensitively so names with leading acronyms (LPSwapRecord →
+			// lpSwapRecord) still resolve to their PascalCase EventType keys.
+			const eventType = this.eventTypeByLowercaseName.get(
+				event.name.toLowerCase()
+			);
+			if (eventType) {
 				event.data.txSig = txSig;
 				event.data.slot = slot;
-				event.data.eventType = pascalName;
+				event.data.eventType = eventType;
 				event.data.txSigIndex =
 					txSigIndex !== undefined ? txSigIndex : runningEventIndex;
 				records.push(event.data);
@@ -393,6 +450,16 @@ export class EventSubscriber {
 		return records;
 	}
 
+	/**
+	 * Resolves once the subscriber has observed and decoded events for `txSig`
+	 * (immediately if it's already in the `TxEventCache`). Useful for waiting
+	 * on the events of a transaction the caller just sent, before reading them
+	 * via `getEventsByTx`. Never rejects; a transaction that never arrives
+	 * (e.g. it failed, or the subscriber isn't subscribed) leaves the returned
+	 * promise pending forever.
+	 * @param txSig Signature to wait for.
+	 * @returns A promise that resolves (with no value) once that transaction's events have been processed.
+	 */
 	public awaitTx(txSig: TransactionSignature): Promise<void> {
 		const existingPromise = this.awaitTxPromises.get(txSig);
 		if (existingPromise !== undefined) {
@@ -410,17 +477,26 @@ export class EventSubscriber {
 		return promise;
 	}
 
+	/**
+	 * Returns the live `EventList` for `eventType` — the ordered, size-bounded
+	 * (`maxEventsPerType`) linked list the subscriber inserts new events into.
+	 * Prefer this over `getEventsArray` to iterate without copying.
+	 * @param eventType Event type to look up; must be one of `options.eventTypes` (subscribed types).
+	 * @returns The `EventList` for that type, or `undefined` if `eventType` was never subscribed (list not yet populated by `subscribe()`).
+	 */
 	public getEventList<Type extends keyof EventMap>(
 		eventType: Type
-	): EventList<Type> {
-		return this.eventListMap.get(eventType) as EventList<Type>;
+	): EventList<Type> | undefined {
+		return this.eventListMap.get(eventType) as EventList<Type> | undefined;
 	}
 
 	/**
 	 * This requires the EventList be cast to an array, which requires reallocation of memory.
 	 * Would bias to using getEventList over getEvents
 	 *
-	 * @param eventType
+	 * @param eventType Event type to snapshot.
+	 * @returns All currently retained events of that type, in the `EventList`'s sort order (see `EventSubscriptionOptions.orderBy`/`orderDir`).
+	 * @throws If `eventType` has no `EventList` (i.e. it isn't in `options.eventTypes`).
 	 */
 	public getEventsArray<Type extends EventType>(
 		eventType: Type
@@ -434,6 +510,11 @@ export class EventSubscriber {
 		return eventList.toArray() as EventMap[Type][];
 	}
 
+	/**
+	 * Looks up the decoded events previously observed for a transaction.
+	 * @param txSig Transaction signature to look up.
+	 * @returns The wrapped events emitted by that transaction, or `undefined` if the transaction has aged out of the `TxEventCache` (bounded by `options.maxTx`) or was never observed.
+	 */
 	public getEventsByTx(txSig: TransactionSignature): WrappedEvents | undefined {
 		return this.txEventCache.get(txSig);
 	}

package/src/events/eventsServerLogProvider.ts

@@ -13,6 +13,17 @@ if (typeof window !== 'undefined' && window.WebSocket) {
 const EVENT_SERVER_HEARTBEAT_INTERVAL_MS = 5000;
 const ALLOWED_MISSED_HEARTBEATS = 3;
 
+/**
+ * `LogProvider` backed by the Velocity-hosted events server: a websocket
+ * that pushes pre-parsed events per subscribed channel (event type),
+ * optionally filtered to one user account, instead of raw RPC logs. Expects
+ * a heartbeat message on channel `'heartbeat'` at least every
+ * `EVENT_SERVER_HEARTBEAT_INTERVAL_MS` (5s); if none arrives within 3 missed
+ * intervals it closes and resubscribes, emitting `'reconnect'` on
+ * `eventEmitter` with the attempt count. Each received event is repackaged
+ * as a synthetic 3-line log array (`invoke` / raw log / `success`) so it can
+ * be run back through the same `parseLogs` pipeline as RPC-sourced logs.
+ */
 export class EventsServerLogProvider implements LogProvider {
 	private ws?: WebSocket;
 	private callback?: logProviderCallback;
@@ -23,6 +34,11 @@ export class EventsServerLogProvider implements LogProvider {
 	private reconnectAttempts = 0;
 	eventEmitter: EventEmitter = new EventEmitter();
 
+	/**
+	 * @param url Websocket URL of the Velocity events server.
+	 * @param eventTypes Event type channels to subscribe to (one `subscribe` message sent per type on connect).
+	 * @param userAccount If provided, scopes the subscription server-side to events for this user account (base58 pubkey string).
+	 */
 	public constructor(
 		private readonly url: string,
 		private readonly eventTypes: EventType[],
@@ -33,6 +49,7 @@ export class EventsServerLogProvider implements LogProvider {
 		return this.ws !== undefined;
 	}
 
+	/** Opens the websocket and sends a `subscribe` message per configured event type once connected. `skipHistory` is accepted for `LogProvider` interface compatibility but has no effect (the server only ever pushes new events). Always resolves `true`; malformed inbound messages are caught and logged, not thrown. */
 	public async subscribe(callback: logProviderCallback): Promise<boolean> {
 		if (this.ws !== undefined) {
 			return true;
@@ -40,6 +57,12 @@ export class EventsServerLogProvider implements LogProvider {
 		const ws = new WebSocketImpl(this.url);
 		this.ws = ws;
 
+		// reset teardown flags for a fresh subscription cycle — the `ws !== undefined`
+		// unsubscribe path (e.g. a heartbeat-timeout resubscribe) leaves isUnsubscribing
+		// set, which would otherwise disable the watchdog and reconnect on this new socket
+		this.isUnsubscribing = false;
+		this.externalUnsubscribe = false;
+
 		this.callback = callback;
 		ws.addEventListener('open', () => {
 			for (const channel of this.eventTypes) {
@@ -113,6 +136,11 @@ export class EventsServerLogProvider implements LogProvider {
 		return true;
 	}
 
+	/**
+	 * Closes the websocket and clears the heartbeat timeout.
+	 * @param external Whether this is a caller-initiated unsubscribe rather than an internal one during a reconnect cycle.
+	 * @returns Always resolves `true`.
+	 */
 	public async unsubscribe(external = false): Promise<boolean> {
 		this.isUnsubscribing = true;
 		this.externalUnsubscribe = external;

package/src/events/fetchLogs.ts

@@ -7,10 +7,27 @@ import {
 	TransactionSignature,
 	VersionedTransactionResponse,
 } from '@solana/web3.js';
-import { WrappedEvents } from './types';
+import {
+	DefaultEventSubscriptionOptions,
+	EventType,
+	WrappedEvents,
+} from './types';
 import { promiseTimeout } from '../util/promiseTimeout';
 import { parseLogs } from './parse';
 
+/**
+ * Case-insensitive lookup from decoded (camelCase) IDL event names to
+ * PascalCase `EventType` keys, mirroring `EventSubscriber`'s
+ * `eventTypeByLowercaseName` — `@coral-xyz/anchor` 0.32+ decodes event names
+ * in camelCase, but the rest of the SDK keys off the PascalCase `EventType`.
+ */
+const eventTypeByLowercaseName = new Map<string, EventType>(
+	(DefaultEventSubscriptionOptions.eventTypes ?? []).map((eventType) => [
+		eventType.toLowerCase(),
+		eventType,
+	])
+);
+
 type Log = { txSig: TransactionSignature; slot: number; logs: string[] };
 type FetchLogsResponse = {
 	earliestTx: string;
@@ -31,6 +48,21 @@ function mapTransactionResponseToLog(
 	};
 }
 
+/**
+ * Fetches raw transaction logs for `address`, newest-first from
+ * `getSignaturesForAddress` then batch-fetched via `getTransaction`. Used by
+ * both `PollingLogProvider` (incremental polling) and
+ * `EventSubscriber.fetchPreviousTx` (historical backfill). Failed
+ * transactions (with an `err`) are filtered out before fetching logs.
+ * @param connection RPC connection.
+ * @param address Account/program address to fetch signatures for.
+ * @param finality Commitment for both the signature list and the transaction fetches.
+ * @param beforeTx Only return signatures older than this one (pagination cursor).
+ * @param untilTx Stop at (exclusive of) this signature.
+ * @param limit Max signatures to request from `getSignaturesForAddress`; RPC default applies if omitted.
+ * @param batchSize Number of `getTransaction` calls batched per RPC round-trip; defaults to 25.
+ * @returns `undefined` if no non-failed signatures were found in range; otherwise the transaction logs plus the earliest/most-recent signature, slot, and block time observed, for use as the next `beforeTx`/`mostRecentSeenTx` cursor.
+ */
 export async function fetchLogs(
 	connection: Connection,
 	address: PublicKey,
@@ -89,6 +121,15 @@ export async function fetchLogs(
 	};
 }
 
+/**
+ * Fetches `getTransaction` for a batch of signatures in a single RPC batch
+ * request, with a 10-second overall timeout.
+ * @param connection RPC connection.
+ * @param signatures Signatures to fetch (fetched as `maxSupportedTransactionVersion: 0`).
+ * @param finality Commitment to fetch each transaction at.
+ * @returns One `Log` per signature that returned a result (signatures the RPC couldn't resolve are silently dropped, not padded with placeholders).
+ * @throws (rejects) if the batch RPC call doesn't complete within 10 seconds.
+ */
 export async function fetchTransactionLogs(
 	connection: Connection,
 	signatures: TransactionSignature[],
@@ -134,6 +175,11 @@ function chunk<T>(array: readonly T[], size: number): T[][] {
 		.map((begin) => array.slice(begin, begin + size));
 }
 
+/**
+ * Standalone helper to decode events out of an already-fetched transaction or
+ * log object, without going through `EventSubscriber`. Useful for one-off
+ * decoding (e.g. re-parsing a transaction fetched elsewhere).
+ */
 export class LogParser {
 	private program: Program;
 
@@ -141,6 +187,7 @@ export class LogParser {
 		this.program = program;
 	}
 
+	/** Decodes the events emitted in a fetched `TransactionResponse`. Assigns `txSigIndex` by decode order (0-based), not by any provider-supplied index. */
 	public parseEventsFromTransaction(
 		transaction: TransactionResponse
 	): WrappedEvents {
@@ -149,6 +196,7 @@ export class LogParser {
 		return this.parseEventsFromLogs(transactionLogObject);
 	}
 
+	/** Decodes the events in a `{ txSig, slot, logs }` log object. Returns an empty array if `logs` is falsy. Assigns `txSigIndex` by decode order (0-based). */
 	public parseEventsFromLogs(event: Log): WrappedEvents {
 		const records: WrappedEvents = [];
 
@@ -158,7 +206,9 @@ export class LogParser {
 		for (const eventLog of parseLogs(this.program, event.logs)) {
 			eventLog.data.txSig = event.txSig;
 			eventLog.data.slot = event.slot;
-			eventLog.data.eventType = eventLog.name;
+			eventLog.data.eventType =
+				eventTypeByLowercaseName.get(eventLog.name.toLowerCase()) ??
+				eventLog.name;
 			eventLog.data.txSigIndex = runningEventIndex;
 			// @ts-ignore
 			records.push(eventLog.data);