@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/accounts/types.ts

@@ -26,16 +26,52 @@ import { OracleInfo, OraclePriceData } from '../oracles/types';
 import { User } from '../user';
 import { Client, CommitmentLevel, LaserstreamConfig } from '../isomorphic/grpc';
 
+/**
+ * Common contract for a subscriber that tracks a single on-chain account of type `T`.
+ * Implemented by the `WebSocketAccountSubscriber`/`WebSocketAccountSubscriberV2`,
+ * `grpcAccountSubscriber`, and polling-loader-backed subscribers. `dataAndSlot` is
+ * undefined until the first fetch/notification lands; once set, `data` and `slot`
+ * are always updated together (see `DataAndSlot`) so a caller never sees data from
+ * one slot paired with another.
+ */
 export interface AccountSubscriber<T> {
+	/** Latest decoded account data and the slot it was observed at, or undefined before the first load. */
 	dataAndSlot?: DataAndSlot<T>;
+	/**
+	 * Begins tracking the account, seeding `dataAndSlot` with an initial `fetch()` if not already
+	 * set, then attaching a live update source (WebSocket/gRPC notification or accountLoader
+	 * callback). Idempotent: calling again while already subscribed is a no-op.
+	 * @param onChange Invoked with the newly decoded account data whenever a strictly newer slot's
+	 * update is observed.
+	 */
 	subscribe(onChange: (data: T) => void): Promise<void>;
+	/** Fetches the account once via RPC and updates `dataAndSlot` if the response's slot is newer than what's cached. */
 	fetch(): Promise<void>;
+	/** Tears down the live update source. Safe to call when not subscribed. */
 	unsubscribe(): Promise<void>;
 
+	/**
+	 * Seeds or overwrites `dataAndSlot` without an RPC round trip. Used to inject data the caller
+	 * already has (e.g. from a prior fetch elsewhere) before `subscribe()` runs its own fetch.
+	 * @param userAccount Decoded account data to store.
+	 * @param slot Slot the data was observed at; defaults to 0 (the oldest-possible sentinel) if omitted, so a later real update always wins.
+	 */
 	setData(userAccount: T, slot?: number): void;
 }
 
