@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/priorityFee/priorityFeeSubscriberMap.ts

@@ -10,7 +10,11 @@ import {
 } from './types';
 
 /**
- * takes advantage of /batchPriorityFees endpoint from Velocity hosted priority fee service
+ * PriorityFeeSubscriberMap — polls the Velocity-hosted `/batchPriorityFees`
+ * endpoint for a fixed set of markets and caches the latest per-market fee
+ * levels, keyed by market type and index. Unlike `PriorityFeeSubscriber`
+ * (single aggregated result across `PriorityFeeMethod.VELOCITY` markets),
+ * this exposes each market's fee levels independently via `getPriorityFees`.
  */
 export class PriorityFeeSubscriberMap {
 	frequencyMs: number;
@@ -20,6 +24,7 @@ export class PriorityFeeSubscriberMap {
 	velocityPriorityFeeEndpoint: string;
 	feesMap: Map<string, Map<number, VelocityPriorityFeeLevels>>; // marketType -> marketIndex -> priority fee
 
+	/** @param config `frequencyMs` defaults to `DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS` (10s); `velocityPriorityFeeEndpoint` is required. */
 	public constructor(config: PriorityFeeSubscriberMapConfig) {
 		this.frequencyMs =
 			config.frequencyMs ?? DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS;
@@ -40,6 +45,7 @@ export class PriorityFeeSubscriberMap {
 		});
 	}
 
+	/** Performs an immediate `load()` and then polls at `frequencyMs`. Idempotent while already subscribed. */
 	public async subscribe(): Promise<void> {
 		if (this.intervalId) {
 			return;
@@ -49,6 +55,7 @@ export class PriorityFeeSubscriberMap {
 		this.intervalId = setInterval(this.load.bind(this), this.frequencyMs);
 	}
 
+	/** Stops polling. */
 	public async unsubscribe(): Promise<void> {
 		if (this.intervalId) {
 			clearInterval(this.intervalId);
@@ -56,9 +63,15 @@ export class PriorityFeeSubscriberMap {
 		}
 	}
 
+	/**
+	 * Fetches one batch of per-market fee levels from
+	 * `/batchPriorityFees` for all `velocityMarkets` and merges the results
+	 * into `feesMap`. No-ops if no markets are configured. Errors are caught
+	 * and logged, not thrown — `feesMap` is left at its previous state.
+	 */
 	public async load(): Promise<void> {
 		try {
-			if (!this.velocityMarkets) {
+			if (!this.velocityMarkets || this.velocityMarkets.length === 0) {
 				return;
 			}
 			const fees = await fetchVelocityPriorityFee(
@@ -72,10 +85,16 @@ export class PriorityFeeSubscriberMap {
 		}
 	}
 
+	/** Replaces the set of markets to fetch fees for; takes effect on the next `load()`. */
 	public updateMarketTypeAndIndex(velocityMarkets: VelocityMarketInfo[]) {
 		this.velocityMarkets = velocityMarkets;
 	}
 
+	/**
+	 * @param marketType `'perp'` or `'spot'`.
+	 * @param marketIndex Market index within that market type.
+	 * @returns The most recently fetched fee-level set for that market, or `undefined` if never fetched (including before the first successful `load()`).
+	 */
 	public getPriorityFees(
 		marketType: string,
 		marketIndex: number

package/src/priorityFee/solanaPriorityFeeMethod.ts

@@ -1,10 +1,22 @@
 import { Connection } from '@solana/web3.js';
 
+/** One sample from Solana's `getRecentPrioritizationFees`. */
 export type SolanaPriorityFeeResponse = {
 	slot: number;
+	/** Priority fee paid, in micro-lamports per compute unit. */
 	prioritizationFee: number;
 };
 
+/**
+ * Fetches recent prioritization fees for `addresses` via the Solana RPC
+ * `getRecentPrioritizationFees` method, then filters to the most recent
+ * `lookbackDistance` slots (relative to the newest returned slot, not the
+ * current chain tip) and sorts descending by slot.
+ * @param connection RPC connection.
+ * @param lookbackDistance Number of slots back from the newest sample to retain.
+ * @param addresses Account keys to scope the fee lookup to (accounts the transaction will write-lock).
+ * @returns Filtered, slot-descending samples; `undefined` if the RPC returned zero results; an empty array if the RPC call itself threw (error is logged, not thrown).
+ */
 export async function fetchSolanaPriorityFee(
 	connection: Connection,
 	lookbackDistance: number,

package/src/priorityFee/types.ts

@@ -6,11 +6,22 @@ import {
 	VelocityPriorityFeeResponse,
 } from './velocityPriorityFeeMethod';
 
+/** Default poll interval (ms) for `PriorityFeeSubscriber`/`PriorityFeeSubscriberMap` when `frequencyMs` is not configured. */
 export const DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS = 10_000;
 
+/**
+ * A pluggable priority-fee aggregation function. `PriorityFeeSubscriber`
+ * calls `calculate` after each poll to derive `getCustomStrategyResult()`.
+ * Built-in implementations: `AverageStrategy`/`AverageOverSlotsStrategy`,
+ * `EwmaStrategy`, `MaxStrategy`/`MaxOverSlotsStrategy`.
+ */
 export interface PriorityFeeStrategy {
 	// calculate the priority fee for a given set of samples.
-	// expect samples to be sorted in descending order (by slot)
+	// when samples is an array (SOLANA), expect it sorted in descending order (by slot)
+	/**
+	 * @param samples Fee samples from whichever `priorityFeeMethod` is active — `SolanaPriorityFeeResponse[]` for SOLANA (expected sorted descending by slot), a single `HeliusPriorityFeeResponse` for HELIUS, or `VelocityPriorityFeeResponse` for VELOCITY.
+	 * @returns A priority fee estimate in micro-lamports per compute unit.
+	 */
 	calculate(
 		samples:
 			| SolanaPriorityFeeResponse[]
@@ -19,46 +30,53 @@ export interface PriorityFeeStrategy {
 	): number;
 }
 
+/** Which upstream API `PriorityFeeSubscriber` queries for priority-fee samples. */
 export enum PriorityFeeMethod {
+	/** Solana RPC `getRecentPrioritizationFees`. Requires `connection`. */
 	SOLANA = 'solana',
+	/** Helius `getPriorityFeeEstimate`. Requires `heliusRpcUrl` or a Helius `connection`. */
 	HELIUS = 'helius',
+	/** Velocity-hosted priority fee cache, scoped by market. Requires `velocityPriorityFeeEndpoint` and `velocityMarkets`. */
 	VELOCITY = 'velocity',
 }
 
+/** Configuration for `PriorityFeeSubscriber`. Which fields are required depends on `priorityFeeMethod` — see `PriorityFeeMethod`. */
 export type PriorityFeeSubscriberConfig = {
-	/// rpc connection, optional if using priorityFeeMethod.HELIUS
+	/** RPC connection used for SOLANA sampling (and as a Helius URL source for HELIUS if `heliusRpcUrl` is omitted); optional only when `priorityFeeMethod` is `HELIUS` or `VELOCITY`. */
 	connection?: Connection;
-	/// frequency to make RPC calls to update priority fee samples, in milliseconds
+	/** Poll interval in milliseconds for `load()`; defaults to `DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS` (10s). */
 	frequencyMs?: number;
-	/// addresses you plan to write lock, used to determine priority fees
+	/** Account keys the transaction will write-lock; scopes SOLANA/HELIUS fee sampling to congestion on these accounts specifically. */
 	addresses?: PublicKey[];
-	/// market type and index, optionally provide at initialization time if using priorityFeeMethod.VELOCITY
+	/** Markets to query when `priorityFeeMethod` is `VELOCITY`; can also be supplied later via `updateMarketTypeAndIndex`. */
 	velocityMarkets?: VelocityMarketInfo[];
-	/// custom strategy to calculate priority fees, defaults to AVERAGE
+	/** `PriorityFeeStrategy` backing `getCustomStrategyResult()`; defaults to `AverageOverSlotsStrategy`. */
 	customStrategy?: PriorityFeeStrategy;
-	/// method for fetching priority fee samples
+	/** Which upstream API to sample from; defaults to `PriorityFeeMethod.SOLANA`. */
 	priorityFeeMethod?: PriorityFeeMethod;
-	/// lookback window to determine priority fees, in slots.
+	/** Number of recent slots to consider when computing fee estimates; defaults to 50. */
 	slotsToCheck?: number;
-	/// url for helius rpc, required if using priorityFeeMethod.HELIUS
+	/** Helius RPC URL; required for `PriorityFeeMethod.HELIUS` unless `connection`'s endpoint already points at Helius. */
 	heliusRpcUrl?: string;
-	/// url for Velocity cached priority fee endpoint, required if using priorityFeeMethod.VELOCITY
+	/** Base URL of the Velocity-hosted priority fee service; required for `PriorityFeeMethod.VELOCITY`. */
 	velocityPriorityFeeEndpoint?: string;
-	/// clamp any returned priority fee value to this value.
+	/** Upper bound (micro-lamports per compute unit) applied to every `get*StrategyResult`/`getHeliusPriorityFeeLevel` return value, after `priorityFeeMultiplier`. Unset (`undefined`) means no clamp. */
 	maxFeeMicroLamports?: number;
-	/// multiplier applied to priority fee before maxFeeMicroLamports, defaults to 1.0
+	/** Multiplier applied to the raw strategy result before `maxFeeMicroLamports` clamping; defaults to `1.0`. */
 	priorityFeeMultiplier?: number;
 };
 
+/** Base config for `PriorityFeeSubscriberMap`, which only supports `PriorityFeeMethod.VELOCITY` (batched per-market fee lookups via `/batchPriorityFees`). */
 type PriorityFeeSubscriberMapConfigBase = {
-	/// frequency to make RPC calls to update priority fee samples, in milliseconds
+	/** Poll interval in milliseconds for `load()`; defaults to `DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS` (10s). */
 	frequencyMs?: number;
-	/// market type and associated market index to query
+	/** Markets to fetch fees for; can also be supplied later via `updateMarketTypeAndIndex`. */
 	velocityMarkets?: VelocityMarketInfo[];
 };
 
-/// url for Velocity cached priority fee endpoint
+/** Configuration for `PriorityFeeSubscriberMap`. */
 export type PriorityFeeSubscriberMapConfig =
 	PriorityFeeSubscriberMapConfigBase & {
+		/** Base URL of the Velocity-hosted priority fee service (queried via `/batchPriorityFees`). */
 		velocityPriorityFeeEndpoint: string;
 	};

package/src/priorityFee/velocityPriorityFeeMethod.ts

@@ -1,11 +1,13 @@
 import fetch from 'node-fetch';
 import { HeliusPriorityLevel } from './heliusPriorityFeeMethod';
 
+/** Identifies a market to fetch/track priority fees for. */
 export type VelocityMarketInfo = {
 	marketType: string;
 	marketIndex: number;
 };
 
+/** Per-percentile priority fee (micro-lamports/CU, same buckets as `HeliusPriorityLevel`) for one market, as returned by the Velocity priority fee endpoint. */
 export type VelocityPriorityFeeLevels = {
 	[key in HeliusPriorityLevel]: number;
 } & {
@@ -13,8 +15,17 @@ export type VelocityPriorityFeeLevels = {
 	marketIndex: number;
 };
 
+/** One `VelocityPriorityFeeLevels` entry per requested market. */
 export type VelocityPriorityFeeResponse = VelocityPriorityFeeLevels[];
 
+/**
+ * Fetches per-market priority fee levels from the Velocity-hosted
+ * `/batchPriorityFees` endpoint.
+ * @param url Base URL of the Velocity priority fee service.
+ * @param marketTypes Market types to query, parallel-indexed to `marketIndexes` (e.g. `['perp', 'perp', 'spot']`).
+ * @param marketIndexes Market indexes to query, parallel-indexed to `marketTypes`.
+ * @returns One `VelocityPriorityFeeLevels` per requested market; an empty array if the request failed (error is logged, not thrown) or returned a non-OK HTTP status.
+ */
 export async function fetchVelocityPriorityFee(
 	url: string,
 	marketTypes: string[],

package/src/slot/SlotSubscriber.ts

@@ -7,10 +7,18 @@ type SlotSubscriberConfig = {
 	resubTimeoutMs?: number;
 }; // for future customization
 
+/** Events emitted on `SlotSubscriber.eventEmitter`. */
 export interface SlotSubscriberEvents {
+	/** Fired whenever a new, strictly-greater slot is observed (including the initial slot fetched by `subscribe()`). */
 	newSlot: (newSlot: number) => void;
 }
 
+/**
+ * SlotSubscriber — tracks the current slot via `connection.onSlotChange`,
+ * with an optional stall-detection resubscribe. Slot updates that are not
+ * strictly greater than the currently tracked slot are ignored (protects
+ * against out-of-order delivery).
+ */
 export class SlotSubscriber {
 	currentSlot = 0;
 	subscriptionId?: number;
@@ -22,6 +30,10 @@ export class SlotSubscriber {
 	isUnsubscribing = false;
 	receivingData = false;
 
+	/**
+	 * @param connection RPC connection to subscribe on.
+	 * @param config.resubTimeoutMs If set to a positive value, resubscribe when no slot update arrives for this many ms; `0` (or unset) disables the resubscribe watchdog. Positive values below 1000ms log a warning (too aggressive) but are still honored.
+	 */
 	public constructor(
 		private connection: Connection,
 		config?: SlotSubscriberConfig
@@ -35,6 +47,7 @@ export class SlotSubscriber {
 		}
 	}
 
+	/** Fetches the current slot once via RPC, then subscribes to `onSlotChange` for live updates. Idempotent while already subscribed. */
 	public async subscribe(): Promise<void> {
 		if (this.subscriptionId != null) {
 			return;
@@ -85,10 +98,15 @@ export class SlotSubscriber {
 		}, this.resubTimeoutMs);
 	}
 
+	/** @returns The most recently observed slot, or `0` if `subscribe()` hasn't completed yet. */
 	public getSlot(): number {
 		return this.currentSlot;
 	}
 
+	/**
+	 * Removes the `onSlotChange` listener and cancels the resub timeout.
+	 * @param onResub Internal flag used when unsubscribing as part of an automatic resubscribe cycle; when `false` (a caller-initiated unsubscribe), also permanently disables future auto-resubscribe by clearing `resubTimeoutMs`.
+	 */
 	public async unsubscribe(onResub = false): Promise<void> {
 		if (!onResub) {
 			this.resubTimeoutMs = undefined;

package/src/slot/SlothashSubscriber.ts

@@ -12,11 +12,19 @@ type SlothashSubscriberConfig = {
 	commitment?: Commitment;
 }; // for future customization
 
+/** A slot and its corresponding blockhash, decoded from the `SysvarS1otHashes111111111111111111111111111` account. */
 export type Slothash = {
 	slot: number;
+	/** Base58-encoded blockhash for that slot. */
 	hash: string;
 };
 
+/**
+ * SlothashSubscriber — tracks the most recent entry of the `SlotHashes`
+ * sysvar via `connection.onAccountChange`, with an optional stall-detection
+ * resubscribe. Updates whose slot is not strictly greater than the currently
+ * tracked one are ignored.
+ */
 export class SlothashSubscriber {
 	private _currentSlothash?: Slothash;
 	private get currentSlothash(): Slothash {
@@ -36,6 +44,11 @@ export class SlothashSubscriber {
 	isUnsubscribing = false;
 	receivingData = false;
 
+	/**
+	 * @param connection RPC connection to subscribe on.
+	 * @param config.commitment Commitment for both the initial fetch and the account-change subscription; defaults to `'processed'`.
+	 * @param config.resubTimeoutMs If set to a positive value, resubscribe when no update arrives for this many ms; `0` (or unset) disables the resubscribe watchdog. Positive values below 1000ms log a warning but are still honored.
+	 */
 	public constructor(
 		private connection: Connection,
 		config?: SlothashSubscriberConfig
@@ -49,6 +62,11 @@ export class SlothashSubscriber {
 		}
 	}
 
+	/**
+	 * Fetches the `SlotHashes` sysvar once via RPC, then subscribes to
+	 * `onAccountChange` for live updates. Idempotent while already subscribed.
+	 * @throws If the sysvar account can't be fetched on the initial load.
+	 */
 	public async subscribe(): Promise<void> {
 		if (this.subscriptionId != null) {
 			return;
@@ -105,10 +123,18 @@ export class SlothashSubscriber {
 		}, this.resubTimeoutMs);
 	}
 
+	/**
+	 * @returns The most recently observed `Slothash`.
+	 * @throws If called before `subscribe()` has completed its initial fetch.
+	 */
 	public getSlothash(): Slothash {
 		return this.currentSlothash;
 	}
 
+	/**
+	 * Removes the `onAccountChange` listener and cancels the resub timeout.
+	 * @param onResub Internal flag used when unsubscribing as part of an automatic resubscribe cycle; when `false`, also permanently disables future auto-resubscribe by clearing `resubTimeoutMs`.
+	 */
 	public async unsubscribe(onResub = false): Promise<void> {
 		if (!onResub) {
 			this.resubTimeoutMs = undefined;
@@ -118,7 +144,7 @@ export class SlothashSubscriber {
 		this.timeoutId = undefined;
 
 		if (this.subscriptionId != null) {
-			await this.connection.removeSlotChangeListener(this.subscriptionId);
+			await this.connection.removeAccountChangeListener(this.subscriptionId);
 			this.subscriptionId = undefined;
 			this.isUnsubscribing = false;
 		} else {