[final report] SolDB — CLI debugger and simulator for Solidity and Stylus

DAO Programs & Initiatives Domain Allocator Offerings (prev Questbook)
1

Per request from a member of Domain Allocators for Developer Tooling, we are submitting a final report on our work for the Developer Tooling on Arbitrum One and Stylus 3.0 grant.

Project: SolDB — CLI debugger and simulator for Solidity and Stylus

Successfully implemented a cross-environment debugging ecosystem for Arbitrum. All milestones are fully tested, enabling seamless tracing across both Solidity and Stylus contracts.

Given StylusDB is already integrated in the official Stylus SDK PR #370, this work will be available to all Arbitrum users by default right after PR #390 gets merged-significantly increasing the grant’s ecosystem impact.

List of Milestones Delivered

M1: Enhanced Call Traces ($9,000)

• Implemented legacy source map parser for Solidity versions < 0.8.29.

• Enables tracing and function resolution via source mapping.

• Result: Trace visibility for legacy solidity versions where ethdebug is missing.

M2: Debug Adapter Protocol ($9,000)

• Defined unified CrossEnvTrace protocol and built a centralized Bridge Server.

• Result: Standardized communication layer between SolDB (Python) and StylusDB (Rust).

M3: SolDB Import of Stylus Traces ($9,000)

• Developed bridge client for SolDB to request and merge Stylus traces.

• Automated function-level merging into the Solidity call hierarchy.

• Result: Full visibility when a Solidity contract interacts with Stylus.

M4: StylusDB Import of Solidity Traces ($9,000)

• Enhanced cargo stylus usertrace with EVM contract call detection.

• Integrated SolDB trace into the Stylus call tree.

• Result: Full visibility when a Stylus contract interacts with EVM/Solidity logic.

M5: Clear Revert Reasons ($7,000)

• Added error detection and revert message in usertrace.

• Mapping error messages to the failing code frame.

• Result: Faster diagnostics for failed cross-language transactions.

M6: Documentation and Onboarding ($2,000)

• Submitted documentation as part of the main tool repository and to Official Arbitrum Docs.

• Result: Clear onboarding path and documentation for developers.

M7: 6 month support ($5,000)

Quick Start and Testing

Prerequisites

Deployment and Testing

Navigate to the https://github.com/walnuthq/soldb/tree/main/test/stylus test examples and run the deployment script - ./deploy.sh.

This script automatically deploys the contracts and executes a test transaction to complexStylusOperation().

The output will provide an example soldb command similar to this:

Test with soldb:

soldb trace 0x4eac0d80dda629ffbc92eff1746e3be1946352daec5b102a1052f00edc9dafa4 \
  --ethdebug-dir 0xA6E41fFD769491a42A6e5Ce453259b93983a22EF:StylusCounterCaller:/Users/mami/Documents/walnut/walnut-evm/soldb/test/stylus/solidity-caller/out \
  --cross-env-bridge http://127.0.0.1:8765 \
  --stylus-contracts /Users/mami/Documents/walnut/walnut-evm/soldb/test/stylus/stylus-contracts.json \
  --rpc http://localhost:8547

Run the command to see a unified trace showing both EVM and Stylus calls.

Link to full report

https://docs.google.com/document/d/1rOcHDruHDFKjcOQhlK6NkfFfvPAQjG5bLvR4e_2V-7Y/edit?tab=t.0

Project Resources