Re-organize top-level crate exports

README.md

@@ -123,6 +123,10 @@ Messages sealed as one type must be unsealed using the corresponding method, oth
 - `RpoRandomCoin`: a struct implementing `FeltRng` as well as the [`RandomCoin`](https://github.com/facebook/winterfell/blob/main/crypto/src/random/mod.rs) trait using RPO hash function.
 - `RpxRandomCoin`: a struct implementing `FeltRng` as well as the [`RandomCoin`](https://github.com/facebook/winterfell/blob/main/crypto/src/random/mod.rs) trait using RPX hash function.
 
+## STARK proving system
+
+The STARK module exports foundational components for the STARK proving system. It primarily consists of re-exports from the [Plonky3](https://github.com/Plonky3/Plonky3) project with some Miden-specific [adaptations](https://github.com/0xMiden/p3-miden).
+
 ## Make commands
 
 We use `make` to automate building, testing, and other processes. In most cases, `make` commands are wrappers around `cargo` commands with specific arguments. You can view the list of available commands in the [Makefile](Makefile), or run the following command:

miden-crypto/benches/common/data.rs

@@ -31,7 +31,7 @@ use std::iter;
 
 use miden_crypto::{
     Felt, ONE, Word,
-    test_utils::{prng_array, rand_value},
+    rand::test_utils::{prng_array, rand_value},
 };
 
 // === Byte Array Generation ===
@@ -81,11 +81,11 @@ pub fn generate_word(seed: &mut [u8; 32]) -> Word {
 }
 
 /// Generate a generic value from seed using PRNG
-pub fn generate_value<T: miden_crypto::utils::Randomizable + std::fmt::Debug + Clone>(
+pub fn generate_value<T: miden_crypto::rand::Randomizable + std::fmt::Debug + Clone>(
     seed: &mut [u8; 32],
 ) -> T {
     *seed = prng_array(*seed);
-    let value: [T; 1] = miden_crypto::test_utils::prng_array(*seed);
+    let value: [T; 1] = miden_crypto::rand::test_utils::prng_array(*seed);
     value[0].clone()
 }
 

miden-crypto/benches/store.rs

@@ -8,7 +8,7 @@ use miden_crypto::{
         smt::{LeafIndex, SMT_MAX_DEPTH, SimpleSmt},
         store::MerkleStore,
     },
-    test_utils::{rand_array, rand_value},
+    rand::test_utils::{rand_array, rand_value},
 };
 
 /// Since MerkleTree can only be created when a power-of-two number of elements is used, the sample

miden-crypto/src/dsa/falcon512_rpo/math/polynomial.rs

@@ -651,11 +651,12 @@ impl<F: Zeroize> ZeroizeOnDrop for Polynomial<F> {}
 #[cfg(all(test, feature = "std"))]
 mod tests {
     use super::{FalconFelt, N, Polynomial};
+    use crate::rand::test_utils::rand_array;
 
     #[test]
     fn test_negacyclic_reduction() {
-        let coef1: [u8; N] = crate::test_utils::rand_array();
-        let coef2: [u8; N] = crate::test_utils::rand_array();
+        let coef1: [u8; N] = rand_array();
+        let coef2: [u8; N] = rand_array();
 
         let poly1 = Polynomial::new(coef1.iter().map(|&a| FalconFelt::new(a as i16)).collect());
         let poly2 = Polynomial::new(coef2.iter().map(|&a| FalconFelt::new(a as i16)).collect());

miden-crypto/src/hash/algebraic_sponge/mod.rs

@@ -22,18 +22,6 @@ use crate::{BasedVectorSpace, PrimeField64};
 pub(crate) mod poseidon2;
 pub(crate) mod rescue;
 
-// Re-export the main hash function types
-pub use poseidon2::Poseidon2;
-// Re-export P3 integration types for public API
-pub use poseidon2::{
-    Poseidon2Challenger, Poseidon2Compression, Poseidon2Hasher, Poseidon2Permutation256,
-};
-pub use rescue::{
-    Rpo256, Rpx256,
-    rpo::{RpoChallenger, RpoCompression, RpoHasher, RpoPermutation256},
-    rpx::{RpxChallenger, RpxCompression, RpxHasher, RpxPermutation256},
-};
-
 // CONSTANTS
 // ================================================================================================
 

miden-crypto/src/hash/algebraic_sponge/rescue/mod.rs

@@ -16,10 +16,7 @@ mod mds;
 use mds::{MDS, apply_mds};
 
 pub(crate) mod rpo;
-pub use rpo::Rpo256;
-
 pub(crate) mod rpx;
-pub use rpx::Rpx256;
 
 #[cfg(test)]
 mod tests;

miden-crypto/src/hash/algebraic_sponge/rescue/rpo/tests.rs

@@ -10,7 +10,7 @@ use super::{
 use crate::{
     ONE, PrimeCharacteristicRing, PrimeField64, Word, ZERO,
     hash::algebraic_sponge::{AlgebraicSponge, BINARY_CHUNK_SIZE, CAPACITY_RANGE, RATE_WIDTH},
-    test_utils::rand_value,
+    rand::test_utils::rand_value,
 };
 
 #[test]

miden-crypto/src/hash/algebraic_sponge/rescue/rpx/tests.rs

@@ -5,7 +5,9 @@ use p3_field::PrimeField64;
 use proptest::prelude::*;
 
 use super::{Felt, Rpx256};
-use crate::{ONE, Word, ZERO, hash::algebraic_sponge::AlgebraicSponge, test_utils::rand_value};
+use crate::{
+    ONE, Word, ZERO, hash::algebraic_sponge::AlgebraicSponge, rand::test_utils::rand_value,
+};
 
 // The number of iterations to run the `ext_round_matches_reference_many` test.
 #[cfg(all(

miden-crypto/src/hash/algebraic_sponge/rescue/tests.rs

@@ -2,7 +2,7 @@
 use p3_field::PrimeCharacteristicRing;
 
 use super::{ALPHA, Felt, INV_ALPHA};
-use crate::test_utils::rand_value;
+use crate::rand::test_utils::rand_value;
 
 #[test]
 fn test_alphas() {

miden-crypto/src/hash/blake/tests.rs

@@ -6,7 +6,7 @@ use p3_miden_goldilocks::Goldilocks as Felt;
 use proptest::prelude::*;
 
 use super::*;
-use crate::test_utils::rand_vector;
+use crate::rand::test_utils::rand_vector;
 
 #[test]
 fn blake3_hash_elements() {

miden-crypto/src/hash/keccak/tests.rs

@@ -4,7 +4,7 @@ use alloc::vec::Vec;
 use proptest::prelude::*;
 
 use super::*;
-use crate::test_utils::rand_vector;
+use crate::rand::test_utils::rand_vector;
 
 #[test]
 fn keccak256_hash_elements() {

miden-crypto/src/hash/mod.rs

@@ -13,20 +13,29 @@ pub mod sha2;
 
 /// Poseidon2 hash function.
 pub mod poseidon2 {
-    pub use super::algebraic_sponge::poseidon2::Poseidon2;
+    pub use p3_miden_goldilocks::Poseidon2Goldilocks;
+
+    pub use super::algebraic_sponge::poseidon2::{
+        Poseidon2, Poseidon2Challenger, Poseidon2Compression, Poseidon2Hasher,
+        Poseidon2Permutation256,
+    };
 }
 
 /// Rescue Prime Optimized (RPO) hash function.
 pub mod rpo {
-    pub use super::algebraic_sponge::rescue::Rpo256;
+    pub use super::algebraic_sponge::rescue::rpo::{
+        Rpo256, RpoChallenger, RpoCompression, RpoHasher,
+    };
 }
 
 /// Rescue Prime Extended (RPX) hash function.
 pub mod rpx {
-    pub use super::algebraic_sponge::rescue::Rpx256;
+    pub use super::algebraic_sponge::rescue::rpx::{
+        Rpx256, RpxChallenger, RpxCompression, RpxHasher,
+    };
 }
 
-pub mod algebraic_sponge;
+mod algebraic_sponge;
 
 // TRAITS
 // ================================================================================================

miden-crypto/src/hash/sha2/tests.rs

@@ -4,7 +4,7 @@ use alloc::vec::Vec;
 use proptest::prelude::*;
 
 use super::*;
-use crate::test_utils::rand_vector;
+use crate::rand::test_utils::rand_vector;
 
 // SHA-256 TESTS
 // ================================================================================================

miden-crypto/src/lib.rs

@@ -15,36 +15,44 @@ pub mod rand;
 pub mod utils;
 pub mod word;
 
-// Test utilities for generating random data (used in tests and benchmarks)
-#[cfg(any(test, feature = "std"))]
-pub mod test_utils;
-
 // RE-EXPORTS
 // ================================================================================================
 
 pub use k256::elliptic_curve::zeroize;
-pub use p3_air::{
-    Air, AirBuilder, AirBuilderWithPublicValues, BaseAir, BaseAirWithPublicValues,
-    ExtensionBuilder, FilteredAirBuilder, PairBuilder, PairCol, PermutationAirBuilder,
-    VirtualPairCol,
-};
 pub use p3_field::{
     BasedVectorSpace, ExtensionField, Field, PrimeCharacteristicRing, PrimeField64,
-    batch_multiplicative_inverse, extension::BinomialExtensionField, integers::QuotientMap,
-};
-pub use p3_miden_air::{BaseAirWithAuxTrace, FilteredMidenAirBuilder, MidenAir, MidenAirBuilder};
-pub use p3_miden_goldilocks::{Goldilocks as Felt, Poseidon2Goldilocks};
-pub use p3_miden_prover::{
-    Commitments, Domain, Entry, OpenedValues, PackedChallenge, PackedVal, PcsError, Proof,
-    ProverConstraintFolder, StarkConfig, StarkGenericConfig, SymbolicAirBuilder,
-    SymbolicExpression, SymbolicVariable, Val, VerificationError, VerifierConstraintFolder,
-    generate_logup_trace, get_log_quotient_degree, get_max_constraint_degree,
-    get_symbolic_constraints, prove, quotient_values, recompose_quotient_from_chunks, verify,
-    verify_constraints,
+    extension::BinomialExtensionField, integers::QuotientMap,
 };
+pub use p3_miden_goldilocks::Goldilocks as Felt;
 pub use word::{Word, WordError};
 
-pub use crate::rand::{Randomizable, RpoRandomCoin, RpxRandomCoin};
+pub mod stark {
+    //! Foundational components for the STARK proving system based on Plonky3.
+    //!
+    //! This module contains components needed to build a STARK prover/verifier and define
+    //! Algebraic Intermediate Representation (AIR) for the Miden VM and other components.
+    //! It primarily consists of re-exports from the Plonky3 project with some Miden-specific
+    //! adaptations.
+    pub use p3_miden_prover::{
+        Commitments, Domain, Entry, OpenedValues, PackedChallenge, PackedVal, PcsError, Proof,
+        ProverConstraintFolder, StarkConfig, StarkGenericConfig, SymbolicAirBuilder,
+        SymbolicExpression, SymbolicVariable, Val, VerificationError, VerifierConstraintFolder,
+        generate_logup_trace, get_log_quotient_degree, get_max_constraint_degree,
+        get_symbolic_constraints, prove, quotient_values, recompose_quotient_from_chunks, verify,
+        verify_constraints,
+    };
+
+    pub mod air {
+        pub use p3_air::{
+            Air, AirBuilder, AirBuilderWithPublicValues, BaseAir, BaseAirWithPublicValues,
+            ExtensionBuilder, FilteredAirBuilder, PairBuilder, PairCol, PermutationAirBuilder,
+            VirtualPairCol,
+        };
+        pub use p3_miden_air::{
+            BaseAirWithAuxTrace, FilteredMidenAirBuilder, MidenAir, MidenAirBuilder,
+        };
+    }
+}
 
 // TYPE ALIASES
 // ================================================================================================

miden-crypto/src/main.rs

@@ -7,7 +7,7 @@ use miden_crypto::{
     EMPTY_WORD, Felt, ONE, Word,
     hash::rpo::Rpo256,
     merkle::smt::{LargeSmt, LargeSmtError, MemoryStorage, SmtStorage},
-    test_utils::rand_value,
+    rand::test_utils::rand_value,
 };
 use rand::{Rng, prelude::IteratorRandom, rng};
 

miden-crypto/src/merkle/smt/large_forest/history/tests.rs

@@ -7,7 +7,7 @@ use super::{CompactLeaf, History, LeafChanges, NodeChanges, error::Result};
 use crate::{
     Felt, Word,
     merkle::{NodeIndex, smt::LeafIndex},
-    test_utils::rand_value,
+    rand::test_utils::rand_value,
 };
 
 // TESTS

miden-crypto/src/merkle/smt/partial/tests.rs

@@ -4,7 +4,7 @@ use assert_matches::assert_matches;
 
 use super::{PartialSmt, SMT_DEPTH};
 #[cfg(any(test, feature = "std"))]
-use crate::test_utils::{rand_array, rand_value};
+use crate::rand::test_utils::{rand_array, rand_value};
 use crate::{
     EMPTY_WORD, Felt, ONE, Word, ZERO,
     merkle::{

miden-crypto/src/rand/mod.rs

@@ -11,6 +11,10 @@ pub use rpo::RpoRandomCoin;
 mod rpx;
 pub use rpx::RpxRandomCoin;
 
+// Test utilities for generating random data (used in tests and benchmarks)
+#[cfg(any(test, feature = "std"))]
+pub mod test_utils;
+
 // RANDOMNESS (ported from Winterfell's winter-utils)
 // ================================================================================================
 

miden-crypto/src/test_utils.rs → miden-crypto/src/rand/test_utils.rs

@@ -9,13 +9,13 @@ use alloc::vec::Vec;
 use rand::{Rng, SeedableRng};
 use rand_chacha::ChaCha20Rng;
 
-use crate::utils::Randomizable;
+use crate::rand::Randomizable;
 
 /// Generates a random value of type T using the thread-local random number generator.
 ///
 /// # Examples
 /// ```
-/// # use miden_crypto::test_utils::rand_value;
+/// # use miden_crypto::rand::test_utils::rand_value;
 /// let x: u64 = rand_value();
 /// let y: u128 = rand_value();
 /// ```
@@ -31,7 +31,7 @@ pub fn rand_value<T: Randomizable>() -> T {
 ///
 /// # Examples
 /// ```
-/// # use miden_crypto::test_utils::rand_array;
+/// # use miden_crypto::rand::test_utils::rand_array;
 /// let arr: [u64; 4] = rand_array();
 /// ```
 #[cfg(feature = "std")]
@@ -43,7 +43,7 @@ pub fn rand_array<T: Randomizable, const N: usize>() -> [T; N] {
 ///
 /// # Examples
 /// ```
-/// # use miden_crypto::test_utils::rand_vector;
+/// # use miden_crypto::rand::test_utils::rand_vector;
 /// let vec: Vec<u64> = rand_vector(100);
 /// ```
 #[cfg(feature = "std")]
@@ -58,7 +58,7 @@ pub fn rand_vector<T: Randomizable>(length: usize) -> Vec<T> {
 ///
 /// # Examples
 /// ```
-/// # use miden_crypto::test_utils::prng_array;
+/// # use miden_crypto::rand::test_utils::prng_array;
 /// let seed = [0u8; 32];
 /// let arr: [u64; 4] = prng_array(seed);
 /// ```
@@ -75,7 +75,7 @@ pub fn prng_array<T: Randomizable, const N: usize>(seed: [u8; 32]) -> [T; N] {
 ///
 /// # Examples
 /// ```
-/// # use miden_crypto::test_utils::prng_vector;
+/// # use miden_crypto::rand::test_utils::prng_vector;
 /// let seed = [0u8; 32];
 /// let vec: Vec<u64> = prng_vector(seed, 100);
 /// ```

miden-crypto/src/utils/mod.rs

@@ -95,6 +95,11 @@ pub fn hex_to_bytes<const N: usize>(value: &str) -> Result<[u8; N], HexParseErro
     Ok(decoded)
 }
 
+// MATH UTILITIES
+// ================================================================================================
+
+pub use p3_field::batch_multiplicative_inverse;
+
 // CONVERSIONS BETWEEN BYTES AND ELEMENTS
 // ================================================================================================
 
@@ -354,8 +359,3 @@ pub fn transpose_slice<T: Copy + Send + Sync, const N: usize>(source: &[T]) -> V
     });
     result
 }
-
-// RANDOMNESS (ported from Winterfell's winter-utils)
-// ================================================================================================
-
-pub use crate::rand::Randomizable;

miden-crypto/src/word/tests.rs

@@ -4,7 +4,7 @@ use alloc::string::String;
 use p3_field::PrimeCharacteristicRing;
 
 use super::{Deserializable, Felt, Serializable, WORD_SIZE_BYTES, WORD_SIZE_FELT, Word};
-use crate::{test_utils::rand_value, utils::SliceReader, word};
+use crate::{rand::test_utils::rand_value, utils::SliceReader, word};
 
 // TESTS
 // ================================================================================================