doc: remove stark-signature and improve docs

Cargo.toml

@@ -10,8 +10,7 @@ members = [
   "prover",
   "verifier",
   "winterfell",
-  "examples"
-, "stark-signature"]
+  "examples"]
 resolver = "2"
 
 [profile.release]

air/src/air/context.rs

@@ -468,7 +468,7 @@ impl ZkParameters {
     pub fn degree_witness_randomizer(&self) -> usize {
         self.degree_witness_randomizer
     }
-    
+
     pub fn degree_constraint_randomizer(&self) -> usize {
         self.degree_constraint_randomizer
     }

air/src/proof/context.rs

@@ -154,6 +154,8 @@ impl Deserializable for Context {
 
         // read options
         let options = ProofOptions::read_from(source)?;
+
+        // TODO: should we validate it?
         let zk_blowup = usize::read_from(source)?;
 
         Ok(Context {

prover/src/constraints/composition_poly.rs

@@ -49,6 +49,11 @@ impl<E: FieldElement> CompositionPolyTrace<E> {
 ///
 /// For example, if the composition polynomial has degree 2N - 1, where N is the trace length,
 /// it will be stored as two columns of size N (each of degree N - 1).
+/// 
+/// When zero-knowledge is enabled, the composition polynomial is split into segment polynomials
+/// such that each segment polynomial's degree is small enough to accommodate adding a randomizer
+/// polynomial without the degree of the resulting ranomized segment polynomial exceeding
+/// `domain.trace_length()`.
 pub struct CompositionPoly<E: FieldElement> {
     data: ColMatrix<E>,
 }
@@ -138,6 +143,10 @@ impl<E: FieldElement> CompositionPoly<E> {
     }
 }
 
+/// Takes a vector of coefficients representing the segment polynomials of a given composition
+/// polynomial as input, and generates coefficients of their randomized version.
+/// 
+/// The randomization technique is the one in section 4.1 in https://eprint.iacr.org/2024/1037.pdf.
 fn complement_to<R: RngCore, E: FieldElement>(
     polys: Vec<Vec<E>>,
     l: usize,

prover/src/matrix/col_matrix.rs

@@ -298,6 +298,21 @@ impl<E: FieldElement> ColMatrix<E> {
         self.columns
     }
 
+    /// Randomizes the trace polynomials when zero-knowledge is enabled.
+    /// 
+    /// Takes as input a factor that is a power of two which is used to determine the size (i.e., 
+    /// the number of coefficients) of the randomized witness polynomial.
+    /// 
+    /// The randomized witness polynomial has the form:
+    /// 
+    ///         \hat{w}(x) = w(x) + r(x) * Z_H(x)
+    /// 
+    /// where:
+    /// 
+    /// 1. w(x) is the witness polynomial of degree trace length minus one.
+    /// 2. \hat{w}(x) is the randomized witness polynomial.
+    /// 3. r(x) is the randomizer polynomial and has degree `(zk_blowup - 1) * n`.
+    /// 4. Z_H(x) = (x^n - 1). 
     pub(crate) fn randomize<R: RngCore>(&self, zk_blowup: usize, prng: &mut R) -> Self {
         let cur_len = self.num_rows();
         let extended_len = zk_blowup * cur_len;

prover/src/trace/trace_lde/default/mod.rs

@@ -296,6 +296,10 @@ where
         .entered();
 
         let trace_polys = trace.interpolate_columns();
+
+        // when zero-knowledge is enabled, we randomize the witness polynomials by adding a random
+        // polynomial times the zerofier over the trace domain. The degree of the random polynomial
+        // is a function of the number of FRI queries.
         let trace_polys = if let Some(parameters) = zk_parameters {
             trace_polys.randomize(parameters.zk_blowup_witness(), prng)
         } else {