Formal Solidity semantics in Lean 4 — the engine behind the Lean Semantics divergence challenge.
  • Lean 73.2%
  • Solidity 18.7%
  • Python 7.9%
  • Shell 0.2%
Find a file
History 2026-11-15 02:02:20 -08:00
contest Optimize Spec Hunt builds, witnesses, and replay runtime 2026-09-29 15:26:27 -07:00
docs Optimize Spec Hunt builds, witnesses, and replay runtime 2026-09-29 15:26:27 -07:00
probes items 1/3/4/5: array-literal-of-storage front-end acceptance (env-aware typing + decline fallbacks, Forge-validated), constructor-family collapse (incDec/assignment/castOp/encode/extFnPart with match_pattern legacy spellings, single eval dispatch per family), contents-vs-load reader unification (shared layout reader, corners documented), sound operator using-for fallback (target-typed binding) 2026-07-21 00:13:32 -04:00
scripts Fix nested function-pointer and storage-path lowering 2026-09-30 06:17:17 -07:00
SolidCore Validate storage bytes headers before deletion (#167) 2026-11-15 02:02:20 -08:00
tests Optimize Spec Hunt builds, witnesses, and replay runtime 2026-09-29 15:26:27 -07:00
.gitignore Checkpoint: full June source-semantics work (98-case corpus, harness, typechecker/interpreter growth) 2026-07-06 00:35:19 -07:00
ARCHITECTURE.md Stage 3+4 (openworld/postworld): PostDelta rows, reentrancy lanes, A2-debit fold, docs 2026-07-07 06:46:42 -07:00
CALLDATA_WRAP_DESIGN.md WS3 Stage A: #129 calldata tail-wrap design note + EVM-verified Forge lane 2026-07-12 16:47:41 -07:00
DIVERGENCE-LOG.md docs: track DIVERGENCE-LOG.md (registry provenance for the DL## known-gap entries) 2026-07-22 03:52:07 -04:00
ENV_LOWERING_DESIGN.md R2 design note: record the literal-constant fix-forward (uniswap-v2 regression) 2026-07-12 05:17:00 -07:00
EVAL_ORDER_DESIGN.md fix: right-first eval for binary with non-core-call LHS and pure state-read RHS (g()*100000 + t) (#15) 2026-07-20 14:18:28 +00:00
KeccakParity.lean keccak from EVMYulLean pin b08573c; alphabet imports via EvmInteraction.* modules 2026-07-09 14:42:24 -07:00
lake-manifest.json Pin evm-interaction as a git dependency @ c939817 (was floating path dep) 2026-07-10 12:53:06 -07:00
lakefile.lean Optimize Spec Hunt builds, witnesses, and replay runtime 2026-09-29 15:26:27 -07:00
lean-toolchain Phase 1: substrate unification onto evm-compiler's toolchain + EVMYulLean pin 2026-07-06 02:52:42 -07:00
LICENSE-APACHE license: MIT OR Apache-2.0 dual (Paradigm OSS convention; (c) 2026 solidity-lean Contributors) 2026-07-24 10:42:20 -04:00
LICENSE-MIT license: MIT OR Apache-2.0 dual (Paradigm OSS convention; (c) 2026 solidity-lean Contributors) 2026-07-24 10:42:20 -04:00
LOWERING_UNIFY_DESIGN.md docs: record §3c phase-1 collapse landing + OZ lane timing evidence (no perf regression; 300s budget is contention-sensitive) 2026-07-21 02:49:03 -04:00
PrecompileParity.lean feat: implement bnPairing (0x8) and pointEvaluation (0xa) in-semantics 2026-07-19 22:51:21 -04:00
PROGRESS_LOG.md Lower pop on conditional storage array receivers (#118) 2026-10-11 13:58:37 -07:00
README.md license: MIT OR Apache-2.0 dual (Paradigm OSS convention; (c) 2026 solidity-lean Contributors) 2026-07-24 10:42:20 -04:00
ROADMAP.md Merge refactor/ref-signatures: all reference/pointer signatures on the internal-function boundary; splice deleted 2026-07-07 13:32:02 -07:00
SolidCore.lean Validate storage bytes headers before deletion (#167) 2026-11-15 02:02:20 -08:00
SpecHuntRunner.lean Optimize Spec Hunt builds, witnesses, and replay runtime 2026-09-29 15:26:27 -07:00
STMT_DISPATCH_UNIFY_DESIGN.md stage 4: record unification results in STMT_DISPATCH_UNIFY_DESIGN 2026-07-12 21:56:17 -07:00
STORAGE_REF_DESIGN.md WS2 closing: record Stage B/C results in the design note (build green, 14-lane self-gate all ok) 2026-07-12 15:46:42 -07:00
TYPECHECK_KEYING_DESIGN.md R4 design note: record audit results, target-4 fix, dead-family deletion 2026-07-12 06:45:09 -07:00
VALUE_TYPING_DESIGN.md R3 fix-forward: make the bytesN width tag invisible at EVERY public boundary and tag-agnostic in coercion (6-fixture gate regression) 2026-07-12 02:53:13 -07:00

solidity-lean — a machine-checked Solidity semantics (SolidCore)

SolidCore is an executable, machine-checked semantics of Solidity written in Lean 4. It typechecks, lowers, and runs real single-contract Solidity programs inside Lean, and its behavior is continuously validated against the reference toolchain: pinned solc 0.8.35 + the real EVM (via Foundry).

The claim this repo makes is narrow and falsifiable: for programs in scope, the on-chain observable computed by the Lean semantics — return data, revert/panic data, emitted events, final storage — is byte-identical to what solc-compiled bytecode produces on the EVM. When that claim fails, it's a bug here, and we fix it at the root.

Spec Hunt — find a divergence, get credited

This repo is the subject of Spec Hunt: submit a Solidity program where this semantics disagrees with real solc + EVM. Every accepted divergence is a concrete, credited bug in the formal model — and its fix lands here, in public, with a regression witness.

  • How to submit: contest/SUBMITTING.md (submission layout, claim.json schema, local adjudication via python -m contest.adjudicate)
  • What's in scope: contest/README.md and the exclusion register (versioned; currently single-contract v1 scope — no external calls, no inline assembly, no gas introspection; precompile staticcalls to literal addresses are in scope)
  • Known/fixed divergences: DIVERGENCE-LOG.md and the fingerprint registry (contest/known_gaps.py) — submissions matching an already-known gap don't score

Validation, continuously

  • 99 witness modules (SolidCore/Witness/) pin end-to-end behavior of fixed programs — every bug fix ships with one.
  • 290-case replay corpus (tests/forge-harness/): each case compiles with pinned solc, executes on a real EVM via forge, and must match the Lean observable byte-for-byte (scripts/run_forge_interpreter_harness.py).
  • Proof obligations (FuelMonotonicity, AdoptionLaws) are checked on every build — Lean will not compile a module whose proofs don't close.
  • Contest sample suite (python3 -m contest.run_samples): ~85 end-to-end adjudication checks, including fault-injection selftests of the detectors themselves.

Building

Prerequisites: elan (Lean toolchain is pinned by lean-toolchain), pinned solc 0.8.35 (solc-select install 0.8.35), and Foundry (foundryup) for the EVM side.

lake build                      # full build: semantics + proofs + all witnesses
scripts/fast_inner_gate.sh      # fast inner loop: semantic spine + laws only
scripts/compare_forge_solc_interpreter.sh   # replay corpus vs real EVM
python3 -m contest.run_samples  # contest harness end-to-end suite

Repository map

Path What
SolidCore/Solidity/ The semantics: importer, TypeCheck, Interface (lowering), Interpreter, ABI, proofs
SolidCore/Witness/ Pinned end-to-end behavior witnesses (one per fixed bug family)
contest/ The Spec Hunt adjudication harness: reject gate, exclusion register, observable comparator, dedup fingerprints, sample suite
tests/forge-harness/ The solc+EVM replay corpus
scripts/ Build/replay/measurement tooling
docs/, *_DESIGN.md Design notes and decision records

Scope

v1 is deliberately single-contract: one contract, one entrypoint call, a pinned environment (Foundry defaults). External calls, contract creation, inline assembly, and gas introspection are out of scope and rejected by the gate — see the exclusion register for the precise, versioned list. The multi-contract responder (v2) has a documented seam but is not part of the contest today.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

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