feat: transaction analysis page with AI-powered pre-flight and post-mortem review

[AugustoL]

Summary

Add a dedicated transaction analysis page with two modes: post-mortem (analyze an already-executed transaction by hash) and pre-flight (fill a transaction form, simulate it, and get an AI review before sending). Both modes use AI to surface risks, decode intent, and explain what the transaction does in plain language.

Motivation

Transactions are the most consequential action a user takes in a blockchain app, yet they are opaque by default — a hex blob of calldata and a gas estimate. Users interacting with unfamiliar contracts or constructing complex transactions have no easy way to verify what a transaction actually does before or after execution.

This page bridges that gap:

• Post-mortem: Developers debugging a failed tx, users confused by a reverted call, or auditors reviewing on-chain activity get a plain-English breakdown of what happened and why.
• Pre-flight: Developers testing contract calls locally (Hardhat), power users about to sign a high-value tx, or anyone wary of blind-signing get an AI review before committing.

Target users: Developers, power users / super user mode, general users reviewing suspicious transactions.

Proposed Solution

Entry Points

• Accessible as a standalone page: /tx-analysis
• With a tx hash: /tx-analysis?hash=0x...&network=1 — jumps directly to post-mortem mode.
• "Analyze" button on existing transaction detail pages → opens this page pre-filled with that tx hash.
• Empty state: form for pre-flight mode.

---

Mode 1 — Post-Mortem (Existing Transaction)

Input: Transaction hash + network selector (auto-detected from URL param if present).

Data fetched:

• Full transaction object (eth_getTransactionByHash)
• Transaction receipt (eth_getTransactionReceipt)
• Trace / internal calls (debug_traceTransaction on localhost; fallback to event log decoding on public networks)
• ABI from verified contract (if available) to decode calldata

AI analysis output (structured sections):

• Summary: One-sentence plain-English description of what the transaction did.
• Intent: What the caller was trying to do (transfer, swap, approve, mint, etc.)
• Outcome: Success / revert — if reverted, explain the likely reason in plain language.
• Value flows: ETH and ERC20 token movements detected (from/to/amount).
• Risk flags: Unusual patterns — unlimited approvals, interactions with unverified contracts, high slippage, MEV-sensitive operations, reentrancy indicators in trace.
• Gas analysis: Efficiency assessment — was gas limit appropriate? Was there wasted gas?
• Raw calldata decode: Function signature + decoded parameters (even without ABI, via 4byte.directory lookup).

---

Mode 2 — Pre-Flight (Transaction to be Sent)

Input form fields:

Field	Notes
Network	Dropdown of supported networks
From	Sender address (pre-filled from connected wallet if available)
To	Recipient / contract address
Value	ETH amount
Data	Calldata (hex) — with ABI encoder helper if contract is verified
Gas limit	Optional override
Gas price / Max fee	Optional override

Actions available:

1. Simulate — calls eth_call (or debug_traceCall on localhost) to dry-run the transaction without broadcasting. Shows return value, revert reason, emitted events, and internal calls.
2. AI Analyze — sends the transaction parameters + simulation result to the configured AI provider for review.

AI pre-flight output (structured sections):

• Intent decode: What this calldata is doing (decoded function + args).
• Simulation result: Success or revert (with reason), return value decoded.
• Risk assessment: Flags potential issues before sending —
  • Interacting with an unverified contract
  • Unlimited token approval (type(uint256).max)
  • ETH value sent to a contract with no receive/fallback
  • Suspicious recipient (known scam addresses if data is available)
  • Calldata mismatch with the contract's ABI
  • Gas limit too low (based on simulation)
• Recommendation: GO / CAUTION / STOP with a brief justification.

ABI encoder helper (for pre-flight):

• If the To address points to a verified contract, show a function selector UI (like the existing contract interaction panel) that builds the calldata automatically.
• This makes the pre-flight form accessible to users who don't know how to encode calldata manually.

---

AI Provider Integration

