Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
b9bcccc
feat(formal): Clean/Lean model of BITWISE, LT, EQ and SHIFT with proo…
ColoCarletti Oct 22, 2026
2b2d9e2
refactor(formal): single lemma for the bit constraint and chips call …
ColoCarletti Oct 26, 2026
2f0fa4b
refactor(formal): ADD/SUB template, LT RowSpec, flags decoded as natu…
ColoCarletti Oct 28, 2026
aa28a67
refactor(formal): ltRaw via BitVec.slt and BitVec.ult
ColoCarletti Oct 28, 2026
a2c6e7a
Merge remote-tracking branch 'origin/main' into formal/clean-model
ColoCarletti Oct 28, 2026
3246375
test(prover): differential check of the Lean models against LT, EQ an…
ColoCarletti Oct 28, 2026
0e4f569
style(prover): rustfmt and clippy fixes in lean_diff
ColoCarletti Oct 28, 2026
59ef8a0
fix(formal): reproducible export, CI check and stricter differential …
ColoCarletti Oct 28, 2026
bb291bb
refactor(formal): shared carry lemmas, named opsels, spec-form HWSL g…
ColoCarletti Oct 28, 2026
2ca8eec
refactor(prover): share the test RNG and the multiplicity evaluator w…
ColoCarletti Oct 28, 2026
3b04970
Bump Clean to f3abad7c (current main, Lean v4.35.0) and adapt the mod…
jotabulacios Nov 2, 2026
48fd9e7
Rename the if/dif lemmas that Lean v4.35.0 deprecates, and drop a ski…
jotabulacios Nov 2, 2026
194d06e
Remove req_vacuous and requirement_vacuous, which no proof uses since…
jotabulacios Nov 3, 2026
bf58630
Reword the doc comment of rust_interaction_at in lean_diff.rs so it s…
jotabulacios Nov 3, 2026
377b125
Answer pull demand in eqComponent generation
jotabulacios Nov 3, 2026
23894db
Update formal/README for the new Clean API
jotabulacios Nov 3, 2026
bdcb2dc
Merge pull request #1030 from yetanotherco/formal/clean-migration
jotabulacios Nov 3, 2026
63e700f
fix(formal): bounded lake cache key, per-table lean_diff seed, untrac…
ColoCarletti Nov 11, 2026
3c5a44b
fix(spec): read class annotations via type(self), which Python 3.14 r…
ColoCarletti Nov 11, 2026
87db021
Add a BITWISE differential check, pin the LT deltas and cover EQ padd…
nicole-graus Nov 11, 2026
a3b9cb8
Check all BITWISE rows and use per-opsel IS_WORD assumptions in the A…
nicole-graus Nov 11, 2026
cf354d4
fix padding asserts, isByte slot, shared lemmas, doc fixes
nicole-graus Nov 12, 2026
f927f3e
fix(formal): caveat on the LT circuit, date-free README results, pinn…
ColoCarletti Nov 16, 2026
04449f1
formal: compare interactions as the verifier emits them, scope sectio…
ColoCarletti Nov 16, 2026
10856f8
Revert the Clean bump to stay on Lean v4.33.1
nicole-graus Nov 16, 2026
5eebc56
Revert "Revert the Clean bump to stay on Lean v4.33.1"
nicole-graus Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions .github/workflows/formal.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
name: Formal model

on:
push:
branches: ["main"]
paths: ["formal/**", ".github/workflows/formal.yml"]
pull_request:
paths: ["formal/**", ".github/workflows/formal.yml"]

permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true

jobs:
lean:
name: Lean build and export check
runs-on: ubuntu-latest
timeout-minutes: 120
defaults:
run:
working-directory: formal
steps:
- name: Checkout sources
uses: actions/checkout@v4

- name: Install elan
env:
ELAN_VERSION: v4.2.4
ELAN_SHA256: 42b94d4244e8353142c456ec0e4ca6528fd898a6c604d4059f494e706e431f63
run: |
cd "$(mktemp -d)"
curl -sSfL "https://github.com/leanprover/elan/releases/download/${ELAN_VERSION}/elan-x86_64-unknown-linux-gnu.tar.gz" -o elan.tar.gz
echo "${ELAN_SHA256} elan.tar.gz" | sha256sum -c -
tar xzf elan.tar.gz
./elan-init -y --default-toolchain none
echo "$HOME/.elan/bin" >> "$GITHUB_PATH"

