@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/priorityFee/priorityFeeSubscriber.js

@@ -7,7 +7,22 @@ const maxOverSlotsStrategy_1 = require("./maxOverSlotsStrategy");
 const solanaPriorityFeeMethod_1 = require("./solanaPriorityFeeMethod");
 const heliusPriorityFeeMethod_1 = require("./heliusPriorityFeeMethod");
 const velocityPriorityFeeMethod_1 = require("./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.
+ */
 class PriorityFeeSubscriber {
+    /**
+     * @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`.
+     */
     constructor(config) {
         var _a, _b, _c, _d, _e;
         this.averageStrategy = new averageOverSlotsStrategy_1.AverageOverSlotsStrategy();
@@ -60,6 +75,7 @@ class PriorityFeeSubscriber {
         this.maxFeeMicroLamports = config.maxFeeMicroLamports;
         this.priorityFeeMultiplier = (_e = config.priorityFeeMultiplier) !== null && _e !== void 0 ? _e : 1.0;
     }
+    /** Starts polling at `frequencyMs` and performs one immediate `load()`. Idempotent while already subscribed. */
     async subscribe() {
         if (this.intervalId) {
             return;
@@ -130,22 +146,32 @@ class PriorityFeeSubscriber {
             }
         }
     }
+    /** @returns The current clamp on returned fee values (micro-lamports/CU), or `undefined` if unclamped. */
     getMaxPriorityFee() {
         return this.maxFeeMicroLamports;
     }
+    /** Updates the clamp applied to all `get*StrategyResult`/`getHeliusPriorityFeeLevel` results. Pass `undefined` to remove the clamp. */
     updateMaxPriorityFee(newMaxFee) {
         this.maxFeeMicroLamports = newMaxFee;
     }
+    /** @returns The multiplier applied to strategy results before clamping; defaults to `1.0`. */
     getPriorityFeeMultiplier() {
         var _a;
         return (_a = this.priorityFeeMultiplier) !== null && _a !== void 0 ? _a : 1.0;
     }
+    /** Updates the multiplier applied to `getCustomStrategyResult`/`getAvgStrategyResult`/`getMaxStrategyResult` before clamping. */
     updatePriorityFeeMultiplier(newPriorityFeeMultiplier) {
         this.priorityFeeMultiplier = newPriorityFeeMultiplier;
     }
+    /** Swaps the `PriorityFeeStrategy` used to compute `getCustomStrategyResult`; takes effect on the next `load()`. */
     updateCustomStrategy(newStrategy) {
         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.
+     */
     getHeliusPriorityFeeLevel(level = heliusPriorityFeeMethod_1.HeliusPriorityLevel.MEDIUM) {
         if (this.lastHeliusSample === undefined) {
             return 0;
@@ -155,6 +181,7 @@ 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()`. */
     getCustomStrategyResult() {
         const result = this.lastCustomStrategyResult * this.getPriorityFeeMultiplier();
         if (this.maxFeeMicroLamports !== undefined) {
@@ -162,6 +189,7 @@ 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()`. */
     getAvgStrategyResult() {
         const result = this.lastAvgStrategyResult * this.getPriorityFeeMultiplier();
         if (this.maxFeeMicroLamports !== undefined) {
@@ -169,6 +197,7 @@ 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()`. */
     getMaxStrategyResult() {
         const result = this.lastMaxStrategyResult * this.getPriorityFeeMultiplier();
         if (this.maxFeeMicroLamports !== undefined) {
@@ -176,6 +205,13 @@ 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.
+     */
     async load() {
         try {
             if (this.priorityFeeMethod === types_1.PriorityFeeMethod.SOLANA) {
@@ -197,15 +233,18 @@ class PriorityFeeSubscriber {
             return;
         }
     }
+    /** Stops polling. */
     async unsubscribe() {
         if (this.intervalId) {
             clearInterval(this.intervalId);
             this.intervalId = undefined;
         }
     }
+    /** Replaces the set of write-locked addresses used for SOLANA/HELIUS fee sampling; takes effect on the next `load()`. */
     updateAddresses(addresses) {
         this.addresses = addresses.map((k) => k.toBase58());
     }
+    /** Replaces the set of markets queried when `priorityFeeMethod` is VELOCITY; takes effect on the next `load()`. */
     updateMarketTypeAndIndex(velocityMarkets) {
         this.velocityMarkets = velocityMarkets;
     }

package/lib/browser/priorityFee/priorityFeeSubscriberMap.d.ts

@@ -1,7 +1,11 @@
 import { VelocityMarketInfo, VelocityPriorityFeeLevels } from './velocityPriorityFeeMethod';
 import { PriorityFeeSubscriberMapConfig } 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 declare class PriorityFeeSubscriberMap {
     frequencyMs: number;
@@ -9,12 +13,27 @@ export declare class PriorityFeeSubscriberMap {
     velocityMarkets?: VelocityMarketInfo[];
     velocityPriorityFeeEndpoint: string;
     feesMap: Map<string, Map<number, VelocityPriorityFeeLevels>>;
+    /** @param config `frequencyMs` defaults to `DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS` (10s); `velocityPriorityFeeEndpoint` is required. */
     constructor(config: PriorityFeeSubscriberMapConfig);
     private updateFeesMap;
+    /** Performs an immediate `load()` and then polls at `frequencyMs`. Idempotent while already subscribed. */
     subscribe(): Promise<void>;
+    /** Stops polling. */
     unsubscribe(): Promise<void>;
+    /**
+     * 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.
+     */
     load(): Promise<void>;
+    /** Replaces the set of markets to fetch fees for; takes effect on the next `load()`. */
     updateMarketTypeAndIndex(velocityMarkets: VelocityMarketInfo[]): void;
+    /**
+     * @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()`).
+     */
     getPriorityFees(marketType: string, marketIndex: number): VelocityPriorityFeeLevels | undefined;
 }
 /** Example usage:

package/lib/browser/priorityFee/priorityFeeSubscriberMap.js

@@ -4,9 +4,14 @@ exports.PriorityFeeSubscriberMap = void 0;
 const velocityPriorityFeeMethod_1 = require("./velocityPriorityFeeMethod");
 const types_1 = require("./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`.
  */
 class PriorityFeeSubscriberMap {
+    /** @param config `frequencyMs` defaults to `DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS` (10s); `velocityPriorityFeeEndpoint` is required. */
     constructor(config) {
         var _a, _b;
         this.frequencyMs =
@@ -23,6 +28,7 @@ class PriorityFeeSubscriberMap {
             this.feesMap.get(fee.marketType).set(fee.marketIndex, fee);
         });
     }
+    /** Performs an immediate `load()` and then polls at `frequencyMs`. Idempotent while already subscribed. */
     async subscribe() {
         if (this.intervalId) {
             return;
@@ -30,15 +36,22 @@ class PriorityFeeSubscriberMap {
         await this.load();
         this.intervalId = setInterval(this.load.bind(this), this.frequencyMs);
     }
+    /** Stops polling. */
     async unsubscribe() {
         if (this.intervalId) {
             clearInterval(this.intervalId);
             this.intervalId = undefined;
         }
     }
+    /**
+     * 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.
+     */
     async load() {
         try {
-            if (!this.velocityMarkets) {
+            if (!this.velocityMarkets || this.velocityMarkets.length === 0) {
                 return;
             }
             const fees = await (0, velocityPriorityFeeMethod_1.fetchVelocityPriorityFee)(this.velocityPriorityFeeEndpoint, this.velocityMarkets.map((m) => m.marketType), this.velocityMarkets.map((m) => m.marketIndex));
@@ -48,9 +61,15 @@ class PriorityFeeSubscriberMap {
             console.error('Error fetching priority fees', e);
         }
     }
+    /** Replaces the set of markets to fetch fees for; takes effect on the next `load()`. */
     updateMarketTypeAndIndex(velocityMarkets) {
         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()`).
+     */
     getPriorityFees(marketType, marketIndex) {
         var _a;
         return (_a = this.feesMap.get(marketType)) === null || _a === void 0 ? void 0 : _a.get(marketIndex);

package/lib/browser/priorityFee/solanaPriorityFeeMethod.d.ts

@@ -1,6 +1,18 @@
 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 declare function fetchSolanaPriorityFee(connection: Connection, lookbackDistance: number, addresses: string[]): Promise<SolanaPriorityFeeResponse[] | undefined>;

package/lib/browser/priorityFee/solanaPriorityFeeMethod.js

@@ -1,6 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchSolanaPriorityFee = void 0;
+/**
+ * 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).
+ */
 async function fetchSolanaPriorityFee(connection, lookbackDistance, addresses) {
     try {
         // @ts-ignore

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

@@ -2,33 +2,65 @@ import { Connection, PublicKey } from '@solana/web3.js';
 import { SolanaPriorityFeeResponse } from './solanaPriorityFeeMethod';
 import { HeliusPriorityFeeResponse } from './heliusPriorityFeeMethod';
 import { VelocityMarketInfo, VelocityPriorityFeeResponse } from './velocityPriorityFeeMethod';
+/** Default poll interval (ms) for `PriorityFeeSubscriber`/`PriorityFeeSubscriberMap` when `frequencyMs` is not configured. */
 export declare const DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS = 10000;
+/**
+ * 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 {
+    /**
+     * @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[] | HeliusPriorityFeeResponse | VelocityPriorityFeeResponse): number;
 }
+/** Which upstream API `PriorityFeeSubscriber` queries for priority-fee samples. */
 export declare 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 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;
+    /** Poll interval in milliseconds for `load()`; defaults to `DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS` (10s). */
     frequencyMs?: number;
+    /** Account keys the transaction will write-lock; scopes SOLANA/HELIUS fee sampling to congestion on these accounts specifically. */
     addresses?: PublicKey[];
+    /** Markets to query when `priorityFeeMethod` is `VELOCITY`; can also be supplied later via `updateMarketTypeAndIndex`. */
     velocityMarkets?: VelocityMarketInfo[];
+    /** `PriorityFeeStrategy` backing `getCustomStrategyResult()`; defaults to `AverageOverSlotsStrategy`. */
     customStrategy?: PriorityFeeStrategy;
+    /** Which upstream API to sample from; defaults to `PriorityFeeMethod.SOLANA`. */
     priorityFeeMethod?: PriorityFeeMethod;
+    /** Number of recent slots to consider when computing fee estimates; defaults to 50. */
     slotsToCheck?: number;
+    /** Helius RPC URL; required for `PriorityFeeMethod.HELIUS` unless `connection`'s endpoint already points at Helius. */
     heliusRpcUrl?: string;
+    /** Base URL of the Velocity-hosted priority fee service; required for `PriorityFeeMethod.VELOCITY`. */
     velocityPriorityFeeEndpoint?: string;
+    /** 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 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 = {
+    /** Poll interval in milliseconds for `load()`; defaults to `DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS` (10s). */
     frequencyMs?: number;
+    /** Markets to fetch fees for; can also be supplied later via `updateMarketTypeAndIndex`. */
     velocityMarkets?: VelocityMarketInfo[];
 };
+/** Configuration for `PriorityFeeSubscriberMap`. */
 export type PriorityFeeSubscriberMapConfig = PriorityFeeSubscriberMapConfigBase & {
+    /** Base URL of the Velocity-hosted priority fee service (queried via `/batchPriorityFees`). */
     velocityPriorityFeeEndpoint: string;
 };
 export {};

package/lib/browser/priorityFee/types.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PriorityFeeMethod = exports.DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS = void 0;
+/** Default poll interval (ms) for `PriorityFeeSubscriber`/`PriorityFeeSubscriberMap` when `frequencyMs` is not configured. */
 exports.DEFAULT_PRIORITY_FEE_MAP_FREQUENCY_MS = 10000;
+/** Which upstream API `PriorityFeeSubscriber` queries for priority-fee samples. */
 var PriorityFeeMethod;
 (function (PriorityFeeMethod) {
+    /** Solana RPC `getRecentPrioritizationFees`. Requires `connection`. */
     PriorityFeeMethod["SOLANA"] = "solana";
+    /** Helius `getPriorityFeeEstimate`. Requires `heliusRpcUrl` or a Helius `connection`. */
     PriorityFeeMethod["HELIUS"] = "helius";
+    /** Velocity-hosted priority fee cache, scoped by market. Requires `velocityPriorityFeeEndpoint` and `velocityMarkets`. */
     PriorityFeeMethod["VELOCITY"] = "velocity";
 })(PriorityFeeMethod || (exports.PriorityFeeMethod = PriorityFeeMethod = {}));

package/lib/browser/priorityFee/velocityPriorityFeeMethod.d.ts

@@ -1,13 +1,24 @@
 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;
 } & {
     marketType: 'perp' | 'spot';
     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 declare function fetchVelocityPriorityFee(url: string, marketTypes: string[], marketIndexes: number[]): Promise<VelocityPriorityFeeResponse>;

package/lib/browser/priorityFee/velocityPriorityFeeMethod.js

@@ -5,6 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchVelocityPriorityFee = void 0;
 const node_fetch_1 = __importDefault(require("node-fetch"));
+/**
+ * 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.
+ */
 async function fetchVelocityPriorityFee(url, marketTypes, marketIndexes) {
     try {
         const response = await (0, node_fetch_1.default)(`${url}/batchPriorityFees?marketType=${marketTypes.join(',')}&marketIndex=${marketIndexes.join(',')}`);

package/lib/browser/slot/SlotSubscriber.d.ts

@@ -5,9 +5,17 @@ import StrictEventEmitter from 'strict-event-emitter-types/types/src';
 type SlotSubscriberConfig = {
     resubTimeoutMs?: number;
 };
+/** 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 declare class SlotSubscriber {
     private connection;
     currentSlot: number;
@@ -17,11 +25,21 @@ export declare class SlotSubscriber {
     resubTimeoutMs?: number;
     isUnsubscribing: boolean;
     receivingData: boolean;
+    /**
+     * @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.
+     */
     constructor(connection: Connection, config?: SlotSubscriberConfig);
+    /** Fetches the current slot once via RPC, then subscribes to `onSlotChange` for live updates. Idempotent while already subscribed. */
     subscribe(): Promise<void>;
     private updateCurrentSlot;
     private setTimeout;
+    /** @returns The most recently observed slot, or `0` if `subscribe()` hasn't completed yet. */
     getSlot(): number;
+    /**
+     * 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`.
+     */
     unsubscribe(onResub?: boolean): Promise<void>;
 }
 export {};

package/lib/browser/slot/SlotSubscriber.js

@@ -2,7 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SlotSubscriber = void 0;
 const events_1 = require("events");
+/**
+ * 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).
+ */
 class SlotSubscriber {
+    /**
+     * @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.
+     */
     constructor(connection, config) {
         this.connection = connection;
         this.currentSlot = 0;
@@ -14,6 +24,7 @@ class SlotSubscriber {
             console.log('resubTimeoutMs should be at least 1000ms to avoid spamming resub');
         }
     }
+    /** Fetches the current slot once via RPC, then subscribes to `onSlotChange` for live updates. Idempotent while already subscribed. */
     async subscribe() {
         if (this.subscriptionId != null) {
             return;
@@ -54,9 +65,14 @@ class SlotSubscriber {
             }
         }, this.resubTimeoutMs);
     }
+    /** @returns The most recently observed slot, or `0` if `subscribe()` hasn't completed yet. */
     getSlot() {
         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`.
+     */
     async unsubscribe(onResub = false) {
         if (!onResub) {
             this.resubTimeoutMs = undefined;

package/lib/browser/slot/SlothashSubscriber.d.ts

@@ -3,10 +3,18 @@ type SlothashSubscriberConfig = {
     resubTimeoutMs?: number;
     commitment?: Commitment;
 };
+/** 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 declare class SlothashSubscriber {
     private connection;
     private _currentSlothash?;
@@ -17,10 +25,28 @@ export declare class SlothashSubscriber {
     resubTimeoutMs?: number;
     isUnsubscribing: boolean;
     receivingData: boolean;
+    /**
+     * @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.
+     */
     constructor(connection: Connection, config?: SlothashSubscriberConfig);
+    /**
+     * 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.
+     */
     subscribe(): Promise<void>;
     private setTimeout;
+    /**
+     * @returns The most recently observed `Slothash`.
+     * @throws If called before `subscribe()` has completed its initial fetch.
+     */
     getSlothash(): Slothash;
+    /**
+     * 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`.
+     */
     unsubscribe(onResub?: boolean): Promise<void>;
 }
 export {};

package/lib/browser/slot/SlothashSubscriber.js

@@ -7,6 +7,12 @@ exports.SlothashSubscriber = void 0;
 const web3_js_1 = require("@solana/web3.js");
 const bs58_1 = __importDefault(require("bs58"));
 const anchor_1 = require("../isomorphic/anchor");
+/**
+ * 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.
+ */
 class SlothashSubscriber {
     get currentSlothash() {
         if (!this._currentSlothash) {
@@ -14,6 +20,11 @@ class SlothashSubscriber {
         }
         return this._currentSlothash;
     }
+    /**
+     * @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.
+     */
     constructor(connection, config) {
         var _a;
         this.connection = connection;
@@ -25,6 +36,11 @@ class SlothashSubscriber {
             console.log('resubTimeoutMs should be at least 1000ms to avoid spamming resub');
         }
     }
+    /**
+     * 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.
+     */
     async subscribe() {
         if (this.subscriptionId != null) {
             return;
@@ -64,9 +80,17 @@ class SlothashSubscriber {
             }
         }, this.resubTimeoutMs);
     }
+    /**
+     * @returns The most recently observed `Slothash`.
+     * @throws If called before `subscribe()` has completed its initial fetch.
+     */
     getSlothash() {
         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`.
+     */
     async unsubscribe(onResub = false) {
         if (!onResub) {
             this.resubTimeoutMs = undefined;
@@ -75,7 +99,7 @@ class SlothashSubscriber {
         clearTimeout(this.timeoutId);
         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;
         }