From 6104d606becf133a69f7a790b5b6462c65f6fd4a Mon Sep 17 00:00:00 2001
From: Luke Parker <lukeparker5132@gmail.com>
Date: Fri, 24 Feb 2023 04:37:20 -0500
Subject: [PATCH] 3.4.2 Document the DLEq lib

---
 crypto/dleq/src/lib.rs | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/crypto/dleq/src/lib.rs b/crypto/dleq/src/lib.rs
index 3fc270bd..f224dd88 100644
--- a/crypto/dleq/src/lib.rs
+++ b/crypto/dleq/src/lib.rs
@@ -21,6 +21,7 @@ pub mod cross_group;
 #[cfg(test)]
 mod tests;
 
+// Produce a non-biased challenge from the transcript in the specified field
 pub(crate) fn challenge<T: Transcript, F: PrimeField>(transcript: &mut T) -> F {
   // From here, there are three ways to get a scalar under the ff/group API
   // 1: Scalar::random(ChaCha20Rng::from_seed(self.transcript.rng_seed(b"challenge")))
@@ -80,6 +81,7 @@ pub(crate) fn challenge<T: Transcript, F: PrimeField>(transcript: &mut T) -> F {
   challenge
 }
 
+// Helper function to read a scalar
 #[cfg(feature = "serialize")]
 fn read_scalar<R: Read, F: PrimeField>(r: &mut R) -> io::Result<F> {
   let mut repr = F::Repr::default();
@@ -91,11 +93,13 @@ fn read_scalar<R: Read, F: PrimeField>(r: &mut R) -> io::Result<F> {
   Ok(scalar.unwrap())
 }
 
-#[derive(Debug)]
+/// Error for DLEq proofs.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum DLEqError {
   InvalidProof,
 }
 
+/// A proof that points have the same discrete logarithm across generators.
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Zeroize)]
 pub struct DLEqProof<G: PrimeGroup> {
   c: G::Scalar,
@@ -110,6 +114,8 @@ impl<G: PrimeGroup> DLEqProof<G> {
     transcript.append_message(b"point", point.to_bytes());
   }
 
+  /// Prove that the points created by `scalar * G`, for each specified generator, share a discrete
+  /// logarithm.
   pub fn prove<R: RngCore + CryptoRng, T: Transcript>(
     rng: &mut R,
     transcript: &mut T,
@@ -134,6 +140,7 @@ impl<G: PrimeGroup> DLEqProof<G> {
     DLEqProof { c, s }
   }
 
+  /// Verify the specified points share a discrete logarithm across the specified generators.
   pub fn verify<T: Transcript>(
     &self,
     transcript: &mut T,
@@ -159,17 +166,20 @@ impl<G: PrimeGroup> DLEqProof<G> {
     Ok(())
   }
 
+  /// Write a DLEq proof to something implementing Write.
   #[cfg(feature = "serialize")]
   pub fn write<W: Write>(&self, w: &mut W) -> io::Result<()> {
     w.write_all(self.c.to_repr().as_ref())?;
     w.write_all(self.s.to_repr().as_ref())
   }
 
+  /// Read a DLEq proof from something implementing Read.
   #[cfg(feature = "serialize")]
   pub fn read<R: Read>(r: &mut R) -> io::Result<DLEqProof<G>> {
     Ok(DLEqProof { c: read_scalar(r)?, s: read_scalar(r)? })
   }
 
+  /// Serialize a DLEq proof to a Vec<u8>.
   #[cfg(feature = "serialize")]
   pub fn serialize(&self) -> Vec<u8> {
     let mut res = vec![];
@@ -178,6 +188,9 @@ impl<G: PrimeGroup> DLEqProof<G> {
   }
 }
 
+/// A proof that multiple series of points each have a single discrete logarithm across generators.
+/// This is effectively n distinct DLEq proofs, one for each discrete logarithm and its points
+/// across some generators, yet with a smaller overall proof size.
 #[cfg(feature = "std")]
 #[derive(Clone, PartialEq, Eq, Debug, Zeroize)]
 pub struct MultiDLEqProof<G: PrimeGroup> {
@@ -188,6 +201,8 @@ pub struct MultiDLEqProof<G: PrimeGroup> {
 #[cfg(feature = "std")]
 #[allow(non_snake_case)]
 impl<G: PrimeGroup> MultiDLEqProof<G> {
+  /// Prove for each scalar that the series of points created by multiplying it against its
+  /// matching generators share a discrete logarithm.
   pub fn prove<R: RngCore + CryptoRng, T: Transcript>(
     rng: &mut R,
     transcript: &mut T,
@@ -226,6 +241,8 @@ impl<G: PrimeGroup> MultiDLEqProof<G> {
     MultiDLEqProof { c, s }
   }
 
+  /// Verify each series of points share a discrete logarithm against their matching series of
+  /// generators.
   pub fn verify<T: Transcript>(
     &self,
     transcript: &mut T,
@@ -263,6 +280,7 @@ impl<G: PrimeGroup> MultiDLEqProof<G> {
     Ok(())
   }
 
+  /// Write a multi-DLEq proof to something implementing Write.
   #[cfg(feature = "serialize")]
   pub fn write<W: Write>(&self, w: &mut W) -> io::Result<()> {
     w.write_all(self.c.to_repr().as_ref())?;
@@ -272,6 +290,7 @@ impl<G: PrimeGroup> MultiDLEqProof<G> {
     Ok(())
   }
 
+  /// Read a multi-DLEq proof from something implementing Read.
   #[cfg(feature = "serialize")]
   pub fn read<R: Read>(r: &mut R, discrete_logs: usize) -> io::Result<MultiDLEqProof<G>> {
     let c = read_scalar(r)?;
@@ -282,6 +301,7 @@ impl<G: PrimeGroup> MultiDLEqProof<G> {
     Ok(MultiDLEqProof { c, s })
   }
 
+  /// Serialize a multi-DLEq proof to a Vec<u8>.
   #[cfg(feature = "serialize")]
   pub fn serialize(&self) -> Vec<u8> {
     let mut res = vec![];