@velocity-exchange/sdk 0.2.5 → 0.4.0

package/src/oracles/types.ts

@@ -8,30 +8,75 @@ 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; // pre-launch markets only
+	/** 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/src/oracles/utils.ts

@@ -2,6 +2,16 @@ 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 async function getOracleAccountDataOrThrow(
 	connection: Connection,
 	pricePublicKey: PublicKey,
@@ -16,6 +26,16 @@ export async function getOracleAccountDataOrThrow(
 	return accountInfo.data;
 }
 
+/**
+ * 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 function getOracleConfidenceFromMMOracleData(
 	mmOraclePrice: BN,
 	oraclePriceData: OraclePriceData

package/src/orderParams.ts

@@ -7,6 +7,15 @@ import {
 } 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 function getLimitOrderParams(
 	params: Omit<OptionalOrderParams, 'orderType'> & { price: BN }
 ): OptionalOrderParams {
@@ -17,6 +26,14 @@ export function 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`.
+ */
 export function getTriggerMarketOrderParams(
 	params: Omit<OptionalOrderParams, 'orderType'> & {
 		triggerCondition: OrderTriggerCondition;
@@ -30,6 +47,14 @@ export function 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`.
+ */
 export function getTriggerLimitOrderParams(
 	params: Omit<OptionalOrderParams, 'orderType'> & {
 		triggerCondition: OrderTriggerCondition;
@@ -44,6 +69,15 @@ export function 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`.
+ */
 export function getMarketOrderParams(
 	params: Omit<OptionalOrderParams, 'orderType'>
 ): OptionalOrderParams {
@@ -55,16 +89,20 @@ export function 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.
  */
 export function getOrderParams(
 	optionalOrderParams: OptionalOrderParams,

package/src/orderSubscriber/OrderSubscriber.ts

@@ -19,6 +19,25 @@ import { grpcSubscription } from './grpcSubscription';
 import { calculateOrderBaseAssetAmount } from '../math/orders';
 import { ZERO } from '../constants/numericConstants';
 
+/*
+ * Byte offset of `lastActiveSlot` (u64) in the `User` account, used here to
+ * cheaply detect stale updates without fully decoding the buffer. Must match
+ * the on-chain `User` layout (see `decode/user.ts`). The previous value (4328)
+ * was for the older 4376-byte layout; the current Velocity layout is 4496
+ * bytes, shifting this field +120 bytes. With the wrong offset this read 8
+ * 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`.
+ */
 export class OrderSubscriber {
 	velocityClient: VelocityClient;
 	usersAccounts = new Map<string, { slot: number; userAccount: UserAccount }>();
@@ -35,6 +54,10 @@ export class OrderSubscriber {
 
 	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) {
 		const velocityClient = config.velocityClient;
 		if (!velocityClient) {
@@ -85,10 +108,18 @@ export class OrderSubscriber {
 		this.fetchAllNonIdleUsers = config.fetchAllNonIdleUsers;
 	}
 
+	/** Starts the underlying transport (polling interval, websocket program-account subscription, or gRPC stream) chosen at construction time. */
 	public async subscribe(): Promise<void> {
 		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(): Promise<void> {
 		if (this.fetchPromise) {
 			return this.fetchPromise;
@@ -150,6 +181,23 @@ export class OrderSubscriber {
 		}
 	}
 
+	/**
+	 * 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',
@@ -176,7 +224,10 @@ export class OrderSubscriber {
 				const buffer = Buffer.from(data[0], data[1]);
 
 				const newLastActiveSlot = new BN(
-					buffer.subarray(4328, 4328 + 8),
+					buffer.subarray(
+						USER_LAST_ACTIVE_SLOT_OFFSET,
+						USER_LAST_ACTIVE_SLOT_OFFSET + 8
+					),
 					undefined,
 					'le'
 				);
@@ -191,7 +242,10 @@ export class OrderSubscriber {
 			} else if (dataType === 'buffer') {
 				const buffer: Buffer = data as Buffer;
 				const newLastActiveSlot = new BN(
-					buffer.subarray(4328, 4328 + 8),
+					buffer.subarray(
+						USER_LAST_ACTIVE_SLOT_OFFSET,
+						USER_LAST_ACTIVE_SLOT_OFFSET + 8
+					),
 					undefined,
 					'le'
 				);
@@ -244,6 +298,15 @@ export class OrderSubscriber {
 		return new 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.
+	 */
 	public async getDLOB(slot: number): Promise<DLOB> {
 		const dlob = this.createDLOB();
 		for (const [key, { userAccount }] of this.usersAccounts.entries()) {
@@ -266,10 +329,12 @@ export class OrderSubscriber {
 		return dlob;
 	}
 
+	/** @returns The highest slot observed across all account updates so far, or 0 if none have arrived yet. */
 	public getSlot(): number {
 		return this.mostRecentSlot ?? 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. */
 	public async addPubkey(userAccountPublicKey: PublicKey): Promise<void> {
 		const accountInfo =
 			await this.velocityClient.connection.getAccountInfoAndContext(
@@ -286,6 +351,12 @@ export class OrderSubscriber {
 		}
 	}
 
+	/**
+	 * 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).
+	 */
 	public async mustGetUserAccount(key: string): Promise<UserAccount> {
 		if (!this.usersAccounts.has(key)) {
 			await this.addPubkey(new PublicKey(key));
@@ -299,6 +370,7 @@ export class OrderSubscriber {
 		return slotAndUserAccount.userAccount;
 	}
 
+	/** Stops the underlying transport and clears the entire cached `User` account map. */
 	public async unsubscribe(): Promise<void> {
 		this.usersAccounts.clear();
 		await this.subscription.unsubscribe();

package/src/orderSubscriber/PollingSubscription.ts

@@ -1,11 +1,20 @@
 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 class PollingSubscription {
 	private orderSubscriber: OrderSubscriber;
 	private frequency: number;
 
 	intervalId?: ReturnType<typeof setTimeout>;
 
+	/**
+	 * @param orderSubscriber The `OrderSubscriber` to feed with each poll.
+	 * @param frequency Poll interval in milliseconds.
+	 */
 	constructor({
 		orderSubscriber,
 		frequency,
@@ -17,6 +26,7 @@ export class PollingSubscription {
 		this.frequency = frequency;
 	}
 
+	/** Starts the polling interval and performs one immediate `fetch()` before returning. Idempotent while already subscribed. */
 	public async subscribe(): Promise<void> {
 		if (this.intervalId) {
 			return;
@@ -30,6 +40,7 @@ export class PollingSubscription {
 		await this.orderSubscriber.fetch();
 	}
 
+	/** Stops the polling interval. */
 	public async unsubscribe(): Promise<void> {
 		if (this.intervalId) {
 			clearInterval(this.intervalId);

package/src/orderSubscriber/WebsocketSubscription.ts

@@ -5,6 +5,14 @@ import { Commitment, Context, PublicKey } from '@solana/web3.js';
 import { ResubOpts } from '../accounts/types';
 import { WebSocketProgramAccountSubscriber } from '../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.
+ */
 export class WebsocketSubscription {
 	private orderSubscriber: OrderSubscriber;
 	private commitment: Commitment;
@@ -17,6 +25,14 @@ export class WebsocketSubscription {
 
 	private decoded?: boolean;
 
+	/**
+	 * @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,
@@ -40,6 +56,7 @@ export class WebsocketSubscription {
 		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. */
 	public async subscribe(): Promise<void> {
 		if (this.subscriber) {
 			return;
@@ -107,6 +124,7 @@ export class WebsocketSubscription {
 		}
 	}
 
+	/** Tears down the program-account subscription and cancels the resync timer, if any. No-op if not subscribed. */
 	public async unsubscribe(): Promise<void> {
 		if (!this.subscriber) return;
 		await this.subscriber.unsubscribe();

package/src/orderSubscriber/grpcSubscription.ts

@@ -7,6 +7,12 @@ import { UserAccount } from '../types';
 import { getUserFilter, getNonIdleUserFilter } from '../memcmp';
 import { LaserstreamProgramAccountSubscriber } from '../accounts/laserProgramAccountSubscriber';
 
+/**
+ * `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 class grpcSubscription {
 	private orderSubscriber: OrderSubscriber;
 	private skipInitialLoad: boolean;
@@ -22,6 +28,14 @@ export class grpcSubscription {
 
 	private grpcConfigs: 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,
@@ -45,6 +59,7 @@ export class grpcSubscription {
 		this.grpcConfigs = grpcConfigs;
 	}
 
+	/** Establishes the gRPC/Laserstream program-account subscription (idempotent), optionally backfills with `fetch()`, and starts the resync timer if configured. */
 	public async subscribe(): Promise<void> {
 		if (this.subscriber) {
 			return;
@@ -127,6 +142,7 @@ export class grpcSubscription {
 		}
 	}
 
+	/** Tears down the gRPC subscription and cancels the resync timer, if any. No-op if not subscribed. */
 	public async unsubscribe(): Promise<void> {
 		if (!this.subscriber) return;
 		await this.subscriber.unsubscribe();

package/src/orderSubscriber/types.ts

@@ -3,8 +3,10 @@ import { Order, UserAccount } from '../types';
 import { VelocityClient } from '../velocityClient';
 import { GrpcConfigs } from '../accounts/types';
 
+/** Configuration for `OrderSubscriber`. */
 export type OrderSubscriberConfig = {
 	velocityClient?: VelocityClient;
+	/** Selects the update transport: `'polling'` (interval `getProgramAccounts`), `'websocket'` (program-account subscription), or `'grpc'` (Geyser/Laserstream). `commitment` defaults to `'processed'` if unset; `skipInitialLoad` (websocket/grpc only) skips the initial `fetch()` full snapshot; `resubTimeoutMs`/`logResubMessages` control websocket/grpc reconnect behavior; `resyncIntervalMs` (websocket/grpc only) triggers a periodic full `fetch()` resync on top of the live subscription. */
 	subscriptionConfig:
 		| {
 				type: 'polling';
@@ -28,12 +30,17 @@ export type OrderSubscriberConfig = {
 				resyncIntervalMs?: number;
 				commitment?: Commitment;
 		  };
+	/** Use the hand-written `decodeUser` fast-path decoder instead of the Anchor account coder. Defaults to `true`. */
 	fastDecode?: boolean;
+	/** For websocket/grpc transports, whether the subscriber's own subscription decodes accounts itself (`true`, default) or passes raw buffers for the caller to decode. */
 	decodeData?: boolean;
+	/** Widen the account filter from "has at least one order" to "any non-idle user", so idle-but-non-empty accounts are also tracked. Defaults to `false`. */
 	fetchAllNonIdleUsers?: boolean;
 };
 
+/** Events emitted on `OrderSubscriber.eventEmitter`. */
 export interface OrderSubscriberEvents {
+	/** Fired when a `User` account update introduces one or more orders newly placed in `(previousObservedSlot, slot]`. */
 	orderCreated: (
 		account: UserAccount,
 		updatedOrders: Order[],
@@ -41,12 +48,14 @@ export interface OrderSubscriberEvents {
 		slot: number,
 		dataType: 'raw' | 'decoded' | 'buffer'
 	) => void;
+	/** Fired whenever a `User` account update is accepted (i.e. not rejected by the staleness/slot check). */
 	userUpdated: (
 		account: UserAccount,
 		pubkey: PublicKey,
 		slot: number,
 		dataType: 'raw' | 'decoded' | 'buffer'
 	) => void;
+	/** Fired for every incoming update, even ones ultimately rejected as stale. */
 	updateReceived: (
 		pubkey: PublicKey,
 		slot: number,

package/src/priorityFee/averageOverSlotsStrategy.ts

@@ -1,6 +1,7 @@
 import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
 import { PriorityFeeStrategy } from './types';
 
+/** `PriorityFeeStrategy` that averages `prioritizationFee` across all samples in the lookback window. Returns `0` for an empty sample set. */
 export class AverageOverSlotsStrategy implements PriorityFeeStrategy {
 	calculate(samples: SolanaPriorityFeeResponse[]): number {
 		if (samples.length === 0) {

package/src/priorityFee/averageStrategy.ts

@@ -1,6 +1,7 @@
 import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
 import { PriorityFeeStrategy } from './types';
 
+/** `PriorityFeeStrategy` that averages `prioritizationFee` across all samples. Unlike `AverageOverSlotsStrategy`, does not guard the empty-sample case — calling with `samples.length === 0` returns `NaN`. */
 export class AverageStrategy implements PriorityFeeStrategy {
 	calculate(samples: SolanaPriorityFeeResponse[]): number {
 		return (

package/src/priorityFee/ewmaStrategy.ts

@@ -1,6 +1,12 @@
 import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
 import { PriorityFeeStrategy } from './types';
 
+/**
+ * `PriorityFeeStrategy` that computes an exponentially-weighted moving
+ * average of `prioritizationFee` over slots, so more recent samples are
+ * weighted more heavily and larger slot gaps decay the older sample's
+ * influence faster.
+ */
 class EwmaStrategy implements PriorityFeeStrategy {
 	private halfLife: number;
 
@@ -12,6 +18,10 @@ class EwmaStrategy implements PriorityFeeStrategy {
 	}
 
 	// samples provided in desc slot order
+	/**
+	 * @param samples Fee samples sorted descending by slot (as returned by `fetchSolanaPriorityFee`). Reversed internally to process oldest-first.
+	 * @returns `0` for an empty sample set; the single sample's fee if only one is provided; otherwise the EWMA, decayed per-step by `1 - exp(ln(0.5) / halfLife * slotGap)`.
+	 */
 	calculate(samples: SolanaPriorityFeeResponse[]): number {
 		if (samples.length === 0) {
 			return 0;

package/src/priorityFee/heliusPriorityFeeMethod.ts

@@ -1,5 +1,6 @@
 import fetch from 'node-fetch';
 
+/** Percentile buckets returned by Helius's `getPriorityFeeEstimate` (`includeAllPriorityFeeLevels`). */
 export enum HeliusPriorityLevel {
 	MIN = 'min', // 25th percentile
 	LOW = 'low', // 25th percentile
@@ -9,21 +10,31 @@ export enum HeliusPriorityLevel {
 	UNSAFE_MAX = 'unsafeMax', // 100th percentile
 }
 
+/** Priority fee (micro-lamports/CU) at each `HeliusPriorityLevel` percentile. */
 export type HeliusPriorityFeeLevels = {
 	[key in HeliusPriorityLevel]: number;
 };
 
+/** Raw JSON-RPC response from Helius's `getPriorityFeeEstimate`. */
 export type HeliusPriorityFeeResponse = {
 	jsonrpc: string;
 	result: {
+		/** Single-value estimate; only populated when `includeAllPriorityFeeLevels` was not requested. */
 		priorityFeeEstimate?: number;
+		/** Per-percentile estimates; populated when `includeAllPriorityFeeLevels: true` is requested (as `fetchHeliusPriorityFee` does). */
 		priorityFeeLevels?: HeliusPriorityFeeLevels;
 	};
 	id: string;
 };
 
-/// Fetches the priority fee from the Helius API
-/// https://docs.helius.dev/solana-rpc-nodes/alpha-priority-fee-api
+/**
+ * Fetches priority fee estimates from the Helius `getPriorityFeeEstimate` API
+ * (https://docs.helius.dev/solana-rpc-nodes/alpha-priority-fee-api).
+ * @param heliusRpcUrl Helius RPC URL to POST the `getPriorityFeeEstimate` request to.
+ * @param lookbackDistance Number of recent slots to consider (`lookbackSlots` option).
+ * @param addresses Account keys to scope the estimate to (accounts the transaction will write-lock).
+ * @returns The full Helius response (with `includeAllPriorityFeeLevels: true`), or `undefined` if the request failed (error is logged, not thrown).
+ */
 export async function fetchHeliusPriorityFee(
 	heliusRpcUrl: string,
 	lookbackDistance: number,

package/src/priorityFee/maxOverSlotsStrategy.ts

@@ -1,6 +1,7 @@
 import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
 import { PriorityFeeStrategy } from './types';
 
+/** `PriorityFeeStrategy` that takes the max `prioritizationFee` across all samples in the lookback window. Returns `0` for an empty sample set. */
 export class MaxOverSlotsStrategy implements PriorityFeeStrategy {
 	calculate(samples: SolanaPriorityFeeResponse[]): number {
 		if (samples.length === 0) {

package/src/priorityFee/maxStrategy.ts

@@ -1,5 +1,6 @@
 import { PriorityFeeStrategy } from './types';
 
+/** `PriorityFeeStrategy` that takes the max `prioritizationFee` across all samples. Unlike `MaxOverSlotsStrategy`, does not guard the empty-sample case — calling with an empty array returns `-Infinity`. */
 export class MaxStrategy implements PriorityFeeStrategy {
 	calculate(samples: { slot: number; prioritizationFee: number }[]): number {
 		return Math.max(...samples.map((result) => result.prioritizationFee));