# Clean and CompPoly are compiled from source; Mathlib and its dependencies come from
# `lake exe cache get`. One entry per toolchain and manifest, holding the source-built
# packages and the LambdaVM build only (a directory in `path` is archived whole, so an
# exclusion under it has no effect).
- name: Cache Lake builds
uses: actions/cache@v4
with:
path: |
formal/.lake/build
formal/.lake/packages/Clean
formal/.lake/packages/CompPoly
key: lake-src-${{ hashFiles('formal/lean-toolchain', 'formal/lake-manifest.json') }}

- name: Fetch Mathlib binaries
run: lake exe cache get

- name: Build
run: lake build

- name: Export is up to date
run: |
lake env lean --run LambdaVM/Export.lean
git diff --exit-code -- export
untracked=$(git ls-files --others --exclude-standard -- export)
if [ -n "$untracked" ]; then
echo "export files not committed:"
echo "$untracked"
exit 1
fi
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 30 additions & 0 deletions crypto/stark/src/constraint_ir/interp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,36 @@ where
values[root as usize].as_base()
}

/// Evaluate every root of `prog` on one base-field main row, with the LogUp
/// challenges and alpha powers given, each root promoted to the extension. For
/// the differential tests: no aux columns, no table offset, row 0 only.
pub fn eval_program_roots<F, E>(
prog: &ConstraintProgram<F, E>,
main_row: &[FieldElement<F>],
challenges: &[FieldElement<E>],
alpha_powers: &[FieldElement<E>],
) -> Vec<FieldElement<E>>
where
F: IsSubFieldOf<E>,
E: IsField,
{
let values = run(
prog,
|main, _offset, row, col| {
assert!(main, "aux leaves are not part of a main-row program");
assert_eq!(row, 0, "a main-row program reads row 0 only");
Value::Base(main_row[col as usize].clone())
},
|idx| challenges[idx as usize].clone(),
|idx| alpha_powers[idx as usize].clone(),
|| panic!("table_offset leaves are not part of a main-row program"),
);
prog.roots
.iter()
.map(|&root| values[root as usize].to_ext())
.collect()
}

/// Full prover entry point: evaluate every constraint in `prog` against `ctx`
/// (must be [`TransitionEvaluationContext::Prover`]), writing base-field
/// ([`Dim::Base`]-rooted) constraints into `base_evals` and extension-field
Expand Down
2 changes: 1 addition & 1 deletion crypto/stark/src/constraint_ir/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -37,5 +37,5 @@ mod tests;

