@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/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/browser/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/browser/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[];

package/lib/browser/accounts/utils.js

@@ -3,10 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.findDelistedPerpMarketsAndOracles = exports.assertDataAndSlot = exports.capitalize = void 0;
 const types_1 = require("../types");
 const oracleId_1 = require("../oracles/oracleId");
+/** Capitalizes the first character of `value` (e.g. for building Anchor event/method names from account names). */
 function capitalize(value) {
     return value[0].toUpperCase() + value.slice(1);
 }
 exports.capitalize = capitalize;
+/**
+ * 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.
+ */
 function assertDataAndSlot(dataAndSlot, message) {
     if (!dataAndSlot) {
         throw new Error(message);
@@ -14,6 +22,16 @@ function assertDataAndSlot(dataAndSlot, message) {
     return dataAndSlot;
 }
 exports.assertDataAndSlot = assertDataAndSlot;
+/**
+ * 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.
+ */
 function findDelistedPerpMarketsAndOracles(perpMarkets, spotMarkets) {
     const delistedPerpMarketIndexes = [];
     const delistedOracles = [];
@@ -29,25 +47,23 @@ function findDelistedPerpMarketsAndOracles(perpMarkets, spotMarkets) {
             });
         }
     }
-    // make sure oracle isn't used by spot market
-    const filteredDelistedOracles = [];
-    for (const delistedOracle of delistedOracles) {
-        let isUsedBySpotMarket = false;
-        for (const spotMarket of spotMarkets) {
-            if (!spotMarket || !spotMarket.data) {
-                continue;
-            }
-            const delistedOracleId = (0, oracleId_1.getOracleId)(delistedOracle.publicKey, delistedOracle.source);
-            const spotMarketOracleId = (0, oracleId_1.getOracleId)(spotMarket.data.oracle, spotMarket.data.oracleSource);
-            if (spotMarketOracleId === delistedOracleId) {
-                isUsedBySpotMarket = true;
-                break;
-            }
+    // make sure oracle isn't still used by a spot market or a live perp market
+    const liveOracleIds = new Set();
+    for (const spotMarket of spotMarkets) {
+        if (!spotMarket || !spotMarket.data) {
+            continue;
+        }
+        liveOracleIds.add((0, oracleId_1.getOracleId)(spotMarket.data.oracle, spotMarket.data.oracleSource));
+    }
+    for (const perpMarket of perpMarkets) {
+        if (!perpMarket || !perpMarket.data) {
+            continue;
         }
-        if (!isUsedBySpotMarket) {
-            filteredDelistedOracles.push(delistedOracle);
+        if (!(0, types_1.isVariant)(perpMarket.data.status, 'delisted')) {
+            liveOracleIds.add((0, oracleId_1.getOracleId)(perpMarket.data.oracle, perpMarket.data.oracleSource));
         }
     }
+    const filteredDelistedOracles = delistedOracles.filter((delistedOracle) => !liveOracleIds.has((0, oracleId_1.getOracleId)(delistedOracle.publicKey, delistedOracle.source)));
     return {
         perpMarketIndexes: delistedPerpMarketIndexes,
         oracles: filteredDelistedOracles,

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

@@ -3,6 +3,16 @@
 import { DataAndSlot, BufferAndSlot, AccountSubscriber, ResubOpts } from './types';
 import { AccountInfo, Commitment, Context, PublicKey } from '@solana/web3.js';
 import { VelocityProgram } from '../config';
+/**
+ * Default `AccountSubscriber` implementation: tracks a single account via
+ * `connection.onAccountChange`, decoding each notification with either a supplied
+ * `decodeBuffer` function or the program's Anchor coder for `accountName`. Updates are applied
+ * only when the notification's slot is not older than the last-seen slot and the raw buffer
+ * actually changed, so `onChange` never fires twice for the same bytes. If `resubOpts.resubTimeoutMs`
+ * is set, a watchdog timer resubscribes to the WebSocket whenever no notification arrives within
+ * that window — see `ResubOpts` for tuning. This is the base class extended by
+ * `grpcAccountSubscriber` for gRPC Geyser-backed tracking.
+ */
 export declare class WebSocketAccountSubscriber<T> implements AccountSubscriber<T> {
     dataAndSlot?: DataAndSlot<T>;
     bufferAndSlot?: BufferAndSlot;
@@ -20,12 +30,43 @@ export declare class WebSocketAccountSubscriber<T> implements AccountSubscriber<
     isUnsubscribing: boolean;
     timeoutId?: ReturnType<typeof setTimeout>;
     receivingData: boolean;
+    /**
+     * @param accountName Anchor account type name (used for logging and, absent `decodeBuffer`, for decoding via the program coder).
+     * @param program Anchor program providing the connection and coder.
+     * @param accountPublicKey Address of the account to track.
+     * @param decodeBuffer Optional custom decode function; defaults to `program.coder.accounts.decode(accountName, buffer)`.
+     * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+     * @param commitment Commitment for both the initial fetch and the `onAccountChange` subscription; defaults to the provider's configured commitment.
+     */
     constructor(accountName: string, program: VelocityProgram, accountPublicKey: PublicKey, decodeBuffer?: (buffer: Buffer) => T, resubOpts?: ResubOpts, commitment?: Commitment);
+    /**
+     * Seeds `dataAndSlot` with an initial `fetch()` (if not already set via `setData`) and then
+     * attaches the `onAccountChange` WebSocket listener. Returning early (no-op) if already
+     * subscribed or mid-unsubscribe.
+     * @param onChange Invoked with the newly decoded account data on each accepted update.
+     */
     subscribe(onChange: (data: T) => void): Promise<void>;
+    /**
+     * Seeds or overwrites `dataAndSlot` directly, bypassing RPC. A no-op if the currently cached
+     * slot is already newer than `slot`.
+     * @param data Decoded account data to store.
+     * @param slot Slot the data was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     setData(data: T, slot?: number): void;
     protected setTimeout(): void;
+    /** Fetches the account once via `getAccountInfoAndContext` and routes the result through `handleRpcResponse`, applying it if newer than the cached slot. */
     fetch(): Promise<void>;
+    /**
+     * Applies a raw RPC/WS response: decodes and stores it (updating `bufferAndSlot`/`dataAndSlot`
+     * and invoking `onChange`) only if the slot is not older than the cached one and the buffer's
+     * bytes actually changed (or this is the first observation).
+     */
     handleRpcResponse(context: Context, accountInfo?: AccountInfo<Buffer>): void;
+    /** Decodes a raw account buffer using the constructor-supplied `decodeBufferFn`, or the program's Anchor coder for `accountName` if none was supplied. */
     decodeBuffer(buffer: Buffer): T;
+    /**
+     * Tears down the WebSocket listener and cancels 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>;
 }

package/lib/browser/accounts/webSocketAccountSubscriber.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocketAccountSubscriber = void 0;
+/**
+ * Default `AccountSubscriber` implementation: tracks a single account via
+ * `connection.onAccountChange`, decoding each notification with either a supplied
+ * `decodeBuffer` function or the program's Anchor coder for `accountName`. Updates are applied
+ * only when the notification's slot is not older than the last-seen slot and the raw buffer
+ * actually changed, so `onChange` never fires twice for the same bytes. If `resubOpts.resubTimeoutMs`
+ * is set, a watchdog timer resubscribes to the WebSocket whenever no notification arrives within
+ * that window — see `ResubOpts` for tuning. This is the base class extended by
+ * `grpcAccountSubscriber` for gRPC Geyser-backed tracking.
+ */
 class WebSocketAccountSubscriber {
     get onChange() {
         if (!this._onChange) {
@@ -11,6 +21,14 @@ class WebSocketAccountSubscriber {
     set onChange(onChange) {
         this._onChange = onChange;
     }
+    /**
+     * @param accountName Anchor account type name (used for logging and, absent `decodeBuffer`, for decoding via the program coder).
+     * @param program Anchor program providing the connection and coder.
+     * @param accountPublicKey Address of the account to track.
+     * @param decodeBuffer Optional custom decode function; defaults to `program.coder.accounts.decode(accountName, buffer)`.
+     * @param resubOpts Resubscription watchdog options; omit to disable the inactivity timer.
+     * @param commitment Commitment for both the initial fetch and the `onAccountChange` subscription; defaults to the provider's configured commitment.
+     */
     constructor(accountName, program, accountPublicKey, decodeBuffer, resubOpts, commitment) {
         var _a;
         this.isUnsubscribing = false;
@@ -28,6 +46,12 @@ class WebSocketAccountSubscriber {
         this.commitment =
             commitment !== null && commitment !== void 0 ? commitment : this.program.provider.opts.commitment;
     }
+    /**
+     * Seeds `dataAndSlot` with an initial `fetch()` (if not already set via `setData`) and then
+     * attaches the `onAccountChange` WebSocket listener. Returning early (no-op) if already
+     * subscribed or mid-unsubscribe.
+     * @param onChange Invoked with the newly decoded account data on each accepted update.
+     */
     async subscribe(onChange) {
         var _a, _b;
         if (this.listenerId != null || this.isUnsubscribing) {
@@ -57,6 +81,12 @@ class WebSocketAccountSubscriber {
             this.setTimeout();
         }
     }
+    /**
+     * Seeds or overwrites `dataAndSlot` directly, bypassing RPC. A no-op if the currently cached
+     * slot is already newer than `slot`.
+     * @param data Decoded account data to store.
+     * @param slot Slot the data was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     setData(data, slot) {
         const newSlot = slot || 0;
         if (this.dataAndSlot && this.dataAndSlot.slot > newSlot) {
@@ -99,11 +129,17 @@ class WebSocketAccountSubscriber {
             }
         }, (_a = this.resubOpts) === null || _a === void 0 ? void 0 : _a.resubTimeoutMs);
     }
+    /** Fetches the account once via `getAccountInfoAndContext` and routes the result through `handleRpcResponse`, applying it if newer than the cached slot. */
     async fetch() {
         var _a;
         const rpcResponse = await this.program.provider.connection.getAccountInfoAndContext(this.accountPublicKey, this.program.provider.opts.commitment);
         this.handleRpcResponse(rpcResponse.context, (_a = rpcResponse === null || rpcResponse === void 0 ? void 0 : rpcResponse.value) !== null && _a !== void 0 ? _a : undefined);
     }
+    /**
+     * Applies a raw RPC/WS response: decodes and stores it (updating `bufferAndSlot`/`dataAndSlot`
+     * and invoking `onChange`) only if the slot is not older than the cached one and the buffer's
+     * bytes actually changed (or this is the first observation).
+     */
     handleRpcResponse(context, accountInfo) {
         const newSlot = context.slot;
         let newBuffer = undefined;
@@ -142,6 +178,7 @@ class WebSocketAccountSubscriber {
             this.onChange(account);
         }
     }
+    /** Decodes a raw account buffer using the constructor-supplied `decodeBufferFn`, or the program's Anchor coder for `accountName` if none was supplied. */
     decodeBuffer(buffer) {
         if (this.decodeBufferFn) {
             return this.decodeBufferFn(buffer);
@@ -150,6 +187,10 @@ class WebSocketAccountSubscriber {
             return this.program.coder.accounts.decode(this.accountName, buffer);
         }
     }
+    /**
+     * Tears down the WebSocket listener and cancels 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 = false) {
         if (!onResub && this.resubOpts) {
             this.resubOpts.resubTimeoutMs = undefined;

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

@@ -88,8 +88,28 @@ export declare class WebSocketAccountSubscriberV2<T> implements AccountSubscribe
      */
     constructor(accountName: string, program: VelocityProgram, accountPublicKey: PublicKey, decodeBuffer?: (buffer: Buffer) => T, resubOpts?: ResubOpts, commitment?: Commitment, rpcSubscriptions?: RpcSubscriptions<SolanaRpcSubscriptionsApi> & string, rpc?: Rpc<any>);
     private handleNotificationLoop;
+    /**
+     * Seeds `dataAndSlot` with an initial `fetch()` (if not already set via `setData`), then opens
+     * the `gill` `accountNotifications` WebSocket subscription and, if `resubOpts.resubTimeoutMs`
+     * is set, arms the inactivity watchdog (`setTimeout`). Idempotent: a no-op if already
+     * subscribed or mid-unsubscribe.
+     * @param onChange Invoked with the newly decoded account data on each accepted update.
+     * @throws Error if `accountPublicKey` is not a valid address per `gill`'s `isAddress`.
+     */
     subscribe(onChange: (data: T) => void): Promise<void>;
+    /**
+     * Seeds or overwrites `dataAndSlot` directly, bypassing RPC. A no-op if the currently cached
+     * slot is already newer than `slot`.
+     * @param data Decoded account data to store.
+     * @param slot Slot the data was observed at; defaults to 0 (the seeded sentinel) if omitted.
+     */
     setData(data: T, slot?: number): void;
+    /**
+     * Arms the inactivity watchdog: if no WS notification resets this timeout within
+     * `resubOpts.resubTimeoutMs`, either starts the polling fallback (`usePollingInsteadOfResub`)
+     * or tears down and recreates the WS subscription. Throws if `onChange` was never set (i.e.
+     * called outside `subscribe()`'s flow).
+     */
     protected setTimeout(): void;
     /**
      * Start the polling loop (single-account).
@@ -103,9 +123,20 @@ export declare class WebSocketAccountSubscriberV2<T> implements AccountSubscribe
      * decoding and update pathway as WS notifications.
      */
     fetch(): Promise<void>;
+    /**
+     * Applies a raw `gill` RPC/WS response: decodes (base58 or base64) and stores it (updating
+     * `bufferAndSlot`/`dataAndSlot` and invoking `onChange`) only if the slot is not older than
+     * the cached one and the buffer's bytes actually changed (or this is the first observation).
+     */
     handleRpcResponse(context: {
         slot: bigint;
     }, accountInfo?: AccountInfoBase & (AccountInfoWithBase58EncodedData | AccountInfoWithBase64EncodedData)): void;
+    /** Decodes a raw account buffer using the constructor-supplied `decodeBufferFn`, or the program's Anchor coder for `accountName` if none was supplied. */
     decodeBuffer(buffer: Buffer): T;
+    /**
+     * Tears down the WebSocket subscription (via `abortController`) and cancels any pending resub
+     * timeout and in-progress polling.
+     * @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>;
 }