hekate_core/
config.rs

1// SPDX-License-Identifier: Apache-2.0
2// This file is part of the hekate project.
3// Copyright (C) 2026 Andrei Kochergin <andrei@oumuamua.dev>
4// Copyright (C) 2026 Oumuamua Labs <info@oumuamua.dev>. All rights reserved.
5//
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10//     http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18use crate::errors;
19use crate::utils::compute_split_vars;
20use core::fmt;
21use tracing::warn;
22
23/// Production soundness floor:
24/// full GF(2^128) security. `security_bits` caps
25/// at the field size, 128 is the strongest attainable.
26pub const MIN_PRODUCTION_BITS: usize = 128;
27
28/// Failures produced by `Config::check_security`.
29#[derive(Clone, Copy, Debug, Eq, PartialEq)]
30pub enum Error {
31    /// Estimated security fell below `min_security_bits`.
32    SecurityTooLow {
33        estimated_bits: usize,
34        min_bits: usize,
35    },
36
37    /// `ldt_blinding_factor < num_queries`;
38    /// opened columns exhaust the noise
39    /// budget and witness data leaks.
40    InsufficientLdtBlinding {
41        ldt_blinding_factor: usize,
42        num_queries: usize,
43    },
44}
45
46impl fmt::Display for Error {
47    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
48        match self {
49            Self::SecurityTooLow {
50                estimated_bits,
51                min_bits,
52            } => write!(
53                f,
54                "Security too low: estimated {estimated_bits} bits, but {min_bits} required",
55            ),
56            Self::InsufficientLdtBlinding {
57                ldt_blinding_factor,
58                num_queries,
59            } => write!(
60                f,
61                "ldt_blinding_factor ({ldt_blinding_factor}) must be >= num_queries ({num_queries})",
62            ),
63        }
64    }
65}
66
67/// Security metrics snapshot for a given `Config`.
68#[derive(Clone, Copy, Debug)]
69pub struct SecurityMetrics {
70    /// Estimated relative distance
71    /// δ of the linear code.
72    pub relative_distance: f64,
73
74    /// LDT spot-check count.
75    pub num_queries: usize,
76
77    /// Soundness error:
78    /// `(1 - δ)^q`.
79    pub soundness_error: f64,
80
81    /// LDT proximity bound:
82    /// `-log₂(soundness_error)`.
83    pub ldt_bits: usize,
84
85    /// `min(ldt_bits, field_bits)`. Schwartz-Zippel
86    /// caps Sumcheck / ZeroCheck / LogUp at field size.
87    pub security_bits: usize,
88
89    /// Non-zero entries per row of
90    /// the expander matrix.
91    pub expansion_degree: usize,
92}
93
94#[derive(Clone, Debug)]
95pub struct Config {
96    /// Non-zero entries per row in
97    /// the expander matrix.
98    pub expansion_degree: usize,
99
100    /// Number of LDT spot-check queries.
101    pub num_queries: usize,
102
103    /// Seed for the deterministic RNG
104    /// that samples the expander matrix.
105    pub matrix_seed: [u8; 32],
106
107    /// Blinding columns for algebraic ZK
108    /// (Sumcheck), extends the 1D trace.
109    pub sumcheck_blinding_factor: usize,
110
111    /// Blinding columns for data ZK
112    /// (LDT), extends the 2D grid width.
113    /// Must be `>= num_queries`.
114    pub ldt_blinding_factor: usize,
115
116    /// `check_security` rejects configs
117    /// whose estimated bits fall below this.
118    pub min_security_bits: usize,
119}
120
121impl Default for Config {
122    fn default() -> Self {
123        Self::prod()
124    }
125}
126
127impl Config {
128    /// Production parameters: ≈128-bit soundness
129    /// with the `MIN_PRODUCTION_BITS` acceptance
130    /// threshold. The `Default`.
131    pub fn prod() -> Self {
132        Self {
133            expansion_degree: 16,
134            num_queries: 160,
135            matrix_seed: [42u8; 32],
136            min_security_bits: MIN_PRODUCTION_BITS,
137            sumcheck_blinding_factor: 2,
138            ldt_blinding_factor: 200,
139        }
140    }
141
142    /// Fast, low-soundness parameters for tests
143    /// and experiments; `min_security_bits = 0`
144    /// accepts weak grids. Never deploy.
145    pub fn dev() -> Self {
146        Self {
147            num_queries: 4,
148            min_security_bits: 0,
149            ..Self::prod()
150        }
151    }
152
153    /// `min(-log₂((1 - δ)^q), field_bits)` where
154    /// δ = relative distance, q = num_queries.
155    ///
156    /// Brakedown (Golovnev et al. 2022), Section 3.2.
157    pub fn estimated_security_bits(&self, field_bits: usize) -> usize {
158        let delta = self.estimate_relative_distance();
159        let q = self.num_queries as f64;
160
161        let soundness_error = (1.0 - delta).powf(q);
162        let ldt_bits = (-soundness_error.log2()).floor() as usize;
163
164        ldt_bits.min(field_bits)
165    }
166
167    /// `field_bits`: `size_of::<F>() * 8`.
168    pub fn security_metrics(&self, field_bits: usize) -> SecurityMetrics {
169        let delta = self.estimate_relative_distance();
170        let q = self.num_queries as f64;
171        let soundness_error = (1.0 - delta).powf(q);
172        let ldt_bits = (-soundness_error.log2()).floor() as usize;
173
174        SecurityMetrics {
175            relative_distance: delta,
176            num_queries: self.num_queries,
177            soundness_error,
178            ldt_bits,
179            security_bits: ldt_bits.min(field_bits),
180            expansion_degree: self.expansion_degree,
181        }
182    }
183
184    /// Rejects configs that can't meet
185    /// `min_security_bits` for the
186    /// given trace dimensions.
187    pub fn check_security(&self, num_vars: usize, field_bits: usize) -> errors::Result<()> {
188        // ZK-privacy floor;
189        // dev (min_security_bits == 0) waives it.
190        if self.min_security_bits > 0 && self.ldt_blinding_factor < self.num_queries {
191            return Err(Error::InsufficientLdtBlinding {
192                ldt_blinding_factor: self.ldt_blinding_factor,
193                num_queries: self.num_queries,
194            }
195            .into());
196        }
197
198        let split_vars = compute_split_vars(num_vars, self.num_queries);
199        let grid_cols = 1usize << split_vars;
200
201        // Random-expander δ guarantees
202        // break down on very narrow grids.
203        if grid_cols > 0 && grid_cols < 128 && self.min_security_bits > 40 {
204            warn!("Grid width ({grid_cols}) too small for random expander guarantees");
205        }
206
207        // degree >> grid_cols degrades δ.
208        if grid_cols > 0 && self.expansion_degree > grid_cols / 4 {
209            warn!(
210                "Expansion degree ({}) too large for grid width ({}), need < {}",
211                self.expansion_degree,
212                grid_cols,
213                grid_cols / 4
214            );
215        }
216
217        let est_bits = self.estimated_security_bits(field_bits);
218        if est_bits < self.min_security_bits {
219            return Err(Error::SecurityTooLow {
220                estimated_bits: est_bits,
221                min_bits: self.min_security_bits,
222            }
223            .into());
224        }
225
226        Ok(())
227    }
228
229    /// Sipser-Spielman "Expander Codes"
230    /// (1996) bound `δ ≥ (d - 2√(d-1)) / d`,
231    /// scaled by an empirical correction
232    /// for finite random graphs.
233    fn estimate_relative_distance(&self) -> f64 {
234        let d = self.expansion_degree as f64;
235        if d < 2.0 {
236            return 0.01;
237        }
238
239        let sqrt_term = 2.0 * (d - 1.0).sqrt();
240        let theoretical_delta = (d - sqrt_term) / d;
241
242        // Random-graph correction:
243        // tighter as d grows.
244        let correction_factor = if d >= 64.0 {
245            0.95
246        } else if d >= 32.0 {
247            0.90
248        } else if d >= 16.0 {
249            // Standard Brakedown parameters
250            0.85
251        } else if d >= 8.0 {
252            0.75
253        } else {
254            0.60
255        };
256
257        (theoretical_delta * correction_factor).max(0.01)
258    }
259}
260
261#[cfg(test)]
262mod tests {
263    use super::*;
264
265    #[test]
266    fn default_is_prod() {
267        assert_eq!(Config::default().min_security_bits, MIN_PRODUCTION_BITS);
268        assert_eq!(Config::default().num_queries, Config::prod().num_queries);
269    }
270
271    #[test]
272    fn prod_meets_production_floor() {
273        let prod = Config::prod();
274
275        assert!(prod.estimated_security_bits(128) >= MIN_PRODUCTION_BITS);
276        assert!(prod.check_security(10, 128).is_ok());
277    }
278
279    #[test]
280    fn dev_is_lenient_on_weak_params() {
281        let dev = Config::dev();
282
283        assert!(dev.estimated_security_bits(128) < MIN_PRODUCTION_BITS);
284        assert!(dev.check_security(10, 128).is_ok());
285    }
286
287    #[test]
288    fn prod_threshold_rejects_weak_queries() {
289        let weak = Config {
290            num_queries: 4,
291            ..Config::prod()
292        };
293
294        assert!(weak.check_security(10, 128).is_err());
295    }
296}
hekate_core/config.rs

hekate_core/
config.rs
