Auditing uses of unsafe (#852)

* Replace unsafe NonZero with safe alternative, document merkle unsafe

- sparse_path.rs: Replace unsafe NonZero::new_unchecked with safe
  NonZero::new().expect(). Micro-benchmarks show no performance
  difference between safe and unsafe versions (both ~175ps).

- merkle_tree.rs: Add performance documentation explaining why unsafe
  code is kept. Benchmarks at 4K+ leaves show ~2-2.5% improvement
  (65K leaves: unsafe=67.17ms vs safe=68.27ms).

- Add sparse_path.rs benchmark suite for future regression testing.

- Add init_vector safe alternative in utils/mod.rs.

- Extend merkle benchmarks to 65K leaves for scale testing.

* Evaluate remaining unsafe code, add benchmarks and documentation

- Add transpose benchmark showing 31% perf improvement from uninit_vector
- Expand SAFETY comments in digest.rs:digests_as_bytes explaining
  repr(transparent) layout guarantees
- Expand SAFETY comments in empty_roots.rs:empty_hashes documenting
  bounds correctness and const fn requirement
- Add performance documentation to transpose_slice
- Update unsafe-evaluation.prose to cover all remaining unsafe uses

* Use MaybeUninit vector init helpers

* Bump MSRV to 1.93

* Fix large forest entries regression and add seed

* Fix Merkle tree unsafe usage and document invariants

* Avoid recursion in large forest iterator and fix MerkleTree reads

* Fix empty history iteration ordering

Author: huitseeker

Cargo.toml

@@ -10,7 +10,7 @@ edition      = "2024"
 keywords     = ["crypto", "hash", "merkle", "miden"]
 license      = "MIT OR Apache-2.0"
 repository   = "https://github.com/0xMiden/crypto"
-rust-version = "1.90"
+rust-version = "1.93"
 version      = "0.23.0"
 
 [workspace.dependencies]

miden-crypto/Cargo.toml

@@ -69,6 +69,16 @@ harness           = false
 name              = "rand"
 required-features = ["std"]
 
+[[bench]]
+harness           = false
+name              = "sparse_path"
+required-features = ["std"]
+
+[[bench]]
+harness           = false
+name              = "transpose"
+required-features = ["std"]
+
 [features]
 concurrent = ["dep:rayon", "p3-maybe-rayon/parallel", "p3-miden-prover/parallel", "p3-util/parallel", "std"]
 default    = ["concurrent", "std"]

miden-crypto/benches/merkle.rs

@@ -22,7 +22,7 @@ use common::{
 benchmark_multi!(
     merkle_tree_construction,
     "merkle_tree_construction",
-    &[4, 8, 16, 32, 64, 128, 256],
+    &[4, 8, 16, 32, 64, 128, 256, 1024, 4096, 16384, 65536],
     |b: &mut Bencher<'_>, &num_leaves: &usize| {
         b.iter_batched(
             || generate_words_pattern(num_leaves, WordPattern::Random),
@@ -38,7 +38,7 @@ benchmark_multi!(
 benchmark_multi!(
     balanced_merkle_even,
     "balanced-merkle-even",
-    &[4, 8, 16, 32, 64, 128, 256],
+    &[4, 8, 16, 32, 64, 128, 256, 1024, 4096, 16384, 65536],
     |b: &mut Bencher<'_>, num_leaves: &usize| {
         b.iter_batched(
             || {

miden-crypto/benches/sparse_path.rs

@@ -0,0 +1,235 @@
+//! SparseMerklePath operation benchmarks.
+//!
+//! This module benchmarks operations on SparseMerklePath, with a focus on
+//! the NonZero construction pattern used in path_depth_iter at line 446.
+
+use std::hint;
+
+use criterion::{Bencher, Criterion, criterion_group, criterion_main};
+use miden_crypto::{
+    Felt, Word,
+    merkle::{
+        MerklePath, MerkleTree, NodeIndex,
+        smt::{LeafIndex, SimpleSmt},
+    },
+};
+
+mod common;
+use common::{config::*, data::*};
+
+// === SparseMerklePath Construction Benchmarks ===
+
+benchmark_multi!(
+    sparse_path_from_sized_iter,
+    "sparse_path_from_sized_iter",
+    &[8, 12, 16],
+    |b: &mut Bencher<'_>, &depth: &usize| {
+        b.iter_batched(
+            || generate_words_pattern(1usize << depth, WordPattern::Random),
+            |leaves| {
+                let tree = MerkleTree::new(hint::black_box(leaves)).unwrap();
+                let path = tree.get_path(NodeIndex::new(depth as u8, 0).unwrap()).unwrap();
+                let _sparse_path = miden_crypto::merkle::SparseMerklePath::from_sized_iter(path);
+            },
+            criterion::BatchSize::SmallInput,
+        );
+    }
+);
+
+// === NonZero Construction Pattern Benchmarks ===
+// Focus on line 446: unsafe { NonZero::new_unchecked(depth) }
+// We benchmark iteration which exercises this code path
+
+benchmark_with_setup_data!(
+    sparse_path_iteration_full,
+    DEFAULT_MEASUREMENT_TIME,
+    DEFAULT_SAMPLE_SIZE,
+    "sparse_path_iteration_full",
+    || {
+        // Create a SparseMerklePath at depth 16
+        let leaves = generate_words_pattern(1 << 16, WordPattern::Random);
+        let tree = MerkleTree::new(leaves).unwrap();
+        let path = tree.get_path(NodeIndex::new(16, 0).unwrap()).unwrap();
+        miden_crypto::merkle::SparseMerklePath::from_sized_iter(path).unwrap()
+    },
+    |b: &mut Bencher<'_>, sparse_path: &miden_crypto::merkle::SparseMerklePath| {
+        b.iter(|| {
+            let _count: Vec<_> = hint::black_box(sparse_path.iter()).collect();
+        });
+    }
+);
+
+// === Comparison with Regular MerklePath ===
+
+benchmark_with_setup_data!(
+    compare_path_iteration,
+    DEFAULT_MEASUREMENT_TIME,
+    DEFAULT_SAMPLE_SIZE,
+    "compare_path_iteration",
+    || {
+        let leaves = generate_words_merkle_std(256);
+        let tree = MerkleTree::new(&leaves).unwrap();
+        let merkle_path = tree.get_path(NodeIndex::new(8, 128).unwrap()).unwrap();
+        let sparse_path =
+            miden_crypto::merkle::SparseMerklePath::from_sized_iter(merkle_path.clone()).unwrap();
+        (merkle_path, sparse_path)
+    },
+    |b: &mut Bencher<'_>,
+     (merkle_path, sparse_path): &(MerklePath, miden_crypto::merkle::SparseMerklePath)| {
+        b.iter(|| {
+            let merkle_nodes: Vec<_> = hint::black_box(merkle_path.iter()).collect();
+            let sparse_nodes: Vec<_> = hint::black_box(sparse_path.iter()).collect();
+            // Ensure both iterators produce the same number of nodes
+            assert_eq!(merkle_nodes.len(), sparse_nodes.len());
+        });
+    }
+);
+
+// === SparseMerklePath with Empty Nodes ===
+
+benchmark_with_setup_data!(
+    sparse_path_with_empty_nodes,
+    DEFAULT_MEASUREMENT_TIME,
+    DEFAULT_SAMPLE_SIZE,
+    "sparse_path_with_empty_nodes",
+    || {
+        // Create a SimpleSmt which will have many empty nodes
+        let mut tree = SimpleSmt::new().unwrap();
+        let mut indices = Vec::new();
+        let mut values = Vec::new();
+
+        // Insert a few sparse entries
+        for i in [0u64, 100, 500, 1000] {
+            let leaf_idx = LeafIndex::new(i).unwrap();
+            let value = Word::new([Felt::new(i), Felt::new(i), Felt::new(i), Felt::new(i)]);
+            tree.insert(leaf_idx, value);
+            indices.push(i);
+            values.push(value);
+        }
+
+        (tree, indices, values)
+    },
+    |b: &mut Bencher<'_>, (tree, indices, values): &(SimpleSmt<10>, Vec<u64>, Vec<Word>)| {
+        b.iter(|| {
+            for (idx, _val) in indices.iter().zip(values.iter()) {
+                let leaf_idx = LeafIndex::new(*idx).unwrap();
+                let proof = tree.open(&leaf_idx);
+                let _sparse = hint::black_box(
+                    miden_crypto::merkle::SparseMerklePath::from_sized_iter(proof.path.into_iter())
+                        .unwrap(),
+                );
+            }
+        });
+    }
+);
+
+// === at_depth Operation Benchmark ===
+
+benchmark_with_setup_data!(
+    sparse_path_at_depth,
+    DEFAULT_MEASUREMENT_TIME,
+    DEFAULT_SAMPLE_SIZE,
+    "sparse_path_at_depth",
+    || {
+        let leaves = generate_words_merkle_std(256);
+        let tree = MerkleTree::new(&leaves).unwrap();
+        let path = tree.get_path(NodeIndex::new(8, 128).unwrap()).unwrap();
+        let sparse_path = miden_crypto::merkle::SparseMerklePath::from_sized_iter(path).unwrap();
+        (sparse_path, 8u8)
+    },
+    |b: &mut Bencher<'_>, (sparse_path, depth): &(miden_crypto::merkle::SparseMerklePath, u8)| {
+        b.iter(|| {
+            for d in 1..=*depth {
+                let nz = core::num::NonZero::new(d).unwrap();
+                let _node = hint::black_box(sparse_path.at_depth(nz).unwrap());
+            }
+        });
+    }
+);
+
+// === Conversion Benchmarks ===
+
+benchmark_with_setup_data!(
+    merkle_to_sparse_conversion,
+    DEFAULT_MEASUREMENT_TIME,
+    DEFAULT_SAMPLE_SIZE,
+    "merkle_to_sparse_conversion",
+    || {
+        let leaves = generate_words_merkle_std(256);
+        let tree = MerkleTree::new(&leaves).unwrap();
+        tree.get_path(NodeIndex::new(8, 128).unwrap()).unwrap()
+    },
+    |b: &mut Bencher<'_>, path: &MerklePath| {
+        b.iter(|| {
+            let _sparse = hint::black_box(
+                miden_crypto::merkle::SparseMerklePath::try_from(hint::black_box(path.clone()))
+                    .unwrap(),
+            );
+        });
+    }
+);
+
+benchmark_with_setup_data!(
+    sparse_to_merkle_conversion,
+    DEFAULT_MEASUREMENT_TIME,
+    DEFAULT_SAMPLE_SIZE,
+    "sparse_to_merkle_conversion",
+    || {
+        let leaves = generate_words_merkle_std(256);
+        let tree = MerkleTree::new(&leaves).unwrap();
+        let path = tree.get_path(NodeIndex::new(8, 128).unwrap()).unwrap();
+        miden_crypto::merkle::SparseMerklePath::from_sized_iter(path).unwrap()
+    },
+    |b: &mut Bencher<'_>, sparse_path: &miden_crypto::merkle::SparseMerklePath| {
+        b.iter(|| {
+            let _merkle: MerklePath = hint::black_box(sparse_path.clone().into());
+        });
+    }
+);
+
+// === Micro-benchmark: NonZero construction pattern comparison ===
+
+fn nonzero_safe_vs_unsafe(c: &mut Criterion) {
+    let depths: Vec<u8> = (1u8..=64u8).collect();
+    let mut group = c.benchmark_group("nonzero_construction");
+    group.measurement_time(DEFAULT_MEASUREMENT_TIME);
+    group.sample_size(DEFAULT_SAMPLE_SIZE);
+
+    // Safe construction
+    group.bench_function("safe", |b| {
+        b.iter(|| {
+            for &depth in &depths {
+                let _nz = core::num::NonZero::new(depth);
+            }
+        })
+    });
+
+    // Unsafe construction (current code at line 446)
+    group.bench_function("unsafe", |b| {
+        b.iter(|| {
+            for &depth in &depths {
+                // SAFETY: In the actual code, depth comes from RangeInclusive<1, _>
+                // which guarantees depth >= 1
+                let _nz = unsafe { core::num::NonZero::new_unchecked(depth) };
+            }
+        })
+    });
+
+    group.finish();
+}
+
+// === Benchmark Group Definition ===
+
+criterion_group!(
+    sparse_path_benches,
+    sparse_path_from_sized_iter,
+    sparse_path_iteration_full,
+    compare_path_iteration,
+    sparse_path_with_empty_nodes,
+    sparse_path_at_depth,
+    merkle_to_sparse_conversion,
+    sparse_to_merkle_conversion,
+    nonzero_safe_vs_unsafe,
+);
+
+criterion_main!(sparse_path_benches);

miden-crypto/benches/transpose.rs

@@ -0,0 +1,100 @@
+//! Benchmark for transpose_slice comparing unsafe uninit_vector vs safe init_vector.
+//!
+//! Results at 1024x1024: unsafe=188us, safe=247us (~31% slower with initialization)
+
+use std::hint::black_box;
+
+use criterion::{Bencher, Criterion, criterion_group, criterion_main};
+use miden_crypto::Felt;
+
+mod common;
+
+const MATRIX_SIZES: &[usize] = &[64, 256, 1024];
+
+fn generate_felt_matrix(size: usize) -> Vec<Felt> {
+    (0..(size * size)).map(|i| Felt::new(i as u64)).collect()
+}
+
+/// Unsafe transpose using uninit_vector
+#[expect(clippy::uninit_vec)]
+fn transpose_unsafe<T: Copy + Send + Sync, const N: usize>(source: &[T]) -> Vec<[T; N]> {
+    let row_count = source.len() / N;
+    assert_eq!(row_count * N, source.len());
+
+    let mut result: Vec<[T; N]> = unsafe {
+        let mut vector = Vec::with_capacity(row_count);
+        vector.set_len(row_count);
+        vector
+    };
+
+    result.iter_mut().enumerate().for_each(|(i, element)| {
+        for j in 0..N {
+            element[j] = source[i + j * row_count]
+        }
+    });
+    result
+}
+
+/// Safe transpose using initialized vector
+fn transpose_safe<T: Copy + Default + Send + Sync, const N: usize>(source: &[T]) -> Vec<[T; N]> {
+    let row_count = source.len() / N;
+    assert_eq!(row_count * N, source.len());
+
+    let mut result: Vec<[T; N]> = vec![[T::default(); N]; row_count];
+
+    result.iter_mut().enumerate().for_each(|(i, element)| {
+        for j in 0..N {
+            element[j] = source[i + j * row_count]
+        }
+    });
+    result
+}
+
+benchmark_multi!(
+    transpose_unsafe_bench,
+    "transpose_unsafe",
+    MATRIX_SIZES,
+    |b: &mut Bencher<'_>, &size: &usize| {
+        let data = generate_felt_matrix(size);
+        b.iter(|| {
+            let result: Vec<[Felt; 4]> = transpose_unsafe(black_box(&data));
+            black_box(result);
+        })
+    }
+);
+
+benchmark_multi!(
+    transpose_safe_bench,
+    "transpose_safe",
+    MATRIX_SIZES,
+    |b: &mut Bencher<'_>, &size: &usize| {
+        let data = generate_felt_matrix(size);
+        b.iter(|| {
+            let result: Vec<[Felt; 4]> = transpose_safe(black_box(&data));
+            black_box(result);
+        })
+    }
+);
+
+benchmark_multi!(
+    transpose_library_bench,
+    "transpose_library",
+    MATRIX_SIZES,
+    |b: &mut Bencher<'_>, &size: &usize| {
+        use miden_crypto::utils::transpose_slice;
+        let data = generate_felt_matrix(size);
+        b.iter(|| {
+            let result: Vec<[Felt; 4]> = transpose_slice::<Felt, 4>(black_box(&data));
+            black_box(result);
+        })
+    }
+);
+
+criterion_group!(
+    transpose_benchmarks,
+    transpose_unsafe_bench,
+    transpose_safe_bench,
+    transpose_library_bench,
+);
+
+criterion_main!(transpose_benchmarks);

miden-crypto/proptest-regressions/merkle/smt/large_forest/property_tests.txt

@@ -0,0 +1 @@
+cc abf493f7aece0d6db6c370e3c95651effc9f46f7a2f97e2dccddacfce2afd16d