+/**
+ * Contract for a subscriber that tracks every account matching a program-account filter
+ * (e.g. all `User` accounts owned by the program), rather than one specific pubkey.
+ * Implemented by `WebSocketProgramAccountSubscriber`, `WebSocketProgramAccountsSubscriberV2`,
+ * `grpcProgramAccountSubscriber`, and `LaserstreamProgramAccountSubscriber`.
+ */
 export interface ProgramAccountSubscriber<T> {
+	/**
+	 * Subscribes to program-account change notifications matching the filters supplied at
+	 * construction.
+	 * @param onChange Invoked once per changed account with its pubkey, decoded data, the
+	 * notification's `Context` (including `slot`), and the raw account buffer.
+	 */
 	subscribe(
 		onChange: (
 			accountId: PublicKey,
@@ -44,13 +80,26 @@ export interface ProgramAccountSubscriber<T> {
 			buffer: Buffer
 		) => void
 	): Promise<void>;
+	/** Tears down the underlying subscription. Safe to call when not subscribed. */
 	unsubscribe(): Promise<void>;
 }
 
+/**
+ * Thrown by every subscriber's `assertIsSubscribed()`-guarded getter (e.g.
+ * `getUserAccountAndSlot`, `getStateAccountAndSlot`) when called before `subscribe()` has
+ * completed. This is the uniform contract across all subscriber implementations in this
+ * directory: never read cached account data without having subscribed first.
+ */
 export class NotSubscribedError extends Error {
 	name = 'NotSubscribedError';
 }
 
+/**
+ * Events emitted by a `VelocityClientAccountSubscriber` on its `eventEmitter`. `update` fires
+ * after every individual account-specific event (state/market/oracle) as a generic "something
+ * changed" signal; `error` surfaces underlying transport errors (e.g. RPC batch failures)
+ * without unsubscribing.
+ */
 export interface VelocityClientAccountEvents {
 	stateAccountUpdate: (payload: StateAccount) => void;
 	perpMarketAccountUpdate: (payload: PerpMarketAccount) => void;
@@ -65,6 +114,18 @@ export interface VelocityClientAccountEvents {
 	error: (e: Error) => void;
 }
 
+/**
+ * Contract for the subscriber `VelocityClient` uses to keep `State`, `PerpMarket`,
+ * `SpotMarket`, and oracle accounts cached in memory. See `webSocketVelocityClientAccountSubscriber.ts`
+ * (default, one WebSocket subscription per account), `pollingVelocityClientAccountSubscriber.ts`
+ * (single `BulkAccountLoader` batches all accounts via periodic `getMultipleAccounts`), and
+ * `grpcVelocityClientAccountSubscriber.ts`/`grpcVelocityClientAccountSubscriberV2.ts` (gRPC
+ * Geyser stream). Accessor contracts differ by shape: the guarded singleton getters
+ * (`getStateAccountAndSlot`) throw `NotSubscribedError` until `subscribe()` has completed; the
+ * per-market/oracle accessors return `undefined` when that entry isn't cached yet; and the
+ * collection getters (`getMarketAccountsAndSlots`, etc.) are cache reads that return a
+ * possibly-empty array.
+ */
 export interface VelocityClientAccountSubscriber {
 	eventEmitter: StrictEventEmitter<EventEmitter, VelocityClientAccountEvents>;
 	isSubscribed: boolean;
@@ -98,45 +159,76 @@ export interface VelocityClientAccountSubscriber {
 		marketIndex: number
 	): DataAndSlot<OraclePriceData> | undefined;
 
+	/** Present only on polling-backed implementations; retunes the shared `BulkAccountLoader`'s poll interval (ms) for all accounts it batches. */
 	updateAccountLoaderPollingFrequency?: (pollingFrequency: number) => void;
 }
 
+/**
+ * Controls what a `VelocityClientAccountSubscriber` does with a perp market (and its oracle, if
+ * unused elsewhere) once the on-chain market status becomes `delisted`.
+ */
 export enum DelistedMarketSetting {
+	/** Drop the live subscription for the delisted market/oracle but keep the last-known data cached. */
 	Unsubscribe,
+	/** Keep subscribing to the delisted market/oracle as normal (no special handling). */
 	Subscribe,
+	/** Drop the subscription and remove the market/oracle from the subscriber's internal maps entirely. */
 	Discard,
 }
 
+/** Events emitted by a `UserAccountSubscriber` on its `eventEmitter`. `update` fires alongside every `userAccountUpdate`. */
 export interface UserAccountEvents {
 	userAccountUpdate: (payload: UserAccount) => void;
 	update: void;
 	error: (e: Error) => void;
 }
 
+/** Events emitted at the `User` (SDK wrapper) level, distinct from the lower-level `UserAccountEvents`. */
 export interface UserEvents {
 	userUpdate: (payload: User) => void;
 	update: void;
 	error: (e: Error) => void;
 }
 
+/**
+ * Contract for the subscriber `User` uses to track a single `UserAccount`. Implementations:
+ * `WebSocketUserAccountSubscriber` (default), `PollingUserAccountSubscriber` (via
+ * `BulkAccountLoader`), `grpcUserAccountSubscriber`, `OneShotUserAccountSubscriber` (fetch-only,
+ * ~1 RPC call), `BasicUserAccountSubscriber` (no network I/O, data supplied by the caller), and
+ * `WebSocketProgramUserAccountSubscriber` (filters a shared program-account stream).
+ */
 export interface UserAccountSubscriber {
 	eventEmitter: StrictEventEmitter<EventEmitter, UserAccountEvents>;
 	isSubscribed: boolean;
 
+	/**
+	 * @param userAccount Optional pre-fetched account data to seed the subscriber with, skipping
+	 * the initial RPC fetch.
+	 */
 	subscribe(userAccount?: UserAccount): Promise<boolean>;
 	fetch(): Promise<void>;
+	/**
+	 * Applies an externally-obtained account update (e.g. relayed from a parent subscriber) if its
+	 * slot is not older than the currently cached one, emitting `userAccountUpdate`/`update` on
+	 * acceptance.
+	 * @param userAccount Decoded account data to apply.
+	 * @param slot Slot the data was observed at.
+	 */
 	updateData(userAccount: UserAccount, slot: number): void;
 	unsubscribe(): Promise<void>;
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
 	getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined;
 }
 
+/** Events emitted by a `TokenAccountSubscriber` on its `eventEmitter`. */
 export interface TokenAccountEvents {
 	tokenAccountUpdate: (payload: Account) => void;
 	update: void;
 	error: (e: Error) => void;
 }
 
+/** Contract for tracking an SPL token account balance (e.g. a spot market vault or a user's token wallet). Implemented by `PollingTokenAccountSubscriber`. */
 export interface TokenAccountSubscriber {
 	eventEmitter: StrictEventEmitter<EventEmitter, TokenAccountEvents>;
 	isSubscribed: boolean;
@@ -145,9 +237,15 @@ export interface TokenAccountSubscriber {
 	fetch(): Promise<void>;
 	unsubscribe(): Promise<void>;
 
+	/** Throws `NotSubscribedError` if not subscribed. */
 	getTokenAccountAndSlot(): DataAndSlot<Account>;
 }
 
+/**
+ * Contract for tracking an `InsuranceFundStake` account. Implementations:
+ * `WebSocketInsuranceFundStakeAccountSubscriber` (default), `PollingInsuranceFundStakeAccountSubscriber`,
+ * and `grpcInsuranceFundStakeAccountSubscriber`.
+ */
 export interface InsuranceFundStakeAccountSubscriber {
 	eventEmitter: StrictEventEmitter<
 		EventEmitter,
@@ -159,23 +257,27 @@ export interface InsuranceFundStakeAccountSubscriber {
 	fetch(): Promise<void>;
 	unsubscribe(): Promise<void>;
 
+	/** Throws `NotSubscribedError` if not subscribed. */
 	getInsuranceFundStakeAccountAndSlot():
 		| DataAndSlot<InsuranceFundStake>
 		| undefined;
 }
 
+/** Events emitted by an `InsuranceFundStakeAccountSubscriber` on its `eventEmitter`. */
 export interface InsuranceFundStakeAccountEvents {
 	insuranceFundStakeAccountUpdate: (payload: InsuranceFundStake) => void;
 	update: void;
 	error: (e: Error) => void;
 }
 
+/** Events emitted by an `OracleAccountSubscriber` on its `eventEmitter`. */
 export interface OracleEvents {
 	oracleUpdate: (payload: OraclePriceData) => void;
 	update: void;
 	error: (e: Error) => void;
 }
 
+/** Contract for tracking a single oracle account's decoded price data. Implemented by `PollingOracleAccountSubscriber` (via `BulkAccountLoader`). */
 export interface OracleAccountSubscriber {
 	eventEmitter: StrictEventEmitter<EventEmitter, OracleEvents>;
 	isSubscribed: boolean;
@@ -184,55 +286,96 @@ export interface OracleAccountSubscriber {
 	fetch(): Promise<void>;
 	unsubscribe(): Promise<void>;
 
+	/** Throws `NotSubscribedError` if not subscribed. */
 	getOraclePriceData(): DataAndSlot<OraclePriceData>;
 }
 
+/** A `state`/`perpMarket`/`spotMarket` account registered with a `PollingVelocityClientAccountSubscriber`'s `BulkAccountLoader`. */
 export type AccountToPoll = {
+	/** Anchor account discriminator name, also used to route the decoded data and pick the emitted event. */
 	key: 'state' | 'perpMarket' | 'spotMarket';
 	publicKey: PublicKey;
+	/** `VelocityClientAccountEvents` key emitted when this account changes. */
 	eventType: string;
+	/** `BulkAccountLoader` callback id, set once registered; used to remove the account later. */
 	callbackId?: string;
+	/** For `perpMarket`/`spotMarket`, the market index this account decodes to. */
 	mapKey?: number;
 };
 
+/** An oracle account registered with a `PollingVelocityClientAccountSubscriber`'s `BulkAccountLoader`. */
 export type OraclesToPoll = {
 	publicKey: PublicKey;
 	source: OracleSource;
+	/** `BulkAccountLoader` callback id, set once registered; used to remove the oracle later. */
 	callbackId?: string;
 };
 
+/** Raw account buffer paired with the slot it was fetched/observed at; the buffer is undefined if the account does not exist on-chain. */
 export type BufferAndSlot = {
 	slot: number;
 	buffer: Buffer | undefined;
 };
 
+/**
+ * A decoded account payload paired atomically with the slot it was observed at. Every
+ * `AccountSubscriber`/getter in this directory updates `data` and `slot` together in a single
+ * assignment, so a caller reading `dataAndSlot` never sees data from one slot mixed with a slot
+ * number from another. `slot === 0` is the seeded sentinel used when data is injected via
+ * `setData`/a constructor without a real fetch (e.g. `BasicUserAccountSubscriber`) — it is
+ * always superseded once a real fetch or notification lands, since updates only apply when the
+ * new slot is `>=` the cached one.
+ */
 export type DataAndSlot<T> = {
 	data: T;
 	slot: number;
 };
 
+/** Resubscription/polling-fallback tuning for WebSocket- and gRPC-backed subscribers. */
 export type ResubOpts = {
+	/**
+	 * Milliseconds of inactivity (no notification) before the subscriber treats the stream as
+	 * stalled and resubscribes (or starts polling, see `usePollingInsteadOfResub`). Should be at
+	 * least 1000ms; smaller values log a warning. Leave undefined to disable the inactivity
+	 * watchdog entirely.
+	 */
 	resubTimeoutMs?: number;
+	/** Emits verbose `console.log`/`console.debug` diagnostics for resub/polling transitions. Defaults to false. */
 	logResubMessages?: boolean;
 	// New options for polling-based resubscription
+	/**
+	 * On inactivity timeout, poll via RPC to check for a missed update instead of immediately
+	 * tearing down and recreating the WebSocket subscription. Defaults to false on the v1
+	 * `WebSocketAccountSubscriber`; the V2 subscribers default this to `true`.
+	 */
 	usePollingInsteadOfResub?: boolean;
+	/** Polling cadence in ms when `usePollingInsteadOfResub` is active. Defaults to 30000 (30s). */
 	pollingIntervalMs?: number;
 };
 
+/** Events emitted by a `UserStatsAccountSubscriber` on its `eventEmitter`. */
 export interface UserStatsAccountEvents {
 	userStatsAccountUpdate: (payload: UserStatsAccount) => void;
 	update: void;
 	error: (e: Error) => void;
 }
 
+/**
+ * Contract for the subscriber `UserStats` uses to track a single `UserStatsAccount`.
+ * Implementations mirror `UserAccountSubscriber`: `WebSocketUserStatsAccountSubscriber` (default),
+ * `PollingUserStatsAccountSubscriber`, `grpcUserStatsAccountSubscriber`,
+ * `OneShotUserStatsAccountSubscriber`, and `BasicUserStatsAccountSubscriber`.
+ */
 export interface UserStatsAccountSubscriber {
 	eventEmitter: StrictEventEmitter<EventEmitter, UserStatsAccountEvents>;
 	isSubscribed: boolean;
 
+	/** @param userStatsAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch. */
 	subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean>;
 	fetch(): Promise<void>;
 	unsubscribe(): Promise<void>;
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
 	getUserStatsAccountAndSlot(): DataAndSlot<UserStatsAccount> | undefined;
 }
 
@@ -247,27 +390,33 @@ type BaseGrpcConfigs = {
 	enableReconnect?: boolean;
 };
 
+/** gRPC Geyser config for the default Yellowstone (Triton/Dragon's Mouth-compatible) client. */
 export type YellowstoneGrpcConfigs = BaseGrpcConfigs & {
 	client?: 'yellowstone';
 	channelOptions?: ConstructorParameters<typeof Client>[2];
 };
 
+/** gRPC Geyser config for the Helius LaserStream client (`LaserstreamProgramAccountSubscriber`). Requires the optional `helius-laserstream` peer dependency. */
 export type LaserGrpcConfigs = BaseGrpcConfigs & {
 	client: 'laser';
 	channelOptions?: LaserstreamConfig['channelOptions'];
 };
 
+/** Union of supported gRPC Geyser client configs; the `client` discriminant selects Yellowstone vs. LaserStream. */
 export type GrpcConfigs = YellowstoneGrpcConfigs | LaserGrpcConfigs;
 
+/** Contract for tracking an LP-pool `ConstituentAccount`. `sync()` is the fetch/reconcile entry point (analogous to `fetch()` on other subscribers). */
 export interface ConstituentAccountSubscriber {
 	eventEmitter: StrictEventEmitter<EventEmitter, ConstituentAccountEvents>;
 	isSubscribed: boolean;
 
+	/** @param constituentAccount Optional pre-fetched account data to seed the subscriber with. */
 	subscribe(constituentAccount?: ConstituentAccount): Promise<boolean>;
 	sync(): Promise<void>;
 	unsubscribe(): Promise<void>;
 }
 
+/** Events emitted by a `ConstituentAccountSubscriber` on its `eventEmitter`. */
 export interface ConstituentAccountEvents {
 	onAccountUpdate: (
 		account: ConstituentAccount,

package/src/accounts/utils.ts

@@ -3,10 +3,18 @@ import { isVariant, PerpMarketAccount, SpotMarketAccount } from '../types';
 import { OracleInfo } from '../oracles/types';
 import { getOracleId } from '../oracles/oracleId';
 
+/** Capitalizes the first character of `value` (e.g. for building Anchor event/method names from account names). */
 export function capitalize(value: string): string {
 	return value[0].toUpperCase() + value.slice(1);
 }
 
+/**
+ * Unwraps a possibly-undefined `DataAndSlot<T>`, throwing if it hasn't loaded. Use this instead
+ * of a bare non-null assertion when a subscriber's cached data must be present by this point.
+ * @param dataAndSlot The cached data/slot pair to check, typically from `AccountSubscriber.dataAndSlot`.
+ * @param message Error message to throw if `dataAndSlot` is undefined.
+ * @returns The same `dataAndSlot`, narrowed to non-undefined.
+ */
 export function assertDataAndSlot<T>(
 	dataAndSlot: DataAndSlot<T> | undefined,
 	message: string
@@ -17,6 +25,16 @@ export function assertDataAndSlot<T>(
 	return dataAndSlot;
 }
 
+/**
+ * Scans cached perp/spot market data for perp markets with `status: delisted` and identifies
+ * both the delisted market indexes and their oracles, excluding any oracle still in use by a
+ * spot market or a non-delisted perp market (so a shared oracle isn't dropped out from under a
+ * still-live market). Used by `VelocityClientAccountSubscriber` implementations to drive
+ * `DelistedMarketSetting` (unsubscribe/discard) handling.
+ * @param perpMarkets Currently cached perp market data/slots (entries with missing `data` are skipped).
+ * @param spotMarkets Currently cached spot market data/slots, checked to avoid dropping oracles they still reference.
+ * @returns `perpMarketIndexes` of delisted perp markets and `oracles` safe to stop tracking.
+ */
 export function findDelistedPerpMarketsAndOracles(
 	perpMarkets: DataAndSlot<PerpMarketAccount>[],
 	spotMarkets: DataAndSlot<SpotMarketAccount>[]
@@ -37,34 +55,34 @@ export function findDelistedPerpMarketsAndOracles(
 		}
 	}
 
-	// make sure oracle isn't used by spot market
-	const filteredDelistedOracles = [];
-	for (const delistedOracle of delistedOracles) {
-		let isUsedBySpotMarket = false;
-		for (const spotMarket of spotMarkets) {
-			if (!spotMarket || !spotMarket.data) {
-				continue;
-			}
-
-			const delistedOracleId = getOracleId(
-				delistedOracle.publicKey,
-				delistedOracle.source
-			);
-			const spotMarketOracleId = getOracleId(
-				spotMarket.data.oracle,
-				spotMarket.data.oracleSource
-			);
-			if (spotMarketOracleId === delistedOracleId) {
-				isUsedBySpotMarket = true;
-				break;
-			}
+	// make sure oracle isn't still used by a spot market or a live perp market
+	const liveOracleIds = new Set<string>();
+	for (const spotMarket of spotMarkets) {
+		if (!spotMarket || !spotMarket.data) {
+			continue;
 		}
-
-		if (!isUsedBySpotMarket) {
-			filteredDelistedOracles.push(delistedOracle);
+		liveOracleIds.add(
+			getOracleId(spotMarket.data.oracle, spotMarket.data.oracleSource)
+		);
+	}
+	for (const perpMarket of perpMarkets) {
+		if (!perpMarket || !perpMarket.data) {
+			continue;
+		}
+		if (!isVariant(perpMarket.data.status, 'delisted')) {
+			liveOracleIds.add(
+				getOracleId(perpMarket.data.oracle, perpMarket.data.oracleSource)
+			);
 		}
 	}
 
+	const filteredDelistedOracles = delistedOracles.filter(
+		(delistedOracle) =>
+			!liveOracleIds.has(
+				getOracleId(delistedOracle.publicKey, delistedOracle.source)
+			)
+	);
+
 	return {
 		perpMarketIndexes: delistedPerpMarketIndexes,
 		oracles: filteredDelistedOracles,

package/src/accounts/webSocketAccountSubscriber.ts

@@ -9,6 +9,16 @@ import { AccountInfo, Commitment, Context, PublicKey } from '@solana/web3.js';
 import { VelocityProgram } from '../config';
 import * as Buffer from 'buffer';
 
+/**
+ * Default `AccountSubscriber` implementation: tracks a single account via
+ * `connection.onAccountChange`, decoding each notification with either a supplied
+ * `decodeBuffer` function or the program's Anchor coder for `accountName`. Updates are applied
+ * only when the notification's slot is not older than the last-seen slot and the raw buffer
+ * actually changed, so `onChange` never fires twice for the same bytes. If `resubOpts.resubTimeoutMs`
+ * is set, a watchdog timer resubscribes to the WebSocket whenever no notification arrives within
+ * that window — see `ResubOpts` for tuning. This is the base class extended by
+ * `grpcAccountSubscriber` for gRPC Geyser-backed tracking.
+ */
 export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 	dataAndSlot?: DataAndSlot<T>;
 	bufferAndSlot?: BufferAndSlot;
@@ -38,6 +48,14 @@ export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 
 	receivingData: boolean;
 
+	/**
+	 * @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 commitment Commitment for both the initial fetch and the `onAccountChange` subscription; defaults to the provider's configured commitment.
+	 */
 	public constructor(
 		accountName: string,
 		program: VelocityProgram,
@@ -65,6 +83,12 @@ export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 			commitment ?? (this.program.provider as AnchorProvider).opts.commitment;
 	}
 
+	/**
+	 * Seeds `dataAndSlot` with an initial `fetch()` (if not already set via `setData`) and then
+	 * attaches the `onAccountChange` WebSocket listener. Returning early (no-op) if already
+	 * subscribed or mid-unsubscribe.
+	 * @param onChange Invoked with the newly decoded account data on each accepted update.
+	 */
 	async subscribe(onChange: (data: T) => void): Promise<void> {
 		if (this.listenerId != null || this.isUnsubscribing) {
 			if (this.resubOpts?.logResubMessages) {
@@ -101,6 +125,12 @@ export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 		}
 	}
 
+	/**
+	 * Seeds or overwrites `dataAndSlot` directly, bypassing RPC. A no-op if the currently cached
+	 * slot is already newer than `slot`.
+	 * @param data Decoded account data to store.
+	 * @param slot Slot the data was observed at; defaults to 0 (the seeded sentinel) if omitted.
+	 */
 	setData(data: T, slot?: number): void {
 		const newSlot = slot || 0;
 		if (this.dataAndSlot && this.dataAndSlot.slot > newSlot) {
@@ -155,6 +185,7 @@ export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 		);
 	}
 
+	/** Fetches the account once via `getAccountInfoAndContext` and routes the result through `handleRpcResponse`, applying it if newer than the cached slot. */
 	async fetch(): Promise<void> {
 		const rpcResponse =
 			await this.program.provider.connection.getAccountInfoAndContext(
@@ -167,6 +198,11 @@ export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 		);
 	}
 
+	/**
+	 * Applies a raw RPC/WS response: decodes and stores it (updating `bufferAndSlot`/`dataAndSlot`
+	 * and invoking `onChange`) only if the slot is not older than the cached one and the buffer's
+	 * bytes actually changed (or this is the first observation).
+	 */
 	handleRpcResponse(context: Context, accountInfo?: AccountInfo<Buffer>): void {
 		const newSlot = context.slot;
 		let newBuffer: Buffer | undefined = undefined;
@@ -209,6 +245,7 @@ export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 		}
 	}
 
+	/** Decodes a raw account buffer using the constructor-supplied `decodeBufferFn`, or the program's Anchor coder for `accountName` if none was supplied. */
 	decodeBuffer(buffer: Buffer): T {
 		if (this.decodeBufferFn) {
 			return this.decodeBufferFn(buffer);
@@ -217,6 +254,10 @@ export class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
 		}
 	}
 
+	/**
+	 * Tears down the WebSocket listener 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.
+	 */
 	unsubscribe(onResub = false): Promise<void> {
 		if (!onResub && this.resubOpts) {
 			this.resubOpts.resubTimeoutMs = undefined;

package/src/accounts/webSocketAccountSubscriberV2.ts

@@ -209,20 +209,15 @@ export class WebSocketAccountSubscriberV2<T> implements AccountSubscriber<T> {
 		}
 	}
 
+	/**
+	 * Seeds `dataAndSlot` with an initial `fetch()` (if not already set via `setData`), then opens
+	 * the `gill` `accountNotifications` WebSocket subscription and, if `resubOpts.resubTimeoutMs`
+	 * is set, arms the inactivity watchdog (`setTimeout`). Idempotent: a no-op if already
+	 * subscribed or mid-unsubscribe.
+	 * @param onChange Invoked with the newly decoded account data on each accepted update.
+	 * @throws Error if `accountPublicKey` is not a valid address per `gill`'s `isAddress`.
+	 */
 	async subscribe(onChange: (data: T) => void): Promise<void> {
-		/**
-		 * Start the WebSocket subscription and (optionally) setup inactivity
-		 * fallback.
-		 *
-		 * Flow
-		 * - If we do not have initial state, perform a one-time `fetch()` to seed
-		 *   internal buffers and emit current data.
-		 * - Subscribe to account notifications via WS.
-		 * - If `resubOpts.resubTimeoutMs` is set, schedule an inactivity timeout.
-		 *   When it fires:
-		 *   - if `usePollingInsteadOfResub` is true, start polling loop;
-		 *   - otherwise, resubscribe to WS immediately.
-		 */
 		if (this.listenerId != null || this.isUnsubscribing) {
 			if (this.resubOpts.logResubMessages) {
 				console.log(
@@ -267,6 +262,12 @@ export class WebSocketAccountSubscriberV2<T> implements AccountSubscriber<T> {
 		}
 	}
 
+	/**
+	 * Seeds or overwrites `dataAndSlot` directly, bypassing RPC. A no-op if the currently cached
+	 * slot is already newer than `slot`.
+	 * @param data Decoded account data to store.
+	 * @param slot Slot the data was observed at; defaults to 0 (the seeded sentinel) if omitted.
+	 */
 	setData(data: T, slot?: number): void {
 		const newSlot = slot || 0;
 		if (this.dataAndSlot && this.dataAndSlot.slot > newSlot) {
@@ -279,12 +280,13 @@ export class WebSocketAccountSubscriberV2<T> implements AccountSubscriber<T> {
 		};
 	}
 
+	/**
+	 * Arms the inactivity watchdog: if no WS notification resets this timeout within
+	 * `resubOpts.resubTimeoutMs`, either starts the polling fallback (`usePollingInsteadOfResub`)
+	 * or tears down and recreates the WS subscription. Throws if `onChange` was never set (i.e.
+	 * called outside `subscribe()`'s flow).
+	 */
 	protected setTimeout(): void {
-		/**
-		 * Schedule inactivity handling. If WS is quiet for
-		 * `resubOpts.resubTimeoutMs` and `receivingData` is true, trigger either
-		 * a polling loop or a resubscribe depending on options.
-		 */
 		if (!this._onChange) {
 			throw new Error('onChange callback function must be set');
 		}
@@ -428,6 +430,11 @@ export class WebSocketAccountSubscriberV2<T> implements AccountSubscriber<T> {
 		);
 	}
 
+	/**
+	 * Applies a raw `gill` RPC/WS response: decodes (base58 or base64) and stores it (updating
+	 * `bufferAndSlot`/`dataAndSlot` and invoking `onChange`) only if the slot is not older than
+	 * the cached one and the buffer's bytes actually changed (or this is the first observation).
+	 */
 	handleRpcResponse(
 		context: { slot: bigint },
 		accountInfo?: AccountInfoBase &
@@ -490,6 +497,7 @@ export class WebSocketAccountSubscriberV2<T> implements AccountSubscriber<T> {
 		}
 	}
 
+	/** Decodes a raw account buffer using the constructor-supplied `decodeBufferFn`, or the program's Anchor coder for `accountName` if none was supplied. */
 	decodeBuffer(buffer: Buffer): T {
 		if (this.decodeBufferFn) {
 			return this.decodeBufferFn(buffer);
@@ -498,12 +506,12 @@ export class WebSocketAccountSubscriberV2<T> implements AccountSubscriber<T> {
 		}
 	}
 
+	/**
+	 * Tears down the WebSocket subscription (via `abortController`) and cancels any pending resub
+	 * timeout and in-progress polling.
+	 * @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.
+	 */
 	unsubscribe(onResub = false): Promise<void> {
-		/**
-		 * Stop timers, polling, and WS subscription.
-		 * - When called during a resubscribe (`onResub=true`), we preserve
-		 *   `resubOpts.resubTimeoutMs` for the restarted subscription.
-		 */
 		if (!onResub && this.resubOpts) {
 			this.resubOpts.resubTimeoutMs = undefined;
 		}