feat(crypto): add crate docs & missing fn docs sections

Cargo.toml

@@ -1,12 +1,10 @@
 [workspace]
 members = ["lib/crypto"]
-
 # Explicitly set the resolver to version 2, which is the default for packages
 # with edition >= 2021.
 # https://doc.rust-lang.org/edition-guide/rust-2021/default-cargo-resolver.html
 resolver = "2"
 
-
 [workspace.package]
 authors = ["OpenZeppelin"]
 edition = "2021"

lib/crypto/Cargo.toml

@@ -1,10 +1,12 @@
 [package]
 name = "crypto"
-version = "0.1.0"
+categories = ["cryptography", "algorithms", "no-std", "wasm"]
+description = "Cryptography Utilities"
 edition.workspace = true
-license.workspace = true
 keywords.workspace = true
-description = "Cryptography Utilities"
+license.workspace = true
+repository.workspace = true
+version = "0.1.0"
 
 [dependencies]
 alloy-primitives = { version = "0.6.4", default-features = false }

lib/crypto/src/lib.rs

@@ -1,3 +1,6 @@
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs, unreachable_pub, rust_2021_compatibility)]
+#![warn(clippy::all, clippy::pedantic)]
 #![cfg_attr(not(test), no_main, no_std)]
 extern crate alloc;
 

lib/crypto/src/merkle.rs

@@ -10,6 +10,7 @@
 //! of internal nodes in the Merkle tree could be reinterpreted as a
 //! leaf value. OpenZeppelin's JavaScript library generates Merkle trees
 //! that are safe against this attack out of the box.
+//!
 use alloc::vec::Vec;
 
 type Bytes32 = [u8; 32];
@@ -19,8 +20,9 @@ type Bytes32 = [u8; 32];
 /// `Hasher` serves as an adapter for consumers to use `verify` with the
 /// hashing algorithm of their choice.
 pub trait Hasher {
+ /// The type of a value resulting from hashing some data.
  type Hash: Copy;
-
+ /// Hash arbitrary data resulting in a value of type `Self::Hash`.
  fn hash(&mut self, data: &[u8]) -> Self::Hash;
 }
 
@@ -88,6 +90,8 @@ pub fn verify<H: Hasher<Hash = Bytes32>>(
 /// TODO: Once <https://github.com/rust-lang/rust/issues/103765> is resolved,
 /// we should derive `core::error::Error`.
 pub enum MultiProofError {
+ /// The number of leaves and proof members does not match the amount of
+ /// hashes necessary to complete the verification.
  InvalidProofLength,
 }
 
@@ -178,6 +182,15 @@ impl core::fmt::Display for MultiProofError {
 /// verify_multi_proof(&proof, &proof_flags, root, &leaves, Keccak256);
 /// assert!(verification.unwrap());
 /// ```
+///
+/// # Errors
+///
+/// Will return `Err` if the arguments are well-formed, but invalid.
+///
+/// # Panics
+///
+/// Will panic with an out-of-bounds error if the proof is malicious. See
+/// <https://github.com/OpenZeppelin/openzeppelin-contracts/security/advisories/GHSA-wprv-93r4-jj2p>
 pub fn verify_multi_proof<H: Hasher<Hash = Bytes32>>(
  proof: &[Bytes32],
  proof_flags: &[bool],