binius_iop/channel/mod.rs
1// Copyright 2026 The Binius Developers
2
3//! Channel abstraction for interactive oracle protocol (IOP) verifiers.
4
5pub mod grinding;
6pub mod naive;
7pub mod oracle_setup;
8pub mod size_tracking;
9
10use std::iter;
11
12use binius_field::Field;
13use binius_ip::channel::IPVerifierChannel;
14use binius_utils::checked_arithmetics::log2_ceil_usize;
15
16use crate::basefold;
17
18/// Error type for IOP verifier channel operations.
19#[derive(Debug, thiserror::Error)]
20pub enum Error {
21 #[error("proof is empty")]
22 ProofEmpty,
23 #[error("BaseFold verification failed: {0}")]
24 BaseFold(#[from] basefold::Error),
25 #[error("IP channel error: {0}")]
26 IPChannel(#[from] binius_ip::channel::Error),
27 #[error("sumcheck error: {0}")]
28 Sumcheck(#[from] binius_ip::sumcheck::Error),
29 #[error("Merkle channel error: {0}")]
30 Merkle(#[from] crate::merkle_channel::Error),
31}
32
33/// Specification for an oracle to be committed in the IOP.
34///
35/// The oracle is a multilinear over `log_msg_len() = ⌈log2 len⌉` variables, whose first `len`
36/// entries are the prover's content:
37///
38/// ```text
39/// [ content: chosen by the prover | padding: chosen arbitrarily by the compiler ]
40/// 0 len 2^log_msg_len
41/// ```
42#[derive(Debug, Clone, Copy, PartialEq, Eq)]
43pub struct OracleSpec {
44 /// The length of the content section.
45 pub len: usize,
46 /// Whether the oracle is committed with zero-knowledge (hiding) masking.
47 ///
48 /// ZK oracles interleave the message with a fresh mask and are folded by a shared masking
49 /// challenge γ in the batched BaseFold opening; non-ZK oracles are committed without a mask.
50 pub is_zk: bool,
51}
52
53impl OracleSpec {
54 /// A non-ZK (unmasked) oracle of `len` content entries.
55 pub const fn new(len: usize) -> Self {
56 Self { len, is_zk: false }
57 }
58
59 /// A ZK (masked, hiding) oracle of `len` content entries.
60 pub const fn new_zk(len: usize) -> Self {
61 Self { len, is_zk: true }
62 }
63
64 /// Log2 of the message length (number of field elements), `⌈log2 len⌉`.
65 pub const fn log_msg_len(&self) -> usize {
66 log2_ceil_usize(self.len)
67 }
68}
69
70/// Every oracle an IOP commits, grouped into the rounds they are committed in.
71///
72/// A round is the run of oracles sent between two challenge samples.
73///
74/// A challenge can only be derived once the commitments before it are absorbed.
75///
76/// So a round closes the moment its challenge is drawn, and takes no further members.
77///
78/// ```text
79/// recv, recv, sample, recv, sample, recv, recv, recv
80/// \__________/ \__/ \______________/
81/// round 0 round 1 round 2
82/// ```
83///
84/// A flat spec list cannot say where those boundaries fall.
85///
86/// BaseFold commits each round as one oracle, so it needs them.
87#[derive(Debug, Default, Clone, PartialEq, Eq)]
88pub struct OracleSchedule {
89 /// Every oracle, in arrival order, across all rounds.
90 specs: Vec<OracleSpec>,
91
92 /// The exclusive end of each closed round, as an index into `specs`.
93 ///
94 /// Round `r` spans `specs[ends[r - 1]..ends[r]]`, and round `0` starts at `0`.
95 ///
96 /// Anything past the last entry is in the round still open.
97 ends: Vec<usize>,
98}
99
100impl OracleSchedule {
101 /// Creates an empty schedule.
102 pub const fn new() -> Self {
103 Self {
104 specs: Vec::new(),
105 ends: Vec::new(),
106 }
107 }
108
109 /// Builds a schedule of closed rounds, each listing its oracles in commit order.
110 pub fn from_rounds(
111 rounds: impl IntoIterator<Item = impl IntoIterator<Item = OracleSpec>>,
112 ) -> Self {
113 let mut schedule = Self::new();
114 for round in rounds {
115 schedule.specs.extend(round);
116 schedule.end_round();
117 }
118 schedule
119 }
120
121 /// Appends one oracle to the round currently open.
122 pub fn push(&mut self, spec: OracleSpec) {
123 self.specs.push(spec);
124 }
125
126 /// Closes the round currently open, so later oracles start a new one.
127 ///
128 /// Does nothing when no oracle has arrived since the last close.
129 ///
130 /// Calling it wherever a challenge could be drawn is therefore always safe.
131 pub fn end_round(&mut self) {
132 let open_start = self.ends.last().copied().unwrap_or(0);
133 if self.specs.len() > open_start {
134 self.ends.push(self.specs.len());
135 }
136 }
137
138 /// Every oracle in the schedule, in arrival order, with round boundaries dropped.
139 pub fn specs(&self) -> &[OracleSpec] {
140 &self.specs
141 }
142
143 /// Consumes the schedule and returns every oracle, with round boundaries dropped.
144 pub fn into_specs(self) -> Vec<OracleSpec> {
145 self.specs
146 }
147
148 /// The number of closed rounds.
149 pub const fn n_rounds(&self) -> usize {
150 self.ends.len()
151 }
152
153 /// The oracles of each closed round, in commit order.
154 pub fn rounds(&self) -> impl Iterator<Item = &[OracleSpec]> {
155 let starts = iter::once(0).chain(self.ends.iter().copied());
156 iter::zip(starts, self.ends.iter().copied()).map(|(start, end)| &self.specs[start..end])
157 }
158}
159
160/// A boxed closure that evaluates a transparent MLE at a given point.
161///
162/// The closure receives the challenge point sampled during the opening and returns the evaluation
163/// of the transparent polynomial's MLE there. It is `'static` and owns every value it reads,
164/// sharing large data via `Rc`/`Arc`, so a channel that defers the opening can store it and
165/// evaluate it later.
166pub type TransparentEvalFn<Elem> = Box<dyn Fn(&[Elem]) -> Elem + 'static>;
167
168/// Channel for IOP verifiers that extends the IP verifier channel with oracle operations.
169///
170/// In an IOP, the verifier can:
171/// 1. Receive field elements from the prover via `recv_*` methods (inherited)
172/// 2. Sample random challenges via `sample` (inherited)
173/// 3. Receive oracle commitments from the prover
174/// 4. Query oracles at specific positions and verify opening proofs
175///
176/// # Contract
177///
178/// The caller must call `recv_oracle()` exactly `remaining_oracle_specs().len()` times before
179/// calling `verify_oracle_relation()`. The oracles must be received in order and match their
180/// specifications.
181pub trait IOPVerifierChannel<F: Field>: IPVerifierChannel<F, Elem: 'static> {
182 type Oracle: Clone;
183
184 /// Returns the specifications for the remaining oracles to be received.
185 ///
186 /// This slice shrinks as oracles are received via `recv_oracle()`.
187 fn remaining_oracle_specs(&self) -> &[OracleSpec];
188
189 /// Receives an oracle commitment from the prover.
190 ///
191 /// The caller describes the oracle being received: `len` is its [`OracleSpec::len`], and
192 /// `is_witness_dependent` is whether the oracle's contents depend on the witness. These let a
193 /// channel record the oracle's [`OracleSpec`] rather than requiring the specs to be supplied up
194 /// front. The resulting oracle is zero-knowledge iff the channel is configured for ZK *and* the
195 /// oracle is witness-dependent — a non-witness-dependent oracle (e.g. a pre-indexed commitment
196 /// to the wiring matrix for succinctness, a planned feature) is never masked.
197 ///
198 /// Only the first `len` entries are the prover's content. The rest is padding the channel may
199 /// fill arbitrarily, so every later claim must hold over the oracle the channel commits.
200 fn recv_oracle(
201 &mut self,
202 len: usize,
203 is_witness_dependent: bool,
204 ) -> Result<Self::Oracle, Error>;
205
206 /// Queues one linear relation over committed oracles to be opened.
207 ///
208 /// The relation asserts that `Σ_i <oracle_i, transparent_i> = claim` over its operands. An
209 /// oracle may appear in any number of relations, and more than once in one.
210 ///
211 /// Implementations may either verify the relation immediately, or queue it and defer the
212 /// actual opening (masking + sumcheck + FRI) to `finish()`.
213 ///
214 /// Each transparent is a multilinear in its oracle's `log_msg_len` variables that vanishes on
215 /// every index at or above the oracle's [`OracleSpec::len`], so the relation does not depend
216 /// on the channel's padding.
217 ///
218 /// # Preconditions
219 ///
220 /// * Every operand's oracle must be a valid handle returned by `recv_oracle()`.
221 fn verify_multi_oracle_relation(
222 &mut self,
223 operands: impl IntoIterator<Item = (Self::Oracle, TransparentEvalFn<Self::Elem>)>,
224 claim: Self::Elem,
225 ) -> Result<(), Error>;
226
227 /// Queues one oracle linear relation `<oracle, transparent> = claim` to be opened.
228 ///
229 /// This is [`Self::verify_multi_oracle_relation`] with a single operand.
230 fn verify_oracle_relation(
231 &mut self,
232 oracle: Self::Oracle,
233 transparent: TransparentEvalFn<Self::Elem>,
234 claim: Self::Elem,
235 ) -> Result<(), Error> {
236 self.verify_multi_oracle_relation([(oracle, transparent)], claim)
237 }
238}