0xPolygonMiden · bobbinth · Feb 14, 2024 · Oct 12, 2023 · Oct 19, 2023 · Oct 19, 2023
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,20 @@
+# Documentation available at editorconfig.org
+
+root=true
+
+[*]
+ident_style = space
+ident_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.rs]
+max_line_length = 100
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.yml]
+ident_size = 2
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -4,46 +4,74 @@ on:
     branches:
       - main
   pull_request:
-    types: [opened, repoened, synchronize]
+    types: [opened, reopened, synchronize]
 
 jobs:
-  build:
-    name: Build ${{matrix.toolchain}} on ${{matrix.os}} with ${{matrix.args}}
+  rustfmt:
+    name: rustfmt ${{matrix.toolchain}} on ${{matrix.os}}
     runs-on: ${{matrix.os}}-latest
     strategy:
       fail-fast: false
       matrix:
-        toolchain: [stable, nightly]
+        toolchain: [nightly]
+        os: [ubuntu]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install minimal Rust with rustfmt
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: ${{matrix.toolchain}}
+          components: rustfmt
+          override: true
+      - name: fmt
+        uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --all -- --check
+
+  clippy:
+    name: clippy ${{matrix.toolchain}} on ${{matrix.os}}
+    runs-on: ${{matrix.os}}-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain: [nightly]
         os: [ubuntu]
-        target: [wasm32-unknown-unknown]
-        args: [--no-default-features --target wasm32-unknown-unknown]
     steps:
-      - uses: actions/checkout@main
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
-      - name: Install rust
+      - name: Install minimal Rust with clippy
         uses: actions-rs/toolchain@v1
         with:
+          profile: minimal
           toolchain: ${{matrix.toolchain}}
+          components: clippy
           override: true
-      - run: rustup target add ${{matrix.target}}
-      - name: Test
+      - name: Clippy
         uses: actions-rs/cargo@v1
         with:
-          command: build
-          args: ${{matrix.args}}
+          command: clippy
+          args: --all-targets -- -D clippy::all -D warnings
+      - name: Clippy all features
+        uses: actions-rs/cargo@v1
+        with:
+          command: clippy
+          args: --all-targets --all-features -- -D clippy::all -D warnings
 
   test:
-    name: Test ${{matrix.toolchain}} on ${{matrix.os}} with ${{matrix.features}}
+    name: test ${{matrix.toolchain}} on ${{matrix.os}} with ${{matrix.features}}
     runs-on: ${{matrix.os}}-latest
     strategy:
       fail-fast: false
       matrix:
         toolchain: [stable, nightly]
         os: [ubuntu]
-        features: ["--features default,std,serde", --no-default-features]
+        features: ["--features default,serde", --no-default-features]
+    timeout-minutes: 30
     steps:
-      - uses: actions/checkout@main
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
       - name: Install rust
@@ -57,45 +85,49 @@ jobs:
           command: test
           args: ${{matrix.features}}
 
-  clippy:
-    name: Clippy with ${{matrix.features}}
+  no-std:
+    name: build ${{matrix.toolchain}} no-std for wasm32-unknown-unknown
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        features: ["--features default,std,serde", --no-default-features]
+        toolchain: [stable, nightly]
     steps:
-      - uses: actions/checkout@main
+      - uses: actions/checkout@v4
         with:
           submodules: recursive
-      - name: Install minimal nightly with clippy
+      - name: Install rust
         uses: actions-rs/toolchain@v1
         with:
-          profile: minimal
-          toolchain: nightly
-          components: clippy
+          toolchain: ${{matrix.toolchain}}
           override: true
-      - name: Clippy
+      - run: rustup target add wasm32-unknown-unknown
+      - name: Build
         uses: actions-rs/cargo@v1
         with:
-          command: clippy
-          args: --all ${{matrix.features}} -- -D clippy::all -D warnings
+          command: build
+          args: --no-default-features --target wasm32-unknown-unknown
 
-  rustfmt:
-    name: rustfmt
+  docs:
+    name: Verify the docs on ${{matrix.toolchain}}
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain: [stable]
     steps:
-      - uses: actions/checkout@main
-      - name: Install minimal stable with rustfmt
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install rust
         uses: actions-rs/toolchain@v1
         with:
-          profile: minimal
-          toolchain: stable
-          components: rustfmt
+          toolchain: ${{matrix.toolchain}}
           override: true
-
-      - name: rustfmt
+      - name: Check docs
         uses: actions-rs/cargo@v1
+        env:
+          RUSTDOCFLAGS: -D warnings
         with:
-          command: fmt
-          args: --all -- --check
+          command: doc
+          args: --verbose --all-features --keep-going
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,6 @@ Cargo.lock
 
 # Generated by cmake
 cmake-build-*
