@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/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/node/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,13 +26,20 @@ 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;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/node/orderSubscriber/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,MAAM,MAAM,qBAAqB,GAAG;IACnC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,kBAAkB,EACf;QACA,IAAI,EAAE,SAAS,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,UAAU,CAAC;KACvB,GACD;QACA,IAAI,EAAE,WAAW,CAAC;QAClB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;KACvB,GACD;QACA,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,WAAW,CAAC;QACzB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;KACvB,CAAC;IACL,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACrC,YAAY,EAAE,CACb,OAAO,EAAE,WAAW,EACpB,aAAa,EAAE,KAAK,EAAE,EACtB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,KAClC,IAAI,CAAC;IACV,WAAW,EAAE,CACZ,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,KAClC,IAAI,CAAC;IACV,cAAc,EAAE,CACf,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,KAClC,IAAI,CAAC;CACV"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/orderSubscriber/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,2CAA2C;AAC3C,MAAM,MAAM,qBAAqB,GAAG;IACnC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,weAAwe;IACxe,kBAAkB,EACf;QACA,IAAI,EAAE,SAAS,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,UAAU,CAAC;KACvB,GACD;QACA,IAAI,EAAE,WAAW,CAAC;QAClB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;KACvB,GACD;QACA,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,WAAW,CAAC;QACzB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,UAAU,CAAC,EAAE,UAAU,CAAC;KACvB,CAAC;IACL,mHAAmH;IACnH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yKAAyK;IACzK,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2JAA2J;IAC3J,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEF,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACrC,uHAAuH;IACvH,YAAY,EAAE,CACb,OAAO,EAAE,WAAW,EACpB,aAAa,EAAE,KAAK,EAAE,EACtB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,KAClC,IAAI,CAAC;IACV,0GAA0G;IAC1G,WAAW,EAAE,CACZ,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,KAClC,IAAI,CAAC;IACV,+EAA+E;IAC/E,cAAc,EAAE,CACf,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,QAAQ,KAClC,IAAI,CAAC;CACV"}

package/lib/node/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/node/priorityFee/averageOverSlotsStrategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"averageOverSlotsStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/averageOverSlotsStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,wBAAyB,YAAW,mBAAmB;IACnE,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAWvD"}
+{"version":3,"file":"averageOverSlotsStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/averageOverSlotsStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,8IAA8I;AAC9I,qBAAa,wBAAyB,YAAW,mBAAmB;IACnE,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAWvD"}

package/lib/node/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/node/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/node/priorityFee/averageStrategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"averageStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/averageStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,eAAgB,YAAW,mBAAmB;IAC1D,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAOvD"}
+{"version":3,"file":"averageStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/averageStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,+MAA+M;AAC/M,qBAAa,eAAgB,YAAW,mBAAmB;IAC1D,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAOvD"}

package/lib/node/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/node/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/node/priorityFee/ewmaStrategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ewmaStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/ewmaStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,cAAM,YAAa,YAAW,mBAAmB;IAChD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;OAEG;gBACS,QAAQ,SAAK;IAKzB,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAwBvD;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"ewmaStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/ewmaStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;GAKG;AACH,cAAM,YAAa,YAAW,mBAAmB;IAChD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;OAEG;gBACS,QAAQ,SAAK;IAKzB;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAwBvD;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/lib/node/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/node/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,16 +7,28 @@ 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>;
 //# sourceMappingURL=heliusPriorityFeeMethod.d.ts.map

