@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/node/accounts/pollingVelocityClientAccountSubscriber.js

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

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"testBulkAccountLoader.d.ts","sourceRoot":"","sources":["../../../src/accounts/testBulkAccountLoader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEvE,qBAAa,qBAAsB,SAAQ,iBAAiB;IACrD,SAAS,CAAC,oBAAoB,EAAE,aAAa,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA+CvE"}
+{"version":3,"file":"testBulkAccountLoader.d.ts","sourceRoot":"","sources":["../../../src/accounts/testBulkAccountLoader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,iBAAiB;IAC3D,4QAA4Q;IACtQ,SAAS,CAAC,oBAAoB,EAAE,aAAa,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CA+CvE"}

package/lib/node/accounts/testBulkAccountLoader.js

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

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

@@ -19,20 +19,69 @@ import { Account } from '@solana/spl-token';
 import { OracleInfo, OraclePriceData } from '../oracles/types';
 import { User } from '../user';
 import { Client, CommitmentLevel, LaserstreamConfig } from '../isomorphic/grpc';
+/**
+ * Common contract for a subscriber that tracks a single on-chain account of type `T`.
+ * Implemented by the `WebSocketAccountSubscriber`/`WebSocketAccountSubscriberV2`,
+ * `grpcAccountSubscriber`, and polling-loader-backed subscribers. `dataAndSlot` is
+ * undefined until the first fetch/notification lands; once set, `data` and `slot`
+ * are always updated together (see `DataAndSlot`) so a caller never sees data from
+ * one slot paired with another.
+ */
 export interface AccountSubscriber<T> {
+    /** Latest decoded account data and the slot it was observed at, or undefined before the first load. */
     dataAndSlot?: DataAndSlot<T>;
+    /**
+     * Begins tracking the account, seeding `dataAndSlot` with an initial `fetch()` if not already
+     * set, then attaching a live update source (WebSocket/gRPC notification or accountLoader
+     * callback). Idempotent: calling again while already subscribed is a no-op.
+     * @param onChange Invoked with the newly decoded account data whenever a strictly newer slot's
+     * update is observed.
+     */
     subscribe(onChange: (data: T) => void): Promise<void>;
+    /** Fetches the account once via RPC and updates `dataAndSlot` if the response's slot is newer than what's cached. */
     fetch(): Promise<void>;
+    /** Tears down the live update source. Safe to call when not subscribed. */
     unsubscribe(): Promise<void>;
+    /**
+     * Seeds or overwrites `dataAndSlot` without an RPC round trip. Used to inject data the caller
+     * already has (e.g. from a prior fetch elsewhere) before `subscribe()` runs its own fetch.
+     * @param userAccount Decoded account data to store.
+     * @param slot Slot the data was observed at; defaults to 0 (the oldest-possible sentinel) if omitted, so a later real update always wins.
+     */
     setData(userAccount: T, slot?: number): void;
 }
+/**
+ * Contract for a subscriber that tracks every account matching a program-account filter
+ * (e.g. all `User` accounts owned by the program), rather than one specific pubkey.
+ * Implemented by `WebSocketProgramAccountSubscriber`, `WebSocketProgramAccountsSubscriberV2`,
+ * `grpcProgramAccountSubscriber`, and `LaserstreamProgramAccountSubscriber`.
+ */
 export interface ProgramAccountSubscriber<T> {
+    /**
+     * Subscribes to program-account change notifications matching the filters supplied at
+     * construction.
+     * @param onChange Invoked once per changed account with its pubkey, decoded data, the
+     * notification's `Context` (including `slot`), and the raw account buffer.
+     */
     subscribe(onChange: (accountId: PublicKey, data: T, context: Context, buffer: Buffer) => void): Promise<void>;
+    /** Tears down the underlying subscription. Safe to call when not subscribed. */
     unsubscribe(): Promise<void>;
 }
+/**
+ * Thrown by every subscriber's `assertIsSubscribed()`-guarded getter (e.g.
+ * `getUserAccountAndSlot`, `getStateAccountAndSlot`) when called before `subscribe()` has
+ * completed. This is the uniform contract across all subscriber implementations in this
+ * directory: never read cached account data without having subscribed first.
+ */
 export declare class NotSubscribedError extends Error {
     name: string;
 }
+/**
+ * Events emitted by a `VelocityClientAccountSubscriber` on its `eventEmitter`. `update` fires
+ * after every individual account-specific event (state/market/oracle) as a generic "something
+ * changed" signal; `error` surfaces underlying transport errors (e.g. RPC batch failures)
+ * without unsubscribing.
+ */
 export interface VelocityClientAccountEvents {
     stateAccountUpdate: (payload: StateAccount) => void;
     perpMarketAccountUpdate: (payload: PerpMarketAccount) => void;
@@ -42,6 +91,18 @@ export interface VelocityClientAccountEvents {
     update: void;
     error: (e: Error) => void;
 }
+/**
+ * Contract for the subscriber `VelocityClient` uses to keep `State`, `PerpMarket`,
+ * `SpotMarket`, and oracle accounts cached in memory. See `webSocketVelocityClientAccountSubscriber.ts`
+ * (default, one WebSocket subscription per account), `pollingVelocityClientAccountSubscriber.ts`
+ * (single `BulkAccountLoader` batches all accounts via periodic `getMultipleAccounts`), and
+ * `grpcVelocityClientAccountSubscriber.ts`/`grpcVelocityClientAccountSubscriberV2.ts` (gRPC
+ * Geyser stream). Accessor contracts differ by shape: the guarded singleton getters
+ * (`getStateAccountAndSlot`) throw `NotSubscribedError` until `subscribe()` has completed; the
+ * per-market/oracle accessors return `undefined` when that entry isn't cached yet; and the
+ * collection getters (`getMarketAccountsAndSlots`, etc.) are cache reads that return a
+ * possibly-empty array.
+ */
 export interface VelocityClientAccountSubscriber {
     eventEmitter: StrictEventEmitter<EventEmitter, VelocityClientAccountEvents>;
     isSubscribed: boolean;
@@ -61,108 +122,190 @@ export interface VelocityClientAccountSubscriber {
     getOraclePriceDataAndSlot(oracleId: string): DataAndSlot<OraclePriceData> | undefined;
     getOraclePriceDataAndSlotForPerpMarket(marketIndex: number): DataAndSlot<OraclePriceData> | undefined;
     getOraclePriceDataAndSlotForSpotMarket(marketIndex: number): DataAndSlot<OraclePriceData> | undefined;
+    /** Present only on polling-backed implementations; retunes the shared `BulkAccountLoader`'s poll interval (ms) for all accounts it batches. */
     updateAccountLoaderPollingFrequency?: (pollingFrequency: number) => void;
 }
+/**
+ * Controls what a `VelocityClientAccountSubscriber` does with a perp market (and its oracle, if
+ * unused elsewhere) once the on-chain market status becomes `delisted`.
+ */
 export declare enum DelistedMarketSetting {
+    /** Drop the live subscription for the delisted market/oracle but keep the last-known data cached. */
     Unsubscribe = 0,
+    /** Keep subscribing to the delisted market/oracle as normal (no special handling). */
     Subscribe = 1,
+    /** Drop the subscription and remove the market/oracle from the subscriber's internal maps entirely. */
     Discard = 2
 }
+/** Events emitted by a `UserAccountSubscriber` on its `eventEmitter`. `update` fires alongside every `userAccountUpdate`. */
 export interface UserAccountEvents {
     userAccountUpdate: (payload: UserAccount) => void;
     update: void;
     error: (e: Error) => void;
 }
+/** Events emitted at the `User` (SDK wrapper) level, distinct from the lower-level `UserAccountEvents`. */
 export interface UserEvents {
     userUpdate: (payload: User) => void;
     update: void;
     error: (e: Error) => void;
 }
+/**
+ * Contract for the subscriber `User` uses to track a single `UserAccount`. Implementations:
+ * `WebSocketUserAccountSubscriber` (default), `PollingUserAccountSubscriber` (via
+ * `BulkAccountLoader`), `grpcUserAccountSubscriber`, `OneShotUserAccountSubscriber` (fetch-only,
+ * ~1 RPC call), `BasicUserAccountSubscriber` (no network I/O, data supplied by the caller), and
+ * `WebSocketProgramUserAccountSubscriber` (filters a shared program-account stream).
+ */
 export interface UserAccountSubscriber {
     eventEmitter: StrictEventEmitter<EventEmitter, UserAccountEvents>;
     isSubscribed: boolean;
+    /**
+     * @param userAccount Optional pre-fetched account data to seed the subscriber with, skipping
+     * the initial RPC fetch.
+     */
     subscribe(userAccount?: UserAccount): Promise<boolean>;
     fetch(): Promise<void>;
+    /**
+     * Applies an externally-obtained account update (e.g. relayed from a parent subscriber) if its
+     * slot is not older than the currently cached one, emitting `userAccountUpdate`/`update` on
+     * acceptance.
+     * @param userAccount Decoded account data to apply.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userAccount: UserAccount, slot: number): void;
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
     getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined;
 }
+/** Events emitted by a `TokenAccountSubscriber` on its `eventEmitter`. */
 export interface TokenAccountEvents {
     tokenAccountUpdate: (payload: Account) => void;
     update: void;
     error: (e: Error) => void;
 }
+/** Contract for tracking an SPL token account balance (e.g. a spot market vault or a user's token wallet). Implemented by `PollingTokenAccountSubscriber`. */
 export interface TokenAccountSubscriber {
     eventEmitter: StrictEventEmitter<EventEmitter, TokenAccountEvents>;
     isSubscribed: boolean;
     subscribe(): Promise<boolean>;
     fetch(): Promise<void>;
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if not subscribed. */
     getTokenAccountAndSlot(): DataAndSlot<Account>;
 }
+/**
+ * Contract for tracking an `InsuranceFundStake` account. Implementations:
+ * `WebSocketInsuranceFundStakeAccountSubscriber` (default), `PollingInsuranceFundStakeAccountSubscriber`,
+ * and `grpcInsuranceFundStakeAccountSubscriber`.
+ */
 export interface InsuranceFundStakeAccountSubscriber {
     eventEmitter: StrictEventEmitter<EventEmitter, InsuranceFundStakeAccountEvents>;
     isSubscribed: boolean;
     subscribe(): Promise<boolean>;
     fetch(): Promise<void>;
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if not subscribed. */
     getInsuranceFundStakeAccountAndSlot(): DataAndSlot<InsuranceFundStake> | undefined;
 }
+/** Events emitted by an `InsuranceFundStakeAccountSubscriber` on its `eventEmitter`. */
 export interface InsuranceFundStakeAccountEvents {
     insuranceFundStakeAccountUpdate: (payload: InsuranceFundStake) => void;
     update: void;
     error: (e: Error) => void;
 }
+/** Events emitted by an `OracleAccountSubscriber` on its `eventEmitter`. */
 export interface OracleEvents {
     oracleUpdate: (payload: OraclePriceData) => void;
     update: void;
     error: (e: Error) => void;
 }
+/** Contract for tracking a single oracle account's decoded price data. Implemented by `PollingOracleAccountSubscriber` (via `BulkAccountLoader`). */
 export interface OracleAccountSubscriber {
     eventEmitter: StrictEventEmitter<EventEmitter, OracleEvents>;
     isSubscribed: boolean;
     subscribe(): Promise<boolean>;
     fetch(): Promise<void>;
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if not subscribed. */
     getOraclePriceData(): DataAndSlot<OraclePriceData>;
 }
+/** A `state`/`perpMarket`/`spotMarket` account registered with a `PollingVelocityClientAccountSubscriber`'s `BulkAccountLoader`. */
 export type AccountToPoll = {
+    /** Anchor account discriminator name, also used to route the decoded data and pick the emitted event. */
     key: 'state' | 'perpMarket' | 'spotMarket';
     publicKey: PublicKey;
+    /** `VelocityClientAccountEvents` key emitted when this account changes. */
     eventType: string;
+    /** `BulkAccountLoader` callback id, set once registered; used to remove the account later. */
     callbackId?: string;
+    /** For `perpMarket`/`spotMarket`, the market index this account decodes to. */
     mapKey?: number;
 };
+/** An oracle account registered with a `PollingVelocityClientAccountSubscriber`'s `BulkAccountLoader`. */
 export type OraclesToPoll = {
     publicKey: PublicKey;
     source: OracleSource;
+    /** `BulkAccountLoader` callback id, set once registered; used to remove the oracle later. */
     callbackId?: string;
 };
+/** Raw account buffer paired with the slot it was fetched/observed at; the buffer is undefined if the account does not exist on-chain. */
 export type BufferAndSlot = {
     slot: number;
     buffer: Buffer | undefined;
 };
+/**
+ * A decoded account payload paired atomically with the slot it was observed at. Every
+ * `AccountSubscriber`/getter in this directory updates `data` and `slot` together in a single
+ * assignment, so a caller reading `dataAndSlot` never sees data from one slot mixed with a slot
+ * number from another. `slot === 0` is the seeded sentinel used when data is injected via
+ * `setData`/a constructor without a real fetch (e.g. `BasicUserAccountSubscriber`) — it is
+ * always superseded once a real fetch or notification lands, since updates only apply when the
+ * new slot is `>=` the cached one.
+ */
 export type DataAndSlot<T> = {
     data: T;
     slot: number;
 };
+/** Resubscription/polling-fallback tuning for WebSocket- and gRPC-backed subscribers. */
 export type ResubOpts = {
+    /**
+     * Milliseconds of inactivity (no notification) before the subscriber treats the stream as
+     * stalled and resubscribes (or starts polling, see `usePollingInsteadOfResub`). Should be at
+     * least 1000ms; smaller values log a warning. Leave undefined to disable the inactivity
+     * watchdog entirely.
+     */
     resubTimeoutMs?: number;
+    /** Emits verbose `console.log`/`console.debug` diagnostics for resub/polling transitions. Defaults to false. */
     logResubMessages?: boolean;
+    /**
+     * On inactivity timeout, poll via RPC to check for a missed update instead of immediately
+     * tearing down and recreating the WebSocket subscription. Defaults to false on the v1
+     * `WebSocketAccountSubscriber`; the V2 subscribers default this to `true`.
+     */
     usePollingInsteadOfResub?: boolean;
+    /** Polling cadence in ms when `usePollingInsteadOfResub` is active. Defaults to 30000 (30s). */
     pollingIntervalMs?: number;
 };
+/** Events emitted by a `UserStatsAccountSubscriber` on its `eventEmitter`. */
 export interface UserStatsAccountEvents {
     userStatsAccountUpdate: (payload: UserStatsAccount) => void;
     update: void;
     error: (e: Error) => void;
 }
+/**
+ * Contract for the subscriber `UserStats` uses to track a single `UserStatsAccount`.
+ * Implementations mirror `UserAccountSubscriber`: `WebSocketUserStatsAccountSubscriber` (default),
+ * `PollingUserStatsAccountSubscriber`, `grpcUserStatsAccountSubscriber`,
+ * `OneShotUserStatsAccountSubscriber`, and `BasicUserStatsAccountSubscriber`.
+ */
 export interface UserStatsAccountSubscriber {
     eventEmitter: StrictEventEmitter<EventEmitter, UserStatsAccountEvents>;
     isSubscribed: boolean;
+    /** @param userStatsAccount Optional pre-fetched account data to seed the subscriber with, skipping the initial RPC fetch. */
     subscribe(userStatsAccount?: UserStatsAccount): Promise<boolean>;
     fetch(): Promise<void>;
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
     getUserStatsAccountAndSlot(): DataAndSlot<UserStatsAccount> | undefined;
 }
 type BaseGrpcConfigs = {
@@ -175,22 +318,28 @@ type BaseGrpcConfigs = {
      */
     enableReconnect?: boolean;
 };
+/** gRPC Geyser config for the default Yellowstone (Triton/Dragon's Mouth-compatible) client. */
 export type YellowstoneGrpcConfigs = BaseGrpcConfigs & {
     client?: 'yellowstone';
     channelOptions?: ConstructorParameters<typeof Client>[2];
 };
+/** gRPC Geyser config for the Helius LaserStream client (`LaserstreamProgramAccountSubscriber`). Requires the optional `helius-laserstream` peer dependency. */
 export type LaserGrpcConfigs = BaseGrpcConfigs & {
     client: 'laser';
     channelOptions?: LaserstreamConfig['channelOptions'];
 };
+/** Union of supported gRPC Geyser client configs; the `client` discriminant selects Yellowstone vs. LaserStream. */
 export type GrpcConfigs = YellowstoneGrpcConfigs | LaserGrpcConfigs;
+/** Contract for tracking an LP-pool `ConstituentAccount`. `sync()` is the fetch/reconcile entry point (analogous to `fetch()` on other subscribers). */
 export interface ConstituentAccountSubscriber {
     eventEmitter: StrictEventEmitter<EventEmitter, ConstituentAccountEvents>;
     isSubscribed: boolean;
+    /** @param constituentAccount Optional pre-fetched account data to seed the subscriber with. */
     subscribe(constituentAccount?: ConstituentAccount): Promise<boolean>;
     sync(): Promise<void>;
     unsubscribe(): Promise<void>;
 }
+/** Events emitted by a `ConstituentAccountSubscriber` on its `eventEmitter`. */
 export interface ConstituentAccountEvents {
     onAccountUpdate: (account: ConstituentAccount, pubkey: PublicKey, slot: number) => void;
     update: void;

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

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

package/lib/node/accounts/types.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DelistedMarketSetting = exports.NotSubscribedError = void 0;
+/**
+ * Thrown by every subscriber's `assertIsSubscribed()`-guarded getter (e.g.
+ * `getUserAccountAndSlot`, `getStateAccountAndSlot`) when called before `subscribe()` has
+ * completed. This is the uniform contract across all subscriber implementations in this
+ * directory: never read cached account data without having subscribed first.
+ */
 class NotSubscribedError extends Error {
     constructor() {
         super(...arguments);
@@ -8,9 +14,16 @@ class NotSubscribedError extends Error {
     }
 }
 exports.NotSubscribedError = NotSubscribedError;
+/**
+ * Controls what a `VelocityClientAccountSubscriber` does with a perp market (and its oracle, if
+ * unused elsewhere) once the on-chain market status becomes `delisted`.
+ */
 var DelistedMarketSetting;
 (function (DelistedMarketSetting) {
+    /** Drop the live subscription for the delisted market/oracle but keep the last-known data cached. */
     DelistedMarketSetting[DelistedMarketSetting["Unsubscribe"] = 0] = "Unsubscribe";
+    /** Keep subscribing to the delisted market/oracle as normal (no special handling). */
     DelistedMarketSetting[DelistedMarketSetting["Subscribe"] = 1] = "Subscribe";
+    /** Drop the subscription and remove the market/oracle from the subscriber's internal maps entirely. */
     DelistedMarketSetting[DelistedMarketSetting["Discard"] = 2] = "Discard";
 })(DelistedMarketSetting || (exports.DelistedMarketSetting = DelistedMarketSetting = {}));

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

@@ -1,8 +1,26 @@
 import { DataAndSlot } from './types';
 import { PerpMarketAccount, SpotMarketAccount } from '../types';
 import { OracleInfo } from '../oracles/types';
+/** Capitalizes the first character of `value` (e.g. for building Anchor event/method names from account names). */
 export declare function capitalize(value: string): string;
+/**
+ * Unwraps a possibly-undefined `DataAndSlot<T>`, throwing if it hasn't loaded. Use this instead
+ * of a bare non-null assertion when a subscriber's cached data must be present by this point.
+ * @param dataAndSlot The cached data/slot pair to check, typically from `AccountSubscriber.dataAndSlot`.
+ * @param message Error message to throw if `dataAndSlot` is undefined.
+ * @returns The same `dataAndSlot`, narrowed to non-undefined.
+ */
 export declare function assertDataAndSlot<T>(dataAndSlot: DataAndSlot<T> | undefined, message: string): DataAndSlot<T>;
+/**
+ * Scans cached perp/spot market data for perp markets with `status: delisted` and identifies
+ * both the delisted market indexes and their oracles, excluding any oracle still in use by a
+ * spot market or a non-delisted perp market (so a shared oracle isn't dropped out from under a
+ * still-live market). Used by `VelocityClientAccountSubscriber` implementations to drive
+ * `DelistedMarketSetting` (unsubscribe/discard) handling.
+ * @param perpMarkets Currently cached perp market data/slots (entries with missing `data` are skipped).
+ * @param spotMarkets Currently cached spot market data/slots, checked to avoid dropping oracles they still reference.
+ * @returns `perpMarketIndexes` of delisted perp markets and `oracles` safe to stop tracking.
+ */
 export declare function findDelistedPerpMarketsAndOracles(perpMarkets: DataAndSlot<PerpMarketAccount>[], spotMarkets: DataAndSlot<SpotMarketAccount>[]): {
     perpMarketIndexes: number[];
     oracles: OracleInfo[];