Improve documentation.

README.md

@@ -1,10 +1,14 @@
-Nimue is a library for Fiat-Shamir implementations
-=========
+<img
+    src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/e2/The_Lady_of_the_Lake_by_Speed_Lancelot.jpg/302px-The_Lady_of_the_Lake_by_Speed_Lancelot.jpg?download"
+    align="right"
+    width=33%/>
 
+Nimue: a Fiat-Shamir library
+=========
 
-Nimue is a hash-agnostic library for Fiat-Shamir, built as an extension on the top of the SAFE framework. 
-It provides an API for generating the verifier's and prover's random coins. 
+Nimue is a hash-agnostic library for Fiat-Shamir, built as an extension on the top of the SAFE framework.
+It provides an API for generating the verifier's and prover's random coins.
 
-check out the [documentation](https://mmaker.github.io/nimue/nimue/) and some [`examples/`](https://github.com/mmaker/nimue/tree/main/examples). 
+check out the [documentation](https://mmaker.github.io/nimue/nimue/) and some [`examples/`](https://github.com/mmaker/nimue/tree/main/examples).
 
-** This library has not been externally reviewed yet and shouldn't be considered ready for deployments yet. **
+**This library has not been externally reviewed yet and shouldn't be considered ready for deployments yet.**

examples/bulletproofs.rs

@@ -45,8 +45,9 @@ where
     S: Duplexer,
     G: AffineRepr + Absorbable<S::L>,
     // XXX. ugly.
-    // This allows to absorb also porjective elements.
-    // This condition is always satisfied. How can we fix it?
+    // This allows to absorb also projective elements.
+    // This condition is however always satisfied, but
+    // Rust will only know when these traits are part of Group.
     G::Group: Absorbable<S::L>,
 {
     assert_eq!(witness.0.len(), witness.1.len());
@@ -154,8 +155,8 @@ fn main() {
 
     type H = nimue::DefaultHash;
 
-    let a = [1, 2, 3, 4].iter().map(|&x| F::from(x)).collect::<Vec<_>>();
-    let b = [1, 2, 3, 4].iter().map(|&x| F::from(x)).collect::<Vec<_>>();
+    let a = [1, 2, 3, 4, 5, 6, 7, 8].iter().map(|&x| F::from(x)).collect::<Vec<_>>();
+    let b = [1, 2, 3, 4, 5, 6, 7, 8].iter().map(|&x| F::from(x)).collect::<Vec<_>>();
     let g = (0..a.len())
         .map(|_| G::rand(&mut OsRng))
         .collect::<Vec<_>>();

examples/schnorr.rs

@@ -46,8 +46,6 @@ fn schnorr_proof<S: Duplexer, G: AffineRepr + Absorbable<S::L>>(
     transcript.append_element(&commitment.into_affine())?;
     // Get a challenge over the field Fr.
     let challenge: G::ScalarField = transcript.field_challenge()?;
-    let challenge: G::ScalarField = transcript.field_challenge().expect("hello");
-
 
     let response = k + challenge * sk;
     let proof = (challenge, response);

src/keccak.rs

@@ -1,4 +1,4 @@
-//! A wrapper around the Keccak-f[1600] permutation.
+//! A wrapper around the Keccak-f\[1600\] permutation.
 //!
 //! **Warning**: this function is not SHA3.
 //! Despite internally we use the same permutation,

src/lib.rs

@@ -12,20 +12,20 @@
 //! # Features
 //!
 //! This library is inspired by [Merlin] but is not a drop-in replacement.
-//! Like Merlin, it supports multi-round protocols and domain separation.
-//! Additionally, it addresses some core design limitations of [Merlin]:
-//! - Supports arbitrary hashes, including algebraic.
+//! It supports multi-round protocols and domain separation, and
+//! addresses of Merlin's core design limitations:
+//! - Support for arbitrary hash function, including algebraic hashes.
 //! To build a secure Fiat-Shamir transform, a permutation function is required.
 //! You can choose from SHA3, Poseidon, Anemoi, instantiated over
 //! $\mathbb{F}_{2^8}$ or any large-characteristic field $\mathbb{F}_p$.
-//! - Provides retro-compatibility with Sha2 and MD hashes.
-//! We have a legacy interface for Sha2 that can be easily extended to Merkle-Damgard hashes
-//! and any hash function that satisfies the [`digest::Digest`] trait.
+//! - Retro-compatibility with Sha2 and MD hashes.
+//! We have a legacy interface for Sha2 and Blake2 that can be easily extended to Merkle-Damgard hashes
+//! and, more in general, any hash function that satisfies the [`digest::Digest`] trait.
 //! - Provides an API for preprocessing.
 //! In recursive SNARKs, minimizing the number of invocations of the permutation
-//! while maintaining security is crucial. We offer tools for preprocessing the Transcript (i.e., the state of the Fiat-Shamir transform) to achieve this.
+//! while maintaining security is crucial. We offer tools for preprocessing the Transcript (i.e., the state of the Fiat-Shamir transform) to achieve this goal.
 //!
-//! - Enables secure randomness generation for the prover.
+//! - Secure randomness generation for the prover.
 //! We provide a secure source of randomness for the prover that is bound to the protocol transcript, and seeded by the oeprating system.
 //!
 //! # Protocol Composition

src/merlin.rs

@@ -19,7 +19,7 @@ impl<S: Duplexer> Merlin<S> {
         Self { safe, leftovers }
     }
 
-    /// Absorb a slice of [`Lane`]'s into the sponge.
+    /// Absorb a slice of lanes into the sponge.
     pub fn append(&mut self, input: &[S::L]) -> Result<&mut Self, InvalidTag> {
         self.leftovers.clear();
         self.safe.absorb(input)?;