@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/browser/orderSubscriber/OrderSubscriber.js

@@ -13,7 +13,29 @@ const user_1 = require("../decode/user");
 const grpcSubscription_1 = require("./grpcSubscription");
 const orders_1 = require("../math/orders");
 const numericConstants_1 = require("../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`.
+ */
 class OrderSubscriber {
+    /**
+     * @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) {
         var _a, _b, _c, _d, _e;
         this.usersAccounts = new Map();
@@ -66,9 +88,17 @@ class OrderSubscriber {
         this.eventEmitter = new events_1.EventEmitter();
         this.fetchAllNonIdleUsers = config.fetchAllNonIdleUsers;
     }
+    /** Starts the underlying transport (polling interval, websocket program-account subscription, or gRPC stream) chosen at construction time. */
     async subscribe() {
         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() {
         if (this.fetchPromise) {
             return this.fetchPromise;
@@ -109,6 +139,23 @@ class OrderSubscriber {
             this.fetchPromise = undefined;
         }
     }
+    /**
+     * 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, dataType, data, slot) {
         if (!this.mostRecentSlot || slot > this.mostRecentSlot) {
             this.mostRecentSlot = slot;
@@ -121,7 +168,7 @@ class OrderSubscriber {
             if (dataType === 'raw') {
                 // @ts-ignore
                 const buffer = buffer_1.Buffer.from(data[0], data[1]);
-                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(4328, 4328 + 8), undefined, 'le');
+                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(USER_LAST_ACTIVE_SLOT_OFFSET, USER_LAST_ACTIVE_SLOT_OFFSET + 8), undefined, 'le');
                 if (slotAndUserAccount &&
                     slotAndUserAccount.userAccount.lastActiveSlot.gt(newLastActiveSlot)) {
                     return;
@@ -130,7 +177,7 @@ class OrderSubscriber {
             }
             else if (dataType === 'buffer') {
                 const buffer = data;
-                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(4328, 4328 + 8), undefined, 'le');
+                const newLastActiveSlot = new anchor_1.BN(buffer.subarray(USER_LAST_ACTIVE_SLOT_OFFSET, USER_LAST_ACTIVE_SLOT_OFFSET + 8), undefined, 'le');
                 if (slotAndUserAccount &&
                     slotAndUserAccount.userAccount.lastActiveSlot.gt(newLastActiveSlot)) {
                     return;
@@ -160,6 +207,15 @@ class OrderSubscriber {
     createDLOB() {
         return new DLOB_1.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.
+     */
     async getDLOB(slot) {
         var _a;
         const dlob = this.createDLOB();
@@ -175,16 +231,24 @@ class OrderSubscriber {
         }
         return dlob;
     }
+    /** @returns The highest slot observed across all account updates so far, or 0 if none have arrived yet. */
     getSlot() {
         var _a;
         return (_a = this.mostRecentSlot) !== null && _a !== void 0 ? _a : 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. */
     async addPubkey(userAccountPublicKey) {
         const accountInfo = await this.velocityClient.connection.getAccountInfoAndContext(userAccountPublicKey, this.commitment);
         if (accountInfo.value) {
             this.tryUpdateUserAccount(userAccountPublicKey.toString(), 'buffer', accountInfo.value.data, accountInfo.context.slot);
         }
     }
+    /**
+     * 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).
+     */
     async mustGetUserAccount(key) {
         if (!this.usersAccounts.has(key)) {
             await this.addPubkey(new web3_js_1.PublicKey(key));
@@ -195,6 +259,7 @@ class OrderSubscriber {
         }
         return slotAndUserAccount.userAccount;
     }
+    /** Stops the underlying transport and clears the entire cached `User` account map. */
     async unsubscribe() {
         this.usersAccounts.clear();
         await this.subscription.unsubscribe();

package/lib/browser/orderSubscriber/PollingSubscription.d.ts

@@ -1,12 +1,23 @@
 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 declare class PollingSubscription {
     private orderSubscriber;
     private frequency;
     intervalId?: ReturnType<typeof setTimeout>;
+    /**
+     * @param orderSubscriber The `OrderSubscriber` to feed with each poll.
+     * @param frequency Poll interval in milliseconds.
+     */
     constructor({ orderSubscriber, frequency, }: {
         orderSubscriber: OrderSubscriber;
         frequency: number;
     });
+    /** Starts the polling interval and performs one immediate `fetch()` before returning. Idempotent while already subscribed. */
     subscribe(): Promise<void>;
+    /** Stops the polling interval. */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/orderSubscriber/PollingSubscription.js

@@ -1,11 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PollingSubscription = void 0;
+/**
+ * `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.
+ */
 class PollingSubscription {
+    /**
+     * @param orderSubscriber The `OrderSubscriber` to feed with each poll.
+     * @param frequency Poll interval in milliseconds.
+     */
     constructor({ orderSubscriber, frequency, }) {
         this.orderSubscriber = orderSubscriber;
         this.frequency = frequency;
     }
+    /** Starts the polling interval and performs one immediate `fetch()` before returning. Idempotent while already subscribed. */
     async subscribe() {
         if (this.intervalId) {
             return;
@@ -13,6 +23,7 @@ class PollingSubscription {
         this.intervalId = setInterval(this.orderSubscriber.fetch.bind(this.orderSubscriber), this.frequency);
         await this.orderSubscriber.fetch();
     }
+    /** Stops the polling interval. */
     async unsubscribe() {
         if (this.intervalId) {
             clearInterval(this.intervalId);

package/lib/browser/orderSubscriber/WebsocketSubscription.d.ts

@@ -1,6 +1,14 @@
 import { OrderSubscriber } from './OrderSubscriber';
 import { Commitment } from '@solana/web3.js';
 import { ResubOpts } from '../accounts/types';
+/**
+ * `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 declare class WebsocketSubscription {
     private orderSubscriber;
     private commitment;
@@ -10,6 +18,14 @@ export declare class WebsocketSubscription {
     private subscriber?;
     private resyncTimeoutId?;
     private decoded?;
+    /**
+     * @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, skipInitialLoad, resubOpts, resyncIntervalMs, decoded, }: {
         orderSubscriber: OrderSubscriber;
         commitment: Commitment;
@@ -18,6 +34,8 @@ export declare class WebsocketSubscription {
         resyncIntervalMs?: number;
         decoded?: boolean;
     });
+    /** Establishes the websocket program-account subscription (idempotent — no-op if already subscribed), optionally backfills with `fetch()`, and starts the resync timer if configured. */
     subscribe(): Promise<void>;
+    /** Tears down the program-account subscription and cancels the resync timer, if any. No-op if not subscribed. */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/orderSubscriber/WebsocketSubscription.js

@@ -3,7 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebsocketSubscription = void 0;
 const memcmp_1 = require("../memcmp");
 const webSocketProgramAccountSubscriber_1 = require("../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.
+ */
 class WebsocketSubscription {
+    /**
+     * @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, skipInitialLoad = false, resubOpts, resyncIntervalMs, decoded = true, }) {
         this.orderSubscriber = orderSubscriber;
         this.commitment = commitment;
@@ -12,6 +28,7 @@ class WebsocketSubscription {
         this.resyncIntervalMs = resyncIntervalMs;
         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. */
     async subscribe() {
         if (this.subscriber) {
             return;
@@ -53,6 +70,7 @@ class WebsocketSubscription {
             recursiveResync();
         }
     }
+    /** Tears down the program-account subscription and cancels the resync timer, if any. No-op if not subscribed. */
     async unsubscribe() {
         if (!this.subscriber)
             return;

package/lib/browser/orderSubscriber/grpcSubscription.d.ts

@@ -1,5 +1,11 @@
 import { OrderSubscriber } from './OrderSubscriber';
 import { GrpcConfigs, ResubOpts } from '../accounts/types';
+/**
+ * `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 declare class grpcSubscription {
     private orderSubscriber;
     private skipInitialLoad;
@@ -9,6 +15,14 @@ export declare class grpcSubscription {
     private resyncTimeoutId?;
     private decoded?;
     private 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, skipInitialLoad, resubOpts, resyncIntervalMs, decoded, }: {
         grpcConfigs: GrpcConfigs;
         orderSubscriber: OrderSubscriber;
@@ -17,6 +31,8 @@ export declare class grpcSubscription {
         resyncIntervalMs?: number;
         decoded?: boolean;
     });
+    /** Establishes the gRPC/Laserstream program-account subscription (idempotent), optionally backfills with `fetch()`, and starts the resync timer if configured. */
     subscribe(): Promise<void>;
+    /** Tears down the gRPC subscription and cancels the resync timer, if any. No-op if not subscribed. */
     unsubscribe(): Promise<void>;
 }

package/lib/browser/orderSubscriber/grpcSubscription.js

@@ -4,7 +4,21 @@ exports.grpcSubscription = void 0;
 const grpcProgramAccountSubscriber_1 = require("../accounts/grpcProgramAccountSubscriber");
 const memcmp_1 = require("../memcmp");
 const laserProgramAccountSubscriber_1 = require("../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`.
+ */
 class grpcSubscription {
+    /**
+     * @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, skipInitialLoad = false, resubOpts, resyncIntervalMs, decoded = true, }) {
         this.orderSubscriber = orderSubscriber;
         this.skipInitialLoad = skipInitialLoad;
@@ -13,6 +27,7 @@ class grpcSubscription {
         this.decoded = decoded;
         this.grpcConfigs = grpcConfigs;
     }
+    /** Establishes the gRPC/Laserstream program-account subscription (idempotent), optionally backfills with `fetch()`, and starts the resync timer if configured. */
     async subscribe() {
         if (this.subscriber) {
             return;
@@ -61,6 +76,7 @@ class grpcSubscription {
             recursiveResync();
         }
     }
+    /** Tears down the gRPC subscription and cancels the resync timer, if any. No-op if not subscribed. */
     async unsubscribe() {
         if (!this.subscriber)
             return;

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

@@ -2,8 +2,10 @@ import { Commitment, PublicKey } from '@solana/web3.js';
 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';
         frequency: number;
@@ -24,12 +26,19 @@ 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[], pubkey: PublicKey, 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, dataType: 'raw' | 'decoded' | 'buffer') => void;
 }

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

@@ -1,5 +1,6 @@
 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 declare class AverageOverSlotsStrategy implements PriorityFeeStrategy {
     calculate(samples: SolanaPriorityFeeResponse[]): number;
 }

package/lib/browser/priorityFee/averageOverSlotsStrategy.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AverageOverSlotsStrategy = void 0;
+/** `PriorityFeeStrategy` that averages `prioritizationFee` across all samples in the lookback window. Returns `0` for an empty sample set. */
 class AverageOverSlotsStrategy {
     calculate(samples) {
         if (samples.length === 0) {

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

@@ -1,5 +1,6 @@
 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 declare class AverageStrategy implements PriorityFeeStrategy {
     calculate(samples: SolanaPriorityFeeResponse[]): number;
 }

package/lib/browser/priorityFee/averageStrategy.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AverageStrategy = void 0;
+/** `PriorityFeeStrategy` that averages `prioritizationFee` across all samples. Unlike `AverageOverSlotsStrategy`, does not guard the empty-sample case — calling with `samples.length === 0` returns `NaN`. */
 class AverageStrategy {
     calculate(samples) {
         return (samples.reduce((a, b) => {

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

@@ -1,11 +1,21 @@
 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.
+ */
 declare class EwmaStrategy implements PriorityFeeStrategy {
     private halfLife;
     /**
      * @param halfLife The half life of the EWMA in slots. Default is 25 slots, approx 10 seconds.
      */
     constructor(halfLife?: number);
+    /**
+     * @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;
 }
 export { EwmaStrategy };

package/lib/browser/priorityFee/ewmaStrategy.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EwmaStrategy = void 0;
+/**
+ * `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 {
     /**
      * @param halfLife The half life of the EWMA in slots. Default is 25 slots, approx 10 seconds.
@@ -9,6 +15,10 @@ class EwmaStrategy {
         this.halfLife = halfLife;
     }
     // 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) {
         if (samples.length === 0) {
             return 0;

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

@@ -1,3 +1,4 @@
+/** Percentile buckets returned by Helius's `getPriorityFeeEstimate` (`includeAllPriorityFeeLevels`). */
 export declare enum HeliusPriorityLevel {
     MIN = "min",// 25th percentile
     LOW = "low",// 25th percentile
@@ -6,15 +7,27 @@ export declare enum HeliusPriorityLevel {
     VERY_HIGH = "veryHigh",// 95th percentile
     UNSAFE_MAX = "unsafeMax"
 }
+/** 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 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 declare function fetchHeliusPriorityFee(heliusRpcUrl: string, lookbackDistance: number, addresses: string[]): Promise<HeliusPriorityFeeResponse | undefined>;

package/lib/browser/priorityFee/heliusPriorityFeeMethod.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchHeliusPriorityFee = exports.HeliusPriorityLevel = void 0;
 const node_fetch_1 = __importDefault(require("node-fetch"));
+/** Percentile buckets returned by Helius's `getPriorityFeeEstimate` (`includeAllPriorityFeeLevels`). */
 var HeliusPriorityLevel;
 (function (HeliusPriorityLevel) {
     HeliusPriorityLevel["MIN"] = "min";
@@ -14,8 +15,14 @@ var HeliusPriorityLevel;
     HeliusPriorityLevel["VERY_HIGH"] = "veryHigh";
     HeliusPriorityLevel["UNSAFE_MAX"] = "unsafeMax";
 })(HeliusPriorityLevel || (exports.HeliusPriorityLevel = HeliusPriorityLevel = {}));
-/// 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).
+ */
 async function fetchHeliusPriorityFee(heliusRpcUrl, lookbackDistance, addresses) {
     try {
         const response = await (0, node_fetch_1.default)(heliusRpcUrl, {

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

@@ -1,5 +1,6 @@
 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 declare class MaxOverSlotsStrategy implements PriorityFeeStrategy {
     calculate(samples: SolanaPriorityFeeResponse[]): number;
 }

package/lib/browser/priorityFee/maxOverSlotsStrategy.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MaxOverSlotsStrategy = void 0;
+/** `PriorityFeeStrategy` that takes the max `prioritizationFee` across all samples in the lookback window. Returns `0` for an empty sample set. */
 class MaxOverSlotsStrategy {
     calculate(samples) {
         if (samples.length === 0) {

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

@@ -1,4 +1,5 @@
 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 declare class MaxStrategy implements PriorityFeeStrategy {
     calculate(samples: {
         slot: number;

package/lib/browser/priorityFee/maxStrategy.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MaxStrategy = void 0;
+/** `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`. */
 class MaxStrategy {
     calculate(samples) {
         return Math.max(...samples.map((result) => result.prioritizationFee));

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

@@ -4,6 +4,17 @@ import { AverageOverSlotsStrategy } from './averageOverSlotsStrategy';
 import { MaxOverSlotsStrategy } from './maxOverSlotsStrategy';
 import { HeliusPriorityFeeLevels, HeliusPriorityLevel } from './heliusPriorityFeeMethod';
 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 declare class PriorityFeeSubscriber {
     connection?: Connection;
     frequencyMs: number;
@@ -25,22 +36,50 @@ export declare class PriorityFeeSubscriber {
     lastAvgStrategyResult: number;
     lastMaxStrategyResult: number;
     lastSlotSeen: number;
+    /**
+     * @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: PriorityFeeSubscriberConfig);
+    /** Starts polling at `frequencyMs` and performs one immediate `load()`. Idempotent while already subscribed. */
     subscribe(): Promise<void>;
     private loadForSolana;
     private loadForHelius;
     private loadForVelocity;
+    /** @returns The current clamp on returned fee values (micro-lamports/CU), or `undefined` if unclamped. */
     getMaxPriorityFee(): number | undefined;
+    /** Updates the clamp applied to all `get*StrategyResult`/`getHeliusPriorityFeeLevel` results. Pass `undefined` to remove the clamp. */
     updateMaxPriorityFee(newMaxFee: number | undefined): void;
+    /** @returns The multiplier applied to strategy results before clamping; defaults to `1.0`. */
     getPriorityFeeMultiplier(): number;
+    /** Updates the multiplier applied to `getCustomStrategyResult`/`getAvgStrategyResult`/`getMaxStrategyResult` before clamping. */
     updatePriorityFeeMultiplier(newPriorityFeeMultiplier: number): void;
+    /** Swaps the `PriorityFeeStrategy` used to compute `getCustomStrategyResult`; takes effect on the next `load()`. */
     updateCustomStrategy(newStrategy: PriorityFeeStrategy): void;
+    /**
+     * 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?: HeliusPriorityLevel): number;
+    /** @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(): number;
+    /** @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(): number;
+    /** @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(): number;
+    /**
+     * 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.
+     */
     load(): Promise<void>;
+    /** Stops polling. */
     unsubscribe(): Promise<void>;
+    /** Replaces the set of write-locked addresses used for SOLANA/HELIUS fee sampling; takes effect on the next `load()`. */
     updateAddresses(addresses: PublicKey[]): void;
+    /** Replaces the set of markets queried when `priorityFeeMethod` is VELOCITY; takes effect on the next `load()`. */
     updateMarketTypeAndIndex(velocityMarkets: VelocityMarketInfo[]): void;
 }