UX.SOL

Hook

useOptimisticTransaction

Manages optimistic transaction state with confirmation and rollback handling.

Installation

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

Usage

use-optimistic-transaction.tsx
"use client";
 
import { useOptimisticTransaction } from "@/hooks/use-optimistic-transaction";
 
type UsdcPaymentProps = {
currentBalance: number;
amount: number;
sendPayment: () => Promise<string>;
confirmPayment: (signature: string) => Promise<void>;
};
 
export function UsdcPayment({
currentBalance,
amount,
sendPayment,
confirmPayment,
}: UsdcPaymentProps) {
const payment = useOptimisticTransaction({
initialState: { balance: currentBalance },
apply: (state) => ({ balance: state.balance - amount }),
transaction: sendPayment,
confirm: confirmPayment,
});
 
async function pay() {
try {
await payment.run();
} catch {
// The balance is rolled back and the hook exposes the error.
}
}
 
return (
<section>
<p>USDC balance: {payment.state.balance.toFixed(2)}</p>
<button disabled={payment.isPending} onClick={pay}>
{payment.isPending ? "Confirming payment..." : `Pay ${amount} USDC`}
</button>
{payment.status === "rolled-back" ? (
<p role="alert">Payment failed. Your displayed balance was restored.</p>
) : null}
</section>
);
}

Options

NameTypeDefaultDescription
initialStateTStaterequiredInitial UI state controlled by the hook.
transaction() => Promise<TResult>requiredAsync transaction or send+confirm operation.
apply(state: TState) => TStaterequiredCreates the optimistic state.
rollback(previousState, error) => TStatepreviousStateRestores or adjusts state after failure.
confirm(result: TResult) => Promise<unknown>undefinedOptional post-send confirmation step.

Functions

NameTypeDefaultDescription
run(override?: Partial<Options>) => Promise<TResult>-Applies optimistic state, runs transaction, confirms, and rolls back on failure.
reset(nextState?: TState) => voidinitialStateResets hook state and clears result/error.
setStateDispatch<SetStateAction<TState>>-Direct state setter for controlled UI updates.

Types

NameTypeDefaultDescription
OptimisticTransactionStatus'idle' | 'optimistic' | 'confirming' | 'confirmed' | 'rolled-back'-Current optimistic transaction phase.

Returns

NameTypeDefaultDescription
state / statusTState / OptimisticTransactionStatusinitialState / 'idle'Current UI state and transaction phase.
error / resultunknown / TResult | nullnullFailure cause or transaction result.
isPendingbooleanfalseTrue during optimistic or confirming phases.