Skip to content
Merged
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
7d27e9d
Say what each counted definition claims, and what it does not.
jotabulacios Nov 16, 2026
809ad79
Let Balance.logUp use the default proof of matchedUpTo_of_balanced.
jotabulacios Nov 16, 2026
0553863
Narrow two counted docstrings to what they actually cover.
jotabulacios Nov 17, 2026
ad6d07d
Pad the counted consumer, and exercise the padding row.
jotabulacios Nov 17, 2026
4b776ad
Move CountedSquares into a directory, as the other examples with a te…
MauroToscano Nov 19, 2026
6f16311
Name the counted lemmas after what they assume, and drop a `_root_`.
MauroToscano Nov 19, 2026
d437fdf
Keep the `pullBound` lemmas out of the default simp set.
MauroToscano Nov 19, 2026
35e6441
Correct counted docstrings that claim more, or other, than the code d…
MauroToscano Nov 19, 2026
4b48bec
Describe the pull bound and the counted channel in the Air README.
MauroToscano Nov 19, 2026
079629e
Merge the updated counted pulls, with their review fixes, into the st…
MauroToscano Nov 19, 2026
258f3bd
Name the staged theorems after their hypotheses, and state their bala…
MauroToscano Nov 19, 2026
a83c993
Add an example that only a finishing order of channels proves sound.
MauroToscano Nov 19, 2026
5603dac
Say what the staged theorems cover, and what OrderedChannel rules out.
MauroToscano Nov 19, 2026
98213d2
Tighten the counted docstrings, and fix the ones that had gone stale.
MauroToscano Nov 19, 2026
876faad
Tighten the staged docstrings, and fix the ones that had gone stale.
MauroToscano Nov 19, 2026
447e9ab
Merge the counted docstring pass into the staged channels.
MauroToscano Nov 19, 2026
7fc3940
Point the CountedSquares module doc at the range-checked example it d…
MauroToscano 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: 2 additions & 1 deletion Clean.lean
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,8 @@ public import Clean.Gadgets.BLAKE3.FinalStateUpdate
public import Clean.Gadgets.BLAKE3.Round
public import Clean.Gadgets.BLAKE3.FinalizeChunk
public import Clean.Examples.FibonacciVm.Ensemble
public import Clean.Examples.CountedSquares
public import Clean.Examples.CountedSquares.Ensemble
public import Clean.Examples.RangeCheckedCount
public import Clean.Examples.OpcodeVm.Ensemble
public import Clean.Examples.BinaryFibonacci.Ensemble
public import Clean.Gadgets.SHA256.SHA256Compress
Expand Down
127 changes: 58 additions & 69 deletions Clean/Air/Balance.lean

Large diffs are not rendered by default.

82 changes: 41 additions & 41 deletions Clean/Air/CountedChannel.lean
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,34 @@ public import Clean.Circuit.Explicit
/-!
# Channels with counted pulls

A table that answers `k` identical lookups with one row pulls the facts it relies on with the same
multiplicity `k`. `Channel.counted N channel` is `channel` with pulls of multiplicity up to `N`: such
a pull gets the guarantee, and an active push owes it. It is consistent in the sense of
`RawChannel.ConsistentUpTo N`, so it can be finished in a `SoundEnsemble` whose balance check has a
`pullBound` of at least `N`, e.g. `Balance.logUpUpTo N`.
A table that answers `k` identical lookups with one row pulls the fact it relies on once, with
multiplicity `k`. `Channel.counted N channel` is `channel` with pulls of multiplicity up to `N`:
such a pull gets the guarantee, and an active push owes it. It is `RawChannel.ConsistentUpTo N`,
so it can be finished in a `SoundEnsemble` whose balance check has a `pullBound` of at least `N`,
such as `Balance.logUpUpTo N`: at exactly `N` by instance, above it through
`counted_consistentUpTo_of_le`.
-/

variable {F : Type} [FiniteField F]
variable {Message : TypeMap} [ProvableType Message]

omit [FiniteField F] in
/-- Channels with different names are different. Lets `circuit_norm` tell a counted channel apart
from the other channels of a circuit without unfolding them. -/
@[circuit_norm] lemma RawChannel.eq_false_of_name_ne {a b : RawChannel F}
(h : a.name ≠ b.name) : (a = b) = False :=
eq_false fun h_eq => h (congrArg RawChannel.name h_eq)

namespace Channel

/-- `channel`, with pulls of multiplicity up to `N`. -/
/-- `channel`, with pulls of multiplicity up to `N`.

