Debugging is core developer infrastructure, not just a feature. The Solidity ecosystem has capable debugging tools today across Foundry, Hardhat, and Tenderly, but it's been missing a shared, reusable building block that frameworks, IDEs, and observability tools can all integrate.
We've been building SolDB to fill that gap: an open-source, ETHDebug-based, CLI-first debugger for Solidity. Think GDB or LLDB, but for the EVM, or a CLI-based Tenderly. The goal is to give the ecosystem a canonical debugging foundation built around standards, not custom internals that every tool has to rebuild independently.
We're building SolDB in collaboration with Argot Collective, the non-profit behind solc, the main Solidity compiler, and the wider Solidity toolchain. They grew out of the Ethereum Foundation and are the core team driving Solidity's development.
Developers keep asking for better debugging
The demand signal is clear. In the 2025 Solidity Developer Survey, 33% of respondents reported recurring debugging issues. When asked how debugging could be improved, developers described wanting a step-by-step debugger with breakpoints and variable inspection for Solidity contracts, better stack traces, transaction replay and simulation, and IDE integration. This is the gap developers feel most directly in their day-to-day work.
The pattern repeats across ecosystems. The 2024 Starknet developer survey put an online debugger and profiler among the top tools developers wanted built. A 2026 Canton Network survey found developers asking for visual debuggers with real-time transaction tracing, failure simulation, and human-readable error decoding. Different ecosystems, same request.
Why we are building it
In Web2, observability products like Sentry and Datadog don't build debugger cores from scratch. They build on top of GDB and LLDB-like infrastructure that the broader ecosystem shares. The debugging layer is modular, open, and maintained as a public good. Product companies focus on the layers above it.
Ethereum hasn't had that equivalent. Each debugging-capable product has built its own internals, which is a lot of parallel effort with no shared benefit. The metadata layer underneath has stayed thin too: legacy Solidity source maps tell a debugger which source range an opcode came from, which is enough for call traces and source locations, but they stop short of describing variables, types, and where values actually live in stack, memory, or storage. Tools reverse-engineer the rest. The missing piece isn't another product with a debugger inside it. It's a building block in the Unix tradition: a special-purpose tool designed to compose into larger workflows rather than stand alone, paired with the compiler-side debug format it reads from.
SolDB fills that gap. The SolDB core is built around ETHDebug, the compiler-produced debug metadata standard. That's what makes it a shared foundation rather than another set of custom internals each tool rebuilds on its own. It doesn't replace Tenderly, Foundry, Hardhat, Walnut, or IDEs. Those are complements. SolDB provides the debugger core layer and those tools provide the product and workflow layers on top.
CLI-first also means agent-accessible. As AI agents become active participants in development workflows, they need programmatic interfaces to inspect, trace, and simulate EVM execution. A developer asking an agent to investigate a failing transaction or simulate a state-dependent call needs the agent to have reliable, structured access to what's happening at the execution level. SolDB provides that infrastructure, not just for developers running CLI commands, but for agents working in the same codebase.
How it works: ETHDebug
SolDB is built around ETHDebug: compiler-produced debug metadata that describes what an EVM transaction is doing at the Solidity level. The compiler emits it, the debugger consumes it, and SolDB targets the spec rather than compiler internals, so the boundary stays stable as compilers evolve.
Debug metadata for Solidity has historically been a thin instruction-to-source mapping: an opcode maps to a byte range in the source. Enough to highlight "you are roughly here in Counter.sol", and what most EVM debuggers have leaned on for years. It falls short on the questions that come up when something breaks: which stack slot holds amount, which storage slot is balances[user], what a memory region represents, why an optimized contract no longer lines up with its source.
A debugger working only from that mapping reverse-engineers the rest, combining the source map with ABI, AST, storage layout, and the EVM trace to guess that a stack value is probably amount, or that an SLOAD of slot 0 probably read counter. It's inference, not direct knowledge. Optimization makes it harder: when the compiler reorders operations, reuses stack slots, or inlines functions, variables and source lines stop lining up cleanly.
ETHDebug replaces that inference with explicit metadata: source ranges, the variables in scope at each point, their high-level types (uint, address, struct, mapping), and pointers to where those values live across stack, memory, storage, calldata, returndata, transient storage, or code. The compiler stops being a black box and hands the debugger the context it needs to show source-level state directly.
ETHDebug is what we're implementing in solc together with Argot Collective, and what we're then feeding into SolDB on the debugger side. solc emits a working subset today, which powers SolDB's current source-level tracing, and richer parts of the spec will land in solc as we build them out. SolDB's decoding gets richer alongside that work. We're also talking with teams behind newer Solidity compilers like solx and solar about generating ETHDebug output. If they adopt the standard, the same SolDB core debugs code from any of them.
What developers can do today
SolDB runs against local nodes like Anvil and supports remote RPC debugging for on-chain transactions. Installation is via Cargo. The core workflows are in working shape today, with rough edges expected: transaction tracing, simulation, source-level call stacks, and step-through debugging with breakpoints.
soldb trace <tx_hash> is the entry point. Pass a transaction hash, an RPC URL, and ETHDebug artifacts from a matching debug build, and SolDB returns a source-level call trace: status, gas used, and the full Solidity call stack, including internal function frames, not just external selectors.
This is the "what did this transaction actually do?" view that's faster to get to than digging through raw logs or stepping through a test failure.
Add --raw to drop to the opcode level. Raw mode gives a step-by-step trace: program counter, opcode, gas remaining, stack words, and storage state at each step. Stack words show as hex until ETHDebug pointers describe what each one represents. Use raw mode for EVM-level questions about gas behavior, stack depth, or storage changes, or when ETHDebug artifacts aren't available for the contract you're tracing.
soldb simulate <address> "function(args)" runs a call without broadcasting. Useful for preflight checks on state-dependent functions, testing revert paths before sending a transaction, and exploring call paths that haven't been triggered on-chain yet. Simulate accepts function signatures or raw calldata via --raw-data.
--json produces machine-readable output. The payload is verbose, because it includes full debug maps, source paths, and ABI, but it's the right integration surface for explorers, IDEs, and observability pipelines that need structured data to work with programmatically.
--interactive launches a debugger loop against a transaction trace. You can step through execution and set breakpoints by PC or source line.
Variable-level decoding tracks ETHDebug's progress in solc. With ETHDebug artifacts, call stacks resolve to Solidity with internal function frames, function names and arguments, source files and line numbers, and decoded events. Without them, traces drop to the opcode level: status, gas, and step count are available, but the call stack won't resolve to Solidity function names or source locations. Typed decoding of stack and storage values and richer source-first views depend on parts of ETHDebug that are still early and experimental in solc. The better solc's output, the better SolDB.
What a minimal workflow looks like
The short path from source to trace:
Install the CLI:
cargo install --git https://github.com/walnuthq/soldb.git soldb-cliCompile with ETHDebug artifacts. Solidity 0.8.29+ supports ETHDebug. If your project uses a standard Foundry build, you'll need a separate debug build outputting ETHDebug artifacts, then deploy that specific bytecode so the debug mappings match your trace:
solc --via-ir --debug-info ethdebug --ethdebug --ethdebug-runtime \
--bin --abi --overwrite -o out contracts/YourContract.solRun Anvil with steps tracing enabled:
anvil --steps-tracingOnce the debug bytecode is deployed and you've sent a transaction, trace it:
soldb trace <tx_hash> \
--ethdebug-dir <address>:<ContractName>:./out \
--rpc http://localhost:8545Or simulate a call before sending:
soldb simulate <address> "functionName(args)" \
--from <caller> \
--ethdebug-dir <address>:<ContractName>:./out \
--rpc http://localhost:8545Full setup instructions and an example project are in the SolDB repo.
Where SolDB is going
The current release is the foundation. Source-level decoding keeps widening as the rest of ETHDebug lands in solc, and more of the trace shifts from opcode-level output to typed Solidity values. DAP integration is also on the roadmap, so SolDB plugs into IDE debuggers as a backend instead of each editor maintaining its own.
The long-term shape is a shared, public-good debugger core for the EVM. Each layer above it (frameworks, block explorers, observability platforms, IDEs, AI agents) picks the workflows, UX, and surface area its users need, and the debugger underneath gets one consolidated investment instead of many parallel ones. The debugger you reach for from a CLI, an IDE, an explorer's tx view, or an agent's tool call ends up being the same core that evolves in one place. More on specific integrations and workflows as those pieces ship.
Try it now
SolDB is available now at GitHub. Try it out or pull the code and see how the ETHDebug integration works. Feedback from the community shapes what we prioritize. If you run into something unexpected, open an issue. If you're building a framework, IDE extension, or observability tool and want to talk about integration, reach out.