@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/accounts/webSocketVelocityClientAccountSubscriber.ts

@@ -55,6 +55,16 @@ async function ensureAccountFetched<T>(
 	}
 }
 
+/**
+ * Default `VelocityClientAccountSubscriber` implementation: creates one `WebSocketAccountSubscriber`
+ * per tracked `State`/`PerpMarket`/`SpotMarket`/oracle account, giving the lowest update latency
+ * at the cost of one WebSocket subscription per account. Before subscribing each per-account
+ * subscriber, `setInitialData()` batch-fetches all of them via `getMultipleAccountsInfo` so the
+ * per-account `WebSocketAccountSubscriber.subscribe()` calls can seed from that data instead of
+ * each issuing its own `getAccountInfo` round trip. `customPerpMarketAccountSubscriber`/
+ * `customOracleAccountSubscriber` let a caller substitute `WebSocketAccountSubscriberV2` (or any
+ * other `AccountSubscriber` implementation) for those two account types specifically.
+ */
 export class WebSocketVelocityClientAccountSubscriber
 	implements VelocityClientAccountSubscriber
 {
@@ -110,6 +120,18 @@ export class WebSocketVelocityClientAccountSubscriber
 	protected subscriptionPromiseResolver: (val: boolean) => void = () => {};
 	protected subscriptionPromise: Promise<boolean> = Promise.resolve(false);
 
+	/**
+	 * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+	 * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+	 * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+	 * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+	 * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state, ignoring the index/info args above.
+	 * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing; see `DelistedMarketSetting`.
+	 * @param resubOpts Resubscription watchdog options passed to every per-account `WebSocketAccountSubscriber`.
+	 * @param commitment Commitment for every per-account subscription; defaults to the provider's configured commitment.
+	 * @param customPerpMarketAccountSubscriber Optional alternate `AccountSubscriber` constructor (e.g. `WebSocketAccountSubscriberV2`) used for perp market accounts instead of the default `WebSocketAccountSubscriber`.
+	 * @param customOracleAccountSubscriber Optional alternate `AccountSubscriber` constructor used for oracle accounts instead of the default `WebSocketAccountSubscriber`.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		perpMarketIndexes: number[],
@@ -150,6 +172,16 @@ export class WebSocketVelocityClientAccountSubscriber
 		this.customOracleAccountSubscriber = customOracleAccountSubscriber;
 	}
 
+	/**
+	 * Subscribes the `State` account, batch-seeds all market/oracle accounts via `setInitialData()`,
+	 * then subscribes every per-account `WebSocketAccountSubscriber` (or the custom subscriber
+	 * class, if configured) for perp markets, spot markets, and oracles. Applies
+	 * `delistedMarketSetting` afterward. Idempotent: a no-op if already subscribed, and concurrent
+	 * calls while a subscribe is in flight share the same result via `subscriptionPromise` rather
+	 * than issuing duplicate subscriptions. Always resolves `true` (no retry/failure path — a
+	 * per-account fetch failure surfaces via `ensureAccountFetched`'s retries, not by aborting
+	 * subscribe).
+	 */
 	public async subscribe(): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;
@@ -238,6 +270,14 @@ export class WebSocketVelocityClientAccountSubscriber
 			.map((begin) => array.slice(begin, begin + size));
 	};
 
+	/**
+	 * Batch-fetches every tracked perp market, spot market, and oracle account via chunked
+	 * `getMultipleAccountsInfo` calls (75 pubkeys per chunk) and stashes the decoded results in
+	 * `initialPerpMarketAccountData`/`initialSpotMarketAccountData`/`initialOraclePriceData`.
+	 * Each per-account `WebSocketAccountSubscriber.subscribe()` call seeds from this data via
+	 * `setData` instead of issuing its own `getAccountInfo` round trip. Skips markets already
+	 * populated (e.g. by `findAllMarketAndOracles` when `shouldFindAllMarketsAndOracles` is set).
+	 */
 	async setInitialData(): Promise<void> {
 		const connection = this.program.provider.connection;
 
@@ -338,12 +378,14 @@ export class WebSocketVelocityClientAccountSubscriber
 		);
 	}
 