It keeps `channel.name`, so `channel.toRaw` and `channel.counted N` for each `N` may be different
`RawChannel`s under one name. An ensemble uses only one of them, since its channel names are unique
(`unique_channel_names`, and `fresh` in `SoundEnsemble.addChannel`). The name is kept for witness
generation, which tallies interactions by name, and whose `DemandMode` and `PreallocatedMode` take
the typed `Channel`: under a new name, no component would answer the counted interactions, and
generation would fail with `unhandledImbalance`. -/
def counted (N : ℕ) (channel : Channel F Message) : RawChannel F where
name := channel.name
arity := size Message
Expand All @@ -31,29 +46,20 @@ def counted (N : ℕ) (channel : Channel F Message) : RawChannel F where
| .push => mult ≠ 0 → channel.Guarantees (fromElements message) data
| .pull => mult = 0 ∨ CountUpTo N mult

omit [FiniteField F] in
/-- Channels with different names are different. Lets `circuit_norm` tell a counted channel apart
from the other channels of a circuit without unfolding them. -/
@[circuit_norm] lemma _root_.RawChannel.eq_false_of_name_ne {a b : RawChannel F}
(h : a.name ≠ b.name) : (a = b) = False :=
eq_false fun h_eq => h (congrArg RawChannel.name h_eq)

@[circuit_norm] lemma counted_name (N : ℕ) (channel : Channel F Message) :
(channel.counted N).name = channel.name := rfl
@[circuit_norm] lemma counted_arity (N : ℕ) (channel : Channel F Message) :
(channel.counted N).arity = size Message := rfl

/-- `counted 1` gives what the plain typed channel gives: only a pull of multiplicity `1` gets the
guarantee. -/
/-- `counted 1` guarantees what `channel.toRaw` does: only at multiplicity `1`. -/
lemma counted_one_guarantees_iff (channel : Channel F Message) (mult : F)
(message : Vector F (size Message)) (data : ProverData F) :
(channel.counted 1).Guarantees mult message data ↔
channel.toRaw.Guarantees mult message data := by
simp [counted, toRaw, countUpTo_one_iff]

/-- `counted 1` owes what the plain typed channel owes: an active push owes the guarantee, and a
pull has multiplicity `0` or `1`. Together with `counted_one_guarantees_iff`, counting up to `1` is the
channel Clean already had. -/
/-- `counted 1` requires what `channel.toRaw` does: an active push owes the guarantee, and a pull
has multiplicity `0` or `1`. -/
lemma counted_one_requirements_iff (channel : Channel F Message) (direction : Direction) (mult : F)
(message : Vector F (size Message)) (data : ProverData F) :
(channel.counted 1).Requirements direction mult message data ↔
Expand All @@ -70,7 +76,8 @@ def emittedUpTo (N : ℕ) (channel : Channel F Message) (mult : Expression F)
(msg : Message (Expression F)) : AbstractInteraction F :=
⟨ channel.counted N, .push, mult, toElements msg ⟩

/-- Pull `msg` `count` times, for `count` up to `N`. -/
/-- Pull `msg` `count` times from `channel.counted N`, which requires `count` to be `0` or to count
up to `N`. -/
@[circuit_norm]
def pullUpTo (N : ℕ) (channel : Channel F Message) (count : Expression F)
(msg : Message (Expression F)) : Circuit F Unit := fun _ =>
Expand Down Expand Up @@ -142,7 +149,7 @@ variable {N : ℕ} {channel : Channel F Message} {mult : Expression F}
end

/-- A pull of multiplicity up to `N` is matched by a push, whose requirement gives the
guarantee. Every other interaction gets no guarantee. -/
guarantee. Every other interaction's guarantee is vacuous. -/
instance (N : ℕ) (channel : Channel F Message) : (channel.counted N).ConsistentUpTo N where
consistent interactions data balanced reqs a a_mem := by
obtain ⟨ a_channel, - ⟩ := reqs a a_mem
Expand All @@ -166,38 +173,31 @@ instance (N : ℕ) (channel : Channel F Message) : (channel.counted N).Consisten
| push => exact b_reqs b_ne_zero
| pull => exact absurd (b_reqs.resolve_left b_ne_zero) (b_not_pull rfl)

/-- Synthesis finds the instance for the `pullBound` of a concrete balance check on its own. That is
what `SoundEnsemble.markFinished` needs, since it takes the instance as an instance argument, where
no `simp` step can run first. -/
/-- Instance search sees `(Balance.logUpUpTo N).pullBound` as `N`, which
`SoundEnsemble.markFinished` relies on. -/
example [ComputableRingChar F] (N : ℕ) (channel : Channel F Message) :
(channel.counted N).ConsistentUpTo (Balance.logUpUpTo (F := F) N).pullBound :=
inferInstance

/-- The counted channel is also consistent for balance checks with a larger bound. -/
/-- `channel.counted N` is also `ConsistentUpTo M` for `N ≤ M`.

