Beat a formally verified Yul → EVM compiler on total gas — while its machine-checked correctness theorem still proves.
  • Lean 89.4%
  • Python 6.7%
  • Shell 3.9%
Find a file
Dan Robinson 32c7cdbc0b arena flow: auto-scored PRs, records tagged from PR head (no merges)
Two flow changes for Season 1:
- Private scoring is automatic: the offline bot polls open arena PRs with
  green required checks; the scoring-requested label is now a legacy no-op
  hook that just explains this.
- Submission PRs are never merged. A winning PR's exact head commit is
  tagged record-N in this repo and the leaderboard entry points at the
  branch on the contestant's fork; the arena branch carries only the
  baseline and the records ledger.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018etYCo1cWUzqaqNkqZCVRU
History 2026-07-24 16:06:00 -04:00
.claude/worktrees Checkpoint current tree 2026-06-10 10:59:06 -07:00
.github arena flow: auto-scored PRs, records tagged from PR head (no merges) 2026-07-24 16:06:00 -04:00
aristotle_runs/arity-primitive-stack Add Aristotle prompts for for-loop arity spine 2026-05-25 14:09:20 -07:00
benchmarks benchmarks: refresh record-0 commit refs after transcript history rewrite 2026-07-24 11:33:31 -04:00
docs/solidity-lowering docs: mark roadmap Stage 1.2/1.3 (alphabet + keccak unification) done 2026-07-10 12:53:34 -07:00
EthereumTests compile full solc contracts with proved fast paths 2026-06-19 10:29:50 -07:00
EvmCompiler PEEPHOLE_PROGRESS §101: reorder SPLICE live; corpus −7.47%→−7.76% (−1219 B, −270402 gas); determinism byte-identical; axioms unchanged 2026-07-21 13:14:28 -04:00
examples corpus: add ProcedureReuseBox (deep call-graph) + WideDispatchBox (dispatcher-heavy) 2026-07-21 13:40:01 -04:00
experiments/lean_python_bpb Organize proof artifacts and BPB harness 2026-07-01 23:22:19 -07:00
proof_artifacts Audit the freeze-contract crowns + OpenRunContainment in the CI axiom gate 2026-07-09 07:37:50 -07:00
proof_assembly WIP derive structured primitive arity contracts 2026-05-25 23:59:28 -07:00
proof_requests Make Lean 4.22 baseline buildable 2026-06-03 13:31:59 +02:00
scripts surface/eigenlayer tests: hoist cast calldata out of argument position; guard required tools 2026-07-19 23:29:03 -04:00
skills/verifiable-compiler skills/verifiable-compiler: drop outdated project-specific references, add freeze-mode guidance 2026-07-15 10:04:05 -07:00
.gitignore Public-repo hardening: CI, CODEOWNERS, contribution docs 2026-07-05 23:01:28 -07:00
.python-version Add reproducible setup and full test runner 2026-06-26 12:49:05 -07:00
CHALLENGE.md arena flow: auto-scored PRs, records tagged from PR head (no merges) 2026-07-24 16:06:00 -04:00
CONTRIBUTING.md Public-repo hardening: CI, CODEOWNERS, contribution docs 2026-07-05 23:01:28 -07:00
EvmCompiler.lean Single supported spine: archive legacy Public.compile? path 2026-07-03 10:52:19 -07:00
EXTERNAL_EFFECTS_ROADMAP.md Organize proof artifacts and BPB harness 2026-07-01 23:22:19 -07:00
lake-manifest.json deps: repoint evmyul to paradigmxyz/EVMYulLean (same rev b08573c); re-pin lake-manifest hash 2026-07-23 16:42:18 -04:00
lakefile.lean deps: repoint evmyul to paradigmxyz/EVMYulLean (same rev b08573c); re-pin lake-manifest hash 2026-07-23 16:42:18 -04:00
lean-toolchain Migrate project to Lean 4.28 2026-06-03 13:58:54 +02:00
LICENSE-APACHE Add MIT OR Apache-2.0 dual licensing (Paradigm OSS convention) 2026-07-24 10:43:17 -04:00
LICENSE-MIT Add MIT OR Apache-2.0 dual licensing (Paradigm OSS convention) 2026-07-24 10:43:17 -04:00
Makefile Add reproducible setup and full test runner 2026-06-26 12:49:05 -07:00
NON_CALL_GAPS_ROADMAP.md docs: narrow compiler preservation gap boundary 2026-06-25 09:40:44 -07:00
OPTIMIZING.md docs(OPTIMIZING): fix stale corpus count in sample output (48 -> 40) 2026-07-22 09:42:59 -04:00
PRODUCTION_ASSUMPTIONS.md Rename Lake package «evm-compiler»→«solidus», exe evm-compiler-backend→solidus-backend 2026-07-14 10:13:47 -07:00
PROGRESS_LOG.md docs: fill CORPUS_DESIGN baseline totals + CHALLENGE pointer + PROGRESS_LOG entry 2026-07-21 13:40:01 -04:00
pyproject.toml Rename Lake package «evm-compiler»→«solidus», exe evm-compiler-backend→solidus-backend 2026-07-14 10:13:47 -07:00
README.md Add MIT OR Apache-2.0 dual licensing (Paradigm OSS convention) 2026-07-24 10:43:17 -04:00
ROADMAP.md Rename Lake package «evm-compiler»→«solidus», exe evm-compiler-backend→solidus-backend 2026-07-14 10:13:47 -07:00
uv.lock Rename Lake package «evm-compiler»→«solidus», exe evm-compiler-backend→solidus-backend 2026-07-14 10:13:47 -07:00

