DiSCo

DiSCo is a research prototype for lifting EVM bytecode to readable source-like contracts and is reimplemented based on the Panoramix decompiler: https://github.com/eveem-org/panoramix.git and https://github.com/palkeo/panoramix with semantic-unit extraction, LLM-guided code generation, and the GNN-based trainer for name inference.

It also maintains Panoramix in a decent shape, fix some crashes, implement missing opcodes, more optimizations for easier comprehension and more efficiency with some new designs.

The code quality still needs improvement, and the software is complex. We will continue working on it, and contributions or pull requests are welcome.

Features

• EVM bytecode decompilation for Solidity and Vyper contracts
• Offline analysis from creation or runtime bytecode files
• Online analysis through configurable RPC endpoints
• Semantic-unit extraction for explanation and description generation
• Optional LLM-based source-code reconstruction
• Trainer on the semantic-unit graph for semantic name inference

Requirements

• Python 3.10+
• Graphviz system executable
• Solc (for source compilation and artifact checks)
• Node.js is not required for DiSCo itself

Install the core dependencies:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

For training or inference with the paper's GNN trainer, install the optional trainer dependencies. DGL and PyTorch should be selected according to your CUDA version:

python -m pip install -r requirements-trainer.txt

Configuration

Copy the environment template:

cp .env.example .env

Then load the values you need, for example with:

set -a
source .env
set +a

Set only the RPC endpoints, LLM credentials, and provider endpoint overrides that you need. No credentials are embedded in source code; the private Azure endpoint is loaded from the environment. Configuration precedence and runtime flags are documented in docs/CONFIGURATION.md.

Decompile a contract

Bundled offline cases and staged pipeline commands are documented in examples/README.md.

Use a local bytecode file:

python -m panoramix --offline-contract ./examples/0xabc/0xabc.bin-runtime

Use an RPC endpoint:

export ETH_RPC_URL="https://your.ethereum.rpc"
python -m panoramix --chain eth --block-number 19000000 0xabc...

The bundled helper supports common offline-analysis options:

python scripts/decompile.sh --addr 0xabc... --file-dir ./examples --output result.json

Database

DiSCo includes a compressed SQLite database with local signature and inferred-name lookups. It is extracted automatically on first use. See docs/DATABASE.md for details.

Code generation

The experiment scripts are configurable CLI tools:

python scripts/bulk_decompile.py --help
python scripts/bulk_describe.py --help
python scripts/bulk_codegen.py --help
python scripts/bulk_compile.py --help

They expect contract workspaces you create from your own bytecode exports and write generated files below a user-supplied output root.

Trainer

The panoramix/trainer package contains graph construction, label clustering, RGCN training, and inference. Provide your decompiled contract units through environment variables such as:

export DISCO_TRAIN_UNITS_DIR=./output/trainer/units
python panoramix/trainer/make_label.py --type-aware --n-neighbors 5 --min-cluster-size 5
python panoramix/trainer/train.py --infer --n-neighbors 15 --min-cluster-size 5

Do not put training artifacts inside the repository; the default output directories are ignored by Git.

Artifacts

The repository includes small public CSV artifacts under disco_artifacts/ that summarize evaluation outputs. Large bytecode datasets and user-study files are intentionally excluded.

License

This project is released under the MIT License.