@velocity-exchange/sdk 0.3.0 → 0.6.0

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

@@ -3,6 +3,26 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import { BN } from '../isomorphic/anchor';
 import { OraclePriceData } from './types';
+/**
+ * Fetches an account's raw data, throwing if the account does not exist. Shared by every
+ * `OracleClient.getOraclePriceData` implementation so a missing oracle account fails loudly rather
+ * than silently decoding garbage/zeroed data.
+ * @param connection - RPC connection to fetch from.
+ * @param pricePublicKey - The oracle account's address.
+ * @param oracleName - Human-readable oracle name used only in the thrown error message (e.g. `"Pyth oracle"`).
+ * @returns The account's raw data buffer.
+ * @throws Error if the account does not exist.
+ */
 export declare function getOracleAccountDataOrThrow(connection: Connection, pricePublicKey: PublicKey, oracleName: string): Promise<Buffer>;
+/**
+ * Derives an effective confidence interval for the market-maker (MM) oracle price by widening the
+ * primary oracle's confidence by however far the MM price has diverged from it. Used when
+ * validating the MM oracle (via `getOracleValidity`) so a large MM/primary-oracle divergence
+ * degrades MM-oracle validity the same way low primary-oracle confidence would, rather than
+ * evaluating MM price divergence with an artificially tight confidence band.
+ * @param mmOraclePrice - The perp market's cached MM oracle price, PRICE_PRECISION (1e6).
+ * @param oraclePriceData - The primary oracle's current price data (`price`/`confidence` in PRICE_PRECISION, 1e6).
+ * @returns `oraclePriceData.confidence + |mmOraclePrice - oraclePriceData.price|`, PRICE_PRECISION (1e6).
+ */
 export declare function getOracleConfidenceFromMMOracleData(mmOraclePrice: BN, oraclePriceData: OraclePriceData): BN;
 //# sourceMappingURL=utils.d.ts.map

package/lib/node/oracles/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/oracles/utils.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,wBAAsB,2BAA2B,CAChD,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,SAAS,EACzB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAgB,mCAAmC,CAClD,aAAa,EAAE,EAAE,EACjB,eAAe,EAAE,eAAe,GAC9B,EAAE,CAGJ"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/oracles/utils.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,EAAE,EAAE,MAAM,sBAAsB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAChD,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,SAAS,EACzB,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mCAAmC,CAClD,aAAa,EAAE,EAAE,EACjB,eAAe,EAAE,eAAe,GAC9B,EAAE,CAGJ"}

