Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
30ef4aa
Prove table soundness from a finishing order of channels and of messa…
jotabulacios Nov 2, 2026
52672f1
Derive the staged theorems' per-channel balance through the named lem…
jotabulacios Nov 11, 2026
cd23f2d
Unfold a staged requirement over stages, the way the channel form alr…
jotabulacios Nov 12, 2026
f9476a7
Read the channel form off the stage one, instead of proving it twice.
jotabulacios Nov 17, 2026
ff2c394
Name the staged theorems after their hypotheses, and drop the unused …
jotabulacios Nov 18, 2026
67d1dc5
Motivate the finishing order from this repo, and state what OrderedCh…
jotabulacios Nov 18, 2026
547a1fb
Ask tableSoundness_of_stagedRequirementsOn only for the pulls it uses.
jotabulacios Nov 18, 2026
5e54dee
Add the two entry points a consumer of the staged API has to write an…
jotabulacios Nov 18, 2026
02901a0
Add the third soundness argument to the Air README.
jotabulacios Nov 18, 2026
b60ac8e
Say which two obligations the empty-verifier hypothesis stands for.
jotabulacios Nov 18, 2026
3c6cf33
Exercise the channel finishing order, in an example.
jotabulacios Nov 18, 2026
1b42459
Push the range chip's count as often as it is pulled, and pin the run.
jotabulacios Nov 18, 2026
fc0bd1d
Exercise the stage order, in an example where one table pulls and pus…
jotabulacios Nov 18, 2026
0758d16
Name the consumer this was written for.
jotabulacios Nov 19, 2026
e5e5728
Take the review fixes from the parallel round.
jotabulacios Nov 19, 2026
f42d709
Point the staged docstrings at declarations, and the README at its ex…
jotabulacios Nov 19, 2026
b749711
Check that the ordered hierarchy cannot take this consumer.
jotabulacios Nov 19, 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
3 changes: 3 additions & 0 deletions Clean.lean
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ public import Clean.Examples.FemtoCairo.FlatAir
public import Clean.Air.WitnessGeneration
public import Clean.Air.Lookup
public import Clean.Air.CountedChannel
public import Clean.Air.StagedChannels
public import Clean.Backends.Plonky3.Print
public import Clean.Tables.Fibonacci8
public import Clean.Tables.Fibonacci32
Expand All @@ -48,6 +49,8 @@ public import Clean.Gadgets.BLAKE3.Round
public import Clean.Gadgets.BLAKE3.FinalizeChunk
public import Clean.Examples.FibonacciVm.Ensemble
public import Clean.Examples.CountedSquares.Ensemble
public import Clean.Examples.StagedSquares.Ensemble
public import Clean.Examples.SameBus.Ensemble
public import Clean.Examples.OpcodeVm.Ensemble
public import Clean.Examples.BinaryFibonacci.Ensemble
public import Clean.Gadgets.SHA256.SHA256Compress
Expand Down
46 changes: 44 additions & 2 deletions Clean/Air/Balance.lean
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,9 @@ This is how a circuit discharges the requirement of a counted pull. The pull owe
`mult ≠ 0` and `mult.val ≤ N`. Stating it over `ZMod p` rather than a general field is what makes
`mult.val` available.

No example in this repo range-checks a multiplicity, because the bound there is `2` and a
constraint is cheaper. The chips that do are in lambda_vm, where the bound is a byte. -/
`Clean/Examples/StagedSquares` range-checks a multiplicity by pulling a channel that guarantees
`CountUpTo`. No example range-checks one by its `.val` against a table, because the bound there is
`2` and a constraint is cheaper; the chips that do are in lambda_vm, where the bound is a byte. -/
lemma countUpTo_of_ne_zero_of_val_le {p : ℕ} [Fact p.Prime] {N : ℕ} {mult : ZMod p} (h0 : mult ≠ 0)
(hN : mult.val ≤ N) : CountUpTo N mult :=
⟨ mult.val, Nat.one_le_iff_ne_zero.mpr ((ZMod.val_ne_zero mult).mpr h0), hN,
Expand Down Expand Up @@ -195,6 +196,47 @@ lemma balancedUpTo_one_iff {interactions : List (Interaction F)} :
⟨ fun balanced => balanced.toBalancedInteractions,
fun balanced => ⟨ balanced, balanced.matchedUpTo_one ⟩ ⟩

/-- Filtering by a class of messages keeps the active count of a message in the class and zeroes
it outside. -/
lemma activeCount_filter_msg (interactions : List (Interaction F)) (cls : Array F → Bool)
(direction : Channel.Direction) (msg : Array F) :
activeCount (interactions.filter fun i => cls i.msg) direction msg =
if cls msg then activeCount interactions direction msg else 0 := by
simp only [activeCount, List.countP_filter]
split_ifs with h_cls
· apply List.countP_congr
intro i _
simp only [Bool.and_eq_true, decide_eq_true_eq]
constructor
· exact fun h => h.1
· exact fun h => ⟨ h, h.2.1 ▸ h_cls ⟩
· rw [List.countP_eq_zero]
intro i _
simp only [Bool.and_eq_true, decide_eq_true_eq, not_and]
rintro ⟨ -, rfl, - ⟩ h
exact h_cls h