Not an instance, since synthesis would have to prove `N ≤ M`. To finish `channel.counted N` under a
check whose `pullBound` is a larger `M`, provide this with `haveI` before
`SoundEnsemble.markFinished`, or pass it explicitly with `@`. -/
theorem counted_consistentUpTo_of_le {M N : ℕ} (h : N ≤ M) (channel : Channel F Message) :
(channel.counted N).ConsistentUpTo M where
consistent interactions data balanced :=
RawChannel.ConsistentUpTo.consistent (N := N) interactions data
⟨ balanced.toBalancedInteractions, balanced.matchedUpTo.mono h ⟩

/--
Why `ConsistentUpTo` is needed: for `2 ≤ N` the counted channel is **not**
`RawChannel.Consistent`, so it could not be finished in a `SoundEnsemble` under Clean's unmodified
balance premise `BalancedInteractions`.

The counterexample is two pulls of a message the channel does not guarantee, one of multiplicity
`N` and one of multiplicity `1`, with nothing pushed. `BalancedInteractions` is satisfied:
`exists_push_of_pull` only has to match pulls of multiplicity `1`, and it counts the pull of `N` as
an `Interaction.Push` of the message, so the pull of `1` is matched; the count condition is vacuous
because `N` is neither `0` nor `1`. The counted channel, in contrast, reads both as pulls and hands
the guarantee to the pull of `1`, which is false.

This is exactly the gap that `MatchedUpTo N` / `BalancedUpTo N` and `Balance.pullBound` close, and
the reason `Channel.counted` carries a `RawChannel.ConsistentUpTo N` instance instead of a
`RawChannel.Consistent` one.

The hypothesis `N < ringChar F` is what makes `N` distinct from both `0` and `1` in `F`; together
with `2 ≤ N` it is all the counterexample needs.
For `2 ≤ N < ringChar F`, and a message `m` that `channel` does not guarantee, `channel.counted N`
is not `RawChannel.Consistent`: it needs the premise `BalancedUpTo N` of `ConsistentUpTo N`.

