Add docstring for SuitableRing (#58)

Cargo.toml

@@ -11,4 +11,9 @@ ark-std = { version = "0.4.0", default-features = false }
 lattirust-linear-algebra = { git = "ssh://[email protected]/NethermindEth/lattirust.git", branch = "main", default-features = false }
 lattirust-poly = { git = "ssh://[email protected]/NethermindEth/lattirust.git", branch = "main", default-features = false }
 lattirust-ring = { git = "ssh://[email protected]/NethermindEth/lattirust.git", branch = "main", default-features = false }
-thiserror = { version = "1.0.63", default-features = false }
+thiserror = { version = "1.0.63", default-features = false }
+
+[workspace.metadata.docs.rs]
+# To build locally, use 
+# RUSTDOCFLAGS="--html-in-header docs-header.html" cargo doc --no-deps --document-private-items --open
+rustdoc-args = [ "--html-in-header", "docs-header.html" ]

cyclotomic-rings/src/rings.rs

@@ -21,23 +21,52 @@ pub use frog::*;
 pub use goldilocks::*;
 pub use stark::*;
 
-/// This trait should be used for rings in Latticefold.
-/// It contains all the data needed in the protocol.
-/// The type itself is meant to be the NTT-representation of a ring.
-/// The associated type `CoefficientRepresentation` is the ring in the coefficient basis.
+/// An umbrella trait of a ring suitable to be used in the LatticeFold protocol.
+///
+/// The ring is assumed to be of the form $$\mathbb{Z}_p\[X\]/(f(X)),$$ for a polynomial
+/// $f(X) \in \mathbb{Z}_p\[X\]$ (typically, this is a cyclotomic polynomial $\Phi_m(X)$) so it has
+/// two isomorphic forms:
+///   * <i>The coefficient form</i>, i.e. a ring element is represented as the unique polynomial $g$ of the
+///     degree $\mathrm{deg}\ g < \mathrm{deg}\ f$.
+///   * <i>The NTT form</i>, i.e. a ring element is represented as its image along the Chinese-remainder isomorphism
+///     $$\mathbb{Z}_p\[X\]/(f(X))\cong \prod\limits\_{i=1}^\tau\mathbb{Z}_p\[X\]/(f\_i(X)),$$
+///     where $f\_1(X),\ldots, f\_\tau(X)$ are irreducible polynomials in $ \mathbb{Z}_p\[X\]$ such that
+///     $$f(X) = f\_1(X)\cdot\ldots\cdot f\_\tau(X).$$
+///
+/// When $f(X)$ is a cyclotomic polynomial the factors $f\_1(X),\ldots, f\_\tau(X)$ have equal degrees, thus the fields in the RHS of
+/// the Chinese-remainder isomorphism are all isomorphic to the same extension of the field $\mathbb{Z}\_p$, implying the NTT form
+/// of the ring is a direct product of $\tau$ instances of $\mathbb{Z}\_{p^k}$ for some $k$ with componentwise operations.
+///
+/// If `R: SuitableRing` then we assume that the type `R` represents the NTT form of the ring as the arithmetic operations
+/// in the NTT form are much faster and we intend to use the NTT form as much as possible only occasionally turning to the
+/// coefficient form (usually, when Ajtai security aspects are discussed). The associated type `CoefficientRepresentation` is the corresponding
+/// coefficient form representation of the ring.
+///
+/// A type `R: SuitableRing` and its `R::CoefficientRepresentation` has to satisfy the following conditions:
+///   * `R` has to be an `OverField` to exhibit an algebra over a field `R::BaseRing` structure.  
+///   * `R::CoefficientRepresentation` has to be an algebra over the prime field `R::BaseRing::BasePrimeField` of the field `R::BaseRing`.
+///   * `R::BaseRing::BasePrimeField` has to be absorbable by sponge hashes (`R::BaseRing::BasePrimeField: Absorb`).
+///   * `R` and `R::CoefficientRepresentation` should be convertible into each other.
+///   * `R::CoefficientRepresentation` is radix-$B$ decomposable and exhibits cyclotomic structure (`R::CoefficientRepresentation: Decompose + Cyclotomic`).
+///
+/// In addition to the data above a suitable ring has to provide Poseidon hash parameters for its base prime field (i.e. $\mathbb{Z}\_p$).
 pub trait SuitableRing:
     OverField + From<Self::CoefficientRepresentation> + Into<Self::CoefficientRepresentation>
 where
     <<Self as PolyRing>::BaseRing as Field>::BasePrimeField: Absorb,
 {
-    /// The coefficient basis version of the ring.
+    /// The coefficient form version of the ring.
     type CoefficientRepresentation: OverField<BaseRing = <<Self as PolyRing>::BaseRing as Field>::BasePrimeField>
         + Decompose
         + Cyclotomic;
+
+    /// Poseidon sponge parameters for the base prime field.
     type PoseidonParams: GetPoseidonParams<<<Self as PolyRing>::BaseRing as Field>::BasePrimeField>;
 }
 
+/// A trait for types with an associated Poseidon sponge configuration.
 pub trait GetPoseidonParams<Fq: PrimeField> {
+    /// Returns the associated Poseidon sponge configuration.
     fn get_poseidon_config() -> PoseidonConfig<Fq>;
 }
 

docs-header.html

@@ -0,0 +1,16 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" crossorigin="anonymous">
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js"                  crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"    crossorigin="anonymous"></script>
+<script>
+    document.addEventListener("DOMContentLoaded", function() {
+        renderMathInElement(document.body, {
+            delimiters: [
+                {left: "$$", right: "$$", display: true},
+                {left: "\\(", right: "\\)", display: false},
+                {left: "$", right: "$", display: false},
+                {left: "\\[", right: "\\]", display: true}
+            ]
+        });
+    });
+</script>
+