@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/browser/accounts/webSocketUserAccountSubscriber.js

@@ -4,6 +4,11 @@ exports.WebSocketUserAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
 const webSocketAccountSubscriber_1 = require("./webSocketAccountSubscriber");
+/**
+ * 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).
+ */
 class WebSocketUserAccountSubscriber {
     get userDataAccountSubscriber() {
         if (!this._userDataAccountSubscriber) {
@@ -14,6 +19,12 @@ class WebSocketUserAccountSubscriber {
     set userDataAccountSubscriber(subscriber) {
         this._userDataAccountSubscriber = subscriber;
     }
+    /**
+     * @param program Anchor program providing the connection and coder.
+     * @param userAccountPublicKey Address of the `UserAccount` to track.
+     * @param resubOpts Resubscription watchdog options passed through to the underlying `WebSocketAccountSubscriber`.
+     * @param commitment Commitment for the underlying subscription; defaults to the provider's configured commitment.
+     */
     constructor(program, userAccountPublicKey, resubOpts, commitment) {
         this.isSubscribed = false;
         this.program = program;
@@ -22,6 +33,11 @@ class WebSocketUserAccountSubscriber {
         this.eventEmitter = new events_1.EventEmitter();
         this.commitment = commitment;
     }
+    /**
+     * Creates the underlying `WebSocketAccountSubscriber` and subscribes it. Idempotent: a no-op
+     * (returns `true`) if already subscribed.
+     * @param userAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+     */
     async subscribe(userAccount) {
         if (this.isSubscribed) {
             return true;
@@ -38,9 +54,11 @@ class WebSocketUserAccountSubscriber {
         this.isSubscribed = true;
         return true;
     }
+    /** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
     async fetch() {
         await Promise.all([this.userDataAccountSubscriber.fetch()]);
     }
+    /** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -48,15 +66,23 @@ class WebSocketUserAccountSubscriber {
         await Promise.all([this.userDataAccountSubscriber.unsubscribe()]);
         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.userDataAccountSubscriber.dataAndSlot;
     }
+    /**
+     * Applies an externally-obtained account update if `slot` is not older than the currently
+     * cached slot.
+     * @param userAccount Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userAccount, slot) {
         var _a;
         const currentDataSlot = ((_a = this.userDataAccountSubscriber.dataAndSlot) === null || _a === void 0 ? void 0 : _a.slot) || 0;

package/lib/browser/accounts/webSocketUserStatsAccountSubsriber.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 { UserStatsAccount } from '../types';
+/**
+ * Default `UserStatsAccountSubscriber` implementation: wraps a single `WebSocketAccountSubscriber`
+ * for the `UserStatsAccount`, mirroring `WebSocketUserAccountSubscriber`.
+ * `userStatsAccountSubscriber` throws if accessed before `subscribe()` has run.
+ */
 export declare class WebSocketUserStatsAccountSubscriber implements UserStatsAccountSubscriber {
     isSubscribed: boolean;
     resubOpts?: ResubOpts;
@@ -15,10 +20,25 @@ export declare class WebSocketUserStatsAccountSubscriber implements UserStatsAcc
     private _userStatsAccountSubscriber?;
     get userStatsAccountSubscriber(): AccountSubscriber<UserStatsAccount>;
     set userStatsAccountSubscriber(subscriber: AccountSubscriber<UserStatsAccount>);
+    /**
+     * @param program Anchor program providing the connection and coder.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+     * @param resubOpts Resubscription watchdog options passed through to the underlying `WebSocketAccountSubscriber`.
+     * @param commitment Commitment for the underlying subscription; defaults to the provider's configured commitment.
+     */
     constructor(program: VelocityProgram, userStatsAccountPublicKey: PublicKey, resubOpts?: ResubOpts, commitment?: Commitment);
+    /**
+     * Creates the underlying `WebSocketAccountSubscriber` and subscribes it. Idempotent: a no-op
+     * (returns `true`) if already subscribed.
+     * @param userStatsAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+     */
     subscribe(userStatsAccount?: UserStatsAccount): 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. */
     getUserStatsAccountAndSlot(): DataAndSlot<UserStatsAccount> | undefined;
 }

package/lib/browser/accounts/webSocketUserStatsAccountSubsriber.js

@@ -4,6 +4,11 @@ exports.WebSocketUserStatsAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
 const webSocketAccountSubscriber_1 = require("./webSocketAccountSubscriber");
+/**
+ * Default `UserStatsAccountSubscriber` implementation: wraps a single `WebSocketAccountSubscriber`
+ * for the `UserStatsAccount`, mirroring `WebSocketUserAccountSubscriber`.
+ * `userStatsAccountSubscriber` throws if accessed before `subscribe()` has run.
+ */
 class WebSocketUserStatsAccountSubscriber {
     get userStatsAccountSubscriber() {
         if (!this._userStatsAccountSubscriber) {
@@ -14,6 +19,12 @@ class WebSocketUserStatsAccountSubscriber {
     set userStatsAccountSubscriber(subscriber) {
         this._userStatsAccountSubscriber = subscriber;
     }
+    /**
+     * @param program Anchor program providing the connection and coder.
+     * @param userStatsAccountPublicKey Address of the `UserStatsAccount` to track.
+     * @param resubOpts Resubscription watchdog options passed through to the underlying `WebSocketAccountSubscriber`.
+     * @param commitment Commitment for the underlying subscription; defaults to the provider's configured commitment.
+     */
     constructor(program, userStatsAccountPublicKey, resubOpts, commitment) {
         this.isSubscribed = false;
         this.program = program;
@@ -22,6 +33,11 @@ class WebSocketUserStatsAccountSubscriber {
         this.resubOpts = resubOpts;
         this.commitment = commitment;
     }
+    /**
+     * Creates the underlying `WebSocketAccountSubscriber` and subscribes it. Idempotent: a no-op
+     * (returns `true`) if already subscribed.
+     * @param userStatsAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch.
+     */
     async subscribe(userStatsAccount) {
         if (this.isSubscribed) {
             return true;
@@ -38,9 +54,11 @@ class WebSocketUserStatsAccountSubscriber {
         this.isSubscribed = true;
         return true;
     }
+    /** Fetches the account once via the underlying `WebSocketAccountSubscriber`. */
     async fetch() {
         await Promise.all([this.userStatsAccountSubscriber.fetch()]);
     }
+    /** Tears down the underlying WebSocket subscription. A no-op if not subscribed. */
     async unsubscribe() {
         if (!this.isSubscribed) {
             return;
@@ -48,11 +66,13 @@ class WebSocketUserStatsAccountSubscriber {
         await Promise.all([this.userStatsAccountSubscriber.unsubscribe()]);
         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.userStatsAccountSubscriber.dataAndSlot;

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

@@ -11,6 +11,16 @@ import { OracleInfo, OraclePriceData } from '../oracles/types';
 import { OracleClientCache } from '../oracles/oracleClientCache';
 import { VelocityProgram } from '../config';
 import { WebSocketAccountSubscriberV2 } from './webSocketAccountSubscriberV2';
+/**
+ * Default `VelocityClientAccountSubscriber` implementation: creates one `WebSocketAccountSubscriber`
+ * per tracked `State`/`PerpMarket`/`SpotMarket`/oracle account, giving the lowest update latency
+ * at the cost of one WebSocket subscription per account. Before subscribing each per-account
+ * subscriber, `setInitialData()` batch-fetches all of them via `getMultipleAccountsInfo` so the
+ * per-account `WebSocketAccountSubscriber.subscribe()` calls can seed from that data instead of
+ * each issuing its own `getAccountInfo` round trip. `customPerpMarketAccountSubscriber`/
+ * `customOracleAccountSubscriber` let a caller substitute `WebSocketAccountSubscriberV2` (or any
+ * other `AccountSubscriber` implementation) for those two account types specifically.
+ */
 export declare class WebSocketVelocityClientAccountSubscriber implements VelocityClientAccountSubscriber {
     isSubscribed: boolean;
     program: VelocityProgram;
@@ -39,35 +49,146 @@ export declare class WebSocketVelocityClientAccountSubscriber implements Velocit
     protected isSubscribing: boolean;
     protected subscriptionPromiseResolver: (val: boolean) => void;
     protected subscriptionPromise: Promise<boolean>;
+    /**
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @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`.
+     * @param resubOpts Resubscription watchdog options passed to every per-account `WebSocketAccountSubscriber`.
+     * @param commitment Commitment for every per-account subscription; defaults to the provider's configured commitment.
+     * @param customPerpMarketAccountSubscriber Optional alternate `AccountSubscriber` constructor (e.g. `WebSocketAccountSubscriberV2`) used for perp market accounts instead of the default `WebSocketAccountSubscriber`.
+     * @param customOracleAccountSubscriber Optional alternate `AccountSubscriber` constructor used for oracle accounts instead of the default `WebSocketAccountSubscriber`.
+     */
     constructor(program: VelocityProgram, perpMarketIndexes: number[], spotMarketIndexes: number[], oracleInfos: OracleInfo[], shouldFindAllMarketsAndOracles: boolean, delistedMarketSetting: DelistedMarketSetting, resubOpts?: ResubOpts, commitment?: Commitment, customPerpMarketAccountSubscriber?: new (accountName: string, program: VelocityProgram, accountPublicKey: PublicKey, decodeBuffer?: (buffer: Buffer) => any, resubOpts?: ResubOpts, commitment?: Commitment) => WebSocketAccountSubscriberV2<any> | WebSocketAccountSubscriber<any>, customOracleAccountSubscriber?: new (accountName: string, program: VelocityProgram, accountPublicKey: PublicKey, decodeBuffer?: (buffer: Buffer) => any, resubOpts?: ResubOpts, commitment?: Commitment) => WebSocketAccountSubscriberV2<any> | WebSocketAccountSubscriber<any>);
+    /**
+     * Subscribes the `State` account, batch-seeds all market/oracle accounts via `setInitialData()`,
+     * then subscribes every per-account `WebSocketAccountSubscriber` (or the custom subscriber
+     * class, if configured) for perp markets, spot markets, and oracles. Applies
+     * `delistedMarketSetting` afterward. 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 subscriptions. Always resolves `true` (no retry/failure path — a
+     * per-account fetch failure surfaces via `ensureAccountFetched`'s retries, not by aborting
+     * subscribe).
+     */
     subscribe(): Promise<boolean>;
     chunks: <T>(array: readonly T[], size: number) => T[][];
+    /**
+     * Batch-fetches every tracked perp market, spot market, and oracle account via chunked
+     * `getMultipleAccountsInfo` calls (75 pubkeys per chunk) and stashes the decoded results in
+     * `initialPerpMarketAccountData`/`initialSpotMarketAccountData`/`initialOraclePriceData`.
+     * Each per-account `WebSocketAccountSubscriber.subscribe()` call seeds from this data via
+     * `setData` instead of issuing its own `getAccountInfo` round trip. Skips markets already
+     * populated (e.g. by `findAllMarketAndOracles` when `shouldFindAllMarketsAndOracles` is set).
+     */
     setInitialData(): Promise<void>;
+    /** Clears the seed data stashed by `setInitialData()` once every per-account subscriber has consumed it, freeing the memory. */
     removeInitialData(): void;
+    /** Subscribes a `WebSocketAccountSubscriber` for every tracked perp market index, in parallel. */
     subscribeToPerpMarketAccounts(): Promise<boolean>;
+    /**
+     * Creates and subscribes the per-account subscriber (custom class if `customPerpMarketAccountSubscriber`
+     * is set, else `WebSocketAccountSubscriber`) for one perp market, seeding it from
+     * `initialPerpMarketAccountData` if available, and waits (via `ensureAccountFetched`, up to 5
+     * retries with a 200ms backoff) for data to actually land before returning.
+     * @param marketIndex Perp market index to subscribe.
+     */
     subscribeToPerpMarketAccount(marketIndex: number): Promise<boolean>;
+    /** Subscribes a `WebSocketAccountSubscriber` for every tracked spot market index, in parallel. */
     subscribeToSpotMarketAccounts(): Promise<boolean>;
+    /**
+     * Creates and subscribes a `WebSocketAccountSubscriber` for one spot market, seeding it from
+     * `initialSpotMarketAccountData` if available, and waits (via `ensureAccountFetched`) for data
+     * to land before returning.
+     * @param marketIndex Spot market index to subscribe.
+     */
     subscribeToSpotMarketAccount(marketIndex: number): Promise<boolean>;
+    /** Subscribes an account subscriber for every tracked oracle, in parallel, skipping the `PublicKey.default` (quote-asset "no oracle") sentinel. */
     subscribeToOracles(): Promise<boolean>;
+    /**
+     * Creates and subscribes the per-account subscriber (custom class if `customOracleAccountSubscriber`
+     * is set, else `WebSocketAccountSubscriber`) for one oracle, decoding buffers with the
+     * source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available and
+     * waits (via `ensureAccountFetched`) for data to land before returning.
+     * @param oracleInfo Oracle pubkey and source to subscribe.
+     * @returns `false` if no `OracleClient` is registered for `oracleInfo.source`; otherwise `true`.
+     */
     subscribeToOracle(oracleInfo: OracleInfo): Promise<boolean>;
+    /** Unsubscribes every per-account subscriber tracking a perp market, in parallel. */
     unsubscribeFromMarketAccounts(): Promise<void>;
+    /** Unsubscribes every per-account subscriber tracking a spot market, in parallel. */
     unsubscribeFromSpotMarketAccounts(): Promise<void>;
+    /** Unsubscribes every per-account subscriber tracking an oracle, in parallel. */
     unsubscribeFromOracles(): Promise<void>;
+    /** Fetches the `State` account and every subscribed perp/spot market's `WebSocketAccountSubscriber` in parallel. A no-op if not subscribed. Oracle accounts are not re-fetched here (they update via their own WS notifications). */
     fetch(): Promise<void>;
+    /** Tears down the `State` subscriber and every per-account market/oracle subscriber. A no-op if not subscribed. */
     unsubscribe(): Promise<void>;
+    /**
+     * Adds a spot market (and its oracle, via `setSpotOracleMap`) to be tracked, subscribing a new
+     * `WebSocketAccountSubscriber` for it. 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, subscribing a new
+     * `WebSocketAccountSubscriber` for it. 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, subscribing a new per-account subscriber for it. 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>;
+    /** 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): unsubscribes the per-account subscriber, and
+     * additionally drops it from `perpMarketAccountSubscribers`/`oracleSubscribers` if the setting
+     * is `Discard`. A no-op if the setting is `Subscribe`.
+     */
     handleDelistedMarkets(): Promise<void>;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed(): void;
+    /** Throws `NotSubscribedError` if not subscribed, or a generic `Error` if subscribed but the `State` account hasn't loaded yet (should not normally happen after `subscribe()` resolves). */
     getStateAccountAndSlot(): DataAndSlot<StateAccount>;
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` isn't tracked (or hasn't loaded yet). */
     getMarketAccountAndSlot(marketIndex: number): DataAndSlot<PerpMarketAccount> | undefined;
+    /** Returns every currently cached (loaded) perp market. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots(): DataAndSlot<PerpMarketAccount>[];
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` isn't tracked (or hasn't loaded yet). */
     getSpotMarketAccountAndSlot(marketIndex: number): DataAndSlot<SpotMarketAccount> | undefined;
+    /** Returns every currently cached (loaded) 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 subscriber 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 (or isn't yet in)
+     * `perpOracleMap`, 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 (or isn't yet in)
+     * `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;
 }

package/lib/browser/accounts/webSocketVelocityClientAccountSubscriber.js

@@ -31,7 +31,29 @@ async function ensureAccountFetched(subscriber, maxAttempts = 5, delayMs = 200)
         await new Promise((resolve) => setTimeout(resolve, delayMs));
     }
 }
+/**
+ * Default `VelocityClientAccountSubscriber` implementation: creates one `WebSocketAccountSubscriber`
+ * per tracked `State`/`PerpMarket`/`SpotMarket`/oracle account, giving the lowest update latency
+ * at the cost of one WebSocket subscription per account. Before subscribing each per-account
+ * subscriber, `setInitialData()` batch-fetches all of them via `getMultipleAccountsInfo` so the
+ * per-account `WebSocketAccountSubscriber.subscribe()` calls can seed from that data instead of
+ * each issuing its own `getAccountInfo` round trip. `customPerpMarketAccountSubscriber`/
+ * `customOracleAccountSubscriber` let a caller substitute `WebSocketAccountSubscriberV2` (or any
+ * other `AccountSubscriber` implementation) for those two account types specifically.
+ */
 class WebSocketVelocityClientAccountSubscriber {
+    /**
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @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`.
+     * @param resubOpts Resubscription watchdog options passed to every per-account `WebSocketAccountSubscriber`.
+     * @param commitment Commitment for every per-account subscription; defaults to the provider's configured commitment.
+     * @param customPerpMarketAccountSubscriber Optional alternate `AccountSubscriber` constructor (e.g. `WebSocketAccountSubscriberV2`) used for perp market accounts instead of the default `WebSocketAccountSubscriber`.
+     * @param customOracleAccountSubscriber Optional alternate `AccountSubscriber` constructor used for oracle accounts instead of the default `WebSocketAccountSubscriber`.
+     */
     constructor(program, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting, resubOpts, commitment, customPerpMarketAccountSubscriber, customOracleAccountSubscriber) {
         this.oracleClientCache = new oracleClientCache_1.OracleClientCache();
         this.perpMarketAccountSubscribers = new Map();
@@ -63,6 +85,16 @@ class WebSocketVelocityClientAccountSubscriber {
         this.customPerpMarketAccountSubscriber = customPerpMarketAccountSubscriber;
         this.customOracleAccountSubscriber = customOracleAccountSubscriber;
     }
+    /**
+     * Subscribes the `State` account, batch-seeds all market/oracle accounts via `setInitialData()`,
+     * then subscribes every per-account `WebSocketAccountSubscriber` (or the custom subscriber
+     * class, if configured) for perp markets, spot markets, and oracles. Applies
+     * `delistedMarketSetting` afterward. 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 subscriptions. Always resolves `true` (no retry/failure path — a
+     * per-account fetch failure surfaces via `ensureAccountFetched`'s retries, not by aborting
+     * subscribe).
+     */
     async subscribe() {
         if (this.isSubscribed) {
             return true;
@@ -110,6 +142,14 @@ class WebSocketVelocityClientAccountSubscriber {
         this.removeInitialData();
         return true;
     }
+    /**
+     * Batch-fetches every tracked perp market, spot market, and oracle account via chunked
+     * `getMultipleAccountsInfo` calls (75 pubkeys per chunk) and stashes the decoded results in
+     * `initialPerpMarketAccountData`/`initialSpotMarketAccountData`/`initialOraclePriceData`.
+     * Each per-account `WebSocketAccountSubscriber.subscribe()` call seeds from this data via
+     * `setData` instead of issuing its own `getAccountInfo` round trip. Skips markets already
+     * populated (e.g. by `findAllMarketAndOracles` when `shouldFindAllMarketsAndOracles` is set).
+     */
     async setInitialData() {
         const connection = this.program.provider.connection;
         if (!this.initialPerpMarketAccountData) {
@@ -153,15 +193,24 @@ class WebSocketVelocityClientAccountSubscriber {
             return result;
         }, []));
     }
+    /** Clears the seed data stashed by `setInitialData()` once every per-account subscriber has consumed it, freeing the memory. */
     removeInitialData() {
         this.initialPerpMarketAccountData = new Map();
         this.initialSpotMarketAccountData = new Map();
         this.initialOraclePriceData = new Map();
     }
+    /** Subscribes a `WebSocketAccountSubscriber` for every tracked perp market index, in parallel. */
     async subscribeToPerpMarketAccounts() {
         await Promise.all(this.perpMarketIndexes.map((marketIndex) => this.subscribeToPerpMarketAccount(marketIndex)));
         return true;
     }
+    /**
+     * Creates and subscribes the per-account subscriber (custom class if `customPerpMarketAccountSubscriber`
+     * is set, else `WebSocketAccountSubscriber`) for one perp market, seeding it from
+     * `initialPerpMarketAccountData` if available, and waits (via `ensureAccountFetched`, up to 5
+     * retries with a 200ms backoff) for data to actually land before returning.
+     * @param marketIndex Perp market index to subscribe.
+     */
     async subscribeToPerpMarketAccount(marketIndex) {
         var _a;
         const perpMarketPublicKey = await (0, pda_1.getPerpMarketPublicKey)(this.program.programId, marketIndex);
@@ -179,10 +228,17 @@ class WebSocketVelocityClientAccountSubscriber {
         this.perpMarketAccountSubscribers.set(marketIndex, accountSubscriber);
         return true;
     }
+    /** Subscribes a `WebSocketAccountSubscriber` for every tracked spot market index, in parallel. */
     async subscribeToSpotMarketAccounts() {
         await Promise.all(this.spotMarketIndexes.map((marketIndex) => this.subscribeToSpotMarketAccount(marketIndex)));
         return true;
     }
+    /**
+     * Creates and subscribes a `WebSocketAccountSubscriber` for one spot market, seeding it from
+     * `initialSpotMarketAccountData` if available, and waits (via `ensureAccountFetched`) for data
+     * to land before returning.
+     * @param marketIndex Spot market index to subscribe.
+     */
     async subscribeToSpotMarketAccount(marketIndex) {
         var _a;
         const marketPublicKey = await (0, pda_1.getSpotMarketPublicKey)(this.program.programId, marketIndex);
@@ -199,12 +255,21 @@ class WebSocketVelocityClientAccountSubscriber {
         this.spotMarketAccountSubscribers.set(marketIndex, accountSubscriber);
         return true;
     }
+    /** Subscribes an account subscriber for every tracked oracle, in parallel, skipping the `PublicKey.default` (quote-asset "no oracle") sentinel. */
     async subscribeToOracles() {
         await Promise.all(this.oracleInfos
             .filter((oracleInfo) => !oracleInfo.publicKey.equals(web3_js_1.PublicKey.default))
             .map((oracleInfo) => this.subscribeToOracle(oracleInfo)));
         return true;
     }
+    /**
+     * Creates and subscribes the per-account subscriber (custom class if `customOracleAccountSubscriber`
+     * is set, else `WebSocketAccountSubscriber`) for one oracle, decoding buffers with the
+     * source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available and
+     * waits (via `ensureAccountFetched`) for data to land before returning.
+     * @param oracleInfo Oracle pubkey and source to subscribe.
+     * @returns `false` if no `OracleClient` is registered for `oracleInfo.source`; otherwise `true`.
+     */
     async subscribeToOracle(oracleInfo) {
         var _a;
         const oracleId = (0, oracleId_1.getOracleId)(oracleInfo.publicKey, oracleInfo.source);
@@ -228,15 +293,19 @@ class WebSocketVelocityClientAccountSubscriber {
         this.oracleSubscribers.set(oracleId, accountSubscriber);
         return true;
     }
+    /** Unsubscribes every per-account subscriber tracking a perp market, in parallel. */
     async unsubscribeFromMarketAccounts() {
         await Promise.all(Array.from(this.perpMarketAccountSubscribers.values()).map((accountSubscriber) => accountSubscriber.unsubscribe()));
     }
+    /** Unsubscribes every per-account subscriber tracking a spot market, in parallel. */
     async unsubscribeFromSpotMarketAccounts() {
         await Promise.all(Array.from(this.spotMarketAccountSubscribers.values()).map((accountSubscriber) => accountSubscriber.unsubscribe()));
     }
+    /** Unsubscribes every per-account subscriber tracking an oracle, in parallel. */
     async unsubscribeFromOracles() {
         await Promise.all(Array.from(this.oracleSubscribers.values()).map((accountSubscriber) => accountSubscriber.unsubscribe()));
     }
+    /** Fetches the `State` account and every subscribed perp/spot market's `WebSocketAccountSubscriber` in parallel. A no-op if not subscribed. Oracle accounts are not re-fetched here (they update via their own WS notifications). */
     async fetch() {
         if (!this.isSubscribed) {
             return;
@@ -249,6 +318,7 @@ class WebSocketVelocityClientAccountSubscriber {
             .concat(Array.from(this.spotMarketAccountSubscribers.values()).map((subscriber) => subscriber.fetch()));
         await Promise.all(promises);
     }
+    /** Tears down the `State` subscriber and every per-account market/oracle subscriber. A no-op if not subscribed. */
     async unsubscribe() {
         var _a;
         if (!this.isSubscribed) {
@@ -260,22 +330,38 @@ class WebSocketVelocityClientAccountSubscriber {
         await this.unsubscribeFromOracles();
         this.isSubscribed = false;
     }
+    /**
+     * Adds a spot market (and its oracle, via `setSpotOracleMap`) to be tracked, subscribing a new
+     * `WebSocketAccountSubscriber` for it. Idempotent: returns `true` immediately if already tracked.
+     * @param marketIndex Spot market index to start tracking.
+     */
     async addSpotMarket(marketIndex) {
         if (this.spotMarketAccountSubscribers.has(marketIndex)) {
             return true;
         }
-        const subscriptionSuccess = this.subscribeToSpotMarketAccount(marketIndex);
+        const subscriptionSuccess = await this.subscribeToSpotMarketAccount(marketIndex);
         await this.setSpotOracleMap();
         return subscriptionSuccess;
     }
+    /**
+     * Adds a perp market (and its oracle, via `setPerpOracleMap`) to be tracked, subscribing a new
+     * `WebSocketAccountSubscriber` for it. Idempotent: returns `true` immediately if already tracked.
+     * @param marketIndex Perp market index to start tracking.
+     */
     async addPerpMarket(marketIndex) {
         if (this.perpMarketAccountSubscribers.has(marketIndex)) {
             return true;
         }
-        const subscriptionSuccess = this.subscribeToPerpMarketAccount(marketIndex);
+        const subscriptionSuccess = await this.subscribeToPerpMarketAccount(marketIndex);
         await this.setPerpOracleMap();
         return subscriptionSuccess;
     }
+    /**
+     * Adds an oracle to be tracked, subscribing a new per-account subscriber for it. 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 (this.oracleSubscribers.has(oracleId)) {
@@ -286,6 +372,7 @@ class WebSocketVelocityClientAccountSubscriber {
         }
         return this.subscribeToOracle(oracleInfo);
     }
+    /** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked. */
     async setPerpOracleMap() {
         const perpMarkets = this.getMarketAccountsAndSlots();
         const addOraclePromises = [];
@@ -308,6 +395,7 @@ class WebSocketVelocityClientAccountSubscriber {
         }
         await Promise.all(addOraclePromises);
     }
+    /** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked. */
     async setSpotOracleMap() {
         const spotMarkets = this.getSpotMarketAccountsAndSlots();
         const addOraclePromises = [];
@@ -330,6 +418,12 @@ class WebSocketVelocityClientAccountSubscriber {
         }
         await Promise.all(addOraclePromises);
     }
+    /**
+     * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+     * oracle, if not shared with a live spot market): unsubscribes the per-account subscriber, and
+     * additionally drops it from `perpMarketAccountSubscribers`/`oracleSubscribers` if the setting
+     * is `Discard`. A no-op if the setting is `Subscribe`.
+     */
     async handleDelistedMarkets() {
         var _a, _b;
         if (this.delistedMarketSetting === types_1.DelistedMarketSetting.Subscribe) {
@@ -351,11 +445,13 @@ class WebSocketVelocityClientAccountSubscriber {
             }
         }
     }
+    /** 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, or a generic `Error` if subscribed but the `State` account hasn't loaded yet (should not normally happen after `subscribe()` resolves). */
     getStateAccountAndSlot() {
         var _a;
         this.assertIsSubscribed();
@@ -365,26 +461,37 @@ class WebSocketVelocityClientAccountSubscriber {
         }
         return dataAndSlot;
     }
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` isn't tracked (or hasn't loaded yet). */
     getMarketAccountAndSlot(marketIndex) {
         var _a;
         this.assertIsSubscribed();
         return (_a = this.perpMarketAccountSubscribers.get(marketIndex)) === null || _a === void 0 ? void 0 : _a.dataAndSlot;
     }
+    /** Returns every currently cached (loaded) perp market. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots() {
         return Array.from(this.perpMarketAccountSubscribers.values())
             .map((subscriber) => subscriber.dataAndSlot)
             .filter((dataAndSlot) => dataAndSlot !== undefined);
     }
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` isn't tracked (or hasn't loaded yet). */
     getSpotMarketAccountAndSlot(marketIndex) {
         var _a;
         this.assertIsSubscribed();
         return (_a = this.spotMarketAccountSubscribers.get(marketIndex)) === null || _a === void 0 ? void 0 : _a.dataAndSlot;
     }
+    /** Returns every currently cached (loaded) spot market. Does not throw `NotSubscribedError`. */
     getSpotMarketAccountsAndSlots() {
         return Array.from(this.spotMarketAccountSubscribers.values())
             .map((subscriber) => subscriber.dataAndSlot)
             .filter((dataAndSlot) => dataAndSlot !== undefined);
     }
+    /**
+     * 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 subscriber 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) {
         var _a;
         this.assertIsSubscribed();
@@ -396,6 +503,13 @@ class WebSocketVelocityClientAccountSubscriber {
         }
         return (_a = this.oracleSubscribers.get(oracleId)) === null || _a === void 0 ? void 0 : _a.dataAndSlot;
     }
+    /**
+     * 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 (or isn't yet in)
+     * `perpOracleMap`, 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);
@@ -409,6 +523,13 @@ class WebSocketVelocityClientAccountSubscriber {
         }
         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 (or isn't yet in)
+     * `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);