|
1 | | -## Installation: |
| 1 | +This is a fork of: https://github.com/eveem-org/panoramix.git |
2 | 2 |
|
3 | | -``` |
4 | | -git clone https://github.com/eveem-org/panoramix.git |
5 | | -pip3 install -r requirements.txt |
6 | | -``` |
| 3 | +The goal of this fork is to maintain Panoramix in a decent shape, fix some crashes, implement missing opcodes... |
7 | 4 |
|
8 | | -## Running: |
9 | | - |
10 | | -You *need* **python3.8** to run Panoramix. Yes, there was no way around it. |
11 | | - |
12 | | -``` |
13 | | -python3.8 panoramix.py address [func_name] [--verbose|--silent|--explain] |
14 | | -``` |
15 | | - |
16 | | -e.g. |
17 | | - |
18 | | -``` |
19 | | -python3.8 panoramix.py 0x06012c8cf97bead5deae237070f9587f8e7a266d |
20 | | -``` |
21 | | -or |
22 | | -``` |
23 | | -python3.8 panoramix.py kitties |
24 | | -``` |
25 | | - |
26 | | -Output goes to two places: |
27 | | -- `console` |
28 | | -- ***`cache_pan/`*** directory - .pan, .json, .asm files |
29 | | - |
30 | | -If you want to see how Panoramix works under the hood, try the `--explain` mode: |
31 | | - |
32 | | -``` |
33 | | -python3.8 panoramix.py kitties paused --explain |
34 | | -python3.8 panoramix.py kitties pause --explain |
35 | | -python3.8 panoramix.py kitties tokenMetadata --explain |
36 | | -``` |
37 | | - |
38 | | -### Optional parameters: |
39 | | - |
40 | | -func_name -- name of the function to decompile (note: storage names won't be discovered in this mode) |
41 | | ---verbose -- prints out the assembly and stack as well as regular functions, a good way to try it out is |
42 | | -by running 'python panoramix.py kitties pause --verbose' - it's a simple function |
43 | | - |
44 | | -There are more parameters as well. You can find what they do in panoramix.py. |
45 | | - |
46 | | -### Address shortcuts |
47 | | -Some contract addresses, which are good for testing, have shortcuts, e.g. you can run |
48 | | -'python panoramix.py kitties' instead of 'python3 panoramix.py 0x06012c8cf97bead5deae237070f9587f8e7a266d'. |
49 | | - |
50 | | -See panoramix.py for the list of shortcuts, feel free to add your own. |
51 | | - |
52 | | -## Directories & Files |
53 | | - |
54 | | -### Code: |
55 | | -- core - modules for doing abstract/symbolic operations |
56 | | -- pano - the proper decompiler |
57 | | -- utils - various helper modules |
58 | | -- tilde - the library for handling pattern matching in python3.8 |
59 | | - |
60 | | -### Data: |
61 | | -- cache_code - cached bytecodes |
62 | | -- cache_pan - cached decompilation outputs |
63 | | -- cache_pabi - cached auto-generated p-abi files |
64 | | -- supplement.db - sqlite3 database of function definitions |
65 | | -- supp2.db - a lightweight variant o the above |
66 | | - |
67 | | -Cache directories are split into subdirectories, so the filesystem doesn't break down with large amounts |
68 | | -of cached contracts (important when running bulk_decompile on all 2.2M contracts on the chain) |
69 | | - |
70 | | -All of the above generated after the first run. |
71 | | - |
72 | | -## Utilities |
73 | | -bulk_decompile.py - batch-decompiles contracts, with multi-processing support |
74 | | -bulk_compare.py - decompiles a set of test contracts, fetches the current decompiled from Eveem, and prepares two files, so you can diff them and see what changes were made |
75 | | - |
76 | | -## Why **python3.8** and **Tilde** |
77 | | -Panoramix uses a ton of pattern matching operations, and python doesn't support those as a language. |
78 | | - |
79 | | -There are some pattern-matching libraries for older python versions, but none of them seemed good enough. |
80 | | -Because of that, I built Tilde, which is a language extension adding a new operator. |
81 | | - |
82 | | -Tilde replaces '~' pattern matching operator with a series of ':=' operators underneath. |
83 | | -Because of that, python3.8 is a must. |
84 | | - |
85 | | -Believe me, I spent a lot of time looking for some other way to make pattern matching readable. |
86 | | -Nothing was close to this good. |
87 | | - |
88 | | -But if you manage to figure out a way to do it without Tilde (and maintain readability), I'll gladly accept a PR :) |
89 | | - |
90 | | -# How Panoramix works |
91 | | - |
92 | | -See the source code comments, starting with panoramix.py. Also, those slides[tbd]. |
| 5 | +For now I only plan to implement very minor (but annoying fixes). If something is too complicated to understand or would require |
| 6 | +a non-negligible amount of time it won't be fixed. |
0 commit comments