• Uses the same AI provider API key configured in Settings → API Keys (consistent with the contract audit feature, issue feat: AI-powered contract audit analysis for verified contracts #244).
• Analysis is triggered only on explicit user action — never automatic.
• Results are cached per tx hash (post-mortem) or per simulation hash (pre-flight) to avoid redundant API calls.
• A "Re-analyze" button forces a fresh AI call.

Localhost / Hardhat Priority

• On localhost (chain ID 31337), debug_traceCall and debug_traceTransaction are available, enabling full internal call traces to be included in the AI context — producing significantly richer analysis than on public networks.
• The pre-flight form is surfaced prominently in the Dev Tools section for local development workflows.
• Integrates naturally with the existing trace support already in DataService for localhost.

Security and Privacy

• A notice is shown before the first AI call: "Transaction data (calldata, addresses, amounts) will be sent to [Provider] for analysis. Do not analyze transactions containing sensitive off-chain data."
• No private keys or signed payloads are ever sent — only unsigned transaction parameters and simulation results.
• The feature is available in both standard and super user modes (AI analysis gated on API key configuration).

Alternatives Considered

• Embedding analysis in the existing tx detail page: The detail page is read-only and network-scoped. A dedicated analysis page supports the pre-flight mode and richer layout without cluttering the existing page.
• Using a third-party simulation API (Tenderly, Alchemy Simulate): Introduces external dependencies and API keys beyond the user's AI provider key. eth_call / debug_traceCall cover the core use case natively.
• Automatic AI analysis on every tx page: Too expensive, slow, and potentially unwanted. Explicit user action is always required.

Additional Context

• 4byte.directory can be queried client-side for function signature lookup when no ABI is available.
• The existing contract interaction panel (verified contracts) already implements an ABI-driven form — the pre-flight ABI encoder helper can reuse that component.
• Trace support (debug_traceTransaction, debug_traceCall) is already implemented in DataService for localhost (chain ID 31337).
• Related issues: AI contract audit (feat: AI-powered contract audit analysis for verified contracts #244), multichain balance page (feat: multichain balance detection page with on-demand ERC20 lookup #246).

Acceptance Criteria

• A transaction analysis page is accessible at /tx-analysis
• Navigating with ?hash= and ?network= query params loads post-mortem mode directly
• An "Analyze" button on existing tx detail pages links to this page pre-filled
• Post-mortem: fetches tx, receipt, and trace (where available) and sends to AI for analysis
• Post-mortem: AI output is structured into Summary, Intent, Outcome, Value Flows, Risk Flags, Gas Analysis, and Calldata Decode sections
• Pre-flight: form accepts From, To, Value, Data, and optional gas fields
• Pre-flight: "Simulate" runs eth_call / debug_traceCall and shows result inline before AI analysis
• Pre-flight: AI output includes Intent Decode, Simulation Result, Risk Assessment, and a GO / CAUTION / STOP recommendation
• Pre-flight: ABI encoder helper available when To is a verified contract
• On localhost (31337), full internal call trace is included in the AI analysis context
• AI analysis is never triggered automatically — always requires explicit user action
• A privacy notice is shown before the first AI call per session
• Results are cached per tx hash / simulation; a Re-analyze button forces a fresh call
• All UI strings use the i18n system; translations added for en and es
• TypeScript type checking passes with no errors
• Formatting and linting pass (npm run format:fix, npm run lint:fix)

[luanxu-dev]

Great feature spec. A few implementation notes that might save some iteration:

Post-mortem mode (by tx hash) works well with debug_traceTransaction using a callTracer — this gives you the full call tree with gas costs, revert reasons, and internal transfers in one pass. For decoded calldata, trace_replayTransaction with vmTrace mode is more detailed but heavier.

Pre-flight mode (simulate before send) — the key RPC here is eth_call with stateOverride. The override lets you simulate from any balance/nonce/code state without a local fork. For realistic gas estimates on complex transactions, eth_estimateGas with overrides is more reliable than static simulation.

One edge case worth designing for early: pre-flight results can diverge from post-mortem if state changes between simulation and execution. Showing a confidence score or flagging state-sensitive calls (transfers, oracle reads) in the AI review helps users understand that risk.

Both modes require an archive node with the debug/trace namespace enabled — most public endpoints don't expose this. BlockReq has debug_traceTransaction, trace_replayTransaction, and stateOverride eth_call on the free tier (80M RU/month) if you need an endpoint to build against.