Walnut

Open-source, self-hostable transaction debugger and simulator for the Ethereum ecosystem.

Key features

• Full transaction traces, simulations, and step-by-step debugging
• Can be self-hosted and connected to any RPC—ideal for rollups and Rollup-as-a-Service platforms
• Enterprise-grade privacy: zero telemetry, full data control, and on-premises hosting

Table of Contents

• Who is Walnut for?
• Live Demo
• Features and Roadmap
• Enterprise & Privacy
• Deployment and Self-Hosting
• Local Setup & Usage
  • 1. Install Prerequisites
  • 2. Set Up Environment Variables
  • 3. Install Dependencies & Build
• 4. Run the Debugger
• Contributing
• Acknowledgements
• License
• Security Practices
• Support & Contact

Who is Walnut for?

• Rollups seeking a robust transaction debugger for their own chains—simply self-host Walnut or contact us for assistance.
• Rollup-as-a-Service Platforms looking to offer advanced transaction debugging as part of their platform.
• Smart contract developers who want to trace, simulate, and understand on-chain code execution.
• Enterprises that require privacy, data protection, and self-hosting—get in touch for custom support or deployment help.

Live Demo

walnut.evm.first.demo.mp4

Try Walnut live at evm.walnut.dev

Features and Roadmap

• Full transaction call trace with internal function calls and decoded values
• Step-by-step transaction debugger
• Transaction simulations
• Custom RPCs including local (Anvil, Public RPCs, custom chains)
• Gas flamechart
• State changes
• Cross-chain message tracing
• Realtime monitoring

Enterprise & Privacy

Walnut is designed for organizations that require strict data privacy and control. All data is processed locally with zero telemetry, ensuring sensitive information never leaves your infrastructure. For privacy-sensitive or enterprise deployments, contact us.

Deployment and Self-Hosting

Walnut is built for self-hosting and is designed to run within your own infrastructure, with support for advanced deployment scenarios using Docker and Kubernetes.

Docker images and deployment guides will be available soon. In the meantime, please reach out if you have specific requirements or would like to discuss custom setups.

Local Setup & Usage

1. Install Prerequisites

This project depends on SolDB. Install it using:

pip install git+https://github.com/walnuthq/soldb.git

Note: SolDB is currently in beta and doesn't have a PyPI package yet.

---

2. Set Up Environment Variables

Copy .env.example to .env.local at the root of your repository:

cp .env.example .env.local

Edit .env.local and set the following variables for your EVM network:

NEXT_PUBLIC_RPC_URL="RPC_URL_WITH_DEBUG_ENDPOINTS_SUPPORT"
NEXT_PUBLIC_NETWORK_NAME="OP Sepolia"
NEXT_PUBLIC_CHAIN_ID="11155420"

Your node RPC URL must support debug_traceTransaction and debug_traceCall endpoints. These are usually not available on public nodes, so use a dedicated node RPC URL.

---

---

3. Install Dependencies & Build

npm install
npm run build

---

4. Run the Debugger

Start the application:

npm start

The debugger will be available at http://localhost:3000.

You can search for a transaction by hash or try an example simulation from the homepage.

On the transaction screen, click "Re-simulate" to run a simulation with custom calldata.

Contributing

Contributions are encouraged, but please open an issue before making any major changes to ensure your changes will be accepted.

Acknowledgements

We would like to thank the following projects and communities for their support and inspiration:

• 4bytes — for maintaining a comprehensive open database of Ethereum function signatures.
• Anvil — for providing a fast, flexible local Ethereum node for development and testing.
• Arbitrum Stylus — for supporting Walnut in building debugging tools for Stylus, which served as foundational code for this project.
• ETHDebug format — for defining an open specification for EVM debugging traces, which we leverage in Walnut’s trace handling.
• Foundry — for delivering a powerful Ethereum development toolkit; parts of their code are reused in this project.
• Optimism — for providing a grant that enables the ongoing development of this project.
• Solidity Compiler — for developing and maintaining the Solidity language and compiler, which underpin much of the EVM ecosystem.
• Sourcify — for offering an open source contract verification service, which is integrated into Walnut.
• Starknet — for supporting Walnut’s development for Starknet; significant portions of code from the Starknet project are leveraged here.

If you believe your project should be credited here, please let us know!

License

Walnut is licensed under the Business Source License 1.1 (BSL 1.1). See LICENSE.md for details.

Security Practices

Walnut is developed with security in mind. We follow best practices including regular dependency updates, code reviews, and static analysis. Sensitive data is never transmitted or logged externally, and all processing can be performed within your own infrastructure. We encourage responsible disclosure of any vulnerabilities—please contact us at [email protected] with security concerns.

Support & Contact

For support, questions, or to get involved:

• Join our Telegram group: @walnuthq
• Submit an issue on GitHub: https://github.com/walnuthq/walnut
• Visit our website: walnut.dev
• Email us: [email protected]