/-- Restricting a balanced list to a class of messages keeps it balanced: every interaction
carrying a message is kept or dropped together. -/
lemma BalancedUpTo.filter_msg {N : ℕ} {interactions : List (Interaction F)}
(cls : Array F → Bool) (balanced : BalancedUpTo N interactions) :
BalancedUpTo N (interactions.filter fun i => cls i.msg) := by
refine ⟨ ⟨ ?_, ?_ ⟩, ?_ ⟩
· intro a a_mem a_pull
obtain ⟨ a_mem, a_cls ⟩ := List.mem_filter.mp a_mem
obtain ⟨ b, b_mem, b_msg, b_push ⟩ := balanced.exists_push_of_pull a a_mem a_pull
exact ⟨ b, List.mem_filter.mpr ⟨ b_mem, b_msg ▸ a_cls ⟩, b_msg, b_push ⟩
· intro msg is_bool
rw [activeCount_filter_msg, activeCount_filter_msg]
split_ifs with h_cls
· exact balanced.activeCount_push_eq_activeCount_pull_of_isBool msg fun i i_mem i_msg =>
is_bool i (List.mem_filter.mpr ⟨ i_mem, i_msg ▸ h_cls ⟩) i_msg
· rfl
· intro a a_mem a_pull
obtain ⟨ a_mem, a_cls ⟩ := List.mem_filter.mp a_mem
obtain ⟨ b, b_mem, b_msg, b_push ⟩ := balanced.matchedUpTo a a_mem a_pull
exact ⟨ b, List.mem_filter.mpr ⟨ b_mem, b_msg ▸ a_cls ⟩, b_msg, b_push ⟩

/--
A balance check: the condition that a verifier checks on the interactions with each channel, the
numbers of interactions with a channel that the check is sound for, and its proof that the condition
Expand Down
6 changes: 4 additions & 2 deletions Clean/Air/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,14 @@ It also proves the basic row-level transport lemmas: instantiated component oper

**Ensemble-level soundness** is more than a simple lifting of per-circuit soundness: it requires that channel guarantees, which were _assumed_ as part of local circuit proofs, are shown to hold unconditionally from global channel balance and constraints.

The library currently provides two distinct arguments to establish soundness, covering two prominent ways of using channels:
The library currently provides three distinct arguments to establish soundness, covering prominent ways of using channels:

`OrderedChannel.lean` contains a staged channel construction for ordinary lookup-like channels. The defining property is a strict hierarchy on the list of component tables: any table that pushes to a channel must come before every table that pulls from it. From little more than this property, we prove ensemble-level soundness, as encapsulated in the `SoundEnsemble` structure. On the way, we introduce a relaxed notion of channel balance called `PartialBalancedChannel` that allows the balanced interaction list to contain additional interactions from tables added later. This makes it suitable for an inductive argument or gradual addition of tables to an existing sound ensemble.
`OrderedChannel.lean` contains a construction for ordinary lookup-like channels. The defining property is a strict hierarchy on the list of component tables: any table that pushes to a channel must come before every table that pulls from it. From little more than this property, we prove ensemble-level soundness, as encapsulated in the `SoundEnsemble` structure. On the way, we introduce a relaxed notion of channel balance called `PartialBalancedChannel` that allows the balanced interaction list to contain additional interactions from tables added later. This makes it suitable for an inductive argument or gradual addition of tables to an existing sound ensemble.

`Vm.lean` contains a construction aimed at "VM-like" components that perform one transition per row. Since VM components both pull from and push to one distinguished state channel, they cannot follow the theory of ordered lookup-channel soundness. Instead, we prove a dedicated soundness theorem that applies to a set of VM components added to an existing hierarchical ensemble; a typical modern zkVMs layout. `Clean/Examples/BinaryFibonacci` is a VM over the binary field GF(2^64), sound under multiset balance.

`StagedChannels.lean` orders the channels instead of the tables. A table's requirements on a channel may follow from its guarantees on channels finished earlier, which the hierarchy of `OrderedChannel.lean` cannot express: a counted pull whose multiplicity is range-checked on a second channel is the case. `finished` lists the channels newest first, `Component.StagedRequirements` says that each component's requirements on one of them follow from its guarantees on those finished before it, and `Ensemble.tableSoundness_of_stagedRequirements` proves soundness by induction from the oldest. A `Stage` refines this to a channel together with a class of its messages, so a bus shared by several operations can be finished in several steps and a table that pulls some of its messages and pushes others is not a cycle; balance is message by message (`BalancedUpTo.filter_msg`), so each stage balances by itself. `Clean/Examples/StagedSquares` is the first case and `Clean/Examples/SameBus` the second. Two limits distinguish it from `OrderedChannel.lean`: the argument is made for a whole ensemble at once rather than built up table by table as `SoundEnsemble` does, and it applies only to ensembles whose verifier is empty. That hypothesis stands for two obligations at once: that every interaction on a stage comes from a table, so that the requirements the induction establishes cover the whole list consistency is applied to, and that the verifier's own spec follows from its guarantees. `OrderedChannel.lean` discharges the first through `PartialBalancedChannel`, which tolerates interactions from outside the list it is stated for, and the second through `verifierChannelGuarantees_of_tableRequirements`. The staged argument has neither, so lifting the hypothesis means saying what a verifier owes on a stage and adding it to the induction.

`WitnessGeneration.lean` constructs ensemble witnesses from the public input and the prover's private input, see the next section.

## Witness generation
Expand Down
Loading
Loading