@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/accounts/webSocketInsuranceFundStakeAccountSubscriber.ts

@@ -12,6 +12,12 @@ import { WebSocketAccountSubscriber } from './webSocketAccountSubscriber';
 import { InsuranceFundStake } from '../types';
 import { VelocityProgram } from '../config';
 
+/**
+ * Default `InsuranceFundStakeAccountSubscriber` implementation: wraps a single
+ * `WebSocketAccountSubscriber` for the `InsuranceFundStake` account, mirroring
+ * `WebSocketUserAccountSubscriber`. `insuranceFundStakeDataAccountSubscriber` throws if accessed
+ * before `subscribe()` has run.
+ */
 export class WebSocketInsuranceFundStakeAccountSubscriber
 	implements InsuranceFundStakeAccountSubscriber
 {
@@ -40,6 +46,12 @@ export class WebSocketInsuranceFundStakeAccountSubscriber
 		this._insuranceFundStakeDataAccountSubscriber = subscriber;
 	}
 
+	/**
+	 * @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 through as `ResubOpts.resubTimeoutMs` to the underlying `WebSocketAccountSubscriber`. Unlike other subscribers here, only this single option is exposed (not the full `ResubOpts` shape).
+	 * @param commitment Commitment for the underlying subscription; defaults to the provider's configured commitment.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		insuranceFundStakeAccountPublicKey: PublicKey,
@@ -55,6 +67,11 @@ export class WebSocketInsuranceFundStakeAccountSubscriber
 		this.commitment = commitment;
 	}
 
+	/**
+	 * Creates the underlying `WebSocketAccountSubscriber` 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> {
@@ -92,10 +109,12 @@ export class WebSocketInsuranceFundStakeAccountSubscriber
 		return true;
 	}
 
+	/** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
 	async fetch(): Promise<void> {
 		await Promise.all([this.insuranceFundStakeDataAccountSubscriber.fetch()]);
 	}
 
+	/** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
 	async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -108,6 +127,7 @@ export class WebSocketInsuranceFundStakeAccountSubscriber
 		this.isSubscribed = false;
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -116,6 +136,7 @@ export class WebSocketInsuranceFundStakeAccountSubscriber
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
 	public getInsuranceFundStakeAccountAndSlot():
 		| DataAndSlot<InsuranceFundStake>
 		| undefined {
@@ -123,6 +144,12 @@ export class WebSocketInsuranceFundStakeAccountSubscriber
 		return this.insuranceFundStakeDataAccountSubscriber.dataAndSlot;
 	}
 
+	/**
+	 * Applies an externally-obtained account update if `slot` is not older than the currently
+	 * cached slot.
+	 * @param insuranceFundStake Decoded account data to apply.
+	 * @param slot Slot the data was observed at.
+	 */
 	public updateData(
 		insuranceFundStake: InsuranceFundStake,
 		slot: number

package/src/accounts/webSocketProgramAccountSubscriber.ts

@@ -10,6 +10,18 @@ import {
 import { VelocityProgram } from '../config';
 import * as Buffer from 'buffer';
 
+/**
+ * Default `ProgramAccountSubscriber` implementation: tracks every account owned by the program
+ * (optionally narrowed by `options.filters`) via `connection.onProgramAccountChange`, decoding
+ * each notification with `decodeBufferFn`. Maintains a per-account (not single, unlike
+ * `WebSocketAccountSubscriber`) `bufferAndSlotMap`, since one program subscription covers many
+ * accounts; updates are applied per-account only when the notification's slot is not older than
+ * that account's last-seen slot and its buffer actually changed. If `resubOpts.resubTimeoutMs`
+ * is set, a watchdog timer resubscribes the whole program subscription whenever no notification
+ * (for *any* account) arrives within that window. This is the base class extended by
+ * `grpcProgramAccountSubscriber` and `LaserstreamProgramAccountSubscriber` for gRPC Geyser-backed
+ * tracking.
+ */
 export class WebSocketProgramAccountSubscriber<T>
 	implements ProgramAccountSubscriber<T>
 {
@@ -54,6 +66,14 @@ export class WebSocketProgramAccountSubscriber<T>
 
 	receivingData = false;
 
+	/**
+	 * @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 watch (filtered to `program.programId` as owner).
+	 * @param decodeBufferFn Decode function for each account's raw buffer.
+	 * @param options `filters` narrowing which program accounts are watched (empty watches every account owned by the program); `commitment` for the subscription, defaulting to the provider's configured commitment.
+	 * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+	 */
 	public constructor(
 		subscriptionName: string,
 		accountDiscriminator: string,
@@ -81,6 +101,12 @@ export class WebSocketProgramAccountSubscriber<T>
 		this.receivingData = false;
 	}
 
+	/**
+	 * Attaches the `onProgramAccountChange` WebSocket listener. Idempotent: a no-op if already
+	 * subscribed or mid-unsubscribe. Does not perform an initial fetch of matching accounts — the
+	 * caller must fetch any pre-existing 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,
@@ -144,6 +170,12 @@ export class WebSocketProgramAccountSubscriber<T>
 		);
 	}
 
+	/**
+	 * Applies a raw notification for one account within the program subscription: decodes and
+	 * stores it (updating that account's entry in `bufferAndSlotMap` and invoking `onChange`) only
+	 * if the slot is not older than the cached one for that specific account and the buffer's
+	 * bytes actually changed (or this is the first observation of that account).
+	 */
 	handleRpcResponse(
 		context: Context,
 		keyedAccountInfo: KeyedAccountInfo
@@ -184,6 +216,10 @@ export class WebSocketProgramAccountSubscriber<T>
 		}
 	}
 
+	/**
+	 * Tears down the `onProgramAccountChange` 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/webSocketProgramAccountSubscriberV2.ts

@@ -161,6 +161,15 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 	private resubscriptionTimeout?: ReturnType<typeof setTimeout>; // Timeout for delayed resubscription
 	private accountsWithMissedUpdates: Set<string> = new Set(); // Track which accounts had missed updates
 
+	/**
+	 * @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 watch (filtered to `program.programId` as owner); its connection's RPC endpoint is reused to build the `gill` client.
+	 * @param decodeBufferFn Decode function for each account's raw buffer.
+	 * @param options `filters` narrowing which program accounts are watched; `commitment` for the WS subscription and RPC polls.
+	 * @param resubOpts Resubscription/polling options; defaults to `{ resubTimeoutMs: 30000, usePollingInsteadOfResub: true }` if omitted (stricter than the v1 `WebSocketProgramAccountSubscriber`, which defaults to no watchdog at all).
+	 * @param accountsToMonitor Initial set of accounts to apply the polling safeguard to; more can be added later via `addAccountToMonitor`.
+	 */
 	public constructor(
 		subscriptionName: string,
 		accountDiscriminator: string,
@@ -377,6 +386,13 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 		);
 	}
 
+	/**
+	 * Applies a raw notification (or polled response) for one account: decodes and stores it
+	 * (updating that account's entry in `bufferAndSlotMap` and invoking `onChange`) only if the
+	 * slot is not older than the cached one for that specific account and the buffer's bytes
+	 * actually changed. Also records the WS notification time and, if this account was in the
+	 * polling set, removes it from polling now that a fresh WS update arrived.
+	 */
 	handleRpcResponse(
 		context: { slot: bigint },
 		accountId: Address,
@@ -932,6 +948,10 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 		}
 	}
 
