@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/accounts/pollingOracleAccountSubscriber.ts

@@ -10,6 +10,7 @@ import { PublicKey } from '@solana/web3.js';
 import { BulkAccountLoader } from './bulkAccountLoader';
 import { OracleClient, OraclePriceData } from '../oracles/types';
 
+/** Tracks a single oracle account's decoded `OraclePriceData` via a shared `BulkAccountLoader`, decoding raw buffers with the source-appropriate `OracleClient` (Pyth/Switchboard/quote-asset/etc.). */
 export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 	isSubscribed: boolean;
 	eventEmitter: StrictEventEmitter<EventEmitter, OracleEvents>;
@@ -22,6 +23,11 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 
 	oraclePriceData?: DataAndSlot<OraclePriceData>;
 
+	/**
+	 * @param publicKey Address of the oracle account to track.
+	 * @param oracleClient Source-specific decoder (Pyth/Switchboard/quote-asset/etc.) used to parse the raw buffer into `OraclePriceData`.
+	 * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+	 */
 	public constructor(
 		publicKey: PublicKey,
 		oracleClient: OracleClient,
@@ -34,6 +40,13 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 		this.eventEmitter = new EventEmitter();
 	}
 
+	/**
+	 * Registers this account with the shared `BulkAccountLoader`, then polls up to 5 times
+	 * (once per `load()` cycle) until data has loaded, since the oracle account may not have been
+	 * fetched by the shared loader on the very first poll. `isSubscribed` is only set `true` if
+	 * data loaded within those retries.
+	 * @returns `true` if oracle data loaded within the retry budget, `false` otherwise.
+	 */
 	async subscribe(): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;
@@ -57,6 +70,7 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 		return subscriptionSucceeded;
 	}
 
+	/** Registers this account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
 	async addToAccountLoader(): Promise<void> {
 		if (this.callbackId) {
 			return;
@@ -64,9 +78,9 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 
 		this.callbackId = await this.accountLoader.addAccount(
 			this.publicKey,
-			async (buffer, slot) => {
+			(buffer, slot) => {
 				const oraclePriceData =
-					await this.oracleClient.getOraclePriceDataFromBuffer(buffer);
+					this.oracleClient.getOraclePriceDataFromBuffer(buffer);
 				this.oraclePriceData = { data: oraclePriceData, slot };
 				// @ts-ignore
 				this.eventEmitter.emit('oracleUpdate', oraclePriceData);
@@ -79,6 +93,7 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 		});
 	}
 
+	/** Forces the shared `BulkAccountLoader` to load, then decodes this account's buffer from it if present. Does not check slot ordering against the previously cached value (the loader itself already filters out stale/unchanged buffers before invoking callbacks). */
 	async fetch(): Promise<void> {
 		await this.accountLoader.load();
 		const bufferAndSlot = this.accountLoader.getBufferAndSlot(this.publicKey);
@@ -95,6 +110,7 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 		};
 	}
 
+	/** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
 	async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -113,6 +129,7 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 		this.isSubscribed = false;
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -121,11 +138,13 @@ export class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. */
 	public getOraclePriceData(): DataAndSlot<OraclePriceData> {
 		this.assertIsSubscribed();
 		return this.oraclePriceData!;
 	}
 
+	/** True once oracle data has been loaded, independent of `isSubscribed`. */
 	didSubscriptionSucceed(): boolean {
 		return !!this.oraclePriceData;
 	}

package/src/accounts/pollingTokenAccountSubscriber.ts

@@ -11,6 +11,11 @@ import { BulkAccountLoader } from './bulkAccountLoader';
 import { Account } from '@solana/spl-token';
 import { parseTokenAccount } from '../token';
 
+/**
+ * Tracks an SPL token account's parsed balance/owner via a shared `BulkAccountLoader`. Used for
+ * things like a spot market's token vault or a user's wallet token account, where a dedicated
+ * WebSocket subscription per account is unnecessary.
+ */
 export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 	isSubscribed: boolean;
 	eventEmitter: StrictEventEmitter<EventEmitter, TokenAccountEvents>;
@@ -22,6 +27,10 @@ export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 
 	tokenAccountAndSlot?: DataAndSlot<Account>;
 
+	/**
+	 * @param publicKey Address of the SPL token account to track.
+	 * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+	 */
 	public constructor(publicKey: PublicKey, accountLoader: BulkAccountLoader) {
 		this.isSubscribed = false;
 		this.publicKey = publicKey;
@@ -29,6 +38,13 @@ export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 		this.eventEmitter = new EventEmitter();
 	}
 
