chore: address feedback

air/src/proof/mod.rs

@@ -99,7 +99,7 @@ impl Proof {
     ///
     /// This is the conjecture on the security of the Toy problem (Conjecture 1)
     /// in https://eprint.iacr.org/2021/582.
-    pub fn security_level_conjectured<H: Hasher>(&self) -> ConjecturedSecurity {
+    pub fn conjectured_security<H: Hasher>(&self) -> ConjecturedSecurity {
         ConjecturedSecurity::compute(
             self.context.options(),
             self.context.num_modulus_bits(),
@@ -111,7 +111,7 @@ impl Proof {
     ///
     /// Usually, the number of queries needed for provable security is 2x - 3x higher than
     /// the number of queries needed for conjectured security at the same security level.
-    pub fn security_level_proven<H: Hasher>(&self) -> ProvenSecurity {
+    pub fn proven_security<H: Hasher>(&self) -> ProvenSecurity {
         ProvenSecurity::compute(
             self.context.options(),
             self.context.num_modulus_bits(),

air/src/proof/security.rs

@@ -9,12 +9,24 @@ use core::cmp;
 
 use crate::ProofOptions;
 
+// CONSTANTS
+// ================================================================================================
+
 const GRINDING_CONTRIBUTION_FLOOR: u32 = 80;
 const MAX_PROXIMITY_PARAMETER: u64 = 1000;
 
+// CONJECTURED SECURITY
+// ================================================================================================
+
+/// Represents the security bits of the protocol under Conjecture 1 in [1].
+///
+/// [1]: https://eprint.iacr.org/2021/582
 pub struct ConjecturedSecurity(u32);
 
 impl ConjecturedSecurity {
+    /// Computes the security bits using a modification of Eq. (19) in [1].
+    ///
+    /// [1]: https://eprint.iacr.org/2021/582
     pub fn compute(
         options: &ProofOptions,
         base_field_bits: u32,
@@ -37,21 +49,31 @@ impl ConjecturedSecurity {
         Self(cmp::min(cmp::min(field_security, query_security) - 1, collision_resistance))
     }
 
+    /// Returns the conjectured security bits.
     pub fn bits(&self) -> u32 {
         self.0
     }
 
+    /// Returns whether or not the conjectured security bits are at least `bits` security bits.
     pub fn is_at_least(&self, bits: u32) -> bool {
         self.0 >= bits
     }
 }
 
+// PROVEN SECURITY
+// ================================================================================================
+
+/// Represents the proven security bits, in list-decoding and unique decoding regimes, of
+/// the protocol.
 pub struct ProvenSecurity {
     unique_decoding: u32,
     list_decoding: u32,
 }
 
 impl ProvenSecurity {
+    /// Computes the proven security bits using Theorem 2 and Theorem 3 in [1].
+    ///
+    /// [1]: https://eprint.iacr.org/2024/1553
     pub fn compute(
         options: &ProofOptions,
         base_field_bits: u32,
@@ -94,14 +116,17 @@ impl ProvenSecurity {
         Self { unique_decoding, list_decoding }
     }
 
+    /// Returns the proven security bits in the list decoding regime.
     pub fn ldr_bits(&self) -> u32 {
         self.list_decoding
     }
 
+    /// Returns the proven security bits in the unique decoding regime.
     pub fn udr_bits(&self) -> u32 {
         self.unique_decoding
     }
 
+    /// Returns whether or not the proven security bits are at least `bits` security bits.
     pub fn is_at_least(&self, bits: u32) -> bool {
         self.list_decoding >= bits || self.unique_decoding >= bits
     }
@@ -278,8 +303,11 @@ pub fn ceil(value: f64) -> f64 {
     libm::ceil(value)
 }
 
+// TESTS
+// ================================================================================================
+
 #[cfg(test)]
-mod prove_security_tests {
+mod tests {
     use math::{fields::f64::BaseElement, StarkField};
 
     use super::ProofOptions;

examples/src/lib.rs

@@ -107,11 +107,11 @@ impl ExampleOptions {
     /// Returns the conjectured security level of the input proof in bits.
     pub fn get_proof_security_level_conjectured(&self, proof: &Proof) -> u32 {
         let security_level = match self.hash_fn.as_str() {
-            "blake3_192" => proof.security_level_conjectured::<Blake3_192>(),
-            "blake3_256" => proof.security_level_conjectured::<Blake3_256>(),
-            "sha3_256" => proof.security_level_conjectured::<Sha3_256>(),
-            "rp64_256" => proof.security_level_conjectured::<Rp64_256>(),
-            "rp_jive64_256" => proof.security_level_conjectured::<RpJive64_256>(),
+            "blake3_192" => proof.conjectured_security::<Blake3_192>(),
+            "blake3_256" => proof.conjectured_security::<Blake3_256>(),
+            "sha3_256" => proof.conjectured_security::<Sha3_256>(),
+            "rp64_256" => proof.conjectured_security::<Rp64_256>(),
+            "rp_jive64_256" => proof.conjectured_security::<RpJive64_256>(),
             val => panic!("'{val}' is not a valid hash function option"),
         };
 
@@ -121,11 +121,11 @@ impl ExampleOptions {
     /// Returns the proven security level of the input proof in bits.
     pub fn get_proof_security_level_proven(&self, proof: &Proof) -> (u32, u32) {
         let security_level = match self.hash_fn.as_str() {
-            "blake3_192" => proof.security_level_proven::<Blake3_192>(),
-            "blake3_256" => proof.security_level_proven::<Blake3_256>(),
-            "sha3_256" => proof.security_level_proven::<Sha3_256>(),
-            "rp64_256" => proof.security_level_proven::<Rp64_256>(),
-            "rp_jive64_256" => proof.security_level_proven::<RpJive64_256>(),
+            "blake3_192" => proof.proven_security::<Blake3_192>(),
+            "blake3_256" => proof.proven_security::<Blake3_256>(),
+            "sha3_256" => proof.proven_security::<Sha3_256>(),
+            "rp64_256" => proof.proven_security::<Rp64_256>(),
+            "rp_jive64_256" => proof.proven_security::<RpJive64_256>(),
             val => panic!("'{val}' is not a valid hash function option"),
         };
 

verifier/src/lib.rs

@@ -360,7 +360,7 @@ impl AcceptableOptions {
     pub fn validate<H: Hasher>(&self, proof: &Proof) -> Result<(), VerifierError> {
         match self {
             AcceptableOptions::MinConjecturedSecurity(minimal_security) => {
-                let conjectured_security = proof.security_level_conjectured::<H>();
+                let conjectured_security = proof.conjectured_security::<H>();
                 if !conjectured_security.is_at_least(*minimal_security) {
                     return Err(VerifierError::InsufficientConjecturedSecurity(
                         *minimal_security,
@@ -369,7 +369,7 @@ impl AcceptableOptions {
                 }
             },
             AcceptableOptions::MinProvenSecurity(minimal_security) => {
-                let proven_security = proof.security_level_proven::<H>();
+                let proven_security = proof.proven_security::<H>();
                 if !proven_security.is_at_least(*minimal_security) {
                     return Err(VerifierError::InsufficientProvenSecurity(
                         *minimal_security,