@naculus/connect-appkit-react 0.1.2

package/src/hooks/useTransactionSimulation.ts

@@ -0,0 +1,401 @@
+/**
+ * useTransactionSimulation — React hook for simulating transactions
+ *                           before signing/submitting.
+ *
+ * Provides a reactive SimulationResult that updates when tx parameters change.
+ * Uses the simulation module from @naculus/connect-core.
+ *
+ * @see /docs/features/transaction-simulation.md
+ */
+
+import { useState, useCallback, useEffect, useRef } from "react";
+import { useWeb3 } from "../provider/Web3ConnectProvider";
+import { useAccount } from "./useAccount";
+import { useChain } from "./useChain";
+import { useViemClient } from "./useViemClient";
+
+import type { EvmTransaction } from "../types";
+
+// ── Types (mirrored from @naculus/connect-core simulation module) ──
+
+export type SimulationStatus = "success" | "reverted" | "unavailable";
+
+export type RiskLevel = "safe" | "warning" | "malicious" | "unknown";
+
+export interface SimulationResult {
+  status: SimulationStatus;
+  revertReason?: string;
+  balanceChanges: BalanceChange[];
+  approvalChanges: ApprovalChange[];
+  riskAssessment: RiskAssessment;
+  gasInfo?: GasInfo;
+  provider: string;
+  summary?: string;
+  changesDetected: boolean;
+}
+
+export interface BalanceChange {
+  tokenAddress: string;
+  tokenSymbol: string;
+  tokenDecimals: number;
+  amount: string;
+  direction: "in" | "out";
+  from: string;
+  to: string;
+  humanReadable: string;
+}
+
+export interface ApprovalChange {
+  tokenAddress: string;
+  tokenSymbol: string;
+  owner: string;
+  spender: string;
+  amount: string;
+  isUnlimited: boolean;
+  humanReadable: string;
+}
+
+export interface RiskAssessment {
+  level: RiskLevel;
+  score: number;
+  warnings: RiskWarning[];
+}
+
+export interface RiskWarning {
+  category: string;
+  severity: string;
+  message: string;
+}
+
+export interface GasInfo {
+  gasLimit: bigint;
+  gasPrice?: bigint;
+  estimatedFeeEth?: string;
+  estimatedFeeUsd?: string;
+}
+
+// ── Hook return type ──────────────────────────────────────────────
+
+export interface UseTransactionSimulationReturn {
+  /** Current simulation result (undefined until first run) */
+  result: SimulationResult | undefined;
+  /** Whether a simulation is in progress */
+  isSimulating: boolean;
+  /** Error from the last simulation attempt */
+  error: Error | null;
+  /** Manually trigger a simulation */
+  simulate: () => Promise<SimulationResult>;
+  /** Reset the simulation state */
+  reset: () => void;
+}
+
+// ── Default owner address for eth_call ────────────────────────────
+
+function getNativeSymbol(chainId: number): string {
+  const ethChains = [1, 5, 11155111, 10, 42161, 421614, 8453, 84532];
+  const maticChains = [137, 80002];
+  const bnbChains = [56, 97];
+
+  if (ethChains.includes(chainId)) return "ETH";
+  if (maticChains.includes(chainId)) return "MATIC";
+  if (bnbChains.includes(chainId)) return "BNB";
+  return "ETH";
+}
+
+// ── Hook ──────────────────────────────────────────────────────────
+
+export function useTransactionSimulation(
+  tx: EvmTransaction | undefined,
+  chainId?: number,
+): UseTransactionSimulationReturn {
+  const { session } = useWeb3();
+  const { evmAccount, isConnected } = useAccount();
+  const { currentChain } = useChain();
+  const { publicClient } = useViemClient();
+
+  const [result, setResult] = useState<SimulationResult | undefined>(undefined);
+  const [isSimulating, setIsSimulating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Debounce ref to avoid rapid re-simulations
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  // ── Core simulation logic ───────────────────────────────────────
+
+  const simulate = useCallback(async (): Promise<SimulationResult> => {
+    if (!tx) {
+      const noTxResult: SimulationResult = {
+        status: "unavailable" as SimulationStatus,
+        balanceChanges: [],
+        approvalChanges: [],
+        riskAssessment: { level: "unknown" as RiskLevel, score: 0, warnings: [] },
+        provider: "eth_call",
+        summary: "No transaction to simulate",
+        changesDetected: false,
+      };
+      setResult(noTxResult);
+      return noTxResult;
+    }
+
+    setIsSimulating(true);
+    setError(null);
+
+    try {
+      // Determine the target chain ID
+      const targetChainId = chainId ?? currentChain?.id ?? 1;
+
+      // Determine RPC URL from the current chain context
+      const rpcUrl = currentChain?.rpcUrl;
+
+      // If we have a viem publicClient, use it for eth_call simulation
+      if (publicClient) {
+        try {
+          const from = evmAccount?.includes(":")
+            ? (evmAccount.split(":").pop() as `0x${string}`)
+            : evmAccount;
+
+          const callParams: any = {
+            to: tx.to as `0x${string}`,
+            data: (tx.data ?? "0x") as `0x${string}`,
+            value: tx.value ? BigInt(tx.value) : 0n,
+          };
+
+          if (from) {
+            callParams.from = from as `0x${string}`;
+          }
+
+          await publicClient.call(callParams);
+
+          // eth_call succeeded — transaction won't revert
+          const simResult: SimulationResult = {
+            status: "success",
+            balanceChanges: [],
+            approvalChanges: [],
+            riskAssessment: { level: "unknown", score: 0, warnings: [] },
+            gasInfo: tx.gas
+              ? { gasLimit: BigInt(tx.gas), estimatedFeeEth: "0" }
+              : undefined,
+            provider: "eth_call",
+            summary: "Transaction simulation succeeded (basic revert check only)",
+            changesDetected: true,
+          };
+          setResult(simResult);
+          return simResult;
+        } catch (callErr: any) {
+          // eth_call reverted — extract reason
+          let revertReason: string | undefined;
+          const errMsg = callErr?.message ?? String(callErr);
+          const errData = callErr?.data ?? callErr?.cause?.data;
+
+          // Try to extract human-readable revert reason
+          if (errData && typeof errData === "string") {
+            const clean = errData.startsWith("0x") ? errData.slice(2) : errData;
+            if (clean.startsWith("08c379a0") && clean.length > 138) {
+              // Error(string) — ABI decode
+              const length = parseInt(clean.slice(72, 136), 16);
+              if (length > 0) {
+                const msgHex = clean.slice(136, 136 + length * 2);
+                const bytes = new Uint8Array(length);
+                for (let i = 0; i < length; i++) {
+                  bytes[i] = parseInt(msgHex.slice(i * 2, i * 2 + 2), 16);
+                }
+                revertReason = new TextDecoder().decode(bytes);
+              }
+            } else if (clean.startsWith("4e487b71")) {
+              revertReason = `Panic: Built-in failure`;
+            }
+          }
+
+          if (!revertReason) {
+            revertReason = errMsg.includes("revert")
+              ? errMsg
+              : "Transaction reverted";
+          }
+
+          const simResult: SimulationResult = {
+            status: "reverted",
+            revertReason,
+            balanceChanges: [],
+            approvalChanges: [],
+            riskAssessment: {
+              level: "unknown",
+              score: 0,
+              warnings: [
+                {
+                  category: "simulation_failed",
+                  severity: "high",
+                  message: revertReason
+                    ? `Transaction would revert: ${revertReason}`
+                    : "Transaction would revert",
+                },
+              ],
+            },
+            provider: "eth_call",
+            summary: revertReason
+              ? `Transaction reverted: ${revertReason}`
+              : "Transaction reverted",
+            changesDetected: false,
+          };
+          setResult(simResult);
+          return simResult;
+        }
+      }
+
+      // Fallback: raw fetch eth_call
+      if (rpcUrl) {
+        try {
+          const response = await fetch(rpcUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              jsonrpc: "2.0",
+              id: Date.now(),
+              method: "eth_call",
+              params: [
+                {
+                  to: tx.to,
+                  from: evmAccount?.includes(":")
+                    ? evmAccount.split(":").pop()
+                    : evmAccount,
+                  data: tx.data ?? "0x",
+                  value: tx.value ?? "0x0",
+                },
+                "latest",
+              ],
+            }),
+          });
+
+          const json: any = await response.json();
+
+          if (json.error) {
+            const simResult: SimulationResult = {
+              status: "reverted",
+              balanceChanges: [],
+              approvalChanges: [],
+              riskAssessment: {
+                level: "unknown",
+                score: 0,
+                warnings: [
+                  {
+                    category: "simulation_failed",
+                    severity: "high",
+                    message: `Transaction would revert: ${json.error.message}`,
+                  },
+                ],
+              },
+              provider: "eth_call",
+              summary: "Transaction reverted",
+              changesDetected: false,
+            };
+            setResult(simResult);
+            return simResult;
+          }
+
+          const simResult: SimulationResult = {
+            status: "success",
+            balanceChanges: [],
+            approvalChanges: [],
+            riskAssessment: { level: "unknown", score: 0, warnings: [] },
+            provider: "eth_call",
+            summary: "Transaction simulation succeeded",
+            changesDetected: true,
+          };
+          setResult(simResult);
+          return simResult;
+        } catch (fetchErr: any) {
+          // Network error
+          const simResult: SimulationResult = {
+            status: "unavailable",
+            balanceChanges: [],
+            approvalChanges: [],
+            riskAssessment: {
+              level: "unknown",
+              score: 0,
+              warnings: [
+                {
+                  category: "simulation_failed",
+                  severity: "medium",
+                  message: `Network error: ${fetchErr?.message ?? "Unknown"}`,
+                },
+              ],
+            },
+            provider: "eth_call",
+            summary: "Simulation unavailable due to network error",
+            changesDetected: false,
+          };
+          setResult(simResult);
+          return simResult;
+        }
+      }
+
+      // No RPC URL available
+      const simResult: SimulationResult = {
+        status: "unavailable",
+        balanceChanges: [],
+        approvalChanges: [],
+        riskAssessment: {
+          level: "unknown",
+          score: 0,
+          warnings: [
+            {
+              category: "simulation_failed",
+              severity: "low",
+              message: "No RPC URL or public client available for simulation",
+            },
+          ],
+        },
+        provider: "eth_call",
+        summary: "Simulation unavailable: no RPC URL",
+        changesDetected: false,
+      };
+      setResult(simResult);
+      return simResult;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Simulation failed");
+      setError(error);
+      throw error;
+    } finally {
+      setIsSimulating(false);
+    }
+  }, [tx, chainId, currentChain, publicClient, evmAccount]);
+
+  // ── Auto-simulate on tx change (debounced) ──────────────────────
+
+  useEffect(() => {
+    if (!tx) return;
+
+    // Clear previous debounce
+    if (debounceRef.current) {
+      clearTimeout(debounceRef.current);
+    }
+
+    // Debounce: wait 300ms after last tx change before simulating
+    debounceRef.current = setTimeout(() => {
+      simulate().catch(() => {
+        // Silently handle; errors are captured in state
+      });
+    }, 300);
+
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [tx, simulate]);
+
+  // ── Reset ───────────────────────────────────────────────────────
+
+  const reset = useCallback(() => {
+    setResult(undefined);
+    setError(null);
+    setIsSimulating(false);
+  }, []);
+
+  return {
+    result,
+    isSimulating,
+    error,
+    simulate,
+    reset,
+  };
+}

