@velocity-exchange/sdk 0.3.0 → 0.4.0

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

@@ -2,12 +2,53 @@ import { WebSocketVelocityClientAccountSubscriber } from './webSocketVelocityCli
 import { OracleInfo } from '../oracles/types';
 import { VelocityProgram } from '../config';
 import { DelistedMarketSetting, GrpcConfigs, ResubOpts } from './types';
+/**
+ * `VelocityClientAccountSubscriber` variant of `WebSocketVelocityClientAccountSubscriber` that
+ * subscribes each per-account subscriber via `grpcAccountSubscriber.create` (gRPC Geyser stream)
+ * instead of `connection.onAccountChange`. Reuses the parent class's `setInitialData`/oracle-map/
+ * delisted-market logic verbatim; only the account-subscription creation is overridden.
+ */
 export declare class grpcVelocityClientAccountSubscriber extends WebSocketVelocityClientAccountSubscriber {
     private grpcConfigs;
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+     * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing.
+     * @param resubOpts Resubscription watchdog options passed to every per-account subscriber.
+     */
     constructor(grpcConfigs: GrpcConfigs, program: VelocityProgram, perpMarketIndexes: number[], spotMarketIndexes: number[], oracleInfos: OracleInfo[], shouldFindAllMarketsAndOracles: boolean, delistedMarketSetting: DelistedMarketSetting, resubOpts?: ResubOpts);
+    /**
+     * Subscribes the `State` account via gRPC, batch-seeds all market/oracle accounts via
+     * `setInitialData()` (inherited RPC-based batch fetch), then subscribes every per-account gRPC
+     * subscriber for perp markets, spot markets, and oracles. Applies `delistedMarketSetting`
+     * afterward. Idempotent: a no-op if already subscribed, and concurrent calls while a subscribe
+     * is in flight share the same result via `subscriptionPromise`.
+     */
     subscribe(): Promise<boolean>;
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one spot market, seeding it from
+     * `initialSpotMarketAccountData` if available.
+     * @param marketIndex Spot market index to subscribe.
+     */
     subscribeToSpotMarketAccount(marketIndex: number): Promise<boolean>;
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one perp market, seeding it from
+     * `initialPerpMarketAccountData` if available. Unlike the parent class's WebSocket variant,
+     * does not call `ensureAccountFetched` — the gRPC subscriber's own initial `fetch()` (inside
+     * `subscribe`) is relied on directly.
+     * @param marketIndex Perp market index to subscribe.
+     */
     subscribeToPerpMarketAccount(marketIndex: number): Promise<boolean>;
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one oracle, decoding buffers with the
+     * source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available.
+     * @param oracleInfo Oracle pubkey and source to subscribe.
+     * @returns `false` if no `OracleClient` is registered for `oracleInfo.source`; otherwise `true`.
+     */
     subscribeToOracle(oracleInfo: OracleInfo): Promise<boolean>;
 }
 //# sourceMappingURL=grpcVelocityClientAccountSubscriber.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"grpcVelocityClientAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcVelocityClientAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wCAAwC,EAAE,MAAM,4CAA4C,CAAC;AACtG,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAA2B,eAAe,EAAE,MAAM,WAAW,CAAC;AAMrE,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKxE,qBAAa,mCAAoC,SAAQ,wCAAwC;IAChG,OAAO,CAAC,WAAW,CAAc;gBAGhC,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,eAAe,EACxB,iBAAiB,EAAE,MAAM,EAAE,EAC3B,iBAAiB,EAAE,MAAM,EAAE,EAC3B,WAAW,EAAE,UAAU,EAAE,EACzB,8BAA8B,EAAE,OAAO,EACvC,qBAAqB,EAAE,qBAAqB,EAC5C,SAAS,CAAC,EAAE,SAAS;IAcT,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAmF3B,4BAA4B,CAC1C,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IA2Bb,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BnE,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAsCjE"}
