refactor: swap Goldilocks re-export to the Felt type unified for off-chain and on-chain code

.github/workflows/build.yml

@@ -34,3 +34,21 @@ jobs:
           rustup default ${{ matrix.toolchain }}
           rustup target add wasm32-unknown-unknown
           make build-no-std
+
+  target-miden:
+    name: Build miden-field for on-chain target
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        toolchain: [stable, nightly]
+    steps:
+      - uses: actions/checkout@main
+      - name: Cleanup large tools for build space
+        uses: ./.github/actions/cleanup-runner
+      - name: Build miden-field for on-chain target
+        run: |
+          rustup update --no-self-update ${{ matrix.toolchain }}
+          rustup default ${{ matrix.toolchain }}
+          rustup target add wasm32-wasip2
+          make build-target-miden

CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.22.3 (unreleased)
+
+- Refactored to introduce a unified `Felt` type for on-chain and off-chain code ([#819](https://github.com/0xMiden/crypto/pull/819)).
+
 ## 0.22.2 (2026-02-01)
 
 - Re-exported `p3_keccak::VECTOR_LEN`.

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 exclude  = ["miden-crypto-fuzz"]
-members  = ["miden-crypto", "miden-crypto-derive", "miden-serde-utils"]
+members  = ["miden-crypto", "miden-crypto-derive", "miden-field", "miden-serde-utils"]
 resolver = "3"
 
 [workspace.package]
@@ -15,6 +15,7 @@ version      = "0.22.2"
 
 [workspace.dependencies]
 miden-crypto-derive = { path = "miden-crypto-derive", version = "0.22" }
+miden-field         = { path = "miden-field", version = "0.22" }
 miden-serde-utils   = { path = "miden-serde-utils", version = "0.22" }
 
 [workspace.lints.rust]

Makefile

@@ -112,6 +112,10 @@ build: ## Build with default features enabled
 build-no-std: ## Build without the standard library
 	cargo build --release --no-default-features --target wasm32-unknown-unknown
 
+.PHONY: build-target-miden
+build-target-miden: ## Build `miden-field` for wasm32-wasip2 with `--cfg miden`
+	RUSTFLAGS="--cfg miden" cargo build --release -p miden-field --target wasm32-wasip2
+
 .PHONY: build-avx2
 build-avx2: ## Build with avx2 support
 	RUSTFLAGS="-C target-feature=+avx2" cargo build --release

miden-crypto/Cargo.toml

@@ -86,36 +86,40 @@ internal = ["concurrent"]
 rocksdb = ["concurrent", "dep:rocksdb"]
 serde = ["dep:serde", "serde?/alloc"]
 std = ["blake3/std", "dep:cc", "miden-serde-utils/std", "rand/std", "rand/thread_rng"]
-testing = ["dep:proptest"]
+testing = ["dep:proptest", "miden-field/testing"]
 
 [dependencies]
-blake3                        = { default-features = false, version = "1.8" }
-chacha20poly1305              = { features = ["alloc", "stream"], version = "0.10" }
-clap                          = { features = ["derive"], optional = true, version = "4.5" }
-curve25519-dalek              = { default-features = false, version = "4" }
-ed25519-dalek                 = { features = ["zeroize"], version = "2" }
-flume                         = { version = "0.11.1" }
-hashbrown                     = { features = ["serde"], optional = true, version = "0.16" }
-hkdf                          = { default-features = false, version = "0.12" }
-k256                          = { features = ["ecdh", "ecdsa"], version = "0.13" }
+# Miden dependencies
 miden-crypto-derive.workspace = true
+miden-field.workspace         = true
 miden-serde-utils.workspace   = true
-num                           = { default-features = false, features = ["alloc", "libm"], version = "0.4" }
-num-complex                   = { default-features = false, version = "0.4" }
-proptest                      = { default-features = false, features = ["alloc"], optional = true, version = "1.7" }
-rand                          = { default-features = false, version = "0.9" }
-rand-utils                    = { optional = true, package = "winter-rand-utils", version = "0.13" }
-rand_chacha                   = { default-features = false, version = "0.9" }
-rand_core                     = { default-features = false, version = "0.9" }
-rand_hc                       = { version = "0.3" }
-rayon                         = { optional = true, version = "1.10" }
-rocksdb                       = { default-features = false, features = ["bindgen-runtime", "lz4"], optional = true, version = "0.24" }
-serde                         = { default-features = false, features = ["derive"], optional = true, version = "1.0" }
-sha2                          = { default-features = false, version = "0.10" }
-sha3                          = { default-features = false, version = "0.10" }
-subtle                        = { default-features = false, version = "2.6" }
-thiserror                     = { default-features = false, version = "2.0" }
-x25519-dalek                  = { default-features = false, features = ["static_secrets"], version = "2.0" }
+
+# External dependencies
+blake3           = { default-features = false, version = "1.8" }
+chacha20poly1305 = { features = ["alloc", "stream"], version = "0.10" }
+clap             = { features = ["derive"], optional = true, version = "4.5" }
+curve25519-dalek = { default-features = false, version = "4" }
+ed25519-dalek    = { features = ["zeroize"], version = "2" }
+flume            = { version = "0.11.1" }
+hashbrown        = { features = ["serde"], optional = true, version = "0.16" }
+hkdf             = { default-features = false, version = "0.12" }
+k256             = { features = ["ecdh", "ecdsa"], version = "0.13" }
+num              = { default-features = false, features = ["alloc", "libm"], version = "0.4" }
+num-complex      = { default-features = false, version = "0.4" }
+proptest         = { default-features = false, features = ["alloc"], optional = true, version = "1.7" }
+rand             = { default-features = false, version = "0.9" }
+rand-utils       = { optional = true, package = "winter-rand-utils", version = "0.13" }
+rand_chacha      = { default-features = false, version = "0.9" }
+rand_core        = { default-features = false, version = "0.9" }
+rand_hc          = { version = "0.3" }
+rayon            = { optional = true, version = "1.10" }
+rocksdb          = { default-features = false, features = ["bindgen-runtime", "lz4"], optional = true, version = "0.24" }
+serde            = { default-features = false, features = ["derive"], optional = true, version = "1.0" }
+sha2             = { default-features = false, version = "0.10" }
+sha3             = { default-features = false, version = "0.10" }
+subtle           = { default-features = false, version = "2.6" }
+thiserror        = { default-features = false, version = "2.0" }
+x25519-dalek     = { default-features = false, features = ["static_secrets"], version = "2.0" }
 
 # Upstream Plonky3 dependencies
 p3-air         = { default-features = false, version = "0.4.2" }
@@ -142,6 +146,7 @@ assert_matches = { default-features = false, version = "1.5" }
 criterion      = { features = ["html_reports"], version = "0.7" }
 hex            = { default-features = false, features = ["alloc"], version = "0.4" }
 itertools      = { version = "0.14" }
+miden-field    = { features = ["testing"], workspace = true }
 proptest       = { default-features = false, features = ["alloc"], version = "1.7" }
 rand-utils     = { package = "winter-rand-utils", version = "0.13" }
 rstest         = { version = "0.26" }

miden-crypto/benches/word.rs

@@ -22,7 +22,7 @@
 
 use criterion::{Criterion, criterion_group, criterion_main};
 // Import Word modules
-use miden_crypto::{Felt, Word, word::LexicographicWord};
+use miden_crypto::{Felt, LexicographicWord, Word};
 
 // Import common utilities
 mod common;

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

@@ -2,11 +2,10 @@
 use alloc::vec::Vec;
 
 use p3_field::PrimeField64;
-use p3_goldilocks::Goldilocks as Felt;
 use proptest::prelude::*;
 
 use super::*;
-use crate::rand::test_utils::rand_vector;
+use crate::{Felt, rand::test_utils::rand_vector};
 
 #[test]
 fn blake3_hash_elements() {

miden-crypto/src/lib.rs

@@ -15,12 +15,11 @@ pub mod ies;
 pub mod merkle;
 pub mod rand;
 pub mod utils;
-pub mod word;
 
+use miden_field::word;
 // RE-EXPORTS
 // ================================================================================================
-pub use p3_goldilocks::Goldilocks as Felt;
-pub use word::{Word, WordError};
+pub use miden_field::{Felt, LexicographicWord, Word, WordError};
 
 pub mod field {
     //! Traits and utilities for working with the Goldilocks finite field (i.e.,
@@ -140,7 +139,7 @@ pub type Set<V> = alloc::collections::BTreeSet<V>;
 // ================================================================================================
 
 /// Number of field elements in a word.
-pub const WORD_SIZE: usize = 4;
+pub const WORD_SIZE: usize = word::WORD_SIZE_FELT;
 
 /// Field element representing ZERO in the Miden base filed.
 pub const ZERO: Felt = Felt::ZERO;

miden-crypto/src/rand/mod.rs

@@ -1,5 +1,6 @@
 //! Pseudo-random element generation.
 
+use miden_field::word::WORD_SIZE_BYTES;
 use p3_field::PrimeField64;
 use rand::RngCore;
 
@@ -104,6 +105,19 @@ impl Randomizable for Felt {
     }
 }
 
+impl Randomizable for Word {
+    const VALUE_SIZE: usize = WORD_SIZE_BYTES;
+
+    fn from_random_bytes(bytes: &[u8]) -> Option<Self> {
+        let bytes_array: Option<[u8; 32]> = bytes.try_into().ok();
+        if let Some(bytes_array) = bytes_array {
+            Self::try_from(bytes_array).ok()
+        } else {
+            None
+        }
+    }
+}
+
 impl<const N: usize> Randomizable for [u8; N] {
     const VALUE_SIZE: usize = N;
 

miden-crypto/src/utils/mod.rs

@@ -12,7 +12,6 @@ pub use miden_serde_utils::{
 };
 use p3_field::{PrimeCharacteristicRing, RawDataSerializable, integers::QuotientMap};
 use p3_maybe_rayon::prelude::*;
-use thiserror::Error;
 
 use crate::{Felt, Word, field::PrimeField64};
 
@@ -41,59 +40,7 @@ pub fn word_to_hex(w: &Word) -> Result<String, fmt::Error> {
     Ok(s)
 }
 
-/// Renders an array of bytes as hex into a String.
-pub fn bytes_to_hex_string<const N: usize>(data: [u8; N]) -> String {
-    let mut s = String::with_capacity(N + 2);
-
-    s.push_str("0x");
-    for byte in data.iter() {
-        write!(s, "{byte:02x}").expect("formatting hex failed");
-    }
-
-    s
-}
-
-/// Defines errors which can occur during parsing of hexadecimal strings.
-#[derive(Debug, Error)]
-pub enum HexParseError {
-    #[error("expected hex data to have length {expected}, including the 0x prefix, found {actual}")]
-    InvalidLength { expected: usize, actual: usize },
-    #[error("hex encoded data must start with 0x prefix")]
-    MissingPrefix,
-    #[error("hex encoded data must contain only characters [0-9a-fA-F]")]
-    InvalidChar,
-    #[error("hex encoded values of a Digest must be inside the field modulus")]
-    OutOfRange,
-}
-
-/// Parses a hex string into an array of bytes of known size.
-pub fn hex_to_bytes<const N: usize>(value: &str) -> Result<[u8; N], HexParseError> {
-    let expected: usize = (N * 2) + 2;
-    if value.len() != expected {
-        return Err(HexParseError::InvalidLength { expected, actual: value.len() });
-    }
-
-    if !value.starts_with("0x") {
-        return Err(HexParseError::MissingPrefix);
-    }
-
-    let mut data = value.bytes().skip(2).map(|v| match v {
-        b'0'..=b'9' => Ok(v - b'0'),
-        b'a'..=b'f' => Ok(v - b'a' + 10),
-        b'A'..=b'F' => Ok(v - b'A' + 10),
-        _ => Err(HexParseError::InvalidChar),
-    });
-
-    let mut decoded = [0u8; N];
-    for byte in decoded.iter_mut() {
-        // These `unwrap` calls are okay because the length was checked above
-        let high: u8 = data.next().unwrap()?;
-        let low: u8 = data.next().unwrap()?;
-        *byte = (high << 4) + low;
-    }
-
-    Ok(decoded)
-}
+pub use miden_field::utils::{HexParseError, bytes_to_hex_string, hex_to_bytes};
 
 // CONVERSIONS BETWEEN BYTES AND ELEMENTS
 // ================================================================================================

miden-field/Cargo.toml

@@ -0,0 +1,43 @@
+[package]
+authors.workspace      = true
+categories.workspace   = true
+description            = "A unified field element type for on-chain and off-chain Miden Rust code"
+documentation          = "https://docs.rs/miden-field"
+edition.workspace      = true
+keywords.workspace     = true
+license.workspace      = true
+name                   = "miden-field"
+readme                 = "README.md"
+repository.workspace   = true
+rust-version.workspace = true
+version.workspace      = true
+
+[lib]
+crate-type = ["rlib"]
+
+# dependendies for both off-chain and on-chain targets
+[dependencies]
+thiserror = { default-features = false, version = "2.0" }
+
+# dependendies for the off-chain target only
+[target.'cfg(not(all(target_family = "wasm", miden)))'.dependencies]
+miden-serde-utils = { workspace = true }
+num-bigint        = { default-features = false, version = "0.4" }
+p3-challenger     = { default-features = false, version = "0.4.2" }
+p3-field          = { default-features = false, version = "0.4.2" }
+p3-goldilocks     = { default-features = false, version = "0.4.2" }
+paste             = { version = "1.0.15" }
+proptest          = { default-features = false, features = ["alloc", "std"], optional = true, version = "1.7" }
+rand              = { default-features = false, features = ["small_rng"], version = "0.9.0" }
+serde             = { default-features = false, features = ["derive"], version = "1.0" }
+
+[features]
+default = []
+testing = ["dep:proptest"]
+
+[dev-dependencies]
+rand   = { default-features = false, version = "0.9" }
+rstest = { version = "0.26" }
+
+[lints]
+workspace = true

miden-field/README.md

@@ -0,0 +1,39 @@
+# `miden-field`
+
+A unified field element type for Miden Rust code that needs to run in two very different
+environments:
+
+- **Off-chain** (native, or regular Wasm): `Felt` is a thin wrapper around Plonky3’s
+  `Goldilocks` field element.
+- **On-chain** (Wasm compiled for the Miden VM): `Felt` is represented using Miden compiler
+  intrinsics.
+
+## Motivation
+
+In the Miden on-chain execution environment, field elements are currently represented by the
+compiler using a *Wasm primitive type* (`f32`) that the compiler “reinterprets” as a felt.
+That works for on-chain code generation, but it means the on-chain `Felt` is not the same type
+as the off-chain `Felt` used throughout the Rust ecosystem.
+
+The result is that any code meant to be shared between on-chain and off-chain ends up either:
+
+- duplicated, or
+- littered with `#[cfg(...)]` gates and wrapper types to bridge the two representations.
+
+`miden-field` exists to provide a single `miden_field::Felt` API surface that compiles in both
+contexts without forcing downstream crates to pick a side.
+
+## How it works
+
+`miden-field` uses conditional compilation to select the backing implementation:
+
+- `cfg(all(target_family = "wasm", miden))` (on-chain): `Felt` is a `#[repr(transparent)]`
+  record with an `inner: f32` field (matching the WIT shape expected by bindings). Arithmetic
+  and conversions are implemented by calling Miden compiler intrinsics (e.g.
+  `intrinsics::felt::add`), and `f32` is never treated as a floating-point number.
+- otherwise (off-chain): `Felt` is `#[repr(transparent)]` over `p3_goldilocks::Goldilocks` and
+  implements the usual field traits. The modulus is the Goldilocks prime `2^64 - 2^32 + 1`.
+
+The rest of the crate (e.g. `Word`) builds on top of `Felt` and therefore works in both
+environments as well.
+