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-14 20:25:50 -06:00
.github/workflows feat(infer): read solar-verify's loop-cut interface (format 1) instead of the stub 2026-11-14 20:25:50 -06:00
Certified feat(uniswap-v2): certified transfer at 0x2000 2026-11-14 14:26:54 -06:00
contest Optimize Spec Hunt builds, witnesses, and replay runtime 2026-09-29 15:26:27 -07:00
Contracts feat(uniswap-v2): certify transfer from any caller 2026-11-14 17:50:34 -06:00
docs feat(frontend): translate inline assembly create2 2026-11-14 13:52:14 -06:00
Loom fix: restore SolidCore, Loom and Verify on the translation branch 2026-11-13 00:59:22 -06: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 feat(uniswap-v2): certify transfer from any caller 2026-11-14 17:50:34 -06:00
SolidCore feat(uniswap-v2): certify transfer from any caller 2026-11-14 17:50:34 -06:00
tests Optimize Spec Hunt builds, witnesses, and replay runtime 2026-09-29 15:26:27 -07:00
tv fix(tv): fold right literals of || and && by rewriting 2026-11-14 16:39:36 +00:00
vendor fix: restore SolidCore, Loom and Verify on the translation branch 2026-11-13 00:59:22 -06:00
Verify feat(infer): read solar-verify's loop-cut interface (format 1) instead of the stub 2026-11-14 20:25:50 -06:00
.gitignore feat(uniswap-v2): approve and transferFrom stage 2026-11-14 12:00:17 -06: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 fix: restore SolidCore, Loom and Verify on the translation branch 2026-11-13 00:59:22 -06:00
lakefile.lean feat(uniswap-v2): certify transfer from any caller 2026-11-14 17:50:34 -06:00
lean-toolchain feat(refinement): certify solar output to bytecode 2026-11-12 17:35:31 -06: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
Loom.lean fix: restore SolidCore, Loom and Verify on the translation branch 2026-11-13 00:59:22 -06: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 chore(tv): drop the old token milestone 2026-11-13 04:57:06 -06: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 feat(refinement): certify solar output to bytecode 2026-11-12 17:35:31 -06: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
Verify.lean feat(refinement): assembly with environment reads, run oracles and call families 2026-11-13 10:06:01 -06: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.

Follow-ups

  • Two SMT term ASTs coexist: Verify/Obligation/Smt.lean (Srt, Op, Term, the obligations the certified contracts discharge) and Verify/VC/Term.lean (Srt, Tm, Cmd, solar-verify's SMT-LIB transcripts). They should become one AST with one evaluator. This is deferred: the frozen VC manifests (Contracts/{ArrayMax,Vault}/Vc/manifest.json, Verify/Discharge/frozen/PINS) record the sha256 of Smt.lean, so merging them means regenerating and re-checking those obligations against the new hash in one change.

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.