@velocity-exchange/sdk 0.3.0 → 0.4.0

package/src/tx/retryTxSender.ts

@@ -12,15 +12,38 @@ 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 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 = 0;
 
+	/**
+	 * @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`.
+	 */
 	public constructor({
 		connection,
 		wallet,
@@ -72,6 +95,12 @@ export class RetryTxSender extends BaseTxSender {
 		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: ResolveReference): Promise<void> {
 		return new Promise((resolve) => {
 			reference.resolve = resolve;
@@ -79,6 +108,17 @@ export class RetryTxSender extends BaseTxSender {
 		});
 	}
 
+	/**
+	 * 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: Buffer | Uint8Array,
 		opts: ConfirmOptions

package/src/tx/txHandler.ts

@@ -63,32 +63,48 @@ const BLOCKHASH_FETCH_RETRY_COUNT = 3;
 const BLOCKHASH_FETCH_RETRY_SLEEP = 200;
 const RECENT_BLOCKHASH_STALE_TIME_MS = 2_000; // Reuse blockhashes within this timeframe during bursts of tx contruction
 
+/** Inputs to `TxHandler.buildTransaction`/`buildBulkTransactions` describing what to build and how. */
 export type TxBuildingProps = {
 	instructions: TransactionInstruction | TransactionInstruction[];
+	/** `'legacy'` for a legacy `Transaction`, or `0` for a v0 `VersionedTransaction`. */
 	txVersion: TransactionVersion;
 	connection: Connection;
+	/** Commitment used when building/signing multiple legacy transactions via `getPreparedAndSignedLegacyTransactionMap`. */
 	preFlightCommitment?: Commitment;
+	/** Supplies the market address lookup tables to merge with `lookupTables` for a v0 transaction. */
 	fetchAllMarketLookupTableAccounts: () => Promise<AddressLookupTableAccount[]>;
+	/** Extra address lookup tables to compile the message against, in addition to the market ones from `fetchAllMarketLookupTableAccounts`. */
 	lookupTables?: AddressLookupTableAccount[];
+	/** If `true`, return a `VersionedTransaction` even when `txVersion === 'legacy'` (wraps the legacy message in a versioned envelope). */
 	forceVersionedTransaction?: boolean;
+	/** Compute-unit limit/price and simulation-based sizing options for this transaction. */
 	txParams?: TxParams;
+	/** Blockhash to use; if omitted, one is resolved via `TxHandler`'s `BlockhashFetcher`. */
 	recentBlockhash?: BlockhashWithExpiryBlockHeight;
 	wallet?: IWallet;
 	optionalIxs?: TransactionInstruction[]; // additional instructions to add to the front of ixs if there's enough room, such as oracle cranks
 	simulatedTx?: SimulatedTransactionResponse; // we could have pre-simulated the tx and we can use this later to get compute units
 };
 
+/** Configuration for `TxHandler`'s blockhash-fetching strategy. */
 export type TxHandlerConfig = {
+	/** If `true`, use a `CachedBlockhashFetcher` (reduces RPC calls during bursts of tx construction); otherwise fetch fresh every time via `BaseBlockhashFetcher`. */
 	blockhashCachingEnabled?: boolean;
+	/** Tuning for `CachedBlockhashFetcher` when `blockhashCachingEnabled` is `true`; each field defaults if omitted (see `BLOCKHASH_FETCH_RETRY_COUNT`/`BLOCKHASH_FETCH_RETRY_SLEEP`/`RECENT_BLOCKHASH_STALE_TIME_MS`). */
 	blockhashCachingConfig?: {
-		retryCount: number;
-		retrySleepTimeMs: number;
-		staleCacheTimeMs: number;
+		retryCount?: number;
+		retrySleepTimeMs?: number;
+		staleCacheTimeMs?: number;
 	};
 };
 
 /**
  * This class is responsible for creating and signing transactions.
+ *
+ * Owns blockhash resolution (via a `BlockhashFetcher`, optionally caching), compute-budget
+ * instruction injection, address-lookup-table compilation, and wallet signing for both legacy and
+ * v0 transactions, single or batched. `TxSender` implementations delegate to a `TxHandler`
+ * instance for all of this rather than duplicating it.
  */
 export class TxHandler {
 	private blockHashToLastValidBlockHeightLookup: Record<string, number> = {};
@@ -107,6 +123,16 @@ export class TxHandler {
 		DEFAULT_CONFIRMATION_OPTS.commitment ?? 'confirmed';
 	private blockHashFetcher: BlockhashFetcher;
 
+	/**
+	 * @param props.connection - RPC connection used for blockhash fetches and (indirectly) sends.
+	 * @param props.wallet - Default wallet used to sign transactions when a call doesn't pass its own.
+	 * @param props.confirmationOptions - Default confirm options; `preflightCommitment` (falling
+	 * back to `connection.commitment`, then `'confirmed'`) sets the commitment used for blockhash fetches.
+	 * @param props.opts.returnBlockHeightsWithSignedTxCallbackData - If `true`, `onSignedCb` receives each signed tx's `lastValidBlockHeight` alongside its signature/blockhash.
+	 * @param props.opts.onSignedCb - Callback invoked with signed-transaction metadata whenever this handler signs one or more transactions.
+	 * @param props.opts.preSignedCb - Callback invoked immediately before wallet signing occurs.
+	 * @param props.config - Blockhash-fetching strategy/tuning; see `TxHandlerConfig`.
+	 */
 	constructor(props: {
 		connection: Connection;
 		wallet: IWallet;
@@ -147,6 +173,7 @@ export class TxHandler {
 		this.preSignedCb = props.opts?.preSignedCb;
 	}
 
+	/** @returns The wallet this handler currently uses to sign transactions when a call doesn't pass its own. */
 	public getWallet() {
 		return this.wallet;
 	}
@@ -166,6 +193,10 @@ export class TxHandler {
 			ConfirmOptions,
 		];
 
+	/**
+	 * Swaps the default wallet used for subsequent signing calls that don't pass their own.
+	 * @param wallet - New default wallet.
+	 */
 	public updateWallet(wallet: IWallet) {
 		this.wallet = wallet;
 	}
@@ -175,7 +206,8 @@ export class TxHandler {
 	 *
 	 * https://www.helius.dev/blog/how-to-deal-with-blockhash-errors-on-solana#why-do-blockhash-errors-occur
 	 *
-	 * @returns
+	 * @returns The latest blockhash (via this handler's configured `BlockhashFetcher`) at the
+	 * commitment level resolved in the constructor, or `undefined` if unavailable.
 	 */
 	public async getLatestBlockhashForTransaction() {
 		return this.blockHashFetcher.getLatestBlockhash();
@@ -198,14 +230,18 @@ export class TxHandler {
 	}
 
 	/**
-	 * Applies recent blockhash and signs a given transaction
-	 * @param tx
-	 * @param additionalSigners
-	 * @param wallet
-	 * @param confirmationOpts
-	 * @param preSigned
-	 * @param recentBlockhash
-	 * @returns
+	 * Applies recent blockhash and signs a given transaction. Attaches an internal
+	 * `SIGNATURE_BLOCK_AND_EXPIRY` property (undocumented in the `Transaction` type, but read by
+	 * `WhileValidTxSender`) recording the blockhash/expiry used, so confirmation logic can know
+	 * when the transaction's blockhash has expired even for pre-built transactions.
+	 * @param tx - Transaction to prepare; mutated in place (feePayer, recentBlockhash, signature).
+	 * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+	 * @param wallet - Wallet to sign with; defaults to this handler's configured wallet.
+	 * @param confirmationOpts - Unused directly here (present for interface symmetry with other overloads).
+	 * @param preSigned - If `true`, return `tx` unchanged without touching blockhash/feePayer/signatures.
+	 * @param recentBlockhash - Blockhash to use; if omitted, resolved via `getLatestBlockhashForTransaction`.
+	 * @returns The prepared (and signed, unless `preSigned`) transaction.
+	 * @throws Error if no blockhash could be resolved.
 	 */
 	public async prepareTx(
 		tx: Transaction,
@@ -310,6 +346,16 @@ export class TxHandler {
 		return signedTx;
 	}
 
+	/**
+	 * Signs a `VersionedTransaction`, optionally overwriting its blockhash first.
+	 * @param tx - Transaction to sign; mutated in place.
+	 * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+	 * @param recentBlockhash - If provided, overwrites `tx.message.recentBlockhash` before signing
+	 * (and records it for `SIGNATURE_BLOCK_AND_EXPIRY` tracking); if omitted, the transaction's
+	 * existing blockhash is used as-is.
+	 * @param wallet - Wallet to sign with; defaults to this handler's configured wallet.
+	 * @returns The signed transaction.
+	 */
 	public async signVersionedTx(
 		tx: VersionedTransaction,
 		additionalSigners: Array<Signer>,
@@ -430,6 +476,15 @@ export class TxHandler {
 		return new VersionedTransaction(message);
 	}
 
+	/**
+	 * Builds an unsigned `VersionedTransaction` that wraps a *legacy* compiled message (no address
+	 * lookup tables) — used when `forceVersionedTransaction` is requested for a `'legacy'`
+	 * `txVersion`.
+	 * @param recentBlockhash - Blockhash to build the message with.
+	 * @param ixs - Instructions to include, in order.
+	 * @param wallet - Wallet whose pubkey becomes the fee payer; defaults to this handler's configured wallet.
+	 * @returns The unsigned `VersionedTransaction`.
+	 */
 	public generateLegacyVersionedTransaction(
 		recentBlockhash: BlockhashWithExpiryBlockHeight,
 		ixs: TransactionInstruction[],
@@ -451,6 +506,15 @@ export class TxHandler {
 		return tx;
 	}
 
+	/**
+	 * Builds an unsigned v0 `VersionedTransaction`, compiling its message against the given
+	 * address lookup tables.
+	 * @param recentBlockhash - Blockhash to build the message with.
+	 * @param ixs - Instructions to include, in order.
+	 * @param lookupTableAccounts - Address lookup tables to compile the message against.
+	 * @param wallet - Wallet whose pubkey becomes the fee payer; defaults to this handler's configured wallet.
+	 * @returns The unsigned `VersionedTransaction`.
+	 */
 	public generateVersionedTransaction(
 		recentBlockhash: BlockhashWithExpiryBlockHeight,
 		ixs: TransactionInstruction[],
@@ -473,6 +537,13 @@ export class TxHandler {
 		return tx;
 	}
 
+	/**
+	 * Builds an unsigned legacy `Transaction` from raw instructions. Unlike the other `generate*`
+	 * methods, this does not set a fee payer.
+	 * @param ixs - Instructions to include, in order.
+	 * @param recentBlockhash - If provided, sets `tx.recentBlockhash`; otherwise left unset.
+	 * @returns The unsigned `Transaction`.
+	 */
 	public generateLegacyTransaction(
 		ixs: TransactionInstruction[],
 		recentBlockhash?: BlockhashWithExpiryBlockHeight
@@ -486,8 +557,10 @@ export class TxHandler {
 
 	/**
 	 * Accepts multiple instructions and builds a transaction for each. Prevents needing to spam RPC with requests for the same blockhash.
-	 * @param props
-	 * @returns
+	 * @param props - Shared `TxBuildingProps` (minus `instructions`) plus one instruction/array
+	 * per output transaction; a falsy entry in `props.instructions` yields `undefined` at that
+	 * position rather than being built.
+	 * @returns One built transaction (or `undefined`) per entry in `props.instructions`, in the same order.
 	 */
 	public async buildBulkTransactions(
 		props: Omit<TxBuildingProps, 'instructions'> & {
@@ -511,13 +584,16 @@ export class TxHandler {
 	}
 
 	/**
-	 *
-	 * @param instructions
-	 * @param txParams
-	 * @param txVersion
-	 * @param lookupTables
-	 * @param forceVersionedTransaction Return a VersionedTransaction instance even if the version of the transaction is Legacy
-	 * @returns
+	 * Builds a full transaction from raw instructions: merges caller-supplied `lookupTables` with
+	 * the market lookup tables from `fetchAllMarketLookupTableAccounts`, optionally appends as many
+	 * `optionalIxs` (e.g. oracle cranks) as fit under `MAX_TX_BYTE_SIZE` (dropped one-by-one and
+	 * re-simulated if the batch fails simulation), resolves compute-unit limit/price (via
+	 * simulation if `txParams.useSimulatedComputeUnits`), and prepends the resulting
+	 * `ComputeBudgetProgram` instructions unless the caller's instructions already include them.
+	 * @param props - See `TxBuildingProps`. `props.forceVersionedTransaction` returns a
+	 * `VersionedTransaction` instance even if `props.txVersion` is `'legacy'`.
+	 * @returns The built transaction — a `Transaction` for `txVersion === 'legacy'` unless
+	 * `forceVersionedTransaction` is set, otherwise a `VersionedTransaction`. Not yet signed.
 	 */
 	public async buildTransaction(
 		props: TxBuildingProps
@@ -648,6 +724,17 @@ export class TxHandler {
 		}
 	}
 
+	/**
+	 * Wraps a single instruction in a legacy `Transaction`, prepending compute-budget instructions
+	 * as needed. Does not set a blockhash or fee payer.
+	 * @param instruction - Instruction to wrap.
+	 * @param computeUnits - Compute unit limit; defaults to 600,000. A `setComputeUnitLimit`
+	 * instruction is added unless this value equals `COMPUTE_UNITS_DEFAULT` (200,000) exactly —
+	 * note the 600,000 default therefore *does* add one.
+	 * @param computeUnitsPrice - Compute unit price in micro-lamports; defaults to 0, in which case
+	 * no `setComputeUnitPrice` instruction is added.
+	 * @returns The unsigned `Transaction`.
+	 */
 	public wrapInTx(
 		instruction: TransactionInstruction,
 		computeUnits = 600_000,
@@ -681,11 +768,12 @@ export class TxHandler {
 
 	/**
 	 * Get a map of signed and prepared transactions from an array of legacy transactions
-	 * @param txsToSign
-	 * @param keys
-	 * @param wallet
-	 * @param commitment
-	 * @returns
+	 * @param txsMap - Map of key to legacy `Transaction` (or `undefined`, passed through unset); each is mutated with blockhash/feePayer before signing.
+	 * @param wallet - Wallet to sign with; defaults to this handler's configured wallet.
+	 * @param commitment - Unused directly here (accepted for interface symmetry with `TxSender.send`-style callers).
+	 * @param recentBlockhash - Blockhash to apply to every transaction in `txsMap`; if omitted, resolved via `getLatestBlockhashForTransaction`.
+	 * @returns `{ signedTxMap, signedTxData }` — see `getSignedTransactionMap`.
+	 * @throws Error if no blockhash could be resolved.
 	 */
 	public async getPreparedAndSignedLegacyTransactionMap<
 		T extends Record<string, Transaction | undefined>,
@@ -714,11 +802,16 @@ export class TxHandler {
 	}
 
 	/**
-	 * Get a map of signed transactions from an array of transactions to sign.
-	 * @param txsToSign
-	 * @param keys
-	 * @param wallet
-	 * @returns
+	 * Get a map of signed transactions from an array of transactions to sign. Signs all non-`undefined`
+	 * entries in a single `wallet.signAllTransactions` batch (one wallet approval for the whole map,
+	 * where the wallet supports it) rather than one signature request per transaction.
+	 * @param txsToSignMap - Map of key to `Transaction`/`VersionedTransaction` (or `undefined`,
+	 * passed through as `undefined` in the result rather than being signed).
+	 * @param wallet - Wallet to sign with; defaults to this handler's configured wallet.
+	 * @returns `signedTxMap` — same keys as the input, with each defined entry replaced by its
+	 * signed transaction; and `signedTxData` — the per-transaction signature/blockhash metadata
+	 * (with `lastValidBlockHeight` if this handler was configured with
+	 * `returnBlockHeightsWithSignedTxCallbackData`), also passed to `onSignedCb` if configured.
 	 */
 	public async getSignedTransactionMap<
 		T extends Record<string, Transaction | VersionedTransaction | undefined>,
@@ -788,8 +881,8 @@ export class TxHandler {
 
 	/**
 	 * Accepts multiple instructions and builds a transaction for each. Prevents needing to spam RPC with requests for the same blockhash.
-	 * @param props
-	 * @returns
+	 * @param props - Shared `TxBuildingProps` (minus `instructions`) plus a named map of instruction(s) per output transaction.
+	 * @returns A map with the same keys as `props.instructionsMap`, each value the corresponding built transaction.
 	 */
 	public async buildTransactionsMap<
 		T extends Record<string, TransactionInstruction | TransactionInstruction[]>,
@@ -814,8 +907,11 @@ export class TxHandler {
 
 	/**
 	 * Builds and signs transactions from a given array of instructions for multiple transactions.
-	 * @param props
-	 * @returns
+	 * Builds every transaction first (`buildTransactionsMap`), then signs them all in one batch —
+	 * via `getPreparedAndSignedLegacyTransactionMap` for `'legacy'` `txVersion`, otherwise
+	 * `getSignedTransactionMap`.
+	 * @param props - Shared `TxBuildingProps` (minus `instructions`) plus a named map of instruction(s) per output transaction.
+	 * @returns `{ signedTxMap, signedTxData }` keyed the same as `props.instructionsMap`; see `getSignedTransactionMap`.
 	 */
 	public async buildAndSignTransactionMap<
 		T extends Record<string, TransactionInstruction | TransactionInstruction[]>,
@@ -837,6 +933,21 @@ export class TxHandler {
 		return preppedTransactions;
 	}
 
+	/**
+	 * Greedily includes as many `optionalInstructions` (e.g. oracle-crank instructions) as fit
+	 * alongside `txBuildingProps.instructions` under `MAX_TX_BYTE_SIZE`, then simulates the result;
+	 * if simulation fails, falls back to simulating with only the base instructions (optional ones
+	 * dropped entirely) rather than trying to isolate which optional instruction caused the failure.
+	 * @param txBuildingProps - Build props whose `instructions` are the required (non-optional) instructions.
+	 * @param optionalInstructions - Extra instructions to include only if they fit; prepended
+	 * ahead of the base instructions and trimmed one-by-one from the front if the combined size
+	 * exceeds `MAX_TX_BYTE_SIZE`. Defaults to none, in which case this is a no-op passthrough.
+	 * @param versionedTransaction - Whether to size the candidate transaction as versioned (v0) or legacy; defaults to `true`.
+	 * @param addressLookupTables - Lookup tables credited toward the size calculation; defaults to none.
+	 * @returns A tuple of `[instructionsActuallyUsed, simulationResult]` — `instructionsActuallyUsed`
+	 * includes the optional instructions only if the combined simulation succeeded; `simulationResult`
+	 * is `undefined` only when `optionalInstructions` was empty (no simulation was needed).
+	 */
 	public async simulateAndCalculateInstructions(
 		txBuildingProps: TxBuildingProps,
 		optionalInstructions: TransactionInstruction[] = [],

package/src/tx/txParamProcessor.ts

@@ -17,6 +17,10 @@ type TransactionBuildingProps = {
 
 /**
  * This class is responsible for running through a "processing" pipeline for a base transaction, to adjust the standard transaction parameters based on a given configuration.
+ *
+ * Currently the only pipeline step is simulation-based compute unit resolution: build the
+ * transaction with a max compute-unit budget, simulate it, and replace the compute-unit limit
+ * (and optionally the compute-unit price) with values derived from actual simulated usage.
  */
 export class TransactionParamProcessor {
 	private static async getComputeUnitsFromSim(
@@ -29,6 +33,24 @@ export class TransactionParamProcessor {
 		return undefined;
 	}
 
+	/**
+	 * Determines a compute-unit limit to use for a transaction by simulating it (or reusing a
+	 * pre-supplied simulation), applying `bufferMultiplier` to the actually-consumed units, and
+	 * clamping the result to at most `MAX_COMPUTE_UNITS` (1,400,000). Simulation runs with
+	 * `replaceRecentBlockhash: true` to avoid spurious `blockHashNotFound` failures from an
+	 * already-stale blockhash on the transaction being sized. Never throws: any error (including
+	 * a simulation error result) is caught and reported via the `success: false` return.
+	 * @param tx - Transaction to simulate (ignored if `simulatedTx` is supplied instead).
+	 * @param connection - RPC connection used to simulate, if `simulatedTx` isn't provided.
+	 * @param bufferMultiplier - Multiplier applied to the raw consumed compute units before
+	 * clamping (e.g. `1.2` for a 20% buffer) — mandatory to force callers to account for
+	 * simulated CU counts being an imperfect predictor of the real on-chain cost.
+	 * @param lowerBoundCu - If provided, the result is floored at `min(lowerBoundCu, MAX_COMPUTE_UNITS)`.
+	 * @param simulatedTx - A pre-computed simulation result to reuse instead of simulating `tx` again.
+	 * @returns `{ success: true, computeUnits }` with the buffered/clamped compute-unit limit on
+	 * success, or `{ success: false, computeUnits: undefined }` if simulation failed or returned no
+	 * `unitsConsumed`.
+	 */
 	public static async getTxSimComputeUnits(
 		tx: VersionedTransaction,
 		connection: Connection,
@@ -93,6 +115,31 @@ export class TransactionParamProcessor {
 		}
 	}
 
+	/**
+	 * Runs the configured processing steps against a base set of tx params and returns the
+	 * adjusted params. If `processConfig` is empty/absent, returns `baseTxParams` unchanged
+	 * without building or simulating anything.
+	 *
+	 * When `processConfig.useSimulatedComputeUnits` is set: rebuilds the transaction (via
+	 * `txBuilder`) with `computeUnits` forced to `MAX_COMPUTE_UNITS` so simulation isn't
+	 * constrained by an under-sized limit, simulates it, and — on success — replaces
+	 * `computeUnits` with the result of `getTxSimComputeUnits` (failure leaves the original
+	 * `baseTxParams.computeUnits` untouched, it does not throw).
+	 *
+	 * When additionally `processConfig.useSimulatedComputeUnitsForCUPriceCalculation` is set:
+	 * derives `computeUnitsPrice` from the simulated `computeUnits` via
+	 * `processConfig.getCUPriceFromComputeUnits`.
+	 * @param props.baseTxParams - Starting compute-unit limit/price to adjust.
+	 * @param props.processConfig - Which processing steps to run (see `ProcessingTxParams`).
+	 * @param props.processParams.connection - RPC connection used for simulation.
+	 * @param props.processParams.simulatedTx - Pre-computed simulation result to reuse instead of simulating again.
+	 * @param props.txBuilder - Builds a `VersionedTransaction` from a given `BaseTxParams`, used to
+	 * produce the transaction that gets simulated.
+	 * @returns The adjusted `BaseTxParams`.
+	 * @throws Error if `useSimulatedComputeUnitsForCUPriceCalculation` is set without
+	 * `useSimulatedComputeUnits`, without `getCUPriceFromComputeUnits`, or if the simulated compute
+	 * units are unavailable (simulation failed).
+	 */
 	static async process(props: {
 		baseTxParams: BaseTxParams;
 		processConfig: ProcessingTxParams;

package/src/tx/types.ts

@@ -10,20 +10,34 @@ import {
 } from '@solana/web3.js';
 import { IWallet } from '../types';
 
+/** How a `TxSender` implementation waits for a transaction to confirm. */
 export enum ConfirmationStrategy {
+	/** Confirm via an RPC websocket `onSignature` subscription only. */
 	WebSocket = 'websocket',
+	/** Confirm by polling `getSignatureStatuses` only. */
 	Polling = 'polling',
+	/** Race a websocket subscription against polling and resolve on whichever confirms first. */
 	Combo = 'combo',
 }
 
+/** A landed transaction's signature plus the slot it was confirmed at (`undefined` if the slot wasn't available). */
 export type TxSigAndSlot = {
 	txSig: TransactionSignature;
 	slot: number | undefined;
 };
 
+/** Common interface implemented by every transaction-sending strategy (`BaseTxSender` and its subclasses). */
 export interface TxSender {
 	wallet: IWallet;
 
+	/**
+	 * Signs (unless `preSigned`), sends, and confirms a legacy `Transaction`.
+	 * @param tx - Transaction to send.
+	 * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+	 * @param opts - Confirmation options overriding the sender's defaults.
+	 * @param preSigned - If `true`, skip wallet signing (the transaction is already fully signed).
+	 * @returns The landed transaction's signature and confirmation slot.
+	 */
 	send(
 		tx: Transaction,
 		additionalSigners?: Array<Signer>,
@@ -31,6 +45,14 @@ export interface TxSender {
 		preSigned?: boolean
 	): Promise<TxSigAndSlot>;
 
+	/**
+	 * Signs (unless `preSigned`), sends, and confirms a `VersionedTransaction`.
+	 * @param tx - Transaction to send.
+	 * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+	 * @param opts - Confirmation options overriding the sender's defaults.
+	 * @param preSigned - If `true`, skip wallet signing (the transaction is already fully signed).
+	 * @returns The landed transaction's signature and confirmation slot.
+	 */
 	sendVersionedTransaction(
 		tx: VersionedTransaction,
 		additionalSigners?: Array<Signer>,
@@ -38,6 +60,15 @@ export interface TxSender {
 		preSigned?: boolean
 	): Promise<TxSigAndSlot>;
 
+	/**
+	 * Builds (but does not send or sign) an unsigned `VersionedTransaction` from raw instructions.
+	 * @param ixs - Instructions to include, in order.
+	 * @param lookupTableAccounts - Address lookup tables to compile the message against.
+	 * @param additionalSigners - Unused by `BaseTxSender` (signing happens at send time, e.g. in `sendVersionedTransaction`).
+	 * @param opts - Unused by `BaseTxSender`.
+	 * @param blockhash - Blockhash to compile the message with; if omitted, the sender fetches a current one.
+	 * @returns The compiled, unsigned `VersionedTransaction`, not yet sent.
+	 */
 	getVersionedTransaction(
 		ixs: TransactionInstruction[],
 		lookupTableAccounts: AddressLookupTableAccount[],
@@ -46,18 +77,33 @@ export interface TxSender {
 		blockhash?: BlockhashWithExpiryBlockHeight
 	): Promise<VersionedTransaction>;
 
+	/**
+	 * Sends an already-serialized, already-signed transaction and confirms it.
+	 * @param rawTransaction - Wire-format serialized transaction bytes.
+	 * @param opts - Confirmation options.
+	 * @returns The landed transaction's signature and confirmation slot.
+	 */
 	sendRawTransaction(
 		rawTransaction: Buffer | Uint8Array,
 		opts: ConfirmOptions
 	): Promise<TxSigAndSlot>;
 
+	/**
+	 * Simulates a transaction against the cluster without sending it.
+	 * @param tx - Transaction to simulate.
+	 * @returns `true` if the simulation succeeded (no error), `false` otherwise.
+	 */
 	simulateTransaction(tx: VersionedTransaction): Promise<boolean>;
 
+	/** Number of transactions sent by this sender that timed out waiting for confirmation. */
 	getTimeoutCount(): number;
+	/** Multiplier this sender currently recommends applying to a base priority fee, derived from recent land/timeout behavior. */
 	getSuggestedPriorityFeeMultiplier(): number;
+	/** Fraction (0-1) of recently sent transactions that landed successfully. */
 	getTxLandRate(): number;
 }
 
+/** Error thrown by tx senders when a transaction fails to send or confirm, carrying a stable numeric `code` (see `constants/txConstants`) alongside the message. */
 export class TxSendError extends Error {
 	constructor(
 		public message: string,

package/src/tx/utils.ts

@@ -5,9 +5,16 @@ import {
 	VersionedTransaction,
 } from '@solana/web3.js';
 
+/** Maximum serialized transaction size (bytes) Solana will accept over the wire — the 1232-byte MTU-derived limit shared by legacy and versioned transactions. */
 export const MAX_TX_BYTE_SIZE = 1232;
+/** 4-byte magic prefix identifying velocity's native (non-Anchor) entrypoint instructions, followed by a 1-byte opcode — see `createNativeInstructionDiscriminatorBuffer`. */
 export const NATIVE_INSTRUCTION_MAGIC_BYTES = [0xff, 0xff, 0xff, 0xff];
 
+/**
+ * Checks whether a transaction is a `VersionedTransaction` (v0+) rather than a legacy `Transaction`.
+ * @param tx - Transaction to check.
+ * @returns `true` if `tx` is versioned.
+ */
 export const isVersionedTransaction = (
 	tx: Transaction | VersionedTransaction
 ): boolean => {
@@ -18,6 +25,18 @@ export const isVersionedTransaction = (
 	return isVersionedTx;
 };
 
+/**
+ * Estimates the serialized wire size (bytes) a transaction built from `instructions` would have,
+ * without actually building/signing it — used to decide whether instructions still fit under
+ * `MAX_TX_BYTE_SIZE` before committing to a blockhash/signature. Accounts for account
+ * deduplication and, for versioned transactions, the byte savings from any accounts resolvable via
+ * `addressLookupTables`.
+ * @param instructions - Instructions the transaction would contain.
+ * @param versionedTransaction - Whether to size as a v0 `VersionedTransaction` (includes the
+ * version byte and lookup-table address/index overhead) or a legacy `Transaction`; defaults to `true`.
+ * @param addressLookupTables - Lookup tables to credit toward reducing the static account-keys list.
+ * @returns The estimated total transaction size in bytes.
+ */
 export const getSizeOfTransaction = (
 	instructions: TransactionInstruction[],
 	versionedTransaction = true,
@@ -97,6 +116,13 @@ function getSizeOfCompressedU16(n: number) {
 	return 1 + Number(n >= 128) + Number(n >= 16384);
 }
 
+/**
+ * Builds the 5-byte instruction-data prefix for velocity's native (non-Anchor) entrypoint:
+ * `NATIVE_INSTRUCTION_MAGIC_BYTES` (`[0xFF, 0xFF, 0xFF, 0xFF]`) followed by a 1-byte opcode. Used
+ * for high-frequency keeper instructions that bypass Anchor's instruction-dispatch overhead.
+ * @param discriminator - The native instruction's opcode byte.
+ * @returns The 5-byte discriminator buffer to prepend to the instruction's data.
+ */
 export function createNativeInstructionDiscriminatorBuffer(
 	discriminator: number
 ): Uint8Array {