@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/accounts/pollingUserAccountSubscriber.js

@@ -3,7 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingUserAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
+/**
+ * `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.
+ */
 class PollingUserAccountSubscriber {
+    /**
+     * @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, userAccountPublicKey, accountLoader, decode) {
         this.isSubscribed = false;
         this.connection = connection;
@@ -12,6 +25,12 @@ class PollingUserAccountSubscriber {
         this.userAccountPublicKey = userAccountPublicKey;
         this.decode = decode;
     }
+    /**
+     * 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.
+     */
     async subscribe(userAccount) {
         if (this.isSubscribed) {
             return true;
@@ -29,6 +48,7 @@ class PollingUserAccountSubscriber {
         this.isSubscribed = true;
         return true;
     }
+    /** Registers this user's account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     async addToAccountLoader() {
         if (this.callbackId) {
             return;
@@ -49,11 +69,13 @@ class PollingUserAccountSubscriber {
             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 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. */
     async fetch() {
         var _a, _b;
         try {
@@ -71,9 +93,11 @@ class PollingUserAccountSubscriber {
             console.log(`PollingUserAccountSubscriber.fetch() UserAccount does not exist: ${err.message}-${err.stack}`);
         }
     }
+    /** Type predicate: true once `user` has loaded, narrowing `this.user` to non-undefined for callers that check it first. */
     doesAccountExist() {
         return this.user !== undefined;
     }
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -88,15 +112,23 @@ class PollingUserAccountSubscriber {
         }
         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. */
     getUserAccountAndSlot() {
         this.assertIsSubscribed();
         return this.user;
     }
+    /**
+     * 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, slot) {
         if (!this.user || this.user.slot < slot) {
             this.user = { data: userAccount, slot };

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

@@ -6,6 +6,10 @@ import { EventEmitter } from 'events';
 import { PublicKey } from '@solana/web3.js';
 import { UserStatsAccount } from '../types';
 import { BulkAccountLoader } from './bulkAccountLoader';
+/**
+ * `UserStatsAccountSubscriber` backed by a shared `BulkAccountLoader` instead of a dedicated
+ * WebSocket subscription, mirroring `PollingUserAccountSubscriber` for `UserStatsAccount`.
+ */
 export declare class PollingUserStatsAccountSubscriber implements UserStatsAccountSubscriber {
     isSubscribed: boolean;
     program: VelocityProgram;
@@ -15,15 +19,33 @@ export declare class PollingUserStatsAccountSubscriber implements UserStatsAccou
     callbackId?: string;
     errorCallbackId?: string;
     userStats?: DataAndSlot<UserStatsAccount>;
+    /**
+     * @param program Anchor program used for the one-off `fetch()` fallback and account decoding.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     */
     constructor(program: VelocityProgram, userStatsAccountPublicKey: PublicKey, accountLoader: BulkAccountLoader);
+    /**
+     * Registers this account with the shared `BulkAccountLoader` and, if no data has loaded yet
+     * (from a prior fetch or the optional `userStatsAccount` seed), performs a one-off `fetch()`
+     * so the subscriber has data before returning. Idempotent: a no-op if already subscribed.
+     * @param userStatsAccount Optional pre-fetched account data to seed with (at slot 0) instead of an immediate fetch.
+     */
     subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean>;
+    /** Registers this user stats 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.userStats.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 `userStats` has loaded, narrowing `this.userStats` to non-undefined. */
     doesAccountExist(): this is {
         userStats: DataAndSlot<UserStatsAccount>;
     };
+    /** 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. */
     getUserStatsAccountAndSlot(): DataAndSlot<UserStatsAccount> | undefined;
 }

package/lib/browser/accounts/pollingUserStatsAccountSubscriber.js

@@ -3,7 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingUserStatsAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
+/**
+ * `UserStatsAccountSubscriber` backed by a shared `BulkAccountLoader` instead of a dedicated
+ * WebSocket subscription, mirroring `PollingUserAccountSubscriber` for `UserStatsAccount`.
+ */
 class PollingUserStatsAccountSubscriber {
+    /**
+     * @param program Anchor program used for the one-off `fetch()` fallback and account decoding.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+     * @param accountLoader Shared `BulkAccountLoader` this subscriber registers its callback with.
+     */
     constructor(program, userStatsAccountPublicKey, accountLoader) {
         this.isSubscribed = false;
         this.program = program;
@@ -11,6 +20,12 @@ class PollingUserStatsAccountSubscriber {
         this.eventEmitter = new events_1.EventEmitter();
         this.userStatsAccountPublicKey = userStatsAccountPublicKey;
     }
+    /**
+     * Registers this account with the shared `BulkAccountLoader` and, if no data has loaded yet
+     * (from a prior fetch or the optional `userStatsAccount` seed), performs a one-off `fetch()`
+     * so the subscriber has data before returning. Idempotent: a no-op if already subscribed.
+     * @param userStatsAccount Optional pre-fetched account data to seed with (at slot 0) instead of an immediate fetch.
+     */
     async subscribe(userStatsAccount) {
         if (this.isSubscribed) {
             return true;
@@ -28,6 +43,7 @@ class PollingUserStatsAccountSubscriber {
         this.isSubscribed = true;
         return true;
     }
+    /** Registers this user stats account and an error callback with the `BulkAccountLoader`. A no-op if already registered. */
     async addToAccountLoader() {
         if (this.callbackId !== undefined) {
             return;
@@ -48,11 +64,13 @@ class PollingUserStatsAccountSubscriber {
             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.userStats.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 {
@@ -68,9 +86,11 @@ class PollingUserStatsAccountSubscriber {
             console.log(`PollingUserStatsAccountSubscriber.fetch() UserStatsAccount does not exist: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
+    /** Type predicate: true once `userStats` has loaded, narrowing `this.userStats` to non-undefined. */
     doesAccountExist() {
         return this.userStats !== undefined;
     }
+    /** Unregisters this account (and its error callback) from the `BulkAccountLoader`. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -81,11 +101,13 @@ class PollingUserStatsAccountSubscriber {
         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. */
     getUserStatsAccountAndSlot() {
         this.assertIsSubscribed();
         return this.userStats;

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

@@ -8,6 +8,15 @@ import { PublicKey } from '@solana/web3.js';
 import { OracleInfo, OraclePriceData } from '../oracles/types';
 import { OracleClientCache } from '../oracles/oracleClientCache';
 import { VelocityProgram } from '../config';
+/**
+ * `VelocityClientAccountSubscriber` that batches the `State`, every tracked `PerpMarket`/
+ * `SpotMarket`, and every tracked oracle behind a single `BulkAccountLoader` instead of one
+ * WebSocket subscription per account. Cheaper on connection count at the cost of update latency
+ * bounded by the loader's poll interval. `subscribe()` retries the initial load up to 5 times
+ * before giving up (returning `false`) if the `State` account never appears — `didSubscriptionSucceed`
+ * checks only for `state`, since market/oracle data can be added incrementally afterward via
+ * `addPerpMarket`/`addSpotMarket`/`addOracle`.
+ */
 export declare class PollingVelocityClientAccountSubscriber implements VelocityClientAccountSubscriber {
     isSubscribed: boolean;
     program: VelocityProgram;
@@ -34,7 +43,23 @@ export declare class PollingVelocityClientAccountSubscriber implements VelocityC
     private isSubscribing;
     private subscriptionPromiseResolver;
     private subscriptionPromise;
+    /**
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @param accountLoader Shared `BulkAccountLoader` all state/market/oracle accounts are registered with.
+     * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+     * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state, ignoring the index/info args above.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing; see `DelistedMarketSetting`.
+     */
     constructor(program: VelocityProgram, accountLoader: BulkAccountLoader, perpMarketIndexes: number[], spotMarketIndexes: number[], oracleInfos: OracleInfo[], shouldFindAllMarketsAndOracles: boolean, delistedMarketSetting: DelistedMarketSetting);
+    /**
+     * Registers state/market/oracle accounts with the `BulkAccountLoader` and retries the initial
+     * load up to 5 times until the `State` account has appeared. Idempotent: a no-op if already
+     * subscribed, and concurrent calls while a subscribe is in flight share the same result via
+     * `subscriptionPromise` rather than issuing duplicate loads.
+     * @returns `true` if `State` account data loaded within the retry budget, `false` otherwise.
+     */
     subscribe(): Promise<boolean>;
     updateAccountsToPoll(): Promise<void>;
     updatePerpMarketAccountsToPoll(): Promise<boolean>;
@@ -52,24 +77,82 @@ export declare class PollingVelocityClientAccountSubscriber implements VelocityC
     private storeDecodedAccount;
     addAccountToAccountLoader(accountToPoll: AccountToPoll): Promise<void>;
     addOracleToAccountLoader(oracleToPoll: OraclesToPoll): Promise<void>;
+    /** Forces the shared `BulkAccountLoader` to load, then re-decodes every tracked state/market/oracle account from the loader's cached buffers into this subscriber's maps. */
     fetch(): Promise<void>;
+    /** True once the `State` account has loaded, independent of `isSubscribed`. Market/oracle data is not required. */
     didSubscriptionSucceed(): boolean;
+    /** Removes every tracked state/market/oracle account and the error callback from the `BulkAccountLoader`, then clears internal maps. */
     unsubscribe(): Promise<void>;
+    /**
+     * Adds a spot market (and its oracle, via `setSpotOracleMap`) to be tracked, registering it
+     * with the `BulkAccountLoader`. Idempotent: returns `true` immediately if already tracked.
+     * @param marketIndex Spot market index to start tracking.
+     */
     addSpotMarket(marketIndex: number): Promise<boolean>;
+    /**
+     * Adds a perp market (and its oracle, via `setPerpOracleMap`) to be tracked, registering it
+     * with the `BulkAccountLoader`. Idempotent: returns `true` immediately if already tracked.
+     * @param marketIndex Perp market index to start tracking.
+     */
     addPerpMarket(marketIndex: number): Promise<boolean>;
+    /**
+     * Adds an oracle to be tracked, registering it with the `BulkAccountLoader` and waiting
+     * (polling up to 3 times at `accountLoader.pollingFrequency` intervals) for it to appear in
+     * the loader's buffer map before resolving. A no-op that resolves `true` immediately for the
+     * `PublicKey.default` sentinel (quote-asset "no oracle") or an oracle already tracked.
+     * @param oracleInfo Oracle pubkey and source to start tracking.
+     */
     addOracle(oracleInfo: OracleInfo): Promise<boolean>;
     private pauseForOracleToBeAdded;
+    /** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked. */
     setPerpOracleMap(): Promise<void>;
+    /** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked. */
     setSpotOracleMap(): Promise<void>;
+    /**
+     * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+     * oracle, if not shared with a live spot market): removes the `BulkAccountLoader` registration,
+     * and additionally drops the market/oracle from internal maps if the setting is `Discard`. A
+     * no-op if the setting is `Subscribe`. Throws if internal bookkeeping is inconsistent (e.g. a
+     * delisted market missing from `accountsToPoll`), which would indicate a bug rather than an
+     * expected runtime condition.
+     */
     handleDelistedMarkets(): void;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed(): void;
+    /** Throws `NotSubscribedError` if not subscribed. */
     getStateAccountAndSlot(): DataAndSlot<StateAccount>;
+    /** Returns the cached perp market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getMarketAccountAndSlot(marketIndex: number): DataAndSlot<PerpMarketAccount> | undefined;
+    /** Returns every currently cached perp market. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots(): DataAndSlot<PerpMarketAccount>[];
+    /** Returns the cached spot market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getSpotMarketAccountAndSlot(marketIndex: number): DataAndSlot<SpotMarketAccount> | undefined;
+    /** Returns every currently cached spot market. Does not throw `NotSubscribedError`. */
     getSpotMarketAccountsAndSlots(): DataAndSlot<SpotMarketAccount>[];
+    /**
+     * Looks up cached oracle price data by oracle id (see `getOracleId`). Special-cases the
+     * quote-asset default oracle id, returning the constant `QUOTE_ORACLE_PRICE_DATA` at slot 0
+     * rather than a map lookup, since that oracle is never actually subscribed to.
+     * @param oracleId Oracle id string from `getOracleId(publicKey, source)`.
+     * @returns Cached price data/slot, or undefined if not tracked. Throws `NotSubscribedError` if not subscribed.
+     */
     getOraclePriceDataAndSlot(oracleId: string): DataAndSlot<OraclePriceData> | undefined;
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a perp market's
+     * oracle. If the cached market's oracle pubkey has drifted from `perpOracleMap` (e.g. an admin
+     * changed it on-chain), triggers a background `setPerpOracleMap()` refresh and still returns
+     * the (possibly stale) mapping for this call.
+     * @param marketIndex Perp market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForPerpMarket(marketIndex: number): DataAndSlot<OraclePriceData> | undefined;
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a spot market's
+     * oracle. If the cached market's oracle pubkey has drifted from `spotOracleMap`, triggers a
+     * background `setSpotOracleMap()` refresh and still returns the (possibly stale) mapping for
+     * this call.
+     * @param marketIndex Spot market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForSpotMarket(marketIndex: number): DataAndSlot<OraclePriceData> | undefined;
+    /** Retunes the shared `BulkAccountLoader`'s poll interval (ms) for every account it batches (affects other subscribers sharing the same loader too). */
     updateAccountLoaderPollingFrequency(pollingFrequency: number): void;
 }

package/lib/browser/accounts/pollingVelocityClientAccountSubscriber.js

@@ -12,7 +12,25 @@ const quoteAssetOracleClient_1 = require("../oracles/quoteAssetOracleClient");
 const config_1 = require("../config");
 const oracleId_1 = require("../oracles/oracleId");
 const ORACLE_DEFAULT_ID = (0, oracleId_1.getOracleId)(web3_js_1.PublicKey.default, types_2.OracleSource.QUOTE_ASSET);
+/**
+ * `VelocityClientAccountSubscriber` that batches the `State`, every tracked `PerpMarket`/
+ * `SpotMarket`, and every tracked oracle behind a single `BulkAccountLoader` instead of one
+ * WebSocket subscription per account. Cheaper on connection count at the cost of update latency
+ * bounded by the loader's poll interval. `subscribe()` retries the initial load up to 5 times
+ * before giving up (returning `false`) if the `State` account never appears — `didSubscriptionSucceed`
+ * checks only for `state`, since market/oracle data can be added incrementally afterward via
+ * `addPerpMarket`/`addSpotMarket`/`addOracle`.
+ */
 class PollingVelocityClientAccountSubscriber {
+    /**
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @param accountLoader Shared `BulkAccountLoader` all state/market/oracle accounts are registered with.
+     * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+     * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state, ignoring the index/info args above.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing; see `DelistedMarketSetting`.
+     */
     constructor(program, accountLoader, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting) {
         this.oracleClientCache = new oracleClientCache_1.OracleClientCache();
         this.accountsToPoll = new Map();
@@ -39,6 +57,13 @@ class PollingVelocityClientAccountSubscriber {
         this.shouldFindAllMarketsAndOracles = shouldFindAllMarketsAndOracles;
         this.delistedMarketSetting = delistedMarketSetting;
     }
+    /**
+     * Registers state/market/oracle accounts with the `BulkAccountLoader` and retries the initial
+     * load up to 5 times until the `State` account has appeared. Idempotent: a no-op if already
+     * subscribed, and concurrent calls while a subscribe is in flight share the same result via
+     * `subscriptionPromise` rather than issuing duplicate loads.
+     * @returns `true` if `State` account data loaded within the retry budget, `false` otherwise.
+     */
     async subscribe() {
         if (this.isSubscribed) {
             return true;
@@ -211,6 +236,7 @@ class PollingVelocityClientAccountSubscriber {
             this.eventEmitter.emit('update');
         });
     }
+    /** Forces the shared `BulkAccountLoader` to load, then re-decodes every tracked state/market/oracle account from the loader's cached buffers into this subscriber's maps. */
     async fetch() {
         await this.accountLoader.load();
         for (const [_, accountToPoll] of this.accountsToPoll) {
@@ -243,11 +269,13 @@ class PollingVelocityClientAccountSubscriber {
             }
         }
     }
+    /** True once the `State` account has loaded, independent of `isSubscribed`. Market/oracle data is not required. */
     didSubscriptionSucceed() {
         if (this.state)
             return true;
         return false;
     }
+    /** Removes every tracked state/market/oracle account and the error callback from the `BulkAccountLoader`, then clears internal maps. */
     async unsubscribe() {
         for (const [_, accountToPoll] of this.accountsToPoll) {
             this.accountLoader.removeAccount(accountToPoll.publicKey, accountToPoll.callbackId);
@@ -261,6 +289,11 @@ class PollingVelocityClientAccountSubscriber {
         this.oraclesToPoll.clear();
         this.isSubscribed = false;
     }
+    /**
+     * Adds a spot market (and its oracle, via `setSpotOracleMap`) to be tracked, registering it
+     * with the `BulkAccountLoader`. Idempotent: returns `true` immediately if already tracked.
+     * @param marketIndex Spot market index to start tracking.
+     */
     async addSpotMarket(marketIndex) {
         const marketPublicKey = await (0, pda_1.getSpotMarketPublicKey)(this.program.programId, marketIndex);
         if (this.accountsToPoll.has(marketPublicKey.toString())) {
@@ -272,9 +305,14 @@ class PollingVelocityClientAccountSubscriber {
             return false;
         }
         await this.addAccountToAccountLoader(accountToPoll);
-        this.setSpotOracleMap();
+        await this.setSpotOracleMap();
         return true;
     }
+    /**
+     * Adds a perp market (and its oracle, via `setPerpOracleMap`) to be tracked, registering it
+     * with the `BulkAccountLoader`. Idempotent: returns `true` immediately if already tracked.
+     * @param marketIndex Perp market index to start tracking.
+     */
     async addPerpMarket(marketIndex) {
         const marketPublicKey = await (0, pda_1.getPerpMarketPublicKey)(this.program.programId, marketIndex);
         if (this.accountsToPoll.has(marketPublicKey.toString())) {
@@ -289,6 +327,13 @@ class PollingVelocityClientAccountSubscriber {
         await this.setPerpOracleMap();
         return true;
     }
+    /**
+     * Adds an oracle to be tracked, registering it with the `BulkAccountLoader` and waiting
+     * (polling up to 3 times at `accountLoader.pollingFrequency` intervals) for it to appear in
+     * the loader's buffer map before resolving. A no-op that resolves `true` immediately for the
+     * `PublicKey.default` sentinel (quote-asset "no oracle") or an oracle already tracked.
+     * @param oracleInfo Oracle pubkey and source to start tracking.
+     */
     async addOracle(oracleInfo) {
         const oracleId = (0, oracleId_1.getOracleId)(oracleInfo.publicKey, oracleInfo.source);
         if (oracleInfo.publicKey.equals(web3_js_1.PublicKey.default) ||
@@ -318,6 +363,7 @@ class PollingVelocityClientAccountSubscriber {
         }
         console.log(`Pausing to find oracle ${oracle} failed`);
     }
+    /** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked. */
     async setPerpOracleMap() {
         const perpMarkets = this.getMarketAccountsAndSlots();
         const oraclePromises = [];
@@ -337,6 +383,7 @@ class PollingVelocityClientAccountSubscriber {
         }
         await Promise.all(oraclePromises);
     }
+    /** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked. */
     async setSpotOracleMap() {
         const spotMarkets = this.getSpotMarketAccountsAndSlots();
         const oraclePromises = [];
@@ -356,6 +403,14 @@ class PollingVelocityClientAccountSubscriber {
         }
         await Promise.all(oraclePromises);
     }
+    /**
+     * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+     * oracle, if not shared with a live spot market): removes the `BulkAccountLoader` registration,
+     * and additionally drops the market/oracle from internal maps if the setting is `Discard`. A
+     * no-op if the setting is `Subscribe`. Throws if internal bookkeeping is inconsistent (e.g. a
+     * delisted market missing from `accountsToPoll`), which would indicate a bug rather than an
+     * expected runtime condition.
+     */
     handleDelistedMarkets() {
         if (this.delistedMarketSetting === types_1.DelistedMarketSetting.Subscribe) {
             return;
@@ -390,27 +445,40 @@ class PollingVelocityClientAccountSubscriber {
             }
         }
     }
+    /** 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. */
     getStateAccountAndSlot() {
         this.assertIsSubscribed();
         return this.state;
     }
+    /** Returns the cached perp market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getMarketAccountAndSlot(marketIndex) {
         return this.perpMarket.get(marketIndex);
     }
+    /** Returns every currently cached perp market. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots() {
         return Array.from(this.perpMarket.values());
     }
+    /** Returns the cached spot market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getSpotMarketAccountAndSlot(marketIndex) {
         return this.spotMarket.get(marketIndex);
     }
+    /** Returns every currently cached spot market. Does not throw `NotSubscribedError`. */
     getSpotMarketAccountsAndSlots() {
         return Array.from(this.spotMarket.values());
     }
+    /**
+     * Looks up cached oracle price data by oracle id (see `getOracleId`). Special-cases the
+     * quote-asset default oracle id, returning the constant `QUOTE_ORACLE_PRICE_DATA` at slot 0
+     * rather than a map lookup, since that oracle is never actually subscribed to.
+     * @param oracleId Oracle id string from `getOracleId(publicKey, source)`.
+     * @returns Cached price data/slot, or undefined if not tracked. Throws `NotSubscribedError` if not subscribed.
+     */
     getOraclePriceDataAndSlot(oracleId) {
         this.assertIsSubscribed();
         if (oracleId === ORACLE_DEFAULT_ID) {
@@ -421,6 +489,13 @@ class PollingVelocityClientAccountSubscriber {
         }
         return this.oracles.get(oracleId);
     }
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a perp market's
+     * oracle. If the cached market's oracle pubkey has drifted from `perpOracleMap` (e.g. an admin
+     * changed it on-chain), triggers a background `setPerpOracleMap()` refresh and still returns
+     * the (possibly stale) mapping for this call.
+     * @param marketIndex Perp market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForPerpMarket(marketIndex) {
         const perpMarketAccount = this.getMarketAccountAndSlot(marketIndex);
         const oracle = this.perpOracleMap.get(marketIndex);
@@ -434,6 +509,13 @@ class PollingVelocityClientAccountSubscriber {
         }
         return this.getOraclePriceDataAndSlot(oracleId);
     }
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a spot market's
+     * oracle. If the cached market's oracle pubkey has drifted from `spotOracleMap`, triggers a
+     * background `setSpotOracleMap()` refresh and still returns the (possibly stale) mapping for
+     * this call.
+     * @param marketIndex Spot market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForSpotMarket(marketIndex) {
         const spotMarketAccount = this.getSpotMarketAccountAndSlot(marketIndex);
         const oracle = this.spotOracleMap.get(marketIndex);
@@ -447,6 +529,7 @@ class PollingVelocityClientAccountSubscriber {
         }
         return this.getOraclePriceDataAndSlot(oracleId);
     }
+    /** Retunes the shared `BulkAccountLoader`'s poll interval (ms) for every account it batches (affects other subscribers sharing the same loader too). */
     updateAccountLoaderPollingFrequency(pollingFrequency) {
         this.accountLoader.updatePollingFrequency(pollingFrequency);
     }

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

@@ -1,4 +1,12 @@
 import { AccountToLoad, BulkAccountLoader } from './bulkAccountLoader';
+/**
+ * Test-only `BulkAccountLoader` that overrides `loadChunk` to fetch each account individually via
+ * `connection.getAccountInfoAndContext` instead of batching through `getMultipleAccounts`. Used
+ * against test validators/bankrun connections that don't implement the `_rpcBatchRequest` path
+ * the base class relies on. Preserves the same per-account slot/buffer dedup semantics as the
+ * base class (an update is only dispatched if the new slot is not older and the buffer changed).
+ */
 export declare class TestBulkAccountLoader extends BulkAccountLoader {
+    /** Sequentially fetches every account in every chunk via individual RPC calls, dispatching callbacks for any that changed at a non-decreasing slot. Slower than the base class's batched `getMultipleAccounts` approach by design — intended for test environments only. */
     loadChunk(accountsToLoadChunks: AccountToLoad[][]): Promise<void>;
 }

package/lib/browser/accounts/testBulkAccountLoader.js

@@ -2,7 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TestBulkAccountLoader = void 0;
 const bulkAccountLoader_1 = require("./bulkAccountLoader");
+/**
+ * Test-only `BulkAccountLoader` that overrides `loadChunk` to fetch each account individually via
+ * `connection.getAccountInfoAndContext` instead of batching through `getMultipleAccounts`. Used
+ * against test validators/bankrun connections that don't implement the `_rpcBatchRequest` path
+ * the base class relies on. Preserves the same per-account slot/buffer dedup semantics as the
+ * base class (an update is only dispatched if the new slot is not older and the buffer changed).
+ */
 class TestBulkAccountLoader extends bulkAccountLoader_1.BulkAccountLoader {
+    /** Sequentially fetches every account in every chunk via individual RPC calls, dispatching callbacks for any that changed at a non-decreasing slot. Slower than the base class's batched `getMultipleAccounts` approach by design — intended for test environments only. */
     async loadChunk(accountsToLoadChunks) {
         if (accountsToLoadChunks.length === 0) {
             return;