@velocity-exchange/sdk 0.2.5 → 0.4.0

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

@@ -13,30 +13,46 @@
 import { AddressLookupTableAccount, BlockhashWithExpiryBlockHeight, Commitment, ConfirmOptions, Connection, Signer, SimulatedTransactionResponse, Transaction, TransactionInstruction, TransactionVersion, VersionedTransaction } from '@solana/web3.js';
 import { VelocityClientMetricsEvents, IWallet, MappedRecord, SignedTxData, TxParams } from '../types';
 export declare const COMPUTE_UNITS_DEFAULT = 200000;
+/** 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[];
     simulatedTx?: SimulatedTransactionResponse;
 };
+/** 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 declare class TxHandler {
     private blockHashToLastValidBlockHeightLookup;
@@ -48,6 +64,16 @@ export declare class TxHandler {
     private onSignedCb?;
     private blockhashCommitment;
     private 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;
@@ -59,16 +85,22 @@ export declare class TxHandler {
         };
         config?: TxHandlerConfig;
     });
+    /** @returns The wallet this handler currently uses to sign transactions when a call doesn't pass its own. */
     getWallet(): IWallet;
     private addHashAndExpiryToLookup;
     private getProps;
+    /**
+     * Swaps the default wallet used for subsequent signing calls that don't pass their own.
+     * @param wallet - New default wallet.
+     */
     updateWallet(wallet: IWallet): void;
     /**
      * Created this to prevent non-finalized blockhashes being used when building transactions. We want to always use finalized because otherwise it's easy to get the BlockHashNotFound error (RPC uses finalized to validate a transaction). Using an older blockhash when building transactions should never really be a problem right now.
      *
      * 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.
      */
     getLatestBlockhashForTransaction(): Promise<Readonly<{
         blockhash: string;
@@ -81,14 +113,18 @@ export declare class TxHandler {
      */
     private resolveRecentBlockhash;
     /**
-     * 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.
      */
     prepareTx(tx: Transaction, additionalSigners: Array<Signer>, wallet?: IWallet, confirmationOpts?: ConfirmOptions, preSigned?: boolean, recentBlockhash?: BlockhashWithExpiryBlockHeight): Promise<Transaction>;
     private isVersionedTransaction;
@@ -96,6 +132,16 @@ export declare class TxHandler {
     private getTxSigFromSignedTx;
     private getBlockhashFromSignedTx;
     private signTx;
+    /**
+     * 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.
+     */
     signVersionedTx(tx: VersionedTransaction, additionalSigners: Array<Signer>, recentBlockhash?: BlockhashWithExpiryBlockHeight, wallet?: IWallet): Promise<VersionedTransaction>;
     private handleSignedTxData;
     /**
@@ -105,46 +151,93 @@ export declare class TxHandler {
      */
     private getProcessedTransactionParams;
     private _generateVersionedTransaction;
+    /**
+     * 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`.
+     */
     generateLegacyVersionedTransaction(recentBlockhash: BlockhashWithExpiryBlockHeight, ixs: TransactionInstruction[], wallet?: IWallet): VersionedTransaction;
+    /**
+     * 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`.
+     */
     generateVersionedTransaction(recentBlockhash: BlockhashWithExpiryBlockHeight, ixs: TransactionInstruction[], lookupTableAccounts: AddressLookupTableAccount[], wallet?: IWallet): VersionedTransaction;
+    /**
+     * 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`.
+     */
     generateLegacyTransaction(ixs: TransactionInstruction[], recentBlockhash?: BlockhashWithExpiryBlockHeight): Transaction;
     /**
      * 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.
      */
     buildBulkTransactions(props: Omit<TxBuildingProps, 'instructions'> & {
         instructions: (TransactionInstruction | TransactionInstruction[])[];
     }): Promise<(Transaction | VersionedTransaction | undefined)[]>;
     /**
-     *
-     * @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.
      */
     buildTransaction(props: TxBuildingProps): Promise<Transaction | VersionedTransaction>;
+    /**
+     * 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`.
+     */
     wrapInTx(instruction: TransactionInstruction, computeUnits?: number, computeUnitsPrice?: number): Transaction;
     /**
      * 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.
      */
     getPreparedAndSignedLegacyTransactionMap<T extends Record<string, Transaction | undefined>>(txsMap: T, wallet?: IWallet, commitment?: Commitment, recentBlockhash?: BlockhashWithExpiryBlockHeight): Promise<{
         signedTxMap: T;
         signedTxData: SignedTxData[];
     }>;
     /**
-     * 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.
      */
     getSignedTransactionMap<T extends Record<string, Transaction | VersionedTransaction | undefined>>(txsToSignMap: T, wallet?: IWallet): Promise<{
         signedTxMap: T;
@@ -152,16 +245,19 @@ export declare 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.
      */
     buildTransactionsMap<T extends Record<string, TransactionInstruction | TransactionInstruction[]>>(props: Omit<TxBuildingProps, 'instructions'> & {
         instructionsMap: T;
     }): Promise<MappedRecord<T, Transaction | VersionedTransaction>>;
     /**
      * 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`.
      */
     buildAndSignTransactionMap<T extends Record<string, TransactionInstruction | TransactionInstruction[]>>(props: Omit<TxBuildingProps, 'instructions'> & {
         instructionsMap: T;
@@ -172,6 +268,21 @@ export declare class TxHandler {
         signedTxMap: MappedRecord<T, Transaction | VersionedTransaction>;
         signedTxData: SignedTxData[];
     }>;
+    /**
+     * 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).
+     */
     simulateAndCalculateInstructions(txBuildingProps: TxBuildingProps, optionalInstructions?: TransactionInstruction[], versionedTransaction?: boolean, addressLookupTables?: AddressLookupTableAccount[]): Promise<[
         TransactionInstruction[],
         SimulatedTransactionResponse | undefined

package/lib/browser/tx/txHandler.js

@@ -36,8 +36,23 @@ const BLOCKHASH_FETCH_RETRY_SLEEP = 200;
 const RECENT_BLOCKHASH_STALE_TIME_MS = 2000; // Reuse blockhashes within this timeframe during bursts of tx contruction
 /**
  * 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.
  */
 class TxHandler {
+    /**
+     * @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) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
         this.blockHashToLastValidBlockHeightLookup = {};
@@ -58,6 +73,7 @@ class TxHandler {
         this.onSignedCb = (_u = props.opts) === null || _u === void 0 ? void 0 : _u.onSignedCb;
         this.preSignedCb = (_v = props.opts) === null || _v === void 0 ? void 0 : _v.preSignedCb;
     }
+    /** @returns The wallet this handler currently uses to sign transactions when a call doesn't pass its own. */
     getWallet() {
         return this.wallet;
     }
@@ -67,6 +83,10 @@ class TxHandler {
         this.blockHashToLastValidBlockHeightLookup[hashAndExpiry.blockhash] =
             hashAndExpiry.lastValidBlockHeight;
     }
+    /**
+     * Swaps the default wallet used for subsequent signing calls that don't pass their own.
+     * @param wallet - New default wallet.
+     */
     updateWallet(wallet) {
         this.wallet = wallet;
     }
@@ -75,7 +95,8 @@ 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.
      */
     async getLatestBlockhashForTransaction() {
         return this.blockHashFetcher.getLatestBlockhash();
@@ -93,14 +114,18 @@ class TxHandler {
         return resolved;
     }
     /**
-     * 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.
      */
     async prepareTx(tx, additionalSigners, wallet, confirmationOpts, preSigned, recentBlockhash) {
         if (preSigned) {
@@ -164,6 +189,16 @@ 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.
+     */
     async signVersionedTx(tx, additionalSigners, recentBlockhash, wallet) {
         var _a;
         [wallet] = this.getProps(wallet);
@@ -247,6 +282,15 @@ class TxHandler {
         this.addHashAndExpiryToLookup(recentBlockhash);
         return new web3_js_1.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`.
+     */
     generateLegacyVersionedTransaction(recentBlockhash, ixs, wallet) {
         [wallet] = this.getProps(wallet);
         const message = new web3_js_1.TransactionMessage({
@@ -259,6 +303,15 @@ class TxHandler {
         tx.SIGNATURE_BLOCK_AND_EXPIRY = recentBlockhash;
         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`.
+     */
     generateVersionedTransaction(recentBlockhash, ixs, lookupTableAccounts, wallet) {
         [wallet] = this.getProps(wallet);
         const message = new web3_js_1.TransactionMessage({
@@ -271,6 +324,13 @@ class TxHandler {
         tx.SIGNATURE_BLOCK_AND_EXPIRY = recentBlockhash;
         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`.
+     */
     generateLegacyTransaction(ixs, recentBlockhash) {
         const tx = new web3_js_1.Transaction().add(...ixs);
         if (recentBlockhash) {
@@ -280,8 +340,10 @@ 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.
      */
     async buildBulkTransactions(props) {
         const recentBlockhash = await this.resolveRecentBlockhash(props === null || props === void 0 ? void 0 : props.recentBlockhash);
@@ -296,13 +358,16 @@ 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.
      */
     async buildTransaction(props) {
         const { txVersion, txParams, connection: _connection, preFlightCommitment: _preFlightCommitment, fetchAllMarketLookupTableAccounts, forceVersionedTransaction, instructions, } = props;
@@ -386,6 +451,17 @@ class TxHandler {
             return this.generateVersionedTransaction(recentBlockhash, allIx, lookupTables);
         }
     }
+    /**
+     * 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`.
+     */
     wrapInTx(instruction, computeUnits = 600000, computeUnitsPrice = 0) {
         const tx = new web3_js_1.Transaction();
         if (computeUnits != exports.COMPUTE_UNITS_DEFAULT) {
@@ -407,11 +483,12 @@ 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.
      */
     async getPreparedAndSignedLegacyTransactionMap(txsMap, wallet, commitment, recentBlockhash) {
         var _a, _b;
@@ -428,11 +505,16 @@ class TxHandler {
         return this.getSignedTransactionMap(txsMap, wallet);
     }
     /**
-     * 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.
      */
     async getSignedTransactionMap(txsToSignMap, wallet) {
         var _a;
@@ -475,8 +557,8 @@ 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.
      */
     async buildTransactionsMap(props) {
         const builtTxs = await this.buildBulkTransactions({
@@ -490,8 +572,11 @@ 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`.
      */
     async buildAndSignTransactionMap(props) {
         const builtTxs = await this.buildTransactionsMap(props);
@@ -500,6 +585,21 @@ class TxHandler {
             : this.getSignedTransactionMap(builtTxs, props.wallet));
         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).
+     */
     async simulateAndCalculateInstructions(txBuildingProps, optionalInstructions = [], versionedTransaction = true, addressLookupTables = []) {
         var _a;
         const baseInstructions = Array.isArray(txBuildingProps.instructions)

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