Two pulls of `m`, of multiplicities `N` and `1`, satisfy `BalancedInteractions`. Since `N` is
neither `0` nor `1` in `F`, `exists_push_of_pull` takes the pull of `N` as an `Interaction.Push`
matching the pull of `1`, and the count condition does not apply to `m`. The counted channel reads
both as pulls, so consistency would give the pull of `1` the guarantee of `m`.
-/
theorem counted_not_consistent {N : ℕ} (hN : 2 ≤ N) (h_char : N < ringChar F)
(channel : Channel F Message) (m : Message F) (data : ProverData F)
Expand Down
6 changes: 3 additions & 3 deletions Clean/Air/OrderedChannel.lean
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ def PartialBalancedChannel (N : ℕ) (tables : Tables F) (channel : RawChannel F
(channel ∉ tables.tables.flatMap (·.channelsWithGuarantees) ∨ ∀ i ∈ extraInteractions, i.Requirements tables.data)

/-- Partial balance is trivially weaker than balance -/
lemma partialBalancedChannel_of_balancedInteractions {tables : Tables F} {channel : RawChannel F} :
lemma partialBalancedChannel_of_balancedUpTo {tables : Tables F} {channel : RawChannel F} :
BalancedUpTo N (tables.interactionsWith channel) → PartialBalancedChannel N tables channel := by
intro balanced
use []
Expand Down Expand Up @@ -569,7 +569,7 @@ def SoundChannels (ens : Ensemble F PublicIO) (N : ℕ) (finished : List (RawCha
lemma partialBalancedChannel_of_balancedChannel {ens : Ensemble F PublicIO}
{witness : EnsembleWitness ens} {channel : RawChannel F} :
ens.OrderedChannel channel →
BalancedUpTo N (witness.interactionsWith channel) →
witness.BalancedChannel N channel →
PartialBalancedChannel N witness.toTables channel := by
intro ordered balanced
use witness.verifierInteractionsWith channel
Expand All @@ -593,7 +593,7 @@ lemma partialBalancedChannel_of_balancedChannel {ens : Ensemble F PublicIO}
lemma verifierChannelGuarantees_of_tableRequirements {ens : Ensemble F PublicIO}
{witness : EnsembleWitness ens} {channel : RawChannel F} [channel.ConsistentUpTo N] :
OrderedChannelRefl channel ens.verifier →
BalancedUpTo N (witness.interactionsWith channel) →
witness.BalancedChannel N channel →
(∀ table ∈ witness.tables, table.ChannelRequirements channel) →
ens.VerifierChannelGuarantees witness.data channel := by
intro ordered balanced table_requirements
Expand Down
8 changes: 6 additions & 2 deletions Clean/Air/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,22 +21,26 @@ In this terminology, a `Flat.Component` is a one-row AIR component: it packages

It also proves the basic row-level transport lemmas: instantiated component operations agree with row operations, component soundness lifts to table soundness, and table interactions can be collected per channel.

`Balance.lean` contains the channel multiset theory. An interaction pushes a message to a channel or pulls it, a number of times given by its multiplicity. What balance means depends on the proof system: a `Balance` is the check a verifier performs on the interactions with each channel, like LogUp's field sums in prime fields or multiset equality with `0`/`1` multiplicities in binary fields, together with the numbers of interactions it is sound for (fewer than the characteristic for LogUp) and its proof of `BalancedInteractions` for those, the facts that soundness proofs use: every pull is matched by an interaction that provides its message, and messages with `0`/`1` multiplicities are pushed as often as they are pulled. The file proves permutation and counting lemmas, and provides the channel-level implication principles used by higher-level soundness proofs. It also defines `RawChannel.Consistent` and `RawChannel.Normal`; typed channels are normal by construction, and normal channels are consistent, so both properties are satisfied in practice. A highlight in `Balance.lean` is the "guarantees-to-requirements-reversal" theorem which provides the basis for soundness of VM channels.
`Balance.lean` contains the channel multiset theory. An interaction pushes a message to a channel or pulls it, a number of times given by its multiplicity. What balance means depends on the proof system: a `Balance` is the check a verifier performs on the interactions with each channel, like LogUp's field sums in prime fields or multiset equality with `0`/`1` multiplicities in binary fields, together with the numbers of interactions it is sound for (fewer than the characteristic for LogUp) and its proof of `BalancedInteractions` for those, the facts that soundness proofs use: every pull of multiplicity `1` is matched by an interaction that provides its message, and messages with `0`/`1` multiplicities are pushed as often as they are pulled. The file proves permutation and counting lemmas, and provides the channel-level implication principles used by higher-level soundness proofs. It also defines `RawChannel.Consistent` and `RawChannel.Normal`; typed channels are normal by construction, and normal channels are consistent, so both properties are satisfied in practice. A highlight in `Balance.lean` is the "guarantees-to-requirements-reversal" theorem which provides the basis for soundness of VM channels. A `Balance` also has a `pullBound`, `1` by default, up to which it matches pull multiplicities with a push: `Balance.logUpUpTo N` raises it to `N` by also asking `count * N < ringChar F` of every channel, and `RawChannel.ConsistentUpTo N` is consistency under the resulting premise `BalancedUpTo N`.

`Verifier.lean` defines the verifier program language: an append-only list of public interactions, together with the verifier's spec and its soundness.

`RowProgram.lean` decides which witness IR a row program may use: the fixed cells of a preallocated component are computed from the row index alone, and its witness cells can also read the hint.

`Lookup.lean` defines a convenience wrapper for static lookups.

`CountedChannel.lean` defines `Channel.counted N channel`, the raw channel of a typed `channel` with pulls of multiplicity up to `N`, so that a row needing a fact `k` times pulls it once with multiplicity `k`. It is `ConsistentUpTo N`, so it can be finished under `Balance.logUpUpTo N`; `Clean/Examples/CountedSquares` uses it.

`FlatEnsemble.lean` defines flat AIR ensembles, `Flat.Ensemble` and their witnesses, `Flat.EnsembleWitness`. An ensemble is everything a prover and a verifier implementation need: components, channels, a verifier program, and the type of the prover's private input. The verifier only contributes public interactions directly. The ensemble lists every channel its components and verifier interact with, under unique names, so a proof system can balance channels by name (`EnsembleWitness.interactionsWith_eq_filter_name`). Its `Statement` is the raw proof-system relation for a balance check: there exists a witness whose table constraints hold and whose interactions with every channel pass the check. Every table of a witness carries the prover data derived from all the witness tables and the public input, so channel guarantees and specs can refer to both. The statement also fixes the table heights. Each row of a component interacts with a channel equally often, so the heights determine the number of interactions with every channel (`Ensemble.interactionCount`, which counts by channel name), and the statement requires the balance check to be sound for those numbers, a computable condition that the verifier checks from the heights (`Ensemble.interactionsFit`). The ensemble file also defines soundness and completeness and the `FormalEnsemble` structure which bundles an ensemble with its `Spec`, `Assumptions`, the `ProverAssumptions` of witness generation, and the soundness proof under a balance check (completeness is TODO), like `FormalCircuit` does for a circuit.

**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.

`StagedChannels.lean` orders channels, or classes of their messages, instead of tables: a table's requirements on a channel may follow from its guarantees on the channels finished before it, so a table may pull from a channel it also owes requirements on. It covers ensembles of tables with an empty verifier; `Clean/Examples/RangeCheckedCount.lean` is an example that `OrderedChannel.lean` cannot order.

`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.

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