+	/**
+	 * Tears down all polling timeouts and aborts the WebSocket subscription.
+	 * @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.resubTimeoutMs = undefined;
@@ -972,6 +992,7 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 	}
 
 	// Method to remove accounts from the polling list
+	/** Removes an account from the monitored set and clears any pending/active polling state for it. */
 	removeAccountFromMonitor(accountId: PublicKey): void {
 		const accountIdString = accountId.toBase58();
 		this.accountsToMonitor.delete(accountIdString);
@@ -986,6 +1007,11 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 		// Remove from currently polling set if it was being polled
 		this.accountsCurrentlyPolling.delete(accountIdString);
 
+		// Clear stale monitoring bookkeeping so a re-added pubkey isn't mistaken for
+		// having a recent WS notification or a still-pending missed update.
+		this.lastWsNotificationTime.delete(accountIdString);
+		this.accountsWithMissedUpdates.delete(accountIdString);
+
 		// If no more accounts are being polled, stop batch polling
 		if (this.accountsCurrentlyPolling.size === 0 && this.batchPollingTimeout) {
 			clearTimeout(this.batchPollingTimeout);

package/src/accounts/webSocketProgramAccountsSubscriberV2.ts

@@ -161,6 +161,15 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 	private resubscriptionTimeout?: ReturnType<typeof setTimeout>; // Timeout for delayed resubscription
 	private accountsWithMissedUpdates: Set<string> = new Set(); // Track which accounts had missed updates
 
+	/**
+	 * @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 watch (filtered to `program.programId` as owner); its connection's RPC endpoint is reused to build the `gill` client.
+	 * @param decodeBufferFn Decode function for each account's raw buffer.
+	 * @param options `filters` narrowing which program accounts are watched; `commitment` for the WS subscription and RPC polls.
+	 * @param resubOpts Resubscription/polling options; defaults to `{ resubTimeoutMs: 30000, usePollingInsteadOfResub: true }` if omitted (stricter than the v1 `WebSocketProgramAccountSubscriber`, which defaults to no watchdog at all).
+	 * @param accountsToMonitor Initial set of accounts to apply the polling safeguard to; more can be added later via `addAccountToMonitor`.
+	 */
 	public constructor(
 		subscriptionName: string,
 		accountDiscriminator: string,
@@ -377,6 +386,13 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 		);
 	}
 
+	/**
+	 * Applies a raw notification (or polled response) for one account: decodes and stores it
+	 * (updating that account's entry in `bufferAndSlotMap` and invoking `onChange`) only if the
+	 * slot is not older than the cached one for that specific account and the buffer's bytes
+	 * actually changed. Also records the WS notification time and, if this account was in the
+	 * polling set, removes it from polling now that a fresh WS update arrived.
+	 */
 	handleRpcResponse(
 		context: { slot: bigint },
 		accountId: Address,
@@ -931,6 +947,10 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 		}
 	}
 
