Zean: write Zig, prove it in Lean

Zean


We just open-sourced Zean (Zig + Lean), a toolkit for translating supported Zig functions into executable Lean models and proving their behavior. It came out of our formal verification work on oksolc, our Solidity compiler written in Zig.

Zean works from AIR, Zig’s analyzed intermediate representation. An instrumented compiler captures supported functions from AIR, and a translator emits executable Lean program definitions. Specifications and proofs live in separate handwritten Lean modules.

A verification library derives the proof obligations for memory access, initialization, permissions, arithmetic, control flow and supported calls. You write the contracts and loop invariants. If an obligation still needs a mathematical argument, you supply that too, and Lean checks the proofs. Unsupported operations are rejected, and unresolved obligations stay open.

The copy tutorial shows what that looks like:

inline fn copyWord(destination: *u32, source: *const u32) void {
    destination.* = source.*;
}

pub export fn copy(destination: [*]u32, source: [*]const u32, length: usize) void {
    var index: usize = 0;
    while (index < length) : (index += 1) {
        copyWord(&destination[index], &source[index]);
    }
}

The caller has to establish that the source has enough initialized words and the destination has enough writable storage. For the source-preservation contract, the two ranges also have to be disjoint. Under those assumptions the proofs show there are no invalid accesses or uninitialized reads. A successful run copies the source contents into the destination and preserves memory outside it. Modeled allocation exhaustion is an explicit permitted failure, and termination is a separate property.

Change the loop bound from < length to <= length and you get an extra boundary access that the original contract can’t justify. The tutorial also includes deliberately false claims that must fail verification.

When the Zig source changes, you recapture the function to regenerate the model, then replay the proofs.

This release covers memory-safety examples derived from Ziglings, buffer updates, copy loops, helper calls and a captured specialization of std.mem.replaceScalar. It supports restricted AIR fragments, with explicit target and layout constraints. The capture pipeline, the Zig frontend and the native backend remain trust boundaries, so the proofs don’t establish correctness of the final native binary or of the whole compiler.

The idea is to keep design iteration in Zig and prove a component’s contracts once it has settled.

To try it you need Zig 0.17.1 and elan:

git clone https://github.com/okcontract/zean
cd zean
elan toolchain install leanprover/lean4:v4.35.0
zig build ziglings

It’s released under Apache 2.0. If you write Zig or Lean, I’d like to know which functions you’d want to verify with it first.

If you like it, leave a star on the repo. And if you’d like more updates, give us a follow: OKcontract Labs | Chainwall (@okcontract) / X

8 Likes

I’m not super familiar with what’s encoded in AIR, but does it allow for modelling atomics? There’s a section of my interpreter that has some delicate multithreaded state, and it would be incredible to have a proof for that section of code (admittedly I haven’t done pretty much any formal verification before, but it’s something I’d like to pick up one of these days).

very cool, this seems like what is described by the commenters in this zig issue

AIR can represent atomic operations, but whether Zean’s translator accepts them is a separate question; the announcement says unsupported operations are rejected and the current fragment is aimed at memory-safety contracts. For delicate multithreaded state, the hard part is the concurrency specification: which interleavings, atomics, and memory ordering you assume. A practical first step is to model the shared state machine sequentially in Lean, prove its invariants, then add a small scheduler/atomics layer with explicit assumptions. That can be useful even before AIR-level support exists.