+	/** Clears the seed data stashed by `setInitialData()` once every per-account subscriber has consumed it, freeing the memory. */
 	removeInitialData() {
 		this.initialPerpMarketAccountData = new Map();
 		this.initialSpotMarketAccountData = new Map();
 		this.initialOraclePriceData = new Map();
 	}
 
+	/** Subscribes a `WebSocketAccountSubscriber` for every tracked perp market index, in parallel. */
 	async subscribeToPerpMarketAccounts(): Promise<boolean> {
 		await Promise.all(
 			this.perpMarketIndexes.map((marketIndex) =>
@@ -353,6 +395,13 @@ export class WebSocketVelocityClientAccountSubscriber
 		return true;
 	}
 
+	/**
+	 * Creates and subscribes the per-account subscriber (custom class if `customPerpMarketAccountSubscriber`
+	 * is set, else `WebSocketAccountSubscriber`) for one perp market, seeding it from
+	 * `initialPerpMarketAccountData` if available, and waits (via `ensureAccountFetched`, up to 5
+	 * retries with a 200ms backoff) for data to actually land before returning.
+	 * @param marketIndex Perp market index to subscribe.
+	 */
 	async subscribeToPerpMarketAccount(marketIndex: number): Promise<boolean> {
 		const perpMarketPublicKey = await getPerpMarketPublicKey(
 			this.program.programId,
@@ -382,6 +431,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		return true;
 	}
 
+	/** Subscribes a `WebSocketAccountSubscriber` for every tracked spot market index, in parallel. */
 	async subscribeToSpotMarketAccounts(): Promise<boolean> {
 		await Promise.all(
 			this.spotMarketIndexes.map((marketIndex) =>
@@ -391,6 +441,12 @@ export class WebSocketVelocityClientAccountSubscriber
 		return true;
 	}
 
+	/**
+	 * Creates and subscribes a `WebSocketAccountSubscriber` for one spot market, seeding it from
+	 * `initialSpotMarketAccountData` if available, and waits (via `ensureAccountFetched`) for data
+	 * to land before returning.
+	 * @param marketIndex Spot market index to subscribe.
+	 */
 	async subscribeToSpotMarketAccount(marketIndex: number): Promise<boolean> {
 		const marketPublicKey = await getSpotMarketPublicKey(
 			this.program.programId,
@@ -418,6 +474,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		return true;
 	}
 
+	/** Subscribes an account subscriber for every tracked oracle, in parallel, skipping the `PublicKey.default` (quote-asset "no oracle") sentinel. */
 	async subscribeToOracles(): Promise<boolean> {
 		await Promise.all(
 			this.oracleInfos
@@ -428,6 +485,14 @@ export class WebSocketVelocityClientAccountSubscriber
 		return true;
 	}
 
+	/**
+	 * Creates and subscribes the per-account subscriber (custom class if `customOracleAccountSubscriber`
+	 * is set, else `WebSocketAccountSubscriber`) for one oracle, decoding buffers with the
+	 * source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available and
+	 * waits (via `ensureAccountFetched`) for data to land before returning.
+	 * @param oracleInfo Oracle pubkey and source to subscribe.
+	 * @returns `false` if no `OracleClient` is registered for `oracleInfo.source`; otherwise `true`.
+	 */
 	async subscribeToOracle(oracleInfo: OracleInfo): Promise<boolean> {
 		const oracleId = getOracleId(oracleInfo.publicKey, oracleInfo.source);
 		const client = this.oracleClientCache.get(
@@ -469,6 +534,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		return true;
 	}
 
+	/** Unsubscribes every per-account subscriber tracking a perp market, in parallel. */
 	async unsubscribeFromMarketAccounts(): Promise<void> {
 		await Promise.all(
 			Array.from(this.perpMarketAccountSubscribers.values()).map(
@@ -477,6 +543,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		);
 	}
 
+	/** Unsubscribes every per-account subscriber tracking a spot market, in parallel. */
 	async unsubscribeFromSpotMarketAccounts(): Promise<void> {
 		await Promise.all(
 			Array.from(this.spotMarketAccountSubscribers.values()).map(
@@ -485,6 +552,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		);
 	}
 
+	/** Unsubscribes every per-account subscriber tracking an oracle, in parallel. */
 	async unsubscribeFromOracles(): Promise<void> {
 		await Promise.all(
 			Array.from(this.oracleSubscribers.values()).map((accountSubscriber) =>
@@ -493,6 +561,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		);
 	}
 
+	/** Fetches the `State` account and every subscribed perp/spot market's `WebSocketAccountSubscriber` in parallel. A no-op if not subscribed. Oracle accounts are not re-fetched here (they update via their own WS notifications). */
 	public async fetch(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -517,6 +586,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		await Promise.all(promises);
 	}
 
+	/** Tears down the `State` subscriber and every per-account market/oracle subscriber. A no-op if not subscribed. */
 	public async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -531,24 +601,44 @@ export class WebSocketVelocityClientAccountSubscriber
 		this.isSubscribed = false;
 	}
 
+	/**
+	 * Adds a spot market (and its oracle, via `setSpotOracleMap`) to be tracked, subscribing a new
+	 * `WebSocketAccountSubscriber` for it. Idempotent: returns `true` immediately if already tracked.
+	 * @param marketIndex Spot market index to start tracking.
+	 */
 	async addSpotMarket(marketIndex: number): Promise<boolean> {
 		if (this.spotMarketAccountSubscribers.has(marketIndex)) {
 			return true;
 		}
-		const subscriptionSuccess = this.subscribeToSpotMarketAccount(marketIndex);
+		const subscriptionSuccess = await this.subscribeToSpotMarketAccount(
+			marketIndex
+		);
 		await this.setSpotOracleMap();
 		return subscriptionSuccess;
 	}
 
+	/**
+	 * Adds a perp market (and its oracle, via `setPerpOracleMap`) to be tracked, subscribing a new
+	 * `WebSocketAccountSubscriber` for it. Idempotent: returns `true` immediately if already tracked.
+	 * @param marketIndex Perp market index to start tracking.
+	 */
 	async addPerpMarket(marketIndex: number): Promise<boolean> {
 		if (this.perpMarketAccountSubscribers.has(marketIndex)) {
 			return true;
 		}
-		const subscriptionSuccess = this.subscribeToPerpMarketAccount(marketIndex);
+		const subscriptionSuccess = await this.subscribeToPerpMarketAccount(
+			marketIndex
+		);
 		await this.setPerpOracleMap();
 		return subscriptionSuccess;
 	}
 
+	/**
+	 * Adds an oracle to be tracked, subscribing a new per-account subscriber for it. A no-op that
+	 * resolves `true` immediately for the `PublicKey.default` sentinel (quote-asset "no oracle")
+	 * or an oracle already tracked.
+	 * @param oracleInfo Oracle pubkey and source to start tracking.
+	 */
 	async addOracle(oracleInfo: OracleInfo): Promise<boolean> {
 		const oracleId = getOracleId(oracleInfo.publicKey, oracleInfo.source);
 		if (this.oracleSubscribers.has(oracleId)) {
@@ -562,6 +652,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		return this.subscribeToOracle(oracleInfo);
 	}
 
+	/** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked. */
 	async setPerpOracleMap() {
 		const perpMarkets = this.getMarketAccountsAndSlots();
 		const addOraclePromises = [];
@@ -587,6 +678,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		await Promise.all(addOraclePromises);
 	}
 
+	/** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked. */
 	async setSpotOracleMap() {
 		const spotMarkets = this.getSpotMarketAccountsAndSlots();
 		const addOraclePromises = [];
@@ -612,6 +704,12 @@ export class WebSocketVelocityClientAccountSubscriber
 		await Promise.all(addOraclePromises);
 	}
 
+	/**
+	 * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+	 * oracle, if not shared with a live spot market): unsubscribes the per-account subscriber, and
+	 * additionally drops it from `perpMarketAccountSubscribers`/`oracleSubscribers` if the setting
+	 * is `Discard`. A no-op if the setting is `Subscribe`.
+	 */
 	async handleDelistedMarkets(): Promise<void> {
 		if (this.delistedMarketSetting === DelistedMarketSetting.Subscribe) {
 			return;
@@ -640,6 +738,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		}
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -648,6 +747,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed, or a generic `Error` if subscribed but the `State` account hasn't loaded yet (should not normally happen after `subscribe()` resolves). */
 	public getStateAccountAndSlot(): DataAndSlot<StateAccount> {
 		this.assertIsSubscribed();
 		const dataAndSlot = this.stateAccountSubscriber?.dataAndSlot;
@@ -657,6 +757,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		return dataAndSlot;
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` isn't tracked (or hasn't loaded yet). */
 	public getMarketAccountAndSlot(
 		marketIndex: number
 	): DataAndSlot<PerpMarketAccount> | undefined {
@@ -664,6 +765,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		return this.perpMarketAccountSubscribers.get(marketIndex)?.dataAndSlot;
 	}
 
+	/** Returns every currently cached (loaded) perp market. Does not throw `NotSubscribedError`. */
 	public getMarketAccountsAndSlots(): DataAndSlot<PerpMarketAccount>[] {
 		return Array.from(this.perpMarketAccountSubscribers.values())
 			.map((subscriber) => subscriber.dataAndSlot)
@@ -673,6 +775,7 @@ export class WebSocketVelocityClientAccountSubscriber
 			);
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` isn't tracked (or hasn't loaded yet). */
 	public getSpotMarketAccountAndSlot(
 		marketIndex: number
 	): DataAndSlot<SpotMarketAccount> | undefined {
@@ -680,6 +783,7 @@ export class WebSocketVelocityClientAccountSubscriber
 		return this.spotMarketAccountSubscribers.get(marketIndex)?.dataAndSlot;
 	}
 
+	/** Returns every currently cached (loaded) spot market. Does not throw `NotSubscribedError`. */
 	public getSpotMarketAccountsAndSlots(): DataAndSlot<SpotMarketAccount>[] {
 		return Array.from(this.spotMarketAccountSubscribers.values())
 			.map((subscriber) => subscriber.dataAndSlot)
@@ -689,6 +793,13 @@ export class WebSocketVelocityClientAccountSubscriber
 			);
 	}
 
+	/**
+	 * Looks up cached oracle price data by oracle id (see `getOracleId`). Special-cases the
+	 * quote-asset default oracle id, returning the constant `QUOTE_ORACLE_PRICE_DATA` at slot 0
+	 * rather than a subscriber lookup, since that oracle is never actually subscribed to.
+	 * @param oracleId Oracle id string from `getOracleId(publicKey, source)`.
+	 * @returns Cached price data/slot, or undefined if not tracked. Throws `NotSubscribedError` if not subscribed.
+	 */
 	public getOraclePriceDataAndSlot(
 		oracleId: string
 	): DataAndSlot<OraclePriceData> | undefined {
@@ -702,6 +813,13 @@ export class WebSocketVelocityClientAccountSubscriber
 		return this.oracleSubscribers.get(oracleId)?.dataAndSlot;
 	}
 
+	/**
+	 * Convenience lookup: resolves the oracle price data currently mapped to a perp market's
+	 * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+	 * `perpOracleMap`, triggers a background `setPerpOracleMap()` refresh and still returns the
+	 * (possibly stale) mapping for this call.
+	 * @param marketIndex Perp market index whose oracle price to look up.
+	 */
 	public getOraclePriceDataAndSlotForPerpMarket(
 		marketIndex: number
 	): DataAndSlot<OraclePriceData> | undefined {
@@ -720,6 +838,13 @@ export class WebSocketVelocityClientAccountSubscriber
 		return this.getOraclePriceDataAndSlot(oracleId);
 	}
 
+	/**
+	 * Convenience lookup: resolves the oracle price data currently mapped to a spot market's
+	 * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+	 * `spotOracleMap`, triggers a background `setSpotOracleMap()` refresh and still returns the
+	 * (possibly stale) mapping for this call.
+	 * @param marketIndex Spot market index whose oracle price to look up.
+	 */
 	public getOraclePriceDataAndSlotForSpotMarket(
 		marketIndex: number
 	): DataAndSlot<OraclePriceData> | undefined {

package/src/accounts/webSocketVelocityClientAccountSubscriberV2.ts

@@ -50,6 +50,15 @@ const ORACLE_DEFAULT_ID = getOracleId(
 	OracleSource.QUOTE_ASSET
 );
 
+/**
+ * `VelocityClientAccountSubscriber` variant that, unlike `WebSocketVelocityClientAccountSubscriber`
+ * (one `WebSocketAccountSubscriber` per market), multiplexes all perp markets onto a single
+ * `WebSocketProgramAccountsSubscriberV2` program-account stream and all spot markets onto a
+ * second — two WebSocket subscriptions total instead of one per market. `State` and each oracle
+ * still get their own `WebSocketAccountSubscriberV2`. Lower connection overhead at scale;
+ * `addPerpMarket`/`addSpotMarket` are no-ops here since new markets simply arrive automatically
+ * over the existing program-account stream rather than needing an explicit new subscription.
+ */
 export class WebSocketVelocityClientAccountSubscriberV2
 	implements VelocityClientAccountSubscriber
 {
@@ -122,6 +131,17 @@ export class WebSocketVelocityClientAccountSubscriberV2
 	private rpcSubscriptions: RpcSubscriptions<SolanaRpcSubscriptionsApi> &
 		string;
 
+	/**
+	 * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+	 * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false. Only used to derive the initial pubkeys handed to the perp program-account subscriber; new markets arrive automatically thereafter.
+	 * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false. Same caveat as `perpMarketIndexes`.
+	 * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+	 * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state, ignoring the index/info args above.
+	 * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing; see `DelistedMarketSetting`.
+	 * @param resubOpts Resubscription watchdog options passed to the underlying program-account and per-oracle subscribers.
+	 * @param commitment Commitment for every subscription; defaults to the provider's configured commitment.
+	 * @param skipInitialData Currently unused by `subscribe()`/`setInitialData()` (the field is set but never read); defaults to `false`.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		perpMarketIndexes: number[],
@@ -152,6 +172,15 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		this.rpcSubscriptions = rpcSubscriptions;
 	}
 
+	/**
+	 * Derives all tracked perp/spot market pubkeys (or discovers them via `findAllMarketAndOracles`
+	 * if `shouldFindAllMarketsAndOracles` is set), then in parallel: opens the perp and spot
+	 * `WebSocketProgramAccountsSubscriberV2` streams, subscribes the `State` account, and seeds +
+	 * subscribes every oracle. Applies `delistedMarketSetting` afterward. Idempotent: a no-op if
+	 * already subscribed, and concurrent calls while a subscribe is in flight share the same
+	 * result via `subscriptionPromise` rather than issuing duplicate subscriptions.
+	 * @returns `true` on success; `false` if any step throws (subscription state is left partially applied in that case, and `isSubscribed` remains `false`).
+	 */
 	public async subscribe(): Promise<boolean> {
 		try {
 			const startTime = performance.now();
@@ -381,6 +410,20 @@ export class WebSocketVelocityClientAccountSubscriberV2
 			return true;
 		} catch (error) {
 			console.error('Subscription failed:', error);
+			// Tear down any child subscribers that were created before the failure so a
+			// subsequent subscribe() attempt doesn't leak live connections; isSubscribed is
+			// still false at this point, so unsubscribe() alone would otherwise skip this.
+			await Promise.all([
+				this.stateAccountSubscriber?.unsubscribe(),
+				this.unsubscribeFromMarketAccounts(),
+				this.unsubscribeFromSpotMarketAccounts(),
+				this.unsubscribeFromOracles(),
+			]).catch((teardownError) => {
+				console.error(
+					'Error tearing down partial subscription:',
+					teardownError
+				);
+			});
 			this.isSubscribing = false;
 			this.subscriptionPromiseResolver(false);
 			return false;
@@ -395,6 +438,7 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		return result;
 	};
 
+	/** Re-runs `setInitialData()`, re-fetching and re-emitting oracle price data. Does not re-fetch perp/spot market or `State` accounts — those are kept current via their live WebSocket streams. */
 	public async fetch(): Promise<void> {
 		await this.setInitialData();
 	}
@@ -424,6 +468,14 @@ export class WebSocketVelocityClientAccountSubscriberV2
 	}
 
 	// TODO: need more options to skip loading perp market and spot market data. Because of how we fetch within the program account subscribers, I am commenting this all out
+	/**
+	 * Batch-fetches every tracked oracle account via chunked `getMultipleAccountsInfo` calls (100
+	 * pubkeys per chunk), decodes each with the source-appropriate `OracleClient`, stashes the
+	 * results in `initialOraclePriceData`, and immediately emits `oraclePriceUpdate`/`update` for
+	 * each. Unlike the v1 subscriber's `setInitialData`, does not seed perp/spot market data —
+	 * those markets are seeded directly by the program-account subscribers' own initial-account
+	 * list instead.
+	 */
 	async setInitialData(): Promise<void> {
 		const connection = this.program.provider.connection;
 		// Profile oracle initial data setup
@@ -495,12 +547,14 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		this.eventEmitter.emit('update');
 	}
 
+	/** Clears the seed data stashed by `setInitialData()`/`findAllMarketAndOracles` once consumed, freeing the memory. */
 	removeInitialData() {
 		this.initialPerpMarketAccountData = new Map();
 		this.initialSpotMarketAccountData = new Map();
 		this.initialOraclePriceData = new Map();
 	}
 
+	/** Subscribes a `WebSocketAccountSubscriberV2` for every tracked oracle not already subscribed, in parallel, skipping duplicates already present in `oracleSubscribers`. */
 	async subscribeToOracles(): Promise<boolean> {
 		const startTime = performance.now();
 
@@ -526,6 +580,13 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		return true;
 	}
 
+	/**
+	 * Creates and subscribes a `WebSocketAccountSubscriberV2` for one oracle, decoding buffers
+	 * with the source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available
+	 * before subscribing.
+	 * @param oracleInfo Oracle pubkey and source to subscribe.
+	 * @returns `false` if no `OracleClient` is registered for `oracleInfo.source` or the subscribe call throws; otherwise `true`.
+	 */
 	async subscribeToOracle(oracleInfo: OracleInfo): Promise<boolean> {
 		try {
 			const oracleId = getOracleId(oracleInfo.publicKey, oracleInfo.source);
@@ -577,14 +638,17 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		}
 	}
 
+	/** Unsubscribes the single multiplexed perp-market program-account stream. */
 	async unsubscribeFromMarketAccounts(): Promise<void> {
 		await this.perpMarketAllAccountsSubscriber.unsubscribe();
 	}
 
+	/** Unsubscribes the single multiplexed spot-market program-account stream. */
 	async unsubscribeFromSpotMarketAccounts(): Promise<void> {
 		await this.spotMarketAllAccountsSubscriber.unsubscribe();
 	}
 
+	/** Unsubscribes every per-oracle `WebSocketAccountSubscriberV2`, in parallel. */
 	async unsubscribeFromOracles(): Promise<void> {
 		await Promise.all(
 			Array.from(this.oracleSubscribers.values()).map((accountSubscriber) =>
@@ -593,6 +657,7 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		);
 	}
 
+	/** Tears down the `State` subscriber, both market program-account streams, and every oracle subscriber. A no-op if not subscribed. */
 	public async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -613,6 +678,12 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		this.subscriptionPromiseResolver = () => {};
 	}
 
+	/**
+	 * Adds an oracle to be tracked, subscribing a new `WebSocketAccountSubscriberV2` for it. A
+	 * no-op that resolves `true` immediately for the `PublicKey.default` sentinel (quote-asset "no
+	 * oracle") or an oracle already tracked.
+	 * @param oracleInfo Oracle pubkey and source to start tracking.
+	 */
 	async addOracle(oracleInfo: OracleInfo): Promise<boolean> {
 		const oracleId = getOracleId(oracleInfo.publicKey, oracleInfo.source);
 		if (this.oracleSubscribers.has(oracleId)) {
@@ -626,6 +697,7 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		return this.subscribeToOracle(oracleInfo);
 	}
 
+	/** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked. */
 	async setPerpOracleMap() {
 		const perpMarkets = this.getMarketAccountsAndSlots();
 		const addOraclePromises = [];
@@ -651,6 +723,7 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		await Promise.all(addOraclePromises);
 	}
 
+	/** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked. */
 	async setSpotOracleMap() {
 		const spotMarkets = this.getSpotMarketAccountsAndSlots();
 		const addOraclePromises = [];
@@ -676,6 +749,16 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		await Promise.all(addOraclePromises);
 	}
 
+	/**
+	 * Applies `delistedMarketSetting` to any oracle backing a currently `status: delisted` perp
+	 * market (and not still used by a live spot market, per `findDelistedPerpMarketsAndOracles`):
+	 * unsubscribes the oracle's subscriber, and additionally drops it from `oracleSubscribers` if
+	 * the setting is `Discard`. A no-op if the setting is `Subscribe`. Note this only manages
+	 * oracle subscriptions — delisted market accounts themselves cannot be selectively unsubscribed
+	 * from the shared perp/spot program-account stream; instead the `subscribe()` update callback
+	 * drops any incoming update for a `status: delisted` market unless `delistedMarketSetting` is
+	 * `Subscribe`, freezing that market's cached data at its last pre-delisting state.
+	 */
 	async handleDelistedMarketOracles(): Promise<void> {
 		if (this.delistedMarketSetting === DelistedMarketSetting.Subscribe) {
 			return;
@@ -698,6 +781,7 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		}
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -706,6 +790,7 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed, or a generic `Error` (via `assertDataAndSlot`) if subscribed but the `State` account hasn't loaded yet. */
 	public getStateAccountAndSlot(): DataAndSlot<StateAccount> {
 		this.assertIsSubscribed();
 		return assertDataAndSlot(
@@ -714,6 +799,7 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		);
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` hasn't been observed yet on the perp program-account stream. */
 	public getMarketAccountAndSlot(
 		marketIndex: number
 	): DataAndSlot<PerpMarketAccount> | undefined {
@@ -721,10 +807,12 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		return this.perpMarketAccountLatestData.get(marketIndex);
 	}
 
+	/** Returns every currently cached (loaded) perp market. Does not throw `NotSubscribedError`. */
 	public getMarketAccountsAndSlots(): DataAndSlot<PerpMarketAccount>[] {
 		return Array.from(this.perpMarketAccountLatestData.values());
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` hasn't been observed yet on the spot program-account stream. */
 	public getSpotMarketAccountAndSlot(
 		marketIndex: number
 	): DataAndSlot<SpotMarketAccount> | undefined {
@@ -732,10 +820,18 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		return this.spotMarketAccountLatestData.get(marketIndex);
 	}
 
+	/** Returns every currently cached (loaded) spot market. Does not throw `NotSubscribedError`. */
 	public getSpotMarketAccountsAndSlots(): DataAndSlot<SpotMarketAccount>[] {
 		return Array.from(this.spotMarketAccountLatestData.values());
 	}
 
+	/**
+	 * Looks up cached oracle price data by oracle id (see `getOracleId`). Special-cases the
+	 * quote-asset default oracle id, returning the constant `QUOTE_ORACLE_PRICE_DATA` at slot 0
+	 * rather than a subscriber lookup, since that oracle is never actually subscribed to.
+	 * @param oracleId Oracle id string from `getOracleId(publicKey, source)`.
+	 * @returns Cached price data/slot, or undefined if not tracked. Throws `NotSubscribedError` if not subscribed.
+	 */
 	public getOraclePriceDataAndSlot(
 		oracleId: string
 	): DataAndSlot<OraclePriceData> | undefined {
@@ -749,6 +845,13 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		return this.oracleSubscribers.get(oracleId)?.dataAndSlot;
 	}
 
+	/**
+	 * Convenience lookup: resolves the oracle price data currently mapped to a perp market's
+	 * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+	 * `perpOracleMap`, triggers a background `setPerpOracleMap()` refresh and still returns the
+	 * (possibly stale) mapping for this call.
+	 * @param marketIndex Perp market index whose oracle price to look up.
+	 */
 	public getOraclePriceDataAndSlotForPerpMarket(
 		marketIndex: number
 	): DataAndSlot<OraclePriceData> | undefined {
@@ -767,6 +870,13 @@ export class WebSocketVelocityClientAccountSubscriberV2
 		return this.getOraclePriceDataAndSlot(oracleId);
 	}
 
+	/**
+	 * Convenience lookup: resolves the oracle price data currently mapped to a spot market's
+	 * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+	 * `spotOracleMap`, triggers a background `setSpotOracleMap()` refresh and still returns the
+	 * (possibly stale) mapping for this call.
+	 * @param marketIndex Spot market index whose oracle price to look up.
+	 */
 	public getOraclePriceDataAndSlotForSpotMarket(
 		marketIndex: number
 	): DataAndSlot<OraclePriceData> | undefined {