Transaction Scanner

Fetch semantic trace data for an Ethereum transaction and generate a self-contained HTML page that visually explains every internal call, token movement, and DeFi action that occurred.

Workflow

1. Fetch the trace tree

Run the query script with the transaction hash from $ARGUMENTS:

./scripts/query_tree.sh <tx_hash>

Save the JSON output to a temp file for processing. If the script fails (API unreachable, invalid hash), tell the user and stop.

Read ./references/tree-json.md to understand the JSON schema — it documents every field, action kind, and type you’ll encounter.

2. Parse and extract

Walk the JSON and extract these layers of information:

Transaction header:

• tx_hash, block_number, tx_idx
• from (sender EOA) and to (recipient contract)
• Gas details: gas_used, effective_gas_price, priority_fee, coinbase_transfer
• timeboosted flag (if true, note it)

Trace tree traversal — build a flat action list: Recursively walk trace_tree → children. For each node with a non-null action_kind, extract:

• The trace_address (depth in the call stack)
• The action_kind (Swap, Transfer, EthTransfer, Mint, Burn, etc.)
• Key fields from the action object (addresses, tokens, amounts)

Rational number conversion: Token amounts use the Rational type { s, n, d }. To get a human-readable number:

• Parse n (hex string) and d (hex string) as big integers
• Result = n / d (already decimal-adjusted, no need to divide by 10^decimals again)
• s indicates sign: true = positive, false = negative
• Format with appropriate decimal places (up to 6 for most tokens, up to 18 for wei-denominated values)

Collect unique addresses: Gather every address that appears as a from, to, recipient, pool, liquidator, debtor, solver, settlement_contract, or receiver_contract. These become the “actors” in the visualization. Shorten addresses to 0x1234...abcd format for display, with full address in a tooltip or data attribute.

3. Generate the HTML

Read the reference template and patterns before generating:

• Read ./templates/architecture.html for the card/section layout patterns
• Read ./references/css-patterns.md for theming, depth tiers, animations, and table styles
• Read ./references/libraries.md if using Mermaid for the call tree diagram

The HTML page should have these sections:

Section A: Transaction Overview (hero card)

A prominent card at the top showing:

• Tx Hash — full hash, monospace, truncated display with copy button
• Block — block number with link placeholder
• From → To — sender and recipient addresses (shortened, with full in tooltip)
• Gas — gas used, effective gas price (in Gwei), total cost (in ETH)
• Status indicators — timeboosted badge if applicable

Use the section--hero depth pattern. Monospace font for all hex values.

Section B: Action Summary (KPI row)

A row of small metric cards showing counts:

• Total actions found
• Swaps count
• Transfers count
• ETH transfers count
• Other action types (Mint, Burn, Liquidation, FlashLoan, etc.) — only show if present

Use the KPI card pattern from css-patterns.md. Each card gets an icon or colored dot matching the action type’s color in the legend.

Section C: Call Trace Tree

This is the core visualization. Two approaches depending on complexity:

For transactions with < 20 trace nodes: Use a nested HTML tree with indentation.

• Each node is a card with left-border color coded by action_kind
• Indent children with padding-left proportional to trace_address depth
• Show trace_idx as a small index badge
• Show the action kind as a colored badge
• Show the key action details inline (e.g., “Swap 1.5 ETH → 3000 USDC on Uniswap V3”)

For transactions with >= 20 trace nodes: Use a Mermaid graph TD diagram.

• Each node labeled with its action kind and a short summary
• Color-coded by action type using classDef
• Edges show the parent-child call relationship
• Include zoom controls (+/−/reset) — see the zoom pattern in css-patterns.md
• Read ./templates/mermaid-flowchart.html for the Mermaid setup pattern

Section D: Token Flow Table

A data table showing every token movement in the transaction:

• # — sequential index
• Action — colored badge (Swap, Transfer, Mint, Burn, etc.)
• From / To — shortened addresses
• Token — symbol with small address tooltip
• Amount — human-readable number from Rational conversion
• Protocol — if the action has a protocol field

For Swap actions, show two rows or a combined row: token_in amount → token_out amount.

Use the data table patterns from ./templates/data-table.html:

• Sticky header
• Alternating row backgrounds
• Status-colored action badges
• Responsive horizontal scroll

Section E: Address Interaction Map (optional, for complex txs)

If the transaction involves 3 or more unique addresses, show a summary of interactions:

• List each address with a color-coded dot
• Show what actions it participated in and its role (sender, receiver, pool, etc.)
• Optionally use a Mermaid sequence diagram for the interaction flow

This section helps answer “who interacted with whom and how.”

4. Style

Palette: Use a blockchain/crypto-themed palette. Dark-first aesthetic (the audience is developers and researchers). Suggested direction:

• Deep navy/charcoal background with cyan/teal accents for primary elements
• Color-code action types consistently throughout the page:
  • Swap — cyan/teal
  • Transfer — green
  • EthTransfer — blue-purple
  • Mint — emerald
  • Burn — amber/orange
  • Liquidation — red/rose
  • FlashLoan — purple
  • Batch/Aggregator — indigo
  • Unclassified — gray
  • Revert — red with strikethrough or muted treatment
• Support both light and dark themes via prefers-color-scheme

Typography: Pick a distinctive pairing. Suggestions:

• JetBrains Mono for hex values and technical data
• Space Grotesk or Outfit for headings and body text

Animations: Staggered fade-in for sections. Keep it subtle — this is a data-heavy tool page, not a marketing site.

5. Deliver

mkdir -p ~/.agent/diagrams

Write to ~/.agent/diagrams/tx-<short_hash>.html where <short_hash> is the first 8 chars of the tx hash (after 0x).

Open in browser:

• macOS: open ~/.agent/diagrams/tx-<short_hash>.html
• Linux: xdg-open ~/.agent/diagrams/tx-<short_hash>.html

Tell the user the file path.

Action Kind Reference

When rendering actions, use these display patterns. The Mermaid Arrow column specifies which arrow style to use for edges in the call trace tree diagram — this makes the diagram scannable at a glance because arrow shape encodes the action type.

Quality Checks

Before delivering:

• All Rational amounts render as readable decimals (not raw hex)
• All addresses display in shortened format with full value accessible
• Action badges are color-coded consistently
• Both light and dark themes work
• Table scrolls horizontally on narrow viewports
• Mermaid diagrams (if used) have zoom controls
• No console errors when opening the file
• The page tells a clear story: “Here’s what this transaction did”