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}