Truffle Debugger

WHAT IT DOES

Truffle Debugger is a transaction debugging tool that retrieves and displays detailed execution traces for any transaction on EVM-compatible chains. It uses debug_traceTransaction to capture every opcode, call, and state change that occurred during execution, showing you exactly what happened inside the contract. The tool displays call trees with depth indicators, stack traces, program counter positions, gas usage, and revert reasons. It supports both Geth-style structLogs and callTracer outputs, adapting to the trace format your node provides.

HOW TO USE

Install the app through the BotSurf interface. Click Connect to link your wallet. Select your target network—localhost (Hardhat/Truffle default), Sepolia, Goerli, Mainnet, or a custom RPC URL. Paste a transaction hash into the debug input and click "Debug Transaction". The tool first fetches the transaction receipt and details, then runs debug_traceTransaction to capture the execution trace. Results appear in the output log with structured call trees, opcode traces, and any revert reasons. The panel shows call depth, from/to addresses, value transfers, and gas cost. For nodes that support it, callTracer provides a clean call tree view; fallback to structLogs shows the full opcode-by-opcode trace.

TRACE RETRIEVAL AND FORMAT ADAPTATION ENGINE

The debugger uses a multi-strategy approach to retrieve transaction traces. It first attempts debug_traceTransaction with the callTracer option, which returns a structured call tree with nested calls, values, and revert reasons. If callTracer is not available or fails, the engine falls back to the default tracer, which returns structLogs—the raw opcode-level execution trace. The display engine adapts to either format: callTracer output is rendered as an indented call tree showing each contract call, its parameters, value transfers, and any revert; structLogs output shows each opcode with program counter, stack state, and operation depth. The tool also extracts and highlights revert reasons, gas usage, and transaction metadata, providing comprehensive debugging visibility without requiring manual trace parsing.

WHAT IT CANNOT SEE

The debugger requires archive node access to trace historical transactions—standard nodes typically only retain recent state. Without an archive node, traces for older transactions may fail with "missing trie node" errors. The tool cannot modify blockchain state or replay transactions with different parameters; it only reads existing transaction data. It cannot debug transactions that have not been mined or are not in the node's trace cache. Some nodes disable debug_traceTransaction entirely for security or performance reasons. The tool does not provide source code mapping or ABI decoding—traces are shown at the EVM opcode level, not as Solidity function calls. It cannot trace transactions on chains that do not support the debug_traceTransaction RPC method.

PLEASE NOTE

This tool requires the BotSurf interface and an EVM-compatible wallet. It is designed for development and debugging on local networks like Hardhat and Truffle. Using it on public mainnet nodes requires archive node access or a node with debug_traceTransaction enabled. The tool does not store or transmit any data; all state is local to your session.