refactor: swap `Goldilocks` re-export to the `Felt` type unified for off-chain and on-chain code by greenhat · Pull Request #819 · 0xMiden/crypto

greenhat · 2026-02-06T14:58:34Z

Close #771

This PR swaps the p3_goldilocks::Goldilocks as Felt re-export to the wrapper Felt(p3_goldilocks::Goldilocks) type for non-Miden targets. For the Miden target Felt(f32) is compiled (see explanation in #771).
Besides that Word type is changed to have the WIT-compatible shape (struct with a named field).

All Felt methods and implemented traits are delegating everything to the underlying Goldilocks type and its trait implementations. So the Felt should be 100% API equivalent to the Goldilocks type and can be used as a drop-in replacement. This allows us to release it as a v0.22.x patch version so that it can be included in VM v0.21 release. That's why I made this PR against the main branch.

The corresponding PR in the VM repo that updates VM to the version of miden-crypto from this branch is 0xMiden/miden-vm#2649.

The corresponding PR in the compiler repo migrating to the miden-field crate from this PR is 0xMiden/compiler#923

In the follow-up PRs:

Remove the Serializable/Deserializable impl for Goldilocks in the miden-serde-utils crate (via refactor: swap Goldilocks re-export to the Felt type unified for off-chain and on-chain code #819 (comment))

make `Word` type to have the WIT-compatible shape

huitseeker

Some concerns with unsafe conversions, and questions inline.

huitseeker · 2026-02-10T00:29:34Z

miden-crypto/src/word/mod.rs

+    ///
+    /// # Safety
+    /// This assumes `(Felt, Felt, Felt, Felt)` has the same memory layout as `[Felt; 4]`.
+    fn as_elements_array(&self) -> &[Felt; WORD_SIZE_FELT] {


The cast from &(Felt, Felt, Felt, Felt) to &[Felt; 4] indeed assumes identical memory layout, but Rust does not guarantee tuple layout. This could lead to UB if the compiler changes layout.

I'd suggest adding compile-time assertions like const_assert!(size_of::<(Felt, Felt, Felt, Felt)>() == size_of::<[Felt; 4]>()); at least (and a proptest) to verify the assumption of equivalence at build (/test) time.

Thank you! I converted the Word type to have named fields instead of a tuple and added a test with a roundtrip in 0e06cae.

huitseeker · 2026-02-10T00:29:40Z

miden-field/src/word/mod.rs

@@ -161,14 +208,13 @@ impl Word {
    where
        I: Iterator<Item = &'a Self>,
    {
-        words.flat_map(|d| d.0.iter())
+        words.flat_map(|d| d.as_elements().iter())
    }

    /// Returns all elements of multiple words as a slice.
    pub fn words_as_elements(words: &[Self]) -> &[Felt] {


words_as_elements casts &[Word] to &[Felt] via raw pointer. With #[repr(C, align(16))] on Word, this assumes no padding between elements and specific field ordering. Suggest adding const_assert! checks for size and alignment, or using the safe words_as_elements_iter instead where performance allows.

Addressed above in #819 (comment)

huitseeker · 2026-02-10T00:29:44Z

miden-field/src/lib.rs

@@ -0,0 +1,20 @@
+//! A unified `Felt` for Miden Rust code.


The new miden-field crate has no tests. Since this is cryptographic code used throughout the codebase, consider adding unit tests for both the native and WASM implementations to ensure correctness of field operations.

I'm not sure adding tests for miden target would be possible here since implementation of these methods would be delegated to compiler intrinsics. IIUC, this would require the whole compiler pipeline to be present. So, maybe a better places for these is in the compiler repo?

For native implementation, I think the main thing we'd be testing is that we didn't mix up delegated function calls. Maybe there is a way to add a couple of tests which would run all (most?) operations on some random elements and make sure we get the same result for Felt and native Goldilocks?

The miden target tests for Felt are living in the compiler repo since they are implemented in the compiler intrinsics which mostly delegate to the VM ops. We have a proptest test suite where we test individual ops and they are also covered in the integration test suite where we are compiling and running some contracts.

For native implementation, the only thing worth testing is that we're delegating properly to the underlying Goldilocks implementation. I'll come up with something.

huitseeker · 2026-02-10T00:50:59Z

miden-field/src/word/mod.rs

+    // We cannot define this type as `Word([Felt;4])` since there is no struct tuple support
+    // and fixed array support is not complete in WIT. For the type remapping to work the
+    // bindings are expecting the remapped type to be the same shape as the one generated from
+    // WIT.


Would it not be possible to use:

#[repr(C)] pub struct Word { a: Felt, b: Felt, c: Felt, d: Felt, }

from a WIT PoV, or do you need the tuple?

Because that is layout-compatible with [Felt; 4].

Thank you! From the WIT it does not have to be a tuple, so I changed it to your suggestion.

…-field` crate

… `build.yml` To test building for the wasm32+miden (on-chain) target.

bobbinth

Looks good! Thank you! Not a full review yet, but I left some comments inline.

miden-field/Cargo.toml

miden-field/src/native.rs

miden-crypto/Cargo.toml

bobbinth · 2026-02-15T00:55:28Z

miden-field/src/word/tests.rs

+pub fn rand_u64() -> u64 {
+    let mut bytes = [0u8; 8];
+    let rng = &mut rand::rng();
+    rng.fill(&mut bytes[..]);
+    let bytes = bytes[..8].try_into().unwrap();
+    u64::from_le_bytes(bytes)
+}


Could this not be just:

pub fn rand_u64() -> u64 { rand::random() }

And if so, maybe we can just use rand::random() instead of this function directly?

Sure. I also planned to convert the existing tests to proptest in this PR as well. Although it might be better to do it in the new PR.

bobbinth · 2026-02-15T00:56:47Z

miden-field/src/wasm_miden.rs

I did a very cursory review of this file.

miden-field/src/native.rs

miden-field/src/native/mod.rs

miden-field/src/word/mod.rs

…ields

split internal vs external dependencies.

miden-crypto/src/lib.rs

greenhat · 2026-02-17T07:39:59Z

Thank you for the review! I've gone through all the review notes and implemented some of them right away and put the rest in the TODO in the PR desc. I'll be going through the TODO and will ping you when I'm done.

The notable change that I made after the @huitseeker review was to move the Word type to the miden-field crate. To avoid compiling miden-crypto and its dependencies for the miden (on-chain) target.

I organized the commits addressing the review notes to make it easier to review so I suggest reviewing the changes on a per-commit basis.

…-field` crate

implementations

huitseeker

On wasm+miden, word! still expands to Word::parse, but parse is behind cfg(not(all(target_family = "wasm", miden))). I think that breaks compile for on-chain users. Please gate word! for this target or add a Miden-safe parse path.

huitseeker · 2026-02-18T12:53:05Z

miden-field/src/word/mod.rs

+        self.as_elements().to_vec()
+    }
+
+    pub fn reversed(&self) -> Self {


Small: Word::reversed() has no direct test. A short round-trip test would lock the behavior.

Done in a897b5b

greenhat · 2026-02-19T11:10:53Z

On wasm+miden, word! still expands to Word::parse, but parse is behind cfg(not(all(target_family = "wasm", miden))). I think that breaks compile for on-chain users. Please gate word! for this target or add a Miden-safe parse path.

Thank you! Done in 04f5af6

greenhat · 2026-02-19T12:41:20Z

I addressed all the review notes and this PR is ready.

Since my last comment at #819 (comment) I did (notable):

Added impl Arbitrary for Felt;
Tests the native Felt properly delegating everything to the underlying Goldilocks implementation;
Converted the tests to proptest in miden-field/src/word/tests.rs;
Tested this branch in the VM chore: update miden-crypto (with unified Felt type) miden-vm#2649 and compiler Switch to the miden-field from miden-crypto repo compiler#923 branches;

I tried to structure the commits for reviewing so I suggest reviewing the changes on a per-commit basis.

huitseeker

Most everything looks good, I think we're just missing the NEG_ONE, thank you!

huitseeker · 2026-02-20T03:40:50Z

miden-field/src/wasm_miden.rs

+
+    /// Field element representing two.
+    pub const TWO: Self = Self { inner: f32::from_bits(2) };
+


The native implementation has NEG_ONE constant but this WASM implementation is missing it. This could cause compilation failures for code that expects it to be available. Should we add it for API parity?

Good catch! But since Felt for miden target is a wrapper on f32 there is no way to encode the 2^64 - 2^32 using the Rust const because it'd involve a call to the compiler intrinsics.

huitseeker · 2026-02-20T03:40:53Z

miden-field/build.rs

+    // `cargo-miden` compiles Rust to Wasm which will then be compiled to Miden VM code by `midenc`.
+    // When targeting a "real" Wasm runtime (e.g. `wasm32-unknown-unknown` for a web SDK), we want a
+    // regular felt representation instead.
+    if env::var_os("MIDENC_TARGET_IS_MIDEN_VM").is_some() {


nit: This accepts any value (even empty string) for MIDENC_TARGET_IS_MIDEN_VM. Consider checking for a non-empty value, true or 1 to avoid accidentally triggering the miden target when the variable is set but empty.

Good catch! Thanks! Done in 7e5a2cb

huitseeker · 2026-02-20T03:40:56Z

miden-field/src/word/mod.rs

+    /// This assumes the four fields of [`Word`] are laid out contiguously with no padding, in
+    /// the same order as `[Felt; 4]`.
+    fn as_elements_array(&self) -> &[Felt; WORD_SIZE_FELTS] {
+        unsafe { &*(&self.a as *const Felt as *const [Felt; WORD_SIZE_FELTS]) }


nit: Consider adding compile-time assertions to verify that size_of::<Word>() == 4 * size_of::<Felt>() and that fields have no padding. This would catch layout changes at compile time rather than risking UB. The static_assertions crate or a simple const _: () = assert!(...) could work here.

Added in 59dadc1

…elt; 4]`

greenhat · 2026-02-20T12:20:13Z

Most everything looks good, I think we're just missing the NEG_ONE, thank you!

Thank you! I addressed all your notes.

huitseeker

Thanks a bunch!

bobbinth

Looks good! Thank you! I left one question inline.

miden-field/src/word/mod.rs

greenhat mentioned this pull request Feb 6, 2026

chore: update miden-crypto (with unified Felt type) 0xMiden/miden-vm#2649

Merged

greenhat changed the title ~~refactor: add Felt type unified for off-chain and on-chain code~~ refactor: swap Goldilocks re-export to the Felt type unified for off-chain and on-chain code Feb 6, 2026

greenhat force-pushed the greenhat-unified-felt branch from f38f76c to bff706b Compare February 9, 2026 07:59

refactor: add Felt type unified for off-chain and on-chain code,

ba5aa2b

make `Word` type to have the WIT-compatible shape

greenhat force-pushed the greenhat-unified-felt branch from bff706b to ba5aa2b Compare February 9, 2026 12:17

greenhat mentioned this pull request Feb 9, 2026

Switch to the miden-field from miden-crypto repo 0xMiden/compiler#923

Closed

1 task

greenhat marked this pull request as ready for review February 9, 2026 12:29

greenhat requested review from Al-Kindi-0, bitwalker, bobbinth and huitseeker February 9, 2026 12:39

huitseeker reviewed Feb 10, 2026

View reviewed changes

greenhat marked this pull request as draft February 10, 2026 10:13

greenhat added 4 commits February 13, 2026 14:51

refactor: move Word and derived types from miden-crypto to `miden…

1519870

…-field` crate

chore: add make build_target_miden task and targe-miden CI job in…

2340896

… `build.yml` To test building for the wasm32+miden (on-chain) target.

fix: bring wasm+miden Felt API on par with native

d852c32

fix: build miden-field for wasm+miden target

06d007b

bobbinth reviewed Feb 15, 2026

View reviewed changes

greenhat added 7 commits February 16, 2026 09:34

fix: imports for LexicographicWord, remove AsRef impl for Word

c5ae258

refactor: change the shape of the Word type from a tuple to named f…

0e06cae

…ields

chore: formatting

d0a0ae6

refactor: make the inner type private in Felt

2374a2b

chore: make miden-field crate a workspace dependency

9ab51d9

split internal vs external dependencies.

chore: add README.md for the miden-field crate

2adaca4

refactor: use format!

d973a9b

bobbinth reviewed Feb 17, 2026

View reviewed changes

miden-crypto/src/lib.rs Show resolved Hide resolved

greenhat added 2 commits February 17, 2026 09:14

fix: re-export miden_field::word module from miden-crypto

b818ccc

refactor: rename miden_field::WORD_SIZE_FELT to WORD_SIZE_FELTS

f3f7bda

fix: cargo check --all-targets --no-default-features for the `miden…

81f9ce6

…-field` crate

greenhat added 4 commits February 17, 2026 15:24

test: implement Arbitrary for Felt

a08abee

refactor: native.rs -> native/mod.rs

ad0c03f

chore: add tests to ensure equivalence of Felt vs Goldilocks

ea183ce

implementations

chore: convert Word tests to proptests

2d67e4c

huitseeker requested changes Feb 18, 2026

View reviewed changes

refactor: re-export p3-field traits in miden-field

21199a3

greenhat force-pushed the greenhat-unified-felt branch from 88c1e88 to 21199a3 Compare February 19, 2026 08:09

greenhat added 2 commits February 19, 2026 13:04

fix: gate word! to be available in the off-chain target only

04f5af6

test: add the roundtrip test for Word::reversed

a897b5b

greenhat added 3 commits February 19, 2026 14:05

fix: don't clobber RUSTFLAGS env var build-target-miden task

daab99c

chore: add doc comment for Word::reversed

f3e1a5a

refactor: define align(16) for Word only for miden target

440b59e

greenhat marked this pull request as ready for review February 19, 2026 12:41

greenhat requested review from bobbinth and huitseeker February 19, 2026 12:41

huitseeker reviewed Feb 20, 2026

View reviewed changes

greenhat added 2 commits February 20, 2026 10:58

test: add a compile-time check that Word has the same layout as `[F…

59dadc1

…elt; 4]`

fix: check that MIDENC_TARGET_IS_MIDEN_VM env var is not empty

7e5a2cb

greenhat requested a review from huitseeker February 20, 2026 12:20

huitseeker approved these changes Feb 20, 2026

View reviewed changes

bobbinth approved these changes Feb 23, 2026

View reviewed changes

miden-field/src/word/mod.rs Show resolved Hide resolved

chore: add comment explaining why Word fields have to be public

12a70dc

bobbinth merged commit e3186e3 into main Feb 23, 2026
29 checks passed

bobbinth deleted the greenhat-unified-felt branch February 23, 2026 21:48

greenhat mentioned this pull request Feb 26, 2026

Unified Felt type for on-chain and off-chain code #771

Closed


		/// Field element representing two.
		pub const TWO: Self = Self { inner: f32::from_bits(2) };

Conversation

greenhat commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

huitseeker left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bobbinth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greenhat commented Feb 17, 2026

Uh oh!

huitseeker left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greenhat commented Feb 19, 2026

Uh oh!

greenhat commented Feb 19, 2026

Uh oh!

huitseeker left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greenhat commented Feb 20, 2026

Uh oh!

huitseeker left a comment

Choose a reason for hiding this comment

Uh oh!

bobbinth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greenhat commented Feb 6, 2026 •

edited

Loading