Implementation Notes

The current version of the Intellij EVM debugger is based on Web3j embedded EVM which starts an in-memory Besu node. So far, we've implemented the bare minimum code to get a basic debug process running, below is a class diagram showing key components.

EVM debugger class diagram

Many of these classes are biolerplate required by Intellij plugin SDK to create the debug session; the entry point for example starts with Web3jDebugProcess which instantiate the debugger process and the embedded EVM, it also implements handlers for the stepping operations and controls the SoliditySuspendContext.

Another key component is the SolidityDebugTracer this is adopted from Web3j EVM ConsoleDebugTracer it has most of Solidity and ABI source code mapping, it also contains a simple state machine for handling the suspend and execution states. The state machine instructs the embedded EVM to pause whenever it hits a breakpoint, and continues when all opcodes in a stack have been executed until it transitions to the next line.

Debug session snippet for Web3App

What is working?

The debug session, breakpoint handler and stepping operations and most of the source code mapping. It's quite hacky, the debugger doesn't show variable memory, local and storage state properly.

The step over don't function properly, it still steps through opcode by opcode rather than jump over to the next line.

Source code mapping creates a nested map structure which supports the break line stepping as well as ability to navigate to imported files; imported library files are not tested.

What needs to be done?

A first working alpha version v.0.1.0 will feature the following:

• Extract and display Solidity state variables

• Extract and display Solidity local variables

• Extract and display memory variables from both local

• Retrieve and display storage variables: reading the content might required implementing get_Storage RPC in Web3j EVM

• Function stack: EVM stack currently displays CONTRACT call type, it should display the current solidity in the stack and the function name.

• Complete source code mapping: this will be conjunction of Solidity source code mapping and navigation of the AST. The debug tracer has most of that based on the generated Binary and ABI code, but this feature can also levarage the PSI Solidity definition from me.serce.solidity.lang.psi.impl package.

• The variables can displayed in seperate panels

• Ability to select the function to debug (partially implemented)

Where to start?

To get started, Here is a recommended steps to follow:

1. Get the code from the repo here

2. Open the project and run the debugger using the runIde gradle task

3. To debug a sample project, we can create new Web3j using the instructions here. This will create a new HelloWorld Web3jApp

4. After running the sample project and testing the implemented debugger feature, the next is to study the plugin source code starting with the key components mentioned above in the class diagram section.

5. It's recommended to understand Web3j EVM and debug tracer class, a simpler version is the PassThroughTracer which simply dumps the opcodes for each line.

6. A good understanding of Solidity internals and EVM opcodes is important.

7. Look at other Intellij language projects for reference.

8. Look at remix debugger for reference.