@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/accounts/grpcAccountSubscriber.ts

@@ -13,6 +13,13 @@ import {
 	SubscribeUpdate,
 } from '../isomorphic/grpc';
 
+/**
+ * `AccountSubscriber` for a single account, streamed via a gRPC Geyser plugin (Yellowstone or
+ * LaserStream, per `GrpcConfigs`) instead of the standard `connection.onAccountChange` WebSocket.
+ * Extends `WebSocketAccountSubscriber` to reuse its buffering/decode/resub-timer logic — only the
+ * transport (`subscribe`/`unsubscribe`) is replaced. Construct via the static `create` factory,
+ * not the constructor directly, since establishing the gRPC client is asynchronous.
+ */
 export class grpcAccountSubscriber<T> extends WebSocketAccountSubscriber<T> {
 	private client: Client;
 	private _stream?: ClientDuplexStream;
@@ -41,6 +48,18 @@ export class grpcAccountSubscriber<T> extends WebSocketAccountSubscriber<T> {
 		this.commitmentLevel = commitmentLevel;
 	}
 
+	/**
+	 * Creates a gRPC client (or reuses `clientProp`, letting multiple subscribers share one
+	 * connection) and constructs a `grpcAccountSubscriber`. Does not itself start streaming — call
+	 * `subscribe()` on the result.
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @param accountName Anchor account type name (used for logging and, absent `decodeBuffer`, for decoding via the program coder).
+	 * @param program Anchor program providing the connection and coder.
+	 * @param accountPublicKey Address of the account to track.
+	 * @param decodeBuffer Optional custom decode function; defaults to `program.coder.accounts.decode(accountName, buffer)`.
+	 * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+	 * @param clientProp Optional existing gRPC client to reuse instead of creating a new connection.
+	 */
 	public static async create<U>(
 		grpcConfigs: GrpcConfigs,
 		accountName: string,
@@ -72,6 +91,12 @@ export class grpcAccountSubscriber<T> extends WebSocketAccountSubscriber<T> {
 		);
 	}
 
+	/**
+	 * Seeds `dataAndSlot` with an initial `fetch()` (if not already set), opens a gRPC subscribe
+	 * stream filtered to this single account, and writes the subscribe request. Idempotent: a
+	 * no-op if already subscribed or mid-unsubscribe.
+	 * @param onChange Invoked with the newly decoded account data on each accepted update.
+	 */
 	override async subscribe(onChange: (data: T) => void): Promise<void> {
 		if (this.listenerId != null || this.isUnsubscribing) {
 			return;
@@ -154,6 +179,11 @@ export class grpcAccountSubscriber<T> extends WebSocketAccountSubscriber<T> {
 		});
 	}
 
+	/**
+	 * Writes an empty subscribe request to clear the stream's account filter and cancels any
+	 * pending resub timeout.
+	 * @param onResub Internal flag set to `true` when called as part of an automatic resubscribe cycle, which preserves `resubOpts.resubTimeoutMs` instead of clearing it. Callers should omit this.
+	 */
 	override async unsubscribe(onResub = false): Promise<void> {
 		if (!onResub && this.resubOpts) {
 			this.resubOpts.resubTimeoutMs = undefined;

package/src/accounts/grpcInsuranceFundStakeAccountSubscriber.ts

@@ -5,9 +5,20 @@ import { WebSocketInsuranceFundStakeAccountSubscriber } from './webSocketInsuran
 import { grpcAccountSubscriber } from './grpcAccountSubscriber';
 import { VelocityProgram } from '../config';
 
+/**
+ * `InsuranceFundStakeAccountSubscriber` variant of `WebSocketInsuranceFundStakeAccountSubscriber`
+ * that tracks the `InsuranceFundStake` account via a `grpcAccountSubscriber` (gRPC Geyser stream)
+ * instead of `connection.onAccountChange`.
+ */
 export class grpcInsuranceFundStakeAccountSubscriber extends WebSocketInsuranceFundStakeAccountSubscriber {
 	private grpcConfigs: GrpcConfigs;
 
+	/**
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @param program Anchor program providing the connection and coder.
+	 * @param insuranceFundStakeAccountPublicKey Address of the `InsuranceFundStake` account to track.
+	 * @param resubTimeoutMs Resub watchdog timeout (ms) passed to the underlying `grpcAccountSubscriber`.
+	 */
 	public constructor(
 		grpcConfigs: GrpcConfigs,
 		program: VelocityProgram,
@@ -18,6 +29,11 @@ export class grpcInsuranceFundStakeAccountSubscriber extends WebSocketInsuranceF
 		this.grpcConfigs = grpcConfigs;
 	}
 
+	/**
+	 * Creates the underlying `grpcAccountSubscriber` and subscribes it. Idempotent: a no-op
+	 * (returns `true`) if already subscribed.
+	 * @param insuranceFundStakeAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+	 */
 	async subscribe(
 		insuranceFundStakeAccount?: InsuranceFundStake
 	): Promise<boolean> {

package/src/accounts/grpcMultiAccountSubscriber.ts

@@ -36,6 +36,15 @@ function commitmentLevelToCommitment(
 	}
 }
 
+/**
+ * Multiplexes many accounts of the same Anchor type onto a single gRPC Geyser subscribe stream,
+ * rather than one `grpcAccountSubscriber` per account. Optional generic `U` ("account props")
+ * lets a caller attach metadata (e.g. `OracleInfo`) per pubkey — or per **array** of `U` values
+ * for a pubkey backing multiple logical entries (see `accountPropsMap`, used when several oracle
+ * ids share one underlying account). Construct via the static `create` factory, not the
+ * constructor directly, since establishing the gRPC client is asynchronous. Accounts can be added/
+ * removed from an already-open stream via `addAccounts`/`removeAccounts` without a full resubscribe.
+ */
 export class grpcMultiAccountSubscriber<T, U = undefined> {
 	private client: Client;
 	private _stream?: ClientDuplexStream;
@@ -100,6 +109,18 @@ export class grpcMultiAccountSubscriber<T, U = undefined> {
 		}
 	}
 
+	/**
+	 * Creates a gRPC client (or reuses `clientProp`) and constructs a `grpcMultiAccountSubscriber`.
+	 * Does not itself start streaming — call `subscribe(accounts, onChange)` on the result.
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @param accountName Anchor account type name all multiplexed accounts share, used for decoding via the program coder absent `decodeBuffer`.
+	 * @param program Anchor program providing the connection (for `fetch()`) and coder.
+	 * @param decodeBuffer Optional custom decode function receiving the buffer, the account's base58 pubkey, and its `accountProps` entry (or one element of it, if an array); defaults to `program.coder.accounts.decode(accountName, buffer)`.
+	 * @param resubOpts Resubscription watchdog options; `resubTimeoutMs` triggers a full unsubscribe on inactivity (no automatic resubscribe here — see `onUnsubscribe`).
+	 * @param clientProp Optional existing gRPC client to reuse instead of creating a new connection.
+	 * @param onUnsubscribe Optional callback invoked after `unsubscribe()` completes (or the resub-timeout-driven unsubscribe fires), typically used by callers to drive their own resubscribe logic.
+	 * @param accountPropsMap Optional per-pubkey metadata (or array of metadata, for a shared pubkey) passed through to `decodeBuffer` and the `subscribe`/`addAccounts` change callback.
+	 */
 	public static async create<T, U = undefined>(
 		grpcConfigs: GrpcConfigs,
 		accountName: string,
@@ -133,18 +154,34 @@ export class grpcMultiAccountSubscriber<T, U = undefined> {
 		);
 	}
 
+	/**
+	 * Seeds or overwrites the cached data for one account, bypassing gRPC/RPC. Used to inject
+	 * data the caller already has (e.g. from an initial batch fetch) before the stream delivers
+	 * live updates.
+	 * @param accountPubkey Base58 pubkey of the account.
+	 * @param data Decoded account data to store.
+	 * @param slot Slot the data was observed at; defaults to 0 (the seeded sentinel) if omitted.
+	 */
 	setAccountData(accountPubkey: string, data: T, slot?: number): void {
 		this.dataMap.set(accountPubkey, { data, slot: slot ?? 0 });
 	}
 
+	/** Returns the cached data/slot for one account, or undefined if not yet loaded. */
 	getAccountData(accountPubkey: string): DataAndSlot<T> | undefined {
 		return this.dataMap.get(accountPubkey);
 	}
 
+	/** Returns the full map of base58 pubkey to cached data/slot for every multiplexed account. */
 	getAccountDataMap(): Map<string, DataAndSlot<T>> {
 		return this.dataMap;
 	}
 
+	/**
+	 * Fetches every subscribed account once via chunked `getMultipleAccountsInfoAndContext` calls
+	 * (100 pubkeys per chunk, processed concurrently), updating `dataMap`/`bufferMap` for any
+	 * account whose buffer changed at a non-decreasing slot. Errors are logged (if
+	 * `resubOpts.logResubMessages`) and swallowed rather than thrown.
+	 */
 	async fetch(): Promise<void> {
 		try {
 			// Chunk account IDs into groups of 100 (getMultipleAccounts limit)
@@ -194,10 +231,21 @@ export class grpcMultiAccountSubscriber<T, U = undefined> {
 								slot: currentSlot,
 							});
 
-							const accountDecoded = this.program.coder.accounts.decode(
-								this.accountName,
-								newBuffer
-							);
+							// decode via the injected decoder (with accountProps) so backfill
+							// matches the live-update decode path — the stock program coder
+							// can't decode custom-decoder accounts (e.g. oracle buffers). For a
+							// pubkey backing multiple props, seed from the first (dataMap is
+							// keyed by pubkey; see the accountPropsMap notes above).
+							const accountProps = this.accountPropsMap?.get(accountId);
+							const decodeProps = Array.isArray(accountProps)
+								? accountProps[0]
+								: accountProps;
+							const accountDecoded = this.decodeBufferFn
+								? this.decodeBufferFn(newBuffer, accountId, decodeProps)
+								: this.program.coder.accounts.decode(
+										this.accountName,
+										newBuffer
+								  );
 							this.setAccountData(accountId, accountDecoded, currentSlot);
 						}
 					}
@@ -213,6 +261,13 @@ export class grpcMultiAccountSubscriber<T, U = undefined> {
 		}
 	}
 
+	/**
+	 * Opens a single gRPC subscribe stream covering all of `accounts`. Each update is decoded and
+	 * cached (via `setAccountData`) before `onChange` is invoked. Idempotent: a no-op if already
+	 * subscribed or mid-unsubscribe.
+	 * @param accounts Pubkeys to include in the stream filter.
+	 * @param onChange Invoked once per changed account with its pubkey, decoded data, the notification's `Context` (including `slot`), the raw buffer, and any `accountProps` metadata registered for that pubkey.
+	 */
 	async subscribe(
 		accounts: PublicKey[],
 		onChange: (
@@ -353,10 +408,27 @@ export class grpcMultiAccountSubscriber<T, U = undefined> {
 		});
 	}
 
-	async addAccounts(accounts: PublicKey[]): Promise<void> {
+	/**
+	 * Extends the already-open stream's filter to include `accounts` (re-writing the full
+	 * accumulated filter set, since the gRPC protocol has no incremental "add" primitive), then
+	 * immediately calls `fetch()` to backfill their initial data.
+	 * @param accounts Additional pubkeys to start tracking.
+	 * @param accountProps Optional per-pubkey metadata to merge into `accountPropsMap` so the
+	 *   injected decoder can decode the newly added accounts (without it, a new `(pubkey, source)`
+	 *   oracle would decode with missing `accountProps` and throw).
+	 */
+	async addAccounts(
+		accounts: PublicKey[],
+		accountProps?: Map<string, U | Array<U>>
+	): Promise<void> {
 		for (const pk of accounts) {
 			this.subscribedAccounts.add(pk.toBase58());
 		}
+		if (accountProps) {
+			for (const [key, props] of accountProps.entries()) {
+				this.accountPropsMap.set(key, props);
+			}
+		}
 		const request: SubscribeRequest = {
 			slots: {},
 			accounts: {
@@ -387,6 +459,11 @@ export class grpcMultiAccountSubscriber<T, U = undefined> {
 		await this.fetch();
 	}
 
+	/**
+	 * Removes `accounts` from `subscribedAccounts`/`onChangeMap` and re-writes the stream's filter
+	 * to exclude them. Does not clear their cached data from `dataMap`/`bufferMap`.
+	 * @param accounts Pubkeys to stop tracking.
+	 */
 	async removeAccounts(accounts: PublicKey[]): Promise<void> {
 		for (const pk of accounts) {
 			const k = pk.toBase58();
@@ -422,47 +499,53 @@ export class grpcMultiAccountSubscriber<T, U = undefined> {
 		});
 	}
 
+	/** Writes an empty subscribe request to clear the stream's account filter, cancels any pending resub timeout, and invokes `onUnsubscribe` if one was registered at construction. */
 	async unsubscribe(): Promise<void> {
 		this.isUnsubscribing = true;
 		clearTimeout(this.timeoutId);
 		this.timeoutId = undefined;
 
-		if (this.listenerId != null) {
-			const promise = new Promise<void>((resolve, reject) => {
-				const request: SubscribeRequest = {
-					slots: {},
-					accounts: {},
-					transactions: {},
-					blocks: {},
-					blocksMeta: {},
-					accountsDataSlice: [],
-					entry: {},
-					transactionsStatus: {},
-				};
-				this.stream.write(request, (err) => {
-					if (err === null || err === undefined) {
-						this.listenerId = undefined;
-						this.isUnsubscribing = false;
-						resolve();
-					} else {
-						reject(err);
-					}
+		try {
+			if (this.listenerId != null) {
+				await new Promise<void>((resolve, reject) => {
+					const request: SubscribeRequest = {
+						slots: {},
+						accounts: {},
+						transactions: {},
+						blocks: {},
+						blocksMeta: {},
+						accountsDataSlice: [],
+						entry: {},
+						transactionsStatus: {},
+					};
+					this.stream.write(request, (err) => {
+						if (err === null || err === undefined) {
+							this.listenerId = undefined;
+							resolve();
+						} else {
+							reject(err);
+						}
+					});
+				}).catch((reason) => {
+					console.error(reason);
+					throw reason;
 				});
-			}).catch((reason) => {
-				console.error(reason);
-				throw reason;
-			});
-			return promise;
-		} else {
-			this.isUnsubscribing = false;
-		}
+			}
 
-		if (this.onUnsubscribe) {
-			try {
-				await this.onUnsubscribe();
-			} catch (e) {
-				console.error(e);
+			// invoke onUnsubscribe on the normal path too (previously it only ran when
+			// listenerId was already null, so the resubscribe hook never fired on the
+			// standard unsubscribe path)
+			if (this.onUnsubscribe) {
+				try {
+					await this.onUnsubscribe();
+				} catch (e) {
+					console.error(e);
+				}
 			}
+		} finally {
+			// clear the flag on every exit path, including a failed stream.write, so
+			// the instance isn't wedged and can resubscribe
+			this.isUnsubscribing = false;
 		}
 	}
 

package/src/accounts/grpcMultiUserAccountSubscriber.ts

@@ -13,6 +13,13 @@ import { UserAccount } from '../types';
 import { VelocityProgram } from '../config';
 import { grpcMultiAccountSubscriber } from './grpcMultiAccountSubscriber';
 
+/**
+ * Multiplexes many `UserAccount` subscriptions onto a single `grpcMultiAccountSubscriber`,
+ * exposing a per-user `UserAccountSubscriber` facade via `forUser()` so callers (e.g. `User`
+ * instances) can interact with it as if each had its own subscription. New `forUser()` keys
+ * registered while already subscribed are debounced (`debounceMs`, 20ms) and flushed in a single
+ * batched `addAccounts` call rather than one gRPC round trip per user.
+ */
 export class grpcMultiUserAccountSubscriber {
 	private program: VelocityProgram;
 	private _multiSubscriber?: grpcMultiAccountSubscriber<UserAccount>;
@@ -34,6 +41,8 @@ export class grpcMultiUserAccountSubscriber {
 	private pendingAddKeys = new Set<string>();
 	private debounceTimer?: ReturnType<typeof setTimeout>;
 	private debounceMs = 20;
+	/** Maximum time to wait in `subscribe()` for every registered user key to appear in the multi-subscriber's data map before giving up. */
+	private static readonly SUBSCRIBE_DATA_TIMEOUT_MS = 30_000;
 	private isMultiSubscribed = false;
 	private userAccountSubscribers = new Map<string, UserAccountSubscriber>();
 	private grpcConfigs: GrpcConfigs;
@@ -57,6 +66,12 @@ export class grpcMultiUserAccountSubscriber {
 		}
 	};
 
+	/**
+	 * @param program Anchor program used for the per-user `fetch()` fallback.
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @param resubOpts Resubscription watchdog options passed to the underlying `grpcMultiAccountSubscriber`.
+	 * @param multiSubscriber Optional pre-constructed `grpcMultiAccountSubscriber` to reuse instead of creating a new one in `subscribe()`.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		grpcConfigs: GrpcConfigs,
@@ -71,6 +86,14 @@ export class grpcMultiUserAccountSubscriber {
 		this.resubOpts = resubOpts;
 	}
 
+	/**
+	 * Creates the shared `grpcMultiAccountSubscriber` (if not injected at construction),
+	 * subscribes every per-user facade already registered via `forUser()`, flushes any pending
+	 * user keys into the underlying gRPC stream, and blocks until the multi-subscriber's account
+	 * data map contains an entry for every registered user key (polling at `debounceMs` intervals),
+	 * up to `SUBSCRIBE_DATA_TIMEOUT_MS`.
+	 * @throws if any registered user key is still missing from the data map once the timeout elapses.
+	 */
 	public async subscribe(): Promise<void> {
 		if (!this._multiSubscriber) {
 			this._multiSubscriber =
@@ -96,23 +119,38 @@ export class grpcMultiUserAccountSubscriber {
 		// Wait until the underlying multi-subscriber has data for every registered user key
 		const targetKeys = Array.from(this.listeners.keys());
 		if (targetKeys.length === 0) return;
-		// Poll until all keys are present in dataMap
+		// Poll until all keys are present in dataMap, bounded by a deadline so a key that never
+		// arrives (e.g. dropped subscription) fails loudly instead of hanging forever.
 		// Use debounceMs as the polling cadence to avoid introducing new magic numbers
-		// eslint-disable-next-line no-constant-condition
-		while (true) {
-			const map = this.multiSubscriber.getAccountDataMap();
-			let allPresent = true;
-			for (const k of targetKeys) {
-				if (!map.has(k)) {
-					allPresent = false;
-					break;
-				}
+		const deadline =
+			Date.now() + grpcMultiUserAccountSubscriber.SUBSCRIBE_DATA_TIMEOUT_MS;
+		let missingKeys = targetKeys.filter(
+			(k) => !this.multiSubscriber.getAccountDataMap().has(k)
+		);
+		while (missingKeys.length > 0) {
+			if (Date.now() >= deadline) {
+				throw new Error(
+					`grpcMultiUserAccountSubscriber: timed out after ${
+						grpcMultiUserAccountSubscriber.SUBSCRIBE_DATA_TIMEOUT_MS
+					}ms waiting for account data for keys: ${missingKeys.join(', ')}`
+				);
 			}
-			if (allPresent) break;
 			await new Promise((resolve) => setTimeout(resolve, this.debounceMs));
+			missingKeys = targetKeys.filter(
+				(k) => !this.multiSubscriber.getAccountDataMap().has(k)
+			);
 		}
 	}
 
+	/**
+	 * Returns a `UserAccountSubscriber` facade for `userAccountPublicKey`, creating one on first
+	 * call (subsequent calls for the same pubkey return the same instance). The facade's
+	 * `subscribe()`/`unsubscribe()` register/deregister interest in this shared multi-subscriber
+	 * rather than opening their own gRPC stream; the underlying account is only actually removed
+	 * from the shared stream once every facade sharing that key has unsubscribed. Its `fetch()`
+	 * bypasses the shared stream and issues a direct one-off `program.account.user.fetch` call.
+	 * @param userAccountPublicKey Address of the `UserAccount` to get (or create) a facade for.
+	 */
 	public forUser(userAccountPublicKey: PublicKey): UserAccountSubscriber {
 		if (this.userAccountSubscribers.has(userAccountPublicKey.toBase58())) {
 			return this.userAccountSubscribers.get(userAccountPublicKey.toBase58())!;

package/src/accounts/grpcProgramAccountSubscriber.ts

@@ -11,6 +11,14 @@ import {
 	SubscribeUpdate,
 } from '../isomorphic/grpc';
 
+/**
+ * `ProgramAccountSubscriber` that streams every account owned by the program (optionally
+ * filtered by `memcmp`) via a gRPC Geyser plugin instead of `connection.onProgramAccountChange`.
+ * Extends `WebSocketProgramAccountSubscriber` to reuse its per-account buffering/decode/resub-
+ * timer logic — only the transport (`subscribe`/`unsubscribe`) is replaced. Construct via the
+ * static `create` factory, not the constructor directly, since establishing the gRPC client is
+ * asynchronous.
+ */
 export class grpcProgramAccountSubscriber<
 	T,
 > extends WebSocketProgramAccountSubscriber<T> {
@@ -51,6 +59,19 @@ export class grpcProgramAccountSubscriber<
 		this.commitmentLevel = commitmentLevel;
 	}
 
+	/**
+	 * Creates a gRPC client and constructs a `grpcProgramAccountSubscriber`. Forces zstd
+	 * compression and an adaptive HTTP/2 window on the channel (in addition to any caller-supplied
+	 * `channelOptions`), since program-wide account streams can be high-volume. Does not itself
+	 * start streaming — call `subscribe(onChange)` on the result.
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @param subscriptionName Human-readable name for logging.
+	 * @param accountDiscriminator Anchor account type name passed to `decodeBufferFn` for each update.
+	 * @param program Anchor program whose accounts to stream (filtered to `program.programId` as owner).
+	 * @param decodeBufferFn Decode function for each account's raw buffer.
+	 * @param options `filters.memcmp` filters narrowing which program accounts are streamed; empty streams every account owned by the program.
+	 * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+	 */
 	public static async create<U>(
 		grpcConfigs: GrpcConfigs,
 		subscriptionName: string,
@@ -88,6 +109,13 @@ export class grpcProgramAccountSubscriber<
 		);
 	}
 
+	/**
+	 * Opens a gRPC subscribe stream filtered to accounts owned by `program.programId` (further
+	 * narrowed by the `filters` passed to `create`). Idempotent: a no-op if already subscribed or
+	 * mid-unsubscribe. Unlike `grpcAccountSubscriber`, does not perform an initial `fetch()` — the
+	 * caller must fetch any pre-existing matching accounts separately if needed.
+	 * @param onChange Invoked once per changed account with its pubkey, decoded data, the notification's `Context`, and the raw buffer.
+	 */
 	async subscribe(
 		onChange: (
 			accountId: PublicKey,
@@ -190,6 +218,11 @@ export class grpcProgramAccountSubscriber<
 		});
 	}
 
+	/**
+	 * Writes an empty subscribe request to clear the stream's filter and cancels any pending
+	 * resub timeout.
+	 * @param onResub Internal flag set to `true` when called as part of an automatic resubscribe cycle, which preserves `resubOpts.resubTimeoutMs` instead of clearing it. Callers should omit this.
+	 */
 	public async unsubscribe(onResub = false): Promise<void> {
 		if (!onResub && this.resubOpts) {
 			this.resubOpts.resubTimeoutMs = undefined;

package/src/accounts/grpcUserAccountSubscriber.ts

@@ -5,9 +5,19 @@ import { WebSocketUserAccountSubscriber } from './webSocketUserAccountSubscriber
 import { grpcAccountSubscriber } from './grpcAccountSubscriber';
 import { VelocityProgram } from '../config';
 
+/**
+ * `UserAccountSubscriber` variant of `WebSocketUserAccountSubscriber` that tracks the
+ * `UserAccount` via a `grpcAccountSubscriber` (gRPC Geyser stream) instead of `connection.onAccountChange`.
+ */
 export class grpcUserAccountSubscriber extends WebSocketUserAccountSubscriber {
 	private grpcConfigs: GrpcConfigs;
 
+	/**
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @param program Anchor program providing the connection and coder.
+	 * @param userAccountPublicKey Address of the `UserAccount` to track.
+	 * @param resubOpts Resubscription watchdog options passed to the underlying `grpcAccountSubscriber`.
+	 */
 	public constructor(
 		grpcConfigs: GrpcConfigs,
 		program: VelocityProgram,
@@ -18,6 +28,11 @@ export class grpcUserAccountSubscriber extends WebSocketUserAccountSubscriber {
 		this.grpcConfigs = grpcConfigs;
 	}
 
+	/**
+	 * Creates the underlying `grpcAccountSubscriber` and subscribes it. Idempotent: a no-op
+	 * (returns `true`) if already subscribed.
+	 * @param userAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+	 */
 	async subscribe(userAccount?: UserAccount): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;

package/src/accounts/grpcUserStatsAccountSubscriber.ts

@@ -5,9 +5,19 @@ import { WebSocketUserStatsAccountSubscriber } from './webSocketUserStatsAccount
 import { grpcAccountSubscriber } from './grpcAccountSubscriber';
 import { VelocityProgram } from '../config';
 
+/**
+ * `UserStatsAccountSubscriber` variant of `WebSocketUserStatsAccountSubscriber` that tracks the
+ * `UserStatsAccount` via a `grpcAccountSubscriber` (gRPC Geyser stream) instead of `connection.onAccountChange`.
+ */
 export class grpcUserStatsAccountSubscriber extends WebSocketUserStatsAccountSubscriber {
 	private grpcConfigs: GrpcConfigs;
 
+	/**
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @param program Anchor program providing the connection and coder.
+	 * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+	 * @param resubOpts Resubscription watchdog options passed to the underlying `grpcAccountSubscriber`.
+	 */
 	public constructor(
 		grpcConfigs: GrpcConfigs,
 		program: VelocityProgram,
@@ -18,6 +28,11 @@ export class grpcUserStatsAccountSubscriber extends WebSocketUserStatsAccountSub
 		this.grpcConfigs = grpcConfigs;
 	}
 
+	/**
+	 * Creates the underlying `grpcAccountSubscriber` and subscribes it. Idempotent: a no-op
+	 * (returns `true`) if already subscribed.
+	 * @param userStatsAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+	 */
 	async subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;

package/src/accounts/grpcVelocityClientAccountSubscriber.ts

@@ -11,9 +11,25 @@ import { grpcAccountSubscriber } from './grpcAccountSubscriber';
 import { PerpMarketAccount, SpotMarketAccount, StateAccount } from '../types';
 import { getOracleId } from '../oracles/oracleId';
 
+/**
+ * `VelocityClientAccountSubscriber` variant of `WebSocketVelocityClientAccountSubscriber` that
+ * subscribes each per-account subscriber via `grpcAccountSubscriber.create` (gRPC Geyser stream)
+ * instead of `connection.onAccountChange`. Reuses the parent class's `setInitialData`/oracle-map/
+ * delisted-market logic verbatim; only the account-subscription creation is overridden.
+ */
 export class grpcVelocityClientAccountSubscriber extends WebSocketVelocityClientAccountSubscriber {
 	private grpcConfigs: GrpcConfigs;
 
+	/**
+	 * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+	 * @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.
+	 * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing.
+	 * @param resubOpts Resubscription watchdog options passed to every per-account subscriber.
+	 */
 	constructor(
 		grpcConfigs: GrpcConfigs,
 		program: VelocityProgram,
@@ -36,6 +52,13 @@ export class grpcVelocityClientAccountSubscriber extends WebSocketVelocityClient
 		this.grpcConfigs = grpcConfigs;
 	}
 
+	/**
+	 * Subscribes the `State` account via gRPC, batch-seeds all market/oracle accounts via
+	 * `setInitialData()` (inherited RPC-based batch fetch), then subscribes every per-account gRPC
+	 * subscriber 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`.
+	 */
 	public async subscribe(): Promise<boolean> {
 		if (this.isSubscribed) {
 			return true;
@@ -119,6 +142,11 @@ export class grpcVelocityClientAccountSubscriber extends WebSocketVelocityClient
 		return true;
 	}
 
+	/**
+	 * Creates and subscribes a `grpcAccountSubscriber` for one spot market, seeding it from
+	 * `initialSpotMarketAccountData` if available.
+	 * @param marketIndex Spot market index to subscribe.
+	 */
 	override async subscribeToSpotMarketAccount(
 		marketIndex: number
 	): Promise<boolean> {
@@ -148,6 +176,13 @@ export class grpcVelocityClientAccountSubscriber extends WebSocketVelocityClient
 		return true;
 	}
 
+	/**
+	 * Creates and subscribes a `grpcAccountSubscriber` for one perp market, seeding it from
+	 * `initialPerpMarketAccountData` if available. Unlike the parent class's WebSocket variant,
+	 * does not call `ensureAccountFetched` — the gRPC subscriber's own initial `fetch()` (inside
+	 * `subscribe`) is relied on directly.
+	 * @param marketIndex Perp market index to subscribe.
+	 */
 	async subscribeToPerpMarketAccount(marketIndex: number): Promise<boolean> {
 		const perpMarketPublicKey = await getPerpMarketPublicKey(
 			this.program.programId,
@@ -175,6 +210,12 @@ export class grpcVelocityClientAccountSubscriber extends WebSocketVelocityClient
 		return true;
 	}
 
+	/**
+	 * Creates and subscribes a `grpcAccountSubscriber` for one oracle, decoding buffers with the
+	 * source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available.
+	 * @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(