Why Web3 Transaction State Management is Broken (And Why useState is an Anti-Pattern)

// ⚠️ THE FATAL ANTI-PATTERN: Component-bound transaction state
export function SwapButton() {
  const [isLoading, setIsLoading] = useState(false);
  const [txHash, setTxHash] = useState<string | null>(null);
 
  const handleDeposit = async () => {
    try {
      setIsLoading(true);
      // Step 1: Wallet signature & broadcast
      const hash = await walletClient.sendTransaction({ ... });
      setTxHash(hash);
 
      // Step 2: Awaiting on-chain receipt in component memory
      await publicClient.waitForTransactionReceipt({ hash });
      toast.success('Transaction confirmed!');
    } catch (error) {
      console.error('Transaction failed:', error);
      toast.error('Transaction reverted');
    } finally {
      setIsLoading(false);
    }
  };
 
  return (
    <button onClick={handleDeposit} disabled={isLoading}>
      {isLoading ? 'Processing...' : 'Deposit Funds'}
    </button>
  );
}

Pending  ──►  Resolved (200 OK)   or   Rejected (500 Error)

Hash(T2) ≠ Hash(T1)    (Account Nonce N is identical)

// Naive component handler:
const receipt = await publicClient.waitForTransactionReceipt({ hash: H1 });

┌─────────────────────────────────────────────────────────────┐
│                  Blockchain Transports Layer                │
│    Viem (EVM) • @solana/kit (Solana) • Bundlers (ERC-4337)  │
└──────────────────────────────┬──────────────────────────────┘
                               │ (Dispatched Actions)
                               ▼
┌──────────────────────────────┴──────────────────────────────┐
│              Headless Engine (@tuwaio/pulsar-core)          │
│  • Local-first Indexed/LocalStorage Persistence (Immer)     │
│  • Nonce-aware Mempool Replacement Watcher (onReplaced)     │
│  • Auto-reconnection & Polling Resumption after Reload      │
└──────────────────────────────┬──────────────────────────────┘
                               │ (Passive Subscriptions)
                               ▼
┌──────────────────────────────┴──────────────────────────────┐
│                 React View Layer (Passive)                  │
│       Subscribes to selectors: usePulsarStore(...)          │
└─────────────────────────────────────────────────────────────┘

// src/types/transactions.ts
import type { EvmTransaction, SolanaTransaction } from '@tuwaio/sdk/pulsar';
 
export enum AppTxType {
  TOKEN_SWAP = 'TOKEN_SWAP',
  STAKE_COLLATERAL = 'STAKE_COLLATERAL',
}
 
export type TokenSwapTx = EvmTransaction & {
  type: AppTxType.TOKEN_SWAP;
  payload: {
    tokenIn: string;
    tokenOut: string;
    amount: string;
  };
};
 
export type TransactionUnion = TokenSwapTx | SolanaTransaction;

// src/stores/pulsarStore.ts
'use client';
 
import { pulsarEvmAdapter } from '@tuwaio/evm-sdk/pulsar';
import { preFlightTxCheck } from '@tuwaio/quasar-sdk/react';
import { createBoundedUseStore, createPulsarStore } from '@tuwaio/sdk/pulsar';
import { pulsarSolanaAdapter } from '@tuwaio/solana-sdk/pulsar';
 
import { syncTransaction } from '@/app/actions';
import { wagmiConfig, appChains, solanaRPCUrls } from '@/configs/web3';
import { QUASAR_BASE_URL } from '@/constants';
import type { TransactionUnion } from '@/types/transactions';
 
const initialStore = createPulsarStore<TransactionUnion>({
  name: 'tuwa-transactions-storage',
  adapter: [pulsarEvmAdapter(wagmiConfig, appChains), pulsarSolanaAdapter({ rpcUrls: solanaRPCUrls })],
  // Pre-flight: verify the SIWX session and that the Quasar engine (Cloud or self-hosted) is reachable
  beforeTxProcess: async () => {
    await preFlightTxCheck(QUASAR_BASE_URL);
  },
  // Background sync: delegate to a Server Action that verifies SIWX session
  // server-side and forwards the transaction to Quasar Engine via Secret Key
  // Throw on failure: Pulsar then keeps the transaction marked as unsynced and sends it again later
  onRemoteCreate: async (tx) => {
    const result = await syncTransaction(tx);
    if (!result.success) throw new Error(result.reason ?? 'Remote sync failed');
  },
});
 
export const usePulsarStore = createBoundedUseStore(initialStore);

// src/app/actions.ts
'use server';
 
import { Quasar, Transaction } from '@tuwaio/quasar-sdk';
import { getSiwxServerSession, isSessionMatchingTarget } from '@tuwaio/sdk/siwx/server';
import { cookies } from 'next/headers';
 
import { QUASAR_BASE_URL } from '@/constants';
 
const quasar = new Quasar({
  baseUrl: QUASAR_BASE_URL,
  secretKey: process.env.QUASAR_SECRET_KEY ?? '',
});
 
export async function syncTransaction(tx: Transaction) {
  const session = await getSiwxServerSession({
    cookieSource: await cookies(),
    cookieName: 'siwx-session',
    signingSecret: process.env.SIWX_SIGNING_SECRET!,
  });
 
  if (!session) {
    return { success: false, reason: 'unauthenticated' };
  }
 
  // Verify the SIWX session wallet matches the transaction sender
  if (tx.from && !isSessionMatchingTarget(session, tx.from, tx.chainId)) {
    return { success: false, reason: 'session_mismatch' };
  }
 
  await quasar.pulsar.syncCreate(tx, 'my-dapp');
  return { success: true };
}

