More documentation.

Author: mmaker

src/hash/legacy.rs

@@ -163,10 +163,9 @@ impl<D: BlockSizeUser + Digest + Clone + FixedOutputReset> DuplexHash<u8> for Di
         // If we still have some digest not yet squeezed
         // from previous invocations, write it to the output.
         } else if !self.leftovers.is_empty() {
-            println!("Here we are, with leftovers {:?}", self.leftovers);
             let len = usize::min(output.len(), self.leftovers.len());
             output[..len].copy_from_slice(&self.leftovers[..len]);
-            self.leftovers.drain(len..);
+            self.leftovers.drain(..len);
             self.squeeze_unchecked(&mut output[len..])
         // Squeeze another digest
         } else if let Mode::Squeeze(i) = self.mode {

src/hash/sponge.rs

@@ -49,9 +49,9 @@ pub struct DuplexSponge<C: Sponge> {
 }
 
 impl<U: Unit, C: Sponge<U = U>> DuplexHash<U> for DuplexSponge<C> {
-    fn new(tag: [u8; 32]) -> Self {
+    fn new(iv: [u8; 32]) -> Self {
         Self {
-            state: C::new(tag),
+            state: C::new(iv),
             absorb_pos: 0,
             squeeze_pos: 0,
         }

src/iopattern.rs

@@ -14,6 +14,31 @@ use super::hash::{DuplexHash, Unit};
 /// and as such is the only forbidden characted in labels.
 const SEP_BYTE: &str = "\0";
 
+/// The IO Pattern of an interactive protocol.
+///
+/// An IO pattern is a string that specifies the protocol in a simple,
+/// non-ambiguous, human-readable format. A typical example is the following:
+///
+/// ```text
+///     domain-separator A32generator A32public-key R A32commitment S32challenge A32response
+/// ```
+/// The domain-separator is a user-specified string uniquely identifying the end-user application  (to avoid cross-protocol attacks).
+/// The letter `A` indicates the absorption of a public input (an `ABSORB`), while the letter `S` indicates the squeezing (a `SQUEEZE`) of a challenge.
+/// The letter `R` indicates a ratcheting operation: ratcheting means invoking the hash function even on an incomplete block.
+/// It provides forward secrecy and allows it to start from a clean rate.
+/// After the operation type, is the number of elements in base 10 that are being absorbed/squeezed.
+/// Then, follows the label associated with the element being absorbed/squeezed. This often comes from the underlying description of the protocol. The label cannot start with a digit or contain the NULL byte.
+
+#[derive(Clone)]
+pub struct IOPattern<H = crate::DefaultHash, U = u8>
+where
+    U: Unit,
+    H: DuplexHash<U>,
+{
+    io: String,
+    _hash: PhantomData<(H, U)>,
+}
+
 /// Sponge operations.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub(crate) enum Op {
@@ -46,34 +71,6 @@ impl Op {
     }
 }
 
-/// The IO Pattern of an interactive protocol.
-///
-/// An IO Pattern is a string denoting a
-/// sequence of operations to be performed on a [`crate::DuplexHash`].
-/// The IO Pattern is prepended by a domain separator, a NULL-terminated string
-/// that is used to prevent collisions between different protocols.
-/// Each operation (absorb, squeeze, ratchet) is identified by a
-/// single character, followed by the number of units (bytes, or field elements)
-/// to be absorbed/squeezed, and a NULL-terminated label identifying the element.
-/// The whole is separated by a NULL byte.
-///
-/// For example, the IO Pattern
-/// ```text
-/// iacr.org\0A32\0S64\0A32\0A32
-/// ```
-///
-/// Denotes a protocol absorbing 32 native elements, squeezing 64 native elements,
-/// and finally absorbing 64 native elements.
-#[derive(Clone)]
-pub struct IOPattern<H = crate::DefaultHash, U = u8>
-where
-    U: Unit,
-    H: DuplexHash<U>,
-{
-    io: String,
-    _hash: PhantomData<(H, U)>,
-}
-
 impl<H: DuplexHash<U>, U: Unit> IOPattern<H, U> {
     fn from_string(io: String) -> Self {
         Self {
@@ -88,6 +85,7 @@ impl<H: DuplexHash<U>, U: Unit> IOPattern<H, U> {
         Self::from_string(domsep.to_string())
     }
 
+    /// Absorb `count` native elements.
     pub fn absorb(self, count: usize, label: &str) -> Self {
         assert!(count > 0, "Count must be positive");
         assert!(!label.contains(SEP_BYTE));
@@ -96,6 +94,7 @@ impl<H: DuplexHash<U>, U: Unit> IOPattern<H, U> {
         Self::from_string(self.io + SEP_BYTE + &format!("A{}", count) + label)
     }
 
+    /// Squeeze `count` native elements.
     pub fn squeeze(self, count: usize, label: &str) -> Self {
         assert!(count > 0, "Count must be positive");
         assert!(!label.contains(SEP_BYTE));
@@ -104,14 +103,17 @@ impl<H: DuplexHash<U>, U: Unit> IOPattern<H, U> {
         Self::from_string(self.io + SEP_BYTE + &format!("S{}", count) + label)
     }
 
+    /// Ratchet the state.
     pub fn ratchet(self) -> Self {
         Self::from_string(self.io + SEP_BYTE + "R")
     }
 
+    /// Return the IO Pattern as bytes.
     pub fn as_bytes(&self) -> &[u8] {
         self.io.as_bytes()
     }
 
+    /// Parse the givern IO Pattern into a sequence of [`Op`]'s.
     pub(crate) fn finalize(&self) -> VecDeque<Op> {
         // Guaranteed to succeed as instances are all valid iopatterns
         Self::parse_io(self.io.as_bytes())
@@ -173,10 +175,12 @@ impl<H: DuplexHash<U>, U: Unit> IOPattern<H, U> {
         }
     }
 
+    /// Create an [`crate::Arthur`] instance from the IO Pattern.
     pub fn to_arthur(&self) -> crate::Arthur<H, U, crate::DefaultRng> {
         crate::Arthur::new(self, crate::DefaultRng::default())
     }
 
+    /// Create a [`crate::Merlin`] instance from the IO Pattern and the protocol transcript (bytes).
     pub fn to_merlin<'a>(&self, transcript: &'a [u8]) -> crate::Merlin<'a, H, U> {
         crate::Merlin::<H, U>::new(self, transcript)
     }

src/lib.rs

@@ -22,11 +22,17 @@
 //! - **Private randomness generation**.
 //! It is vital to avoid providing two different challenges for the same prover message. We do our best to avoid it by tying down the prover randomness to the protocol transcript, without making the proof deterministic.
 //!
-//! # Intuition
+//! # Overview
+//!
+//! The library does three things:
+//!
+//! - Assist in the construction of a protocol transcript for a public-coin zero-knowledge proof ([Arthur]),
+//! - Assist in the deserialization and verification of a public-coin protocol ([Merlin]).
 //!
 //! The basic idea behind Nimue is that prover and verifier "commit" to the protocol before running the actual protocol.
-//! This preprocessing step, where the input/output of the prover, generates an "IV" that is used to initialize the hash function for the Fiat-Shamir heuristic.
-//! From here, prover just proceeds with concatenation, without ever worrying
+//! They a string encoding the sequence of messages sent from the prover and the verifier (the [IOPattern]), which is used as an  "IV" to initialize the hash function for the Fiat-Shamir heuristic.
+//!
+//! There are prover just proceeds with concatenation, without ever worrying
 //! about encoding length and special flags to embed in the hash function.
 //! This allows for
 //! better preprocessing,
@@ -48,7 +54,7 @@
 //! An [`IOPattern`] is a UTF8-encoded string wrapper. Absorptions are denoted as `format!(A{}, length)` and
 //! squeezes as `format!(S{}, length)`. A label is added at the end of the string, meant to describe the *type* and
 //! *the variable* as used in the protocol. Operations are separated by a NULL byte and therefore labels cannot contain
-//! NULL bytes themselves, nor start with an ASCII digit.x
+//! NULL bytes themselves, nor start with an ASCII digit.
 //!
 //!
 //! # Protocol transcripts

src/plugins/ark/mod.rs

@@ -1,8 +1,59 @@
 //! This module contains utilities for working with Arkworks types
 //! and aid in the Fiat-Shamir heuristic for protocols dealing with
 //! field elements and group elements.
-
-/// Common utilities for adding public elements to the protocol transcript.
+//!
+//! # Examples
+//!
+//! Here's a protocol that does Fiat-Shamir without caring about the hash function used
+//! or the serialization format.
+//!
+//! ```rust
+//! use ark_ec::CurveGroup;
+//! use ark_std::UniformRand;
+//! use nimue::{IOPattern, Arthur, DuplexHash, ProofResult};
+//! use nimue::plugins::ark::*;
+//!
+//! fn prove<G>(
+//!     arthur: &mut Arthur,
+//!     x: G::ScalarField,
+//! ) -> ProofResult<&[u8]>
+//! where
+//!     G: CurveGroup,
+//!     Arthur: GroupWriter<G> + FieldChallenges<G::ScalarField>,
+//! {
+//!     let k = G::ScalarField::rand(arthur.rng());
+//!     arthur.add_points(&[G::generator() * k])?;
+//!     let [c] = arthur.challenge_scalars()?;
+//!     arthur.add_scalars(&[k + c * x])?;
+//!     Ok(arthur.transcript())
+//! }
+//! ```
+//! The type constraint on [`crate::Arthur`] hints the compiler that we are going to be absorbing elements from the group `G` and squeezing challenges in the scalar field `G::ScalarField`. Similarly, we could have been squeezing out bytes.
+//!
+//! ```rust
+//! # use ark_ec::CurveGroup;
+//! # use ark_std::UniformRand;
+//! # use ark_ff::PrimeField;
+//! # use nimue::{IOPattern, Arthur, DuplexHash, ProofResult};
+//! # use nimue::plugins::ark::*;
+//!
+//! fn prove<G>(
+//!     arthur: &mut Arthur,
+//!     x: G::ScalarField,
+//! ) -> ProofResult<&[u8]>
+//! where
+//!     G: CurveGroup,
+//!     Arthur: GroupWriter<G> + ByteChallenges,
+//! {
+//!     let k = G::ScalarField::rand(arthur.rng());
+//!     arthur.add_points(&[G::generator() * k])?;
+//!     let c_bytes = arthur.challenge_bytes::<16>()?;
+//!     let c = G::ScalarField::from_le_bytes_mod_order(&c_bytes);
+//!     arthur.add_scalars(&[k + c * x])?;
+//!     Ok(arthur.transcript())
+//! }
+//! ```
+/// Add public elements (field or group elements) to the protocol transcript.
 mod common;
 /// IO Pattern utilities.
 mod iopattern;

src/plugins/ark/poseidon.rs

@@ -2,10 +2,10 @@ use ark_ff::PrimeField;
 
 use crate::hash::sponge::Sponge;
 use crate::hash::Unit;
+use crate::hash::index::impl_indexing;
 
 #[derive(Clone)]
 pub struct PoseidonSponge<F: PrimeField, const R: usize, const N: usize> {
-
     /// Number of rounds in a full-round operation.
     pub full_rounds: usize,
     /// Number of rounds in a partial-round operation.
@@ -18,11 +18,14 @@ pub struct PoseidonSponge<F: PrimeField, const R: usize, const N: usize> {
     /// Maximally Distance Separating (MDS) Matrix.
     pub mds: &'static [[F; N]],
 
-    // Sponge State
-    /// Current sponge's state (current elements in the permutation block)
+    /// Sponge state
     pub state: [F; N],
 }
 
+// Indexing over PoseidonSponge is just forwarded to indexing on the state.
+impl_indexing!(PoseidonSponge, state, Output = F, Params = [F: PrimeField], Constants = [R, N]);
+
+
 impl<F: PrimeField, const R: usize, const N: usize> PoseidonSponge<F, R, N> {
     fn apply_s_box(&self, state: &mut [F], is_full_round: bool) {
         // Full rounds apply the S Box (x^alpha) to every element of state
@@ -57,7 +60,6 @@ impl<F: PrimeField, const R: usize, const N: usize> PoseidonSponge<F, R, N> {
     }
 }
 
-crate::hash::index::impl_indexing!(PoseidonSponge, state, Output = F, Params = [F: PrimeField], Constants = [R, N]);
 
 impl<F: PrimeField, const R: usize, const N: usize> zeroize::Zeroize for PoseidonSponge<F, R, N> {
     fn zeroize(&mut self) {

src/plugins/mod.rs

@@ -23,4 +23,4 @@ pub(super) const fn bytes_modp(modulus_bits: u32) -> usize {
 
 /// Unit-tests for inter-operability among libraries.
 #[cfg(all(test, feature = "ark", feature = "group"))]
-mod tests;
+mod tests;

src/tests.rs

@@ -3,7 +3,9 @@ use crate::hash::legacy::DigestBridge;
 use crate::{Arthur, ByteChallenges, ByteWriter, DuplexHash, IOPattern, Safe};
 
 type Sha2 = DigestBridge<sha2::Sha256>;
-type Blake2 = DigestBridge<blake2::Blake2b512>;
+type Blake2b512 = DigestBridge<blake2::Blake2b512>;
+type Blake2s256 = DigestBridge<blake2::Blake2s256>;
+
 
 /// How should a protocol without IOPattern be handled?
 #[test]
@@ -165,7 +167,8 @@ fn test_streaming_sha2() {
 
 #[test]
 fn test_streaming_blake2() {
-    test_streaming_absorb_and_squeeze::<Blake2>();
+    test_streaming_absorb_and_squeeze::<Blake2b512>();
+    test_streaming_absorb_and_squeeze::<Blake2s256>();
 }
 
 #[test]