@velocity-exchange/sdk 0.3.0 → 0.4.0

package/lib/browser/tx/txParamProcessor.js

@@ -6,6 +6,10 @@ const MAX_COMPUTE_UNITS = 1400000;
 const TEST_SIMS_ALWAYS_FAIL = false;
 /**
  * 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.
  */
 class TransactionParamProcessor {
     static async getComputeUnitsFromSim(txSim) {
@@ -15,6 +19,24 @@ 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`.
+     */
     static async getTxSimComputeUnits(tx, connection, bufferMultiplier, // Making this a mandatory param to force the user to remember that simulated CU's can be inaccurate and a buffer should be applied
     lowerBoundCu, simulatedTx) {
         var _a, _b;
@@ -54,6 +76,31 @@ 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) {
         var _a;
         // # Exit early if no process config is provided

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

@@ -2,26 +2,72 @@
 /// <reference types="node" />
 import { AddressLookupTableAccount, BlockhashWithExpiryBlockHeight, ConfirmOptions, Signer, Transaction, TransactionInstruction, TransactionSignature, VersionedTransaction } from '@solana/web3.js';
 import { IWallet } from '../types';
+/** How a `TxSender` implementation waits for a transaction to confirm. */
 export declare 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>, opts?: ConfirmOptions, 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>, opts?: ConfirmOptions, 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[], additionalSigners?: Array<Signer>, opts?: ConfirmOptions, 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 declare class TxSendError extends Error {
     message: string;
     code: number;

package/lib/browser/tx/types.js

@@ -1,12 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TxSendError = exports.ConfirmationStrategy = void 0;
+/** How a `TxSender` implementation waits for a transaction to confirm. */
 var ConfirmationStrategy;
 (function (ConfirmationStrategy) {
+    /** Confirm via an RPC websocket `onSignature` subscription only. */
     ConfirmationStrategy["WebSocket"] = "websocket";
+    /** Confirm by polling `getSignatureStatuses` only. */
     ConfirmationStrategy["Polling"] = "polling";
+    /** Race a websocket subscription against polling and resolve on whichever confirms first. */
     ConfirmationStrategy["Combo"] = "combo";
 })(ConfirmationStrategy || (exports.ConfirmationStrategy = ConfirmationStrategy = {}));
+/** Error thrown by tx senders when a transaction fails to send or confirm, carrying a stable numeric `code` (see `constants/txConstants`) alongside the message. */
 class TxSendError extends Error {
     constructor(message, code) {
         super(message);

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

@@ -1,6 +1,32 @@
 import { AddressLookupTableAccount, Transaction, TransactionInstruction, 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 declare 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 declare const NATIVE_INSTRUCTION_MAGIC_BYTES: number[];
+/**
+ * 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 declare const isVersionedTransaction: (tx: Transaction | VersionedTransaction) => boolean;
+/**
+ * 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 declare const getSizeOfTransaction: (instructions: TransactionInstruction[], versionedTransaction?: boolean, addressLookupTables?: AddressLookupTableAccount[]) => number;
+/**
+ * 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 declare function createNativeInstructionDiscriminatorBuffer(discriminator: number): Uint8Array;

package/lib/browser/tx/utils.js

@@ -2,14 +2,33 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNativeInstructionDiscriminatorBuffer = exports.getSizeOfTransaction = exports.isVersionedTransaction = exports.NATIVE_INSTRUCTION_MAGIC_BYTES = exports.MAX_TX_BYTE_SIZE = void 0;
 const web3_js_1 = require("@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. */
 exports.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`. */
 exports.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.
+ */
 const isVersionedTransaction = (tx) => {
     const version = tx === null || tx === void 0 ? void 0 : tx.version;
     const isVersionedTx = tx instanceof web3_js_1.VersionedTransaction || version !== undefined;
     return isVersionedTx;
 };
 exports.isVersionedTransaction = isVersionedTransaction;
+/**
+ * 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.
+ */
 const getSizeOfTransaction = (instructions, versionedTransaction = true, addressLookupTables = []) => {
     const programs = new Set();
     const signers = new Set();
@@ -69,6 +88,13 @@ exports.getSizeOfTransaction = getSizeOfTransaction;
 function getSizeOfCompressedU16(n) {
     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.
+ */
 function createNativeInstructionDiscriminatorBuffer(discriminator) {
     const buffer = new Uint8Array(5);
     buffer.set(exports.NATIVE_INSTRUCTION_MAGIC_BYTES, 0);

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

@@ -8,15 +8,50 @@ import { IWallet } from '../types';
 type ResolveReference = {
     resolve?: () => void;
 };
+/**
+ * `TxSender` that (like `RetryTxSender`) resends the same signed transaction to `connection`
+ * every `retrySleep` ms until confirmation or timeout, additionally recording each in-flight
+ * signature's blockhash/`lastValidBlockHeight` in `untilValid` and detecting solana-core's
+ * blockhash-height-offset behavior via `useBlockHeightOffset`. Note: as currently implemented,
+ * `sendRawTransaction`'s resend/timeout loop uses the same wall-clock `this.timeout` as
+ * `RetryTxSender` and does not itself consult `untilValid`/`useBlockHeightOffset` to stop
+ * resending once a transaction's blockhash has actually expired — those fields are populated for
+ * callers/subclasses that want to inspect per-transaction validity, not consumed internally here.
+ * Prefer this sender when you build transactions via this class's `prepareTx`/`sendVersionedTransaction`
+ * (which populate `untilValid`) and need that bookkeeping available.
+ */
 export declare class WhileValidTxSender extends BaseTxSender {
+    /** Interval (ms) between resend attempts of the same signed transaction. */
     retrySleep: number;
     timoutCount: number;
+    /** Tracks each currently in-flight transaction signature's blockhash and `lastValidBlockHeight`, populated by `prepareTx`/`sendVersionedTransaction` and cleared once `sendRawTransaction` finishes. */
     untilValid: Map<string, {
         blockhash: string;
         lastValidBlockHeight: number;
     }>;
+    /** Whether the connected cluster's solana-core version (`< 2`) requires the legacy block-height offset when checking blockhash validity; refreshed asynchronously by `checkAndSetUseBlockHeightOffset`. */
     useBlockHeightOffset: boolean;
+    /**
+     * Queries `connection.getVersion()` and sets `useBlockHeightOffset` based on the cluster's
+     * solana-core major version (`true` for `< 2`, `false` for `>= 2`). Fire-and-forget: errors
+     * and unparseable versions are silently ignored, leaving `useBlockHeightOffset` at its current value.
+     */
     private checkAndSetUseBlockHeightOffset;
+    /**
+     * @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.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`.
+     * @param props.throwOnTransactionError - Whether a failed on-chain result throws; defaults to `true`.
+     */
     constructor({ connection, wallet, opts, retrySleep, additionalConnections, confirmationStrategy, additionalTxSenderCallbacks, txHandler, trackTxLandRate, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError, throwOnTransactionError, }: {
         connection: Connection;
         wallet: IWallet;
@@ -32,9 +67,56 @@ export declare class WhileValidTxSender extends BaseTxSender {
         throwOnTimeoutError?: boolean;
         throwOnTransactionError?: boolean;
     });
+    /**
+     * Waits `retrySleep` milliseconds, exposing an early-wake `resolve` via `reference` so the
+     * resend loop in `sendRawTransaction` can stop promptly once the transaction confirms or a
+     * resend fails.
+     * @param reference - Mutable holder `sendRawTransaction` uses to resolve this sleep early.
+     */
     sleep(reference: ResolveReference): Promise<void>;
+    /**
+     * Prepares (blockhash + signs, unless `preSigned`) a legacy `Transaction` using a fresh
+     * blockhash from `txHandler.getLatestBlockhashForTransaction()` (rather than `BaseTxSender`'s
+     * `prepareTx`, which would resolve one via `TxHandler.prepareTx`'s own path), and records the
+     * resulting signature's blockhash/expiry in `untilValid`.
+     * @param tx - Transaction to prepare.
+     * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+     * @param opts - Confirmation options passed through to `TxHandler.prepareTx`.
+     * @param preSigned - If `true`, skip signing; if the transaction carries a
+     * `SIGNATURE_BLOCK_AND_EXPIRY` marker (see `TxHandler`), that blockhash is used for `untilValid`
+     * instead of a freshly fetched one.
+     * @returns The prepared (and signed, unless `preSigned`) transaction.
+     * @throws Error if a blockhash can't be fetched/resolved, or the (pre)signed transaction has no signature.
+     */
     prepareTx(tx: Transaction, additionalSigners: Array<Signer>, opts: ConfirmOptions, preSigned?: boolean): Promise<Transaction>;
+    /**
+     * Signs (unless `preSigned`) and sends a `VersionedTransaction`, always overwriting its
+     * `recentBlockhash` with a freshly fetched one first (unless `preSigned` with a
+     * `SIGNATURE_BLOCK_AND_EXPIRY` marker, in which case that recorded blockhash is used for
+     * `untilValid` instead) — records the signature's blockhash/expiry in `untilValid` before
+     * delegating to `sendRawTransaction`.
+     * @param tx - Transaction to send; mutated in place (blockhash, signatures) unless `preSigned`.
+     * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+     * @param opts - Confirmation options; defaults to `this.opts`.
+     * @param preSigned - If `true`, skip signing (blockhash/`untilValid` bookkeeping still applies).
+     * @returns The result of `sendRawTransaction` on the serialized, signed transaction.
+     * @throws Error if a blockhash can't be fetched/resolved, or the (pre)signed transaction has no signature.
+     */
     sendVersionedTransaction(tx: VersionedTransaction, additionalSigners?: Array<Signer>, opts?: ConfirmOptions, preSigned?: boolean): Promise<TxSigAndSlot>;
+    /**
+     * 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, like `RetryTxSender`. Additionally: if
+     * confirmation resolves with an on-chain error and `checkConfirmationResultForError` doesn't
+     * itself throw (e.g. the detailed error couldn't be resolved), throws a generic
+     * `SendTransactionError` as a fallback when `throwOnTransactionError` is set; and always removes
+     * `txid` from `untilValid` once done, regardless of outcome.
+     * @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, or the
+     * fallback `SendTransactionError` described above.
+     */
     sendRawTransaction(rawTransaction: Buffer | Uint8Array, opts: ConfirmOptions): Promise<TxSigAndSlot>;
 }
 export {};

package/lib/browser/tx/whileValidTxSender.js

@@ -10,7 +10,24 @@ const baseTxSender_1 = require("./baseTxSender");
 const bs58_1 = __importDefault(require("bs58"));
 const config_1 = require("../config");
 const DEFAULT_RETRY = 2000;
+/**
+ * `TxSender` that (like `RetryTxSender`) resends the same signed transaction to `connection`
+ * every `retrySleep` ms until confirmation or timeout, additionally recording each in-flight
+ * signature's blockhash/`lastValidBlockHeight` in `untilValid` and detecting solana-core's
+ * blockhash-height-offset behavior via `useBlockHeightOffset`. Note: as currently implemented,
+ * `sendRawTransaction`'s resend/timeout loop uses the same wall-clock `this.timeout` as
+ * `RetryTxSender` and does not itself consult `untilValid`/`useBlockHeightOffset` to stop
+ * resending once a transaction's blockhash has actually expired — those fields are populated for
+ * callers/subclasses that want to inspect per-transaction validity, not consumed internally here.
+ * Prefer this sender when you build transactions via this class's `prepareTx`/`sendVersionedTransaction`
+ * (which populate `untilValid`) and need that bookkeeping available.
+ */
 class WhileValidTxSender extends baseTxSender_1.BaseTxSender {
+    /**
+     * Queries `connection.getVersion()` and sets `useBlockHeightOffset` based on the cluster's
+     * solana-core major version (`true` for `< 2`, `false` for `>= 2`). Fire-and-forget: errors
+     * and unparseable versions are silently ignored, leaving `useBlockHeightOffset` at its current value.
+     */
     async checkAndSetUseBlockHeightOffset() {
         this.connection.getVersion().then((version) => {
             const solanaCoreVersion = version['solana-core'];
@@ -30,6 +47,21 @@ class WhileValidTxSender extends baseTxSender_1.BaseTxSender {
             }
         });
     }
+    /**
+     * @param props.connection - RPC connection used for sending, resending, and confirming.
+     * @param props.wallet - Wallet used to sign transactions that aren't already `preSigned`.
+     * @param props.opts - Default `ConfirmOptions`; defaults to `DEFAULT_CONFIRMATION_OPTS` with `maxRetries: 0` (retries are handled by this sender's own resend loop, not the RPC node).
+     * @param props.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`.
+     * @param props.throwOnTransactionError - Whether a failed on-chain result throws; defaults to `true`.
+     */
     constructor({ connection, wallet, opts = { ...config_1.DEFAULT_CONFIRMATION_OPTS, maxRetries: 0 }, retrySleep = DEFAULT_RETRY, additionalConnections = new Array(), confirmationStrategy = types_1.ConfirmationStrategy.Combo, additionalTxSenderCallbacks = [], txHandler, trackTxLandRate, txLandRateLookbackWindowMinutes, landRateToFeeFunc, throwOnTimeoutError = true, throwOnTransactionError = true, }) {
         super({
             connection,
@@ -46,17 +78,39 @@ class WhileValidTxSender extends baseTxSender_1.BaseTxSender {
             throwOnTransactionError,
         });
         this.timoutCount = 0;
+        /** Tracks each currently in-flight transaction signature's blockhash and `lastValidBlockHeight`, populated by `prepareTx`/`sendVersionedTransaction` and cleared once `sendRawTransaction` finishes. */
         this.untilValid = new Map();
+        /** Whether the connected cluster's solana-core version (`< 2`) requires the legacy block-height offset when checking blockhash validity; refreshed asynchronously by `checkAndSetUseBlockHeightOffset`. */
         this.useBlockHeightOffset = true;
         this.retrySleep = retrySleep;
         this.checkAndSetUseBlockHeightOffset();
     }
+    /**
+     * Waits `retrySleep` milliseconds, exposing an early-wake `resolve` via `reference` so the
+     * resend loop in `sendRawTransaction` can stop promptly once the transaction confirms or a
+     * resend fails.
+     * @param reference - Mutable holder `sendRawTransaction` uses to resolve this sleep early.
+     */
     async sleep(reference) {
         return new Promise((resolve) => {
             reference.resolve = resolve;
             setTimeout(resolve, this.retrySleep);
         });
     }
+    /**
+     * Prepares (blockhash + signs, unless `preSigned`) a legacy `Transaction` using a fresh
+     * blockhash from `txHandler.getLatestBlockhashForTransaction()` (rather than `BaseTxSender`'s
+     * `prepareTx`, which would resolve one via `TxHandler.prepareTx`'s own path), and records the
+     * resulting signature's blockhash/expiry in `untilValid`.
+     * @param tx - Transaction to prepare.
+     * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+     * @param opts - Confirmation options passed through to `TxHandler.prepareTx`.
+     * @param preSigned - If `true`, skip signing; if the transaction carries a
+     * `SIGNATURE_BLOCK_AND_EXPIRY` marker (see `TxHandler`), that blockhash is used for `untilValid`
+     * instead of a freshly fetched one.
+     * @returns The prepared (and signed, unless `preSigned`) transaction.
+     * @throws Error if a blockhash can't be fetched/resolved, or the (pre)signed transaction has no signature.
+     */
     async prepareTx(tx, additionalSigners, opts, preSigned) {
         var _a;
         let latestBlockhash = await this.txHandler.getLatestBlockhashForTransaction();
@@ -86,6 +140,19 @@ class WhileValidTxSender extends baseTxSender_1.BaseTxSender {
         this.untilValid.set(txSig, latestBlockhash);
         return signedTx;
     }
+    /**
+     * Signs (unless `preSigned`) and sends a `VersionedTransaction`, always overwriting its
+     * `recentBlockhash` with a freshly fetched one first (unless `preSigned` with a
+     * `SIGNATURE_BLOCK_AND_EXPIRY` marker, in which case that recorded blockhash is used for
+     * `untilValid` instead) — records the signature's blockhash/expiry in `untilValid` before
+     * delegating to `sendRawTransaction`.
+     * @param tx - Transaction to send; mutated in place (blockhash, signatures) unless `preSigned`.
+     * @param additionalSigners - Extra signers to co-sign alongside the wallet.
+     * @param opts - Confirmation options; defaults to `this.opts`.
+     * @param preSigned - If `true`, skip signing (blockhash/`untilValid` bookkeeping still applies).
+     * @returns The result of `sendRawTransaction` on the serialized, signed transaction.
+     * @throws Error if a blockhash can't be fetched/resolved, or the (pre)signed transaction has no signature.
+     */
     async sendVersionedTransaction(tx, additionalSigners, opts, preSigned) {
         let latestBlockhash = await this.txHandler.getLatestBlockhashForTransaction();
         if (!latestBlockhash) {
@@ -129,6 +196,20 @@ class WhileValidTxSender extends baseTxSender_1.BaseTxSender {
         this.untilValid.set(txSig, latestBlockhash);
         return this.sendRawTransaction(signedTx.serialize(), opts);
     }
+    /**
+     * 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, like `RetryTxSender`. Additionally: if
+     * confirmation resolves with an on-chain error and `checkConfirmationResultForError` doesn't
+     * itself throw (e.g. the detailed error couldn't be resolved), throws a generic
+     * `SendTransactionError` as a fallback when `throwOnTransactionError` is set; and always removes
+     * `txid` from `untilValid` once done, regardless of outcome.
+     * @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, or the
+     * fallback `SendTransactionError` described above.
+     */
     async sendRawTransaction(rawTransaction, opts) {
         var _a, _b, _c;
         const startTime = this.getTimestamp();