velma

Velma Solidity Debugger

Real-time Solidity Debugger and Associated VS Code Integration

Stepping

Stepping Into

Constructor and Contract State

Get Status Updates About Releases!

Follow us on Twitter at https://twitter.com/seeseplusplus to get updates about new releases/etc about Velma

Get Started!

Checkout the Velma sample project to see how you can get started with debugging with Velma. We're definitely looking to streamline the process of using Velma, but we currently highly recommend to follow the instructions in the sample project's README to get started.

:warning: Results May Vary

Velma is a very new tool built from scratch just a few months ago. There will be growing pains as the project reaches maturity. Help us out by reporting any issues or requesting features on the Issues Page. We'll try to address all of them, but please bare with us (us being 1 guy doing this as a side project) if we don't get to you in a short manner (i.e. 1-2 weeks, ping us again after that!).

Another Solidity Debugger??

Velma was created to fulfill, and winner of, an Augur bounty for a portable Solidity Debugger which supported TestRPC (now ganache-cli/core), had VS Code integration, and arbitrary Solidity code execution at a breakpoint. While there are other awesome and notable debuggers (i.e. Truffle and Remix), Velma addresses Solidity Debugging differently to achieve real-time debugging.

Real-time vs. Trace Analyzing

Trace Analyzer Debugging

Current debugger runtimes utilize the debug_traceTransaction RPC method:

The traceTransaction debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash.

In lamen terms, it replays a transaction to build the EVM low-level debugging information. Debuggers then play back this history of events. The developer scan debug code after it was executed and understand exactly what happened in the exact same state. This can be extremely helpful, especially for complex distributed systems like Ethereum. However, the code was already executed; it can't be prevented from executing or modified before finishing execution.

Real-time Debugging

Velma uses a different method for debugging. Velma directly ties in with the Ethereum Virtual Machine (specifically, the ethereumjs-vm implementation of the EVM) and debugs transactions as they happen. This means when you stop on a breakpoint using Velma, the code that you are about to step over/into hasn't actually executed yet. You can hypothetically change the state of variables (currently not supported in Velma, but not out of the realm of things), execute arbitrary code with the current state (supported by Velma!), and even stop execution from continuing.

The biggest feature we gain from this is arbitrary code execution. We can inject code directly into the EVM to execute some piece of Solidity the user inputs, run it, and return the result. This is ran in the context of the running transaction. Pretty cool stuff if you ask me!

Arbitrary Code Execution

Final Thoughts

Velma was written completely by Mike Seese (@seesemichaelj). While Mike now works full-time with the awesome Truffle team, Velma is a side project for Mike and currently has no affilation with Truffle's debugger. With that said, do note that this is not maintained by a full-time developer, and the frequency of updates will be diminished because of such.