@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/oracles/pythLazerClient.js

@@ -10,7 +10,24 @@ const numericConstants_1 = require("../constants/numericConstants");
 const wallet_1 = require("../wallet");
 const velocity_json_1 = __importDefault(require("../idl/velocity.json"));
 const utils_1 = require("./utils");
+/**
+ * `OracleClient` for `PythLazerOracle` accounts — Velocity's on-chain cache of a Pyth Lazer
+ * push-update feed, decoded via the velocity program's own Anchor coder (Lazer has no dedicated
+ * client account layout package, unlike legacy Pyth). Backs the `pythLazer`, `pythLazer1K`,
+ * `pythLazer1M`, and `pythLazerStableCoin` `OracleSource` variants.
+ */
 class PythLazerClient {
+    /**
+     * @param connection - RPC connection used to fetch oracle account data; also used to spin up a
+     * throwaway `AnchorProvider`/`Program` (with a fresh random keypair, never used to sign) purely
+     * to get access to the IDL's `pythLazerOracle` account coder.
+     * @param multiple - Divisor applied to the raw Lazer precision before rescaling to
+     * PRICE_PRECISION; pass `1000`/`1000000` for the `pythLazer1K`/`pythLazer1M` source variants, or
+     * the default `ONE` (1) for a standard per-unit feed.
+     * @param stableCoin - When `true` (the `pythLazerStableCoin` variant), snaps the decoded price
+     * to exactly `QUOTE_PRECISION` (1.0) whenever it is within 5bps (or within `confidence` if
+     * tighter) of peg — see `getStableCoinPrice`.
+     */
     constructor(connection, multiple = numericConstants_1.ONE, stableCoin = false) {
         this.connection = connection;
         this.multiple = multiple;
@@ -23,10 +40,27 @@ class PythLazerClient {
         this.program = new anchor_1.Program(velocity_json_1.default, provider);
         this.decodeFunc = this.program.account.pythLazerOracle.coder.accounts.decodeUnchecked.bind(this.program.account.pythLazerOracle.coder.accounts);
     }
+    /**
+     * Fetches and decodes a `PythLazerOracle` account's current price data.
+     * @param pricePublicKey - The `PythLazerOracle` account's address (see `getPythLazerOraclePublicKey`).
+     * @returns The decoded, normalized price data.
+     * @throws Error if the account does not exist.
+     */
     async getOraclePriceData(pricePublicKey) {
         const data = await (0, utils_1.getOracleAccountDataOrThrow)(this.connection, pricePublicKey, 'Pyth lazer oracle');
         return this.getOraclePriceDataFromBuffer(data);
     }
+    /**
+     * Decodes raw `PythLazerOracle` account bytes into normalized `OraclePriceData`, rescaling from
+     * the feed's native exponent to PRICE_PRECISION (1e6) via `convertPythPrice`. Unlike legacy
+     * Pyth, Lazer has no separate TWAP field on-chain, so `twap`/`twapConfidence` are both set to
+     * the same converted live `price`/`conf` rather than a genuine time-weighted average.
+     * `hasSufficientNumberOfDataPoints` is always `true` (no publisher-count concept for this
+     * source), and `sequenceId` is set to the feed's `publishTime` for staleness/ordering checks.
+     * @param buffer - Raw `PythLazerOracle` account data.
+     * @returns `price`, `confidence`, `twap`, `twapConfidence` (all PRICE_PRECISION 1e6), `slot`
+     * (`postedSlot`, the slot the update landed on-chain), and `sequenceId` (`publishTime`).
+     */
     getOraclePriceDataFromBuffer(buffer) {
         const priceData = this.decodeFunc('pythLazerOracle', buffer);
         const confidence = convertPythPrice(priceData.conf, priceData.exponent, this.multiple);
@@ -53,7 +87,7 @@ function convertPythPrice(price, exponent, multiple) {
 }
 const fiveBPS = new anchor_1.BN(500);
 function getStableCoinPrice(price, confidence) {
-    if (price.sub(numericConstants_1.QUOTE_PRECISION).abs().lt(anchor_1.BN.min(confidence, fiveBPS))) {
+    if (price.sub(numericConstants_1.QUOTE_PRECISION).abs().lte(anchor_1.BN.min(confidence, fiveBPS))) {
         return numericConstants_1.QUOTE_PRECISION;
     }
     else {

package/lib/browser/oracles/quoteAssetOracleClient.d.ts

@@ -2,9 +2,27 @@
 /// <reference types="node" />
 import { PublicKey } from '@solana/web3.js';
 import { OracleClient, OraclePriceData } from './types';
+/**
+ * Fixed price of exactly 1.0 (PRICE_PRECISION, 1e6) with a minimal confidence band, returned by
+ * `QuoteAssetOracleClient` for any oracle lookup. Represents the quote asset (e.g. USDC) pegged
+ * 1:1 to itself with no real oracle needed.
+ */
 export declare const QUOTE_ORACLE_PRICE_DATA: OraclePriceData;
+/**
+ * `OracleClient` for the `quoteAsset` `OracleSource` variant — the spot market whose asset *is*
+ * the protocol's quote currency. Ignores its inputs entirely and always returns the constant
+ * `QUOTE_ORACLE_PRICE_DATA` (price 1.0); never makes an RPC call.
+ */
 export declare class QuoteAssetOracleClient implements OracleClient {
     constructor();
+    /**
+     * @param _pricePublicKey - Ignored.
+     * @returns The constant `QUOTE_ORACLE_PRICE_DATA`.
+     */
     getOraclePriceData(_pricePublicKey: PublicKey): Promise<OraclePriceData>;
+    /**
+     * @param _buffer - Ignored.
+     * @returns The constant `QUOTE_ORACLE_PRICE_DATA`.
+     */
     getOraclePriceDataFromBuffer(_buffer: Buffer): OraclePriceData;
 }

package/lib/browser/oracles/quoteAssetOracleClient.js

@@ -3,17 +3,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.QuoteAssetOracleClient = exports.QUOTE_ORACLE_PRICE_DATA = void 0;
 const anchor_1 = require("../isomorphic/anchor");
 const numericConstants_1 = require("../constants/numericConstants");
+/**
+ * Fixed price of exactly 1.0 (PRICE_PRECISION, 1e6) with a minimal confidence band, returned by
+ * `QuoteAssetOracleClient` for any oracle lookup. Represents the quote asset (e.g. USDC) pegged
+ * 1:1 to itself with no real oracle needed.
+ */
 exports.QUOTE_ORACLE_PRICE_DATA = {
     price: numericConstants_1.PRICE_PRECISION,
     slot: new anchor_1.BN(0),
     confidence: new anchor_1.BN(1),
     hasSufficientNumberOfDataPoints: true,
 };
+/**
+ * `OracleClient` for the `quoteAsset` `OracleSource` variant — the spot market whose asset *is*
+ * the protocol's quote currency. Ignores its inputs entirely and always returns the constant
+ * `QUOTE_ORACLE_PRICE_DATA` (price 1.0); never makes an RPC call.
+ */
 class QuoteAssetOracleClient {
     constructor() { }
+    /**
+     * @param _pricePublicKey - Ignored.
+     * @returns The constant `QUOTE_ORACLE_PRICE_DATA`.
+     */
     async getOraclePriceData(_pricePublicKey) {
         return Promise.resolve(exports.QUOTE_ORACLE_PRICE_DATA);
     }
+    /**
+     * @param _buffer - Ignored.
+     * @returns The constant `QUOTE_ORACLE_PRICE_DATA`.
+     */
     getOraclePriceDataFromBuffer(_buffer) {
         return exports.QUOTE_ORACLE_PRICE_DATA;
     }

package/lib/browser/oracles/strictOraclePrice.d.ts

@@ -1,8 +1,29 @@
 import { BN } from '../isomorphic/anchor';
+/**
+ * Pairs a live oracle price with its 5-minute TWAP so margin/value calculations can pick whichever
+ * is more conservative — mirroring the on-chain "strict" price used for collateral valuation, which
+ * exists so a transient price spike/dip can't be used to over-value collateral or under-value a
+ * liability. All values are PRICE_PRECISION (1e6).
+ */
 export declare class StrictOraclePrice {
     current: BN;
     twap?: BN;
+    /**
+     * @param current - Live oracle price, PRICE_PRECISION (1e6).
+     * @param twap - 5-minute oracle TWAP, PRICE_PRECISION (1e6). If omitted, `max()`/`min()` both
+     * fall back to `current`.
+     */
     constructor(current: BN, twap?: BN);
+    /**
+     * The higher of `current` and `twap` — use when a higher price is the conservative choice
+     * (e.g. valuing a liability/borrow, where undervaluing it would overstate free collateral).
+     * @returns The larger of `current` and `twap` (or just `current` if no `twap` was provided), PRICE_PRECISION (1e6).
+     */
     max(): BN;
+    /**
+     * The lower of `current` and `twap` — use when a lower price is the conservative choice (e.g.
+     * valuing a deposit/asset, where overvaluing it would overstate free collateral).
+     * @returns The smaller of `current` and `twap` (or just `current` if no `twap` was provided), PRICE_PRECISION (1e6).
+     */
     min(): BN;
 }

package/lib/browser/oracles/strictOraclePrice.js

@@ -2,14 +2,35 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StrictOraclePrice = void 0;
 const anchor_1 = require("../isomorphic/anchor");
+/**
+ * Pairs a live oracle price with its 5-minute TWAP so margin/value calculations can pick whichever
+ * is more conservative — mirroring the on-chain "strict" price used for collateral valuation, which
+ * exists so a transient price spike/dip can't be used to over-value collateral or under-value a
+ * liability. All values are PRICE_PRECISION (1e6).
+ */
 class StrictOraclePrice {
+    /**
+     * @param current - Live oracle price, PRICE_PRECISION (1e6).
+     * @param twap - 5-minute oracle TWAP, PRICE_PRECISION (1e6). If omitted, `max()`/`min()` both
+     * fall back to `current`.
+     */
     constructor(current, twap) {
         this.current = current;
         this.twap = twap;
     }
+    /**
+     * The higher of `current` and `twap` — use when a higher price is the conservative choice
+     * (e.g. valuing a liability/borrow, where undervaluing it would overstate free collateral).
+     * @returns The larger of `current` and `twap` (or just `current` if no `twap` was provided), PRICE_PRECISION (1e6).
+     */
     max() {
         return this.twap ? anchor_1.BN.max(this.twap, this.current) : this.current;
     }
+    /**
+     * The lower of `current` and `twap` — use when a lower price is the conservative choice (e.g.
+     * valuing a deposit/asset, where overvaluing it would overstate free collateral).
+     * @returns The smaller of `current` and `twap` (or just `current` if no `twap` was provided), PRICE_PRECISION (1e6).
+     */
     min() {
         return this.twap ? anchor_1.BN.min(this.twap, this.current) : this.current;
     }

package/lib/browser/oracles/types.d.ts

@@ -9,24 +9,69 @@
 import { BN } from '../isomorphic/anchor';
 import { PublicKey } from '@solana/web3.js';
 import { OracleSource } from '../types';
+/**
+ * `OraclePriceData` variant for the market-maker (MM) oracle feed, which has no TWAP or
+ * pre-launch `maxPrice` fields but instead flags whether the MM oracle is currently trusted.
+ */
 export type MMOraclePriceData = Omit<OraclePriceData, 'twap' | 'twapConfidence' | 'maxPrice'> & {
+    /** Whether the MM oracle is currently considered active/valid and safe to use in place of the primary oracle. */
     isMMOracleActive: boolean;
+    /**
+     * Whether the MM oracle is enabled (has a non-zero price), mirroring `MMOraclePriceData::is_enabled`.
+     * Populated by `VelocityClient.getMMOracleDataForPerpMarket`; used by the AMM-fill volatility gate
+     * (`isFallbackAvailableLiquiditySource`). Optional because MM data is sometimes constructed without it.
+     */
+    isMMOracleEnabled?: boolean;
+    /**
+     * Whether the MM oracle is at least as recent as the exchange (safe) oracle, mirroring
+     * `MMOraclePriceData::is_mm_oracle_as_recent`. Used together with `isMMExchangeDiffBpsHigh` by the
+     * AMM-fill volatility gate.
+     */
+    isMMOracleAsRecent?: boolean;
+    /**
+     * Whether the MM-vs-exchange oracle price difference exceeds the 1% fallback threshold
+     * (`MM_EXCHANGE_FALLBACK_THRESHOLD`), mirroring `MMOraclePriceData::is_mm_exchange_diff_bps_high`.
+     * When the MM oracle is enabled and as-recent, a high diff suppresses AMM fills (early volatility protection).
+     */
+    isMMExchangeDiffBpsHigh?: boolean;
 };
+/** Normalized oracle price snapshot produced by every `OracleClient`, regardless of underlying source. */
 export type OraclePriceData = {
+    /** Oracle price, PRICE_PRECISION (1e6). */
     price: BN;
+    /** Slot at which this price was last updated on-chain. */
     slot: BN;
+    /** Oracle confidence interval (± band around `price`), PRICE_PRECISION (1e6). */
     confidence: BN;
+    /** Whether the source had enough independent publishers/quoters for the price to be trusted (Pyth-specific; always `true` for sources without a publisher-count concept). */
     hasSufficientNumberOfDataPoints: boolean;
+    /** Time-weighted average price, PRICE_PRECISION (1e6). Absent for sources with no TWAP (e.g. Pyth Lazer echoes the live price here instead). */
     twap?: BN;
+    /** Confidence interval of `twap`, PRICE_PRECISION (1e6). */
     twapConfidence?: BN;
+    /** Upper price bound; only populated for prelaunch-market oracles, PRICE_PRECISION (1e6). */
     maxPrice?: BN;
+    /** Monotonic sequence/publish-time id used to detect out-of-order updates (Pyth Lazer only). */
     sequenceId?: BN;
 };
+/** Identifies an oracle account and which `OracleSource` variant to decode it as. */
 export type OracleInfo = {
     publicKey: PublicKey;
     source: OracleSource;
 };
+/** Common interface implemented by every per-source oracle adapter (Pyth, Pyth Lazer, prelaunch, quote-asset). */
 export interface OracleClient {
+    /**
+     * Decodes raw oracle account bytes into normalized `OraclePriceData` without any RPC call.
+     * @param buffer - Raw account data as returned by `getAccountInfo`/`getMultipleAccounts`.
+     * @returns The decoded, normalized price data.
+     */
     getOraclePriceDataFromBuffer(buffer: Buffer): OraclePriceData;
+    /**
+     * Fetches and decodes an oracle account's current price data.
+     * @param publicKey - The oracle account's address.
+     * @returns The decoded, normalized price data.
+     * @throws Error if the account does not exist.
+     */
     getOraclePriceData(publicKey: PublicKey): Promise<OraclePriceData>;
 }

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

@@ -3,5 +3,25 @@
 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;

package/lib/browser/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/browser/orderParams.d.ts

@@ -1,28 +1,66 @@
 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;

package/lib/browser/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/browser/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,9 +75,27 @@ 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>;
 }