// src/transactions/evm/swapTokens.ts
import { writeContract } from '@wagmi/core';
import { parseUnits } from 'viem';
import { wagmiConfig } from '@/configs/wagmi';
import { ROUTER_ABI, ROUTER_ADDRESS } from '@/contracts/router';
 
export async function swapTokens({
  tokenIn,
  tokenOut,
  amount,
  recipient,
}: {
  tokenIn: `0x${string}`;
  tokenOut: `0x${string}`;
  amount: string;
  recipient: `0x${string}`;
}) {
  return writeContract(wagmiConfig, {
    abi: ROUTER_ABI,
    address: ROUTER_ADDRESS,
    functionName: 'exactInputSingle',
    args: [
      {
        tokenIn,
        tokenOut,
        fee: 3000,
        recipient,
        amountIn: parseUnits(amount, 6),
        amountOutMinimum: 0n,
        sqrtPriceLimitX96: 0n,
      },
    ],
    chainId: 1,
  });
}

// src/components/SwapActionButton.tsx
'use client';
 
import { usePulsarStore } from '@/stores/pulsarStore';
import { OrbitAdapter } from '@tuwaio/sdk/orbit';
import { AppTxType } from '@/types/transactions';
import { swapTokens } from '@/transactions/evm/swapTokens';
 
export function SwapActionButton({
  amount,
  tokenIn,
  tokenOut,
  recipient,
}: {
  amount: string;
  tokenIn: `0x${string}`;
  tokenOut: `0x${string}`;
  recipient: `0x${string}`;
}) {
  const executeTxAction = usePulsarStore((state) => state.executeTxAction);
 
  const handleSwap = async () => {
    await executeTxAction({
      actionFunction: () => swapTokens({ tokenIn, tokenOut, amount, recipient }),
      params: {
        type: AppTxType.TOKEN_SWAP,
        adapter: OrbitAdapter.EVM,
        desiredChainID: 1, // Automatic chain validation & switching
        title: ['Swapping Tokens', 'Swap Confirmed', 'Swap Failed', 'Transaction Sped Up'],
        description: [
          `Swapping ${amount} USDC for ETH...`,
          `Successfully swapped ${amount} USDC for ETH.`,
          'Transaction reverted on-chain.',
          'Gas fee was increased; replacement hash emitted via callback.',
        ],
        payload: {
          tokenIn,
          tokenOut,
          amount,
        },
        withTrackedModal: true, // Triggers Nova UIKit modal sheet
        requiredConfirmations: 2, // Wait for safe consensus depth
      },
      onSuccess: (tx) => {
        console.log('[Pulsar] Transaction finalized:', tx.txKey);
      },
      onReplaced: (newTx, oldTx) => {
        // Pulsar flags oldTx as Replaced (pending: false), persists replacedTxHash, and fires callback
        console.warn(`[Pulsar] Transaction ${oldTx.txKey} was replaced by: ${newTx.replacedTxHash}`);
      },
      onError: (err, tx) => {
        console.error('[Pulsar] Execution error:', err);
      },
    });
  };
 
  return (
    <button onClick={handleSwap} className="btn-primary">
      Execute Swap
    </button>
  );
}

// src/app/providers.tsx
'use client';
 
import { useEffect } from 'react';
import { usePulsarStore } from '@/stores/pulsarStore';
 
export function TransactionTrackerBootstrap({ children }: { children: React.ReactNode }) {
  const initializeTransactionsPool = usePulsarStore((s) => s.initializeTransactionsPool);
 
  useEffect(() => {
    // Automatically re-attaches trackers to all unconfirmed mempool transactions
    initializeTransactionsPool();
  }, [initializeTransactionsPool]);
 
  return <>{children}</>;
}

// src/components/PendingTransactionsBadge.tsx
import { usePulsarStore } from '@/stores/pulsarStore';
import { selectPendingTransactions } from '@tuwaio/sdk/pulsar';
 
export function PendingTransactionsBadge() {
  const pendingTransactions = usePulsarStore((state) => selectPendingTransactions(state.transactionsPool));
 
  if (pendingTransactions.length === 0) return null;
 
  return (
    <div className="flex items-center gap-2 px-3 py-1 bg-amber-500/10 text-amber-500 rounded-full border border-amber-500/20 text-xs font-mono">
      <span className="w-2 h-2 rounded-full bg-amber-500 animate-ping" />
      <span>{pendingTransactions.length} pending on-chain</span>
    </div>
  );
}

// src/components/BalanceRefresher.tsx
'use client';
 
import { TransactionStatus, useTxFinished } from '@tuwaio/sdk/pulsar';
 
import { usePulsarStore } from '@/stores/pulsarStore';
import { AppTxType } from '@/types/transactions';
 
export function BalanceRefresher({ refetchBalances }: { refetchBalances: () => void }) {
  const subscribeTxFinished = usePulsarStore((state) => state.subscribeTxFinished);
 
  // Also runs for a swap whose tracker was restarted after a reload
  useTxFinished({
    subscribeTxFinished,
    onFinished: (tx) => {
      if (tx.type === AppTxType.TOKEN_SWAP && tx.status === TransactionStatus.Success) refetchBalances();
    },
  });
 
  return null;
}