package/lib/node/priorityFee/heliusPriorityFeeMethod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heliusPriorityFeeMethod.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/heliusPriorityFeeMethod.ts"],"names":[],"mappings":"AAEA,oBAAY,mBAAmB;IAC9B,GAAG,QAAQ,CAAE,kBAAkB;IAC/B,GAAG,QAAQ,CAAE,kBAAkB;IAC/B,MAAM,WAAW,CAAE,kBAAkB;IACrC,IAAI,SAAS,CAAE,kBAAkB;IACjC,SAAS,aAAa,CAAE,kBAAkB;IAC1C,UAAU,cAAc;CACxB;AAED,MAAM,MAAM,uBAAuB,GAAG;KACpC,GAAG,IAAI,mBAAmB,GAAG,MAAM;CACpC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QACP,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;KAC5C,CAAC;IACF,EAAE,EAAE,MAAM,CAAC;CACX,CAAC;AAIF,wBAAsB,sBAAsB,CAC3C,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CA0BhD"}
+{"version":3,"file":"heliusPriorityFeeMethod.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/heliusPriorityFeeMethod.ts"],"names":[],"mappings":"AAEA,wGAAwG;AACxG,oBAAY,mBAAmB;IAC9B,GAAG,QAAQ,CAAE,kBAAkB;IAC/B,GAAG,QAAQ,CAAE,kBAAkB;IAC/B,MAAM,WAAW,CAAE,kBAAkB;IACrC,IAAI,SAAS,CAAE,kBAAkB;IACjC,SAAS,aAAa,CAAE,kBAAkB;IAC1C,UAAU,cAAc;CACxB;AAED,iFAAiF;AACjF,MAAM,MAAM,uBAAuB,GAAG;KACpC,GAAG,IAAI,mBAAmB,GAAG,MAAM;CACpC,CAAC;AAEF,oEAAoE;AACpE,MAAM,MAAM,yBAAyB,GAAG;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QACP,kGAAkG;QAClG,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,oIAAoI;QACpI,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;KAC5C,CAAC;IACF,EAAE,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC3C,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,yBAAyB,GAAG,SAAS,CAAC,CA0BhD"}

package/lib/node/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/node/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/node/priorityFee/maxOverSlotsStrategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maxOverSlotsStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/maxOverSlotsStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,oBAAqB,YAAW,mBAAmB;IAC/D,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAYvD"}
+{"version":3,"file":"maxOverSlotsStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/maxOverSlotsStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,mJAAmJ;AACnJ,qBAAa,oBAAqB,YAAW,mBAAmB;IAC/D,SAAS,CAAC,OAAO,EAAE,yBAAyB,EAAE,GAAG,MAAM;CAYvD"}

package/lib/node/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/node/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/node/priorityFee/maxStrategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"maxStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/maxStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,qBAAa,WAAY,YAAW,mBAAmB;IACtD,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,MAAM;CAGzE"}
+{"version":3,"file":"maxStrategy.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/maxStrategy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,8MAA8M;AAC9M,qBAAa,WAAY,YAAW,mBAAmB;IACtD,SAAS,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,MAAM;CAGzE"}

package/lib/node/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/node/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,23 +36,51 @@ 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;
 }
 //# sourceMappingURL=priorityFeeSubscriber.d.ts.map

