Skip to main content

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}