@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/node/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,36 +49,147 @@ 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;
 }
 //# sourceMappingURL=webSocketVelocityClientAccountSubscriber.d.ts.map

package/lib/node/accounts/webSocketVelocityClientAccountSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webSocketVelocityClientAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/webSocketVelocityClientAccountSubscriber.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webSocketVelocityClientAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/webSocketVelocityClientAccountSubscriber.ts"],"names":[],"mappings":"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"}

package/lib/node/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);

package/lib/node/accounts/webSocketVelocityClientAccountSubscriberV2.d.ts

@@ -10,6 +10,15 @@ import { OracleClientCache } from '../oracles/oracleClientCache';
 import { VelocityProgram } from '../config';
 import { WebSocketProgramAccountsSubscriberV2 } from './webSocketProgramAccountsSubscriberV2';
 import { WebSocketAccountSubscriberV2 } from './webSocketAccountSubscriberV2';
+/**
+ * `VelocityClientAccountSubscriber` variant that, unlike `WebSocketVelocityClientAccountSubscriber`
+ * (one `WebSocketAccountSubscriber` per market), multiplexes all perp markets onto a single
+ * `WebSocketProgramAccountsSubscriberV2` program-account stream and all spot markets onto a
+ * second — two WebSocket subscriptions total instead of one per market. `State` and each oracle
+ * still get their own `WebSocketAccountSubscriberV2`. Lower connection overhead at scale;
+ * `addPerpMarket`/`addSpotMarket` are no-ops here since new markets simply arrive automatically
+ * over the existing program-account stream rather than needing an explicit new subscription.
+ */
 export declare class WebSocketVelocityClientAccountSubscriberV2 implements VelocityClientAccountSubscriber {
     isSubscribed: boolean;
     program: VelocityProgram;
@@ -45,9 +54,30 @@ export declare class WebSocketVelocityClientAccountSubscriberV2 implements Veloc
     protected subscriptionPromise: Promise<boolean>;
     private rpc;
     private rpcSubscriptions;
+    /**
+     * @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. Only used to derive the initial pubkeys handed to the perp program-account subscriber; new markets arrive automatically thereafter.
+     * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false. Same caveat as `perpMarketIndexes`.
+     * @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 the underlying program-account and per-oracle subscribers.
+     * @param commitment Commitment for every subscription; defaults to the provider's configured commitment.
+     * @param skipInitialData Currently unused by `subscribe()`/`setInitialData()` (the field is set but never read); defaults to `false`.
+     */
     constructor(program: VelocityProgram, perpMarketIndexes: number[], spotMarketIndexes: number[], oracleInfos: OracleInfo[], shouldFindAllMarketsAndOracles: boolean, delistedMarketSetting: DelistedMarketSetting, resubOpts?: ResubOpts, commitment?: Commitment, skipInitialData?: boolean);
+    /**
+     * Derives all tracked perp/spot market pubkeys (or discovers them via `findAllMarketAndOracles`
+     * if `shouldFindAllMarketsAndOracles` is set), then in parallel: opens the perp and spot
+     * `WebSocketProgramAccountsSubscriberV2` streams, subscribes the `State` account, and seeds +
+     * subscribes every oracle. 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.
+     * @returns `true` on success; `false` if any step throws (subscription state is left partially applied in that case, and `isSubscribed` remains `false`).
+     */
     subscribe(): Promise<boolean>;
     chunks: <T>(array: readonly T[], size: number) => T[][];
+    /** Re-runs `setInitialData()`, re-fetching and re-emitting oracle price data. Does not re-fetch perp/spot market or `State` accounts — those are kept current via their live WebSocket streams. */
     fetch(): Promise<void>;
     /**
      * This is a no-op method that always returns true.
@@ -67,26 +97,92 @@ export declare class WebSocketVelocityClientAccountSubscriberV2 implements Veloc
      * @returns Promise that resolves to true
      */
     addSpotMarket(_marketIndex: number): Promise<boolean>;
+    /**
+     * Batch-fetches every tracked oracle account via chunked `getMultipleAccountsInfo` calls (100
+     * pubkeys per chunk), decodes each with the source-appropriate `OracleClient`, stashes the
+     * results in `initialOraclePriceData`, and immediately emits `oraclePriceUpdate`/`update` for
+     * each. Unlike the v1 subscriber's `setInitialData`, does not seed perp/spot market data —
+     * those markets are seeded directly by the program-account subscribers' own initial-account
+     * list instead.
+     */
     setInitialData(): Promise<void>;
+    /** Clears the seed data stashed by `setInitialData()`/`findAllMarketAndOracles` once consumed, freeing the memory. */
     removeInitialData(): void;
+    /** Subscribes a `WebSocketAccountSubscriberV2` for every tracked oracle not already subscribed, in parallel, skipping duplicates already present in `oracleSubscribers`. */
     subscribeToOracles(): Promise<boolean>;
+    /**
+     * Creates and subscribes a `WebSocketAccountSubscriberV2` for one oracle, decoding buffers
+     * with the source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available
+     * before subscribing.
+     * @param oracleInfo Oracle pubkey and source to subscribe.
+     * @returns `false` if no `OracleClient` is registered for `oracleInfo.source` or the subscribe call throws; otherwise `true`.
+     */
     subscribeToOracle(oracleInfo: OracleInfo): Promise<boolean>;
+    /** Unsubscribes the single multiplexed perp-market program-account stream. */
     unsubscribeFromMarketAccounts(): Promise<void>;
+    /** Unsubscribes the single multiplexed spot-market program-account stream. */
     unsubscribeFromSpotMarketAccounts(): Promise<void>;
+    /** Unsubscribes every per-oracle `WebSocketAccountSubscriberV2`, in parallel. */
     unsubscribeFromOracles(): Promise<void>;
+    /** Tears down the `State` subscriber, both market program-account streams, and every oracle subscriber. A no-op if not subscribed. */
     unsubscribe(): Promise<void>;
+    /**
+     * Adds an oracle to be tracked, subscribing a new `WebSocketAccountSubscriberV2` 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 oracle backing a currently `status: delisted` perp
+     * market (and not still used by a live spot market, per `findDelistedPerpMarketsAndOracles`):
+     * unsubscribes the oracle's subscriber, and additionally drops it from `oracleSubscribers` if
+     * the setting is `Discard`. A no-op if the setting is `Subscribe`. Note this only manages
+     * oracle subscriptions — delisted market accounts themselves cannot be selectively unsubscribed
+     * from the shared perp/spot program-account stream; instead the `subscribe()` update callback
+     * drops any incoming update for a `status: delisted` market unless `delistedMarketSetting` is
+     * `Subscribe`, freezing that market's cached data at its last pre-delisting state.
+     */
     handleDelistedMarketOracles(): Promise<void>;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed(): void;
+    /** Throws `NotSubscribedError` if not subscribed, or a generic `Error` (via `assertDataAndSlot`) if subscribed but the `State` account hasn't loaded yet. */
     getStateAccountAndSlot(): DataAndSlot<StateAccount>;
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` hasn't been observed yet on the perp program-account stream. */
     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` hasn't been observed yet on the spot program-account stream. */
     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;
 }
 //# sourceMappingURL=webSocketVelocityClientAccountSubscriberV2.d.ts.map