@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/accounts/laserProgramAccountSubscriber.js

@@ -28,6 +28,14 @@ const web3_js_1 = require("@solana/web3.js");
 const Buffer = __importStar(require("buffer"));
 const webSocketProgramAccountSubscriber_1 = require("./webSocketProgramAccountSubscriber");
 const grpc_1 = require("../isomorphic/grpc");
+/**
+ * `ProgramAccountSubscriber` that streams every account owned by the program (optionally filtered
+ * by `memcmp`) via Helius LaserStream instead of `connection.onProgramAccountChange`. Extends
+ * `WebSocketProgramAccountSubscriber` to reuse its per-account buffering/decode/resub-timer logic
+ * (`handleRpcResponse`, `bufferAndSlotMap`) — only the transport (`subscribe`/`unsubscribe`) is
+ * replaced. Construct via the static `create` factory, not the constructor directly, since it
+ * dynamically loads the optional `helius-laserstream` peer dependency and its enums.
+ */
 class LaserstreamProgramAccountSubscriber extends webSocketProgramAccountSubscriber_1.WebSocketProgramAccountSubscriber {
     constructor(laserConfig, commitmentLevel, laserCommitmentLevel, subscriptionName, accountDiscriminator, program, decodeBufferFn, options = { filters: [] }, resubOpts) {
         super(subscriptionName, accountDiscriminator, program, decodeBufferFn, options, resubOpts);
@@ -35,6 +43,19 @@ class LaserstreamProgramAccountSubscriber extends webSocketProgramAccountSubscri
         this.laserCommitmentLevel = laserCommitmentLevel;
         this.commitmentLevel = this.toLaserCommitment(commitmentLevel);
     }
+    /**
+     * Loads the optional `helius-laserstream` module, builds its `LaserstreamConfig` (forcing zstd
+     * compression and a 1GB max receive message size), and constructs a
+     * `LaserstreamProgramAccountSubscriber`. Does not itself start streaming — call
+     * `subscribe(onChange)` on the result.
+     * @param grpcConfigs LaserStream endpoint/token/commitment config; `enableReconnect` maps to up to 10 reconnect attempts (0 if unset).
+     * @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) 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.
+     */
     static async create(grpcConfigs, subscriptionName, accountDiscriminator, program, decodeBufferFn, options = {
         filters: [],
     }, resubOpts) {
@@ -56,6 +77,14 @@ class LaserstreamProgramAccountSubscriber extends webSocketProgramAccountSubscri
         const commitmentLevel = (_a = grpcConfigs.commitmentLevel) !== null && _a !== void 0 ? _a : grpc_1.CommitmentLevel.CONFIRMED;
         return new LaserstreamProgramAccountSubscriber(laserConfig, commitmentLevel, laserCommitmentLevel, subscriptionName, accountDiscriminator, program, decodeBufferFn, options, resubOpts);
     }
+    /**
+     * Opens a LaserStream `accounts` subscription filtered to `program.programId` as owner
+     * (further narrowed by the `filters` passed to `create`). Idempotent: a no-op if already
+     * subscribed or mid-unsubscribe. Does not perform an initial fetch — the caller must fetch any
+     * pre-existing matching accounts separately if needed. Throws if the LaserStream client fails
+     * to start.
+     * @param onChange Invoked once per changed account with its pubkey, decoded data, the notification's `Context` (slot only), and the raw buffer.
+     */
     async subscribe(onChange) {
         var _a;
         if (this.listenerId != null || this.isUnsubscribing)
@@ -134,6 +163,10 @@ class LaserstreamProgramAccountSubscriber extends webSocketProgramAccountSubscri
             throw err;
         }
     }
+    /**
+     * Cancels the LaserStream and clears 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.
+     */
     async unsubscribe(onResub = false) {
         if (!onResub && this.resubOpts) {
             this.resubOpts.resubTimeoutMs = undefined;
@@ -154,6 +187,7 @@ class LaserstreamProgramAccountSubscriber extends webSocketProgramAccountSubscri
             this.isUnsubscribing = false;
         }
     }