+	/**
+	 * Registers this account with the shared `BulkAccountLoader`, then polls up to 5 times
+	 * (once per `load()` cycle) until data has loaded, since the token account may not have been
+	 * fetched by the shared loader on the very first poll. `isSubscribed` is only set `true` if
+	 * data loaded within those retries.
+	 * @returns `true` if account data loaded within the retry budget, `false` otherwise.
+	 */
 	async subscribe(): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;
@@ -51,6 +67,7 @@ export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 		return subscriptionSucceeded;
 	}
 
+	/** Registers this account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
 	async addToAccountLoader(): Promise<void> {
 		if (this.callbackId) {
 			return;
@@ -72,6 +89,7 @@ export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 		});
 	}
 
+	/** Forces the shared `BulkAccountLoader` to load, then reads and parses this account's buffer from it if present. Does not check slot ordering against the previously cached value (the loader itself already filters out stale/unchanged buffers before invoking callbacks). */
 	async fetch(): Promise<void> {
 		await this.accountLoader.load();
 		const bufferAndSlot = this.accountLoader.getBufferAndSlot(this.publicKey);
@@ -88,6 +106,7 @@ export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 		};
 	}
 
+	/** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
 	async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -106,6 +125,7 @@ export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 		this.isSubscribed = false;
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -114,11 +134,13 @@ export class PollingTokenAccountSubscriber implements TokenAccountSubscriber {
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. */
 	public getTokenAccountAndSlot(): DataAndSlot<Account> {
 		this.assertIsSubscribed();
 		return this.tokenAccountAndSlot!;
 	}
 
+	/** True once account data has been loaded, independent of `isSubscribed`. */
 	didSubscriptionSucceed(): boolean {
 		return !!this.tokenAccountAndSlot;
 	}

package/src/accounts/pollingUserAccountSubscriber.ts

@@ -11,6 +11,13 @@ import { PublicKey } from '@solana/web3.js';
 import { UserAccount } from '../types';
 import { BulkAccountLoader } from './bulkAccountLoader';
 
+/**
+ * `UserAccountSubscriber` backed by a shared `BulkAccountLoader` instead of a dedicated
+ * WebSocket subscription. Registers a callback for the user's `UserAccount` and relies on the
+ * loader's periodic batched `getMultipleAccounts` polling to detect changes. Prefer this over
+ * `WebSocketUserAccountSubscriber` when tracking many users concurrently (e.g. a keeper watching
+ * the whole DLOB) to keep the RPC/WS connection count bounded.
+ */
 export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 	isSubscribed: boolean;
 	connection: Connection;
@@ -25,6 +32,12 @@ export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 
 	user?: DataAndSlot<UserAccount>;
 
+	/**
+	 * @param connection Connection (or bankrun-compatible shim) used for the one-off `fetch()` fallback.
+	 * @param userAccountPublicKey Address of the `UserAccount` to track.
+	 * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+	 * @param decode Decode function for the raw account buffer (typically the program's Anchor coder).
+	 */
 	public constructor(
 		connection: Connection,
 		userAccountPublicKey: PublicKey,
@@ -39,6 +52,12 @@ export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 		this.decode = decode;
 	}
 
+	/**
+	 * Registers this account with the shared `BulkAccountLoader` and, if no data has loaded yet
+	 * (from a prior fetch or the optional `userAccount` seed), performs a one-off `fetch()` so the
+	 * subscriber has data before returning. Idempotent: a no-op if already subscribed.
+	 * @param userAccount Optional pre-fetched account data to seed with (at slot 0) instead of an immediate fetch.
+	 */
 	async subscribe(userAccount?: UserAccount): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;
@@ -61,6 +80,7 @@ export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 		return true;
 	}
 
