@velocity-exchange/sdk 0.3.0 → 0.4.0

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

@@ -5,24 +5,57 @@ import { Commitment, ConfirmOptions, RpcResponseAndContext, Signer, SignatureRes
 import { TxHandler } from './txHandler';
 import { IWallet } from '../types';
 import NodeCache from 'node-cache';
+/**
+ * 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.
+ */
 export declare abstract class BaseTxSender implements TxSender {
     connection: Connection;
     wallet: IWallet;
     opts: ConfirmOptions;
+    /** Confirmation timeout in milliseconds, applied to both websocket and polling confirmation. */
     timeout: number;
+    /** Extra RPC connections a raw transaction is also broadcast to (best-effort, errors logged not thrown), for redundancy. */
     additionalConnections: Connection[];
+    /** Count of `confirmTransactionWebSocket`/`confirmTransactionPolling` calls that hit `timeout` without a definitive result. */
     timeoutCount: number;
     confirmationStrategy: ConfirmationStrategy;
+    /** Callbacks invoked with the base58-encoded raw transaction alongside `additionalConnections` broadcasts, e.g. for logging/mempool submission. */
     additionalTxSenderCallbacks?: ((base58EncodedTx: string) => void)[];
     txHandler: TxHandler;
+    /** Whether to record each sent signature (via `txSigCache`) to compute `getTxLandRate()`. */
     trackTxLandRate?: boolean;
+    /** Whether `confirmTransactionWebSocket`/`confirmTransactionPolling` throw `TxSendError` on timeout (`true`) or return `undefined` (`false`). */
     throwOnTimeoutError: boolean;
+    /** Whether `checkConfirmationResultForError` throws the resolved on-chain error, or is a no-op. */
     throwOnTransactionError: boolean;
+    /** Lookback window, in seconds, over which `txSigCache` entries expire for the land-rate calculation. */
     lookbackWindowMinutes: number;
+    /** TTL cache of `txSig -> landed?` used to compute `getTxLandRate()` when `trackTxLandRate` is set. */
     txSigCache?: NodeCache;
     txLandRate: number;
     lastPriorityFeeSuggestion: number;
+    /** Maps a land rate (0-1) to a priority-fee multiplier; defaults to `defaultLandRateToFeeFunc`. */
     landRateToFeeFunc: (landRate: number) => number;
+    /**
+     * @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, timeout, additionalConnections, confirmationStrategy, additionalTxSenderCallbacks, trackTxLandRate, txHandler, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError, throwOnTransactionError, }: {
         connection: Connection;
         wallet: IWallet;
@@ -38,22 +71,152 @@ export declare abstract class BaseTxSender implements TxSender {
         throwOnTimeoutError?: boolean;
         throwOnTransactionError?: boolean;
     });
+    /**
+     * 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.
+     */
     send(tx: Transaction, additionalSigners?: Array<Signer>, opts?: ConfirmOptions, preSigned?: boolean): Promise<TxSigAndSlot>;
+    /**
+     * 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.
+     */
     prepareTx(tx: Transaction, additionalSigners: Array<Signer>, opts: ConfirmOptions, preSigned?: boolean): Promise<Transaction>;
+    /**
+     * 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).
+     */
     getVersionedTransaction(ixs: TransactionInstruction[], lookupTableAccounts: AddressLookupTableAccount[], _additionalSigners?: Array<Signer>, opts?: ConfirmOptions, blockhash?: BlockhashWithExpiryBlockHeight): Promise<VersionedTransaction>;
+    /**
+     * 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.
+     */
     sendVersionedTransaction(tx: VersionedTransaction, additionalSigners?: Array<Signer>, opts?: ConfirmOptions, preSigned?: boolean): Promise<TxSigAndSlot>;
+    /**
+     * 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.
+     */
     sendRawTransaction(rawTransaction: Buffer | Uint8Array, opts: ConfirmOptions): Promise<TxSigAndSlot>;
+    /**
+     * 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.
+     */
     simulateTransaction(tx: VersionedTransaction): Promise<boolean>;
+    /**
+     * 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.
+     */
     confirmTransactionWebSocket(signature: TransactionSignature, commitment?: Commitment): Promise<RpcResponseAndContext<SignatureResult> | 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.
+     */
     confirmTransactionPolling(signature: TransactionSignature, commitment?: Commitment): Promise<RpcResponseAndContext<SignatureResult> | undefined>;
+    /**
+     * 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`).
+     */
     confirmTransaction(signature: TransactionSignature, commitment?: Commitment): Promise<RpcResponseAndContext<SignatureResult> | undefined>;
+    /** Current time in milliseconds since epoch (thin wrapper over `Date.now()`, overridable in tests). */
     getTimestamp(): number;
+    /**
+     * 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<T>(promises: Promise<T>[], timeoutMs: number): Promise<T | null>;
+    /**
+     * 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: Buffer | Uint8Array, opts: ConfirmOptions): void;
+    /**
+     * 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: Connection): void;
+    /** @returns The number of confirmation attempts that have timed out so far. */
     getTimeoutCount(): number;
+    /**
+     * 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.
+     */
     checkConfirmationResultForError(txSig: string, result: SignatureResult): Promise<void>;
+    /**
+     * 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(): number;
+    /**
+     * 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.
+     */
     private defaultLandRateToFeeFunc;
+    /**
+     * 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(): number;
 }

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

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

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