Source and bytecode verification for deployed EVM smart contracts.

Quick Start · How-To Guides · Configuration Reference · CLI Reference · Bytecode Comparison

Diffyscan compares deployed EVM contracts with source code pinned to a GitHub commit. It retrieves explorer-verified sources, generates source diffs, recompiles the pinned revision, and compares the resulting runtime bytecode with live chain state. Unapproved differences produce a non-zero exit code for local and CI use.

Quick start

Requirements: Python >=3.11,<4, uv, a GitHub API token, a block explorer API token, and an RPC endpoint for the target network.

git clone https://github.com/lidofinance/diffyscan.git
cd diffyscan
uv sync --locked
cp .env.example .env

Set the API tokens and RPC URLs required by your config, then run it:

uv run diffyscan config_samples/ethereum/mainnet/circuit-breaker/circuit_breaker_config.yaml

What it checks

• explorer-verified sources against files at the pinned GitHub commit
• compiled runtime bytecode against code deployed on-chain
• constructor-set immutable values through remote eth_call simulation
• expected differences declared with granular allowed_diffs rules

To reproduce deployment bytecode, Diffyscan trusts explorer-provided constructor calldata, linked-library addresses, compiler settings, and EVM version as inputs.

Development

The Dev Container uses the same image as the regression workflow. For a manual checkout:

uv run pre-commit install
uv run pytest -q
uv run mypy
uv run black --check diffyscan tests
uv run pre-commit run --all-files

Pull requests, bug reports, and feature requests are welcome. Report security issues through private vulnerability reporting.

License

MIT