+{"version":3,"file":"grpcVelocityClientAccountSubscriber.d.ts","sourceRoot":"","sources":["../../../src/accounts/grpcVelocityClientAccountSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wCAAwC,EAAE,MAAM,4CAA4C,CAAC;AACtG,OAAO,EAAE,UAAU,EAAmB,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAA2B,eAAe,EAAE,MAAM,WAAW,CAAC;AAMrE,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKxE;;;;;GAKG;AACH,qBAAa,mCAAoC,SAAQ,wCAAwC;IAChG,OAAO,CAAC,WAAW,CAAc;IAEjC;;;;;;;;;OASG;gBAEF,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,eAAe,EACxB,iBAAiB,EAAE,MAAM,EAAE,EAC3B,iBAAiB,EAAE,MAAM,EAAE,EAC3B,WAAW,EAAE,UAAU,EAAE,EACzB,8BAA8B,EAAE,OAAO,EACvC,qBAAqB,EAAE,qBAAqB,EAC5C,SAAS,CAAC,EAAE,SAAS;IActB;;;;;;OAMG;IACU,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAmF1C;;;;OAIG;IACY,4BAA4B,CAC1C,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC;IA2BnB;;;;;;OAMG;IACG,4BAA4B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2BzE;;;;;OAKG;IACG,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAsCjE"}

package/lib/node/accounts/grpcVelocityClientAccountSubscriber.js

@@ -6,11 +6,34 @@ const config_1 = require("../config");
 const pda_1 = require("../addresses/pda");
 const grpcAccountSubscriber_1 = require("./grpcAccountSubscriber");
 const oracleId_1 = require("../oracles/oracleId");
+/**
+ * `VelocityClientAccountSubscriber` variant of `WebSocketVelocityClientAccountSubscriber` that
+ * subscribes each per-account subscriber via `grpcAccountSubscriber.create` (gRPC Geyser stream)
+ * instead of `connection.onAccountChange`. Reuses the parent class's `setInitialData`/oracle-map/
+ * delisted-market logic verbatim; only the account-subscription creation is overridden.
+ */
 class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccountSubscriber_1.WebSocketVelocityClientAccountSubscriber {
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+     * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing.
+     * @param resubOpts Resubscription watchdog options passed to every per-account subscriber.
+     */
     constructor(grpcConfigs, program, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting, resubOpts) {
         super(program, perpMarketIndexes, spotMarketIndexes, oracleInfos, shouldFindAllMarketsAndOracles, delistedMarketSetting, resubOpts);
         this.grpcConfigs = grpcConfigs;
     }
+    /**
+     * Subscribes the `State` account via gRPC, batch-seeds all market/oracle accounts via
+     * `setInitialData()` (inherited RPC-based batch fetch), then subscribes every per-account gRPC
+     * subscriber for perp markets, spot markets, and oracles. Applies `delistedMarketSetting`
+     * afterward. Idempotent: a no-op if already subscribed, and concurrent calls while a subscribe
+     * is in flight share the same result via `subscriptionPromise`.
+     */
     async subscribe() {
         if (this.isSubscribed) {
             return true;
@@ -59,6 +82,11 @@ class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccount
         this.removeInitialData();
         return true;
     }
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one spot market, seeding it from
+     * `initialSpotMarketAccountData` if available.
+     * @param marketIndex Spot market index to subscribe.
+     */
     async subscribeToSpotMarketAccount(marketIndex) {
         var _a;
         const marketPublicKey = await (0, pda_1.getSpotMarketPublicKey)(this.program.programId, marketIndex);
@@ -74,6 +102,13 @@ class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccount
         this.spotMarketAccountSubscribers.set(marketIndex, accountSubscriber);
         return true;
     }
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one perp market, seeding it from
+     * `initialPerpMarketAccountData` if available. Unlike the parent class's WebSocket variant,
+     * does not call `ensureAccountFetched` — the gRPC subscriber's own initial `fetch()` (inside
+     * `subscribe`) is relied on directly.
+     * @param marketIndex Perp market index to subscribe.
+     */
     async subscribeToPerpMarketAccount(marketIndex) {
         var _a;
         const perpMarketPublicKey = await (0, pda_1.getPerpMarketPublicKey)(this.program.programId, marketIndex);
@@ -89,6 +124,12 @@ class grpcVelocityClientAccountSubscriber extends webSocketVelocityClientAccount
         this.perpMarketAccountSubscribers.set(marketIndex, accountSubscriber);
         return true;
     }
+    /**
+     * Creates and subscribes a `grpcAccountSubscriber` for one oracle, decoding buffers with the
+     * source-appropriate `OracleClient`. Seeds from `initialOraclePriceData` if available.
+     * @param oracleInfo Oracle pubkey and source to subscribe.
+     * @returns `false` if no `OracleClient` is registered for `oracleInfo.source`; otherwise `true`.
+     */
     async subscribeToOracle(oracleInfo) {
         var _a;
         const oracleId = (0, oracleId_1.getOracleId)(oracleInfo.publicKey, oracleInfo.source);

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

@@ -7,6 +7,15 @@ import { VelocityProgram } from '../config';
 import { AccountSubscriber, DataAndSlot, DelistedMarketSetting, VelocityClientAccountEvents, VelocityClientAccountSubscriber, GrpcConfigs, ResubOpts } from './types';
 import { PerpMarketAccount, SpotMarketAccount, StateAccount } from '../types';
 import { OracleClientCache } from '../oracles/oracleClientCache';
+/**
+ * `VelocityClientAccountSubscriber` variant that, unlike `grpcVelocityClientAccountSubscriber`
+ * (one gRPC stream per account), multiplexes all perp markets onto one `grpcMultiAccountSubscriber`,
+ * all spot markets onto a second, and all oracles onto a third — three gRPC streams total instead
+ * of one per account. Lower connection/stream overhead at scale; `getOraclePriceDataAndSlot`
+ * relies on this class's own `oracleIdToOracleDataMap` rather than the multi-subscriber's account
+ * map, since a single oracle pubkey can back multiple `(pubkey, source)` oracle ids (e.g. a market
+ * pair sharing an underlying price feed).
+ */
 export declare class grpcVelocityClientAccountSubscriberV2 implements VelocityClientAccountSubscriber {
     private grpcConfigs;
     private perpMarketsSubscriber?;
@@ -36,31 +45,138 @@ export declare class grpcVelocityClientAccountSubscriberV2 implements VelocityCl
     private resubOpts?;
     private subscriptionPromiseResolver;
     private subscriptionPromise;
+    /**
+     * @param grpcConfigs gRPC Geyser endpoint/token/commitment config (Yellowstone or LaserStream).
+     * @param program Anchor program used to derive PDAs, decode accounts, and resolve oracle clients.
+     * @param perpMarketIndexes Perp market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param spotMarketIndexes Spot market indexes to track, if `shouldFindAllMarketsAndOracles` is false.
+     * @param oracleInfos Oracles to track up front, if `shouldFindAllMarketsAndOracles` is false.
+     * @param shouldFindAllMarketsAndOracles If true, `subscribe()` first discovers every market/oracle from on-chain state.
+     * @param delistedMarketSetting Behavior applied to delisted perp markets/oracles after subscribing.
+     * @param resubOpts Resubscription watchdog options passed to the underlying multi-account subscribers.
+     */
     constructor(grpcConfigs: GrpcConfigs, program: VelocityProgram, perpMarketIndexes: number[], spotMarketIndexes: number[], oracleInfos: OracleInfo[], shouldFindAllMarketsAndOracles: boolean, delistedMarketSetting: DelistedMarketSetting, resubOpts?: ResubOpts);
     chunks: <T>(array: readonly T[], size: number) => T[][];
+    /**
+     * Batch-fetches every tracked perp market, spot market, and oracle account via chunked
+     * `getMultipleAccountsInfo` calls (75 pubkeys per chunk) and stashes the decoded results in
+     * `initialPerpMarketAccountData`/`initialSpotMarketAccountData`/`initialOraclePriceData`, which
+     * the multi-account subscribers seed from before their gRPC streams deliver live data. Skips
+     * data already populated (e.g. by `findAllMarketAndOracles` when `shouldFindAllMarketsAndOracles`
+     * is set).
+     */
     setInitialData(): Promise<void>;
+    /**
+     * Records `_marketIndex` in `perpMarketIndexes` for bookkeeping. Note this does **not**
+     * actually add the account to the live `perpMarketsSubscriber` gRPC stream — unlike the
+     * WebSocket/per-account subscribers' `addPerpMarket`, no new subscription is created here.
+     * @param _marketIndex Perp market index to record.
+     */
     addPerpMarket(_marketIndex: number): Promise<boolean>;
+    /** No-op; unlike `addPerpMarket`, does not even record the index. Always resolves `true`. */
     addSpotMarket(_marketIndex: number): Promise<boolean>;
+    /**
+     * Adds an oracle to `oracleInfos` and, if the oracle multi-subscriber's gRPC stream is already
+     * active, calls `oracleMultiSubscriber.addAccounts` to extend it. A no-op that resolves `true`
+     * immediately for the `PublicKey.default` sentinel (quote-asset "no oracle") or an oracle
+     * already tracked.
+     * @param oracleInfo Oracle pubkey and source to start tracking.
+     */
     addOracle(oracleInfo: OracleInfo): Promise<boolean>;
+    /**
+     * Subscribes the `State` account (single-account gRPC subscriber), batch-seeds all market/
+     * oracle accounts via `setInitialData()`, then opens the three multiplexed
+     * `grpcMultiAccountSubscriber` streams (perp markets, spot markets, oracles). Applies
+     * `delistedMarketSetting` afterward. Idempotent: a no-op if already subscribed, and concurrent
+     * calls while a subscribe is in flight share the same result via `subscriptionPromise`.
+     */
     subscribe(): Promise<boolean>;
+    private subscribeInner;
+    /** Fetches the `State` account and all three multiplexed subscribers (perp markets, spot markets, oracles) in sequence. */
     fetch(): Promise<void>;
+    /** Throws `NotSubscribedError` if `subscribe()` has not been called. */
     private assertIsSubscribed;
+    /** Throws `NotSubscribedError` if not subscribed. */
     getStateAccountAndSlot(): DataAndSlot<StateAccount>;
+    /** Returns every currently cached (loaded) perp market from the multiplexed subscriber. Does not throw `NotSubscribedError`. */
     getMarketAccountsAndSlots(): DataAndSlot<PerpMarketAccount>[];
+    /** Returns every currently cached (loaded) spot market from the multiplexed subscriber. Does not throw `NotSubscribedError`. */
     getSpotMarketAccountsAndSlots(): DataAndSlot<SpotMarketAccount>[];
+    /** Returns the cached perp market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getMarketAccountAndSlot(marketIndex: number): DataAndSlot<PerpMarketAccount> | undefined;
+    /** Returns the cached spot market, or undefined if `marketIndex` isn't tracked (or hasn't loaded yet). Does not throw `NotSubscribedError`. */
     getSpotMarketAccountAndSlot(marketIndex: number): DataAndSlot<SpotMarketAccount> | undefined;
+    /**
+     * Looks up cached oracle price data by oracle id (see `getOracleId`), from this class's own
+     * `oracleIdToOracleDataMap` rather than `oracleMultiSubscriber.getAccountData` — a single
+     * oracle pubkey backing multiple oracle ids (e.g. shared price feeds) means the multi-subscriber's
+     * own account map cannot be trusted to disambiguate them correctly.
+     * @param oracleId Oracle id string from `getOracleId(publicKey, source)`.
+     * @returns Cached price data/slot, or undefined if not tracked. Throws `NotSubscribedError` if not subscribed.
+     */
     getOraclePriceDataAndSlot(oracleId: string): DataAndSlot<OraclePriceData> | undefined;
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a perp market's
+     * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+     * `perpOracleMap`, triggers a background `setPerpOracleMap()` refresh and still returns the
+     * (possibly stale) mapping for this call.
+     * @param marketIndex Perp market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForPerpMarket(marketIndex: number): DataAndSlot<OraclePriceData> | undefined;
+    /**
+     * Convenience lookup: resolves the oracle price data currently mapped to a spot market's
+     * oracle. If the cached market's oracle pubkey has drifted from (or isn't yet in)
+     * `spotOracleMap`, triggers a background `setSpotOracleMap()` refresh and still returns the
+     * (possibly stale) mapping for this call.
+     * @param marketIndex Spot market index whose oracle price to look up.
+     */
     getOraclePriceDataAndSlotForSpotMarket(marketIndex: number): DataAndSlot<OraclePriceData> | undefined;
+    /** Rebuilds `perpOracleMap`/`perpOracleStringMap` from currently cached perp markets, calling `addOracle` for any oracle not yet tracked by `oracleMultiSubscriber`. */
     setPerpOracleMap(): Promise<void>;
+    /** Rebuilds `spotOracleMap`/`spotOracleStringMap` from currently cached spot markets, calling `addOracle` for any oracle not yet tracked by `oracleMultiSubscriber`. */
     setSpotOracleMap(): Promise<void>;
+    /**
+     * Creates `perpMarketsSubscriber` (a `grpcMultiAccountSubscriber<PerpMarketAccount>`), seeds
+     * it with `initialPerpMarketAccountData`, and subscribes it to every tracked perp market
+     * pubkey in one gRPC stream. Registers an `onUnsubscribe` handler that automatically
+     * re-invokes this method to resubscribe if the underlying stream drops.
+     */
     subscribeToPerpMarketAccounts(): Promise<boolean>;
+    /**
+     * Creates `spotMarketsSubscriber` (a `grpcMultiAccountSubscriber<SpotMarketAccount>`), seeds
+     * it with `initialSpotMarketAccountData`, and subscribes it to every tracked spot market
+     * pubkey in one gRPC stream. Registers an `onUnsubscribe` handler that automatically
+     * re-invokes this method to resubscribe if the underlying stream drops.
+     */
     subscribeToSpotMarketAccounts(): Promise<boolean>;
+    /**
+     * Creates `oracleMultiSubscriber` (a `grpcMultiAccountSubscriber<OraclePriceData, OracleInfo>`)
+     * and subscribes it to every distinct oracle pubkey in one gRPC stream, decoding buffers with
+     * the source-appropriate `OracleClient`. Because multiple `(pubkey, source)` oracle ids can
+     * share one pubkey, `oraclePubkeyToInfosMap` fans a single decode out to every matching
+     * `OracleInfo`, and results are additionally indexed into `oracleIdToOracleDataMap` (by oracle
+     * id, not pubkey) for `getOraclePriceDataAndSlot` to read. Registers an `onUnsubscribe` handler
+     * that automatically re-invokes this method to resubscribe if the underlying stream drops.
+     */
     subscribeToOracles(): Promise<boolean>;
+    /**
+     * Applies `delistedMarketSetting` to any perp market currently `status: delisted` (and its
+     * oracle, if not shared with a live spot market) by removing its pubkey from the relevant
+     * `grpcMultiAccountSubscriber` via `removeAccounts`. A no-op if the setting is `Subscribe`.
+     * Unlike the WebSocket/polling variants, this does not distinguish `Unsubscribe` from
+     * `Discard` — both remove the account from the multiplexed stream (there is no per-account
+     * "keep last known data, stop streaming" state to preserve at this granularity).
+     */
     handleDelistedMarkets(): Promise<void>;
+    /** Clears the seed data stashed by `setInitialData()` once the multi-account subscribers have consumed it, freeing the memory. */
     removeInitialData(): void;
+    /** Tears down `oracleMultiSubscriber`'s gRPC stream, if active, and clears the reference. */
     unsubscribeFromOracles(): Promise<void>;
+    /**
+     * Tears down the `State` subscriber and all three multiplexed subscribers (perp markets, spot
+     * markets, oracles), then clears every internal map to avoid holding stale references. A no-op
+     * if not subscribed.
+     */
     unsubscribe(): Promise<void>;
 }
 //# sourceMappingURL=grpcVelocityClientAccountSubscriberV2.d.ts.map

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

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

package/lib/node/accounts/grpcVelocityClientAccountSubscriberV2.js

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