From 7ddcdc5e39716ffbb3c57e8b2ab0fbc5f247a0b6 Mon Sep 17 00:00:00 2001 From: Bobbin Threadbare Date: Fri, 6 Oct 2023 21:13:42 -0700 Subject: [PATCH] docs: add module descriptions --- .git-blame-ignore-revs | 2 -- README.md | 6 +++--- src/dsa/mod.rs | 2 ++ src/hash/mod.rs | 2 ++ src/lib.rs | 2 +- src/merkle/mod.rs | 2 ++ src/rand/mod.rs | 3 +++ src/utils/mod.rs | 11 +++++++---- 8 files changed, 20 insertions(+), 10 deletions(-) delete mode 100644 .git-blame-ignore-revs create mode 100644 src/rand/mod.rs diff --git a/.git-blame-ignore-revs b/.git-blame-ignore-revs deleted file mode 100644 index a0350b9..0000000 --- a/.git-blame-ignore-revs +++ /dev/null @@ -1,2 +0,0 @@ -# initial run of pre-commit -956e4c6fad779ef15eaa27702b26f05f65d31494 diff --git a/README.md b/README.md index 156a1b0..7ec16b2 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ For performance benchmarks of these hash functions and their comparison to other ## Merkle [Merkle module](./src/merkle/) provides a set of data structures related to Merkle trees. All these data structures are implemented using the RPO hash function described above. The data structures are: -* `Mmr`: a Merkle mountain range structure designed to function as an append-only log. -* `MerkleTree`: a regular fully-balanced binary Merkle tree. The depth of this tree can be at most 64. * `MerkleStore`: a collection of Merkle trees of different heights designed to efficiently store trees with common subtrees. When instantiated with `RecordingMap`, a Merkle store records all accesses to the original data. +* `MerkleTree`: a regular fully-balanced binary Merkle tree. The depth of this tree can be at most 64. +* `Mmr`: a Merkle mountain range structure designed to function as an append-only log. * `PartialMerkleTree`: a partial view of a Merkle tree where some sub-trees may not be known. This is similar to a collection of Merkle paths all resolving to the same root. The length of the paths can be at most 64. * `SimpleSmt`: a Sparse Merkle Tree (with no compaction), mapping 64-bit keys to 4-element values. * `TieredSmt`: a Sparse Merkle tree (with compaction), mapping 4-element keys to 4-element values. @@ -22,7 +22,7 @@ For performance benchmarks of these hash functions and their comparison to other The module also contains additional supporting components such as `NodeIndex`, `MerklePath`, and `MerkleError` to assist with tree indexation, opening proofs, and reporting inconsistent arguments/state. ## Signatures -[DAS module](./src/dsa) provides a set of digital signature schemes supported by default in Miden VM. Currently, these schemes are: +[DAS module](./src/dsa) provides a set of digital signature schemes supported by default in the Miden VM. Currently, these schemes are: * `RPO Falcon512`: a variant of the [Falcon](https://falcon-sign.info/) signature scheme. This variant differs from the standard in that instead of using SHAKE256 hash function in the *hash-to-point* algorithm we use RPO256. This makes the signature more efficient to verify in Miden VM. diff --git a/src/dsa/mod.rs b/src/dsa/mod.rs index 80fb8a8..9c5c0a5 100644 --- a/src/dsa/mod.rs +++ b/src/dsa/mod.rs @@ -1 +1,3 @@ +//! Digital signature schemes supported by default in the Miden VM. + pub mod rpo_falcon512; diff --git a/src/hash/mod.rs b/src/hash/mod.rs index d295cbe..8c87562 100644 --- a/src/hash/mod.rs +++ b/src/hash/mod.rs @@ -1,3 +1,5 @@ +//! Cryptographic hash functions used by the Miden VM and the Miden rollup. + use super::{Felt, FieldElement, StarkField, ONE, ZERO}; pub mod blake; diff --git a/src/lib.rs b/src/lib.rs index ddf146c..0eca3e3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -7,12 +7,12 @@ extern crate alloc; pub mod dsa; pub mod hash; pub mod merkle; +pub mod rand; pub mod utils; // RE-EXPORTS // ================================================================================================ -pub use winter_crypto::{RandomCoin, RandomCoinError}; pub use winter_math::{fields::f64::BaseElement as Felt, FieldElement, StarkField}; // TYPE ALIASES diff --git a/src/merkle/mod.rs b/src/merkle/mod.rs index c4e43ca..839e811 100644 --- a/src/merkle/mod.rs +++ b/src/merkle/mod.rs @@ -1,3 +1,5 @@ +//! Data structures related to Merkle trees based on RPO256 hash function. + use super::{ hash::rpo::{Rpo256, RpoDigest}, utils::collections::{vec, BTreeMap, BTreeSet, KvMap, RecordingMap, TryApplyDiff, Vec}, diff --git a/src/rand/mod.rs b/src/rand/mod.rs new file mode 100644 index 0000000..2633527 --- /dev/null +++ b/src/rand/mod.rs @@ -0,0 +1,3 @@ +//! Pseudo-random element generation. + +pub use winter_crypto::{RandomCoin, RandomCoinError}; diff --git a/src/utils/mod.rs b/src/utils/mod.rs index 7449c89..715eee8 100644 --- a/src/utils/mod.rs +++ b/src/utils/mod.rs @@ -1,3 +1,5 @@ +//! Utilities used in this crate which can also be generally useful downstream. + use super::{utils::string::String, Word}; use core::fmt::{self, Display, Write}; @@ -49,9 +51,10 @@ pub fn bytes_to_hex_string(data: [u8; N]) -> String { s } +/// Defines errors which can occur during parsing of hexadecimal strings. #[derive(Debug)] pub enum HexParseError { - InvalidLength { expected: usize, got: usize }, + InvalidLength { expected: usize, actual: usize }, MissingPrefix, InvalidChar, OutOfRange, @@ -60,8 +63,8 @@ pub enum HexParseError { impl Display for HexParseError { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { match self { - HexParseError::InvalidLength { expected, got } => { - write!(f, "Hex encoded RpoDigest must have length 66, including the 0x prefix. expected {expected} got {got}") + HexParseError::InvalidLength { expected, actual } => { + write!(f, "Hex encoded RpoDigest must have length 66, including the 0x prefix. expected {expected} got {actual}") } HexParseError::MissingPrefix => { write!(f, "Hex encoded RpoDigest must start with 0x prefix") @@ -83,7 +86,7 @@ impl std::error::Error for HexParseError {} pub fn hex_to_bytes(value: &str) -> Result<[u8; N], HexParseError> { let expected: usize = (N * 2) + 2; if value.len() != expected { - return Err(HexParseError::InvalidLength { expected, got: value.len() }); + return Err(HexParseError::InvalidLength { expected, actual: value.len() }); } if !value.starts_with("0x") {