pub use builder::{Expr, IrBuilder};
pub use device::{DeviceNode, DeviceProgram, eval_device_program};
pub use interp::{eval_program, eval_program_base, eval_program_verifier};
pub use interp::{eval_program, eval_program_base, eval_program_roots, eval_program_verifier};
pub use ir::{ConstraintProgram, Dim, Op};
7 changes: 5 additions & 2 deletions crypto/stark/src/lookup.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1413,6 +1413,8 @@ pub enum Multiplicity {
impl Multiplicity {
/// Evaluate the multiplicity expression to a field element. `get_col(i)`
/// must return the value of main column `i` at the row being evaluated.
///
/// Public so the prover's `lean_diff` test can evaluate multiplicities on a row.
#[inline]
fn evaluate_with<F, G>(&self, get_col: G) -> FieldElement<F>
where
Expand Down Expand Up @@ -1970,7 +1972,8 @@ impl LogUpLayout {

/// Capture a [`Multiplicity`] as a base-field expression, mirroring
/// [`Multiplicity::evaluate_with`].
fn emit_multiplicity<F, E, B>(b: &B, multiplicity: &Multiplicity, offset: usize) -> B::Expr
/// An interaction's multiplicity as the expression the verifier evaluates.
pub fn emit_multiplicity<F, E, B>(b: &B, multiplicity: &Multiplicity, offset: usize) -> B::Expr
where
F: IsField,
E: IsField,
Expand Down Expand Up @@ -2159,7 +2162,7 @@ where
/// accumulator. The prover folder runs this body once per LDE row, where
/// collecting the terms in a `Vec` costs a heap allocation per fingerprint
/// per row.
fn emit_fingerprint<F, E, B>(b: &B, interaction: &BusInteraction, offset: usize) -> B::ExprE
pub fn emit_fingerprint<F, E, B>(b: &B, interaction: &BusInteraction, offset: usize) -> B::ExprE
where
F: IsField,
E: IsField,
Expand Down
1 change: 1 addition & 0 deletions formal/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.lake/
15 changes: 15 additions & 0 deletions formal/LambdaVM.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
module

public import LambdaVM.Field
public import LambdaVM.AluOp
public import LambdaVM.StaticLookup
public import LambdaVM.Templates.IsBit
public import LambdaVM.Templates.Add
public import LambdaVM.Tables.Bitwise
public import LambdaVM.Templates.IsByte
public import LambdaVM.Buses.Alu
public import LambdaVM.Tables.Lt
public import LambdaVM.Tables.Eq
public import LambdaVM.Tables.Shift
public import LambdaVM.Ensembles.EqLookup
public import LambdaVM.Channels.Counted
23 changes: 23 additions & 0 deletions formal/LambdaVM/AluOp.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
module

public import LambdaVM.Field

@[expose] public section

/-!
# `alu_op` descriptors (`prover/src/tables/types.rs`)

One enumeration serves two places: the `opsel` of the `BYTE_ALU` lookup (AND, OR, XOR) and the
low bits of the flag byte on the `ALU` bus (EQ, LT, SHIFT).
-/

namespace LambdaVM

def opselAND : ℕ := 0
def opselOR : ℕ := 1
def opselXOR : ℕ := 2
def opselEQ : ℕ := 3
def opselLT : ℕ := 4
def opselSHIFT : ℕ := 5

end LambdaVM
99 changes: 99 additions & 0 deletions formal/LambdaVM/Buses/Alu.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
module

public import LambdaVM.Field
public import LambdaVM.AluOp

@[expose] public section

/-!
# ALU bus (`BusId::Alu`)

`ALU[out; in1, in2, flags]`: operands and result travel as `(lo32, hi32)` pairs, `flags`
carries the `alu_op` descriptor plus per-chip flag bits. Every ALU chip pushes to this
channel; the CPU pulls. Each chip adds the clause of `Guarantees` for its own `opsel`.
-/

namespace LambdaVM.Alu

structure Msg (F : Type) where
in1Lo : F
in1Hi : F
in2Lo : F
in2Hi : F
flags : F
outLo : F
outHi : F
deriving ProvableStruct

/-- `lhs < rhs` on 64-bit values, signed (two's complement) or unsigned, as a bit. -/
def ltRaw (signed L R : ℕ) : ℕ :=
if signed = 1 then (if (BitVec.ofNat 64 L).slt (BitVec.ofNat 64 R) then 1 else 0)
else (if (BitVec.ofNat 64 L).ult (BitVec.ofNat 64 R) then 1 else 0)

/-- The two comparisons on values below `2⁶⁴`, read on naturals. -/
lemma ult_ofNat_iff {L R : ℕ} (hL : L < 2^64) (hR : R < 2^64) :
(BitVec.ofNat 64 L).ult (BitVec.ofNat 64 R) = true ↔ L < R := by
simp only [BitVec.ult_eq_decide, decide_eq_true_eq, BitVec.toNat_ofNat, Nat.mod_eq_of_lt hL,
Nat.mod_eq_of_lt hR]

lemma slt_ofNat_iff {L R : ℕ} (hL : L < 2^64) (hR : R < 2^64) :
(BitVec.ofNat 64 L).slt (BitVec.ofNat 64 R) = true ↔
(if L < 2^63 then (L : ℤ) else (L : ℤ) - 2^64) <
(if R < 2^63 then (R : ℤ) else (R : ℤ) - 2^64) := by
simp only [BitVec.slt_eq_decide, decide_eq_true_eq, BitVec.toInt_eq_toNat_cond, BitVec.toNat_ofNat,
Nat.mod_eq_of_lt hL, Nat.mod_eq_of_lt hR]
split_ifs <;> omega

/-- LT result: `(lhs < rhs) xor invert`. -/
def ltBit (signed invert L R : ℕ) : ℕ :=
if ltRaw signed L R = invert then 0 else 1

/-- EQ result: `(a = b) xor invert`. -/
def eqBit (invert A B : ℕ) : ℕ :=
if (if A = B then 1 else 0) = invert then 0 else 1

/-- Arithmetic right shift of a 64-bit value: sign-extend to 128 bits, shift, truncate. -/
def sra64 (x k : ℕ) : ℕ :=
if x < 2^63 then x >>> k else ((x + (2^128 - 2^64)) >>> k) % 2^64

/-- `SHIFT` result (spec/src/shift.toml): the shift amount is reduced mod 32 for word instructions
and mod 64 otherwise; `direction` picks left (0) or right (1); `signed` picks the arithmetic
right shift. Word results are not sign-extended here (the CPU does that). For `word = 1` the
shift still acts on all 64 bits of `x`, so for a right shift the caller must pass `x` with its
high word already zero-extended (logical) or sign-extended (arithmetic); otherwise bits of the
high word shift into the low 32 bits of the result. -/
def shiftResult (word signed direction x s : ℕ) : ℕ :=
let k := s % (if word = 1 then 32 else 64)
if direction = 0 then (x <<< k) % 2^64
else if signed = 0 then x >>> k
else sra64 x k

/-- What a puller learns. One clause per `opsel`, selected by the flag byte read as a natural.
Each clause takes as hypotheses exactly the `[[assumptions]]` of its chip's spec: the words the
caller must have range-checked. The words a chip range-checks itself need no hypothesis. -/
def Guarantees (m : Msg (F p)) : Prop :=
-- LT (spec/src/lt.toml): flags = opsel(LT) + 32·signed + 64·invert, out = [res, 0];
-- assumes `IS_WORD[lhs[0]]`, `IS_WORD[rhs[0]]` (LT range-checks the high halves)
(∀ s i : ℕ, s < 2 → i < 2 → m.flags.val = opselLT + 32 * s + 64 * i →
m.in1Lo.val < 2^32 → m.in2Lo.val < 2^32 →
m.outHi = 0 ∧
m.outLo = ((ltBit s i (dword m.in1Lo m.in1Hi) (dword m.in2Lo m.in2Hi) : ℕ) : F p)) ∧
-- EQ (spec/src/eq.toml): flags = opsel(EQ) + 64·invert, out = [res, 0];
-- assumes `IS_WORD[a[i]]`, `IS_WORD[b[i]]`
(∀ i : ℕ, i < 2 → m.flags.val = opselEQ + 64 * i →
m.in1Lo.val < 2^32 → m.in1Hi.val < 2^32 → m.in2Lo.val < 2^32 → m.in2Hi.val < 2^32 →
m.outHi = 0 ∧
m.outLo = ((eqBit i (dword m.in1Lo m.in1Hi) (dword m.in2Lo m.in2Hi) : ℕ) : F p)) ∧
-- SHIFT (spec/src/shift.toml): flags = opsel(SHIFT) + word_instr + 32·signed + 64·direction;
-- no assumptions (SHIFT range-checks `in` and the low bytes of the shift amount itself),
-- only the low byte of the shift amount matters
(∀ w s d : ℕ, w < 2 → s < 2 → d < 2 →
m.flags.val = opselSHIFT + w + 32 * s + 64 * d →
m.outLo.val < 2^32 ∧ m.outHi.val < 2^32 ∧
dword m.outLo m.outHi = shiftResult w s d (dword m.in1Lo m.in1Hi) (m.in2Lo.val % 256))

def channel : Channel (F p) Msg where
name := "ALU"
Guarantees m _ := Guarantees m

end LambdaVM.Alu
Loading
Loading