@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/browser/accounts/grpcVelocityClientAccountSubscriber.js

@@ -6,11 +6,34 @@ const config_1 = require("../config");
 const pda_1 = require("../addresses/pda");
 const grpcAccountSubscriber_1 = require("./grpcAccountSubscriber");
 const oracleId_1 = require("../oracles/oracleId");
+/**
+ * `VelocityClientAccountSubscriber` variant of `WebSocketVelocityClientAccountSubscriber` that
+ * subscribes each per-account subscriber via `grpcAccountSubscriber.create` (gRPC Geyser stream)
+ * instead of `connection.onAccountChange`. Reuses the parent class's `setInitialData`/oracle-map/
+ * delisted-market logic verbatim; only the account-subscription creation is overridden.
+ */
 class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccountSubscriber_1.WebSocketVelocityClientAccountSubscriber {
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @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.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing.
+     * @param resubOpts Resubscription watchdog options passed to every per-account subscriber.
+     */
     constructor(grpcConfigs, program, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting, resubOpts) {
         super(program, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting, resubOpts);
         this.grpcConfigs = grpcConfigs;
     }
+    /**
+     * Subscribes the `State` account via gRPC, batch-seeds all market/oracle accounts via
+     * `setInitialData()` (inherited RPC-based batch fetch), then subscribes every per-account gRPC
+     * subscriber 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`.
+     */
     async subscribe() {
         if (this.isSubscribed) {
             return true;
@@ -59,6 +82,11 @@ class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccount
         this.removeInitialData();
         return true;
     }
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one spot market, seeding it from
+     * `initialSpotMarketAccountData` if available.
+     * @param marketIndex Spot market index to subscribe.
+     */
     async subscribeToSpotMarketAccount(marketIndex) {
         var _a;
         const marketPublicKey = await (0, pda_1.getSpotMarketPublicKey)(this.program.programId, marketIndex);
@@ -74,6 +102,13 @@ class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccount
         this.spotMarketAccountSubscribers.set(marketIndex, accountSubscriber);
         return true;
     }
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one perp market, seeding it from
+     * `initialPerpMarketAccountData` if available. Unlike the parent class's WebSocket variant,
+     * does not call `ensureAccountFetched` — the gRPC subscriber's own initial `fetch()` (inside
+     * `subscribe`) is relied on directly.
+     * @param marketIndex Perp market index to subscribe.
+     */
     async subscribeToPerpMarketAccount(marketIndex) {
         var _a;
         const perpMarketPublicKey = await (0, pda_1.getPerpMarketPublicKey)(this.program.programId, marketIndex);
@@ -89,6 +124,12 @@ class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccount
         this.perpMarketAccountSubscribers.set(marketIndex, accountSubscriber);
         return true;
     }
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one oracle, decoding buffers with the
+     * source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available.
+     * @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);

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

@@ -7,6 +7,15 @@ import { VelocityProgram } from '../config';
 import { AccountSubscriber, DataAndSlot, DelistedMarketSetting, VelocityClientAccountEvents, VelocityClientAccountSubscriber, GrpcConfigs, ResubOpts } from './types';
 import { PerpMarketAccount, SpotMarketAccount, StateAccount } from '../types';
 import { OracleClientCache } from '../oracles/oracleClientCache';