+
+# VS Code
+.vscode/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,15 @@
+## 0.8.0 (2024-02-14)
+
+* Implemented the `PartialMmr` data structure (#195).
+* Implemented RPX hash function (#201).
+* Added `FeltRng` and `RpoRandomCoin` (#237).
+* Accelerated RPO/RPX hash functions using AVX512 instructions (#234).
+* Added `inner_nodes()` method to `PartialMmr` (#238).
+* Improved `PartialMmr::apply_delta()` (#242).
+* Refactored `SimpleSmt` struct (#245).
+* Replaced `TieredSmt` struct with `Smt` struct (#254, #277).
+* Updated Winterfell dependency to v0.8 (#275).
+
 ## 0.7.1 (2023-10-10)
 
 * Fixed RPO Falcon signature build on Windows.
@@ -12,7 +24,6 @@
 * Implemented benchmarking for `TieredSmt` (#182).
 * Added more leaf traversal methods for `MerkleStore` (#185).
 * Added SVE acceleration for RPO hash function (#189).
-* Implemented the `PartialMmr` datastructure (#195).
 
 ## 0.6.0 (2023-06-25)
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -72,7 +72,7 @@ For example, a new change to the AIR crate might have the following message: `fe
     // ================================================================================
     ```
 
-- [Rustfmt](https://github.com/rust-lang/rustfmt) and [Clippy](https://github.com/rust-lang/rust-clippy) linting is included in CI pipeline. Anyways it's prefferable to run linting locally before push:
+- [Rustfmt](https://github.com/rust-lang/rustfmt) and [Clippy](https://github.com/rust-lang/rust-clippy) linting is included in CI pipeline. Anyways it's preferable to run linting locally before push:
     ```
     cargo fix --allow-staged --allow-dirty --all-targets --all-features; cargo fmt; cargo clippy --workspace --all-targets --all-features -- -D warnings
     ```

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,16 +1,16 @@
 [package]
 name = "miden-crypto"
-version = "0.7.1"
+version = "0.8.0"
 description = "Miden Cryptographic primitives"
 authors = ["miden contributors"]
 readme = "README.md"
 license = "MIT"
 repository = "https://github.com/0xPolygonMiden/crypto"
-documentation = "https://docs.rs/miden-crypto/0.7.1"
+documentation = "https://docs.rs/miden-crypto/0.8.0"
 categories = ["cryptography", "no-std"]
 keywords = ["miden", "crypto", "hash", "merkle"]
 edition = "2021"
-rust-version = "1.73"
+rust-version = "1.75"
 
 [[bin]]
 name = "miden-crypto"
@@ -35,23 +35,30 @@ harness = false
 default = ["std"]
 executable = ["dep:clap", "dep:rand_utils", "std"]
 serde = ["dep:serde", "serde?/alloc", "winter_math/serde"]
-std = ["blake3/std", "dep:cc", "dep:libc", "winter_crypto/std", "winter_math/std", "winter_utils/std"]
-sve = ["std"]
+std = [
+    "blake3/std",
+    "dep:cc",
+    "dep:libc",
+    "winter_crypto/std",
+    "winter_math/std",
+    "winter_utils/std",
+]
 
 [dependencies]
 blake3 = { version = "1.5", default-features = false }
-clap = { version = "4.4", features = ["derive"], optional = true }
-libc = { version =  "0.2", default-features = false, optional = true }
-rand_utils = { version = "0.6", package = "winter-rand-utils", optional = true }
-serde = { version = "1.0", features = [ "derive" ], default-features = false, optional = true }
-winter_crypto = { version = "0.6", package = "winter-crypto", default-features = false }
-winter_math = { version = "0.6", package = "winter-math", default-features = false }
-winter_utils = { version = "0.6", package = "winter-utils", default-features = false }
+clap = { version = "4.5", features = ["derive"], optional = true }
+libc = { version = "0.2", default-features = false, optional = true }
+rand_utils = { version = "0.8", package = "winter-rand-utils", optional = true }
+serde = { version = "1.0", features = ["derive"], default-features = false, optional = true }
+winter_crypto = { version = "0.8", package = "winter-crypto", default-features = false }
+winter_math = { version = "0.8", package = "winter-math", default-features = false }
+winter_utils = { version = "0.8", package = "winter-utils", default-features = false }
 
 [dev-dependencies]
+seq-macro = { version = "0.3" }
 criterion = { version = "0.5", features = ["html_reports"] }
-proptest = "1.3"
-rand_utils = { version = "0.6", package = "winter-rand-utils" }
+proptest = "1.4"
+rand_utils = { version = "0.8", package = "winter-rand-utils" }
 
 [build-dependencies]
 cc = { version = "1.0", features = ["parallel"], optional = true }

diff --git a/README.md b/README.md
@@ -6,6 +6,7 @@ This crate contains cryptographic primitives used in Polygon Miden.
 
 * [BLAKE3](https://github.com/BLAKE3-team/BLAKE3) hash function with 256-bit, 192-bit, or 160-bit output. The 192-bit and 160-bit outputs are obtained by truncating the 256-bit output of the standard BLAKE3.
 * [RPO](https://eprint.iacr.org/2022/1577) hash function with 256-bit output. This hash function is an algebraic hash function suitable for recursive STARKs.
+* [RPX](https://eprint.iacr.org/2023/1045) hash function with 256-bit output. Similar to RPO, this hash function is suitable for recursive STARKs but it is about 2x faster as compared to RPO.
 
 For performance benchmarks of these hash functions and their comparison to other popular hash functions please see [here](./benches/).
 
@@ -16,18 +17,25 @@ For performance benchmarks of these hash functions and their comparison to other
 * `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.
+* `PartialMmr`: a partial view of a Merkle mountain range structure.
 * `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.
+* `Smt`: a Sparse Merkle tree (with compaction at depth 64), mapping 4-element keys to 4-element values.
 
 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 the Miden VM. Currently, these schemes are:
+[DSA 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.
 
 For the above signatures, key generation and signing is available only in the `std` context (see [crate features](#crate-features) below), while signature verification is available in `no_std` context as well.
 
+## Pseudo-Random Element Generator
+[Pseudo random element generator module](./src/rand/) provides a set of traits and data structures that facilitate generating pseudo-random elements in the context of Miden VM and Miden rollup. The module currently includes:
+
+* `FeltRng`: a trait for generating random field elements and random 4 field elements.
+* `RpoRandomCoin`: a struct implementing `FeltRng` as well as the [`RandomCoin`](https://github.com/facebook/winterfell/blob/main/crypto/src/random/mod.rs) trait.
+
 ## Crate features
 This crate can be compiled with the following features:
 
@@ -38,10 +46,16 @@ Both of these features imply the use of [alloc](https://doc.rust-lang.org/alloc/
 
 To compile with `no_std`, disable default features via `--no-default-features` flag.
 
+### AVX2 acceleration
+On platforms with [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) support, RPO and RPX hash function can be accelerated by using the vector processing unit. To enable AVX2 acceleration, the code needs to be compiled with the `avx2` target feature enabled. For example:
+```shell
+RUSTFLAGS="-C target-feature=+avx2" cargo build --release
+```
+
 ### SVE acceleration
-On platforms with [SVE](https://en.wikipedia.org/wiki/AArch64#Scalable_Vector_Extension_(SVE)) support, RPO hash function can be accelerated by using the vector processing unit. To enable SVE acceleration, the code needs to be compiled with the `sve` feature enabled. This feature has an effect only if the platform exposes `target-feature=sve` flag. On some platforms (e.g., Graviton 3), for this flag to be set, the compilation must be done in "native" mode. For example, to enable SVE acceleration on Graviton 3, we can execute the following:
+On platforms with [SVE](https://en.wikipedia.org/wiki/AArch64#Scalable_Vector_Extension_(SVE)) support, RPO and RPX hash function can be accelerated by using the vector processing unit. To enable SVE acceleration, the code needs to be compiled with the `sve` target feature enabled. For example:
 ```shell
-RUSTFLAGS="-C target-cpu=native" cargo build --release --features sve
+ RUSTFLAGS="-C target-feature=+sve" cargo build --release
 ```
 
 ## Testing

diff --git a/benches/README.md b/benches/README.md
@@ -6,6 +6,7 @@ In the Miden VM, we make use of different hash functions. Some of these are "tra
 * **Poseidon** as specified [here](https://eprint.iacr.org/2019/458.pdf) and implemented [here](https://github.com/mir-protocol/plonky2/blob/806b88d7d6e69a30dc0b4775f7ba275c45e8b63b/plonky2/src/hash/poseidon_goldilocks.rs) (but in pure Rust, without vectorized instructions).
 * **Rescue Prime (RP)** as specified [here](https://eprint.iacr.org/2020/1143) and implemented [here](https://github.com/novifinancial/winterfell/blob/46dce1adf0/crypto/src/hash/rescue/rp64_256/mod.rs).
 * **Rescue Prime Optimized (RPO)** as specified [here](https://eprint.iacr.org/2022/1577) and implemented in this crate.
+* **Rescue Prime Extended (RPX)** a variant of the [xHash](https://eprint.iacr.org/2023/1045) hash function as implemented in this crate.
 
 ## Comparison and Instructions
 
@@ -15,28 +16,31 @@ The second scenario is that of sequential hashing where we take a sequence of le
 
 #### Scenario 1: 2-to-1 hashing `h(a,b)`
 
-| Function            | BLAKE3 | SHA3    | Poseidon  | Rp64_256  | RPO_256 |
-| ------------------- | ------ | --------| --------- | --------- | ------- |
-| Apple M1 Pro        | 80 ns  | 245 ns  |  1.5 us   |  9.1 us   | 5.4 us  |
-| Apple M2            | 76 ns  | 233 ns  |  1.3 us   |  7.9 us   | 5.0 us  |
-| Amazon Graviton 3   | 108 ns |         |           |           | 5.3 us  |
-| AMD Ryzen 9 5950X   | 64 ns  | 273 ns  |  1.2 us   |  9.1 us   | 5.5 us  |
-| Intel Core i5-8279U | 80 ns  |         |           |           | 8.7 us  |
-| Intel Xeon 8375C    | 67 ns  |         |           |           | 8.2 us  |
+| Function            | BLAKE3 | SHA3    | Poseidon  | Rp64_256  | RPO_256 | RPX_256 |
+| ------------------- | ------ | ------- | --------- | --------- | ------- | ------- |
+| Apple M1 Pro        | 76 ns  | 245 ns  |  1.5 µs   |  9.1 µs   | 5.2 µs  | 2.7 µs  |
+| Apple M2 Max        | 71 ns  | 233 ns  |  1.3 µs   |  7.9 µs   | 4.6 µs  | 2.4 µs  |
+| Amazon Graviton 3   | 108 ns |         |           |           | 5.3 µs  | 3.1 µs  |
+| AMD Ryzen 9 5950X   | 64 ns  | 273 ns  |  1.2 µs   |  9.1 µs   | 5.5 µs  |         |
+| AMD EPYC 9R14       | 83 ns  |         |           |           | 4.3 µs  | 2.4 µs  |
+| Intel Core i5-8279U | 68 ns  | 536 ns  |  2.0 µs   |  13.6 µs  | 8.5 µs  | 4.4 µs  |
+| Intel Xeon 8375C    | 67 ns  |         |           |           | 8.2 µs  |         |
 
 #### Scenario 2: Sequential hashing of 100 elements `h([a_0,...,a_99])`
 
-| Function            | BLAKE3 | SHA3    | Poseidon  | Rp64_256  | RPO_256 |
-| ------------------- | -------| ------- | --------- | --------- | ------- |
-| Apple M1 Pro        | 1.0 us | 1.5 us  |  19.4 us  |   118 us  | 70 us   |
-| Apple M2            | 1.0 us | 1.5 us  |  17.4 us  |   103 us  | 65 us   |
-| Amazon Graviton 3   | 1.4 us |         |           |           | 69 us   |
-| AMD Ryzen 9 5950X   | 0.8 us | 1.7 us  |  15.7 us  |   120 us  | 72 us   |
-| Intel Core i5-8279U | 1.0 us |         |           |           | 116 us  |
-| Intel Xeon 8375C    | 0.8 ns |         |           |           | 110 us  |
+| Function            | BLAKE3 | SHA3    | Poseidon  | Rp64_256  | RPO_256 | RPX_256 |
+| ------------------- | -------| ------- | --------- | --------- | ------- | ------- |
+| Apple M1 Pro        | 1.0 µs | 1.5 µs  |  19.4 µs  |   118 µs  | 69 µs   | 35 µs   |
+| Apple M2 Max        | 0.9 µs | 1.5 µs  |  17.4 µs  |   103 µs  | 60 µs   | 31 µs   |
+| Amazon Graviton 3   | 1.4 µs |         |           |           | 69 µs   | 41 µs   |
+| AMD Ryzen 9 5950X   | 0.8 µs | 1.7 µs  |  15.7 µs  |   120 µs  | 72 µs   |         |
+| AMD EPYC 9R14       | 0.9 µs |         |           |           | 56 µs   | 32 µs   |
+| Intel Core i5-8279U | 0.9 µs |         |           |           | 107 µs  | 56 µs   |
+| Intel Xeon 8375C    | 0.8 µs |         |           |           | 110 µs  |         |
 
 Notes:
-- On Graviton 3, RPO256 is run with SVE acceleration enabled.
+- On Graviton 3, RPO256 and RPX256 are run with SVE acceleration enabled.
+- On AMD EPYC 9R14, RPO256 and RPX256 are run with AVX2 acceleration enabled.
 
 ### Instructions
 Before you can run the benchmarks, you'll need to make sure you have Rust [installed](https://www.rust-lang.org/tools/install). After that, to run the benchmarks for RPO and BLAKE3, clone the current repository, and from the root directory of the repo run the following: