@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/node/tx/baseTxSender.js

@@ -15,8 +15,32 @@ const reportTransactionError_1 = require("./reportTransactionError");
 const BASELINE_TX_LAND_RATE = 0.9;
 const DEFAULT_TIMEOUT = 35000;
 const DEFAULT_TX_LAND_RATE_LOOKBACK_WINDOW_MINUTES = 10;
+/**
+ * Shared base for all `TxSender` implementations (`RetryTxSender`, `WhileValidTxSender`,
+ * `FastSingleTxSender`, `ForwardOnlyTxSender`). Provides signing/serialization via `TxHandler`,
+ * confirmation via websocket subscription and/or polling (per `ConfirmationStrategy`),
+ * timeout/land-rate bookkeeping, and fan-out to `additionalConnections`. Subclasses are expected
+ * to implement `sendRawTransaction` with their specific retry/broadcast behavior — the base
+ * implementation always throws.
+ */
 class BaseTxSender {
+    /**
+     * @param props.connection - Primary RPC connection used for sending and confirming transactions.
+     * @param props.wallet - Wallet used to sign transactions that aren't already `preSigned`.
+     * @param props.opts - Default `ConfirmOptions` used when a call site doesn't pass its own; defaults to `DEFAULT_CONFIRMATION_OPTS` (`'confirmed'`).
+     * @param props.timeout - Confirmation timeout in milliseconds; defaults to 35000 (35s).
+     * @param props.additionalConnections - Extra connections to also broadcast raw transactions to.
+     * @param props.confirmationStrategy - How to wait for confirmation; defaults to `ConfirmationStrategy.Combo`.
+     * @param props.additionalTxSenderCallbacks - Callbacks invoked with each sent transaction's base58 encoding.
+     * @param props.trackTxLandRate - Enables land-rate tracking (backs `getTxLandRate()`/`getSuggestedPriorityFeeMultiplier()`).
+     * @param props.txHandler - Custom `TxHandler` for signing/building transactions; defaults to one constructed from `connection`/`wallet`/`opts`.
+     * @param props.txLandRateLookbackWindowMinutes - Rolling window, in minutes, of sent signatures kept for the land-rate calculation; defaults to 10.
+     * @param props.landRateToFeeFunc - Custom mapping from land rate to priority-fee multiplier; defaults to `defaultLandRateToFeeFunc`.
+     * @param props.throwOnTimeoutError - Whether confirmation timeouts throw `TxSendError` instead of returning `undefined`; defaults to `true`.
+     * @param props.throwOnTransactionError - Whether a failed on-chain result throws the resolved program error; defaults to `true`.
+     */
     constructor({ connection, wallet, opts = config_1.DEFAULT_CONFIRMATION_OPTS, timeout = DEFAULT_TIMEOUT, additionalConnections = new Array(), confirmationStrategy = types_1.ConfirmationStrategy.Combo, additionalTxSenderCallbacks, trackTxLandRate, txHandler, txLandRateLookbackWindowMinutes = DEFAULT_TX_LAND_RATE_LOOKBACK_WINDOW_MINUTES, landRateToFeeFunc, throwOnTimeoutError = true, throwOnTransactionError = true, }) {
+        /** Count of `confirmTransactionWebSocket`/`confirmTransactionPolling` calls that hit `timeout` without a definitive result. */
         this.timeoutCount = 0;
         this.txLandRate = 0;
         this.lastPriorityFeeSuggestion = 1;
@@ -46,6 +70,14 @@ class BaseTxSender {
         this.throwOnTimeoutError = throwOnTimeoutError;
         this.throwOnTransactionError = throwOnTransactionError;
     }
+    /**
+     * Signs (via `prepareTx`, unless `preSigned`) and sends a legacy `Transaction`.
+     * @param tx - Transaction to send.
+     * @param additionalSigners - Extra signers to co-sign alongside the wallet; defaults to none.
+     * @param opts - Confirmation options; defaults to `this.opts`.
+     * @param preSigned - If `true`, skip wallet signing.
+     * @returns The result of `sendRawTransaction` on the serialized, signed transaction.
+     */
     async send(tx, additionalSigners, opts, preSigned) {
         if (additionalSigners === undefined) {
             additionalSigners = [];
@@ -56,12 +88,40 @@ class BaseTxSender {
         const signedTx = await this.prepareTx(tx, additionalSigners, opts, preSigned);
         return this.sendRawTransaction(signedTx.serialize(), opts);
     }
+    /**
+     * Delegates to `TxHandler.prepareTx` to attach a recent blockhash, fee payer, and signatures.
+     * @param tx - Transaction to prepare.
+     * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+     * @param opts - Confirmation options (affects blockhash commitment).
+     * @param preSigned - If `true`, skip wallet signing.
+     * @returns The prepared (blockhash-populated, signed unless `preSigned`) transaction.
+     */
     async prepareTx(tx, additionalSigners, opts, preSigned) {
         return this.txHandler.prepareTx(tx, additionalSigners, undefined, opts, preSigned);
     }
+    /**
+     * Builds (but does not send) a `VersionedTransaction` from raw instructions via
+     * `TxHandler.generateVersionedTransaction`.
+     * @param ixs - Instructions to include, in order.
+     * @param lookupTableAccounts - Address lookup tables to compile the message against.
+     * @param _additionalSigners - Unused by this implementation.
+     * @param opts - Unused by this implementation (present for `TxSender` interface compatibility).
+     * @param blockhash - Blockhash to use; if omitted, fetched fresh via `connection.getLatestBlockhash()`.
+     * @returns The compiled `VersionedTransaction` (not yet signed by additional signers beyond the wallet).
+     */
     async getVersionedTransaction(ixs, lookupTableAccounts, _additionalSigners, opts, blockhash) {
         return this.txHandler.generateVersionedTransaction(blockhash !== null && blockhash !== void 0 ? blockhash : (await this.connection.getLatestBlockhash()), ixs, lookupTableAccounts, this.wallet);
     }
+    /**
+     * Signs (unless `preSigned`) and sends a `VersionedTransaction`. When the wallet exposes a
+     * `payer` `Keypair` directly, signs in-place with `tx.sign(...)`; otherwise delegates to
+     * `TxHandler.signVersionedTx` (needed for wallet adapters without direct keypair access).
+     * @param tx - Transaction to send.
+     * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+     * @param opts - Confirmation options; defaults to `this.opts`.
+     * @param preSigned - If `true`, skip signing entirely.
+     * @returns The result of `sendRawTransaction` on the serialized, signed transaction.
+     */
     async sendVersionedTransaction(tx, additionalSigners, opts, preSigned) {
         let signedTx;
         if (preSigned) {
@@ -81,6 +141,12 @@ class BaseTxSender {
         }
         return this.sendRawTransaction(signedTx.serialize(), opts);
     }
+    /**
+     * Sends and confirms an already-serialized, already-signed transaction. `BaseTxSender` itself
+     * has no broadcast/retry strategy — every concrete sender (`RetryTxSender`,
+     * `WhileValidTxSender`, `FastSingleTxSender`, `ForwardOnlyTxSender`) must override this.
+     * @throws Error always, if not overridden by a subclass.
+     */
     async sendRawTransaction(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     rawTransaction, 
@@ -88,7 +154,12 @@ class BaseTxSender {
     opts) {
         throw new Error('Must be implemented by subclass');
     }
-    /* Simulate the tx and return a boolean for success value */
+    /**
+     * Simulates a transaction via `connection.simulateTransaction` without sending it, swallowing
+     * both simulation errors and RPC-call failures into a `false` result (logged to `console.error`).
+     * @param tx - Transaction to simulate.
+     * @returns `true` if simulation succeeded with no error, `false` otherwise.
+     */
     async simulateTransaction(tx) {
         try {
             const result = await this.connection.simulateTransaction(tx);
@@ -103,6 +174,18 @@ class BaseTxSender {
             return false;
         }
     }
+    /**
+     * Waits for a transaction to confirm by subscribing to `onSignature` on `connection` and every
+     * `additionalConnections` entry simultaneously, resolving on whichever responds first. If no
+     * connection confirms within `this.timeout` and `confirmationStrategy` is `Combo`, falls back
+     * to a one-shot `getSignatureStatuses` check before giving up.
+     * @param signature - Base58-encoded transaction signature to confirm.
+     * @param commitment - Commitment level for the subscription; defaults to `this.opts.commitment`.
+     * @returns The confirmation result, or `undefined` if it timed out and `throwOnTimeoutError` is `false`.
+     * @throws Error if `signature` isn't valid base58 or isn't 64 bytes decoded. `TxSendError`
+     * (code `NOT_CONFIRMED_ERROR_CODE`) on timeout if `throwOnTimeoutError` is `true` (the default) —
+     * in that case the transaction's actual outcome is unknown, not necessarily failed.
+     */
     async confirmTransactionWebSocket(signature, commitment) {
         var _a, _b;
         let decodedSignature;
@@ -120,7 +203,10 @@ class BaseTxSender {
         let response = null;
         const promises = connections.map((connection, i) => {
             let subscriptionId;
-            const confirmPromise = new Promise((resolve, reject) => {
+            // a failed subscription setup on one connection is best-effort: log and
+            // leave its promise pending so the race keeps waiting on the others
+            // (if every subscription fails, the timeout/Combo fallback still applies)
+            const confirmPromise = new Promise((resolve) => {
                 try {
                     subscriptionId = connection.onSignature(signature, (result, context) => {
                         subscriptionIds[i] = undefined;
@@ -132,7 +218,7 @@ class BaseTxSender {
                     }, subscriptionCommitment);
                 }
                 catch (err) {
-                    reject(err);
+                    console.error('confirmTransactionWebSocket: failed to set up onSignature listener', err);
                 }
             });
             subscriptionIds.push(subscriptionId);
@@ -174,8 +260,19 @@ class BaseTxSender {
         }
         return response !== null && response !== void 0 ? response : undefined;
     }
+    /**
+     * Waits for a transaction to confirm by polling `getSignatureStatuses` with exponential
+     * backoff, starting at 400ms and capping at 5000ms, until `commitment` is reached or
+     * `this.timeout` elapses.
+     * @param signature - Base58-encoded transaction signature to confirm.
+     * @param commitment - Commitment level to wait for; defaults to `'finalized'`.
+     * @returns The confirmation result (`{ err: null }` on success), or `undefined` if it timed out and `throwOnTimeoutError` is `false`.
+     * @throws TxSendError (code `NOT_CONFIRMED_ERROR_CODE`) on timeout if `throwOnTimeoutError` is
+     * `true` (the default) — in that case the transaction's actual outcome is unknown, not
+     * necessarily failed.
+     */
     async confirmTransactionPolling(signature, commitment = 'finalized') {
-        var _a;
+        var _a, _b;
         let totalTime = 0;
         let backoffTime = 400; // approx block time
         const start = Date.now();
@@ -185,10 +282,22 @@ class BaseTxSender {
                 signature,
             ]);
             const signatureResult = rpcResponse && ((_a = rpcResponse.value) === null || _a === void 0 ? void 0 : _a[0]);
+            // a stronger status satisfies a weaker commitment (processed < confirmed < finalized),
+            // e.g. a tx already finalized must not keep a 'confirmed' wait polling until timeout
+            const statusRank = {
+                processed: 0,
+                confirmed: 1,
+                finalized: 2,
+            };
             if (rpcResponse &&
                 signatureResult &&
-                signatureResult.confirmationStatus === commitment) {
-                return { context: rpcResponse.context, value: { err: null } };
+                signatureResult.confirmationStatus &&
+                statusRank[signatureResult.confirmationStatus] >=
+                    ((_b = statusRank[commitment]) !== null && _b !== void 0 ? _b : 2)) {
+                return {
+                    context: rpcResponse.context,
+                    value: { err: signatureResult.err },
+                };
             }
             totalTime += backoffTime;
             backoffTime = Math.min(backoffTime * 2, 5000);
@@ -200,6 +309,14 @@ class BaseTxSender {
             throw new types_1.TxSendError(`Transaction was not confirmed in ${duration.toFixed(2)} seconds. It is unknown if it succeeded or failed. Check signature ${signature} using the Solana Explorer or CLI tools.`, txConstants_1.NOT_CONFIRMED_ERROR_CODE);
         }
     }
+    /**
+     * Confirms a transaction using whichever strategy `this.confirmationStrategy` selects:
+     * `WebSocket`/`Combo` route to `confirmTransactionWebSocket`, `Polling` to `confirmTransactionPolling`.
+     * @param signature - Base58-encoded transaction signature to confirm.
+     * @param commitment - Commitment level to wait for.
+     * @returns The confirmation result, or `undefined` on timeout if `throwOnTimeoutError` is `false`.
+     * @throws TxSendError on timeout if `throwOnTimeoutError` is `true` (see `confirmTransactionWebSocket`/`confirmTransactionPolling`).
+     */
     async confirmTransaction(signature, commitment) {
         if (this.confirmationStrategy === types_1.ConfirmationStrategy.WebSocket ||
             this.confirmationStrategy === types_1.ConfirmationStrategy.Combo) {
@@ -209,9 +326,18 @@ class BaseTxSender {
             return await this.confirmTransactionPolling(signature, commitment);
         }
     }
+    /** Current time in milliseconds since epoch (thin wrapper over `Date.now()`, overridable in tests). */
     getTimestamp() {
         return new Date().getTime();
     }
+    /**
+     * Races an array of promises against a timeout, resolving to `null` (rather than rejecting) if
+     * none settle in time. Unlike `../util/promiseTimeout`, this accepts multiple promises (used to
+     * race confirmation across `connection` plus every `additionalConnections` entry).
+     * @param promises - Promises to race.
+     * @param timeoutMs - Timeout in milliseconds.
+     * @returns The first promise's resolved value, or `null` if none settled before `timeoutMs`.
+     */
     promiseTimeout(promises, timeoutMs) {
         let timeoutId;
         const timeoutPromise = new Promise((resolve) => {
@@ -222,6 +348,13 @@ class BaseTxSender {
             return result;
         });
     }
+    /**
+     * Best-effort broadcasts a raw transaction to every `additionalConnections` entry and invokes
+     * `additionalTxSenderCallbacks` with its base58 encoding. Failures are logged, not thrown or
+     * awaited by the caller — this never affects whether the primary send/confirm succeeds.
+     * @param rawTx - Serialized, signed transaction bytes.
+     * @param opts - Options passed through to each connection's `sendRawTransaction`.
+     */
     sendToAdditionalConnections(rawTx, opts) {
         var _a;
         this.additionalConnections.map((connection) => {
@@ -236,6 +369,11 @@ class BaseTxSender {
             callback(bs58_1.default.encode(rawTx));
         });
     }
+    /**
+     * Adds an extra RPC connection to broadcast future transactions to, unless a connection with
+     * the same RPC endpoint is already registered.
+     * @param newConnection - Connection to add to `additionalConnections`.
+     */
     addAdditionalConnection(newConnection) {
         const alreadyUsingConnection = this.additionalConnections.filter((connection) => {
             // @ts-ignore
@@ -245,9 +383,20 @@ class BaseTxSender {
             this.additionalConnections.push(newConnection);
         }
     }
+    /** @returns The number of confirmation attempts that have timed out so far. */
     getTimeoutCount() {
         return this.timeoutCount;
     }
+    /**
+     * Inspects a confirmed signature's result and, if it recorded an on-chain error, resolves the
+     * detailed program error via `throwTransactionError` and throws it. Note this check runs
+     * whenever `result.err` is set, independent of the `throwOnTransactionError` field — callers
+     * that want to suppress transaction-error throwing should avoid calling this method rather
+     * than rely on that flag here.
+     * @param txSig - Transaction signature to look up the detailed error for.
+     * @param result - The `SignatureResult` returned by confirmation.
+     * @throws Error the resolved on-chain program error, if `result.err` is set.
+     */
     async checkConfirmationResultForError(txSig, result) {
         var _a;
         if (result === null || result === void 0 ? void 0 : result.err) {
@@ -255,6 +404,12 @@ class BaseTxSender {
         }
         return;
     }
+    /**
+     * Computes the fraction of recently sent transactions (within `lookbackWindowMinutes`) that
+     * landed, from `txSigCache`'s current entries. Returns the last computed `txLandRate` (default
+     * 0) if `trackTxLandRate` is disabled or the cache is empty, rather than recomputing.
+     * @returns The land rate as a fraction between 0 and 1.
+     */
     getTxLandRate() {
         if (!this.trackTxLandRate || !this.txSigCache) {
             return this.txLandRate;
@@ -274,6 +429,14 @@ class BaseTxSender {
         this.txLandRate = numerator / denominator;
         return this.txLandRate;
     }
+    /**
+     * Default `landRateToFeeFunc`: returns `1` (no boost) if the land rate is already at/above
+     * `BASELINE_TX_LAND_RATE` (0.9) or fewer than 3 samples have been recorded yet (too little data
+     * to react); otherwise returns a multiplier that grows logarithmically as the land rate falls
+     * further below baseline, capped at `10`.
+     * @param txLandRate - Recent land rate, 0-1 (see `getTxLandRate`).
+     * @returns A priority-fee multiplier between 1 and 10.
+     */
     defaultLandRateToFeeFunc(txLandRate) {
         var _a, _b;
         if (txLandRate >= BASELINE_TX_LAND_RATE ||
@@ -283,6 +446,11 @@ class BaseTxSender {
         const multiplier = 10 * Math.log10(1 + (BASELINE_TX_LAND_RATE - txLandRate) * 5);
         return Math.min(multiplier, 10);
     }
+    /**
+     * Suggests a multiplier to apply to a base priority fee, based on recent land rate — intended
+     * for callers to scale up their compute-unit price when transactions have been landing poorly.
+     * @returns `1` (no change) if `trackTxLandRate` is disabled; otherwise `landRateToFeeFunc(getTxLandRate())`.
+     */
     getSuggestedPriorityFeeMultiplier() {
         if (!this.trackTxLandRate) {
             return 1;

package/lib/node/tx/blockhashFetcher/baseBlockhashFetcher.d.ts

@@ -1,9 +1,21 @@
 import { BlockhashWithExpiryBlockHeight, Commitment, Connection } from '@solana/web3.js';
 import { BlockhashFetcher } from './types';
+/**
+ * Simplest `BlockhashFetcher`: makes a fresh `getLatestBlockhash` RPC call on every request, no
+ * caching or retry. Prefer `CachedBlockhashFetcher` for senders issuing many transactions in quick
+ * succession to avoid RPC rate limits.
+ */
 export declare class BaseBlockhashFetcher implements BlockhashFetcher {
     private connection;
     private blockhashCommitment;
+    /**
+     * @param connection - RPC connection to fetch the blockhash from.
+     * @param blockhashCommitment - Commitment level to request the blockhash at.
+     */
     constructor(connection: Connection, blockhashCommitment: Commitment);
+    /**
+     * @returns The latest blockhash and its expiry block height, fetched fresh from `connection`.
+     */
     getLatestBlockhash(): Promise<BlockhashWithExpiryBlockHeight | undefined>;
 }
 //# sourceMappingURL=baseBlockhashFetcher.d.ts.map

package/lib/node/tx/blockhashFetcher/baseBlockhashFetcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"baseBlockhashFetcher.d.ts","sourceRoot":"","sources":["../../../../src/tx/blockhashFetcher/baseBlockhashFetcher.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,8BAA8B,EAC9B,UAAU,EACV,UAAU,EACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,qBAAa,oBAAqB,YAAW,gBAAgB;IAE3D,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,mBAAmB;gBADnB,UAAU,EAAE,UAAU,EACtB,mBAAmB,EAAE,UAAU;IAG3B,kBAAkB,IAAI,OAAO,CACzC,8BAA8B,GAAG,SAAS,CAC1C;CAGD"}
+{"version":3,"file":"baseBlockhashFetcher.d.ts","sourceRoot":"","sources":["../../../../src/tx/blockhashFetcher/baseBlockhashFetcher.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,8BAA8B,EAC9B,UAAU,EACV,UAAU,EACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,oBAAqB,YAAW,gBAAgB;IAM3D,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,mBAAmB;IAN5B;;;OAGG;gBAEM,UAAU,EAAE,UAAU,EACtB,mBAAmB,EAAE,UAAU;IAGxC;;OAEG;IACU,kBAAkB,IAAI,OAAO,CACzC,8BAA8B,GAAG,SAAS,CAC1C;CAGD"}

package/lib/node/tx/blockhashFetcher/baseBlockhashFetcher.js

@@ -1,11 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseBlockhashFetcher = void 0;
+/**
+ * Simplest `BlockhashFetcher`: makes a fresh `getLatestBlockhash` RPC call on every request, no
+ * caching or retry. Prefer `CachedBlockhashFetcher` for senders issuing many transactions in quick
+ * succession to avoid RPC rate limits.
+ */
 class BaseBlockhashFetcher {
+    /**
+     * @param connection - RPC connection to fetch the blockhash from.
+     * @param blockhashCommitment - Commitment level to request the blockhash at.
+     */
     constructor(connection, blockhashCommitment) {
         this.connection = connection;
         this.blockhashCommitment = blockhashCommitment;
     }
+    /**
+     * @returns The latest blockhash and its expiry block height, fetched fresh from `connection`.
+     */
     async getLatestBlockhash() {
         return this.connection.getLatestBlockhash(this.blockhashCommitment);
     }

package/lib/node/tx/blockhashFetcher/cachedBlockhashFetcher.d.ts

@@ -15,10 +15,25 @@ export declare class CachedBlockhashFetcher implements BlockhashFetcher {
     private staleCacheTimeMs;
     private recentBlockhashCache;
     private blockhashFetchingPromise;
+    /**
+     * @param connection - RPC connection to fetch the blockhash from.
+     * @param blockhashCommitment - Commitment level to request the blockhash at.
+     * @param retryCount - Maximum fetch attempts before giving up and throwing.
+     * @param retrySleepTimeMs - Base backoff delay (ms) between retries; doubles each attempt (`retrySleepTimeMs * 2^i`).
+     * @param staleCacheTimeMs - How long (ms) a cached blockhash is served before a refresh is triggered.
+     */
     constructor(connection: Connection, blockhashCommitment: Commitment, retryCount: number, retrySleepTimeMs: number, staleCacheTimeMs: number);
     private fetchBlockhashWithRetry;
     private sleep;
     private updateBlockhashCache;
+    /**
+     * Returns the cached blockhash, refreshing it first if the cache is older than
+     * `staleCacheTimeMs`. Concurrent calls during a refresh all await the same in-flight fetch
+     * rather than issuing duplicate RPC requests.
+     * @returns The latest (possibly cached) blockhash and its expiry block height.
+     * @throws If no cached value exists yet and the initial fetch fails after exhausting
+     * `retryCount` retries.
+     */
     getLatestBlockhash(): Promise<BlockhashWithExpiryBlockHeight | undefined>;
     private isCacheStale;
     /**

package/lib/node/tx/blockhashFetcher/cachedBlockhashFetcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cachedBlockhashFetcher.d.ts","sourceRoot":"","sources":["../../../../src/tx/blockhashFetcher/cachedBlockhashFetcher.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,8BAA8B,EAC9B,UAAU,EACV,UAAU,EACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAS7D,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,mBAAmB;IAC3B,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,gBAAgB;IAZzB,OAAO,CAAC,oBAAoB,CAGa;IAEzC,OAAO,CAAC,wBAAwB,CAA8B;gBAGrD,UAAU,EAAE,UAAU,EACtB,mBAAmB,EAAE,UAAU,EAC/B,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM;YAGnB,uBAAuB;IAgBrC,OAAO,CAAC,KAAK;YAIC,oBAAoB;IAQrB,kBAAkB,IAAI,OAAO,CACzC,8BAA8B,GAAG,SAAS,CAC1C;IAOD,OAAO,CAAC,YAAY;IAOpB;;OAEG;YACW,gBAAgB;CAY9B"}
+{"version":3,"file":"cachedBlockhashFetcher.d.ts","sourceRoot":"","sources":["../../../../src/tx/blockhashFetcher/cachedBlockhashFetcher.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,8BAA8B,EAC9B,UAAU,EACV,UAAU,EACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAgB7D,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,mBAAmB;IAC3B,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,gBAAgB;IACxB,OAAO,CAAC,gBAAgB;IAnBzB,OAAO,CAAC,oBAAoB,CAGa;IAEzC,OAAO,CAAC,wBAAwB,CAA8B;IAE9D;;;;;;OAMG;gBAEM,UAAU,EAAE,UAAU,EACtB,mBAAmB,EAAE,UAAU,EAC/B,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM;YAGnB,uBAAuB;IAgBrC,OAAO,CAAC,KAAK;YAIC,oBAAoB;IAQlC;;;;;;;OAOG;IACU,kBAAkB,IAAI,OAAO,CACzC,8BAA8B,GAAG,SAAS,CAC1C;IAOD,OAAO,CAAC,YAAY;IAOpB;;OAEG;YACW,gBAAgB;CAY9B"}

package/lib/node/tx/blockhashFetcher/cachedBlockhashFetcher.js

@@ -9,6 +9,13 @@ exports.CachedBlockhashFetcher = void 0;
  * - Prevents concurrent requests for the same blockhash
  */
 class CachedBlockhashFetcher {
+    /**
+     * @param connection - RPC connection to fetch the blockhash from.
+     * @param blockhashCommitment - Commitment level to request the blockhash at.
+     * @param retryCount - Maximum fetch attempts before giving up and throwing.
+     * @param retrySleepTimeMs - Base backoff delay (ms) between retries; doubles each attempt (`retrySleepTimeMs * 2^i`).
+     * @param staleCacheTimeMs - How long (ms) a cached blockhash is served before a refresh is triggered.
+     */
     constructor(connection, blockhashCommitment, retryCount, retrySleepTimeMs, staleCacheTimeMs) {
         this.connection = connection;
         this.blockhashCommitment = blockhashCommitment;
@@ -42,6 +49,14 @@ class CachedBlockhashFetcher {
             lastUpdated: Date.now(),
         };
     }
+    /**
+     * Returns the cached blockhash, refreshing it first if the cache is older than
+     * `staleCacheTimeMs`. Concurrent calls during a refresh all await the same in-flight fetch
+     * rather than issuing duplicate RPC requests.
+     * @returns The latest (possibly cached) blockhash and its expiry block height.
+     * @throws If no cached value exists yet and the initial fetch fails after exhausting
+     * `retryCount` retries.
+     */
     async getLatestBlockhash() {
         if (this.isCacheStale()) {
             await this.refreshBlockhash();

package/lib/node/tx/blockhashFetcher/types.d.ts

@@ -1,5 +1,9 @@
 import { BlockhashWithExpiryBlockHeight } from '@solana/web3.js';
+/** Strategy interface for obtaining a recent blockhash, abstracting whether it's fetched fresh every call or cached (see `BaseBlockhashFetcher`/`CachedBlockhashFetcher`). */
 export interface BlockhashFetcher {
+    /**
+     * @returns The latest blockhash and its expiry block height, or `undefined` if unavailable.
+     */
     getLatestBlockhash(): Promise<BlockhashWithExpiryBlockHeight | undefined>;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/node/tx/blockhashFetcher/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/tx/blockhashFetcher/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAEjE,MAAM,WAAW,gBAAgB;IAChC,kBAAkB,IAAI,OAAO,CAAC,8BAA8B,GAAG,SAAS,CAAC,CAAC;CAC1E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/tx/blockhashFetcher/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAEjE,8KAA8K;AAC9K,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,kBAAkB,IAAI,OAAO,CAAC,8BAA8B,GAAG,SAAS,CAAC,CAAC;CAC1E"}

package/lib/node/tx/fastSingleTxSender.d.ts

@@ -6,19 +6,51 @@ import { ConfirmOptions, Connection, Commitment, BlockhashWithExpiryBlockHeight
 import { BaseTxSender } from './baseTxSender';
 import { TxHandler } from './txHandler';
 import { IWallet } from '../types';
+/**
+ * `TxSender` optimized for low latency: sends a transaction exactly once (no resend/retry loop —
+ * relies on the RPC node's own forwarding), and can skip confirmation entirely or confirm
+ * asynchronously in the background so `sendRawTransaction` returns as soon as the send lands.
+ * Maintains its own periodically-refreshed blockhash cache (independent of `TxHandler`'s) purely
+ * for that background-refresh convenience; it is not actually consumed by `sendRawTransaction`
+ * here. Suited to latency-sensitive keeper bots that would rather fire-and-forget than pay for
+ * `RetryTxSender`'s resend loop.
+ */
 export declare class FastSingleTxSender extends BaseTxSender {
     connection: Connection;
     wallet: IWallet;
     opts: ConfirmOptions;
     timeout: number;
+    /** How often (ms) `startBlockhashRefreshLoop` refreshes `recentBlockhash`; `0` disables the refresh loop. */
     blockhashRefreshInterval: number;
     additionalConnections: Connection[];
     timoutCount: number;
+    /** Periodically refreshed blockhash cache (see `startBlockhashRefreshLoop`); informational only — `sendRawTransaction` does not currently read this field. */
     recentBlockhash?: BlockhashWithExpiryBlockHeight;
+    /** If `true`, `sendRawTransaction` returns immediately after sending, without waiting for or checking confirmation. */
     skipConfirmation: boolean;
+    /** If `true` (and `skipConfirmation` is `false`), confirmation runs without being awaited — `sendRawTransaction` returns before the transaction is confirmed. */
     confirmInBackground: boolean;
+    /** Commitment level used when refreshing `recentBlockhash`. */
     blockhashCommitment: Commitment;
+    /** Handle for the interval timer started by `startBlockhashRefreshLoop`. */
     blockhashIntervalId?: NodeJS.Timer;
+    /**
+     * @param props.connection - RPC connection used for sending, confirming, and blockhash refresh.
+     * @param props.wallet - Wallet used to sign transactions that aren't already `preSigned`.
+     * @param props.opts - Default `ConfirmOptions`; defaults to `DEFAULT_CONFIRMATION_OPTS` with `maxRetries: 0` (this sender does not retry sends itself).
+     * @param props.timeout - Confirmation timeout in milliseconds; defaults to 35000 (35s).
+     * @param props.blockhashRefreshInterval - Interval (ms) for the background blockhash refresh; defaults to 10000 (10s). `0` disables it.
+     * @param props.additionalConnections - Extra connections to also broadcast raw transactions to.
+     * @param props.skipConfirmation - Skip confirmation entirely after sending; defaults to `false`.
+     * @param props.confirmInBackground - Confirm without awaiting, so `sendRawTransaction` resolves right after send; defaults to `false`.
+     * @param props.blockhashCommitment - Commitment for the background blockhash refresh; defaults to `'finalized'`.
+     * @param props.confirmationStrategy - How to wait for confirmation; defaults to `ConfirmationStrategy.Combo`.
+     * @param props.trackTxLandRate - Enables land-rate tracking.
+     * @param props.txHandler - Custom `TxHandler` for signing/building transactions.
+     * @param props.txLandRateLookbackWindowMinutes - Rolling window, in minutes, for the land-rate calculation.
+     * @param props.landRateToFeeFunc - Custom mapping from land rate to priority-fee multiplier.
+     * @param props.throwOnTimeoutError - Whether confirmation timeouts throw `TxSendError`; defaults to `true`.
+     */
     constructor({ connection, wallet, opts, timeout, blockhashRefreshInterval, additionalConnections, skipConfirmation, confirmInBackground, blockhashCommitment, confirmationStrategy, trackTxLandRate, txHandler, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError, }: {
         connection: Connection;
         wallet: IWallet;
@@ -36,7 +68,22 @@ export declare class FastSingleTxSender extends BaseTxSender {
         landRateToFeeFunc?: (landRate: number) => number;
         throwOnTimeoutError?: boolean;
     });
+    /**
+     * Starts a `setInterval` loop (if `blockhashRefreshInterval > 0`) that refreshes
+     * `this.recentBlockhash` every `blockhashRefreshInterval` ms. Fetch errors are logged and
+     * otherwise ignored (the loop keeps running with the stale cached value).
+     */
     startBlockhashRefreshLoop(): void;
+    /**
+     * Sends a raw transaction exactly once via `connection.sendRawTransaction` (plus a best-effort
+     * broadcast to `additionalConnections`), then confirms it unless `skipConfirmation` is set —
+     * awaited normally, or fired without awaiting if `confirmInBackground` is set (in which case
+     * the returned `slot` will be `undefined`, since it isn't known yet at return time).
+     * @param rawTransaction - Serialized, signed transaction bytes.
+     * @param opts - Options passed to `sendRawTransaction`/`confirmTransaction`; `opts.commitment` selects confirmation level.
+     * @returns The signature, and the confirmation slot if confirmation completed synchronously (`undefined` if `skipConfirmation` or `confirmInBackground` is set).
+     * @throws Whatever `connection.sendRawTransaction` or (if awaited) `confirmTransaction`/`checkConfirmationResultForError` throw.
+     */
     sendRawTransaction(rawTransaction: Buffer | Uint8Array, opts: ConfirmOptions): Promise<TxSigAndSlot>;
 }
 //# sourceMappingURL=fastSingleTxSender.d.ts.map

package/lib/node/tx/fastSingleTxSender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fastSingleTxSender.d.ts","sourceRoot":"","sources":["../../../src/tx/fastSingleTxSender.ts"],"names":[],"mappings":";;;AAAA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EACN,cAAc,EAEd,UAAU,EACV,UAAU,EACV,8BAA8B,EAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAMnC,qBAAa,kBAAmB,SAAQ,YAAY;IACnD,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,UAAU,EAAE,CAAC;IACpC,WAAW,SAAK;IAChB,eAAe,CAAC,EAAE,8BAA8B,CAAC;IACjD,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,mBAAmB,EAAE,UAAU,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC;gBAEhB,EAClB,UAAU,EACV,MAAM,EACN,IAAsD,EACtD,OAAyB,EACzB,wBAAoD,EACpD,qBAA+C,EAC/C,gBAAwB,EACxB,mBAA2B,EAC3B,mBAAiC,EACjC,oBAAiD,EACjD,eAAe,EACf,SAAS,EACT,+BAA+B,EAC/B,iBAAiB,EACjB,mBAA0B,GAC1B,EAAE;QACF,UAAU,EAAE,UAAU,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,qBAAqB,CAAC,EAAE,UAAU,EAAE,CAAC;QACrC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,mBAAmB,CAAC,EAAE,UAAU,CAAC;QACjC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;QAC5C,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,+BAA+B,CAAC,EAAE,MAAM,CAAC;QACzC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;QACjD,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC9B;IA0BD,yBAAyB,IAAI,IAAI;IAc3B,kBAAkB,CACvB,cAAc,EAAE,MAAM,GAAG,UAAU,EACnC,IAAI,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC;CAwCxB"}
+{"version":3,"file":"fastSingleTxSender.d.ts","sourceRoot":"","sources":["../../../src/tx/fastSingleTxSender.ts"],"names":[],"mappings":";;;AAAA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EACN,cAAc,EAEd,UAAU,EACV,UAAU,EACV,8BAA8B,EAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAMnC;;;;;;;;GAQG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IACnD,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,UAAU,EAAE,CAAC;IACpC,WAAW,SAAK;IAChB,8JAA8J;IAC9J,eAAe,CAAC,EAAE,8BAA8B,CAAC;IACjD,uHAAuH;IACvH,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iKAAiK;IACjK,mBAAmB,EAAE,OAAO,CAAC;IAC7B,+DAA+D;IAC/D,mBAAmB,EAAE,UAAU,CAAC;IAChC,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC;IAEnC;;;;;;;;;;;;;;;;OAgBG;gBACgB,EAClB,UAAU,EACV,MAAM,EACN,IAAsD,EACtD,OAAyB,EACzB,wBAAoD,EACpD,qBAA+C,EAC/C,gBAAwB,EACxB,mBAA2B,EAC3B,mBAAiC,EACjC,oBAAiD,EACjD,eAAe,EACf,SAAS,EACT,+BAA+B,EAC/B,iBAAiB,EACjB,mBAA0B,GAC1B,EAAE;QACF,UAAU,EAAE,UAAU,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,qBAAqB,CAAC,EAAE,UAAU,EAAE,CAAC;QACrC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,mBAAmB,CAAC,EAAE,UAAU,CAAC;QACjC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;QAC5C,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,+BAA+B,CAAC,EAAE,MAAM,CAAC;QACzC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;QACjD,mBAAmB,CAAC,EAAE,OAAO,CAAC;KAC9B;IA0BD;;;;OAIG;IACH,yBAAyB,IAAI,IAAI;IAcjC;;;;;;;;;OASG;IACG,kBAAkB,CACvB,cAAc,EAAE,MAAM,GAAG,UAAU,EACnC,IAAI,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC;CA+CxB"}

package/lib/node/tx/fastSingleTxSender.js

@@ -6,7 +6,33 @@ const baseTxSender_1 = require("./baseTxSender");
 const config_1 = require("../config");
 const DEFAULT_TIMEOUT = 35000;
 const DEFAULT_BLOCKHASH_REFRESH = 10000;
+/**
+ * `TxSender` optimized for low latency: sends a transaction exactly once (no resend/retry loop —
+ * relies on the RPC node's own forwarding), and can skip confirmation entirely or confirm
+ * asynchronously in the background so `sendRawTransaction` returns as soon as the send lands.
+ * Maintains its own periodically-refreshed blockhash cache (independent of `TxHandler`'s) purely
+ * for that background-refresh convenience; it is not actually consumed by `sendRawTransaction`
+ * here. Suited to latency-sensitive keeper bots that would rather fire-and-forget than pay for
+ * `RetryTxSender`'s resend loop.
+ */
 class FastSingleTxSender extends baseTxSender_1.BaseTxSender {
+    /**
+     * @param props.connection - RPC connection used for sending, confirming, and blockhash refresh.
+     * @param props.wallet - Wallet used to sign transactions that aren't already `preSigned`.
+     * @param props.opts - Default `ConfirmOptions`; defaults to `DEFAULT_CONFIRMATION_OPTS` with `maxRetries: 0` (this sender does not retry sends itself).
+     * @param props.timeout - Confirmation timeout in milliseconds; defaults to 35000 (35s).
+     * @param props.blockhashRefreshInterval - Interval (ms) for the background blockhash refresh; defaults to 10000 (10s). `0` disables it.
+     * @param props.additionalConnections - Extra connections to also broadcast raw transactions to.
+     * @param props.skipConfirmation - Skip confirmation entirely after sending; defaults to `false`.
+     * @param props.confirmInBackground - Confirm without awaiting, so `sendRawTransaction` resolves right after send; defaults to `false`.
+     * @param props.blockhashCommitment - Commitment for the background blockhash refresh; defaults to `'finalized'`.
+     * @param props.confirmationStrategy - How to wait for confirmation; defaults to `ConfirmationStrategy.Combo`.
+     * @param props.trackTxLandRate - Enables land-rate tracking.
+     * @param props.txHandler - Custom `TxHandler` for signing/building transactions.
+     * @param props.txLandRateLookbackWindowMinutes - Rolling window, in minutes, for the land-rate calculation.
+     * @param props.landRateToFeeFunc - Custom mapping from land rate to priority-fee multiplier.
+     * @param props.throwOnTimeoutError - Whether confirmation timeouts throw `TxSendError`; defaults to `true`.
+     */
     constructor({ connection, wallet, opts = { ...config_1.DEFAULT_CONFIRMATION_OPTS, maxRetries: 0 }, timeout = DEFAULT_TIMEOUT, blockhashRefreshInterval = DEFAULT_BLOCKHASH_REFRESH, additionalConnections = new Array(), skipConfirmation = false, confirmInBackground = false, blockhashCommitment = 'finalized', confirmationStrategy = types_1.ConfirmationStrategy.Combo, trackTxLandRate, txHandler, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError = true, }) {
         super({
             connection,
@@ -33,6 +59,11 @@ class FastSingleTxSender extends baseTxSender_1.BaseTxSender {
         this.blockhashCommitment = blockhashCommitment;
         this.startBlockhashRefreshLoop();
     }
+    /**
+     * Starts a `setInterval` loop (if `blockhashRefreshInterval > 0`) that refreshes
+     * `this.recentBlockhash` every `blockhashRefreshInterval` ms. Fetch errors are logged and
+     * otherwise ignored (the loop keeps running with the stale cached value).
+     */
     startBlockhashRefreshLoop() {
         if (this.blockhashRefreshInterval > 0) {
             this.blockhashIntervalId = setInterval(async () => {
@@ -45,6 +76,16 @@ class FastSingleTxSender extends baseTxSender_1.BaseTxSender {
             }, this.blockhashRefreshInterval);
         }
     }
+    /**
+     * Sends a raw transaction exactly once via `connection.sendRawTransaction` (plus a best-effort
+     * broadcast to `additionalConnections`), then confirms it unless `skipConfirmation` is set —
+     * awaited normally, or fired without awaiting if `confirmInBackground` is set (in which case
+     * the returned `slot` will be `undefined`, since it isn't known yet at return time).
+     * @param rawTransaction - Serialized, signed transaction bytes.
+     * @param opts - Options passed to `sendRawTransaction`/`confirmTransaction`; `opts.commitment` selects confirmation level.
+     * @returns The signature, and the confirmation slot if confirmation completed synchronously (`undefined` if `skipConfirmation` or `confirmInBackground` is set).
+     * @throws Whatever `connection.sendRawTransaction` or (if awaited) `confirmTransaction`/`checkConfirmationResultForError` throw.
+     */
     async sendRawTransaction(rawTransaction, opts) {
         var _a, _b;
         let txid;
@@ -61,13 +102,19 @@ class FastSingleTxSender extends baseTxSender_1.BaseTxSender {
         if (!this.skipConfirmation) {
             try {
                 if (this.confirmInBackground) {
-                    this.confirmTransaction(txid, opts.commitment).then(async (result) => {
+                    this.confirmTransaction(txid, opts.commitment)
+                        .then(async (result) => {
                         var _a;
                         (_a = this.txSigCache) === null || _a === void 0 ? void 0 : _a.set(txid, true);
                         if (result) {
                             await this.checkConfirmationResultForError(txid, result.value);
                             slot = result.context.slot;
                         }
+                    })
+                        .catch((err) => {
+                        // background confirmation is fire-and-forget; surface failures
+                        // in logs instead of as unhandled promise rejections
+                        console.error(`Error confirming transaction ${txid} in background:`, err);
                     });
                 }
                 else {