@velocity-exchange/sdk 0.3.0 → 0.6.0

package/lib/browser/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/browser/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/browser/tx/blockhashFetcher/types.d.ts

@@ -1,4 +1,8 @@
 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>;
 }

package/lib/browser/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,6 +68,21 @@ 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>;
 }

package/lib/browser/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 {

package/lib/browser/tx/forwardOnlyTxSender.d.ts

@@ -8,6 +8,18 @@ import { IWallet } from '../types';
 type ResolveReference = {
     resolve?: () => void;
 };
+/**
+ * `TxSender` that never calls `connection.sendRawTransaction` itself — instead it hands the raw
+ * transaction to `additionalTxSenderCallbacks` (e.g. a Jito/third-party bundle submitter) and
+ * re-invokes those callbacks on a `retrySleep` interval until the transaction confirms or
+ * `timeout` elapses. `connection` is used only to *confirm* the transaction (via
+ * `BaseTxSender.confirmTransaction`), never to broadcast it. `additionalConnections` is always
+ * empty for this sender (the constructor doesn't accept it) since forwarding goes exclusively
+ * through the callbacks.
+ *
+ * Use this when transaction submission is delegated to an external forwarder/relay rather than
+ * this RPC connection, but you still want this SDK's confirmation/retry/land-rate machinery.
+ */
 export declare class ForwardOnlyTxSender extends BaseTxSender {
     connection: Connection;
     wallet: IWallet;
@@ -16,6 +28,20 @@ export declare class ForwardOnlyTxSender extends BaseTxSender {
     retrySleep: number;
     additionalConnections: Connection[];
     timoutCount: number;
+    /**
+     * @param props.connection - RPC connection used only for confirmation, never for sending.
+     * @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` (retries are handled by this sender's own re-forward loop, not the RPC node).
+     * @param props.timeout - Total time (ms) to keep re-forwarding and waiting for confirmation before giving up; defaults to 35000 (35s).
+     * @param props.retrySleep - Interval (ms) between re-invocations of `additionalTxSenderCallbacks`; defaults to 5000 (5s).
+     * @param props.confirmationStrategy - How to wait for confirmation; defaults to `ConfirmationStrategy.Combo`.
+     * @param props.additionalTxSenderCallbacks - Callbacks that actually submit the transaction (e.g. to a relay/bundler); required for this sender to do anything, since it never calls `sendRawTransaction` on `connection` itself. Defaults to an empty array (transaction is never actually broadcast anywhere).
+     * @param props.txHandler - Custom `TxHandler` for signing/building transactions.
+     * @param props.trackTxLandRate - Enables land-rate tracking.
+     * @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, retrySleep, confirmationStrategy, additionalTxSenderCallbacks, txHandler, trackTxLandRate, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError, }: {
         connection: Connection;
         wallet: IWallet;
@@ -30,8 +56,30 @@ export declare class ForwardOnlyTxSender extends BaseTxSender {
         landRateToFeeFunc?: (landRate: number) => number;
         throwOnTimeoutError?: boolean;
     });
+    /**
+     * Waits `retrySleep` milliseconds, exposing an early-wake `resolve` via `reference` so
+     * `sendRawTransaction`'s stop condition can cut the wait short once the transaction confirms.
+     * @param reference - Mutable holder `sendRawTransaction` uses to resolve this sleep early.
+     */
     sleep(reference: ResolveReference): Promise<void>;
+    /**
+     * Overrides `BaseTxSender.sendToAdditionalConnections` to skip `additionalConnections`
+     * entirely (always empty for this sender) and only invoke `additionalTxSenderCallbacks` with
+     * the base58-encoded transaction — this is this sender's *only* transaction submission path.
+     * @param rawTx - Serialized, signed transaction bytes.
+     * @param _opts - Unused (kept for `BaseTxSender` override compatibility).
+     */
     sendToAdditionalConnections(rawTx: Buffer | Uint8Array, _opts: ConfirmOptions): void;
+    /**
+     * "Sends" a raw transaction by repeatedly invoking `additionalTxSenderCallbacks` with it every
+     * `retrySleep` ms (never calling `connection.sendRawTransaction`) while concurrently waiting
+     * for confirmation via `confirmTransaction`. Re-forwarding stops as soon as confirmation
+     * resolves (successfully or by throwing) or `timeout` elapses.
+     * @param rawTransaction - Serialized, signed transaction bytes (must deserialize as a `VersionedTransaction`).
+     * @param opts - Confirmation options; `opts.commitment` is used for confirmation.
+     * @returns The signature and confirmation slot once confirmed.
+     * @throws Whatever `confirmTransaction` throws (e.g. `TxSendError` on timeout, or the resolved on-chain error).
+     */
     sendRawTransaction(rawTransaction: Buffer | Uint8Array, opts: ConfirmOptions): Promise<TxSigAndSlot>;
 }
 export {};

package/lib/browser/tx/forwardOnlyTxSender.js

@@ -11,7 +11,33 @@ const types_1 = require("./types");
 const config_1 = require("../config");
 const DEFAULT_TIMEOUT = 35000;
 const DEFAULT_RETRY = 5000;
+/**
+ * `TxSender` that never calls `connection.sendRawTransaction` itself — instead it hands the raw
+ * transaction to `additionalTxSenderCallbacks` (e.g. a Jito/third-party bundle submitter) and
+ * re-invokes those callbacks on a `retrySleep` interval until the transaction confirms or
+ * `timeout` elapses. `connection` is used only to *confirm* the transaction (via
+ * `BaseTxSender.confirmTransaction`), never to broadcast it. `additionalConnections` is always
+ * empty for this sender (the constructor doesn't accept it) since forwarding goes exclusively
+ * through the callbacks.
+ *
+ * Use this when transaction submission is delegated to an external forwarder/relay rather than
+ * this RPC connection, but you still want this SDK's confirmation/retry/land-rate machinery.
+ */
 class ForwardOnlyTxSender extends baseTxSender_1.BaseTxSender {
+    /**
+     * @param props.connection - RPC connection used only for confirmation, never for sending.
+     * @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` (retries are handled by this sender's own re-forward loop, not the RPC node).
+     * @param props.timeout - Total time (ms) to keep re-forwarding and waiting for confirmation before giving up; defaults to 35000 (35s).
+     * @param props.retrySleep - Interval (ms) between re-invocations of `additionalTxSenderCallbacks`; defaults to 5000 (5s).
+     * @param props.confirmationStrategy - How to wait for confirmation; defaults to `ConfirmationStrategy.Combo`.
+     * @param props.additionalTxSenderCallbacks - Callbacks that actually submit the transaction (e.g. to a relay/bundler); required for this sender to do anything, since it never calls `sendRawTransaction` on `connection` itself. Defaults to an empty array (transaction is never actually broadcast anywhere).
+     * @param props.txHandler - Custom `TxHandler` for signing/building transactions.
+     * @param props.trackTxLandRate - Enables land-rate tracking.
+     * @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, retrySleep = DEFAULT_RETRY, confirmationStrategy = types_1.ConfirmationStrategy.Combo, additionalTxSenderCallbacks = [], txHandler, trackTxLandRate, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError = true, }) {
         super({
             connection,
@@ -35,18 +61,40 @@ class ForwardOnlyTxSender extends baseTxSender_1.BaseTxSender {
         this.retrySleep = retrySleep;
         this.additionalConnections = [];
     }
+    /**
+     * Waits `retrySleep` milliseconds, exposing an early-wake `resolve` via `reference` so
+     * `sendRawTransaction`'s stop condition can cut the wait short once the transaction confirms.
+     * @param reference - Mutable holder `sendRawTransaction` uses to resolve this sleep early.
+     */
     async sleep(reference) {
         return new Promise((resolve) => {
             reference.resolve = resolve;
             setTimeout(resolve, this.retrySleep);
         });
     }
+    /**
+     * Overrides `BaseTxSender.sendToAdditionalConnections` to skip `additionalConnections`
+     * entirely (always empty for this sender) and only invoke `additionalTxSenderCallbacks` with
+     * the base58-encoded transaction — this is this sender's *only* transaction submission path.
+     * @param rawTx - Serialized, signed transaction bytes.
+     * @param _opts - Unused (kept for `BaseTxSender` override compatibility).
+     */
     sendToAdditionalConnections(rawTx, _opts) {
         var _a;
         (_a = this.additionalTxSenderCallbacks) === null || _a === void 0 ? void 0 : _a.map((callback) => {
             callback(bs58_1.default.encode(rawTx));
         });
     }
+    /**
+     * "Sends" a raw transaction by repeatedly invoking `additionalTxSenderCallbacks` with it every
+     * `retrySleep` ms (never calling `connection.sendRawTransaction`) while concurrently waiting
+     * for confirmation via `confirmTransaction`. Re-forwarding stops as soon as confirmation
+     * resolves (successfully or by throwing) or `timeout` elapses.
+     * @param rawTransaction - Serialized, signed transaction bytes (must deserialize as a `VersionedTransaction`).
+     * @param opts - Confirmation options; `opts.commitment` is used for confirmation.
+     * @returns The signature and confirmation slot once confirmed.
+     * @throws Whatever `confirmTransaction` throws (e.g. `TxSendError` on timeout, or the resolved on-chain error).
+     */
     async sendRawTransaction(rawTransaction, opts) {
         var _a, _b, _c;
         const deserializedTx = web3_js_1.VersionedTransaction.deserialize(rawTransaction);

package/lib/browser/tx/reportTransactionError.d.ts

@@ -3,18 +3,30 @@ import { Commitment, Connection, SendTransactionError, VersionedTransactionRespo
  * THROWS if there is an error
  *
  * Should only be used for a txSig that is confirmed has an error. There is a race-condition where sometimes the transaction is not instantly available to fetch after the confirmation has already failed with an error, so this method has retry logic which we don't want to do wastefully. This method will throw a generic error if it can't get the transaction result after a retry period.
- * @param txSig
- * @param connection
- * @returns
+ * @param txSig - Signature of the transaction already known/confirmed to have failed.
+ * @param connection - RPC connection used to fetch the transaction (retried up to 3 times over ~3s).
+ * @param commitment - Commitment to fetch at; defaults to `connection.commitment`, then `DEFAULT_CONFIRMATION_OPTS.commitment`. Must resolve to `'confirmed'` or `'finalized'`.
+ * @returns Resolves with no value if no error could be extracted (should not normally happen for a known-failed signature).
+ * @throws SendTransactionError with the resolved on-chain error/logs — or a generic "Transaction Failed" error if the transaction result couldn't be fetched after retrying.
  */
 export declare const throwTransactionError: (txSig: string, connection: Connection, commitment?: Commitment) => Promise<void>;
 /**
  * RETURNS an error if there is one
  *
  * Should only be used for a txSig that is confirmed has an error. There is a race-condition where sometimes the transaction is not instantly available to fetch after the confirmation has already failed with an error, so this method has retry logic which we don't want to do wastefully. This method will throw a generic error if it can't get the transaction result after a retry period.
- * @param txSig
- * @param connection
- * @returns
+ * @param txSig - Signature of the transaction already known/confirmed to have failed.
+ * @param connection - RPC connection used to fetch the transaction (retried up to 3 times over ~3s).
+ * @param commitment - Commitment to fetch at; defaults to `connection.commitment`, then `DEFAULT_CONFIRMATION_OPTS.commitment`. Must resolve to `'confirmed'` or `'finalized'`.
+ * @returns The resolved `SendTransactionError` (with parsed logs/friendly message), a generic
+ * "Transaction Failed" `SendTransactionError` if the transaction couldn't be fetched after
+ * retrying, or `undefined` if the fetched transaction unexpectedly has no recorded error.
  */
 export declare const getTransactionErrorFromTxSig: (txSig: string, connection: Connection, commitment?: Commitment) => Promise<SendTransactionError | undefined>;
+/**
+ * Builds a `SendTransactionError` from an already-fetched transaction response, extracting a
+ * "friendly" message from the last log line (matching `failed: <message>`) when present.
+ * @param transactionResult - A fetched `VersionedTransactionResponse`.
+ * @returns A `SendTransactionError` populated with the signature, logs, and (if parseable) a
+ * friendly failure message, or `undefined` if `transactionResult.meta.err` is not set.
+ */
 export declare const getTransactionError: (transactionResult: VersionedTransactionResponse) => SendTransactionError | undefined;

package/lib/browser/tx/reportTransactionError.js

@@ -51,9 +51,11 @@ const getTransactionResultWithRetry = async (txSig, connection, commitment) => {
  * THROWS if there is an error
  *
  * Should only be used for a txSig that is confirmed has an error. There is a race-condition where sometimes the transaction is not instantly available to fetch after the confirmation has already failed with an error, so this method has retry logic which we don't want to do wastefully. This method will throw a generic error if it can't get the transaction result after a retry period.
- * @param txSig
- * @param connection
- * @returns
+ * @param txSig - Signature of the transaction already known/confirmed to have failed.
+ * @param connection - RPC connection used to fetch the transaction (retried up to 3 times over ~3s).
+ * @param commitment - Commitment to fetch at; defaults to `connection.commitment`, then `DEFAULT_CONFIRMATION_OPTS.commitment`. Must resolve to `'confirmed'` or `'finalized'`.
+ * @returns Resolves with no value if no error could be extracted (should not normally happen for a known-failed signature).
+ * @throws SendTransactionError with the resolved on-chain error/logs — or a generic "Transaction Failed" error if the transaction result couldn't be fetched after retrying.
  */
 const throwTransactionError = async (txSig, connection, commitment) => {
     const err = await (0, exports.getTransactionErrorFromTxSig)(txSig, connection, commitment);
@@ -67,9 +69,12 @@ exports.throwTransactionError = throwTransactionError;
  * RETURNS an error if there is one
  *
  * Should only be used for a txSig that is confirmed has an error. There is a race-condition where sometimes the transaction is not instantly available to fetch after the confirmation has already failed with an error, so this method has retry logic which we don't want to do wastefully. This method will throw a generic error if it can't get the transaction result after a retry period.
- * @param txSig
- * @param connection
- * @returns
+ * @param txSig - Signature of the transaction already known/confirmed to have failed.
+ * @param connection - RPC connection used to fetch the transaction (retried up to 3 times over ~3s).
+ * @param commitment - Commitment to fetch at; defaults to `connection.commitment`, then `DEFAULT_CONFIRMATION_OPTS.commitment`. Must resolve to `'confirmed'` or `'finalized'`.
+ * @returns The resolved `SendTransactionError` (with parsed logs/friendly message), a generic
+ * "Transaction Failed" `SendTransactionError` if the transaction couldn't be fetched after
+ * retrying, or `undefined` if the fetched transaction unexpectedly has no recorded error.
  */
 const getTransactionErrorFromTxSig = async (txSig, connection, commitment) => {
     var _a;
@@ -89,6 +94,13 @@ const getTransactionErrorFromTxSig = async (txSig, connection, commitment) => {
     return (0, exports.getTransactionError)(transactionResult);
 };
 exports.getTransactionErrorFromTxSig = getTransactionErrorFromTxSig;
+/**
+ * Builds a `SendTransactionError` from an already-fetched transaction response, extracting a
+ * "friendly" message from the last log line (matching `failed: <message>`) when present.
+ * @param transactionResult - A fetched `VersionedTransactionResponse`.
+ * @returns A `SendTransactionError` populated with the signature, logs, and (if parseable) a
+ * friendly failure message, or `undefined` if `transactionResult.meta.err` is not set.
+ */
 const getTransactionError = (transactionResult) => {
     var _a, _b, _c, _d, _e, _f;
     if (!((_a = transactionResult === null || transactionResult === void 0 ? void 0 : transactionResult.meta) === null || _a === void 0 ? void 0 : _a.err)) {

package/lib/browser/tx/retryTxSender.d.ts

@@ -8,14 +8,37 @@ import { IWallet } from '../types';
 type ResolveReference = {
     resolve?: () => void;
 };
+/**
+ * Default `TxSender` for most clients: sends a transaction once, then keeps resending the exact
+ * same signed bytes (to `connection` and every `additionalConnections` entry) every `retrySleep`
+ * ms until it confirms or `timeout` elapses. This is client-side resend, independent of the RPC
+ * node's own forwarding — useful when relying on rebroadcast to improve inclusion odds under
+ * congestion, at the cost of extra RPC load compared to `FastSingleTxSender`.
+ */
 export declare class RetryTxSender extends BaseTxSender {
     connection: Connection;
     wallet: IWallet;
     opts: ConfirmOptions;
     timeout: number;
+    /** Interval (ms) between resend attempts of the same signed transaction. */
     retrySleep: number;
     additionalConnections: Connection[];
     timoutCount: number;
+    /**
+     * @param props.connection - RPC connection used for sending, resending, and confirming.
+     * @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` (retries are handled by this sender's own resend loop, not the RPC node).
+     * @param props.timeout - Total time (ms) to keep resending and waiting for confirmation before giving up; defaults to 35000 (35s).
+     * @param props.retrySleep - Interval (ms) between resend attempts; defaults to 2000 (2s).
+     * @param props.additionalConnections - Extra connections to also (re)broadcast raw transactions to.
+     * @param props.confirmationStrategy - How to wait for confirmation; defaults to `ConfirmationStrategy.Combo`.
+     * @param props.additionalTxSenderCallbacks - Callbacks invoked with each (re)sent transaction's base58 encoding.
+     * @param props.txHandler - Custom `TxHandler` for signing/building transactions.
+     * @param props.trackTxLandRate - Enables land-rate tracking.
+     * @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, retrySleep, additionalConnections, confirmationStrategy, additionalTxSenderCallbacks, txHandler, trackTxLandRate, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError, }: {
         connection: Connection;
         wallet: IWallet;
@@ -31,7 +54,24 @@ export declare class RetryTxSender extends BaseTxSender {
         landRateToFeeFunc?: (landRate: number) => number;
         throwOnTimeoutError?: boolean;
     });
+    /**
+     * Waits `retrySleep` milliseconds, exposing an early-wake `resolve` via `reference` so the
+     * resend loop in `sendRawTransaction` can stop promptly once the transaction confirms or a
+     * resend fails.
+     * @param reference - Mutable holder `sendRawTransaction` uses to resolve this sleep early.
+     */
     sleep(reference: ResolveReference): Promise<void>;
+    /**
+     * Sends a raw transaction, then repeatedly resends the identical signed bytes to `connection`
+     * (and broadcasts to `additionalConnections`/`additionalTxSenderCallbacks`) every `retrySleep`
+     * ms while concurrently waiting for confirmation. The resend loop stops as soon as
+     * confirmation resolves, a resend attempt itself throws, or `timeout` elapses.
+     * @param rawTransaction - Serialized, signed transaction bytes.
+     * @param opts - Options passed to each send/resend and to confirmation; `opts.commitment` selects confirmation level.
+     * @returns The signature and confirmation slot once confirmed.
+     * @throws Whatever `confirmTransaction` or `checkConfirmationResultForError` throw (e.g.
+     * `TxSendError` on timeout, or the resolved on-chain error for a failed transaction).
+     */
     sendRawTransaction(rawTransaction: Buffer | Uint8Array, opts: ConfirmOptions): Promise<TxSigAndSlot>;
 }
 export {};

package/lib/browser/tx/retryTxSender.js

@@ -6,7 +6,29 @@ const baseTxSender_1 = require("./baseTxSender");
 const config_1 = require("../config");
 const DEFAULT_TIMEOUT = 35000;
 const DEFAULT_RETRY = 2000;
+/**
+ * Default `TxSender` for most clients: sends a transaction once, then keeps resending the exact
+ * same signed bytes (to `connection` and every `additionalConnections` entry) every `retrySleep`
+ * ms until it confirms or `timeout` elapses. This is client-side resend, independent of the RPC
+ * node's own forwarding — useful when relying on rebroadcast to improve inclusion odds under
+ * congestion, at the cost of extra RPC load compared to `FastSingleTxSender`.
+ */
 class RetryTxSender extends baseTxSender_1.BaseTxSender {
+    /**
+     * @param props.connection - RPC connection used for sending, resending, and confirming.
+     * @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` (retries are handled by this sender's own resend loop, not the RPC node).
+     * @param props.timeout - Total time (ms) to keep resending and waiting for confirmation before giving up; defaults to 35000 (35s).
+     * @param props.retrySleep - Interval (ms) between resend attempts; defaults to 2000 (2s).
+     * @param props.additionalConnections - Extra connections to also (re)broadcast raw transactions to.
+     * @param props.confirmationStrategy - How to wait for confirmation; defaults to `ConfirmationStrategy.Combo`.
+     * @param props.additionalTxSenderCallbacks - Callbacks invoked with each (re)sent transaction's base58 encoding.
+     * @param props.txHandler - Custom `TxHandler` for signing/building transactions.
+     * @param props.trackTxLandRate - Enables land-rate tracking.
+     * @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, retrySleep = DEFAULT_RETRY, additionalConnections = new Array(), confirmationStrategy = types_1.ConfirmationStrategy.Combo, additionalTxSenderCallbacks = [], txHandler, trackTxLandRate, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError = true, }) {
         super({
             connection,
@@ -30,12 +52,29 @@ class RetryTxSender extends baseTxSender_1.BaseTxSender {
         this.retrySleep = retrySleep;
         this.additionalConnections = additionalConnections;
     }
+    /**
+     * Waits `retrySleep` milliseconds, exposing an early-wake `resolve` via `reference` so the
+     * resend loop in `sendRawTransaction` can stop promptly once the transaction confirms or a
+     * resend fails.
+     * @param reference - Mutable holder `sendRawTransaction` uses to resolve this sleep early.
+     */
     async sleep(reference) {
         return new Promise((resolve) => {
             reference.resolve = resolve;
             setTimeout(resolve, this.retrySleep);
         });
     }
+    /**
+     * Sends a raw transaction, then repeatedly resends the identical signed bytes to `connection`
+     * (and broadcasts to `additionalConnections`/`additionalTxSenderCallbacks`) every `retrySleep`
+     * ms while concurrently waiting for confirmation. The resend loop stops as soon as
+     * confirmation resolves, a resend attempt itself throws, or `timeout` elapses.
+     * @param rawTransaction - Serialized, signed transaction bytes.
+     * @param opts - Options passed to each send/resend and to confirmation; `opts.commitment` selects confirmation level.
+     * @returns The signature and confirmation slot once confirmed.
+     * @throws Whatever `confirmTransaction` or `checkConfirmationResultForError` throw (e.g.
+     * `TxSendError` on timeout, or the resolved on-chain error for a failed transaction).
+     */
     async sendRawTransaction(rawTransaction, opts) {
         var _a, _b, _c;
         const startTime = this.getTimestamp();