Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
dc88e42
Allow pulls of multiplicity up to N when the balance check bounds the…
jotabulacios Nov 2, 2026
edd26ee
Add Channel.counted N, a typed channel whose pulls may count up to N.
jotabulacios Nov 2, 2026
b71d183
Show that a counted channel with 2 <= N is not Consistent under plain…
jotabulacios Nov 5, 2026
a58b594
Expose the pullBound of each balance check to simp.
jotabulacios Nov 5, 2026
fd16747
Give matchedUpTo_of_balanced a default, so a plain balance check comp…
jotabulacios Nov 5, 2026
4479c99
Put the pull bound after the subject in the top-level SoundChannels.
jotabulacios Nov 5, 2026
84ca439
Follow upstream's vector eval normal form in the counted channel's tw…
jotabulacios Nov 11, 2026
1bfba6d
Give balancedChannels_of_balanced the balance check's pull bound, so …
jotabulacios Nov 11, 2026
d1f0b7a
State the count of a pull once, drop the unrelated multiset refactor,…
jotabulacios Nov 11, 2026
36cbaf3
Say that counting up to one is the channel Clean already had, and pro…
jotabulacios Nov 11, 2026
6930551
Let synthesis project the pull bound, so a counted channel can be fin…
jotabulacios Nov 12, 2026
7ff8fa7
Name the balance lemma after the predicate it assumes.
jotabulacios Nov 12, 2026
f1f542d
Put countUpTo_of_val next to the definition it is about.
jotabulacios Nov 12, 2026
e496485
Exercise the counted channel end to end, in an example.
jotabulacios Nov 12, 2026
2ee0027
Relate the counted definitions to the ones they generalize.
jotabulacios Nov 13, 2026
9d88d77
Seed the counted squares example, so that it generates.
jotabulacios Nov 13, 2026
42c0991
Say what CountUpTo claims about the field, which is nothing.
jotabulacios Nov 13, 2026
7ea1149
Say what each counted definition claims, and what it does not.
jotabulacios Nov 16, 2026
1d7cd58
Let Balance.logUp use the default proof of matchedUpTo_of_balanced.
jotabulacios Nov 16, 2026
603c470
Narrow two counted docstrings to what they actually cover.
jotabulacios Nov 17, 2026
ef49d0d
Pad the counted consumer, and exercise the padding row.
jotabulacios Nov 17, 2026
3c6d5b3
Follow two of the repo's stated conventions in the new code.
jotabulacios Nov 18, 2026
04c26b0
Keep using BalancedChannel where this branch had spelled it out.
jotabulacios Nov 18, 2026
7dba7f8
Describe the pull bound and the counted channel in the Air README.
jotabulacios Nov 18, 2026
e0483dd
Give the counted squares example a directory, and fix three things in…
jotabulacios Nov 18, 2026
3e2cb49
Say why the padding scenarios run on empty prover data.
jotabulacios Nov 18, 2026
6b7eafd
Name the consumer this was written for.
jotabulacios Nov 19, 2026
3b5b146
Take the review fixes from the parallel round, and correct three of m…
jotabulacios Nov 19, 2026
bebc0cd
Name the declarations the docstrings describe, and restore the genera…
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
2 changes: 2 additions & 0 deletions Clean.lean
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ public import Clean.Examples.FemtoCairo.FemtoCairo
public import Clean.Examples.FemtoCairo.FlatAir
public import Clean.Air.WitnessGeneration
public import Clean.Air.Lookup
public import Clean.Air.CountedChannel
public import Clean.Backends.Plonky3.Print
public import Clean.Tables.Fibonacci8
public import Clean.Tables.Fibonacci32
Expand All @@ -46,6 +47,7 @@ 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.Ensemble
public import Clean.Examples.OpcodeVm.Ensemble
public import Clean.Examples.BinaryFibonacci.Ensemble
public import Clean.Gadgets.SHA256.SHA256Compress
Expand Down
322 changes: 322 additions & 0 deletions Clean/Air/Balance.lean

Large diffs are not rendered by default.

267 changes: 267 additions & 0 deletions Clean/Air/CountedChannel.lean
Original file line number Diff line number Diff line change
@@ -0,0 +1,267 @@
module