+	/** Registers this user's account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
 	async addToAccountLoader(): Promise<void> {
 		if (this.callbackId) {
 			return;
@@ -89,12 +109,14 @@ export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 		});
 	}
 
+	/** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
 	async fetchIfUnloaded(): Promise<void> {
 		if (!this.doesAccountExist()) {
 			await this.fetch();
 		}
 	}
 
+	/** Fetches the account once directly via RPC (independent of the account loader's poll cycle), applying it only if the response's slot is newer than what's cached. Logs and swallows errors (e.g. account not yet initialized) rather than throwing. */
 	async fetch(): Promise<void> {
 		try {
 			const dataAndContext = await this.connection.getAccountInfoAndContext(
@@ -118,10 +140,12 @@ export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 		}
 	}
 
+	/** Type predicate: true once `user` has loaded, narrowing `this.user` to non-undefined for callers that check it first. */
 	doesAccountExist(): this is { user: DataAndSlot<UserAccount> } {
 		return this.user !== undefined;
 	}
 
+	/** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
 	async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -143,6 +167,7 @@ export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 		this.isSubscribed = false;
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -151,11 +176,18 @@ export class PollingUserAccountSubscriber implements UserAccountSubscriber {
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
 	public getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined {
 		this.assertIsSubscribed();
 		return this.user;
 	}
 
+	/**
+	 * Applies an externally-obtained account update (e.g. relayed by the SDK's `User` wrapper) if
+	 * `slot` is strictly newer than the currently cached slot (equal-slot updates are ignored).
+	 * @param userAccount Decoded account data to apply.
+	 * @param slot Slot the data was observed at.
+	 */
 	public updateData(userAccount: UserAccount, slot: number): void {
 		if (!this.user || this.user.slot < slot) {
 			this.user = { data: userAccount, slot };

package/src/accounts/pollingUserStatsAccountSubscriber.ts

@@ -11,6 +11,10 @@ import { PublicKey } from '@solana/web3.js';
 import { UserStatsAccount } from '../types';
 import { BulkAccountLoader } from './bulkAccountLoader';
 
+/**
+ * `UserStatsAccountSubscriber` backed by a shared `BulkAccountLoader` instead of a dedicated
+ * WebSocket subscription, mirroring `PollingUserAccountSubscriber` for `UserStatsAccount`.
+ */
 export class PollingUserStatsAccountSubscriber
 	implements UserStatsAccountSubscriber
 {
@@ -25,6 +29,11 @@ export class PollingUserStatsAccountSubscriber
 
 	userStats?: DataAndSlot<UserStatsAccount>;
 
+	/**
+	 * @param program Anchor program used for the one-off `fetch()` fallback and account decoding.
+	 * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+	 * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		userStatsAccountPublicKey: PublicKey,
@@ -37,6 +46,12 @@ export class PollingUserStatsAccountSubscriber
 		this.userStatsAccountPublicKey = userStatsAccountPublicKey;
 	}
 
+	/**
+	 * Registers this account with the shared `BulkAccountLoader` and, if no data has loaded yet
+	 * (from a prior fetch or the optional `userStatsAccount` seed), performs a one-off `fetch()`
+	 * so the subscriber has data before returning. Idempotent: a no-op if already subscribed.
+	 * @param userStatsAccount Optional pre-fetched account data to seed with (at slot 0) instead of an immediate fetch.
+	 */
 	async subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;
@@ -60,6 +75,7 @@ export class PollingUserStatsAccountSubscriber
 		return true;
 	}
 
+	/** Registers this user stats account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
 	async addToAccountLoader(): Promise<void> {
 		if (this.callbackId !== undefined) {
 			return;
@@ -91,12 +107,14 @@ export class PollingUserStatsAccountSubscriber
 		});
 	}
 
+	/** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
 	async fetchIfUnloaded(): Promise<void> {
 		if (!this.doesAccountExist()) {
 			await this.fetch();
 		}
 	}
 
+	/** Fetches the account once directly via `program.account.userStats.fetchAndContext` (independent of the account loader's poll cycle), applying it only if the response's slot is newer than what's cached. Logs and swallows errors rather than throwing. */
 	async fetch(): Promise<void> {
 		try {
 			const dataAndContext = await (
@@ -120,10 +138,12 @@ export class PollingUserStatsAccountSubscriber
 		}
 	}
 
+	/** Type predicate: true once `userStats` has loaded, narrowing `this.userStats` to non-undefined. */
 	doesAccountExist(): this is { userStats: DataAndSlot<UserStatsAccount> } {
 		return this.userStats !== undefined;
 	}
 
+	/** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
 	async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -141,6 +161,7 @@ export class PollingUserStatsAccountSubscriber
 		this.isSubscribed = false;
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -149,6 +170,7 @@ export class PollingUserStatsAccountSubscriber
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
 	public getUserStatsAccountAndSlot():
 		| DataAndSlot<UserStatsAccount>
 		| undefined {

package/src/accounts/pollingVelocityClientAccountSubscriber.ts

@@ -35,6 +35,15 @@ const ORACLE_DEFAULT_ID = getOracleId(
 	OracleSource.QUOTE_ASSET
 );
 
+/**
+ * `VelocityClientAccountSubscriber` that batches the `State`, every tracked `PerpMarket`/
+ * `SpotMarket`, and every tracked oracle behind a single `BulkAccountLoader` instead of one
+ * WebSocket subscription per account. Cheaper on connection count at the cost of update latency
+ * bounded by the loader's poll interval. `subscribe()` retries the initial load up to 5 times
+ * before giving up (returning `false`) if the `State` account never appears — `didSubscriptionSucceed`
+ * checks only for `state`, since market/oracle data can be added incrementally afterward via
+ * `addPerpMarket`/`addSpotMarket`/`addOracle`.
+ */
 export class PollingVelocityClientAccountSubscriber
 	implements VelocityClientAccountSubscriber
 {
@@ -71,6 +80,15 @@ export class PollingVelocityClientAccountSubscriber
 		this.subscriptionPromiseResolver = res;
 	});
 
+	/**
+	 * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+	 * @param accountLoader Shared `BulkAccountLoader` all state/market/oracle accounts are registered with.
+	 * @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`.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		accountLoader: BulkAccountLoader,
@@ -91,6 +109,13 @@ export class PollingVelocityClientAccountSubscriber
 		this.delistedMarketSetting = delistedMarketSetting;
 	}
 
+	/**
+	 * Registers state/market/oracle accounts with the `BulkAccountLoader` and retries the initial
+	 * load up to 5 times until the `State` account has appeared. 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 loads.
+	 * @returns `true` if `State` account data loaded within the retry budget, `false` otherwise.
+	 */
 	public async subscribe(): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;
@@ -341,6 +366,7 @@ export class PollingVelocityClientAccountSubscriber
 		);
 	}
 
+	/** Forces the shared `BulkAccountLoader` to load, then re-decodes every tracked state/market/oracle account from the loader's cached buffers into this subscriber's maps. */
 	public async fetch(): Promise<void> {
 		await this.accountLoader.load();
 		for (const [_, accountToPoll] of this.accountsToPoll) {
@@ -396,12 +422,14 @@ export class PollingVelocityClientAccountSubscriber
 		}
 	}
 
+	/** True once the `State` account has loaded, independent of `isSubscribed`. Market/oracle data is not required. */
 	didSubscriptionSucceed(): boolean {
 		if (this.state) return true;
 
 		return false;
 	}
 
+	/** Removes every tracked state/market/oracle account and the error callback from the `BulkAccountLoader`, then clears internal maps. */
 	public async unsubscribe(): Promise<void> {
 		for (const [_, accountToPoll] of this.accountsToPoll) {
 			this.accountLoader.removeAccount(
@@ -425,6 +453,11 @@ export class PollingVelocityClientAccountSubscriber
 		this.isSubscribed = false;
 	}
 
+	/**
+	 * Adds a spot market (and its oracle, via `setSpotOracleMap`) to be tracked, registering it
+	 * with the `BulkAccountLoader`. Idempotent: returns `true` immediately if already tracked.
+	 * @param marketIndex Spot market index to start tracking.
+	 */
 	async addSpotMarket(marketIndex: number): Promise<boolean> {
 		const marketPublicKey = await getSpotMarketPublicKey(
 			this.program.programId,
@@ -443,10 +476,15 @@ export class PollingVelocityClientAccountSubscriber
 		}
 
 		await this.addAccountToAccountLoader(accountToPoll);
-		this.setSpotOracleMap();
+		await this.setSpotOracleMap();
 		return true;
 	}
 
+	/**
+	 * Adds a perp market (and its oracle, via `setPerpOracleMap`) to be tracked, registering it
+	 * with the `BulkAccountLoader`. Idempotent: returns `true` immediately if already tracked.
+	 * @param marketIndex Perp market index to start tracking.
+	 */
 	async addPerpMarket(marketIndex: number): Promise<boolean> {
 		const marketPublicKey = await getPerpMarketPublicKey(
 			this.program.programId,
@@ -467,6 +505,13 @@ export class PollingVelocityClientAccountSubscriber
 		return true;
 	}
 
+	/**
+	 * Adds an oracle to be tracked, registering it with the `BulkAccountLoader` and waiting
+	 * (polling up to 3 times at `accountLoader.pollingFrequency` intervals) for it to appear in
+	 * the loader's buffer map before resolving. 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 (
@@ -508,6 +553,7 @@ export class PollingVelocityClientAccountSubscriber
 		console.log(`Pausing to find oracle ${oracle} failed`);
 	}
 
+	/** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked. */
 	async setPerpOracleMap() {
 		const perpMarkets = this.getMarketAccountsAndSlots();
 		const oraclePromises = [];
@@ -530,6 +576,7 @@ export class PollingVelocityClientAccountSubscriber
 		await Promise.all(oraclePromises);
 	}
 
+	/** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked. */
 	async setSpotOracleMap() {
 		const spotMarkets = this.getSpotMarketAccountsAndSlots();
 		const oraclePromises = [];
@@ -552,6 +599,14 @@ export class PollingVelocityClientAccountSubscriber
 		await Promise.all(oraclePromises);
 	}
 
+	/**
+	 * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+	 * oracle, if not shared with a live spot market): removes the `BulkAccountLoader` registration,
+	 * and additionally drops the market/oracle from internal maps if the setting is `Discard`. A
+	 * no-op if the setting is `Subscribe`. Throws if internal bookkeeping is inconsistent (e.g. a
+	 * delisted market missing from `accountsToPoll`), which would indicate a bug rather than an
+	 * expected runtime condition.
+	 */
 	handleDelistedMarkets(): void {
 		if (this.delistedMarketSetting === DelistedMarketSetting.Subscribe) {
 			return;
@@ -601,6 +656,7 @@ export class PollingVelocityClientAccountSubscriber
 		}
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -609,31 +665,43 @@ export class PollingVelocityClientAccountSubscriber
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. */
 	public getStateAccountAndSlot(): DataAndSlot<StateAccount> {
 		this.assertIsSubscribed();
 		return this.state!;
 	}
 
+	/** Returns the cached perp market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
 	public getMarketAccountAndSlot(
 		marketIndex: number
 	): DataAndSlot<PerpMarketAccount> | undefined {
 		return this.perpMarket.get(marketIndex);
 	}
 
+	/** Returns every currently cached perp market. Does not throw `NotSubscribedError`. */
 	public getMarketAccountsAndSlots(): DataAndSlot<PerpMarketAccount>[] {
 		return Array.from(this.perpMarket.values());
 	}
 
+	/** Returns the cached spot market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
 	public getSpotMarketAccountAndSlot(
 		marketIndex: number
 	): DataAndSlot<SpotMarketAccount> | undefined {
 		return this.spotMarket.get(marketIndex);
 	}
 
+	/** Returns every currently cached spot market. Does not throw `NotSubscribedError`. */
 	public getSpotMarketAccountsAndSlots(): DataAndSlot<SpotMarketAccount>[] {
 		return Array.from(this.spotMarket.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 map 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 {
@@ -648,6 +716,13 @@ export class PollingVelocityClientAccountSubscriber
 		return this.oracles.get(oracleId);
 	}
 
+	/**
+	 * 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 `perpOracleMap` (e.g. an admin
+	 * changed it on-chain), 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 {
@@ -667,6 +742,13 @@ export class PollingVelocityClientAccountSubscriber
 		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 `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 {
@@ -685,6 +767,7 @@ export class PollingVelocityClientAccountSubscriber
 		return this.getOraclePriceDataAndSlot(oracleId);
 	}
 
+	/** Retunes the shared `BulkAccountLoader`'s poll interval (ms) for every account it batches (affects other subscribers sharing the same loader too). */
 	public updateAccountLoaderPollingFrequency(pollingFrequency: number): void {
 		this.accountLoader.updatePollingFrequency(pollingFrequency);
 	}

package/src/accounts/testBulkAccountLoader.ts

@@ -1,6 +1,14 @@
 import { AccountToLoad, BulkAccountLoader } from './bulkAccountLoader';
 
+/**
+ * Test-only `BulkAccountLoader` that overrides `loadChunk` to fetch each account individually via
+ * `connection.getAccountInfoAndContext` instead of batching through `getMultipleAccounts`. Used
+ * against test validators/bankrun connections that don't implement the `_rpcBatchRequest` path
+ * the base class relies on. Preserves the same per-account slot/buffer dedup semantics as the
+ * base class (an update is only dispatched if the new slot is not older and the buffer changed).
+ */
 export class TestBulkAccountLoader extends BulkAccountLoader {
+	/** Sequentially fetches every account in every chunk via individual RPC calls, dispatching callbacks for any that changed at a non-decreasing slot. Slower than the base class's batched `getMultipleAccounts` approach by design — intended for test environments only. */
 	async loadChunk(accountsToLoadChunks: AccountToLoad[][]): Promise<void> {
 		if (accountsToLoadChunks.length === 0) {
 			return;