@velocity-exchange/sdk 0.3.0 → 0.4.0

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

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

package/lib/node/accounts/webSocketVelocityClientAccountSubscriberV2.js

@@ -18,6 +18,15 @@ const memcmp_1 = require("../memcmp");
 const webSocketProgramAccountsSubscriberV2_1 = require("./webSocketProgramAccountsSubscriberV2");
 const webSocketAccountSubscriberV2_1 = require("./webSocketAccountSubscriberV2");
 const ORACLE_DEFAULT_ID = (0, oracleId_1.getOracleId)(web3_js_1.PublicKey.default, types_3.OracleSource.QUOTE_ASSET);
+/**
+ * `VelocityClientAccountSubscriber` variant that, unlike `WebSocketVelocityClientAccountSubscriber`
+ * (one `WebSocketAccountSubscriber` per market), multiplexes all perp markets onto a single
+ * `WebSocketProgramAccountsSubscriberV2` program-account stream and all spot markets onto a
+ * second — two WebSocket subscriptions total instead of one per market. `State` and each oracle
+ * still get their own `WebSocketAccountSubscriberV2`. Lower connection overhead at scale;
+ * `addPerpMarket`/`addSpotMarket` are no-ops here since new markets simply arrive automatically
+ * over the existing program-account stream rather than needing an explicit new subscription.
+ */
 class WebSocketVelocityClientAccountSubscriberV2 {
     get perpMarketAllAccountsSubscriber() {
         if (!this._perpMarketAllAccountsSubscriber) {
@@ -37,6 +46,17 @@ class WebSocketVelocityClientAccountSubscriberV2 {
     set spotMarketAllAccountsSubscriber(subscriber) {
         this._spotMarketAllAccountsSubscriber = subscriber;
     }
+    /**
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false. Only used to derive the initial pubkeys handed to the perp program-account subscriber; new markets arrive automatically thereafter.
+     * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false. Same caveat as `perpMarketIndexes`.
+     * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+     * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state, ignoring the index/info args above.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing; see `DelistedMarketSetting`.
+     * @param resubOpts Resubscription watchdog options passed to the underlying program-account and per-oracle subscribers.
+     * @param commitment Commitment for every subscription; defaults to the provider's configured commitment.
+     * @param skipInitialData Currently unused by `subscribe()`/`setInitialData()` (the field is set but never read); defaults to `false`.
+     */
     constructor(program, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting, resubOpts, commitment, skipInitialData) {
         this.oracleClientCache = new oracleClientCache_1.OracleClientCache();
         this.skipInitialData = true;
@@ -77,7 +97,17 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         this.rpc = rpc;
         this.rpcSubscriptions = rpcSubscriptions;
     }
+    /**
+     * Derives all tracked perp/spot market pubkeys (or discovers them via `findAllMarketAndOracles`
+     * if `shouldFindAllMarketsAndOracles` is set), then in parallel: opens the perp and spot
+     * `WebSocketProgramAccountsSubscriberV2` streams, subscribes the `State` account, and seeds +
+     * subscribes every oracle. Applies `delistedMarketSetting` afterward. Idempotent: a no-op if
+     * already subscribed, and concurrent calls while a subscribe is in flight share the same
+     * result via `subscriptionPromise` rather than issuing duplicate subscriptions.
+     * @returns `true` on success; `false` if any step throws (subscription state is left partially applied in that case, and `isSubscribed` remains `false`).
+     */
     async subscribe() {
+        var _a;
         try {
             const startTime = performance.now();
             if (this.isSubscribed) {
@@ -206,11 +236,23 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         }
         catch (error) {
             console.error('Subscription failed:', error);
+            // Tear down any child subscribers that were created before the failure so a
+            // subsequent subscribe() attempt doesn't leak live connections; isSubscribed is
+            // still false at this point, so unsubscribe() alone would otherwise skip this.
+            await Promise.all([
+                (_a = this.stateAccountSubscriber) === null || _a === void 0 ? void 0 : _a.unsubscribe(),
+                this.unsubscribeFromMarketAccounts(),
+                this.unsubscribeFromSpotMarketAccounts(),
+                this.unsubscribeFromOracles(),
+            ]).catch((teardownError) => {
+                console.error('Error tearing down partial subscription:', teardownError);
+            });
             this.isSubscribing = false;
             this.subscriptionPromiseResolver(false);
             return false;
         }
     }
+    /** Re-runs `setInitialData()`, re-fetching and re-emitting oracle price data. Does not re-fetch perp/spot market or `State` accounts — those are kept current via their live WebSocket streams. */
     async fetch() {
         await this.setInitialData();
     }
@@ -237,6 +279,14 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         return Promise.resolve(true);
     }
     // TODO: need more options to skip loading perp market and spot market data. Because of how we fetch within the program account subscribers, I am commenting this all out
+    /**
+     * Batch-fetches every tracked oracle account via chunked `getMultipleAccountsInfo` calls (100
+     * pubkeys per chunk), decodes each with the source-appropriate `OracleClient`, stashes the
+     * results in `initialOraclePriceData`, and immediately emits `oraclePriceUpdate`/`update` for
+     * each. Unlike the v1 subscriber's `setInitialData`, does not seed perp/spot market data —
+     * those markets are seeded directly by the program-account subscribers' own initial-account
+     * list instead.
+     */
     async setInitialData() {
         var _a;
         const connection = this.program.provider.connection;
@@ -272,11 +322,13 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         });
         this.eventEmitter.emit('update');
     }
+    /** Clears the seed data stashed by `setInitialData()`/`findAllMarketAndOracles` once consumed, freeing the memory. */
     removeInitialData() {
         this.initialPerpMarketAccountData = new Map();
         this.initialSpotMarketAccountData = new Map();
         this.initialOraclePriceData = new Map();
     }
+    /** Subscribes a `WebSocketAccountSubscriberV2` for every tracked oracle not already subscribed, in parallel, skipping duplicates already present in `oracleSubscribers`. */
     async subscribeToOracles() {
         const startTime = performance.now();
         // Filter out default oracles and duplicates to avoid unnecessary subscriptions
@@ -286,6 +338,13 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         console.log(`[PROFILING] subscribeToOracles() completed in ${totalDuration.toFixed(2)}ms`);
         return true;
     }
+    /**
+     * Creates and subscribes a `WebSocketAccountSubscriberV2` for one oracle, decoding buffers
+     * with the source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available
+     * before subscribing.
+     * @param oracleInfo Oracle pubkey and source to subscribe.
+     * @returns `false` if no `OracleClient` is registered for `oracleInfo.source` or the subscribe call throws; otherwise `true`.
+     */
     async subscribeToOracle(oracleInfo) {
         var _a;
         try {
@@ -313,15 +372,19 @@ class WebSocketVelocityClientAccountSubscriberV2 {
             return false;
         }
     }
+    /** Unsubscribes the single multiplexed perp-market program-account stream. */
     async unsubscribeFromMarketAccounts() {
         await this.perpMarketAllAccountsSubscriber.unsubscribe();
     }
+    /** Unsubscribes the single multiplexed spot-market program-account stream. */
     async unsubscribeFromSpotMarketAccounts() {
         await this.spotMarketAllAccountsSubscriber.unsubscribe();
     }
+    /** Unsubscribes every per-oracle `WebSocketAccountSubscriberV2`, in parallel. */
     async unsubscribeFromOracles() {
         await Promise.all(Array.from(this.oracleSubscribers.values()).map((accountSubscriber) => accountSubscriber.unsubscribe()));
     }
+    /** Tears down the `State` subscriber, both market program-account streams, and every oracle subscriber. A no-op if not subscribed. */
     async unsubscribe() {
         var _a;
         if (!this.isSubscribed) {
@@ -340,6 +403,12 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         this.isSubscribing = false;
         this.subscriptionPromiseResolver = () => { };
     }
+    /**
+     * Adds an oracle to be tracked, subscribing a new `WebSocketAccountSubscriberV2` for it. A
+     * no-op that resolves `true` immediately for the `PublicKey.default` sentinel (quote-asset "no
+     * oracle") or an oracle already tracked.
+     * @param oracleInfo Oracle pubkey and source to start tracking.
+     */
     async addOracle(oracleInfo) {
         const oracleId = (0, oracleId_1.getOracleId)(oracleInfo.publicKey, oracleInfo.source);
         if (this.oracleSubscribers.has(oracleId)) {
@@ -350,6 +419,7 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         }
         return this.subscribeToOracle(oracleInfo);
     }
+    /** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked. */
     async setPerpOracleMap() {
         const perpMarkets = this.getMarketAccountsAndSlots();
         const addOraclePromises = [];
@@ -372,6 +442,7 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         }
         await Promise.all(addOraclePromises);
     }
+    /** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked. */
     async setSpotOracleMap() {
         const spotMarkets = this.getSpotMarketAccountsAndSlots();
         const addOraclePromises = [];
@@ -394,6 +465,16 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         }
         await Promise.all(addOraclePromises);
     }
+    /**
+     * Applies `delistedMarketSetting` to any oracle backing a currently `status: delisted` perp
+     * market (and not still used by a live spot market, per `findDelistedPerpMarketsAndOracles`):
+     * unsubscribes the oracle's subscriber, and additionally drops it from `oracleSubscribers` if
+     * the setting is `Discard`. A no-op if the setting is `Subscribe`. Note this only manages
+     * oracle subscriptions — delisted market accounts themselves cannot be selectively unsubscribed
+     * from the shared perp/spot program-account stream; instead the `subscribe()` update callback
+     * drops any incoming update for a `status: delisted` market unless `delistedMarketSetting` is
+     * `Subscribe`, freezing that market's cached data at its last pre-delisting state.
+     */
     async handleDelistedMarketOracles() {
         if (this.delistedMarketSetting === types_1.DelistedMarketSetting.Subscribe) {
             return;
@@ -410,30 +491,43 @@ class WebSocketVelocityClientAccountSubscriberV2 {
             }
         }
     }
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     assertIsSubscribed() {
         if (!this.isSubscribed) {
             throw new types_1.NotSubscribedError('You must call `subscribe` before using this function');
         }
     }
+    /** Throws `NotSubscribedError` if not subscribed, or a generic `Error` (via `assertDataAndSlot`) if subscribed but the `State` account hasn't loaded yet. */
     getStateAccountAndSlot() {
         var _a;
         this.assertIsSubscribed();
         return (0, utils_1.assertDataAndSlot)((_a = this.stateAccountSubscriber) === null || _a === void 0 ? void 0 : _a.dataAndSlot, 'State account data not available');
     }
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` hasn't been observed yet on the perp program-account stream. */
     getMarketAccountAndSlot(marketIndex) {
         this.assertIsSubscribed();
         return this.perpMarketAccountLatestData.get(marketIndex);
     }
+    /** Returns every currently cached (loaded) perp market. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots() {
         return Array.from(this.perpMarketAccountLatestData.values());
     }
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined if `marketIndex` hasn't been observed yet on the spot program-account stream. */
     getSpotMarketAccountAndSlot(marketIndex) {
         this.assertIsSubscribed();
         return this.spotMarketAccountLatestData.get(marketIndex);
     }
+    /** Returns every currently cached (loaded) spot market. Does not throw `NotSubscribedError`. */
     getSpotMarketAccountsAndSlots() {
         return Array.from(this.spotMarketAccountLatestData.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 subscriber lookup, since that oracle is never actually subscribed to.
+     * @param oracleId Oracle id string from `getOracleId(publicKey, source)`.
+     * @returns Cached price data/slot, or undefined if not tracked. Throws `NotSubscribedError` if not subscribed.
+     */
     getOraclePriceDataAndSlot(oracleId) {
         var _a;
         this.assertIsSubscribed();
@@ -445,6 +539,13 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         }
         return (_a = this.oracleSubscribers.get(oracleId)) === null || _a === void 0 ? void 0 : _a.dataAndSlot;
     }
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a perp market's
+     * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+     * `perpOracleMap`, triggers a background `setPerpOracleMap()` refresh and still returns the
+     * (possibly stale) mapping for this call.
+     * @param marketIndex Perp market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForPerpMarket(marketIndex) {
         const perpMarketAccount = this.getMarketAccountAndSlot(marketIndex);
         const oracle = this.perpOracleMap.get(marketIndex);
@@ -458,6 +559,13 @@ class WebSocketVelocityClientAccountSubscriberV2 {
         }
         return this.getOraclePriceDataAndSlot(oracleId);
     }
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a spot market's
+     * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+     * `spotOracleMap`, triggers a background `setSpotOracleMap()` refresh and still returns the
+     * (possibly stale) mapping for this call.
+     * @param marketIndex Spot market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForSpotMarket(marketIndex) {
         const spotMarketAccount = this.getSpotMarketAccountAndSlot(marketIndex);
         const oracle = this.spotOracleMap.get(marketIndex);

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

@@ -6,6 +6,13 @@ import { EventEmitter } from 'events';
 import { PublicKey } from '@solana/web3.js';
 import { WebSocketProgramAccountSubscriber } from './webSocketProgramAccountSubscriber';
 import { UserAccount } from '../types';
+/**
+ * `UserAccountSubscriber` that filters a *shared* `WebSocketProgramAccountSubscriber` (subscribed
+ * once, program-wide, by the caller) down to a single `UserAccount` by pubkey, instead of opening
+ * its own dedicated subscription. Overwrites the shared subscriber's `onChange` callback in
+ * `subscribe()` — only one `WebSocketProgramUserAccountSubscriber` can usefully attach to a given
+ * `programSubscriber` at a time, since each `subscribe()` call replaces the previous `onChange`.
+ */
 export declare class WebSocketProgramUserAccountSubscriber implements UserAccountSubscriber {
     isSubscribed: boolean;
     eventEmitter: StrictEventEmitter<EventEmitter, UserAccountEvents>;
@@ -13,11 +20,32 @@ export declare class WebSocketProgramUserAccountSubscriber implements UserAccoun
     private program;
     private programSubscriber;
     private userAccountAndSlot?;
+    /**
+     * @param program Anchor program used for the one-off `fetch()` fallback.
+     * @param userAccountPublicKey Address of the `UserAccount` to filter for.
+     * @param programSubscriber Shared, already-created program-account subscriber (not subscribed by this constructor — see `subscribe()`).
+     */
     constructor(program: VelocityProgram, userAccountPublicKey: PublicKey, programSubscriber: WebSocketProgramAccountSubscriber<UserAccount>);
+    /**
+     * Installs (overwriting) an `onChange` handler on the shared `programSubscriber` that filters
+     * updates down to this instance's `userAccountPublicKey`. Does not itself call
+     * `programSubscriber.subscribe()` — the caller is responsible for starting the shared program
+     * subscription separately.
+     * @param userAccount Optional pre-fetched account data to seed with immediately (at slot 0).
+     */
     subscribe(userAccount?: UserAccount): Promise<boolean>;
+    /** Fetches the account once directly via `program.account.user.fetch` (independent of the shared program subscription), storing the result at slot 0 (not the fetch's actual slot). Throws `NotSubscribedError` if not subscribed. */
     fetch(): Promise<void>;
+    /**
+     * Overwrites the cached data unconditionally — unlike most other `updateData` implementations
+     * in this directory, there is no slot-ordering guard here, so a caller must not pass stale data.
+     * @param userAccount Decoded account data to store.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userAccount: UserAccount, slot: number): void;
+    /** Marks this facade unsubscribed. Does not touch the shared `programSubscriber`'s `onChange` handler or its subscription state. */
     unsubscribe(): Promise<void>;
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
     getUserAccountAndSlot(): DataAndSlot<UserAccount> | undefined;
 }
 //# sourceMappingURL=websocketProgramUserAccountSubscriber.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"websocketProgramUserAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/websocketProgramUserAccountSubscriber.ts"],"names":[],"mappings":";AAAA,OAAO,EACN,WAAW,EAEX,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,kBAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAW,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC,qBAAa,qCACZ,YAAW,qBAAqB;IAEhC,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;IAElE,OAAO,CAAC,oBAAoB,CAAY;IACxC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,iBAAiB,CAAiD;IAC1E,OAAO,CAAC,kBAAkB,CAAC,CAA2B;gBAGrD,OAAO,EAAE,eAAe,EACxB,oBAAoB,EAAE,SAAS,EAC/B,iBAAiB,EAAE,iCAAiC,CAAC,WAAW,CAAC;IAS5D,SAAS,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B,UAAU,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAOlD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC,qBAAqB,IAAI,WAAW,CAAC,WAAW,CAAC,GAAG,SAAS;CAQ7D"}
+{"version":3,"file":"websocketProgramUserAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/websocketProgramUserAccountSubscriber.ts"],"names":[],"mappings":";AAAA,OAAO,EACN,WAAW,EAEX,iBAAiB,EACjB,qBAAqB,EACrB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,kBAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAW,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,iCAAiC,EAAE,MAAM,qCAAqC,CAAC;AACxF,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;GAMG;AACH,qBAAa,qCACZ,YAAW,qBAAqB;IAEhC,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;IAElE,OAAO,CAAC,oBAAoB,CAAY;IACxC,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,iBAAiB,CAAiD;IAC1E,OAAO,CAAC,kBAAkB,CAAC,CAA2B;IAEtD;;;;OAIG;gBAEF,OAAO,EAAE,eAAe,EACxB,oBAAoB,EAAE,SAAS,EAC/B,iBAAiB,EAAE,iCAAiC,CAAC,WAAW,CAAC;IASlE;;;;;;OAMG;IACG,SAAS,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IA8B5D,sOAAsO;IAChO,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;;;;OAKG;IACH,UAAU,CAAC,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAOxD,oIAAoI;IAC9H,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlC,sHAAsH;IACtH,qBAAqB,IAAI,WAAW,CAAC,WAAW,CAAC,GAAG,SAAS;CAQ7D"}

package/lib/node/accounts/websocketProgramUserAccountSubscriber.js

@@ -3,7 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebSocketProgramUserAccountSubscriber = void 0;
 const types_1 = require("./types");
 const events_1 = require("events");
+/**
+ * `UserAccountSubscriber` that filters a *shared* `WebSocketProgramAccountSubscriber` (subscribed
+ * once, program-wide, by the caller) down to a single `UserAccount` by pubkey, instead of opening
+ * its own dedicated subscription. Overwrites the shared subscriber's `onChange` callback in
+ * `subscribe()` — only one `WebSocketProgramUserAccountSubscriber` can usefully attach to a given
+ * `programSubscriber` at a time, since each `subscribe()` call replaces the previous `onChange`.
+ */
 class WebSocketProgramUserAccountSubscriber {
+    /**
+     * @param program Anchor program used for the one-off `fetch()` fallback.
+     * @param userAccountPublicKey Address of the `UserAccount` to filter for.
+     * @param programSubscriber Shared, already-created program-account subscriber (not subscribed by this constructor — see `subscribe()`).
+     */
     constructor(program, userAccountPublicKey, programSubscriber) {
         this.isSubscribed = false;
         this.program = program;
@@ -11,6 +23,13 @@ class WebSocketProgramUserAccountSubscriber {
         this.eventEmitter = new events_1.EventEmitter();
         this.programSubscriber = programSubscriber;
     }
+    /**
+     * Installs (overwriting) an `onChange` handler on the shared `programSubscriber` that filters
+     * updates down to this instance's `userAccountPublicKey`. Does not itself call
+     * `programSubscriber.subscribe()` — the caller is responsible for starting the shared program
+     * subscription separately.
+     * @param userAccount Optional pre-fetched account data to seed with immediately (at slot 0).
+     */
     async subscribe(userAccount) {
         if (this.isSubscribed) {
             return true;
@@ -19,6 +38,11 @@ class WebSocketProgramUserAccountSubscriber {
             this.updateData(userAccount, 0);
         }
         this.programSubscriber.onChange = (accountId, data, context) => {
+            // the shared programSubscriber callback isn't detached on unsubscribe(), so
+            // guard here to stop delivering updates once this facade is unsubscribed
+            if (!this.isSubscribed) {
+                return;
+            }
             if (accountId.equals(this.userAccountPublicKey)) {
                 this.updateData(data, context.slot);
                 this.eventEmitter.emit('userAccountUpdate', data);
@@ -28,6 +52,7 @@ class WebSocketProgramUserAccountSubscriber {
         this.isSubscribed = true;
         return true;
     }
+    /** Fetches the account once directly via `program.account.user.fetch` (independent of the shared program subscription), storing the result at slot 0 (not the fetch's actual slot). Throws `NotSubscribedError` if not subscribed. */
     async fetch() {
         if (!this.isSubscribed) {
             throw new types_1.NotSubscribedError('Must subscribe before fetching account updates');
@@ -35,15 +60,23 @@ class WebSocketProgramUserAccountSubscriber {
         const account = await this.program.account.user.fetch(this.userAccountPublicKey);
         this.updateData(account, 0);
     }
+    /**
+     * Overwrites the cached data unconditionally — unlike most other `updateData` implementations
+     * in this directory, there is no slot-ordering guard here, so a caller must not pass stale data.
+     * @param userAccount Decoded account data to store.
+     * @param slot Slot the data was observed at.
+     */
     updateData(userAccount, slot) {
         this.userAccountAndSlot = {
             data: userAccount,
             slot,
         };
     }
+    /** Marks this facade unsubscribed. Does not touch the shared `programSubscriber`'s `onChange` handler or its subscription state. */
     async unsubscribe() {
         this.isSubscribed = false;
     }
+    /** Throws `NotSubscribedError` if not subscribed. Returns undefined only if subscribed but no data has loaded yet. */
     getUserAccountAndSlot() {
         if (!this.isSubscribed) {
             throw new types_1.NotSubscribedError('You must call `subscribe` before using this function');

package/lib/node/addresses/marketAddresses.d.ts

@@ -1,3 +1,13 @@
 import { PublicKey } from '@solana/web3.js';
+/**
+ * Derives (and memoizes) a `PerpMarket` account's PDA. Thin wrapper over
+ * `getPerpMarketPublicKey` that caches results in a module-level `Map` keyed by
+ * `${programId}-${marketIndex}` so repeated calls for the same market avoid redoing the
+ * `findProgramAddress` computation. The cache is process-lifetime and never invalidated/evicted —
+ * safe because a market's PDA for a given `programId`/`marketIndex` never changes.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Perp market index.
+ * @returns The `PerpMarket` account's public key.
+ */
 export declare function getMarketAddress(programId: PublicKey, marketIndex: number): Promise<PublicKey>;
 //# sourceMappingURL=marketAddresses.d.ts.map

package/lib/node/addresses/marketAddresses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"marketAddresses.d.ts","sourceRoot":"","sources":["../../../src/addresses/marketAddresses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C,wBAAsB,gBAAgB,CACrC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,CAAC,CAUpB"}
+{"version":3,"file":"marketAddresses.d.ts","sourceRoot":"","sources":["../../../src/addresses/marketAddresses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5C;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACrC,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,CAAC,CAUpB"}

package/lib/node/addresses/marketAddresses.js

@@ -3,6 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMarketAddress = void 0;
 const pda_1 = require("./pda");
 const CACHE = new Map();
+/**
+ * Derives (and memoizes) a `PerpMarket` account's PDA. Thin wrapper over
+ * `getPerpMarketPublicKey` that caches results in a module-level `Map` keyed by
+ * `${programId}-${marketIndex}` so repeated calls for the same market avoid redoing the
+ * `findProgramAddress` computation. The cache is process-lifetime and never invalidated/evicted —
+ * safe because a market's PDA for a given `programId`/`marketIndex` never changes.
+ * @param programId - Deployed velocity program id.
+ * @param marketIndex - Perp market index.
+ * @returns The `PerpMarket` account's public key.
+ */
 async function getMarketAddress(programId, marketIndex) {
     const cacheKey = `${programId.toString()}-${marketIndex.toString()}`;
     const cached = CACHE.get(cacheKey);