package/lib/node/oracles/utils.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getOracleConfidenceFromMMOracleData = exports.getOracleAccountDataOrThrow = void 0;
+/**
+ * Fetches an account's raw data, throwing if the account does not exist. Shared by every
+ * `OracleClient.getOraclePriceData` implementation so a missing oracle account fails loudly rather
+ * than silently decoding garbage/zeroed data.
+ * @param connection - RPC connection to fetch from.
+ * @param pricePublicKey - The oracle account's address.
+ * @param oracleName - Human-readable oracle name used only in the thrown error message (e.g. `"Pyth oracle"`).
+ * @returns The account's raw data buffer.
+ * @throws Error if the account does not exist.
+ */
 async function getOracleAccountDataOrThrow(connection, pricePublicKey, oracleName) {
     const accountInfo = await connection.getAccountInfo(pricePublicKey);
     if (!accountInfo) {
@@ -9,6 +19,16 @@ async function getOracleAccountDataOrThrow(connection, pricePublicKey, oracleNam
     return accountInfo.data;
 }
 exports.getOracleAccountDataOrThrow = getOracleAccountDataOrThrow;
+/**
+ * Derives an effective confidence interval for the market-maker (MM) oracle price by widening the
+ * primary oracle's confidence by however far the MM price has diverged from it. Used when
+ * validating the MM oracle (via `getOracleValidity`) so a large MM/primary-oracle divergence
+ * degrades MM-oracle validity the same way low primary-oracle confidence would, rather than
+ * evaluating MM price divergence with an artificially tight confidence band.
+ * @param mmOraclePrice - The perp market's cached MM oracle price, PRICE_PRECISION (1e6).
+ * @param oraclePriceData - The primary oracle's current price data (`price`/`confidence` in PRICE_PRECISION, 1e6).
+ * @returns `oraclePriceData.confidence + |mmOraclePrice - oraclePriceData.price|`, PRICE_PRECISION (1e6).
+ */
 function getOracleConfidenceFromMMOracleData(mmOraclePrice, oraclePriceData) {
     const mmOracleDiffPremium = mmOraclePrice.sub(oraclePriceData.price).abs();
     return oraclePriceData.confidence.add(mmOracleDiffPremium);

package/lib/node/orderParams.d.ts

@@ -1,29 +1,67 @@
 import { OptionalOrderParams, OrderParams, OrderTriggerCondition } from './types';
 import { BN } from './isomorphic/anchor';
+/**
+ * Builds `OptionalOrderParams` for a resting limit order (`OrderType.LIMIT`).
+ * Unlike a market order, a limit order has no auction and rests on the book at `price` until
+ * filled, cancelled, or expired.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount` is in BASE_PRECISION
+ * (1e9), `price` is in PRICE_PRECISION (1e6). `orderType` is set automatically and must not be
+ * passed in.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 export declare function getLimitOrderParams(params: Omit<OptionalOrderParams, 'orderType'> & {
     price: BN;
 }): OptionalOrderParams;
+/**
+ * Builds `OptionalOrderParams` for a trigger market order (`OrderType.TRIGGER_MARKET`) — a
+ * conditional order (e.g. stop-loss/take-profit) that becomes an auctioned market order once the
+ * oracle price crosses `triggerPrice` per `triggerCondition`.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount` and `triggerPrice` use
+ * BASE_PRECISION (1e9) and PRICE_PRECISION (1e6) respectively. `orderType` is set automatically.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 export declare function getTriggerMarketOrderParams(params: Omit<OptionalOrderParams, 'orderType'> & {
     triggerCondition: OrderTriggerCondition;
     triggerPrice: BN;
 }): OptionalOrderParams;
+/**
+ * Builds `OptionalOrderParams` for a trigger limit order (`OrderType.TRIGGER_LIMIT`) — a
+ * conditional order that becomes a resting limit order at `price` once the oracle price crosses
+ * `triggerPrice` per `triggerCondition`.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount`, `triggerPrice`, and `price`
+ * use BASE_PRECISION (1e9) and PRICE_PRECISION (1e6) respectively. `orderType` is set automatically.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 export declare function getTriggerLimitOrderParams(params: Omit<OptionalOrderParams, 'orderType'> & {
     triggerCondition: OrderTriggerCondition;
     triggerPrice: BN;
     price: BN;
 }): OptionalOrderParams;
+/**
+ * Builds `OptionalOrderParams` for a market order (`OrderType.MARKET`), filled immediately via a
+ * Dutch auction between `auctionStartPrice` and `auctionEndPrice` (defaults derived on-chain from
+ * the oracle price if omitted) over `auctionDuration` slots.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount` is in BASE_PRECISION (1e9),
+ * any price fields are in PRICE_PRECISION (1e6). `orderType` is set automatically and must not be
+ * passed in.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 export declare function getMarketOrderParams(params: Omit<OptionalOrderParams, 'orderType'>): OptionalOrderParams;
 /**
- * Creates an OrderParams object with the given OptionalOrderParams and any params to override.
+ * Merges `optionalOrderParams` onto `DefaultOrderParams` (filling in any field the caller omitted,
+ * e.g. `marketType: MarketType.PERP`, `reduceOnly: false`, no trigger/oracle-offset), then applies
+ * `overridingParams` on top of that. Used internally by the `get*OrderParams` factories; call it
+ * directly only if you need to force a field that a factory doesn't expose.
  *
  * example:
  * ```
  * const orderParams = getOrderParams(optionalOrderParams, { marketType: MarketType.PERP });
  * ```
  *
- * @param optionalOrderParams
- * @param overridingParams
- * @returns
+ * @param optionalOrderParams - Required order fields plus any optional `OrderParams` overrides.
+ * @param overridingParams - Fields applied last, taking precedence over both the defaults and
+ * `optionalOrderParams`.
+ * @returns A fully-populated `OrderParams` object.
  */
 export declare function getOrderParams(optionalOrderParams: OptionalOrderParams, overridingParams?: Record<string, any>): OrderParams;
 //# sourceMappingURL=orderParams.d.ts.map

package/lib/node/orderParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orderParams.d.ts","sourceRoot":"","sources":["../../src/orderParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EAErB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAEzC,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAAE,KAAK,EAAE,EAAE,CAAA;CAAE,GAC5D,mBAAmB,CAMrB;AAED,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAChD,gBAAgB,EAAE,qBAAqB,CAAC;IACxC,YAAY,EAAE,EAAE,CAAC;CACjB,GACC,mBAAmB,CAMrB;AAED,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAChD,gBAAgB,EAAE,qBAAqB,CAAC;IACxC,YAAY,EAAE,EAAE,CAAC;IACjB,KAAK,EAAE,EAAE,CAAC;CACV,GACC,mBAAmB,CAMrB;AAED,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAC5C,mBAAmB,CAMrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC7B,mBAAmB,EAAE,mBAAmB,EACxC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GACxC,WAAW,CAOb"}
+{"version":3,"file":"orderParams.d.ts","sourceRoot":"","sources":["../../src/orderParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,mBAAmB,EACnB,WAAW,EACX,qBAAqB,EAErB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAEzC;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAAE,KAAK,EAAE,EAAE,CAAA;CAAE,GAC5D,mBAAmB,CAMrB;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAChD,gBAAgB,EAAE,qBAAqB,CAAC;IACxC,YAAY,EAAE,EAAE,CAAC;CACjB,GACC,mBAAmB,CAMrB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAAG;IAChD,gBAAgB,EAAE,qBAAqB,CAAC;IACxC,YAAY,EAAE,EAAE,CAAC;IACjB,KAAK,EAAE,EAAE,CAAC;CACV,GACC,mBAAmB,CAMrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,GAC5C,mBAAmB,CAMrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAC7B,mBAAmB,EAAE,mBAAmB,EACxC,gBAAgB,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,GACxC,WAAW,CAOb"}

package/lib/node/orderParams.js

@@ -2,24 +2,58 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getOrderParams = exports.getMarketOrderParams = exports.getTriggerLimitOrderParams = exports.getTriggerMarketOrderParams = exports.getLimitOrderParams = void 0;
 const types_1 = require("./types");
+/**
+ * Builds `OptionalOrderParams` for a resting limit order (`OrderType.LIMIT`).
+ * Unlike a market order, a limit order has no auction and rests on the book at `price` until
+ * filled, cancelled, or expired.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount` is in BASE_PRECISION
+ * (1e9), `price` is in PRICE_PRECISION (1e6). `orderType` is set automatically and must not be
+ * passed in.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 function getLimitOrderParams(params) {
     return getOrderParams(Object.assign({}, params, {
         orderType: types_1.OrderType.LIMIT,
     }));
 }
 exports.getLimitOrderParams = getLimitOrderParams;
+/**
+ * Builds `OptionalOrderParams` for a trigger market order (`OrderType.TRIGGER_MARKET`) — a
+ * conditional order (e.g. stop-loss/take-profit) that becomes an auctioned market order once the
+ * oracle price crosses `triggerPrice` per `triggerCondition`.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount` and `triggerPrice` use
+ * BASE_PRECISION (1e9) and PRICE_PRECISION (1e6) respectively. `orderType` is set automatically.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 function getTriggerMarketOrderParams(params) {
     return getOrderParams(Object.assign({}, params, {
         orderType: types_1.OrderType.TRIGGER_MARKET,
     }));
 }
 exports.getTriggerMarketOrderParams = getTriggerMarketOrderParams;
+/**
+ * Builds `OptionalOrderParams` for a trigger limit order (`OrderType.TRIGGER_LIMIT`) — a
+ * conditional order that becomes a resting limit order at `price` once the oracle price crosses
+ * `triggerPrice` per `triggerCondition`.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount`, `triggerPrice`, and `price`
+ * use BASE_PRECISION (1e9) and PRICE_PRECISION (1e6) respectively. `orderType` is set automatically.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 function getTriggerLimitOrderParams(params) {
     return getOrderParams(Object.assign({}, params, {
         orderType: types_1.OrderType.TRIGGER_LIMIT,
     }));
 }
 exports.getTriggerLimitOrderParams = getTriggerLimitOrderParams;
+/**
+ * Builds `OptionalOrderParams` for a market order (`OrderType.MARKET`), filled immediately via a
+ * Dutch auction between `auctionStartPrice` and `auctionEndPrice` (defaults derived on-chain from
+ * the oracle price if omitted) over `auctionDuration` slots.
+ * @param params - Order fields (see `OrderParams`); `baseAssetAmount` is in BASE_PRECISION (1e9),
+ * any price fields are in PRICE_PRECISION (1e6). `orderType` is set automatically and must not be
+ * passed in.
+ * @returns Params merged onto `DefaultOrderParams`, ready to pass to `placeOrder`/`placePerpOrder`.
+ */
 function getMarketOrderParams(params) {
     return getOrderParams(Object.assign({}, params, {
         orderType: types_1.OrderType.MARKET,
@@ -27,16 +61,20 @@ function getMarketOrderParams(params) {
 }
 exports.getMarketOrderParams = getMarketOrderParams;
 /**
- * Creates an OrderParams object with the given OptionalOrderParams and any params to override.
+ * Merges `optionalOrderParams` onto `DefaultOrderParams` (filling in any field the caller omitted,
+ * e.g. `marketType: MarketType.PERP`, `reduceOnly: false`, no trigger/oracle-offset), then applies
+ * `overridingParams` on top of that. Used internally by the `get*OrderParams` factories; call it
+ * directly only if you need to force a field that a factory doesn't expose.
  *
  * example:
  * ```
  * const orderParams = getOrderParams(optionalOrderParams, { marketType: MarketType.PERP });
  * ```
  *
- * @param optionalOrderParams
- * @param overridingParams
- * @returns
+ * @param optionalOrderParams - Required order fields plus any optional `OrderParams` overrides.
+ * @param overridingParams - Fields applied last, taking precedence over both the defaults and
+ * `optionalOrderParams`.
+ * @returns A fully-populated `OrderParams` object.
  */
 function getOrderParams(optionalOrderParams, overridingParams = {}) {
     return Object.assign({}, types_1.DefaultOrderParams, optionalOrderParams, overridingParams);

package/lib/node/orderSubscriber/OrderSubscriber.d.ts

@@ -12,6 +12,15 @@ import { WebsocketSubscription } from './WebsocketSubscription';
 import StrictEventEmitter from 'strict-event-emitter-types';
 import { EventEmitter } from 'events';
 import { grpcSubscription } from './grpcSubscription';
+/**
+ * OrderSubscriber — maintains a live, in-memory map of every `User` account
+ * (and therefore every open order) on the program, refreshed via polling,
+ * websocket program-account subscription, or gRPC/Laserstream, depending on
+ * `config.subscriptionConfig.type`. Used by keeper bots and `DLOBSubscriber`
+ * to build a full DLOB without individually subscribing to each trader's
+ * `User` account. Emits `orderCreated`/`userUpdated`/`updateReceived` on
+ * `eventEmitter` as updates arrive; see `OrderSubscriberEvents`.
+ */
 export declare class OrderSubscriber {
     velocityClient: VelocityClient;
     usersAccounts: Map<string, {
@@ -27,9 +36,38 @@ export declare class OrderSubscriber {
     decodeFn: (name: string, data: Buffer) => UserAccount;
     decodeData?: boolean;
     fetchAllNonIdleUsers?: boolean;
+    /**
+     * @param config Subscription config. `subscriptionConfig.type` selects the transport (`'polling'`, `'websocket'`, or `'grpc'`); `fastDecode` (default `true`) uses the hand-written `decodeUser` fast path instead of the Anchor coder; `fetchAllNonIdleUsers` (default `false`) widens the account filter from "has at least one order" to "any non-idle user", useful for consumers that need idle-but-active accounts too.
+     * @throws If `config.velocityClient` is not provided.
+     */
     constructor(config: OrderSubscriberConfig);
+    /** Starts the underlying transport (polling interval, websocket program-account subscription, or gRPC stream) chosen at construction time. */
     subscribe(): Promise<void>;
+    /**
+     * One-shot full refresh: fetches every `User` account matching the
+     * configured filters via `getProgramAccounts` and feeds each through
+     * `tryUpdateUserAccount`. Concurrent calls share the in-flight promise
+     * rather than issuing a second `getProgramAccounts` request. Errors are
+     * caught and logged, not thrown — the promise still resolves.
+     */
     fetch(): Promise<void>;
+    /**
+     * Applies an incoming update for the `User` account `key`, called by
+     * `fetch`, `addPubkey`, and each subscription transport
+     * (`PollingSubscription`/`WebsocketSubscription`/`grpcSubscription`).
+     * Advances `mostRecentSlot` and always emits `updateReceived`. The stored
+     * account is only replaced if `slot` is >= the currently cached slot for
+     * that key; for `'raw'`/`'buffer'` inputs, before decoding it also cheaply
+     * peeks the account's `lastActiveSlot` field at a fixed byte offset and
+     * discards the update if that's older than what's cached, without paying
+     * the cost of a full decode. On acceptance, emits `userUpdated`, and
+     * `orderCreated` for any orders in the account whose `order.slot` falls in
+     * `(previousSlot, slot]`.
+     * @param key Base58 pubkey of the `User` account.
+     * @param dataType `'raw'` (base64/base58 tuple from `getProgramAccounts`), `'decoded'` (already an Anchor-decoded `UserAccount`), or `'buffer'` (raw account bytes) — determines how `data` is interpreted/decoded.
+     * @param data The account payload, shaped per `dataType`.
+     * @param slot Slot the update was observed at.
+     */
     tryUpdateUserAccount(key: string, dataType: 'raw' | 'decoded' | 'buffer', data: string[] | UserAccount | Buffer, slot: number): void;
     /**
      * Creates a new DLOB for the order subscriber to fill. This will allow a
@@ -37,10 +75,28 @@ export declare class OrderSubscriber {
      * @returns New, empty DLOB object.
      */
     protected createDLOB(): DLOB;
+    /**
+     * Builds a fresh `DLOB` from the currently cached `User` accounts. For
+     * reduce-only orders, resolves the base asset amount against the trader's
+     * existing perp position (via `calculateOrderBaseAssetAmount`, `BASE_PRECISION`,
+     * 1e9) rather than trusting the order's own `baseAssetAmount` field, since a
+     * reduce-only order's fillable size is capped by the position it reduces.
+     * @param slot Slot to stamp onto inserted orders (used by the DLOB for auction/expiry timing, not for filtering which accounts are included).
+     * @returns A new `DLOB` populated with every order across all cached users.
+     */
     getDLOB(slot: number): Promise<DLOB>;
+    /** @returns The highest slot observed across all account updates so far, or 0 if none have arrived yet. */
     getSlot(): number;
+    /** Fetches a single `User` account directly (bypassing the subscription's filters) and applies it via `tryUpdateUserAccount`. Useful to backfill an account this subscriber's filters would otherwise exclude (e.g. an idle user with no orders). No-ops if the account doesn't exist. */
     addPubkey(userAccountPublicKey: PublicKey): Promise<void>;
+    /**
+     * Returns the cached `UserAccount` for `key`, fetching it on demand via
+     * `addPubkey` if not already cached.
+     * @param key Base58 pubkey of the `User` account.
+     * @throws If the account still isn't present after `addPubkey` (e.g. it doesn't exist on-chain).
+     */
     mustGetUserAccount(key: string): Promise<UserAccount>;
+    /** Stops the underlying transport and clears the entire cached `User` account map. */
     unsubscribe(): Promise<void>;
 }
 //# sourceMappingURL=OrderSubscriber.d.ts.map

package/lib/node/orderSubscriber/OrderSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OrderSubscriber.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/OrderSubscriber.ts"],"names":[],"mappings":";;;AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAMvC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAyB,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,kBAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AActD,qBAAa,eAAe;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa;cAA2B,MAAM;qBAAe,WAAW;OAAM;IAC9E,YAAY,EAAE,mBAAmB,GAAG,qBAAqB,GAAG,gBAAgB,CAAC;IAC7E,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,qBAAqB,CAAC,CAAC;IAEtE,YAAY,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,oBAAoB,CAAwB;IAEpD,cAAc,SAAK;IACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,WAAW,CAAC;IACtD,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,oBAAoB,CAAC,EAAE,OAAO,CAAC;gBAEnB,MAAM,EAAE,qBAAqB;IAkD5B,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6D5B,oBAAoB,CACnB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,EACtC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,MAAM,EACrC,IAAI,EAAE,MAAM,GACV,IAAI;IAsFP;;;;OAIG;IACH,SAAS,CAAC,UAAU,IAAI,IAAI;IAIf,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB1C,OAAO,IAAI,MAAM;IAIX,SAAS,CAAC,oBAAoB,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBzD,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAarD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAIzC"}
+{"version":3,"file":"OrderSubscriber.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/OrderSubscriber.ts"],"names":[],"mappings":";;;AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAMvC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAyB,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACpC,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,kBAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AActD;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa;cAA2B,MAAM;qBAAe,WAAW;OAAM;IAC9E,YAAY,EAAE,mBAAmB,GAAG,qBAAqB,GAAG,gBAAgB,CAAC;IAC7E,UAAU,EAAE,UAAU,CAAC;IACvB,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,qBAAqB,CAAC,CAAC;IAEtE,YAAY,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,oBAAoB,CAAwB;IAEpD,cAAc,SAAK;IACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,WAAW,CAAC;IACtD,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;OAGG;gBACS,MAAM,EAAE,qBAAqB;IAkDzC,8IAA8I;IACjI,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiE5B;;;;;;;;;;;;;;;;OAgBG;IACH,oBAAoB,CACnB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,EACtC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,GAAG,MAAM,EACrC,IAAI,EAAE,MAAM,GACV,IAAI;IAsFP;;;;OAIG;IACH,SAAS,CAAC,UAAU,IAAI,IAAI;IAI5B;;;;;;;;OAQG;IACU,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjD,2GAA2G;IACpG,OAAO,IAAI,MAAM;IAIxB,0RAA0R;IAC7Q,SAAS,CAAC,oBAAoB,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBtE;;;;;OAKG;IACU,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAalE,sFAAsF;IACzE,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAIzC"}

package/lib/node/orderSubscriber/OrderSubscriber.js

@@ -22,7 +22,20 @@ const numericConstants_1 = require("../constants/numericConstants");
  * zero-padding bytes, so the staleness guard rejected every post-load update.
  */
 const USER_LAST_ACTIVE_SLOT_OFFSET = 4448;
+/**
+ * OrderSubscriber — maintains a live, in-memory map of every `User` account
+ * (and therefore every open order) on the program, refreshed via polling,
+ * websocket program-account subscription, or gRPC/Laserstream, depending on
+ * `config.subscriptionConfig.type`. Used by keeper bots and `DLOBSubscriber`
+ * to build a full DLOB without individually subscribing to each trader's
+ * `User` account. Emits `orderCreated`/`userUpdated`/`updateReceived` on
+ * `eventEmitter` as updates arrive; see `OrderSubscriberEvents`.
+ */
 class OrderSubscriber {
+    /**
+     * @param config Subscription config. `subscriptionConfig.type` selects the transport (`'polling'`, `'websocket'`, or `'grpc'`); `fastDecode` (default `true`) uses the hand-written `decodeUser` fast path instead of the Anchor coder; `fetchAllNonIdleUsers` (default `false`) widens the account filter from "has at least one order" to "any non-idle user", useful for consumers that need idle-but-active accounts too.
+     * @throws If `config.velocityClient` is not provided.
+     */
     constructor(config) {
         var _a, _b, _c, _d, _e;
         this.usersAccounts = new Map();
@@ -75,9 +88,17 @@ class OrderSubscriber {
         this.eventEmitter = new events_1.EventEmitter();
         this.fetchAllNonIdleUsers = config.fetchAllNonIdleUsers;
     }
+    /** Starts the underlying transport (polling interval, websocket program-account subscription, or gRPC stream) chosen at construction time. */
     async subscribe() {
         await this.subscription.subscribe();
     }
+    /**
+     * One-shot full refresh: fetches every `User` account matching the
+     * configured filters via `getProgramAccounts` and feeds each through
+     * `tryUpdateUserAccount`. Concurrent calls share the in-flight promise
+     * rather than issuing a second `getProgramAccounts` request. Errors are
+     * caught and logged, not thrown — the promise still resolves.
+     */
     async fetch() {
         if (this.fetchPromise) {
             return this.fetchPromise;
@@ -103,6 +124,9 @@ class OrderSubscriber {
             await this.velocityClient.connection._rpcRequest('getProgramAccounts', rpcRequestArgs);
             const rpcResponseAndContext = rpcJSONResponse.result;
             const slot = rpcResponseAndContext.context.slot;
+            if (!this.mostRecentSlot || slot > this.mostRecentSlot) {
+                this.mostRecentSlot = slot;
+            }
             for (const programAccount of rpcResponseAndContext.value) {
                 const key = programAccount.pubkey.toString();
                 this.tryUpdateUserAccount(key, 'raw', programAccount.account.data, slot);
@@ -118,6 +142,23 @@ class OrderSubscriber {
             this.fetchPromise = undefined;
         }
     }
+    /**
+     * Applies an incoming update for the `User` account `key`, called by
+     * `fetch`, `addPubkey`, and each subscription transport
+     * (`PollingSubscription`/`WebsocketSubscription`/`grpcSubscription`).
+     * Advances `mostRecentSlot` and always emits `updateReceived`. The stored
+     * account is only replaced if `slot` is >= the currently cached slot for
+     * that key; for `'raw'`/`'buffer'` inputs, before decoding it also cheaply
+     * peeks the account's `lastActiveSlot` field at a fixed byte offset and
+     * discards the update if that's older than what's cached, without paying
+     * the cost of a full decode. On acceptance, emits `userUpdated`, and
+     * `orderCreated` for any orders in the account whose `order.slot` falls in
+     * `(previousSlot, slot]`.
+     * @param key Base58 pubkey of the `User` account.
+     * @param dataType `'raw'` (base64/base58 tuple from `getProgramAccounts`), `'decoded'` (already an Anchor-decoded `UserAccount`), or `'buffer'` (raw account bytes) — determines how `data` is interpreted/decoded.
+     * @param data The account payload, shaped per `dataType`.
+     * @param slot Slot the update was observed at.
+     */
     tryUpdateUserAccount(key, dataType, data, slot) {
         if (!this.mostRecentSlot || slot > this.mostRecentSlot) {
             this.mostRecentSlot = slot;
@@ -169,6 +210,15 @@ class OrderSubscriber {
     createDLOB() {
         return new DLOB_1.DLOB();
     }
+    /**
+     * Builds a fresh `DLOB` from the currently cached `User` accounts. For
+     * reduce-only orders, resolves the base asset amount against the trader's
+     * existing perp position (via `calculateOrderBaseAssetAmount`, `BASE_PRECISION`,
+     * 1e9) rather than trusting the order's own `baseAssetAmount` field, since a
+     * reduce-only order's fillable size is capped by the position it reduces.
+     * @param slot Slot to stamp onto inserted orders (used by the DLOB for auction/expiry timing, not for filtering which accounts are included).
+     * @returns A new `DLOB` populated with every order across all cached users.
+     */
     async getDLOB(slot) {
         var _a;
         const dlob = this.createDLOB();
@@ -184,16 +234,24 @@ class OrderSubscriber {
         }
         return dlob;
     }
+    /** @returns The highest slot observed across all account updates so far, or 0 if none have arrived yet. */
     getSlot() {
         var _a;
         return (_a = this.mostRecentSlot) !== null && _a !== void 0 ? _a : 0;
     }
+    /** Fetches a single `User` account directly (bypassing the subscription's filters) and applies it via `tryUpdateUserAccount`. Useful to backfill an account this subscriber's filters would otherwise exclude (e.g. an idle user with no orders). No-ops if the account doesn't exist. */
     async addPubkey(userAccountPublicKey) {
         const accountInfo = await this.velocityClient.connection.getAccountInfoAndContext(userAccountPublicKey, this.commitment);
         if (accountInfo.value) {
             this.tryUpdateUserAccount(userAccountPublicKey.toString(), 'buffer', accountInfo.value.data, accountInfo.context.slot);
         }
     }
+    /**
+     * Returns the cached `UserAccount` for `key`, fetching it on demand via
+     * `addPubkey` if not already cached.
+     * @param key Base58 pubkey of the `User` account.
+     * @throws If the account still isn't present after `addPubkey` (e.g. it doesn't exist on-chain).
+     */
     async mustGetUserAccount(key) {
         if (!this.usersAccounts.has(key)) {
             await this.addPubkey(new web3_js_1.PublicKey(key));
@@ -204,6 +262,7 @@ class OrderSubscriber {
         }
         return slotAndUserAccount.userAccount;
     }
+    /** Stops the underlying transport and clears the entire cached `User` account map. */
     async unsubscribe() {
         this.usersAccounts.clear();
         await this.subscription.unsubscribe();

package/lib/node/orderSubscriber/PollingSubscription.d.ts

@@ -1,13 +1,24 @@
 import { OrderSubscriber } from './OrderSubscriber';
+/**
+ * `OrderSubscriber` transport that repeatedly calls `OrderSubscriber.fetch()`
+ * (a full `getProgramAccounts` snapshot) on a fixed interval. Simplest and
+ * most RPC-expensive transport; prefer websocket or grpc for large user sets.
+ */
 export declare class PollingSubscription {
     private orderSubscriber;
     private frequency;
     intervalId?: ReturnType<typeof setTimeout>;
+    /**
+     * @param orderSubscriber The `OrderSubscriber` to feed with each poll.
+     * @param frequency Poll interval in milliseconds.
+     */
     constructor({ orderSubscriber, frequency, }: {
         orderSubscriber: OrderSubscriber;
         frequency: number;
     });
+    /** Starts the polling interval and performs one immediate `fetch()` before returning. Idempotent while already subscribed. */
     subscribe(): Promise<void>;
+    /** Stops the polling interval. */
     unsubscribe(): Promise<void>;
 }
 //# sourceMappingURL=PollingSubscription.d.ts.map

package/lib/node/orderSubscriber/PollingSubscription.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PollingSubscription.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/PollingSubscription.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,qBAAa,mBAAmB;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,SAAS,CAAS;IAE1B,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;gBAE/B,EACX,eAAe,EACf,SAAS,GACT,EAAE;QACF,eAAe,EAAE,eAAe,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC;KAClB;IAKY,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAa1B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAMzC"}
+{"version":3,"file":"PollingSubscription.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/PollingSubscription.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC/B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,SAAS,CAAS;IAE1B,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAE3C;;;OAGG;gBACS,EACX,eAAe,EACf,SAAS,GACT,EAAE;QACF,eAAe,EAAE,eAAe,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC;KAClB;IAKD,8HAA8H;IACjH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAavC,kCAAkC;IACrB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CAMzC"}

package/lib/node/orderSubscriber/PollingSubscription.js

@@ -1,11 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingSubscription = void 0;
+/**
+ * `OrderSubscriber` transport that repeatedly calls `OrderSubscriber.fetch()`
+ * (a full `getProgramAccounts` snapshot) on a fixed interval. Simplest and
+ * most RPC-expensive transport; prefer websocket or grpc for large user sets.
+ */
 class PollingSubscription {
+    /**
+     * @param orderSubscriber The `OrderSubscriber` to feed with each poll.
+     * @param frequency Poll interval in milliseconds.
+     */
     constructor({ orderSubscriber, frequency, }) {
         this.orderSubscriber = orderSubscriber;
         this.frequency = frequency;
     }
+    /** Starts the polling interval and performs one immediate `fetch()` before returning. Idempotent while already subscribed. */
     async subscribe() {
         if (this.intervalId) {
             return;
@@ -13,6 +23,7 @@ class PollingSubscription {
         this.intervalId = setInterval(this.orderSubscriber.fetch.bind(this.orderSubscriber), this.frequency);
         await this.orderSubscriber.fetch();
     }
+    /** Stops the polling interval. */
     async unsubscribe() {
         if (this.intervalId) {
             clearInterval(this.intervalId);

package/lib/node/orderSubscriber/WebsocketSubscription.d.ts

@@ -1,6 +1,14 @@
 import { OrderSubscriber } from './OrderSubscriber';
 import { Commitment } from '@solana/web3.js';
 import { ResubOpts } from '../accounts/types';
+/**
+ * `OrderSubscriber` transport backed by a websocket `WebSocketProgramAccountSubscriber`
+ * filtered to non-idle `User` accounts. On subscribe, optionally performs an
+ * initial full `fetch()` snapshot (unless `skipInitialLoad`), then applies
+ * live updates as they arrive; if `resyncIntervalMs` is set, also runs a
+ * periodic full `fetch()` resync alongside the subscription to self-heal any
+ * missed program-account notifications.
+ */
 export declare class WebsocketSubscription {
     private orderSubscriber;
     private commitment;
@@ -10,6 +18,14 @@ export declare class WebsocketSubscription {
     private subscriber?;
     private resyncTimeoutId?;
     private decoded?;
+    /**
+     * @param orderSubscriber The `OrderSubscriber` to feed with updates.
+     * @param commitment Commitment level for the program-account subscription.
+     * @param skipInitialLoad Skip the initial full `fetch()` snapshot after subscribing; defaults to `false`.
+     * @param resubOpts Reconnect behavior for the underlying `WebSocketProgramAccountSubscriber`.
+     * @param resyncIntervalMs If set, runs a periodic full `fetch()` resync at this interval.
+     * @param decoded Whether updates are delivered already Anchor-decoded (`true`, default) or as raw buffers for `OrderSubscriber` to decode itself.
+     */
     constructor({ orderSubscriber, commitment, skipInitialLoad, resubOpts, resyncIntervalMs, decoded, }: {
         orderSubscriber: OrderSubscriber;
         commitment: Commitment;
@@ -18,7 +34,9 @@ export declare class WebsocketSubscription {
         resyncIntervalMs?: number;
         decoded?: boolean;
     });
+    /** Establishes the websocket program-account subscription (idempotent — no-op if already subscribed), optionally backfills with `fetch()`, and starts the resync timer if configured. */
     subscribe(): Promise<void>;
+    /** Tears down the program-account subscription and cancels the resync timer, if any. No-op if not subscribed. */
     unsubscribe(): Promise<void>;
 }
 //# sourceMappingURL=WebsocketSubscription.d.ts.map

package/lib/node/orderSubscriber/WebsocketSubscription.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebsocketSubscription.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/WebsocketSubscription.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,UAAU,EAAsB,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C,qBAAa,qBAAqB;IACjC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,SAAS,CAAC,CAAY;IAC9B,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAElC,OAAO,CAAC,UAAU,CAAC,CAAiD;IACpE,OAAO,CAAC,eAAe,CAAC,CAAgC;IAExD,OAAO,CAAC,OAAO,CAAC,CAAU;gBAEd,EACX,eAAe,EACf,UAAU,EACV,eAAuB,EACvB,SAAS,EACT,gBAAgB,EAChB,OAAc,GACd,EAAE;QACF,eAAe,EAAE,eAAe,CAAC;QACjC,UAAU,EAAE,UAAU,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;KAClB;IASY,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE1B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CASzC"}
+{"version":3,"file":"WebsocketSubscription.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/WebsocketSubscription.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,OAAO,EAAE,UAAU,EAAsB,MAAM,iBAAiB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG9C;;;;;;;GAOG;AACH,qBAAa,qBAAqB;IACjC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,eAAe,CAAU;IACjC,OAAO,CAAC,SAAS,CAAC,CAAY;IAC9B,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAElC,OAAO,CAAC,UAAU,CAAC,CAAiD;IACpE,OAAO,CAAC,eAAe,CAAC,CAAgC;IAExD,OAAO,CAAC,OAAO,CAAC,CAAU;IAE1B;;;;;;;OAOG;gBACS,EACX,eAAe,EACf,UAAU,EACV,eAAuB,EACvB,SAAS,EACT,gBAAgB,EAChB,OAAc,GACd,EAAE;QACF,eAAe,EAAE,eAAe,CAAC;QACjC,UAAU,EAAE,UAAU,CAAC;QACvB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;KAClB;IASD,yLAAyL;IAC5K,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAmEvC,iHAAiH;IACpG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;CASzC"}

package/lib/node/orderSubscriber/WebsocketSubscription.js

@@ -3,7 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebsocketSubscription = void 0;
 const memcmp_1 = require("../memcmp");
 const webSocketProgramAccountSubscriber_1 = require("../accounts/webSocketProgramAccountSubscriber");
+/**
+ * `OrderSubscriber` transport backed by a websocket `WebSocketProgramAccountSubscriber`
+ * filtered to non-idle `User` accounts. On subscribe, optionally performs an
+ * initial full `fetch()` snapshot (unless `skipInitialLoad`), then applies
+ * live updates as they arrive; if `resyncIntervalMs` is set, also runs a
+ * periodic full `fetch()` resync alongside the subscription to self-heal any
+ * missed program-account notifications.
+ */
 class WebsocketSubscription {
+    /**
+     * @param orderSubscriber The `OrderSubscriber` to feed with updates.
+     * @param commitment Commitment level for the program-account subscription.
+     * @param skipInitialLoad Skip the initial full `fetch()` snapshot after subscribing; defaults to `false`.
+     * @param resubOpts Reconnect behavior for the underlying `WebSocketProgramAccountSubscriber`.
+     * @param resyncIntervalMs If set, runs a periodic full `fetch()` resync at this interval.
+     * @param decoded Whether updates are delivered already Anchor-decoded (`true`, default) or as raw buffers for `OrderSubscriber` to decode itself.
+     */
     constructor({ orderSubscriber, commitment, skipInitialLoad = false, resubOpts, resyncIntervalMs, decoded = true, }) {
         this.orderSubscriber = orderSubscriber;
         this.commitment = commitment;
@@ -12,6 +28,7 @@ class WebsocketSubscription {
         this.resyncIntervalMs = resyncIntervalMs;
         this.decoded = decoded;
     }
+    /** Establishes the websocket program-account subscription (idempotent — no-op if already subscribed), optionally backfills with `fetch()`, and starts the resync timer if configured. */
     async subscribe() {
         if (this.subscriber) {
             return;
@@ -53,6 +70,7 @@ class WebsocketSubscription {
             recursiveResync();
         }
     }
+    /** Tears down the program-account subscription and cancels the resync timer, if any. No-op if not subscribed. */
     async unsubscribe() {
         if (!this.subscriber)
             return;

package/lib/node/orderSubscriber/grpcSubscription.d.ts

@@ -1,5 +1,11 @@
 import { OrderSubscriber } from './OrderSubscriber';
 import { GrpcConfigs, ResubOpts } from '../accounts/types';
+/**
+ * `OrderSubscriber` transport backed by a gRPC Geyser stream — either the
+ * standard `grpcProgramAccountSubscriber` or, when `grpcConfigs.client ===
+ * 'laser'`, `LaserstreamProgramAccountSubscriber` — filtered to non-idle
+ * `User` accounts. Same initial-load/resync semantics as `WebsocketSubscription`.
+ */
 export declare class grpcSubscription {
     private orderSubscriber;
     private skipInitialLoad;
@@ -9,6 +15,14 @@ export declare class grpcSubscription {
     private resyncTimeoutId?;
     private decoded?;
     private grpcConfigs;
+    /**
+     * @param grpcConfigs gRPC/Geyser endpoint config; `client: 'laser'` selects the Laserstream implementation, otherwise the standard gRPC subscriber is used.
+     * @param orderSubscriber The `OrderSubscriber` to feed with updates.
+     * @param skipInitialLoad Skip the initial full `fetch()` snapshot after subscribing; defaults to `false`.
+     * @param resubOpts Reconnect behavior for the underlying gRPC subscriber.
+     * @param resyncIntervalMs If set, runs a periodic full `fetch()` resync at this interval.
+     * @param decoded Whether updates are delivered already Anchor-decoded (`true`, default) or as raw buffers for `OrderSubscriber` to decode itself.
+     */
     constructor({ grpcConfigs, orderSubscriber, skipInitialLoad, resubOpts, resyncIntervalMs, decoded, }: {
         grpcConfigs: GrpcConfigs;
         orderSubscriber: OrderSubscriber;
@@ -17,7 +31,9 @@ export declare class grpcSubscription {
         resyncIntervalMs?: number;
         decoded?: boolean;
     });
+    /** Establishes the gRPC/Laserstream program-account subscription (idempotent), optionally backfills with `fetch()`, and starts the resync timer if configured. */
     subscribe(): Promise<void>;
+    /** Tears down the gRPC subscription and cancels the resync timer, if any. No-op if not subscribed. */
     unsubscribe(): Promise<void>;
 }
 //# sourceMappingURL=grpcSubscription.d.ts.map