package/lib/node/priorityFee/priorityFeeSubscriber.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"priorityFeeSubscriber.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/priorityFeeSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAEN,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAC3B,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EACN,uBAAuB,EACvB,mBAAmB,EAEnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEN,kBAAkB,EAClB,MAAM,6BAA6B,CAAC;AAErC,qBAAa,qBAAqB;IACjC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,eAAe,2BAAkC;IACjD,WAAW,uBAA8B;IACzC,iBAAiB,oBAA4B;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAE3C,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAE3C,iBAAiB,SAAK;IACtB,wBAAwB,SAAK;IAC7B,qBAAqB,SAAK;IAC1B,qBAAqB,SAAK;IAC1B,YAAY,SAAK;gBAEE,MAAM,EAAE,2BAA2B;IAkDzC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;YASzB,aAAa;YA0Bb,aAAa;YAwBb,eAAe;IAyCtB,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAIvC,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;IAIlD,wBAAwB,IAAI,MAAM;IAIlC,2BAA2B,CAAC,wBAAwB,EAAE,MAAM;IAI5D,oBAAoB,CAAC,WAAW,EAAE,mBAAmB;IAIrD,yBAAyB,CAC/B,KAAK,GAAE,mBAAgD,GACrD,MAAM;IAUF,uBAAuB,IAAI,MAAM;IASjC,oBAAoB,IAAI,MAAM;IAQ9B,oBAAoB,IAAI,MAAM;IAQxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBrB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAOlC,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE;IAItC,wBAAwB,CAAC,eAAe,EAAE,kBAAkB,EAAE;CAGrE"}
+{"version":3,"file":"priorityFeeSubscriber.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/priorityFeeSubscriber.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAEN,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAC3B,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EACN,uBAAuB,EACvB,mBAAmB,EAEnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEN,kBAAkB,EAClB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;GAUG;AACH,qBAAa,qBAAqB;IACjC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACrC,eAAe,2BAAkC;IACjD,WAAW,uBAA8B;IACzC,iBAAiB,oBAA4B;IAC7C,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAE3C,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAE3C,iBAAiB,SAAK;IACtB,wBAAwB,SAAK;IAC7B,qBAAqB,SAAK;IAC1B,qBAAqB,SAAK;IAC1B,YAAY,SAAK;IAEjB;;;OAGG;gBACgB,MAAM,EAAE,2BAA2B;IAkDtD,gHAAgH;IACnG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;YASzB,aAAa;YA0Bb,aAAa;YAwBb,eAAe;IAyC7B,0GAA0G;IACnG,iBAAiB,IAAI,MAAM,GAAG,SAAS;IAI9C,uIAAuI;IAChI,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS;IAIzD,8FAA8F;IACvF,wBAAwB,IAAI,MAAM;IAIzC,iIAAiI;IAC1H,2BAA2B,CAAC,wBAAwB,EAAE,MAAM;IAInE,oHAAoH;IAC7G,oBAAoB,CAAC,WAAW,EAAE,mBAAmB;IAI5D;;;;OAIG;IACI,yBAAyB,CAC/B,KAAK,GAAE,mBAAgD,GACrD,MAAM;IAUT,gOAAgO;IACzN,uBAAuB,IAAI,MAAM;IASxC,wTAAwT;IACjT,oBAAoB,IAAI,MAAM;IAQrC,4TAA4T;IACrT,oBAAoB,IAAI,MAAM;IAQrC;;;;;;OAMG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAsBlC,qBAAqB;IACR,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAOzC,yHAAyH;IAClH,eAAe,CAAC,SAAS,EAAE,SAAS,EAAE;IAI7C,mHAAmH;IAC5G,wBAAwB,CAAC,eAAe,EAAE,kBAAkB,EAAE;CAGrE"}

package/lib/node/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/node/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/node/priorityFee/priorityFeeSubscriberMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"priorityFeeSubscriberMap.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/priorityFeeSubscriberMap.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,kBAAkB,EAClB,yBAAyB,EAGzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAEN,8BAA8B,EAC9B,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,wBAAwB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAE3C,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,2BAA2B,EAAE,MAAM,CAAC;IACpC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;gBAE1C,MAAM,EAAE,8BAA8B;IAYzD,OAAO,CAAC,aAAa;IAQR,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAS1B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB3B,wBAAwB,CAAC,eAAe,EAAE,kBAAkB,EAAE;IAI9D,eAAe,CACrB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GACjB,yBAAyB,GAAG,SAAS;CAGxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BE"}
+{"version":3,"file":"priorityFeeSubscriberMap.d.ts","sourceRoot":"","sources":["../../../src/priorityFee/priorityFeeSubscriberMap.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,kBAAkB,EAClB,yBAAyB,EAGzB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAEN,8BAA8B,EAC9B,MAAM,SAAS,CAAC;AAEjB;;;;;;GAMG;AACH,qBAAa,wBAAwB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;IAE3C,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACvC,2BAA2B,EAAE,MAAM,CAAC;IACpC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAE7D,wIAAwI;gBACrH,MAAM,EAAE,8BAA8B;IAYzD,OAAO,CAAC,aAAa;IAQrB,2GAA2G;IAC9F,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IASvC,qBAAqB;IACR,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAOzC;;;;;OAKG;IACU,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBlC,wFAAwF;IACjF,wBAAwB,CAAC,eAAe,EAAE,kBAAkB,EAAE;IAIrE;;;;OAIG;IACI,eAAe,CACrB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GACjB,yBAAyB,GAAG,SAAS;CAGxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BE"}

package/lib/node/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/node/priorityFee/solanaPriorityFeeMethod.d.ts

@@ -1,7 +1,19 @@
 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>;
 //# sourceMappingURL=solanaPriorityFeeMethod.d.ts.map