@velocity-exchange/sdk 0.2.5 → 0.4.0

package/lib/node/tx/txParamProcessor.d.ts

@@ -5,9 +5,31 @@ 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 declare class TransactionParamProcessor {
     private static getComputeUnitsFromSim;
+    /**
+     * 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 getTxSimComputeUnits(tx: VersionedTransaction, connection: Connection, bufferMultiplier: number, // 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?: number, simulatedTx?: SimulatedTransactionResponse): Promise<{
         success: true;
@@ -16,6 +38,31 @@ export declare class TransactionParamProcessor {
         success: false;
         computeUnits: undefined;
     }>;
+    /**
+     * 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 process(props: {
         baseTxParams: BaseTxParams;
         processConfig: ProcessingTxParams;

package/lib/node/tx/txParamProcessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"txParamProcessor.d.ts","sourceRoot":"","sources":["../../../src/tx/txParamProcessor.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,UAAU,EAEV,4BAA4B,EAC5B,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAO5D,KAAK,wBAAwB,GAAG;IAC/B,QAAQ,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,qBAAa,yBAAyB;mBAChB,sBAAsB;WAUvB,oBAAoB,CACvC,EAAE,EAAE,oBAAoB,EACxB,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,MAAM,EAAE,mIAAmI;IAC7J,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,4BAA4B,GACxC,OAAO,CACP;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GACvC;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,YAAY,EAAE,SAAS,CAAA;KAAE,CAC7C;WAuDY,OAAO,CAAC,KAAK,EAAE;QAC3B,YAAY,EAAE,YAAY,CAAC;QAC3B,aAAa,EAAE,kBAAkB,CAAC;QAClC,aAAa,EAAE;YACd,UAAU,EAAE,UAAU,CAAC;YACvB,WAAW,CAAC,EAAE,4BAA4B,CAAC;SAC3C,CAAC;QACF,SAAS,EAAE,CACV,oBAAoB,EAAE,wBAAwB,KAC1C,OAAO,CAAC,oBAAoB,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,YAAY,CAAC;CAwEzB"}
+{"version":3,"file":"txParamProcessor.d.ts","sourceRoot":"","sources":["../../../src/tx/txParamProcessor.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,UAAU,EAEV,4BAA4B,EAC5B,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAO5D,KAAK,wBAAwB,GAAG;IAC/B,QAAQ,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF;;;;;;GAMG;AACH,qBAAa,yBAAyB;mBAChB,sBAAsB;IAU3C;;;;;;;;;;;;;;;;;OAiBG;WACiB,oBAAoB,CACvC,EAAE,EAAE,oBAAoB,EACxB,UAAU,EAAE,UAAU,EACtB,gBAAgB,EAAE,MAAM,EAAE,mIAAmI;IAC7J,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,4BAA4B,GACxC,OAAO,CACP;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GACvC;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,YAAY,EAAE,SAAS,CAAA;KAAE,CAC7C;IAuDD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACU,OAAO,CAAC,KAAK,EAAE;QAC3B,YAAY,EAAE,YAAY,CAAC;QAC3B,aAAa,EAAE,kBAAkB,CAAC;QAClC,aAAa,EAAE;YACd,UAAU,EAAE,UAAU,CAAC;YACvB,WAAW,CAAC,EAAE,4BAA4B,CAAC;SAC3C,CAAC;QACF,SAAS,EAAE,CACV,oBAAoB,EAAE,wBAAwB,KAC1C,OAAO,CAAC,oBAAoB,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,YAAY,CAAC;CAwEzB"}

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tx/types.ts"],"names":[],"mappings":";;AAAA,OAAO,EACN,yBAAyB,EACzB,8BAA8B,EAC9B,cAAc,EACd,MAAM,EACN,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,oBAAY,oBAAoB;IAC/B,SAAS,cAAc;IACvB,OAAO,YAAY;IACnB,KAAK,UAAU;CACf;AAED,MAAM,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,oBAAoB,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB,CAAC;AAEF,MAAM,WAAW,QAAQ;IACxB,MAAM,EAAE,OAAO,CAAC;IAEhB,IAAI,CACH,EAAE,EAAE,WAAW,EACf,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB,wBAAwB,CACvB,EAAE,EAAE,oBAAoB,EACxB,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB,uBAAuB,CACtB,GAAG,EAAE,sBAAsB,EAAE,EAC7B,mBAAmB,EAAE,yBAAyB,EAAE,EAChD,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,8BAA8B,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC,kBAAkB,CACjB,cAAc,EAAE,MAAM,GAAG,UAAU,EACnC,IAAI,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB,mBAAmB,CAAC,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhE,eAAe,IAAI,MAAM,CAAC;IAC1B,iCAAiC,IAAI,MAAM,CAAC;IAC5C,aAAa,IAAI,MAAM,CAAC;CACxB;AAED,qBAAa,WAAY,SAAQ,KAAK;IAE7B,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,MAAM;gBADZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM;CAOpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tx/types.ts"],"names":[],"mappings":";;AAAA,OAAO,EACN,yBAAyB,EACzB,8BAA8B,EAC9B,cAAc,EACd,MAAM,EACN,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,0EAA0E;AAC1E,oBAAY,oBAAoB;IAC/B,oEAAoE;IACpE,SAAS,cAAc;IACvB,sDAAsD;IACtD,OAAO,YAAY;IACnB,6FAA6F;IAC7F,KAAK,UAAU;CACf;AAED,qHAAqH;AACrH,MAAM,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,oBAAoB,CAAC;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB,CAAC;AAEF,8GAA8G;AAC9G,MAAM,WAAW,QAAQ;IACxB,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;;OAOG;IACH,IAAI,CACH,EAAE,EAAE,WAAW,EACf,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;OAOG;IACH,wBAAwB,CACvB,EAAE,EAAE,oBAAoB,EACxB,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;;;;;OAQG;IACH,uBAAuB,CACtB,GAAG,EAAE,sBAAsB,EAAE,EAC7B,mBAAmB,EAAE,yBAAyB,EAAE,EAChD,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,8BAA8B,GACxC,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,kBAAkB,CACjB,cAAc,EAAE,MAAM,GAAG,UAAU,EACnC,IAAI,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC,CAAC;IAEzB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhE,0FAA0F;IAC1F,eAAe,IAAI,MAAM,CAAC;IAC1B,8HAA8H;IAC9H,iCAAiC,IAAI,MAAM,CAAC;IAC5C,6EAA6E;IAC7E,aAAa,IAAI,MAAM,CAAC;CACxB;AAED,oKAAoK;AACpK,qBAAa,WAAY,SAAQ,KAAK;IAE7B,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,MAAM;gBADZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM;CAOpB"}

package/lib/node/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/node/tx/utils.d.ts

@@ -1,7 +1,33 @@
 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;
 //# sourceMappingURL=utils.d.ts.map

package/lib/node/tx/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/tx/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,yBAAyB,EACzB,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,eAAO,MAAM,8BAA8B,UAA2B,CAAC;AAEvE,eAAO,MAAM,sBAAsB,OAC9B,WAAW,GAAG,oBAAoB,KACpC,OAMF,CAAC;AAEF,eAAO,MAAM,oBAAoB,iBAClB,sBAAsB,EAAE,wDAEjB,yBAAyB,EAAE,KAC9C,MAqEF,CAAC;AAMF,wBAAgB,0CAA0C,CACzD,aAAa,EAAE,MAAM,GACnB,UAAU,CAKZ"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/tx/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,yBAAyB,EACzB,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AAEzB,kKAAkK;AAClK,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,8KAA8K;AAC9K,eAAO,MAAM,8BAA8B,UAA2B,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,OAC9B,WAAW,GAAG,oBAAoB,KACpC,OAMF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,iBAClB,sBAAsB,EAAE,wDAEjB,yBAAyB,EAAE,KAC9C,MAqEF,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CACzD,aAAa,EAAE,MAAM,GACnB,UAAU,CAKZ"}

package/lib/node/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/node/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/node/tx/whileValidTxSender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"whileValidTxSender.d.ts","sourceRoot":"","sources":["../../../src/tx/whileValidTxSender.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EACN,cAAc,EACd,UAAU,EAEV,MAAM,EACN,WAAW,EACX,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAKnC,KAAK,gBAAgB,GAAG;IACvB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,qBAAa,kBAAmB,SAAQ,YAAY;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,SAAK;IAChB,UAAU;mBAEI,MAAM;8BAAwB,MAAM;OAC9C;IAEJ,oBAAoB,UAAQ;YAEd,+BAA+B;gBAsB1B,EAClB,UAAU,EACV,MAAM,EACN,IAAsD,EACtD,UAA0B,EAC1B,qBAA+C,EAC/C,oBAAiD,EACjD,2BAAgC,EAChC,SAAS,EACT,eAAe,EACf,+BAA+B,EAC/B,iBAAiB,EACjB,mBAA0B,EAC1B,uBAA8B,GAC9B,EAAE;QACF,UAAU,EAAE,UAAU,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,qBAAqB,CAAC,EAAE,UAAU,EAAE,CAAC;QACrC,2BAA2B,CAAC,EAAE,CAAC,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;QACpE,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;QAC5C,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,+BAA+B,CAAC,EAAE,MAAM,CAAC;QACzC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;QACjD,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,uBAAuB,CAAC,EAAE,OAAO,CAAC;KAClC;IAoBK,KAAK,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjD,SAAS,CACd,EAAE,EAAE,WAAW,EACf,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,EAChC,IAAI,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,WAAW,CAAC;IAgDjB,wBAAwB,CAC7B,EAAE,EAAE,oBAAoB,EACxB,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,YAAY,CAAC;IA8DlB,kBAAkB,CACvB,cAAc,EAAE,MAAM,GAAG,UAAU,EACnC,IAAI,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC;CA+DxB"}
+{"version":3,"file":"whileValidTxSender.d.ts","sourceRoot":"","sources":["../../../src/tx/whileValidTxSender.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EACN,cAAc,EACd,UAAU,EAEV,MAAM,EACN,WAAW,EACX,oBAAoB,EACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAKnC,KAAK,gBAAgB,GAAG;IACvB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IACnD,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,SAAK;IAChB,wMAAwM;IACxM,UAAU;mBAEI,MAAM;8BAAwB,MAAM;OAC9C;IAEJ,2MAA2M;IAC3M,oBAAoB,UAAQ;IAE5B;;;;OAIG;YACW,+BAA+B;IAsB7C;;;;;;;;;;;;;;OAcG;gBACgB,EAClB,UAAU,EACV,MAAM,EACN,IAAsD,EACtD,UAA0B,EAC1B,qBAA+C,EAC/C,oBAAiD,EACjD,2BAAgC,EAChC,SAAS,EACT,eAAe,EACf,+BAA+B,EAC/B,iBAAiB,EACjB,mBAA0B,EAC1B,uBAA8B,GAC9B,EAAE;QACF,UAAU,EAAE,UAAU,CAAC;QACvB,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,CAAC,EAAE,cAAc,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,qBAAqB,CAAC,EAAE,UAAU,EAAE,CAAC;QACrC,2BAA2B,CAAC,EAAE,CAAC,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC,EAAE,CAAC;QACpE,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;QAC5C,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,+BAA+B,CAAC,EAAE,MAAM,CAAC;QACzC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;QACjD,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,uBAAuB,CAAC,EAAE,OAAO,CAAC;KAClC;IAoBD;;;;;OAKG;IACG,KAAK,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOvD;;;;;;;;;;;;;OAaG;IACG,SAAS,CACd,EAAE,EAAE,WAAW,EACf,iBAAiB,EAAE,KAAK,CAAC,MAAM,CAAC,EAChC,IAAI,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,WAAW,CAAC;IAgDvB;;;;;;;;;;;;OAYG;IACG,wBAAwB,CAC7B,EAAE,EAAE,oBAAoB,EACxB,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EACjC,IAAI,CAAC,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,YAAY,CAAC;IA8DxB;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CACvB,cAAc,EAAE,MAAM,GAAG,UAAU,EACnC,IAAI,EAAE,cAAc,GAClB,OAAO,CAAC,YAAY,CAAC;CA+DxB"}

package/lib/node/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();