public import Clean.Air.Balance
public import Clean.Circuit.Explicit

@[expose] public section

/-!
# 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`, such as `Balance.logUpUpTo N`: at exactly `N` by instance, above it
through `counted_consistentUpTo_of_le`.

This was written for lambda_vm, a RISC-V zkVM built on Clean, whose arithmetic chips answer several
identical lookups per row. `Clean/Examples/CountedSquares` is the same shape in miniature.
-/

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

The name is kept, so `channel.toRaw`, `channel.counted 2` and `channel.counted 3` may denote
different `RawChannel`s under one name. That is deliberate: witness generation tallies
interactions by channel name, and `DemandMode` and `PreallocatedMode` take the plain `Channel`, so
a counted channel under a new name would silently stop generating rows. An `Ensemble` asks the
names of its channels to be distinct, so use one raw-channel value per name: a second entry under
a name already taken fails `unique_channel_names`. -/
def counted (N : ℕ) (channel : Channel F Message) : RawChannel F where
name := channel.name
arity := size Message
Guarantees mult message data :=
CountUpTo N mult → channel.Guarantees (fromElements message) data
Requirements direction mult message data :=
match direction with
| .push => mult ≠ 0 → channel.Guarantees (fromElements message) data
| .pull => mult = 0 ∨ CountUpTo N mult