+	/**
+	 * Tears down all polling timeouts and aborts the WebSocket subscription.
+	 * @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.resubTimeoutMs = undefined;
@@ -971,6 +991,7 @@ export class WebSocketProgramAccountsSubscriberV2<T>
 	}
 
 	// Method to remove accounts from the polling list
+	/** Removes an account from the monitored set and clears any pending/active polling state for it. */
 	removeAccountFromMonitor(accountId: PublicKey): void {
 		const accountIdString = accountId.toBase58();
 		this.accountsToMonitor.delete(accountIdString);

package/src/accounts/webSocketUserAccountSubscriber.ts

@@ -13,6 +13,11 @@ import { Commitment, PublicKey } from '@solana/web3.js';
 import { WebSocketAccountSubscriber } from './webSocketAccountSubscriber';
 import { UserAccount } from '../types';
 
+/**
+ * Default `UserAccountSubscriber` implementation: wraps a single `WebSocketAccountSubscriber`
+ * for the `UserAccount`. `userDataAccountSubscriber` throws if accessed before `subscribe()` has
+ * run (it is created there, not in the constructor).
+ */
 export class WebSocketUserAccountSubscriber implements UserAccountSubscriber {
 	isSubscribed: boolean;
 	resubOpts?: ResubOpts;
@@ -32,6 +37,12 @@ export class WebSocketUserAccountSubscriber implements UserAccountSubscriber {
 		this._userDataAccountSubscriber = subscriber;
 	}
 
+	/**
+	 * @param program Anchor program providing the connection and coder.
+	 * @param userAccountPublicKey Address of the `UserAccount` to track.
+	 * @param resubOpts Resubscription watchdog options passed through to the underlying `WebSocketAccountSubscriber`.
+	 * @param commitment Commitment for the underlying subscription; defaults to the provider's configured commitment.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		userAccountPublicKey: PublicKey,
@@ -46,6 +57,11 @@ export class WebSocketUserAccountSubscriber implements UserAccountSubscriber {
 		this.commitment = commitment;
 	}
 
+	/**
+	 * Creates the underlying `WebSocketAccountSubscriber` 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;
@@ -74,10 +90,12 @@ export class WebSocketUserAccountSubscriber implements UserAccountSubscriber {
 		return true;
 	}
 
+	/** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
 	async fetch(): Promise<void> {
 		await Promise.all([this.userDataAccountSubscriber.fetch()]);
 	}
 
+	/** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
 	async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -88,6 +106,7 @@ export class WebSocketUserAccountSubscriber implements UserAccountSubscriber {
 		this.isSubscribed = false;
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -96,11 +115,18 @@ export class WebSocketUserAccountSubscriber 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.userDataAccountSubscriber.dataAndSlot;
 	}
 
+	/**
+	 * Applies an externally-obtained account update if `slot` is not older than the currently
+	 * cached slot.
+	 * @param userAccount Decoded account data to apply.
+	 * @param slot Slot the data was observed at.
+	 */
 	public updateData(userAccount: UserAccount, slot: number) {
 		const currentDataSlot =
 			this.userDataAccountSubscriber.dataAndSlot?.slot || 0;

package/src/accounts/webSocketUserStatsAccountSubsriber.ts

@@ -13,6 +13,11 @@ import { Commitment, PublicKey } from '@solana/web3.js';
 import { WebSocketAccountSubscriber } from './webSocketAccountSubscriber';
 import { UserStatsAccount } from '../types';
 
+/**
+ * Default `UserStatsAccountSubscriber` implementation: wraps a single `WebSocketAccountSubscriber`
+ * for the `UserStatsAccount`, mirroring `WebSocketUserAccountSubscriber`.
+ * `userStatsAccountSubscriber` throws if accessed before `subscribe()` has run.
+ */
 export class WebSocketUserStatsAccountSubscriber
 	implements UserStatsAccountSubscriber
 {
@@ -36,6 +41,12 @@ export class WebSocketUserStatsAccountSubscriber
 		this._userStatsAccountSubscriber = subscriber;
 	}
 
+	/**
+	 * @param program Anchor program providing the connection and coder.
+	 * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+	 * @param resubOpts Resubscription watchdog options passed through to the underlying `WebSocketAccountSubscriber`.
+	 * @param commitment Commitment for the underlying subscription; defaults to the provider's configured commitment.
+	 */
 	public constructor(
 		program: VelocityProgram,
 		userStatsAccountPublicKey: PublicKey,
@@ -50,6 +61,11 @@ export class WebSocketUserStatsAccountSubscriber
 		this.commitment = commitment;
 	}
 
+	/**
+	 * Creates the underlying `WebSocketAccountSubscriber` 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;
@@ -80,10 +96,12 @@ export class WebSocketUserStatsAccountSubscriber
 		return true;
 	}
 
+	/** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
 	async fetch(): Promise<void> {
 		await Promise.all([this.userStatsAccountSubscriber.fetch()]);
 	}
 
+	/** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
 	async unsubscribe(): Promise<void> {
 		if (!this.isSubscribed) {
 			return;
@@ -94,6 +112,7 @@ export class WebSocketUserStatsAccountSubscriber
 		this.isSubscribed = false;
 	}
 
+	/** Throws `NotSubscribedError` if `subscribe()` has not been called. */
 	assertIsSubscribed(): void {
 		if (!this.isSubscribed) {
 			throw new NotSubscribedError(
@@ -102,6 +121,7 @@ export class WebSocketUserStatsAccountSubscriber
 		}
 	}
 
+	/** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
 	public getUserStatsAccountAndSlot():
 		| DataAndSlot<UserStatsAccount>
 		| undefined {