package/src/hooks/useTxHistory.test.ts

@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { useTxHistory } from "./useTxHistory";
+import type { TxMonitorLike, TxStatusEntry } from "./useTxMonitor";
+
+class MockMonitor implements TxMonitorLike {
+  private entries: TxStatusEntry[] = [];
+  private listeners = new Map<string, Set<Function>>();
+
+  setEntries(entries: TxStatusEntry[]): void {
+    this.entries = entries;
+  }
+
+  async watchTx(): Promise<TxStatusEntry> {
+    throw new Error("not implemented");
+  }
+  stopWatching(): void {}
+  getTxStatus(): TxStatusEntry | null { return null; }
+
+  async getTxHistory(): Promise<TxStatusEntry[]> {
+    return this.entries;
+  }
+  async refreshTx(): Promise<void> {}
+
+  on(event: string, listener: Function): this {
+    const set = this.listeners.get(event) ?? new Set();
+    set.add(listener);
+    this.listeners.set(event, set);
+    return this;
+  }
+  off(event: string, listener: Function): this {
+    const set = this.listeners.get(event);
+    if (set) set.delete(listener);
+    return this;
+  }
+
+  emit(event: string, ...args: any[]): void {
+    const set = this.listeners.get(event);
+    if (set) set.forEach(fn => fn(...args));
+  }
+}
+
+describe("useTxHistory", () => {
+  let monitor: MockMonitor;
+
+  beforeEach(() => {
+    monitor = new MockMonitor();
+  });
+
+  it("returns empty array when no history exists", async () => {
+    const { result } = renderHook(() => useTxHistory(undefined, undefined, monitor));
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false);
+    });
+
+    expect(result.current.entries).toEqual([]);
+    expect(result.current.summary.pending).toBe(0);
+    expect(result.current.summary.confirmed).toBe(0);
+    expect(result.current.summary.failed).toBe(0);
+  });
+
+  it("returns history entries", async () => {
+    const entry: TxStatusEntry = {
+      hash: "0x" + "a".repeat(64), chainId: 1,
+      from: "", to: "", value: "0x0",
+      status: "confirmed", createdAt: Date.now(), updatedAt: Date.now(),
+      replacementCount: 0,
+    };
+    monitor.setEntries([entry]);
+
+    const { result } = renderHook(() => useTxHistory(undefined, undefined, monitor));
+
+    await waitFor(() => {
+      expect(result.current.entries.length).toBe(1);
+    });
+
+    expect(result.current.entries[0].hash).toBe(entry.hash);
+    expect(result.current.summary.confirmed).toBe(1);
+  });
+
+  it("provides status summary counts", async () => {
+    const now = Date.now();
+    monitor.setEntries([
+      { hash: "0x1" + "a".repeat(63), chainId: 1, from: "", to: "", value: "0x0",
+        status: "pending", createdAt: now, updatedAt: now, replacementCount: 0 },
+      { hash: "0x2" + "b".repeat(63), chainId: 1, from: "", to: "", value: "0x0",
+        status: "confirmed", createdAt: now, updatedAt: now, replacementCount: 0, confirmedAt: now },
+      { hash: "0x3" + "c".repeat(63), chainId: 1, from: "", to: "", value: "0x0",
+        status: "failed", createdAt: now, updatedAt: now, replacementCount: 0, error: "reverted" },
+      { hash: "0x4" + "d".repeat(63), chainId: 1, from: "", to: "", value: "0x0",
+        status: "confirmed", createdAt: now, updatedAt: now, replacementCount: 0, confirmedAt: now },
+    ]);
+
+    const { result } = renderHook(() => useTxHistory(undefined, undefined, monitor));
+
+    await waitFor(() => {
+      expect(result.current.entries.length).toBe(4);
+    });
+
+    expect(result.current.summary).toEqual({
+      pending: 1,
+      confirmed: 2,
+      failed: 1,
+    });
+  });
+});