+    /** Coerces a commitment level (string name, numeric enum value, or undefined) into a LaserStream `LaserCommitmentLevel`, defaulting to `CONFIRMED`. */
     toLaserCommitment(level) {
         var _a, _b;
         if (typeof level === 'string') {

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

@@ -11,8 +11,27 @@ import { VelocityProgram } from '../config';
 export declare class OneShotUserAccountSubscriber extends BasicUserAccountSubscriber implements UserAccountSubscriber {
     program: VelocityProgram;
     commitment: Commitment;
+    /**
+     * @param program Anchor program used for the one-off `fetchAndContext` call.
+     * @param userAccountPublicKey Address of the `UserAccount` to fetch.
+     * @param data Optional pre-fetched account data to seed with, skipping the RPC call entirely.
+     * @param slot Slot `data` was observed at, if provided.
+     * @param commitment Commitment for the fetch; defaults to `'confirmed'`.
+     */
     constructor(program: VelocityProgram, userAccountPublicKey: PublicKey, data?: UserAccount, slot?: number, commitment?: Commitment);
+    /**
+     * If `userAccount` is supplied, seeds directly with no RPC call. Otherwise fetches once via
+     * `fetchIfUnloaded()` if no data is cached yet. Always resolves `true` — there is no
+     * persistent subscription to fail.
+     * @param userAccount Optional pre-fetched account data to seed with instead of fetching.
+     */
     subscribe(userAccount?: UserAccount): Promise<boolean>;
+    /** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
     fetchIfUnloaded(): Promise<void>;
+    /**
+     * Fetches the account once via `program.account.user.fetchAndContext`, applying it only if
+     * the response's slot is newer than what's cached. Logs and swallows errors (e.g. account not
+     * yet initialized) rather than throwing.
+     */
     fetch(): Promise<void>;
 }

package/lib/browser/accounts/oneShotUserAccountSubscriber.js

@@ -8,11 +8,24 @@ const basicUserAccountSubscriber_1 = require("./basicUserAccountSubscriber");
  * Expect to use only 1 RPC call unless you call fetch repeatedly.
  */
 class OneShotUserAccountSubscriber extends basicUserAccountSubscriber_1.BasicUserAccountSubscriber {
+    /**
+     * @param program Anchor program used for the one-off `fetchAndContext` call.
+     * @param userAccountPublicKey Address of the `UserAccount` to fetch.
+     * @param data Optional pre-fetched account data to seed with, skipping the RPC call entirely.
+     * @param slot Slot `data` was observed at, if provided.
+     * @param commitment Commitment for the fetch; defaults to `'confirmed'`.
+     */
     constructor(program, userAccountPublicKey, data, slot, commitment) {
         super(userAccountPublicKey, data, slot);
         this.program = program;
         this.commitment = commitment !== null && commitment !== void 0 ? commitment : 'confirmed';
     }
+    /**
+     * If `userAccount` is supplied, seeds directly with no RPC call. Otherwise fetches once via
+     * `fetchIfUnloaded()` if no data is cached yet. Always resolves `true` — there is no
+     * persistent subscription to fail.
+     * @param userAccount Optional pre-fetched account data to seed with instead of fetching.
+     */
     async subscribe(userAccount) {
         var _a, _b;
         if (userAccount) {
@@ -25,11 +38,17 @@ class OneShotUserAccountSubscriber extends basicUserAccountSubscriber_1.BasicUse
         }
         return true;
     }
+    /** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
     async fetchIfUnloaded() {
         if (!this.user) {
             await this.fetch();
         }
     }
+    /**
+     * Fetches the account once via `program.account.user.fetchAndContext`, applying it only if
+     * the response's slot is newer than what's cached. Logs and swallows errors (e.g. account not
+     * yet initialized) rather than throwing.
+     */
     async fetch() {
         var _a, _b;
         try {

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

@@ -11,8 +11,27 @@ import { VelocityProgram } from '../config';
 export declare class OneShotUserStatsAccountSubscriber extends BasicUserStatsAccountSubscriber implements UserStatsAccountSubscriber {
     program: VelocityProgram;
     commitment: Commitment;
+    /**
+     * @param program Anchor program used for the one-off `fetchAndContext` call.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to fetch.
+     * @param data Optional pre-fetched account data to seed with, skipping the RPC call entirely.
+     * @param slot Slot `data` was observed at, if provided.
+     * @param commitment Commitment for the fetch; defaults to `'confirmed'`.
+     */
     constructor(program: VelocityProgram, userStatsAccountPublicKey: PublicKey, data?: UserStatsAccount, slot?: number, commitment?: Commitment);
+    /**
+     * If `userStatsAccount` is supplied, seeds directly with no RPC call. Otherwise fetches once
+     * via `fetchIfUnloaded()` if no data is cached yet. Always resolves `true` — there is no
+     * persistent subscription to fail.
+     * @param userStatsAccount Optional pre-fetched account data to seed with instead of fetching.
+     */
     subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean>;
+    /** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
     fetchIfUnloaded(): Promise<void>;
+    /**
+     * Fetches the account once via `program.account.userStats.fetchAndContext`, applying it only
+     * if the response's slot is newer than what's cached. Logs and swallows errors (e.g. account
+     * not yet initialized) rather than throwing.
+     */
     fetch(): Promise<void>;
 }

package/lib/browser/accounts/oneShotUserStatsAccountSubscriber.js

@@ -8,11 +8,24 @@ const basicUserStatsAccountSubscriber_1 = require("./basicUserStatsAccountSubscr
  * Expect to use only 1 RPC call unless you call fetch repeatedly.
  */
 class OneShotUserStatsAccountSubscriber extends basicUserStatsAccountSubscriber_1.BasicUserStatsAccountSubscriber {
+    /**
+     * @param program Anchor program used for the one-off `fetchAndContext` call.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to fetch.
+     * @param data Optional pre-fetched account data to seed with, skipping the RPC call entirely.
+     * @param slot Slot `data` was observed at, if provided.
+     * @param commitment Commitment for the fetch; defaults to `'confirmed'`.
+     */
     constructor(program, userStatsAccountPublicKey, data, slot, commitment) {
         super(userStatsAccountPublicKey, data, slot);
         this.program = program;
         this.commitment = commitment !== null && commitment !== void 0 ? commitment : 'confirmed';
     }
+    /**
+     * If `userStatsAccount` is supplied, seeds directly with no RPC call. Otherwise fetches once
+     * via `fetchIfUnloaded()` if no data is cached yet. Always resolves `true` — there is no
+     * persistent subscription to fail.
+     * @param userStatsAccount Optional pre-fetched account data to seed with instead of fetching.
+     */
     async subscribe(userStatsAccount) {
         var _a, _b;
         if (userStatsAccount) {
@@ -28,11 +41,17 @@ class OneShotUserStatsAccountSubscriber extends basicUserStatsAccountSubscriber_
         }
         return true;
     }
+    /** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
     async fetchIfUnloaded() {
         if (!this.userStats) {
             await this.fetch();
         }
     }
+    /**
+     * Fetches the account once via `program.account.userStats.fetchAndContext`, applying it only
+     * if the response's slot is newer than what's cached. Logs and swallows errors (e.g. account
+     * not yet initialized) rather than throwing.
+     */
     async fetch() {
         var _a, _b;
         try {

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

@@ -6,6 +6,11 @@ import { EventEmitter } from 'events';
 import { PublicKey } from '@solana/web3.js';
 import { BulkAccountLoader } from './bulkAccountLoader';
 import { InsuranceFundStake } from '../types';
+/**
+ * `InsuranceFundStakeAccountSubscriber` backed by a shared `BulkAccountLoader` instead of a
+ * dedicated WebSocket subscription, mirroring `PollingUserAccountSubscriber` for
+ * `InsuranceFundStake` accounts.
+ */
 export declare class PollingInsuranceFundStakeAccountSubscriber implements InsuranceFundStakeAccountSubscriber {
     isSubscribed: boolean;
     program: VelocityProgram;
@@ -15,17 +20,43 @@ export declare class PollingInsuranceFundStakeAccountSubscriber implements Insur
     callbackId?: string;
     errorCallbackId?: string;
     insuranceFundStakeAccountAndSlot?: DataAndSlot<InsuranceFundStake>;
+    /**
+     * @param program Anchor program used for the one-off `fetch()` fallback and account decoding.
+     * @param publicKey Address of the `InsuranceFundStake` account to track.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     */
     constructor(program: VelocityProgram, publicKey: PublicKey, accountLoader: BulkAccountLoader);
+    /**
+     * Registers this account with the shared `BulkAccountLoader`. Note this does not wait for an
+     * initial fetch to land before returning `isSubscribed = true`, unlike the analogous
+     * `PollingUserAccountSubscriber.subscribe`; call `fetchIfUnloaded()` explicitly if data is
+     * needed immediately. Idempotent: a no-op if already subscribed.
+     * @param insuranceFundStake Optional pre-fetched account data to seed with (at slot 0) instead of an immediate fetch.
+     */
     subscribe(insuranceFundStake?: InsuranceFundStake): Promise<boolean>;
+    /** Registers this account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     addToAccountLoader(): Promise<void>;
+    /** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
     fetchIfUnloaded(): Promise<void>;
+    /** Fetches the account once directly via `program.account.insuranceFundStake.fetchAndContext` (independent of the account loader's poll cycle), applying it only if the response's slot is newer than what's cached. Logs and swallows errors rather than throwing. */
     fetch(): Promise<void>;
+    /** Type predicate: true once `insuranceFundStakeAccountAndSlot` has loaded, narrowing it to non-undefined. */
     doesAccountExist(): this is {
         insuranceFundStakeAccountAndSlot: DataAndSlot<InsuranceFundStake>;
     };
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. 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;
+    /** True once account data has been loaded, independent of `isSubscribed`. */
     didSubscriptionSucceed(): boolean;
+    /**
+     * Applies an externally-obtained account update if `slot` is newer than the currently cached
+     * slot (strictly newer — unlike most other subscribers here, an equal slot is not accepted).
+     * @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/pollingInsuranceFundStakeAccountSubscriber.js

@@ -3,7 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingInsuranceFundStakeAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
+/**
+ * `InsuranceFundStakeAccountSubscriber` backed by a shared `BulkAccountLoader` instead of a
+ * dedicated WebSocket subscription, mirroring `PollingUserAccountSubscriber` for
+ * `InsuranceFundStake` accounts.
+ */
 class PollingInsuranceFundStakeAccountSubscriber {
+    /**
+     * @param program Anchor program used for the one-off `fetch()` fallback and account decoding.
+     * @param publicKey Address of the `InsuranceFundStake` account to track.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     */
     constructor(program, publicKey, accountLoader) {
         this.isSubscribed = false;
         this.program = program;
@@ -11,6 +21,13 @@ class PollingInsuranceFundStakeAccountSubscriber {
         this.accountLoader = accountLoader;
         this.eventEmitter = new events_1.EventEmitter();
     }
+    /**
+     * Registers this account with the shared `BulkAccountLoader`. Note this does not wait for an
+     * initial fetch to land before returning `isSubscribed = true`, unlike the analogous
+     * `PollingUserAccountSubscriber.subscribe`; call `fetchIfUnloaded()` explicitly if data is
+     * needed immediately. Idempotent: a no-op if already subscribed.
+     * @param insuranceFundStake Optional pre-fetched account data to seed with (at slot 0) instead of an immediate fetch.
+     */
     async subscribe(insuranceFundStake) {
         if (this.isSubscribed) {
             return true;
@@ -28,6 +45,7 @@ class PollingInsuranceFundStakeAccountSubscriber {
         this.isSubscribed = true;
         return true;
     }
+    /** Registers this account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     async addToAccountLoader() {
         if (this.callbackId) {
             return;
@@ -49,11 +67,13 @@ class PollingInsuranceFundStakeAccountSubscriber {
             this.eventEmitter.emit('error', error);
         });
     }
+    /** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
     async fetchIfUnloaded() {
         if (!this.doesAccountExist()) {
             await this.fetch();
         }
     }
+    /** Fetches the account once directly via `program.account.insuranceFundStake.fetchAndContext` (independent of the account loader's poll cycle), applying it only if the response's slot is newer than what's cached. Logs and swallows errors rather than throwing. */
     async fetch() {
         var _a, _b;
         try {
@@ -70,9 +90,11 @@ class PollingInsuranceFundStakeAccountSubscriber {
             console.log(`PollingInsuranceFundStakeAccountSubscriber.fetch() InsuranceFundStake does not exist: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
+    /** Type predicate: true once `insuranceFundStakeAccountAndSlot` has loaded, narrowing it to non-undefined. */
     doesAccountExist() {
         return this.insuranceFundStakeAccountAndSlot !== undefined;
     }
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -83,18 +105,27 @@ class PollingInsuranceFundStakeAccountSubscriber {
         this.errorCallbackId = undefined;
         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.insuranceFundStakeAccountAndSlot;
     }
+    /** True once account data has been loaded, independent of `isSubscribed`. */
     didSubscriptionSucceed() {
         return !!this.insuranceFundStakeAccountAndSlot;
     }
+    /**
+     * Applies an externally-obtained account update if `slot` is newer than the currently cached
+     * slot (strictly newer — unlike most other subscribers here, an equal slot is not accepted).
+     * @param insuranceFundStake Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(insuranceFundStake, slot) {
         if (!this.insuranceFundStakeAccountAndSlot ||
             this.insuranceFundStakeAccountAndSlot.slot < slot) {

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

@@ -5,6 +5,7 @@ import { EventEmitter } from 'events';
 import { PublicKey } from '@solana/web3.js';
 import { BulkAccountLoader } from './bulkAccountLoader';
 import { OracleClient, OraclePriceData } from '../oracles/types';
+/** Tracks a single oracle account's decoded `OraclePriceData` via a shared `BulkAccountLoader`, decoding raw buffers with the source-appropriate `OracleClient` (Pyth/Switchboard/quote-asset/etc.). */
 export declare class PollingOracleAccountSubscriber implements OracleAccountSubscriber {
     isSubscribed: boolean;
     eventEmitter: StrictEventEmitter<EventEmitter, OracleEvents>;
@@ -14,12 +15,30 @@ export declare class PollingOracleAccountSubscriber implements OracleAccountSubs
     callbackId?: string;
     errorCallbackId?: string;
     oraclePriceData?: DataAndSlot<OraclePriceData>;
+    /**
+     * @param publicKey Address of the oracle account to track.
+     * @param oracleClient Source-specific decoder (Pyth/Switchboard/quote-asset/etc.) used to parse the raw buffer into `OraclePriceData`.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     */
     constructor(publicKey: PublicKey, oracleClient: OracleClient, accountLoader: BulkAccountLoader);
+    /**
+     * Registers this account with the shared `BulkAccountLoader`, then polls up to 5 times
+     * (once per `load()` cycle) until data has loaded, since the oracle account may not have been
+     * fetched by the shared loader on the very first poll. `isSubscribed` is only set `true` if
+     * data loaded within those retries.
+     * @returns `true` if oracle data loaded within the retry budget, `false` otherwise.
+     */
     subscribe(): Promise<boolean>;
+    /** Registers this account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     addToAccountLoader(): Promise<void>;
+    /** Forces the shared `BulkAccountLoader` to load, then decodes this account's buffer from it if present. Does not check slot ordering against the previously cached value (the loader itself already filters out stale/unchanged buffers before invoking callbacks). */
     fetch(): Promise<void>;
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed(): void;
+    /** Throws `NotSubscribedError` if not subscribed. */
     getOraclePriceData(): DataAndSlot<OraclePriceData>;
+    /** True once oracle data has been loaded, independent of `isSubscribed`. */
     didSubscriptionSucceed(): boolean;
 }

package/lib/browser/accounts/pollingOracleAccountSubscriber.js

@@ -3,7 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingOracleAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
+/** Tracks a single oracle account's decoded `OraclePriceData` via a shared `BulkAccountLoader`, decoding raw buffers with the source-appropriate `OracleClient` (Pyth/Switchboard/quote-asset/etc.). */
 class PollingOracleAccountSubscriber {
+    /**
+     * @param publicKey Address of the oracle account to track.
+     * @param oracleClient Source-specific decoder (Pyth/Switchboard/quote-asset/etc.) used to parse the raw buffer into `OraclePriceData`.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     */
     constructor(publicKey, oracleClient, accountLoader) {
         this.isSubscribed = false;
         this.publicKey = publicKey;
@@ -11,6 +17,13 @@ class PollingOracleAccountSubscriber {
         this.accountLoader = accountLoader;
         this.eventEmitter = new events_1.EventEmitter();
     }
+    /**
+     * Registers this account with the shared `BulkAccountLoader`, then polls up to 5 times
+     * (once per `load()` cycle) until data has loaded, since the oracle account may not have been
+     * fetched by the shared loader on the very first poll. `isSubscribed` is only set `true` if
+     * data loaded within those retries.
+     * @returns `true` if oracle data loaded within the retry budget, `false` otherwise.
+     */
     async subscribe() {
         if (this.isSubscribed) {
             return true;
@@ -29,12 +42,13 @@ class PollingOracleAccountSubscriber {
         this.isSubscribed = subscriptionSucceeded;
         return subscriptionSucceeded;
     }
+    /** Registers this account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     async addToAccountLoader() {
         if (this.callbackId) {
             return;
         }
-        this.callbackId = await this.accountLoader.addAccount(this.publicKey, async (buffer, slot) => {
-            const oraclePriceData = await this.oracleClient.getOraclePriceDataFromBuffer(buffer);
+        this.callbackId = await this.accountLoader.addAccount(this.publicKey, (buffer, slot) => {
+            const oraclePriceData = this.oracleClient.getOraclePriceDataFromBuffer(buffer);
             this.oraclePriceData = { data: oraclePriceData, slot };
             // @ts-ignore
             this.eventEmitter.emit('oracleUpdate', oraclePriceData);
@@ -44,6 +58,7 @@ class PollingOracleAccountSubscriber {
             this.eventEmitter.emit('error', error);
         });
     }
+    /** Forces the shared `BulkAccountLoader` to load, then decodes this account's buffer from it if present. Does not check slot ordering against the previously cached value (the loader itself already filters out stale/unchanged buffers before invoking callbacks). */
     async fetch() {
         await this.accountLoader.load();
         const bufferAndSlot = this.accountLoader.getBufferAndSlot(this.publicKey);
@@ -59,6 +74,7 @@ class PollingOracleAccountSubscriber {
             slot,
         };
     }
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -73,15 +89,18 @@ class PollingOracleAccountSubscriber {
         }
         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. */
     getOraclePriceData() {
         this.assertIsSubscribed();
         return this.oraclePriceData;
     }
+    /** True once oracle data has been loaded, independent of `isSubscribed`. */
     didSubscriptionSucceed() {
         return !!this.oraclePriceData;
     }

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

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

package/lib/browser/accounts/pollingTokenAccountSubscriber.js

@@ -4,13 +4,29 @@ exports.PollingTokenAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
 const token_1 = require("../token");
+/**
+ * Tracks an SPL token account's parsed balance/owner via a shared `BulkAccountLoader`. Used for
+ * things like a spot market's token vault or a user's wallet token account, where a dedicated
+ * WebSocket subscription per account is unnecessary.
+ */
 class PollingTokenAccountSubscriber {
+    /**
+     * @param publicKey Address of the SPL token account to track.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     */
     constructor(publicKey, accountLoader) {
         this.isSubscribed = false;
         this.publicKey = publicKey;
         this.accountLoader = accountLoader;
         this.eventEmitter = new events_1.EventEmitter();
     }
+    /**
+     * Registers this account with the shared `BulkAccountLoader`, then polls up to 5 times
+     * (once per `load()` cycle) until data has loaded, since the token account may not have been
+     * fetched by the shared loader on the very first poll. `isSubscribed` is only set `true` if
+     * data loaded within those retries.
+     * @returns `true` if account data loaded within the retry budget, `false` otherwise.
+     */
     async subscribe() {
         if (this.isSubscribed) {
             return true;
@@ -29,6 +45,7 @@ class PollingTokenAccountSubscriber {
         this.isSubscribed = subscriptionSucceeded;
         return subscriptionSucceeded;
     }
+    /** Registers this account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     async addToAccountLoader() {
         if (this.callbackId) {
             return;
@@ -44,6 +61,7 @@ class PollingTokenAccountSubscriber {
             this.eventEmitter.emit('error', error);
         });
     }
+    /** Forces the shared `BulkAccountLoader` to load, then reads and parses this account's buffer from it if present. Does not check slot ordering against the previously cached value (the loader itself already filters out stale/unchanged buffers before invoking callbacks). */
     async fetch() {
         await this.accountLoader.load();
         const bufferAndSlot = this.accountLoader.getBufferAndSlot(this.publicKey);
@@ -59,6 +77,7 @@ class PollingTokenAccountSubscriber {
             slot,
         };
     }
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -73,15 +92,18 @@ class PollingTokenAccountSubscriber {
         }
         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. */
     getTokenAccountAndSlot() {
         this.assertIsSubscribed();
         return this.tokenAccountAndSlot;
     }
+    /** True once account data has been loaded, independent of `isSubscribed`. */
     didSubscriptionSucceed() {
         return !!this.tokenAccountAndSlot;
     }

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

@@ -8,6 +8,13 @@ import { EventEmitter } from 'events';
 import { PublicKey } from '@solana/web3.js';
 import { UserAccount } from '../types';
 import { BulkAccountLoader } from './bulkAccountLoader';
+/**
+ * `UserAccountSubscriber` backed by a shared `BulkAccountLoader` instead of a dedicated
+ * WebSocket subscription. Registers a callback for the user's `UserAccount` and relies on the
+ * loader's periodic batched `getMultipleAccounts` polling to detect changes. Prefer this over
+ * `WebSocketUserAccountSubscriber` when tracking many users concurrently (e.g. a keeper watching
+ * the whole DLOB) to keep the RPC/WS connection count bounded.
+ */
 export declare class PollingUserAccountSubscriber implements UserAccountSubscriber {
     isSubscribed: boolean;
     connection: Connection;
@@ -18,16 +25,41 @@ export declare class PollingUserAccountSubscriber implements UserAccountSubscrib
     errorCallbackId?: string;
     decode: (name: string, buffer: Buffer) => UserAccount;
     user?: DataAndSlot<UserAccount>;
+    /**
+     * @param connection Connection (or bankrun-compatible shim) used for the one-off `fetch()` fallback.
+     * @param userAccountPublicKey Address of the `UserAccount` to track.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     * @param decode Decode function for the raw account buffer (typically the program's Anchor coder).
+     */
     constructor(connection: Connection, userAccountPublicKey: PublicKey, accountLoader: BulkAccountLoader, decode: (name: string, buffer: Buffer) => UserAccount);
+    /**
+     * Registers this account with the shared `BulkAccountLoader` and, if no data has loaded yet
+     * (from a prior fetch or the optional `userAccount` seed), performs a one-off `fetch()` so the
+     * subscriber has data before returning. Idempotent: a no-op if already subscribed.
+     * @param userAccount Optional pre-fetched account data to seed with (at slot 0) instead of an immediate fetch.
+     */
     subscribe(userAccount?: UserAccount): Promise<boolean>;
+    /** Registers this user's account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     addToAccountLoader(): Promise<void>;
+    /** Fetches via `fetch()` only if no data is cached yet; otherwise a no-op. */
     fetchIfUnloaded(): Promise<void>;
+    /** Fetches the account once directly via RPC (independent of the account loader's poll cycle), applying it only if the response's slot is newer than what's cached. Logs and swallows errors (e.g. account not yet initialized) rather than throwing. */
     fetch(): Promise<void>;
+    /** Type predicate: true once `user` has loaded, narrowing `this.user` to non-undefined for callers that check it first. */
     doesAccountExist(): this is {
         user: DataAndSlot<UserAccount>;
     };
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. 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 (e.g. relayed by the SDK's `User` wrapper) if
+     * `slot` is strictly newer than the currently cached slot (equal-slot updates are ignored).
+     * @param userAccount Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userAccount: UserAccount, slot: number): void;
 }