Solidus

Solidus is a work-in-progress compiler from Solidity to the EVM, implemented and formally verified in Lean 4.

⚠️ Pre-alpha. Solidus is a research project, not production software. Do not use it to compile contracts that hold real value.

What is here today

The backend of Solidus — from Yul (the intermediate representation used by the Solidity compiler) down to EVM bytecode — is essentially complete and formally verified. A single Lean theorem, Solidus.compile_correct, connects the source program's semantics to the emitted bytes on a pinned EVM interpreter. The EVM and Yul semantics live in their own repository — paradigmxyz/EVMYulLean, a fork of Nethermind's EVMYulLean with some corrections — and this repository builds its Yul program semantics (the source side of the theorem) on top of that base.

The frontend (Solidity → Yul) does not exist yet. Today the supported pipeline takes the irOptimizedAst Yul object emitted by a pinned solc and compiles it to bytecode, with a machine-checked preservation proof from compile success alone. Finalizing a frozen Solidity source semantics and building a verified frontend against it is the next phase of the project.

Because the correctness claim is a machine-checked theorem over a frozen specification, contributions do not need a "did you break something" review step: if the compiler builds, the axiom audit is clean, and the frozen spec still elaborates, a rewrite is correct by construction. That is what makes aggressive, trustless optimization — including by untrusted automated contributors — possible. See CHALLENGE.md for the optimization challenge built on this property.

How it was built

Solidus is an automated-research project: no human read or wrote a line of its code. It was built over roughly ten weeks of aggregate agent time across many parallel threads, primarily with OpenAI's Codex, with Harmonic's Aristotle used for some of the hardest proofs and Claude used for some of the final steps. Humans supplied the spec judgment and some of the higher-level proof architecture.

Trust boundary and proof status

  • PRODUCTION_ASSUMPTIONS.md — the authoritative trust and theorem boundary, including a "Which theorem should I rely on?" guide.
  • ROADMAP.md — current proof scope and remaining gaps.
  • CHALLENGE.md — the Solidus optimization challenge: make compiled contracts cheaper while the theorem still proves.
  • CONTRIBUTING.md — how to contribute.

Install on macOS or Linux

The bootstrap script installs user-local tooling and project dependencies. It does not use sudo.

System prerequisites:

  • macOS: install the Xcode command-line tools (xcode-select --install) and jq (brew install jq).
  • Debian/Ubuntu: sudo apt-get install -y build-essential ca-certificates curl git jq.
  • Other Linux distributions: install a C/C++ toolchain, curl, git, and jq with the system package manager.
  • Linux ARM64 also needs qemu-x86_64 (for example, sudo apt-get install qemu-user-static) because the pinned solc binaries are x86-64.

Then run:

git clone https://github.com/paradigmxyz/solidus.git
cd solidus
./scripts/setup.sh

Setup installs and selects:

  • Python 3.12 and the locked Python environment through uv;
  • elan and the Lean version pinned by lean-toolchain;
  • the Lake dependencies pinned by lake-manifest.json and the Mathlib cache;
  • solc-select 1.2.0 with solc 0.8.17, 0.8.19, 0.8.26, and 0.8.35;
  • Foundry v1.5.1 (forge, cast, anvil, and chisel).

The official installers used by the script are documented by Lean/elan, uv, and Foundry. Set SKIP_MATHLIB_CACHE=1 to skip only the optional prebuilt Mathlib download, or FOUNDRY_VERSION=vX.Y.Z to test another Foundry release.

Run the tests

Run every Lean, Python, shell, real-contract, and supported-solc test exactly once (with the nine compiler-surface tests run once for each supported solc):

make test
# equivalent: ./scripts/test_all.sh

The full suite fetches pinned public contract repositories, so it requires network access. It continues after individual failures and writes one log per test under .test-results/<timestamp>/, then exits nonzero with a summary.

Useful focused commands:

make verify       # architecture checks, full Lean build, proof smokes
make python-test  # Python unit suite in the uv environment
uv run -- scripts/test_advanced_type_surface_backend.sh

No manual virtual-environment activation or pip install is needed. Use uv add <package> when changing Python dependencies, commit both pyproject.toml and uv.lock, and use uv run -- <command> for an individual script that imports project Python dependencies.

Detailed bridge and diagnostic command documentation lives in scripts/README.md.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.