package/src/hooks/useTxHistory.ts

@@ -0,0 +1,83 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import type { TxMonitorLike, TxStatusEntry, TxStatus } from "./useTxMonitor";
+import { useTxMonitorProvider } from "./useTxMonitor";
+
+// ── Hook ──────────────────────────────────────────────────────────
+
+export interface UseTxHistoryResult {
+  entries: TxStatusEntry[];
+  isLoading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  summary: {
+    pending: number;
+    confirmed: number;
+    failed: number;
+  };
+}
+
+/**
+ * Query transaction history.
+ * address defaults to current wallet address; chainId defaults to current chain.
+ */
+export function useTxHistory(
+  address?: string,
+  chainId?: number,
+  monitor?: TxMonitorLike,
+): UseTxHistoryResult {
+  const ctxMonitor = useTxMonitorProvider();
+  const effectiveMonitor = monitor ?? ctxMonitor;
+
+  const [entries, setEntries] = useState<TxStatusEntry[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const refreshCounter = useRef(0);
+
+  const refresh = useCallback(async () => {
+    if (!effectiveMonitor) return;
+    setIsLoading(true);
+    setError(null);
+    refreshCounter.current++;
+    try {
+      const results = await effectiveMonitor.getTxHistory(address, chainId);
+      setEntries(results);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      setIsLoading(false);
+    }
+  }, [effectiveMonitor, address, chainId]);
+
+  useEffect(() => {
+    refresh().catch(() => {});
+  }, [refresh]);
+
+  // Listen for status changes to update entries reactively
+  useEffect(() => {
+    if (!effectiveMonitor) return;
+
+    const onStatusChange = () => {
+      // Re-fetch on any status change
+      refresh().catch(() => {});
+    };
+    effectiveMonitor.on("statusChange", onStatusChange);
+
+    return () => {
+      effectiveMonitor.off("statusChange", onStatusChange as any);
+    };
+  }, [effectiveMonitor, refresh]);
+
+  const summary = {
+    pending: entries.filter(e => e.status === "pending").length,
+    confirmed: entries.filter(e => e.status === "confirmed").length,
+    failed: entries.filter(e => e.status === "failed").length,
+  };
+
+  return {
+    entries,
+    isLoading,
+    error,
+    refresh,
+    summary,
+  };
+}