@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/tx/baseTxSender.ts

@@ -32,27 +32,60 @@ 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.
+ */
 export 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 = 0;
 	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;
 
 	// For landing rate calcs
+	/** 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 = 0;
 	lastPriorityFeeSuggestion = 1;
+	/** 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`.
+	 */
 	public constructor({
 		connection,
 		wallet,
@@ -110,6 +143,14 @@ export abstract class BaseTxSender implements TxSender {
 		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: Transaction,
 		additionalSigners?: Array<Signer>,
@@ -133,6 +174,14 @@ export abstract class BaseTxSender implements TxSender {
 		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: Transaction,
 		additionalSigners: Array<Signer>,
@@ -148,6 +197,16 @@ export abstract class BaseTxSender implements TxSender {
 		);
 	}
 
+	/**
+	 * 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: TransactionInstruction[],
 		lookupTableAccounts: AddressLookupTableAccount[],
@@ -163,6 +222,16 @@ export abstract class BaseTxSender implements TxSender {
 		);
 	}
 
+	/**
+	 * 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: VersionedTransaction,
 		additionalSigners?: Array<Signer>,
@@ -194,6 +263,12 @@ export abstract class BaseTxSender implements TxSender {
 		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: Buffer | Uint8Array,
@@ -203,7 +278,12 @@ export abstract class BaseTxSender implements TxSender {
 		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: VersionedTransaction): Promise<boolean> {
 		try {
 			const result = await this.connection.simulateTransaction(tx);
@@ -218,6 +298,18 @@ export abstract class BaseTxSender implements TxSender {
 		}
 	}
 
+	/**
+	 * 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: TransactionSignature,
 		commitment?: Commitment
@@ -239,7 +331,10 @@ export abstract class BaseTxSender implements TxSender {
 		let response: RpcResponseAndContext<SignatureResult> | null = null;
 		const promises = connections.map((connection, i) => {
 			let subscriptionId: number | undefined;
-			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,
@@ -254,7 +349,10 @@ export abstract class BaseTxSender implements TxSender {
 						subscriptionCommitment
 					);
 				} catch (err) {
-					reject(err);
+					console.error(
+						'confirmTransactionWebSocket: failed to set up onSignature listener',
+						err
+					);
 				}
 			});
 			subscriptionIds.push(subscriptionId);
@@ -304,6 +402,17 @@ export abstract class BaseTxSender implements TxSender {
 		return 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: TransactionSignature,
 		commitment: Commitment = 'finalized'
@@ -321,12 +430,24 @@ export abstract class BaseTxSender implements TxSender {
 
 			const signatureResult = rpcResponse && rpcResponse.value?.[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: Record<string, number> = {
+				processed: 0,
+				confirmed: 1,
+				finalized: 2,
+			};
 			if (
 				rpcResponse &&
 				signatureResult &&
-				signatureResult.confirmationStatus === commitment
+				signatureResult.confirmationStatus &&
+				statusRank[signatureResult.confirmationStatus] >=
+					(statusRank[commitment] ?? 2)
 			) {
-				return { context: rpcResponse.context, value: { err: null } };
+				return {
+					context: rpcResponse.context,
+					value: { err: signatureResult.err },
+				};
 			}
 
 			totalTime += backoffTime;
@@ -346,6 +467,14 @@ export abstract class BaseTxSender implements TxSender {
 		}
 	}
 
+	/**
+	 * 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: TransactionSignature,
 		commitment?: Commitment
@@ -360,10 +489,19 @@ export abstract class BaseTxSender implements TxSender {
 		}
 	}
 
+	/** Current time in milliseconds since epoch (thin wrapper over `Date.now()`, overridable in tests). */
 	getTimestamp(): number {
 		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<T>(
 		promises: Promise<T>[],
 		timeoutMs: number
@@ -381,6 +519,13 @@ export abstract class BaseTxSender implements TxSender {
 		);
 	}
 
+	/**
+	 * 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
@@ -399,6 +544,11 @@ export abstract class BaseTxSender implements TxSender {
 		});
 	}
 
+	/**
+	 * 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`.
+	 */
 	public addAdditionalConnection(newConnection: Connection): void {
 		const alreadyUsingConnection =
 			this.additionalConnections.filter((connection) => {
@@ -411,10 +561,21 @@ export abstract class BaseTxSender implements TxSender {
 		}
 	}
 
+	/** @returns The number of confirmation attempts that have timed out so far. */
 	public getTimeoutCount(): number {
 		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.
+	 */
 	public async checkConfirmationResultForError(
 		txSig: string,
 		result: SignatureResult
@@ -430,6 +591,12 @@ export abstract class BaseTxSender implements TxSender {
 		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.
+	 */
 	public getTxLandRate(): number {
 		if (!this.trackTxLandRate || !this.txSigCache) {
 			return this.txLandRate;
@@ -450,6 +617,14 @@ export abstract class BaseTxSender implements TxSender {
 		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.
+	 */
 	private defaultLandRateToFeeFunc(txLandRate: number) {
 		if (
 			txLandRate >= BASELINE_TX_LAND_RATE ||
@@ -462,6 +637,11 @@ export abstract class BaseTxSender implements TxSender {
 		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())`.
+	 */
 	public getSuggestedPriorityFeeMultiplier(): number {
 		if (!this.trackTxLandRate) {
 			return 1;

package/src/tx/blockhashFetcher/baseBlockhashFetcher.ts

@@ -5,12 +5,24 @@ import {
 } 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 class BaseBlockhashFetcher implements BlockhashFetcher {
+	/**
+	 * @param connection - RPC connection to fetch the blockhash from.
+	 * @param blockhashCommitment - Commitment level to request the blockhash at.
+	 */
 	constructor(
 		private connection: Connection,
 		private blockhashCommitment: Commitment
 	) {}
 
+	/**
+	 * @returns The latest blockhash and its expiry block height, fetched fresh from `connection`.
+	 */
 	public async getLatestBlockhash(): Promise<
 		BlockhashWithExpiryBlockHeight | undefined
 	> {

package/src/tx/blockhashFetcher/cachedBlockhashFetcher.ts

@@ -20,6 +20,13 @@ export class CachedBlockhashFetcher implements BlockhashFetcher {
 
 	private blockhashFetchingPromise: Promise<void> | null = null;
 
+	/**
+	 * @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(
 		private connection: Connection,
 		private blockhashCommitment: Commitment,
@@ -56,6 +63,14 @@ export class CachedBlockhashFetcher implements BlockhashFetcher {
 		};
 	}
 
+	/**
+	 * 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.
+	 */
 	public async getLatestBlockhash(): Promise<
 		BlockhashWithExpiryBlockHeight | undefined
 	> {

package/src/tx/blockhashFetcher/types.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>;
 }

package/src/tx/fastSingleTxSender.ts

@@ -14,20 +14,52 @@ import { DEFAULT_CONFIRMATION_OPTS } from '../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.
+ */
 export 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 = 0;
+	/** 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`.
+	 */
 	public constructor({
 		connection,
 		wallet,
@@ -86,6 +118,11 @@ export class FastSingleTxSender extends BaseTxSender {
 		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(): void {
 		if (this.blockhashRefreshInterval > 0) {
 			this.blockhashIntervalId = setInterval(async () => {
@@ -100,6 +137,16 @@ export class FastSingleTxSender extends BaseTxSender {
 		}
 	}
 
+	/**
+	 * 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: Buffer | Uint8Array,
 		opts: ConfirmOptions
@@ -118,15 +165,22 @@ export class FastSingleTxSender extends BaseTxSender {
 		if (!this.skipConfirmation) {
 			try {
 				if (this.confirmInBackground) {
-					this.confirmTransaction(txid, opts.commitment).then(
-						async (result) => {
+					this.confirmTransaction(txid, opts.commitment)
+						.then(async (result) => {
 							this.txSigCache?.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 {
 					const result = await this.confirmTransaction(txid, opts.commitment);
 					this.txSigCache?.set(txid, true);

package/src/tx/forwardOnlyTxSender.ts

@@ -17,6 +17,18 @@ 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 class ForwardOnlyTxSender extends BaseTxSender {
 	connection: Connection;
 	wallet: IWallet;
@@ -26,6 +38,20 @@ export class ForwardOnlyTxSender extends BaseTxSender {
 	additionalConnections: Connection[];
 	timoutCount = 0;
 
+	/**
+	 * @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`.
+	 */
 	public constructor({
 		connection,
 		wallet,
@@ -75,6 +101,11 @@ export class ForwardOnlyTxSender extends BaseTxSender {
 		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: ResolveReference): Promise<void> {
 		return new Promise((resolve) => {
 			reference.resolve = resolve;
@@ -82,6 +113,13 @@ export class ForwardOnlyTxSender extends BaseTxSender {
 		});
 	}
 
+	/**
+	 * 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
@@ -91,6 +129,16 @@ export class ForwardOnlyTxSender extends BaseTxSender {
 		});
 	}
 
+	/**
+	 * "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: Buffer | Uint8Array,
 		opts: ConfirmOptions

package/src/tx/reportTransactionError.ts

@@ -86,9 +86,11 @@ const getTransactionResultWithRetry = async (
  * 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 const throwTransactionError = async (
 	txSig: string,
@@ -108,9 +110,12 @@ export const throwTransactionError = async (
  * 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 const getTransactionErrorFromTxSig = async (
 	txSig: string,
@@ -140,6 +145,13 @@ export const getTransactionErrorFromTxSig = async (
 	return getTransactionError(transactionResult);
 };
 
+/**
+ * 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 const getTransactionError = (
 	transactionResult: VersionedTransactionResponse
 ): SendTransactionError | undefined => {