Solidity Spec

Solidity Spec is an executable formal model of Solidity in Lean. It follows our work on oksolc's compiler verification.

This standalone Lean 4.29.0 package targets Solidity 0.8.36, reference compiler 0.8.36+commit.8a079791, and Cancun. target.json and Solidity/Target.lean record the pin; an accepted pragma does not select a different semantics. Compiler compatibility is scoped to viaIR: true, with optimization disabled or enabled at 200 runs. Legacy code generation is outside this profile: it can perform implicit aggregate argument copies before later argument effects, whereas the documented IR policy gathers raw arguments before conversion. This scope is not a proof of general compiler conformance.

The package contains certificate models and a shared typed core with correspondence proofs for its statement and certificate interfaces. It is an incomplete, standalone Solidity formalization.

Read the paper (LaTeX source) for the semantics and trust boundary. The external conformance checks compare selected machine executions with the pinned compiler and a local Cancun EVM, including explicit legacy-pipeline boundary controls.

LayerAuthoritative sourcesRole
Unified scalar, aggregate and effect coreSolidity/Core, Solidity/Core/Aggregates, Solidity/Core/ExecutionWidth-indexed values, physical aggregate references, permitted effect orders, scopes, loops and internal function frames
Correspondence proofsSolidity/Proofs, Solidity/Compatibility/ExecutionWord, typed-expression, condition and stateful evaluators agree with the core; complete call certificates imply core trace preservation
Checked frontend stagesSolidity/FrontendTyped name resolution, rational constants, exact integer conversion, structural elaboration and evaluation preservation; unannotated scalar inference and nominal types
Words and typed contract languageContract/Language, Contract/SemanticsTyped finite statements, explicit arithmetic modes, rollback, helpers, logs
Admitted SoliditySolidity/Word.lean, Checked.lean, Function.lean, ABI.lean, StorageSource.leanExpression evaluation, call admission, stateful statements
Layout and initializationSolidity/StorageLayout.lean, StorageInitialization.lean, StorageConstructor.leanPacked Boolean fields, word fields, declaration order and constructor execution
Target machineContract/EvmPartial Cancun bytecode semantics, gas, storage and deployment frames
Supporting modelsContract/Yul, Contract/Interaction, Contract/ExportWord expressions, world/memory operations and Keccak
Certificate interfacesSolidity/Call.lean, Contract.lean, Storage.lean, StorageCreation.leanPrecise predicates and composition theorems for accepted artifacts
Proof auditContract/CheckDependency/axiom inspection for selected theorem contracts

Paths following the first entry in a cell are relative to the same directory. The resolved machine and certificate interfaces have different input domains. Consult the paper for their source-admission assumptions and proof scope.

Build and check

From the root of this package, with the toolchain in lean-toolchain installed:

make replay

make check builds both libraries and their regression modules with four Lean workers. make replay also checks selected theorem statements, transitive axioms and definition-source identities, then freshly rechecks the foundation, pilot and scalar machine proof closures, one at a time. Set JOBS to change build parallelism. For an explicit installation, prepend the Lean 4.29.0 bin directory to PATH so Lake and the kernel checker share the same toolchain. The package uses Lean's bundled Std and has no external Lean package dependencies. The manifest checks require Python 3's standard library; no Zig compiler is required.

To rebuild the paper with Tectonic:

make paper

The result is paper/solidity-semantics.pdf; intermediate files stay in paper/build/. Tectonic may download its TeX bundle on the first build.

Use the model

Use import Solidity.Execution for lightweight checked execution. Additional laws are in Solidity.Execution.Proofs, and admitted-state safety is in Solidity.Execution.Safety. Compiler-model bridge clients use Solidity.Compatibility.Execution. The Solidity umbrella exports all of these interfaces. Certificate clients also use the exported Compiler.Validation namespaces.

The execution machine consumes resolved, typed trees and explicit program tables. It models effect-order choices, physical aliases, scopes, loops, internal calls and rollback. Source return, revert and fault remain distinct from unsupported behavior and interpreter exhaustion. Host-work bounds are separate from EVM gas.

A successful proof checks a statement about this model under its stated assumptions. The safety contract describes the supported configuration profile; the paper explains the scope of the executable model and the interpretation of its certificate interfaces.

Documentation

Source licensing is GPL-3.0. Vendored reference snapshots retain their upstream notices and licenses.