@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/accounts/webSocketAccountSubscriberV2.js

@@ -138,20 +138,15 @@ class WebSocketAccountSubscriberV2 {
             this.setTimeout();
         }
     }
+    /**
+     * 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) {
-        /**
-         * 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(`[${this.logAccountName}] Subscribe returning early - listenerId=${this.listenerId}, isUnsubscribing=${this.isUnsubscribing}`);
@@ -188,6 +183,12 @@ class WebSocketAccountSubscriberV2 {
             throw new Error('Invalid account public key');
         }
     }
+    /**
+     * 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, slot) {
         const newSlot = slot || 0;
         if (this.dataAndSlot && this.dataAndSlot.slot > newSlot) {
@@ -198,12 +199,13 @@ class WebSocketAccountSubscriberV2 {
             slot: newSlot,
         };
     }
+    /**
+     * 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).
+     */
     setTimeout() {
-        /**
-         * 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');
         }
@@ -317,6 +319,11 @@ class WebSocketAccountSubscriberV2 {
         const accountInfo = rpcResponse.value;
         this.handleRpcResponse({ slot: BigInt(context.slot) }, accountInfo !== null && accountInfo !== void 0 ? accountInfo : undefined);
     }
+    /**
+     * 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, accountInfo) {
         const newSlot = context.slot;
         let newBuffer = undefined;
@@ -370,6 +377,7 @@ class WebSocketAccountSubscriberV2 {
             this.onChange(account);
         }
     }
+    /** Decodes a raw account buffer using the constructor-supplied `decodeBufferFn`, or the program's Anchor coder for `accountName` if none was supplied. */
     decodeBuffer(buffer) {
         if (this.decodeBufferFn) {
             return this.decodeBufferFn(buffer);
@@ -378,12 +386,12 @@ class WebSocketAccountSubscriberV2 {
             return this.program.coder.accounts.decode(this.accountName, buffer);
         }
     }
+    /**
+     * 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) {
-        /**
-         * 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;
         }

package/lib/browser/accounts/webSocketInsuranceFundStakeAccountSubscriber.d.ts

@@ -5,6 +5,12 @@ import { EventEmitter } from 'events';
 import { Commitment, PublicKey } from '@solana/web3.js';
 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 declare class WebSocketInsuranceFundStakeAccountSubscriber implements InsuranceFundStakeAccountSubscriber {
     isSubscribed: boolean;
     resubTimeoutMs?: number;
@@ -15,11 +21,32 @@ export declare class WebSocketInsuranceFundStakeAccountSubscriber implements Ins
     private _insuranceFundStakeDataAccountSubscriber?;
     get insuranceFundStakeDataAccountSubscriber(): AccountSubscriber<InsuranceFundStake>;
     set insuranceFundStakeDataAccountSubscriber(subscriber: AccountSubscriber<InsuranceFundStake>);
+    /**
+     * @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.
+     */
     constructor(program: VelocityProgram, insuranceFundStakeAccountPublicKey: PublicKey, resubTimeoutMs?: number, 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.
+     */
     subscribe(insuranceFundStakeAccount?: InsuranceFundStake): Promise<boolean>;
+    /** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
     fetch(): Promise<void>;
+    /** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed(): void;
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
     getInsuranceFundStakeAccountAndSlot(): DataAndSlot<InsuranceFundStake> | undefined;
+    /**
+     * 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.
+     */
     updateData(insuranceFundStake: InsuranceFundStake, slot: number): void;
 }

package/lib/browser/accounts/webSocketInsuranceFundStakeAccountSubscriber.js

@@ -4,6 +4,12 @@ exports.WebSocketInsuranceFundStakeAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
 const webSocketAccountSubscriber_1 = require("./webSocketAccountSubscriber");
+/**
+ * Default `InsuranceFundStakeAccountSubscriber` implementation: wraps a single
+ * `WebSocketAccountSubscriber` for the `InsuranceFundStake` account, mirroring
+ * `WebSocketUserAccountSubscriber`. `insuranceFundStakeDataAccountSubscriber` throws if accessed
+ * before `subscribe()` has run.
+ */
 class WebSocketInsuranceFundStakeAccountSubscriber {
     get insuranceFundStakeDataAccountSubscriber() {
         if (!this._insuranceFundStakeDataAccountSubscriber) {
@@ -14,6 +20,12 @@ class WebSocketInsuranceFundStakeAccountSubscriber {
     set insuranceFundStakeDataAccountSubscriber(subscriber) {
         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.
+     */
     constructor(program, insuranceFundStakeAccountPublicKey, resubTimeoutMs, commitment) {
         this.isSubscribed = false;
         this.program = program;
@@ -23,6 +35,11 @@ class WebSocketInsuranceFundStakeAccountSubscriber {
         this.resubTimeoutMs = resubTimeoutMs;
         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) {
         if (this.isSubscribed) {
             return true;
@@ -42,9 +59,11 @@ class WebSocketInsuranceFundStakeAccountSubscriber {
         this.isSubscribed = true;
         return true;
     }
+    /** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
     async fetch() {
         await Promise.all([this.insuranceFundStakeDataAccountSubscriber.fetch()]);
     }
+    /** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -54,15 +73,23 @@ class WebSocketInsuranceFundStakeAccountSubscriber {
         ]);
         this.isSubscribed = false;
     }
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed() {
         if (!this.isSubscribed) {
             throw new types_1.NotSubscribedError('You must call `subscribe` before using this function');
         }
     }
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
     getInsuranceFundStakeAccountAndSlot() {
         this.assertIsSubscribed();
         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.
+     */
     updateData(insuranceFundStake, slot) {
         var _a;
         const currentDataSlot = ((_a = this.insuranceFundStakeDataAccountSubscriber.dataAndSlot) === null || _a === void 0 ? void 0 : _a.slot) || 0;

package/lib/browser/accounts/webSocketProgramAccountSubscriber.d.ts

@@ -3,6 +3,18 @@
 import { BufferAndSlot, ProgramAccountSubscriber, ResubOpts } from './types';
 import { Commitment, Context, KeyedAccountInfo, MemcmpFilter, PublicKey } from '@solana/web3.js';
 import { VelocityProgram } from '../config';
+/**
+ * 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 declare class WebSocketProgramAccountSubscriber<T> implements ProgramAccountSubscriber<T> {
     subscriptionName: string;
     accountDiscriminator: string;
@@ -22,12 +34,36 @@ export declare class WebSocketProgramAccountSubscriber<T> implements ProgramAcco
         commitment?: Commitment;
     };
     receivingData: boolean;
+    /**
+     * @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.
+     */
     constructor(subscriptionName: string, accountDiscriminator: string, program: VelocityProgram, decodeBufferFn: (accountName: string, ix: Buffer) => T, options?: {
         filters: MemcmpFilter[];
         commitment?: Commitment;
     }, resubOpts?: ResubOpts);
+    /**
+     * 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.
+     */
     subscribe(onChange: (accountId: PublicKey, data: T, context: Context, buffer: Buffer) => void): Promise<void>;
     protected setTimeout(): void;
+    /**
+     * 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): void;
+    /**
+     * 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?: boolean): Promise<void>;
 }

package/lib/browser/accounts/webSocketProgramAccountSubscriber.js

@@ -1,6 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocketProgramAccountSubscriber = void 0;
+/**
+ * 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.
+ */
 class WebSocketProgramAccountSubscriber {
     get onChange() {
         if (!this._onChange) {
@@ -11,6 +23,14 @@ class WebSocketProgramAccountSubscriber {
     set onChange(onChange) {
         this._onChange = onChange;
     }
+    /**
+     * @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.
+     */
     constructor(subscriptionName, accountDiscriminator, program, decodeBufferFn, options = {
         filters: [],
     }, resubOpts) {
@@ -30,6 +50,12 @@ class WebSocketProgramAccountSubscriber {
         this.options = options;
         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) {
         var _a, _b;
         if (this.listenerId != null || this.isUnsubscribing) {
@@ -74,6 +100,12 @@ class WebSocketProgramAccountSubscriber {
             }
         }, (_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.resubTimeoutMs);
     }
+    /**
+     * 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, keyedAccountInfo) {
         const newSlot = context.slot;
         let newBuffer = undefined;
@@ -106,6 +138,10 @@ class WebSocketProgramAccountSubscriber {
             this.onChange(keyedAccountInfo.accountId, account, context, newBuffer);
         }
     }
+    /**
+     * 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) {
         if (!onResub && this.resubOpts) {
             this.resubOpts.resubTimeoutMs = undefined;

package/lib/browser/accounts/webSocketProgramAccountSubscriberV2.d.ts

@@ -95,6 +95,15 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
     private missedChangeDetected;
     private resubscriptionTimeout?;
     private accountsWithMissedUpdates;
+    /**
+     * @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`.
+     */
     constructor(subscriptionName: string, accountDiscriminator: string, program: VelocityProgram, decodeBufferFn: (accountName: string, ix: Buffer) => T, options?: {
         filters: MemcmpFilter[];
         commitment?: Commitment;
@@ -102,6 +111,13 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
     private handleNotificationLoop;
     subscribe(onChange: (accountId: PublicKey, data: T, context: Context, buffer: Buffer) => void): Promise<void>;
     protected setTimeout(): void;
+    /**
+     * 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, accountInfo?: AccountInfoBase & (AccountInfoWithBase58EncodedData | AccountInfoWithBase64EncodedData)['data']): void;
@@ -130,6 +146,10 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
      * Signal that a missed change was detected and schedule resubscription
      */
     private signalMissedChange;
+    /**
+     * 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?: boolean): Promise<void>;
     /**
      * Add an account to the monitored set.
@@ -137,6 +157,7 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
      *   if WS notifications are not observed within `pollingIntervalMs`.
      */
     addAccountToMonitor(accountId: PublicKey): void;
+    /** Removes an account from the monitored set and clears any pending/active polling state for it. */
     removeAccountFromMonitor(accountId: PublicKey): void;
     /**
      * Set the monitoring/polling interval for monitored accounts.

package/lib/browser/accounts/webSocketProgramAccountSubscriberV2.js

@@ -76,6 +76,15 @@ class WebSocketProgramAccountsSubscriberV2 {
     set onChange(onChange) {
         this._onChange = onChange;
     }
+    /**
+     * @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`.
+     */
     constructor(subscriptionName, accountDiscriminator, program, decodeBufferFn, options = {
         filters: [],
     }, resubOpts, accountsToMonitor // Optional list of accounts to poll
@@ -249,6 +258,13 @@ class WebSocketProgramAccountsSubscriberV2 {
             }
         }, (_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.resubTimeoutMs);
     }
+    /**
+     * 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, accountId, accountInfo) {
         const newSlot = Number(context.slot);
         let newBuffer = undefined;
@@ -681,6 +697,10 @@ class WebSocketProgramAccountsSubscriberV2 {
             this.accountsWithMissedUpdates.add(accountIdString);
         }
     }
+    /**
+     * 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) {
         if (!onResub) {
             this.resubOpts.resubTimeoutMs = undefined;
@@ -714,6 +734,7 @@ class WebSocketProgramAccountsSubscriberV2 {
         }
     }
     // 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) {
         const accountIdString = accountId.toBase58();
         this.accountsToMonitor.delete(accountIdString);
@@ -725,6 +746,10 @@ class WebSocketProgramAccountsSubscriberV2 {
         }
         // 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/lib/browser/accounts/webSocketProgramAccountsSubscriberV2.d.ts

@@ -95,6 +95,15 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
     private missedChangeDetected;
     private resubscriptionTimeout?;
     private accountsWithMissedUpdates;
+    /**
+     * @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`.
+     */
     constructor(subscriptionName: string, accountDiscriminator: string, program: VelocityProgram, decodeBufferFn: (accountName: string, ix: Buffer) => T, options?: {
         filters: MemcmpFilter[];
         commitment?: Commitment;
@@ -102,6 +111,13 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
     private handleNotificationLoop;
     subscribe(onChange: (accountId: PublicKey, data: T, context: Context, buffer: Buffer) => void): Promise<void>;
     protected setTimeout(): void;
+    /**
+     * 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, accountInfo?: AccountInfoBase & (AccountInfoWithBase58EncodedData | AccountInfoWithBase64EncodedData)['data']): void;
@@ -130,6 +146,10 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
      * Signal that a missed change was detected and schedule resubscription
      */
     private signalMissedChange;
+    /**
+     * 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?: boolean): Promise<void>;
     /**
      * Add an account to the monitored set.
@@ -137,6 +157,7 @@ export declare class WebSocketProgramAccountsSubscriberV2<T> implements ProgramA
      *   if WS notifications are not observed within `pollingIntervalMs`.
      */
     addAccountToMonitor(accountId: PublicKey): void;
+    /** Removes an account from the monitored set and clears any pending/active polling state for it. */
     removeAccountFromMonitor(accountId: PublicKey): void;
     /**
      * Set the monitoring/polling interval for monitored accounts.

package/lib/browser/accounts/webSocketProgramAccountsSubscriberV2.js

@@ -76,6 +76,15 @@ class WebSocketProgramAccountsSubscriberV2 {
     set onChange(onChange) {
         this._onChange = onChange;
     }
+    /**
+     * @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`.
+     */
     constructor(subscriptionName, accountDiscriminator, program, decodeBufferFn, options = {
         filters: [],
     }, resubOpts, accountsToMonitor // Optional list of accounts to poll
@@ -248,6 +257,13 @@ class WebSocketProgramAccountsSubscriberV2 {
             }
         }, (_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.resubTimeoutMs);
     }
+    /**
+     * 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, accountId, accountInfo) {
         const newSlot = Number(context.slot);
         let newBuffer = undefined;
@@ -679,6 +695,10 @@ class WebSocketProgramAccountsSubscriberV2 {
             this.accountsWithMissedUpdates.add(accountIdString);
         }
     }
+    /**
+     * 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) {
         if (!onResub) {
             this.resubOpts.resubTimeoutMs = undefined;
@@ -712,6 +732,7 @@ class WebSocketProgramAccountsSubscriberV2 {
         }
     }
     // 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) {
         const accountIdString = accountId.toBase58();
         this.accountsToMonitor.delete(accountIdString);

package/lib/browser/accounts/webSocketUserAccountSubscriber.d.ts

@@ -5,6 +5,11 @@ import StrictEventEmitter from 'strict-event-emitter-types';
 import { EventEmitter } from 'events';
 import { Commitment, PublicKey } from '@solana/web3.js';
 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 declare class WebSocketUserAccountSubscriber implements UserAccountSubscriber {
     isSubscribed: boolean;
     resubOpts?: ResubOpts;
@@ -15,11 +20,32 @@ export declare class WebSocketUserAccountSubscriber implements UserAccountSubscr
     private _userDataAccountSubscriber?;
     get userDataAccountSubscriber(): AccountSubscriber<UserAccount>;
     set userDataAccountSubscriber(subscriber: AccountSubscriber<UserAccount>);
+    /**
+     * @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.
+     */
     constructor(program: VelocityProgram, userAccountPublicKey: PublicKey, resubOpts?: ResubOpts, 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.
+     */
     subscribe(userAccount?: UserAccount): Promise<boolean>;
+    /** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
     fetch(): Promise<void>;
+    /** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed(): void;
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
     getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined;
+    /**
+     * 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.
+     */
     updateData(userAccount: UserAccount, slot: number): void;
 }