Skip to main content

binius_iop/basefold/
compiler.rs

1// Copyright 2026 The Binius Developers
2
3//! BaseFold compiler for IOP verifiers.
4
5use std::borrow::BorrowMut;
6
7use binius_field::BinaryField;
8use binius_hash::HashSuite;
9use binius_transcript::{VerifierTranscript, fiat_shamir::Challenger};
10use binius_utils::{DeserializeBytes, FixedSizeSerializeBytes};
11use digest::Output;
12
13use crate::{
14	basefold::{
15		channel::BaseFoldVerifierChannel,
16		layout::{RoundLayout, layout_rounds},
17	},
18	channel::OracleSchedule,
19	fri::FRIParams,
20	merkle_channel::{MerkleIPVerifierChannel, VerifierMerkleTranscriptChannel},
21	merkle_tree::BinaryMerkleTreeScheme,
22};
23
24/// A compiler that creates BaseFold ZK verifier channels with precomputed parameters.
25///
26/// This compiler commits each round of the schedule as one oracle, laid out by [`layout_rounds`],
27/// and builds a single combined FRI over the round oracles. ZK round oracles configure FRI
28/// parameters for zero-knowledge mode (`log_msg_len + 1` as the message length and
29/// `log_batch_size = 1`); non-ZK ones take a flexible batch size with no mask. Each ZK round also
30/// reserves a ZK pad of one coordinate per test query, which hides the codeword symbols the query
31/// phase opens.
32///
33/// # Invariant
34///
35/// A ZK round oracle is batched only with its mask. Its FRI codeword has `log_batch_size = 1`, and
36/// the code's message length (`rs_code.log_dim() - log_lift`) equals the round layout's
37/// `log_len`, so the oracle is fully encoded with no further lifting or batching. The ZK pad's
38/// hiding argument relies on this. [`Self::new`] asserts it.
39#[derive(Clone)]
40pub struct BaseFoldVerifierCompiler<F>
41where
42	F: BinaryField,
43{
44	schedule: OracleSchedule,
45	layouts: Vec<RoundLayout>,
46	fri_params: FRIParams<F>,
47}
48
49impl<F> BaseFoldVerifierCompiler<F>
50where
51	F: BinaryField,
52{
53	/// Creates a new compiler with precomputed combined FRI parameters.
54	///
55	/// The `merkle_scheme` is consulted only for proof-size estimation while choosing the FRI
56	/// parameters; it is not stored. Each round oracle's batch size is derived from its ZK flag: a
57	/// ZK oracle fixes `log_batch_size = 1` (message ‖ equal-length mask), a non-ZK oracle takes a
58	/// flexible batch size. Requires at least one oracle.
59	///
60	/// # Panics
61	///
62	/// Panics if a ZK round oracle is not fully encoded, i.e. its codeword does not have
63	/// `log_batch_size = 1` and a message length equal to the layout's.
64	pub fn new<H>(
65		merkle_scheme: &BinaryMerkleTreeScheme<F, H>,
66		schedule: OracleSchedule,
67		log_inv_rate: usize,
68		n_test_queries: usize,
69	) -> Self
70	where
71		H: HashSuite,
72	{
73		assert!(
74			!schedule.specs().is_empty(),
75			"BaseFoldVerifierCompiler requires at least one oracle spec"
76		);
77		let layouts = layout_rounds(&schedule, n_test_queries);
78		let round_specs = layouts.iter().map(RoundLayout::spec).collect::<Vec<_>>();
79
80		// The single combined FRI parameters over all oracles. `optimal_for_batch` chooses the fold
81		// arities to minimize proof size. It derives each oracle's batch size from its ZK flag: ZK
82		// oracles fix `log_batch_size = 1` (message ‖ mask), non-ZK oracles take a flexible batch
83		// size.
84		let (fri_params, _) =
85			FRIParams::optimal_for_batch(merkle_scheme, &round_specs, log_inv_rate, n_test_queries);
86
87		// ZK hiding invariant: each ZK round oracle is batched only with its mask and is fully
88		// encoded.
89		let input_oracles = fri_params.input_oracles();
90		assert_eq!(input_oracles.len(), layouts.len());
91		for (layout, codeword) in layouts.iter().zip(input_oracles) {
92			if layout.is_zk {
93				assert_eq!(
94					codeword.log_batch_size(),
95					1,
96					"ZK round oracle must batch only with its mask"
97				);
98				assert_eq!(
99					fri_params.rs_code().log_dim() - codeword.log_lift,
100					layout.log_len,
101					"ZK round oracle must be fully encoded"
102				);
103			}
104		}
105
106		Self {
107			schedule,
108			layouts,
109			fri_params,
110		}
111	}
112
113	/// Returns the schedule of oracles the channels commit.
114	pub const fn oracle_schedule(&self) -> &OracleSchedule {
115		&self.schedule
116	}
117
118	/// Returns the layout of each round oracle.
119	pub fn layouts(&self) -> &[RoundLayout] {
120		&self.layouts
121	}
122
123	/// Returns a reference to the precomputed combined FRI parameters.
124	pub const fn fri_params(&self) -> &FRIParams<F> {
125		&self.fri_params
126	}
127
128	/// The dimension of the largest evaluation domain the combined FRI parameters need.
129	///
130	/// A prover builds its NTT domain context from this. The basis is not communicated because
131	/// [`ReedSolomonCode`](binius_math::reed_solomon::ReedSolomonCode) fixes it: the Gao-Mateer
132	/// basis of this dimension.
133	pub fn max_log_domain_size(&self) -> usize {
134		self.fri_params.rs_code().log_len()
135	}
136
137	/// Creates a ZK verifier channel over the given Merkle channel.
138	///
139	/// The returned channel drives all prover interaction through `channel`, opening oracles with
140	/// this compiler's schedule, round layouts and combined FRI parameters. The caller constructs
141	/// the Merkle channel, so it decides how commitments are received and verified.
142	pub fn create_channel<Channel>(
143		&self,
144		channel: Channel,
145	) -> BaseFoldVerifierChannel<'_, F, Channel>
146	where
147		Channel: MerkleIPVerifierChannel<F, Elem: From<F> + 'static>,
148	{
149		BaseFoldVerifierChannel::new(channel, &self.schedule, &self.layouts, &self.fri_params)
150	}
151
152	/// Creates a ZK verifier channel over a transcript, for the common case.
153	///
154	/// The transcript may be owned or mutably borrowed.
155	/// It is wrapped in a [`VerifierMerkleTranscriptChannel`] for the given hash suite.
156	/// That channel is then passed to [`Self::create_channel`].
157	pub fn create_channel_from_transcript<H, Challenger_, T>(
158		&self,
159		transcript: T,
160	) -> BaseFoldVerifierChannel<'_, F, VerifierMerkleTranscriptChannel<T, Challenger_, F, H>>
161	where
162		F: FixedSizeSerializeBytes,
163		H: HashSuite,
164		Challenger_: Challenger,
165		T: BorrowMut<VerifierTranscript<Challenger_>>,
166		Output<H::LeafHash>: DeserializeBytes,
167	{
168		self.create_channel(VerifierMerkleTranscriptChannel::new(transcript))
169	}
170}