@velocity-exchange/sdk 0.3.0 → 0.4.0

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

@@ -29,6 +29,15 @@ import { ZERO } from '../constants/numericConstants';
  */
 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 }>();
@@ -45,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) {
@@ -95,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;
@@ -160,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',
@@ -260,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()) {
@@ -282,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(
@@ -302,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));
@@ -315,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));

package/src/priorityFee/priorityFeeSubscriber.ts

@@ -18,6 +18,17 @@ import {
 	VelocityMarketInfo,
 } from './velocityPriorityFeeMethod';
 
+/**
+ * PriorityFeeSubscriber — polls one of three sources (Solana RPC, Helius, or
+ * the Velocity-hosted priority fee cache — see `PriorityFeeMethod`) on an
+ * interval and exposes several aggregations over the resulting samples: a
+ * simple average, a max, and a caller-supplied `customStrategy`. All
+ * `get*StrategyResult` accessors return `0` until the first successful poll,
+ * and are clamped to `maxFeeMicroLamports` (if set) after applying
+ * `priorityFeeMultiplier`. All returned fee values are in micro-lamports per
+ * compute unit, the unit Solana's `ComputeBudgetProgram.setComputeUnitPrice`
+ * expects.
+ */
 export class PriorityFeeSubscriber {
 	connection?: Connection;
 	frequencyMs: number;
@@ -43,6 +54,10 @@ export class PriorityFeeSubscriber {
 	lastMaxStrategyResult = 0;
 	lastSlotSeen = 0;
 
+	/**
+	 * @param config See `PriorityFeeSubscriberConfig`. Required fields depend on `priorityFeeMethod` (default `SOLANA`): SOLANA needs `connection`; HELIUS needs `heliusRpcUrl` or a Helius `connection`; VELOCITY needs `velocityPriorityFeeEndpoint`.
+	 * @throws If `priorityFeeMethod` is `HELIUS` without a resolvable Helius RPC URL, or `SOLANA` without a `connection`.
+	 */
 	public constructor(config: PriorityFeeSubscriberConfig) {
 		this.connection = config.connection;
 		this.frequencyMs =
@@ -93,6 +108,7 @@ export class PriorityFeeSubscriber {
 		this.priorityFeeMultiplier = config.priorityFeeMultiplier ?? 1.0;
 	}
 
+	/** Starts polling at `frequencyMs` and performs one immediate `load()`. Idempotent while already subscribed. */
 	public async subscribe(): Promise<void> {
 		if (this.intervalId) {
 			return;
@@ -193,26 +209,36 @@ export class PriorityFeeSubscriber {
 		}
 	}
 
+	/** @returns The current clamp on returned fee values (micro-lamports/CU), or `undefined` if unclamped. */
 	public getMaxPriorityFee(): number | undefined {
 		return this.maxFeeMicroLamports;
 	}
 
+	/** Updates the clamp applied to all `get*StrategyResult`/`getHeliusPriorityFeeLevel` results. Pass `undefined` to remove the clamp. */
 	public updateMaxPriorityFee(newMaxFee: number | undefined) {
 		this.maxFeeMicroLamports = newMaxFee;
 	}
 
+	/** @returns The multiplier applied to strategy results before clamping; defaults to `1.0`. */
 	public getPriorityFeeMultiplier(): number {
 		return this.priorityFeeMultiplier ?? 1.0;
 	}
 
+	/** Updates the multiplier applied to `getCustomStrategyResult`/`getAvgStrategyResult`/`getMaxStrategyResult` before clamping. */
 	public updatePriorityFeeMultiplier(newPriorityFeeMultiplier: number) {
 		this.priorityFeeMultiplier = newPriorityFeeMultiplier;
 	}
 
+	/** Swaps the `PriorityFeeStrategy` used to compute `getCustomStrategyResult`; takes effect on the next `load()`. */
 	public updateCustomStrategy(newStrategy: PriorityFeeStrategy) {
 		this.customStrategy = newStrategy;
 	}
 
+	/**
+	 * Only meaningful with `priorityFeeMethod: HELIUS`.
+	 * @param level Helius percentile level to read; defaults to `MEDIUM`.
+	 * @returns That level's fee (micro-lamports/CU) from the most recent Helius sample, clamped to `maxFeeMicroLamports` if set, or `0` if no sample has been loaded yet.
+	 */
 	public getHeliusPriorityFeeLevel(
 		level: HeliusPriorityLevel = HeliusPriorityLevel.MEDIUM
 	): number {
@@ -225,6 +251,7 @@ export class PriorityFeeSubscriber {
 		return this.lastHeliusSample[level];
 	}
 
+	/** @returns The configured `customStrategy`'s result from the most recent poll (micro-lamports/CU), scaled by `priorityFeeMultiplier` and clamped to `maxFeeMicroLamports` if set. `0` before the first successful `load()`. */
 	public getCustomStrategyResult(): number {
 		const result =
 			this.lastCustomStrategyResult * this.getPriorityFeeMultiplier();
@@ -234,6 +261,7 @@ export class PriorityFeeSubscriber {
 		return result;
 	}
 
+	/** @returns The average-over-samples fee from the most recent poll (micro-lamports/CU) — for HELIUS this is the MEDIUM level, for VELOCITY the max MEDIUM level across configured markets — scaled by `priorityFeeMultiplier` and clamped to `maxFeeMicroLamports` if set. `0` before the first successful `load()`. */
 	public getAvgStrategyResult(): number {
 		const result = this.lastAvgStrategyResult * this.getPriorityFeeMultiplier();
 		if (this.maxFeeMicroLamports !== undefined) {
@@ -242,6 +270,7 @@ export class PriorityFeeSubscriber {
 		return result;
 	}
 
+	/** @returns The max-over-samples fee from the most recent poll (micro-lamports/CU) — for HELIUS this is the UNSAFE_MAX level, for VELOCITY the max UNSAFE_MAX level across configured markets — scaled by `priorityFeeMultiplier` and clamped to `maxFeeMicroLamports` if set. `0` before the first successful `load()`. */
 	public getMaxStrategyResult(): number {
 		const result = this.lastMaxStrategyResult * this.getPriorityFeeMultiplier();
 		if (this.maxFeeMicroLamports !== undefined) {
@@ -250,6 +279,13 @@ export class PriorityFeeSubscriber {
 		return result;
 	}
 
+	/**
+	 * Fetches one round of samples from the configured `priorityFeeMethod`
+	 * and recomputes `latestPriorityFee`/`lastAvgStrategyResult`/
+	 * `lastMaxStrategyResult`/`lastCustomStrategyResult`. Errors are caught
+	 * and logged, not thrown, so a transient failure just leaves the previous
+	 * values in place until the next poll.
+	 */
 	public async load(): Promise<void> {
 		try {
 			if (this.priorityFeeMethod === PriorityFeeMethod.SOLANA) {
@@ -272,6 +308,7 @@ export class PriorityFeeSubscriber {
 		}
 	}
 
+	/** Stops polling. */
 	public async unsubscribe(): Promise<void> {
 		if (this.intervalId) {
 			clearInterval(this.intervalId);
@@ -279,10 +316,12 @@ export class PriorityFeeSubscriber {
 		}
 	}
 
+	/** Replaces the set of write-locked addresses used for SOLANA/HELIUS fee sampling; takes effect on the next `load()`. */
 	public updateAddresses(addresses: PublicKey[]) {
 		this.addresses = addresses.map((k) => k.toBase58());
 	}
 
+	/** Replaces the set of markets queried when `priorityFeeMethod` is VELOCITY; takes effect on the next `load()`. */
 	public updateMarketTypeAndIndex(velocityMarkets: VelocityMarketInfo[]) {
 		this.velocityMarkets = velocityMarkets;
 	}