Clear signing in React: building a transaction preview users can trust

TAIWO EMMANUEL / CODE NOTE

TSCOPYDOWNLOAD

import { decodeFunctionData, erc20Abi, maxUint256, type Hex } from "viem";

export type Authorization = { chainId: number; address: Hex; nonce: number }; // EIP-7702 tuple
export type TxRequest = { to: Hex; data: Hex; value: bigint; authorizationList?: Authorization[] };

export type Risk = { level: "low" | "medium" | "critical"; reasons: string[] };
export type Decoded = { summary: string; functionName?: string; args?: readonly unknown[] };

export function decode(tx: TxRequest): Decoded {
  if (tx.authorizationList?.length) {
    const targets = tx.authorizationList.map((a) => a.address).join(", ");
    return { summary: `Delegate control of this account to ${targets}` };
  }
  try {
    const { functionName, args } = decodeFunctionData({ abi: erc20Abi, data: tx.data });
    return { summary: `${functionName} on token ${tx.to}`, functionName, args };
  } catch {
    return { summary: "Unknown contract call. The function could not be decoded." };
  }
}

export function assess(tx: TxRequest, decoded: Decoded, knownContracts: ReadonlySet<string>): Risk {
  const reasons: string[] = [];
  if (tx.authorizationList?.length) reasons.push("Account delegation: the delegate gains control of every asset.");
  if (decoded.functionName === "approve" && decoded.args?.[1] === maxUint256) reasons.push("Unlimited token approval.");
  if (!decoded.functionName && !tx.authorizationList?.length) reasons.push("Payload could not be decoded.");
  if (!knownContracts.has(tx.to.toLowerCase())) reasons.push("Interacting with a contract outside your address book.");
  const level = tx.authorizationList?.length || decoded.functionName === undefined ? "critical" : reasons.length ? "medium" : "low";
  return { level, reasons };
}

TAIWO EMMANUEL / CODE NOTE

TSCOPYDOWNLOAD

import { useQuery } from "@tanstack/react-query";
import { keccak256, toHex } from "viem";
import type { TxRequest } from "./assess";

export const fingerprint = (tx: TxRequest) =>
  keccak256(toHex(JSON.stringify(tx, (_key, value) => (typeof value === "bigint" ? value.toString() : value))));

export type Simulation = { blockNumber: number; balanceChanges: { asset: string; delta: string }[]; reverted: boolean };

export function useSimulation(tx: TxRequest, latestBlock: number | undefined) {
  const id = fingerprint(tx);
  return useQuery({
    queryKey: ["simulation", id, latestBlock],
    enabled: latestBlock !== undefined,
    queryFn: async ({ signal }) => {
      const response = await fetch("/api/simulate", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ tx, blockNumber: latestBlock }, (_k, v) => (typeof v === "bigint" ? v.toString() : v)),
        signal,
      });
      if (!response.ok) throw new Error("Simulation failed");
      return { fingerprint: id, ...((await response.json()) as Simulation) };
    },
    staleTime: 4_000,
    // Deliberately no placeholderData (e.g. keepPreviousData): the previous block's preview must never pose as current.
  });
}

TAIWO EMMANUEL / CODE NOTE

TSCOPYDOWNLOAD

import { create } from "zustand";

type Phase = "reviewing" | "signing" | "submitted" | "aborted";

type SigningSession = {
  phase: Phase;
  reviewed: { fingerprint: string; blockNumber: number } | null;
  criticalAcknowledged: boolean;
  markReviewed: (fingerprint: string, blockNumber: number) => void;
  acknowledgeCritical: () => void;
  beginSigning: (requestFingerprint: string, latestBlock: number) => boolean;
  finish: (outcome: "submitted" | "aborted") => void;
};

export const useSigningSession = create<SigningSession>()((set, get) => ({
  phase: "reviewing",
  reviewed: null,
  criticalAcknowledged: false,
  markReviewed: (fingerprint, blockNumber) => set({ reviewed: { fingerprint, blockNumber } }),
  acknowledgeCritical: () => set({ criticalAcknowledged: true }),
  beginSigning: (requestFingerprint, latestBlock) => {
    const { phase, reviewed } = get();
    const fresh = reviewed !== null && reviewed.blockNumber >= latestBlock - 1;
    if (phase !== "reviewing" || !fresh || reviewed.fingerprint !== requestFingerprint) return false;
    set({ phase: "signing" });
    return true;
  },
  finish: (outcome) => set({ phase: outcome }),
}));

TAIWO EMMANUEL / CODE NOTE

TSXCOPYDOWNLOAD

import { useEffect } from "react";
import { assess, decode, type TxRequest } from "./assess";
import { fingerprint, useSimulation } from "./use-simulation";
import { useSigningSession } from "./signing-session";

export function SignReview({ tx, latestBlock, knownContracts, onSign }: {
  tx: TxRequest; latestBlock: number; knownContracts: ReadonlySet<string>; onSign: () => Promise<void>;
}) {
  const decoded = decode(tx);
  const risk = assess(tx, decoded, knownContracts);
  const simulation = useSimulation(tx, latestBlock);
  const { markReviewed, beginSigning, criticalAcknowledged, acknowledgeCritical, finish } = useSigningSession();

  useEffect(() => {
    if (simulation.data) markReviewed(simulation.data.fingerprint, simulation.data.blockNumber);
  }, [simulation.data, markReviewed]);

  const ready = simulation.isSuccess && !simulation.data.reverted && (risk.level !== "critical" || criticalAcknowledged);

  return (
    <section aria-labelledby="sign-title">
      <h2 id="sign-title">{decoded.summary}</h2>
      <ul>{risk.reasons.map((reason) => <li key={reason}>{reason}</li>)}</ul>
      {simulation.isPending ? <p>Simulating against the latest block…</p> : null}
      {simulation.data ? (
        <dl>{simulation.data.balanceChanges.map((c) => <div key={c.asset}><dt>{c.asset}</dt><dd>{c.delta}</dd></div>)}</dl>
      ) : null}
      {risk.level === "critical" ? (
        <label><input type="checkbox" onChange={acknowledgeCritical} /> I understand this can transfer control of the account</label>
      ) : null}
      <button
        disabled={!ready}
        onClick={async () => {
          if (!beginSigning(fingerprint(tx), latestBlock)) return;
          try { await onSign(); finish("submitted"); } catch { finish("aborted"); }
        }}
      >
        Sign with hardware wallet
      </button>
    </section>
  );
}