|
1 | 1 | # ethereum-graph-debugger |
2 | 2 |
|
3 | | - |
| 3 | + |
4 | 4 |
|
5 | | -Graphical Solidity debugger. This debugger takes a different approach to traditional debugging. |
6 | | -Instead of stepping through the execution of the program, it shows the whole program control flow graph and |
7 | | -the actual execution of the transaction highlighted in red. In this way, the developer can see the whole picture |
8 | | -and jump where it is necessary in a quick and graphical way. |
| 5 | +Graphical EVM debugger. This debugger takes a different approach to traditional debugging. Instead of stepping through the execution of the program, it shows the whole program control flow graph and the actual execution of the transaction highlighted in red. In this way, the developer can see the whole picture and jump where it is necessary in a quick and graphical way. |
9 | 6 |
|
10 | | -### Update with interactive UI coming soon... |
| 7 | +This project was rewritten with a frontend made by [Swolfeyes](https://github.com/Swolfeyes) and backend by [fergarrui](https://github.com/fergarrui) |
11 | 8 |
|
12 | | -# Usage |
13 | | - |
14 | | -``` |
15 | | -edebugger-<VERSION>.jar <OPTIONS> |
16 | | -Options category 'mandatory': |
17 | | - --address [-a] (a string; default: "") |
18 | | - The Address of the contract the transaction is executed against. Cannot be |
19 | | - set in combination with -f |
20 | | - --node [-n] (a string; default: "") |
21 | | - The node where the transaction was run. It must support |
22 | | - debug_traceTransaction |
23 | | - --source-file [-f] (a string; default: "") |
24 | | - The source file of the contract the transaction is executed against. Cannot |
25 | | - be set in combination with -a |
26 | | - --transaction-hash [-t] (a string; default: "") |
27 | | - Transaction hash to debug |
28 | | -
|
29 | | -Options category 'optional': |
30 | | - --d3-memory [-m] (a string; default: "537395200") |
31 | | - D3 graph memory. If the graph is too large, you may want to increase this |
32 | | - value (by multiplying it) |
33 | | - --[no]only-trace [-o] (a boolean; default: "false") |
34 | | - Exclude opcodes that are not executed in the transaction when creating the |
35 | | - graph. This may help if the graph is too large and the opcodes not executed |
36 | | - are not important |
37 | | -``` |
38 | | - |
39 | | -Example: |
40 | | -``` |
41 | | -java -jar edebugger-<VERSION>.jar -f ~/tests/Program.sol -n http://127.0.0.1:8545 -t 0x0c971feb820d2bca26c3e7a0a27b5015694d9ec8ea0169935ff7168a63da3f6f |
42 | | -``` |
43 | | - |
44 | | -# Download |
45 | | - |
46 | | -Go to the [releases](https://github.com/fergarrui/ethereum-graph-debugger/releases) section of this repo |
47 | | - |
48 | | -# Example debug file |
49 | | - |
50 | | -This file is made as a demo to see what this debugger does at this stage. The file can be found here: [Example debug file](http://htmlpreview.github.com/?https://raw.githubusercontent.com/fergarrui/ethereum-graph-debugger/master/examples/debug.html) |
| 9 | +[Development repository](https://github.com/fergarrui/ethereum-graph-debugger-ts) was archived, marked as read-only and moved here, to the main repo. |
51 | 10 |
|
52 | 11 | # Existing tools |
53 | 12 | There are already tools that allow you to debug Ethereum transactions (Solidity): |
54 | 13 |
|
55 | 14 | * [Remix](https://remix.ethereum.org) |
56 | 15 | * [Truffle](http://truffleframework.com) |
57 | 16 |
|
58 | | -# Important note |
59 | | -The bytecode generated by this debugger is compiled **without** compiler optimizations. Make sure to turn it off if you are, for example, using Remix to deploy the contracts. An option should be added anyway to this debugger to support contracts deployed with optimized bytecode. |
60 | | - |
61 | | -# Features |
62 | | - |
63 | | -* It compiles the provided source code and draws a control flow graph (also imported contracts) |
64 | | -* It supports debugging of transactions even if no source code is provided (option `-a`). It will draw the CFG and trace the transaction |
65 | | -* From the provided transaction hash (using `debug_traceTransaction`) it gets the trace of the transaction |
66 | | -* Combines the control flow graph with the execution trace, highlighting the executed instructions in red |
67 | | -* Supports contracts calls. All contracts involved in the transaction can be debugged |
68 | | -* Instructions opcodes can be clicked in the graph, and the Solidity source code in the left panel involving that instruction is highlighted. |
69 | | -* For the selected opcode, The EVM state is shown (stack, memory, storage, gas, gasCost) |
| 17 | +# Usage |
70 | 18 |
|
71 | | -# Limitations |
| 19 | +Clone and start the application |
72 | 20 |
|
73 | | -For now there are many limitations since this is a very early release of the debugger |
| 21 | +For the first time: |
| 22 | +``` |
| 23 | + git clone https://github.com/fergarrui/ethereum-graph-debugger.git |
| 24 | + cd ethereum-graph-debugger |
| 25 | + npm install |
| 26 | + npm start |
| 27 | +``` |
| 28 | +Subsequents just: |
74 | 29 |
|
75 | | -* The control flow graph is drawn from the static bytecode, so there can be nodes without all edges, a symbolic execution would be needed. Maybe will be added in future releases |
76 | | -* Transactions executed in the runtime bytecode are supported (for example, the constructor execution of a contract cannot be debugged right now) |
77 | | -* You must provide a node URL that supports `debug_traceTransaction`, like Geth or Ganache, therefore, Infura is not supported |
78 | | -* It only supports Solidity or bytecode for now, but planning to make it more modular to support different languages (if the compiler gives source mappings) |
79 | | -* The interface is quite ugly, but usable |
80 | | -* Not really a limitation, but the editor syntax highlighting is set to Javascript at the moment |
81 | | -* Probably many more |
| 30 | +``` |
| 31 | +npm start |
| 32 | +``` |
82 | 33 |
|
83 | | -# Build the project |
| 34 | +Go to localhost:9090 |
84 | 35 |
|
85 | | -`mvn clean package` creates a fat executable jar at: `target/edebugger-<version>.jar` |
| 36 | +# Features |
86 | 37 |
|
87 | | -A dependency needs to be in your local maven repository (I want to rewrite that in the future). |
88 | | -The project [Ethereum disassembler](https://github.com/fergarrui/ethereum-disassembler) must be installed using `mvn clean install`. |
| 38 | + * Now interactive :star2:: it has a sepparate frontend and API instead of building a static HTML file like in earlier versions |
| 39 | + * Control flow graph: the CFG can be built without debugging a transaction. |
| 40 | + * Disassembler: just disassembled opcodes can be seen, from runtime and constructor |
| 41 | + * Source mapping: snippet of code related to the selected instruction is highlighted in the editor left panel |
| 42 | + * Debug transaction: a transaction can be debugged using the contract's CFG and the execution trace |
| 43 | + * Supports contracts calls. All contracts involved in the transaction can be debugged (going to the caller/called tab to see the contract-specific trace) |
| 44 | + * EVM state in transaction: it is shown below the editor when selecting an opcode present in the execution trace of the provided transaction hash |
| 45 | + * Settings: right now, there are settings to point to a different chain (by default it connects to http://127.0.0.1:8545) and basic authentication can be configured, so the RPC endpoint can be accessed if authentication is needed (to be compatible with platforms like [Kaleido](http://kaleido.io)) |
| 46 | + * When building the CFG a basic dynamic execution is made to calculate jumps and to remove most of orphan blocks (this will be improved in the future, probably with SymExec) |
| 47 | + |
| 48 | +# Limitations/Considerations |
| 49 | + |
| 50 | + * Only Solidity is supported at the moment |
| 51 | + * Only runtime debugging is supported for now (no constructor) |
| 52 | + * You must run it against a node that supports `debug_traceTransaction`, like Geth or Ganache, therefore, Infura is not supported |
| 53 | + * It was rewritten, so new bugs may appear |
0 commit comments