@[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. -/
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. -/
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 ↔
channel.toRaw.Requirements direction mult message data := by
cases direction <;> simp [counted, toRaw, countUpTo_one_iff]

/-- The interaction of pulling `msg` `count` times from `channel.counted N`. -/
def pulledUpTo (N : ℕ) (channel : Channel F Message) (count : Expression F)
(msg : Message (Expression F)) : AbstractInteraction F :=
⟨ channel.counted N, .pull, count, toElements msg ⟩

/-- The interaction of pushing `msg` `mult` times to `channel.counted N`. -/
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 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 _ =>
((), [.interact (pulledUpTo N channel count msg)])

/-- Push `msg` `mult` times to `channel.counted N`. -/
@[circuit_norm]
def emitUpTo (N : ℕ) (channel : Channel F Message) (mult : Expression F)
(msg : Message (Expression F)) : Circuit F Unit := fun _ =>
((), [.interact (emittedUpTo N channel mult msg)])

instance {N : ℕ} {channel : Channel F Message} {count : Expression F} :
ExplicitCircuits (F:=F) (channel.pullUpTo N count) where
output _ _ := ()
localLength _ _ := 0
operations msg _ := [.interact (pulledUpTo N channel count msg)]
channelsWithGuarantees _ _ := [channel.counted N]

instance {N : ℕ} {channel : Channel F Message} {mult : Expression F} :
ExplicitCircuits (F:=F) (channel.emitUpTo N mult) where
output _ _ := ()
localLength _ _ := 0
operations msg _ := [.interact (emittedUpTo N channel mult msg)]
channelsWithGuarantees _ _ := []

attribute [explicit_circuit_no_unfold] pullUpTo emitUpTo

section
variable {N : ℕ} {channel : Channel F Message} {mult : Expression F}
{msg : Message (Expression F)} {env : Environment F}

@[circuit_norm] lemma pulledUpTo_channel :
(pulledUpTo N channel mult msg).channel = channel.counted N := rfl
@[circuit_norm] lemma pulledUpTo_direction :
(pulledUpTo N channel mult msg).direction = .pull := rfl
@[circuit_norm] lemma pulledUpTo_mult :
(pulledUpTo N channel mult msg).mult = mult := rfl
@[circuit_norm] lemma pulledUpTo_msg :
(pulledUpTo N channel mult msg).msg = toElements msg := rfl
@[circuit_norm] lemma emittedUpTo_channel :
(emittedUpTo N channel mult msg).channel = channel.counted N := rfl
@[circuit_norm] lemma emittedUpTo_direction :
(emittedUpTo N channel mult msg).direction = .push := rfl
@[circuit_norm] lemma emittedUpTo_mult :
(emittedUpTo N channel mult msg).mult = mult := rfl
@[circuit_norm] lemma emittedUpTo_msg :
(emittedUpTo N channel mult msg).msg = toElements msg := rfl

@[circuit_norm] lemma pulledUpTo_guarantees :
(pulledUpTo N channel mult msg).Guarantees env ↔
(CountUpTo N (Expression.eval env mult) → channel.Guarantees (eval env msg) env.data) := by
simp [pulledUpTo, AbstractInteraction.Guarantees, counted,
ProvableType.fromElements_toElements]

@[circuit_norm] lemma pulledUpTo_requirements :
(pulledUpTo N channel mult msg).Requirements env ↔
(Expression.eval env mult = 0 ∨ CountUpTo N (Expression.eval env mult)) := by
simp [pulledUpTo, AbstractInteraction.Requirements, counted]

@[circuit_norm] lemma emittedUpTo_guarantees :
(emittedUpTo N channel mult msg).Guarantees env := by
simp [emittedUpTo, AbstractInteraction.Guarantees]

@[circuit_norm] lemma emittedUpTo_requirements :
(emittedUpTo N channel mult msg).Requirements env ↔
(Expression.eval env mult ≠ 0 → channel.Guarantees (eval env msg) env.data) := by
simp [emittedUpTo, AbstractInteraction.Requirements, counted,
ProvableType.fromElements_toElements]
end

/-- A pull of multiplicity up to `N` is matched by a push, whose requirement gives the
guarantee. Every other interaction gets no guarantee. -/
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
by_cases a_pull : a.PullUpTo N
case neg =>
rcases a with ⟨ _, a_direction, a_mult, a_msg, a_size ⟩
subst a_channel
simp only [Interaction.Guarantees, counted]
exact fun h_direction h_count => absurd ⟨ h_direction, h_count ⟩ a_pull
obtain ⟨ b, b_mem, b_msg, b_ne_zero, b_not_pull ⟩ := balanced.matchedUpTo a a_mem a_pull
obtain ⟨ b_channel, b_reqs ⟩ := reqs b b_mem
rcases a with ⟨ _, a_direction, a_mult, a_msg, a_size ⟩
rcases b with ⟨ _, b_direction, b_mult, b_msg', b_size ⟩
subst a_channel b_channel
simp only at b_msg
subst b_msg
simp only [Interaction.Guarantees, Interaction.Requirements, Interaction.msgVector,
counted] at b_reqs ⊢
intro _ _
cases b_direction with
| 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. -/
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.

A theorem and not an instance. The instance above fixes the channel's own `N` on both sides, so
synthesis closes `ConsistentUpTo N` for a channel counted at `N` and nothing else. An ensemble
that finishes a channel counted at `N` under a check whose `pullBound` is a larger `M` has to
supply this theorem with `haveI` before calling `SoundEnsemble.markFinished`, which takes the
consistency as an instance argument and leaves no place for a `simp` step. As an instance this
would send synthesis looking for an `N ≤ M` on every goal of the shape. -/
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.
-/
theorem counted_not_consistent {N : ℕ} (hN : 2 ≤ N) (h_char : N < ringChar F)
(channel : Channel F Message) (m : Message F) (data : ProverData F)
(h_m : ¬ channel.Guarantees m data) : ¬ (channel.counted N).Consistent := by
rintro ⟨ consistent ⟩
have cast_inj {a b : ℕ} (ha : a < ringChar F) (hb : b < ringChar F) :
(a : F) = (b : F) → a = b :=
fun h => (Lean.Grind.IsCharP.natCast_eq_iff_of_lt (α := F) _ ha hb).mp h
have hN0 : (N : F) ≠ 0 := fun h => by
have := cast_inj h_char (b := 0) (by omega) (by simpa using h); omega
have hN1 : (N : F) ≠ 1 := fun h => by
have := cast_inj h_char (b := 1) (by omega) (by simpa using h); omega
let mk : F → Interaction F :=
fun mult => ⟨ channel.counted N, .pull, mult, (toElements m).toArray, by simp [counted] ⟩
let l := [mk (N : F), mk 1]
have h_bal : BalancedInteractions l := by
constructor
· -- the pull of `1` is matched by the pull of `N`, which `Interaction.Push` counts as a push
intro a a_mem _
refine ⟨ mk (N : F), by simp [l], ?_, hN0, fun _ => hN1 ⟩
simp only [l, List.mem_cons, List.not_mem_nil, or_false] at a_mem
rcases a_mem with rfl | rfl <;> rfl
· -- the multiplicity `N` is neither `0` nor `1`, so only untouched messages qualify
intro msg is_bool
by_cases h_msg : (toElements m).toArray = msg
· exfalso
rcases is_bool (mk (N : F)) (by simp [l]) h_msg with h | h
· exact hN0 h
· exact hN1 h
· simp [activeCount, l, mk, h_msg]
have h_reqs : ∀ i ∈ l, i.channel = channel.counted N ∧ i.Requirements data := by
intro i h_i
simp only [l, List.mem_cons, List.not_mem_nil, or_false] at h_i
rcases h_i with rfl | rfl
· refine ⟨ rfl, ?_ ⟩
simp only [Interaction.Requirements, mk, counted, Interaction.msgVector]
exact .inr ⟨ N, by omega, le_rfl, rfl ⟩
· refine ⟨ rfl, ?_ ⟩
simp only [Interaction.Requirements, mk, counted, Interaction.msgVector]
exact .inr ⟨ 1, le_rfl, by omega, by simp ⟩
have h_g := consistent l data h_bal h_reqs (mk 1) (by simp [l])
simp only [Interaction.Guarantees, mk, counted, Interaction.msgVector] at h_g
apply h_m
have h := h_g trivial ⟨ 1, le_rfl, by omega, by simp ⟩
convert h
simp [ProvableType.fromElements_toElements]

end Channel
18 changes: 10 additions & 8 deletions Clean/Air/FlatEnsemble.lean
Original file line number Diff line number Diff line change
Expand Up @@ -333,16 +333,18 @@ lemma interactionsWith_of_verifier_empty {ens : Ensemble F PublicIO} {witness :
simp [interactionsWith, verifierInteractionsWith, Tables.interactionsWith,
circuit_norm, h_verifier_empty, Verifier.Program.empty]

/-- The ensemble interactions with a particular channel are balanced. -/
/-- The ensemble interactions with a particular channel are balanced, with pulls of multiplicity up
to `N` matched by a push. -/
@[circuit_norm]
abbrev BalancedChannel {ens : Ensemble F PublicIO} (witness : EnsembleWitness ens)
abbrev BalancedChannel {ens : Ensemble F PublicIO} (witness : EnsembleWitness ens) (N : ℕ)
(channel : RawChannel F) : Prop :=
BalancedInteractions (witness.interactionsWith channel)
BalancedUpTo N (witness.interactionsWith channel)

/-- All ensemble interactions with all ensemble channels are balanced. -/
/-- All ensemble interactions with all ensemble channels are balanced, with pulls of multiplicity up
to `N` matched by a push. -/
@[circuit_norm]
def BalancedChannels {ens : Ensemble F PublicIO} (witness : EnsembleWitness ens) : Prop :=
∀ channel ∈ ens.channels, BalancedChannel witness channel
def BalancedChannels {ens : Ensemble F PublicIO} (witness : EnsembleWitness ens) (N : ℕ) : Prop :=
∀ channel ∈ ens.channels, BalancedChannel witness N channel

/-- The number of rows of each table, in the order of the ensemble's components. -/
def heights {ens : Ensemble F PublicIO} (witness : EnsembleWitness ens) : List ℕ :=
Expand All @@ -360,9 +362,9 @@ def InteractionsFit {ens : Ensemble F PublicIO} (witness : EnsembleWitness ens)

lemma balancedChannels_of_balanced {ens : Ensemble F PublicIO} {witness : EnsembleWitness ens}
{balance : Balance F} (fit : witness.InteractionsFit balance)
(balanced : witness.Balanced balance) : witness.BalancedChannels :=
(balanced : witness.Balanced balance) : witness.BalancedChannels balance.pullBound :=
fun channel h_channel =>
balance.balancedInteractions_of_balanced _ (fit channel h_channel) (balanced channel h_channel)
balance.balancedUpTo_of_balanced (fit channel h_channel) (balanced channel h_channel)
end EnsembleWitness

/--
Expand Down
Loading
Loading