@velocity-exchange/sdk 0.4.0 → 0.6.0

package/src/tx/txParamProcessor.ts

@@ -1,225 +0,0 @@
-import {
-	Connection,
-	RpcResponseAndContext,
-	SimulatedTransactionResponse,
-	VersionedTransaction,
-} from '@solana/web3.js';
-import { BaseTxParams, ProcessingTxParams } from '../types';
-
-const COMPUTE_UNIT_BUFFER_FACTOR = 1.2;
-const MAX_COMPUTE_UNITS = 1_400_000;
-
-const TEST_SIMS_ALWAYS_FAIL = false;
-
-type TransactionBuildingProps = {
-	txParams: BaseTxParams;
-};
-
-/**
- * This class is responsible for running through a "processing" pipeline for a base transaction, to adjust the standard transaction parameters based on a given configuration.
- *
- * Currently the only pipeline step is simulation-based compute unit resolution: build the
- * transaction with a max compute-unit budget, simulate it, and replace the compute-unit limit
- * (and optionally the compute-unit price) with values derived from actual simulated usage.
- */
-export class TransactionParamProcessor {
-	private static async getComputeUnitsFromSim(
-		txSim: RpcResponseAndContext<SimulatedTransactionResponse>
-	) {
-		if (txSim?.value?.unitsConsumed) {
-			return txSim?.value?.unitsConsumed;
-		}
-
-		return undefined;
-	}
-
-	/**
-	 * Determines a compute-unit limit to use for a transaction by simulating it (or reusing a
-	 * pre-supplied simulation), applying `bufferMultiplier` to the actually-consumed units, and
-	 * clamping the result to at most `MAX_COMPUTE_UNITS` (1,400,000). Simulation runs with
-	 * `replaceRecentBlockhash: true` to avoid spurious `blockHashNotFound` failures from an
-	 * already-stale blockhash on the transaction being sized. Never throws: any error (including
-	 * a simulation error result) is caught and reported via the `success: false` return.
-	 * @param tx - Transaction to simulate (ignored if `simulatedTx` is supplied instead).
-	 * @param connection - RPC connection used to simulate, if `simulatedTx` isn't provided.
-	 * @param bufferMultiplier - Multiplier applied to the raw consumed compute units before
-	 * clamping (e.g. `1.2` for a 20% buffer) — mandatory to force callers to account for
-	 * simulated CU counts being an imperfect predictor of the real on-chain cost.
-	 * @param lowerBoundCu - If provided, the result is floored at `min(lowerBoundCu, MAX_COMPUTE_UNITS)`.
-	 * @param simulatedTx - A pre-computed simulation result to reuse instead of simulating `tx` again.
-	 * @returns `{ success: true, computeUnits }` with the buffered/clamped compute-unit limit on
-	 * success, or `{ success: false, computeUnits: undefined }` if simulation failed or returned no
-	 * `unitsConsumed`.
-	 */
-	public static async getTxSimComputeUnits(
-		tx: VersionedTransaction,
-		connection: Connection,
-		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; computeUnits: number }
-		| { success: false; computeUnits: undefined }
-	> {
-		try {
-			if (TEST_SIMS_ALWAYS_FAIL)
-				throw new Error('Test Error::SIMS_ALWAYS_FAIL');
-
-			const simTxResult = simulatedTx
-				? ({
-						value: simulatedTx,
-				  } as RpcResponseAndContext<SimulatedTransactionResponse>)
-				: await connection.simulateTransaction(tx, {
-						replaceRecentBlockhash: true, // This is important to ensure that the blockhash is not too new.. Otherwise we will very often receive a "blockHashNotFound" error
-				  });
-
-			if (simTxResult?.value?.err) {
-				throw simTxResult?.value?.err;
-			}
-
-			const computeUnits = await this.getComputeUnitsFromSim(simTxResult);
-
-			if (computeUnits === undefined) {
-				throw new Error(
-					'TransactionParamProcessor: simulation did not return units consumed'
-				);
-			}
-
-			// Apply the buffer, but round down to the MAX_COMPUTE_UNITS, and round up to the nearest whole number
-			let bufferedComputeUnits = Math.ceil(
-				Math.min(computeUnits * bufferMultiplier, MAX_COMPUTE_UNITS)
-			);
-
-			// If a lower bound CU is passed then enforce it
-			if (lowerBoundCu) {
-				bufferedComputeUnits = Math.max(
-					bufferedComputeUnits,
-					Math.min(lowerBoundCu, MAX_COMPUTE_UNITS)
-				);
-			}
-
-			return {
-				success: true as const,
-				computeUnits: bufferedComputeUnits,
-			};
-		} catch (e) {
-			console.warn(
-				`Failed to get Simulated Compute Units for txParamProcessor`,
-				e
-			);
-
-			return {
-				success: false as const,
-				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 async process(props: {
-		baseTxParams: BaseTxParams;
-		processConfig: ProcessingTxParams;
-		processParams: {
-			connection: Connection;
-			simulatedTx?: SimulatedTransactionResponse;
-		};
-		txBuilder: (
-			baseTransactionProps: TransactionBuildingProps
-		) => Promise<VersionedTransaction>;
-	}): Promise<BaseTxParams> {
-		// # Exit early if no process config is provided
-		if (!props.processConfig || Object.keys(props.processConfig).length === 0) {
-			return props.baseTxParams;
-		}
-
-		// # Setup
-		const {
-			txBuilder: txBuilder,
-			processConfig,
-			processParams: processProps,
-		} = props;
-
-		const finalTxParams: BaseTxParams = {
-			...props.baseTxParams,
-		};
-
-		// # Run Processes
-		if (processConfig.useSimulatedComputeUnits) {
-			const txToSim = await txBuilder({
-				txParams: { ...finalTxParams, computeUnits: MAX_COMPUTE_UNITS },
-			});
-
-			const txSimComputeUnitsResult = await this.getTxSimComputeUnits(
-				txToSim,
-				processProps.connection,
-				processConfig?.computeUnitsBufferMultiplier ??
-					COMPUTE_UNIT_BUFFER_FACTOR,
-				undefined,
-				processProps.simulatedTx
-			);
-
-			if (txSimComputeUnitsResult.success) {
-				// Adjust the transaction based on the simulated compute units
-				finalTxParams.computeUnits = txSimComputeUnitsResult.computeUnits;
-			}
-		}
-
-		if (processConfig?.useSimulatedComputeUnitsForCUPriceCalculation) {
-			if (!processConfig?.useSimulatedComputeUnits) {
-				throw new Error(
-					`encountered useSimulatedComputeUnitsForFees=true, but useSimulatedComputeUnits is false`
-				);
-			}
-			if (!processConfig?.getCUPriceFromComputeUnits) {
-				throw new Error(
-					`encountered useSimulatedComputeUnitsForFees=true, but getComputeUnitPriceFromUnitsToUse helper method is undefined`
-				);
-			}
-
-			const simulatedComputeUnits = finalTxParams.computeUnits;
-
-			if (simulatedComputeUnits === undefined) {
-				throw new Error(
-					`encountered useSimulatedComputeUnitsForFees=true, but simulated compute units are unavailable (simulation likely failed)`
-				);
-			}
-
-			const computeUnitPrice = processConfig.getCUPriceFromComputeUnits(
-				simulatedComputeUnits
-			);
-
-			console.debug(
-				`🔧:: Adjusting compute unit price for simulated compute unit budget :: ${finalTxParams.computeUnitsPrice}=>${computeUnitPrice}`
-			);
-
-			finalTxParams.computeUnitsPrice = computeUnitPrice;
-		}
-
-		// # Return Final Tx Params
-		return finalTxParams;
-	}
-}

package/src/tx/types.ts

@@ -1,117 +0,0 @@
-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 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 class TxSendError extends Error {
-	constructor(
-		public message: string,
-		public code: number
-	) {
-		super(message);
-		if (Error.captureStackTrace) {
-			Error.captureStackTrace(this, TxSendError);
-		}
-	}
-}

package/src/tx/utils.ts

@@ -1,133 +0,0 @@
-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 const MAX_TX_BYTE_SIZE = 1232;
-/** 4-byte magic prefix identifying velocity's native (non-Anchor) entrypoint instructions, followed by a 1-byte opcode — see `createNativeInstructionDiscriminatorBuffer`. */
-export const NATIVE_INSTRUCTION_MAGIC_BYTES = [0xff, 0xff, 0xff, 0xff];
-
-/**
- * Checks whether a transaction is a `VersionedTransaction` (v0+) rather than a legacy `Transaction`.
- * @param tx - Transaction to check.
- * @returns `true` if `tx` is versioned.
- */
-export const isVersionedTransaction = (
-	tx: Transaction | VersionedTransaction
-): boolean => {
-	const version = (tx as VersionedTransaction)?.version;
-	const isVersionedTx =
-		tx instanceof VersionedTransaction || version !== undefined;
-
-	return isVersionedTx;
-};
-
-/**
- * Estimates the serialized wire size (bytes) a transaction built from `instructions` would have,
- * without actually building/signing it — used to decide whether instructions still fit under
- * `MAX_TX_BYTE_SIZE` before committing to a blockhash/signature. Accounts for account
- * deduplication and, for versioned transactions, the byte savings from any accounts resolvable via
- * `addressLookupTables`.
- * @param instructions - Instructions the transaction would contain.
- * @param versionedTransaction - Whether to size as a v0 `VersionedTransaction` (includes the
- * version byte and lookup-table address/index overhead) or a legacy `Transaction`; defaults to `true`.
- * @param addressLookupTables - Lookup tables to credit toward reducing the static account-keys list.
- * @returns The estimated total transaction size in bytes.
- */
-export const getSizeOfTransaction = (
-	instructions: TransactionInstruction[],
-	versionedTransaction = true,
-	addressLookupTables: AddressLookupTableAccount[] = []
-): number => {
-	const programs = new Set<string>();
-	const signers = new Set<string>();
-	let accounts = new Set<string>();
-
-	instructions.forEach((ix) => {
-		try {
-			if (ix.programId) {
-				programs.add(ix.programId.toBase58());
-				accounts.add(ix.programId.toBase58());
-			}
-			if (ix.keys) {
-				ix.keys.forEach((key) => {
-					if (key.isSigner) {
-						signers.add(key.pubkey.toBase58());
-					}
-					accounts.add(key.pubkey.toBase58());
-				});
-			}
-		} catch (e) {
-			console.log(e);
-		}
-	});
-
-	const instructionSizes: number = instructions
-		.map(
-			(ix) =>
-				1 +
-				getSizeOfCompressedU16(ix.keys.length) +
-				ix.keys.length +
-				getSizeOfCompressedU16(ix.data.length) +
-				ix.data.length
-		)
-		.reduce((a, b) => a + b, 0);
-
-	let numberOfAddressLookups = 0;
-	// Filter out null/undefined lookup tables before accessing .state
-	const validLookupTables = addressLookupTables.filter(
-		(table): table is AddressLookupTableAccount =>
-			table !== null && table !== undefined
-	);
-	if (validLookupTables.length > 0) {
-		const lookupTableAddresses = validLookupTables
-			.map((addressLookupTable) =>
-				addressLookupTable.state.addresses.map((address) => address.toBase58())
-			)
-			.flat();
-		const totalNumberOfAccounts = accounts.size;
-		accounts = new Set(
-			[...accounts].filter((account) => !lookupTableAddresses.includes(account))
-		);
-		accounts = new Set([...accounts, ...programs, ...signers]);
-		numberOfAddressLookups = totalNumberOfAccounts - accounts.size;
-	}
-
-	return (
-		getSizeOfCompressedU16(signers.size) +
-		signers.size * 64 + // array of signatures
-		3 +
-		getSizeOfCompressedU16(accounts.size) +
-		32 * accounts.size + // array of account addresses
-		32 + // recent blockhash
-		getSizeOfCompressedU16(instructions.length) +
-		instructionSizes + // array of instructions
-		(versionedTransaction ? 1 + getSizeOfCompressedU16(0) : 0) +
-		(versionedTransaction ? 32 * addressLookupTables.length : 0) +
-		(versionedTransaction && addressLookupTables.length > 0 ? 2 : 0) +
-		numberOfAddressLookups
-	);
-};
-
-function getSizeOfCompressedU16(n: number) {
-	return 1 + Number(n >= 128) + Number(n >= 16384);
-}
-
-/**
- * Builds the 5-byte instruction-data prefix for velocity's native (non-Anchor) entrypoint:
- * `NATIVE_INSTRUCTION_MAGIC_BYTES` (`[0xFF, 0xFF, 0xFF, 0xFF]`) followed by a 1-byte opcode. Used
- * for high-frequency keeper instructions that bypass Anchor's instruction-dispatch overhead.
- * @param discriminator - The native instruction's opcode byte.
- * @returns The 5-byte discriminator buffer to prepend to the instruction's data.
- */
-export function createNativeInstructionDiscriminatorBuffer(
-	discriminator: number
-): Uint8Array {
-	const buffer = new Uint8Array(5);
-	buffer.set(NATIVE_INSTRUCTION_MAGIC_BYTES, 0);
-	buffer.set([discriminator], 4);
-	return buffer;
-}