UX.SOL

Hook

useTransactionSimulation

Simulates Solana transactions before requesting a wallet signature.

Installation

terminal
$npx shadcn@latest add https://uxdotsol.xyz/r/use-transaction-simulation.json

Usage

use-transaction-simulation.tsx
"use client";
 
import type {
Connection,
Transaction,
VersionedTransaction,
} from "@solana/web3.js";
import { useTransactionSimulation } from "@/hooks/use-transaction-simulation";
 
type TransferReviewProps = {
connection: Connection;
transaction: Transaction | VersionedTransaction;
onContinue: () => void;
};
 
export function TransferReview({
connection,
transaction,
onContinue,
}: TransferReviewProps) {
const simulation = useTransactionSimulation({ client: connection, transaction });
 
return (
<section>
<h2>Review transfer</h2>
<button
onClick={() => simulation.simulate()}
disabled={!simulation.canSimulate || simulation.isSimulating}
>
{simulation.isSimulating ? "Checking transfer..." : "Check before signing"}
</button>
 
{simulation.status === "success" ? (
<p>Ready to sign. Estimated compute: {simulation.unitsConsumed ?? "unknown"} units.</p>
) : null}
{simulation.hasError ? (
<p role="alert">This transfer would fail. Review the amount and recipient.</p>
) : null}
 
<button disabled={simulation.status !== "success"} onClick={onContinue}>
Continue to wallet
</button>
</section>
);
}

Options

NameTypeDefaultDescription
clientConnection | KitRpcLikeundefinedweb3.js connection or kit-style RPC client.
transactionTransaction | VersionedTransaction | string | Uint8ArrayundefinedTransaction object or base64/byte payload to simulate.
commitmentCommitment'processed'Commitment used for simulation requests.
replaceRecentBlockhashbooleantrueAsks RPC to simulate with a fresh blockhash when supported.
sigVerifybooleanfalseVerifies signatures during versioned transaction simulation.

Functions

NameTypeDefaultDescription
simulate(override?: Partial<TransactionSimulationOptions>) => Promise<TransactionSimulationResult | null>-Runs simulation with hook options plus optional per-call overrides.
reset() => void-Clears simulation state back to idle.

Types

NameTypeDefaultDescription
TransactionSimulationStatus'idle' | 'simulating' | 'success' | 'failed'-Finite states exposed by the hook.
SimulationClientConnection | KitRpcLike-Supported RPC client shapes.

Returns

NameTypeDefaultDescription
statusTransactionSimulationStatus'idle'Current simulation state.
valueSimulatedTransactionResponse | unknown | nullnullRaw RPC simulation response.
logs / unitsConsumedstring[] / number | null[] / nullParsed logs and compute units when RPC returns them.
canSimulate / isSimulating / hasErrorbooleanfalseConvenience flags for UI state.