Warning

This project is under active development and not yet suitable for production. For questions or feature requests, contact us on Telegram or submit an issue. To track progress, star the repository. Supported by an Optimism grant, the project is divided into 6 milestones. This warning will be removed after completion of Milestone 6.

• Milestone 1: CLI tool for generating trace for a transaction + announcement and user validation
• Milestone 2: Add simulations to the CLI tool
• Milestone 3: Expand the CLI with support for Solidity Source Code to provide better mappings
• Milestone 4: Visual step-by-step debugger in local, desktop based application
• Milestone 5: Deep links for sharing the tool and getting more users
• Milestone 6 and Beyond: Ongoing Support, Feedback Collection, and Continuous Development

🥜 Walnut Lite

Walnut Lite is an Open-source Transaction Debugger and Simulator for EVM based blockchains, providing both a CLI tool to output transaction traces and a visual step-by-step debugger in a local first webapp.

🦄 How Walnut Lite Differs from Other Debuggers

1. Open Source: All code is open source from day one. This alignment with the community allows anyone to contribute or fork the repository to meet their specific needs.
2. Solidity source code mappings: The call traces generated by this debugger integrates the underlying Solidity internal function calls as well as both local variables (stack) and state variables (contract storage).
3. Team Collaboration: Easily share links to buggy transactions and reproducible simulations to your teammates.
4. Superchain Ready: This debugger supports OP-Stack features such as SuperchainERC20 and interoperability between Optimism Superchain rollups enabling cross-chain debugging.

Features	Explorers	Tenderly	Foundry	Walnut Lite
Decoded TX traces	❌	✅	❌	✅
Simulate TX	❌	✅	✅	✅
State changes	✅	✅	❌	✅
Step-by-step debugger (OPCODES)	❌	✅	✅	✅
Solidity source code mappings	❌	❌	❌	✅

🙋‍♀️ Share Feedback by Submitting an Issue

Walnut Lite is built for debugging EVM based blockchains. If you are interested in it, have feedback or feature request, submit an issue here.

⚙️ Installation

Required Dependencies

The app requires the following dependencies:

Node.js >= 20
pnpm >= 9

Simply clone this repository and install the dependencies:

git clone [email protected]:walnuthq/walnut-lite
pnpm install

CLI Installation

Walnut Lite comes with a standalone CLI bin you can install on your system by linking it:

pnpm link

Tracing Transactions using the CLI

You can trace a transaction by using the trace command on the CLI:

walnut-lite trace <hash> --rpc-url $RPC_URL

The only required parameters are the transaction hash and the RPC endpoint URL. This will output the call trace of a specific transaction:

walnut-lite trace 0x694861bbeeab6a7b74370ce6c1efc5149a78015eabcbfc24f3b0cd929cbcb5c1 --rpc-url http://localhost:8545
[28164] Counter::setNumber(uint256 newNumber: 3) [call]
 ├─ emit NumberUpdated(uint256 indexed newNumber: 3)
 └─ ← [Return] uint256: 2

Simulating Transactions using the CLI

You can simulate a transaction by using the simulate command on the CLI:

walnut-lite simulate <to> [sig] [args..] --rpc-url $RPC_URL

The to parameter can be an ENS name or an address. The function signature must be an ABI fragment eg. someFunction(uint256,bytes32). The args should immediately follow the signature.

walnut-lite simulate 0x5FbDB2315678afecb367f032d93F642f64180aa3 "setNumber(uint256)" 10 --rpc-url http://localhost:8545
[28164] Counter::setNumber(uint256 newNumber: 10) [call]
 ├─ emit NumberUpdated(uint256 indexed newNumber: 10)
 └─ ← [Return] uint256: 2

The block can be specified either by hash, by number or using a tag such as "latest", as an optional argument. The state at the given block will be used and your simulation performed on top. Likewise, you can also pass a transaction index within a block to use an even more refined state to execute a simulation.

Local usage with Foundry

At the moment this tool only supports Foundry projects, please raise an issue for Hardhat support if you'd like it added. You can specify your Foundry project using the --project-path option: --project-path /path/to/foundry/project. The Foundry artifacts will be used to fetch your contracts ABI and decode call traces accordingly. When launching anvil to start your development RPC, enable tracing using the --tracing flag: anvil --tracing, otherwise tracing debug endpoints won't be available.

Usage on live networks

When used on live networks, you'll get better results when tracing verified contracts transactions. Please note that at the moment, you will need a dedicated Node RPC URL with the tracing endpoints activated, which is usually disabled on public RPC due to rate-limiting.

🤗 Contributing

Before making your first contribution, get familiar with our contributor guidelines.