+/**
+ * `VelocityClientAccountSubscriber` variant that, unlike `grpcVelocityClientAccountSubscriber`
+ * (one gRPC stream per account), multiplexes all perp markets onto one `grpcMultiAccountSubscriber`,
+ * all spot markets onto a second, and all oracles onto a third — three gRPC streams total instead
+ * of one per account. Lower connection/stream overhead at scale; `getOraclePriceDataAndSlot`
+ * relies on this class's own `oracleIdToOracleDataMap` rather than the multi-subscriber's account
+ * map, since a single oracle pubkey can back multiple `(pubkey, source)` oracle ids (e.g. a market
+ * pair sharing an underlying price feed).
+ */
 export declare class grpcVelocityClientAccountSubscriberV2 implements VelocityClientAccountSubscriber {
     private grpcConfigs;
     private perpMarketsSubscriber?;
@@ -36,30 +45,137 @@ export declare class grpcVelocityClientAccountSubscriberV2 implements VelocityCl
     private resubOpts?;
     private subscriptionPromiseResolver;
     private subscriptionPromise;
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @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.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing.
+     * @param resubOpts Resubscription watchdog options passed to the underlying multi-account subscribers.
+     */
     constructor(grpcConfigs: GrpcConfigs, program: VelocityProgram, perpMarketIndexes: number[], spotMarketIndexes: number[], oracleInfos: OracleInfo[], shouldFindAllMarketsAndOracles: boolean, delistedMarketSetting: DelistedMarketSetting, resubOpts?: ResubOpts);
     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`, which
+     * the multi-account subscribers seed from before their gRPC streams deliver live data. Skips
+     * data already populated (e.g. by `findAllMarketAndOracles` when `shouldFindAllMarketsAndOracles`
+     * is set).
+     */
     setInitialData(): Promise<void>;
+    /**
+     * Records `_marketIndex` in `perpMarketIndexes` for bookkeeping. Note this does **not**
+     * actually add the account to the live `perpMarketsSubscriber` gRPC stream — unlike the
+     * WebSocket/per-account subscribers' `addPerpMarket`, no new subscription is created here.
+     * @param _marketIndex Perp market index to record.
+     */
     addPerpMarket(_marketIndex: number): Promise<boolean>;
+    /** No-op; unlike `addPerpMarket`, does not even record the index. Always resolves `true`. */
     addSpotMarket(_marketIndex: number): Promise<boolean>;
+    /**
+     * Adds an oracle to `oracleInfos` and, if the oracle multi-subscriber's gRPC stream is already
+     * active, calls `oracleMultiSubscriber.addAccounts` to extend 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>;
+    /**
+     * Subscribes the `State` account (single-account gRPC subscriber), batch-seeds all market/
+     * oracle accounts via `setInitialData()`, then opens the three multiplexed
+     * `grpcMultiAccountSubscriber` streams (perp markets, spot markets, 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`.
+     */
     subscribe(): Promise<boolean>;
+    private subscribeInner;
+    /** Fetches the `State` account and all three multiplexed subscribers (perp markets, spot markets, oracles) in sequence. */
     fetch(): Promise<void>;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     private assertIsSubscribed;
+    /** Throws `NotSubscribedError` if not subscribed. */
     getStateAccountAndSlot(): DataAndSlot<StateAccount>;
+    /** Returns every currently cached (loaded) perp market from the multiplexed subscriber. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots(): DataAndSlot<PerpMarketAccount>[];
+    /** Returns every currently cached (loaded) spot market from the multiplexed subscriber. Does not throw `NotSubscribedError`. */
     getSpotMarketAccountsAndSlots(): DataAndSlot<SpotMarketAccount>[];
+    /** 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 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;
+    /**
+     * Looks up cached oracle price data by oracle id (see `getOracleId`), from this class's own
+     * `oracleIdToOracleDataMap` rather than `oracleMultiSubscriber.getAccountData` — a single
+     * oracle pubkey backing multiple oracle ids (e.g. shared price feeds) means the multi-subscriber's
+     * own account map cannot be trusted to disambiguate them correctly.
+     * @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;
+    /** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked by `oracleMultiSubscriber`. */
     setPerpOracleMap(): Promise<void>;
+    /** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked by `oracleMultiSubscriber`. */
     setSpotOracleMap(): Promise<void>;
+    /**
+     * Creates `perpMarketsSubscriber` (a `grpcMultiAccountSubscriber<PerpMarketAccount>`), seeds
+     * it with `initialPerpMarketAccountData`, and subscribes it to every tracked perp market
+     * pubkey in one gRPC stream. Registers an `onUnsubscribe` handler that automatically
+     * re-invokes this method to resubscribe if the underlying stream drops.
+     */
     subscribeToPerpMarketAccounts(): Promise<boolean>;
+    /**
+     * Creates `spotMarketsSubscriber` (a `grpcMultiAccountSubscriber<SpotMarketAccount>`), seeds
+     * it with `initialSpotMarketAccountData`, and subscribes it to every tracked spot market
+     * pubkey in one gRPC stream. Registers an `onUnsubscribe` handler that automatically
+     * re-invokes this method to resubscribe if the underlying stream drops.
+     */
     subscribeToSpotMarketAccounts(): Promise<boolean>;
+    /**
+     * Creates `oracleMultiSubscriber` (a `grpcMultiAccountSubscriber<OraclePriceData, OracleInfo>`)
+     * and subscribes it to every distinct oracle pubkey in one gRPC stream, decoding buffers with
+     * the source-appropriate `OracleClient`. Because multiple `(pubkey, source)` oracle ids can
+     * share one pubkey, `oraclePubkeyToInfosMap` fans a single decode out to every matching
+     * `OracleInfo`, and results are additionally indexed into `oracleIdToOracleDataMap` (by oracle
+     * id, not pubkey) for `getOraclePriceDataAndSlot` to read. Registers an `onUnsubscribe` handler
+     * that automatically re-invokes this method to resubscribe if the underlying stream drops.
+     */
     subscribeToOracles(): Promise<boolean>;
+    /**
+     * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+     * oracle, if not shared with a live spot market) by removing its pubkey from the relevant
+     * `grpcMultiAccountSubscriber` via `removeAccounts`. A no-op if the setting is `Subscribe`.
+     * Unlike the WebSocket/polling variants, this does not distinguish `Unsubscribe` from
+     * `Discard` — both remove the account from the multiplexed stream (there is no per-account
+     * "keep last known data, stop streaming" state to preserve at this granularity).
+     */
     handleDelistedMarkets(): Promise<void>;
+    /** Clears the seed data stashed by `setInitialData()` once the multi-account subscribers have consumed it, freeing the memory. */
     removeInitialData(): void;
+    /** Tears down `oracleMultiSubscriber`'s gRPC stream, if active, and clears the reference. */
     unsubscribeFromOracles(): Promise<void>;
+    /**
+     * Tears down the `State` subscriber and all three multiplexed subscribers (perp markets, spot
+     * markets, oracles), then clears every internal map to avoid holding stale references. A no-op
+     * if not subscribed.
+     */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/accounts/grpcVelocityClientAccountSubscriberV2.js

@@ -11,7 +11,26 @@ const grpcMultiAccountSubscriber_1 = require("./grpcMultiAccountSubscriber");
 const oracleId_1 = require("../oracles/oracleId");
 const oracleClientCache_1 = require("../oracles/oracleClientCache");
 const utils_1 = require("./utils");
+/**
+ * `VelocityClientAccountSubscriber` variant that, unlike `grpcVelocityClientAccountSubscriber`
+ * (one gRPC stream per account), multiplexes all perp markets onto one `grpcMultiAccountSubscriber`,
+ * all spot markets onto a second, and all oracles onto a third — three gRPC streams total instead
+ * of one per account. Lower connection/stream overhead at scale; `getOraclePriceDataAndSlot`
+ * relies on this class's own `oracleIdToOracleDataMap` rather than the multi-subscriber's account
+ * map, since a single oracle pubkey can back multiple `(pubkey, source)` oracle ids (e.g. a market
+ * pair sharing an underlying price feed).
+ */
 class grpcVelocityClientAccountSubscriberV2 {
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @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.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing.
+     * @param resubOpts Resubscription watchdog options passed to the underlying multi-account subscribers.
+     */
     constructor(grpcConfigs, program, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting, resubOpts) {
         this.perpMarketIndexToAccountPubkeyMap = new Map();
         this.spotMarketIndexToAccountPubkeyMap = new Map();
@@ -48,6 +67,14 @@ class grpcVelocityClientAccountSubscriberV2 {
         this.resubOpts = resubOpts;
         this.delistedMarketSetting = delistedMarketSetting;
     }
+    /**
+     * 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`, which
+     * the multi-account subscribers seed from before their gRPC streams deliver live data. Skips
+     * data already populated (e.g. by `findAllMarketAndOracles` when `shouldFindAllMarketsAndOracles`
+     * is set).
+     */
     async setInitialData() {
         const connection = this.program.provider.connection;
         if (!this.initialPerpMarketAccountData ||
@@ -93,15 +120,29 @@ class grpcVelocityClientAccountSubscriberV2 {
             return result;
         }, []));
     }
+    /**
+     * Records `_marketIndex` in `perpMarketIndexes` for bookkeeping. Note this does **not**
+     * actually add the account to the live `perpMarketsSubscriber` gRPC stream — unlike the
+     * WebSocket/per-account subscribers' `addPerpMarket`, no new subscription is created here.
+     * @param _marketIndex Perp market index to record.
+     */
     async addPerpMarket(_marketIndex) {
         if (!this.perpMarketIndexes.includes(_marketIndex)) {
             this.perpMarketIndexes = this.perpMarketIndexes.concat(_marketIndex);
         }
         return true;
     }
+    /** No-op; unlike `addPerpMarket`, does not even record the index. Always resolves `true`. */
     async addSpotMarket(_marketIndex) {
         return true;
     }
+    /**
+     * Adds an oracle to `oracleInfos` and, if the oracle multi-subscriber's gRPC stream is already
+     * active, calls `oracleMultiSubscriber.addAccounts` to extend 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) {
         var _a, _c;
         if ((_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.logResubMessages) {
@@ -116,10 +157,26 @@ class grpcVelocityClientAccountSubscriberV2 {
             return true; // Already exists, don't add duplicate
         }
         this.oracleInfos = this.oracleInfos.concat(oracleInfo);
-        (_c = this.oracleMultiSubscriber) === null || _c === void 0 ? void 0 : _c.addAccounts([oracleInfo.publicKey]);
+        // extend the multi-subscriber's accountPropsMap alongside the pubkey filter, so the
+        // oracle decode path has the OracleInfo(s) it needs for the newly added feed (all infos
+        // sharing this pubkey, mirroring the fan-out map built in subscribeToOracles)
+        const pubkey = oracleInfo.publicKey.toBase58();
+        const infosForPubkey = this.oracleInfos.filter((o) => o.publicKey.toBase58() === pubkey);
+        const accountProps = new Map([
+            [pubkey, infosForPubkey],
+        ]);
+        (_c = this.oracleMultiSubscriber) === null || _c === void 0 ? void 0 : _c.addAccounts([oracleInfo.publicKey], accountProps);
         return true;
     }
+    /**
+     * Subscribes the `State` account (single-account gRPC subscriber), batch-seeds all market/
+     * oracle accounts via `setInitialData()`, then opens the three multiplexed
+     * `grpcMultiAccountSubscriber` streams (perp markets, spot markets, 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`.
+     */
     async subscribe() {
+        var _a, _c, _d, _e;
         if (this.isSubscribed) {
             return true;
         }
@@ -130,6 +187,33 @@ class grpcVelocityClientAccountSubscriberV2 {
         this.subscriptionPromise = new Promise((res) => {
             this.subscriptionPromiseResolver = res;
         });
+        try {
+            return await this.subscribeInner();
+        }
+        catch (err) {
+            // tear down any partially-created subscribers so a retry starts clean and doesn't
+            // stack duplicate gRPC streams / leak callbacks — unsubscribe() bails while
+            // isSubscribed is still false, so it can't recover these on its own
+            try {
+                await ((_a = this.stateAccountSubscriber) === null || _a === void 0 ? void 0 : _a.unsubscribe());
+                await ((_c = this.oracleMultiSubscriber) === null || _c === void 0 ? void 0 : _c.unsubscribe());
+                await ((_d = this.perpMarketsSubscriber) === null || _d === void 0 ? void 0 : _d.unsubscribe());
+                await ((_e = this.spotMarketsSubscriber) === null || _e === void 0 ? void 0 : _e.unsubscribe());
+            }
+            catch (teardownErr) {
+                console.error('[grpcVelocityClientAccountSubscriberV2] cleanup after failed subscribe threw', teardownErr);
+            }
+            this.stateAccountSubscriber = undefined;
+            this.oracleMultiSubscriber = undefined;
+            this.perpMarketsSubscriber = undefined;
+            this.spotMarketsSubscriber = undefined;
+            // settle the shared promise so concurrent subscribe() callers don't hang forever
+            this.isSubscribing = false;
+            this.subscriptionPromiseResolver(false);
+            throw err;
+        }
+    }
+    async subscribeInner() {
         if (this.shouldFindAllMarketsAndOracles) {
             const { perpMarketIndexes, perpMarketAccounts, spotMarketIndexes, spotMarketAccounts, oracleInfos, } = await (0, config_1.findAllMarketAndOracles)(this.program);
             this.perpMarketIndexes = perpMarketIndexes;
@@ -165,6 +249,7 @@ class grpcVelocityClientAccountSubscriberV2 {
         this.removeInitialData();
         return true;
     }
+    /** Fetches the `State` account and all three multiplexed subscribers (perp markets, spot markets, oracles) in sequence. */
     async fetch() {
         var _a, _c, _d, _e;
         await ((_a = this.stateAccountSubscriber) === null || _a === void 0 ? void 0 : _a.fetch());
@@ -172,25 +257,30 @@ class grpcVelocityClientAccountSubscriberV2 {
         await ((_d = this.spotMarketsSubscriber) === null || _d === void 0 ? void 0 : _d.fetch());
         await ((_e = this.oracleMultiSubscriber) === null || _e === void 0 ? void 0 : _e.fetch());
     }
+    /** 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.stateAccountSubscriber.dataAndSlot;
     }
+    /** Returns every currently cached (loaded) perp market from the multiplexed subscriber. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots() {
         var _a, _c;
         const map = (_a = this.perpMarketsSubscriber) === null || _a === void 0 ? void 0 : _a.getAccountDataMap();
         return Array.from((_c = map === null || map === void 0 ? void 0 : map.values()) !== null && _c !== void 0 ? _c : []);
     }
+    /** Returns every currently cached (loaded) spot market from the multiplexed subscriber. Does not throw `NotSubscribedError`. */
     getSpotMarketAccountsAndSlots() {
         var _a, _c;
         const map = (_a = this.spotMarketsSubscriber) === null || _a === void 0 ? void 0 : _a.getAccountDataMap();
         return Array.from((_c = map === null || map === void 0 ? void 0 : map.values()) !== null && _c !== void 0 ? _c : []);
     }
+    /** Returns the cached perp market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getMarketAccountAndSlot(marketIndex) {
         var _a;
         const accountPubkey = this.perpMarketIndexToAccountPubkeyMap.get(marketIndex);
@@ -199,6 +289,7 @@ class grpcVelocityClientAccountSubscriberV2 {
         }
         return (_a = this.perpMarketsSubscriber) === null || _a === void 0 ? void 0 : _a.getAccountData(accountPubkey);
     }
+    /** Returns the cached spot market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getSpotMarketAccountAndSlot(marketIndex) {
         var _a;
         const accountPubkey = this.spotMarketIndexToAccountPubkeyMap.get(marketIndex);
@@ -207,12 +298,27 @@ class grpcVelocityClientAccountSubscriberV2 {
         }
         return (_a = this.spotMarketsSubscriber) === null || _a === void 0 ? void 0 : _a.getAccountData(accountPubkey);
     }
+    /**
+     * Looks up cached oracle price data by oracle id (see `getOracleId`), from this class's own
+     * `oracleIdToOracleDataMap` rather than `oracleMultiSubscriber.getAccountData` — a single
+     * oracle pubkey backing multiple oracle ids (e.g. shared price feeds) means the multi-subscriber's
+     * own account map cannot be trusted to disambiguate them correctly.
+     * @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();
         // we need to rely on a map we store in this class because the grpcMultiAccountSubscriber does not track a mapping or oracle ID.
         // DO NOT call getAccountData on the oracleMultiSubscriber, it will not return the correct data in certain cases(BONK spot and perp market subscribed too at once).
         return this.oracleIdToOracleDataMap.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 (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);
@@ -226,6 +332,13 @@ class grpcVelocityClientAccountSubscriberV2 {
         }
         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);
@@ -239,6 +352,7 @@ class grpcVelocityClientAccountSubscriberV2 {
         }
         return this.getOraclePriceDataAndSlot(oracleId);
     }
+    /** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked by `oracleMultiSubscriber`. */
     async setPerpOracleMap() {
         var _a, _c, _d;
         const perpMarketsMap = (_a = this.perpMarketsSubscriber) === null || _a === void 0 ? void 0 : _a.getAccountDataMap();
@@ -263,6 +377,7 @@ class grpcVelocityClientAccountSubscriberV2 {
         }
         await Promise.all(addOraclePromises);
     }
+    /** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked by `oracleMultiSubscriber`. */
     async setSpotOracleMap() {
         var _a, _c, _d;
         const spotMarketsMap = (_a = this.spotMarketsSubscriber) === null || _a === void 0 ? void 0 : _a.getAccountDataMap();
@@ -287,6 +402,12 @@ class grpcVelocityClientAccountSubscriberV2 {
         }
         await Promise.all(addOraclePromises);
     }
+    /**
+     * Creates `perpMarketsSubscriber` (a `grpcMultiAccountSubscriber<PerpMarketAccount>`), seeds
+     * it with `initialPerpMarketAccountData`, and subscribes it to every tracked perp market
+     * pubkey in one gRPC stream. Registers an `onUnsubscribe` handler that automatically
+     * re-invokes this method to resubscribe if the underlying stream drops.
+     */
     async subscribeToPerpMarketAccounts() {
         var _a;
         if ((_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.logResubMessages) {
@@ -322,6 +443,12 @@ class grpcVelocityClientAccountSubscriberV2 {
         });
         return true;
     }
+    /**
+     * Creates `spotMarketsSubscriber` (a `grpcMultiAccountSubscriber<SpotMarketAccount>`), seeds
+     * it with `initialSpotMarketAccountData`, and subscribes it to every tracked spot market
+     * pubkey in one gRPC stream. Registers an `onUnsubscribe` handler that automatically
+     * re-invokes this method to resubscribe if the underlying stream drops.
+     */
     async subscribeToSpotMarketAccounts() {
         var _a;
         if ((_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.logResubMessages) {
@@ -357,6 +484,15 @@ class grpcVelocityClientAccountSubscriberV2 {
         });
         return true;
     }
+    /**
+     * Creates `oracleMultiSubscriber` (a `grpcMultiAccountSubscriber<OraclePriceData, OracleInfo>`)
+     * and subscribes it to every distinct oracle pubkey in one gRPC stream, decoding buffers with
+     * the source-appropriate `OracleClient`. Because multiple `(pubkey, source)` oracle ids can
+     * share one pubkey, `oraclePubkeyToInfosMap` fans a single decode out to every matching
+     * `OracleInfo`, and results are additionally indexed into `oracleIdToOracleDataMap` (by oracle
+     * id, not pubkey) for `getOraclePriceDataAndSlot` to read. Registers an `onUnsubscribe` handler
+     * that automatically re-invokes this method to resubscribe if the underlying stream drops.
+     */
     async subscribeToOracles() {
         var _a;
         if ((_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.logResubMessages) {
@@ -418,6 +554,14 @@ class grpcVelocityClientAccountSubscriberV2 {
         });
         return true;
     }
+    /**
+     * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+     * oracle, if not shared with a live spot market) by removing its pubkey from the relevant
+     * `grpcMultiAccountSubscriber` via `removeAccounts`. A no-op if the setting is `Subscribe`.
+     * Unlike the WebSocket/polling variants, this does not distinguish `Unsubscribe` from
+     * `Discard` — both remove the account from the multiplexed stream (there is no per-account
+     * "keep last known data, stop streaming" state to preserve at this granularity).
+     */
     async handleDelistedMarkets() {
         var _a, _c, _d, _e;
         if (this.delistedMarketSetting === types_1.DelistedMarketSetting.Subscribe) {
@@ -442,11 +586,13 @@ class grpcVelocityClientAccountSubscriberV2 {
             await ((_e = this.oracleMultiSubscriber) === null || _e === void 0 ? void 0 : _e.removeAccounts(oraclePubkeysToRemove));
         }
     }
+    /** Clears the seed data stashed by `setInitialData()` once the multi-account subscribers have consumed it, freeing the memory. */
     removeInitialData() {
         this.initialPerpMarketAccountData = new Map();
         this.initialSpotMarketAccountData = new Map();
         this.initialOraclePriceData = new Map();
     }
+    /** Tears down `oracleMultiSubscriber`'s gRPC stream, if active, and clears the reference. */
     async unsubscribeFromOracles() {
         if (this.oracleMultiSubscriber) {
             await this.oracleMultiSubscriber.unsubscribe();
@@ -454,6 +600,11 @@ class grpcVelocityClientAccountSubscriberV2 {
             return;
         }
     }
+    /**
+     * Tears down the `State` subscriber and all three multiplexed subscribers (perp markets, spot
+     * markets, oracles), then clears every internal map to avoid holding stale references. A no-op
+     * if not subscribed.
+     */
     async unsubscribe() {
         var _a, _c, _d;
         if (!this.isSubscribed) {

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

@@ -6,6 +6,14 @@ import { VelocityProgram } from '../config';
 import { WebSocketProgramAccountSubscriber } from './webSocketProgramAccountSubscriber';
 import { LaserCommitmentLevel } from '../isomorphic/grpc';
 type LaserCommitment = (typeof LaserCommitmentLevel)[keyof typeof LaserCommitmentLevel];
+/**
+ * `ProgramAccountSubscriber` that streams every account owned by the program (optionally filtered
+ * by `memcmp`) via Helius LaserStream instead of `connection.onProgramAccountChange`. Extends
+ * `WebSocketProgramAccountSubscriber` to reuse its per-account buffering/decode/resub-timer logic
+ * (`handleRpcResponse`, `bufferAndSlotMap`) — only the transport (`subscribe`/`unsubscribe`) is
+ * replaced. Construct via the static `create` factory, not the constructor directly, since it
+ * dynamically loads the optional `helius-laserstream` peer dependency and its enums.
+ */
 export declare class LaserstreamProgramAccountSubscriber<T> extends WebSocketProgramAccountSubscriber<T> {
     private stream;
     private commitmentLevel;
@@ -13,11 +21,37 @@ export declare class LaserstreamProgramAccountSubscriber<T> extends WebSocketPro
     private readonly laserConfig;
     private readonly laserCommitmentLevel;
     private constructor();
+    /**
+     * Loads the optional `helius-laserstream` module, builds its `LaserstreamConfig` (forcing zstd
+     * compression and a 1GB max receive message size), and constructs a
+     * `LaserstreamProgramAccountSubscriber`. Does not itself start streaming — call
+     * `subscribe(onChange)` on the result.
+     * @param grpcConfigs LaserStream endpoint/token/commitment config; `enableReconnect` maps to up to 10 reconnect attempts (0 if unset).
+     * @param subscriptionName Human-readable name for logging.
+     * @param accountDiscriminator Anchor account type name passed to `decodeBufferFn` for each update.
+     * @param program Anchor program whose accounts to stream (filtered to `program.programId` as owner).
+     * @param decodeBufferFn Decode function for each account's raw buffer.
+     * @param options `filters` (memcmp) narrowing which program accounts are streamed; empty streams every account owned by the program.
+     * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+     */
     static create<U>(grpcConfigs: LaserGrpcConfigs, subscriptionName: string, accountDiscriminator: string, program: VelocityProgram, decodeBufferFn: (accountName: string, ix: Buffer) => U, options?: {
         filters: MemcmpFilter[];
     }, resubOpts?: ResubOpts): Promise<LaserstreamProgramAccountSubscriber<U>>;
+    /**
+     * Opens a LaserStream `accounts` subscription filtered to `program.programId` as owner
+     * (further narrowed by the `filters` passed to `create`). Idempotent: a no-op if already
+     * subscribed or mid-unsubscribe. Does not perform an initial fetch — the caller must fetch any
+     * pre-existing matching accounts separately if needed. Throws if the LaserStream client fails
+     * to start.
+     * @param onChange Invoked once per changed account with its pubkey, decoded data, the notification's `Context` (slot only), and the raw buffer.
+     */
     subscribe(onChange: (accountId: PublicKey, data: T, context: Context, buffer: Buffer) => void): Promise<void>;
+    /**
+     * Cancels the LaserStream and clears any pending resub timeout.
+     * @param onResub Internal flag set to `true` when called as part of an automatic resubscribe cycle, which preserves `resubOpts.resubTimeoutMs` instead of clearing it. Callers should omit this.
+     */
     unsubscribe(onResub?: boolean): Promise<void>;
+    /** Coerces a commitment level (string name, numeric enum value, or undefined) into a LaserStream `LaserCommitmentLevel`, defaulting to `CONFIRMED`. */
     toLaserCommitment(level: string | number | undefined): LaserCommitment;
 }
 export {};