Add `QM31` implementation #149

FrancoGiachetta · 2025-08-12T15:55:54Z

Summary

The purpose of this PR is to move QM31's implementation from Cairo VM to types-rs. It adds a wrapper over FieldElement<Stark252PrimeField> which allows a safer usage of QM31 operations.
The implemented set of operations only corresponds to the ones in Cairo VM.

Pull Request type

Please add the labels corresponding to the type of changes your PR introduces:

Feature

What is the current behavior?

QM31 is not implemented in types-rs

Resolves: #NA

What is the new behavior?

Add QM31Felt abstraction for performing QM31 operation in a safe manner.

Does this introduce a breaking change?

No

Other information

crates/starknet-types-core/src/felt/qm31.rs

crates/starknet-types-core/src/qm31/mod.rs

0xLucqs · 2025-08-21T11:30:54Z

crates/starknet-types-core/src/qm31/mod.rs

+/// Each of this limbs can be represented by 36 bits.
+#[repr(transparent)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct QM31([u64; 4]);


why are we using u64s here ?
and why a limb would be 36 bits ?
Shouldn't we also introduce CM31 as an intermediate type ?

why are we using u64s here

So that we can hold 36 bits.

and why a limb would be 36 bits ?

This is how it was implemented in Cairo VM. This is the commit which introduced it. The comments suggests QM31 is composted of 4 u64 limbs which represent 36 bit values, so 144 bits in total.

Shouldn't we also introduce CM31 as an intermediate type ?

This is implementation of a QM31. Instead of having two CM31, we have the four coordinates.

This PR migrates what was implemented in the Cairo VM. Is there anything you think should be changed?

a felt in M31 is 31 bits i don't get why here it'd be 36, am i missing something ?

This PR migrates what was implemented in the Cairo VM.

I understand that but it feels weird to have the quartic EF and not the base field imo. Fine for now but i think the rest should be added in a follow up PR

Found this comment from one of the commits that implemented this feature in Cairo VM. It explains why is was decided to use u64 as m31 representation. Seems it uses 36 bits for a m31 for an efficient Felt representation.
As you suggested, I think it's better to u32 instead of u64. I'll make this change. Sorry about the inconvenience.

Change the representation to u32 coordinates 020c0dc.

you changed the coordinates to be [u32; 4] but 32*4 = 128.
We need 144 bits.
Which is 4,5 u32. So we need [u35; 5].

Or am I missing something?

I mess up with the docs in cairo VM. This firstly was implemented in the cairo VM and since it only operates with felts, a qm31 was always being packed into a Felt. For efficiency reasons (check this lambdaclass/cairo-vm#1944 (comment)), related to the multiplication operation, it's better to represent every M31 with 36 bits instead of 31 (as it should). This mens that, only in the felt representation, a QM31 is 144 bits long.

This implementation treats every M31 as 31 bit value. So only when packing a QM31 into a felt a M31 be represented with 36 bits now. This is why we still check that, when unpacking from a Felt, the value is no longer than 144 bits.

gabrielbosio · 2025-08-21T17:30:28Z

crates/starknet-types-core/src/qm31/mod.rs

+    /// [QM31] constant that's equal to 0.
+    pub const ZERO: Self = Self([0, 0, 0, 0]);
+
+    pub fn inner(&self) -> [u32; 4] {


Suggested change

pub fn inner(&self) -> [u32; 4] {

pub fn to_coordinates(&self) -> [u32; 4] {

Done in: edd3fa5

gabrielbosio · 2025-08-21T17:30:56Z

crates/starknet-types-core/src/qm31/mod.rs

+    /// This method is convinient for performing multications and inversions,
+    /// in which operating with the coordinates could result in overflows if
+    /// the 32 bit representation was used.
+    fn inner_u64(&self) -> [u64; 4] {


Suggested change

fn inner_u64(&self) -> [u64; 4] {

fn to_coordinates_u64(&self) -> [u64; 4] {

Done in: edd3fa5

convinient -> convenient

I didn't realize that renaming to to_coordinates_u64 would cause a clippy error. Maybe we can rename it to as_coordinates_u64 (or as_u64_coordinates) since it's private

Yes, I ended up doing that

tdelabro · 2025-08-21T18:24:16Z

@FrancoGiachetta We still need top level (//!) documentation to explain what "quadruple mersenne 31" is, and when it should be used.

FrancoGiachetta · 2025-08-22T13:38:59Z

Hi @tdelabro! Added the requested top level docs.

tdelabro · 2025-08-22T13:39:11Z

crates/starknet-types-core/src/qm31/mod.rs

@@ -1,3 +1,20 @@
+//! A Cairo-like QM31 type.
+//!
+//! The QM31 type represents a Degree-4 extension the Mersenne 31 Field. This extension can be


in the Mersenne 31 field ?
"in" missing + field don't have to be capitalized

Fix here: 7f3d6ef

tdelabro · 2025-08-22T13:40:35Z

crates/starknet-types-core/src/qm31/mod.rs

+//! The QM31 type represents a Degree-4 extension the Mersenne 31 Field. This extension can be
+//! represented as two components of the Complex extension the Mersenne 31 Field as follows ((a, b), (c, d)), where
+//! a, b, c and d represent a value from the Mersenne 31 Field, denotated as M31.
+//! If anly a M31 was used by the verifier, then a 31 bit value wouldn't be enough to provide security


"If any" typo
"a M31" is it "a" like the value you named "a" or a regular english word?

It refers to the value a named. This is to avoid repeating "a value from the Mersenne 31 field". The first typo is already fixed in this commit: b65e34b

gabrielbosio · 2025-08-22T20:16:12Z

crates/starknet-types-core/src/qm31/mod.rs

+//! A Cairo-like QM31 type.
+//!
+//! The QM31 type represents a Degree-4 extension in the Mersenne 31 field. This extension can be
+//! represented as two components of the Complex extension the Mersenne 31 field as follows ((a, b), (c, d)), where


of the Complex extension the Mersenne 31 field

It doesn't seem very clear, maybe a word is missing here?

Yes, I forgot to add an "in". Fix here: 6bad58f

gabrielbosio · 2025-08-22T20:16:17Z

crates/starknet-types-core/src/qm31/mod.rs

+//! The QM31 type represents a Degree-4 extension in the Mersenne 31 field. This extension can be
+//! represented as two components of the Complex extension the Mersenne 31 field as follows ((a, b), (c, d)), where
+//! a, b, c and d represent a value from the Mersenne 31 field, denotated as M31.
+//! If only a M31 was used by the verifier, then a 31 bit value wouldn't be enough to provide security


Suggested change

//! If only a M31 was used by the verifier, then a 31 bit value wouldn't be enough to provide security

//! If only an M31 was used by the verifier, then a 31 bit value wouldn't be enough to provide security

Done here: 6bad58f

gabrielbosio · 2025-08-22T20:17:38Z

crates/starknet-types-core/src/qm31/mod.rs

+//! If only a M31 was used by the verifier, then a 31 bit value wouldn't be enough to provide security
+//! to the verification. A QM31 not only provides an efficient arithmetic field, since it is composed of four M31 values, but
+//! also allows for a more secure level of verification as it offers a 124 bit value. By using this extension,
+//! the verifier is able to generate challeges with a proper level of randomness, ensuring the security of the protocol.


the verifier is able

What verifier? The Cairo one?

Suggested change

//! the verifier is able to generate challeges with a proper level of randomness, ensuring the security of the protocol.

//! the verifier is able to generate challenges with a proper level of randomness, ensuring the security of the protocol.

A verifier in general. A 31 bit value is not enough to provided security since the range of random values is too short and vulnerable to brute-force attacks

fixed typo here: 6bad58f. Also changed the verifier for a verifier as the comment aims to a verifier in general.

gabrielbosio · 2025-08-22T20:18:52Z

crates/starknet-types-core/src/qm31/mod.rs

+//! While the Cairo language's representation of QM31 consists of four `BoundedInt`s
+//! simulating a 31 bit value, this implementation uses four 32 bit values.


I would add the corresponding link to the cairo repo, at the end of this paragraph.

Done here: 6bad58f

gabrielbosio · 2025-08-22T20:22:29Z

crates/starknet-types-core/src/qm31/mod.rs

+//! The conversion to a Felt is done by using the four elements of the struct, refered to as coordinates, as bytes and then 
+//! parsed as a little endian value. For a more efficient Felt representation, each coordinate is stored as a 36 bit. Hence, 


The conversion to a Felt is done by using the four elements of the struct, refered to as coordinates, as bytes

It doesn't seem very clear. I would briefly explain what a coordinate is and then describe the Felt conversion. That way you don't have to define coordinates in the middle of the description of the conversion.

Done here: 035a87c

FrancoGiachetta added 6 commits August 11, 2025 18:46

Add QM31Felt

c569f44

fix tests and improve doc comments

529979c

format

b1551ba

add coords checking when converting from a felt

31bd701

fix clippy

725d4d0

Merge branch 'main' into add-qm31

3f219c1

FrancoGiachetta changed the title ~~Add qm31~~ Add QM31Felt implementation Aug 12, 2025

FrancoGiachetta added 3 commits August 12, 2025 13:02

add proper spacing

4f61521

Merge branch 'add-qm31' of github.com:lambdaclass/types-rs into add-qm31

2ce7637

make read_coordinates pub

97e1a99

FrancoGiachetta mentioned this pull request Aug 12, 2025

Move QM31 logic to types-rs repo lambdaclass/cairo-vm#2157

Open

FrancoGiachetta marked this pull request as ready for review August 12, 2025 18:24

FrancoGiachetta requested review from pefontana, dan-starkware and gabrielbosio as code owners August 12, 2025 18:24

fix clippy

a1b9664

FrancoGiachetta marked this pull request as draft August 12, 2025 20:33

FrancoGiachetta added 2 commits August 13, 2025 10:54

api restructure

1435e7d

Merge branch 'main' into add-qm31

f0fea9f

FrancoGiachetta marked this pull request as ready for review August 13, 2025 13:58

fix doc comment

176c1de

JulianGCalderon reviewed Aug 13, 2025

View reviewed changes

FrancoGiachetta added 2 commits August 14, 2025 10:18

change qm31 representation, remove outdated comments

21ec03e

return an error instead of panicking when trying to divide by zero

ddc19e7

JulianGCalderon reviewed Aug 14, 2025

View reviewed changes

FrancoGiachetta added 5 commits August 14, 2025 18:45

add test felt -> qm31 -> felt

a7691d7

fix doc comment

bb721e5

reduce felt with converting into qm31

0dc0d27

change From<QM31Felt> implementation + add test

5473a0f

update comments

7a64646

tdelabro requested changes Aug 20, 2025

View reviewed changes

crates/starknet-types-core/src/qm31/mod.rs Outdated Show resolved Hide resolved

crates/starknet-types-core/src/qm31/mod.rs Show resolved Hide resolved

FrancoGiachetta added 5 commits August 20, 2025 14:55

add docs on the algorithms used and fix typo

d8bbdb5

Merge branch 'main' into add-qm31

d0c0578

add docs on multiplication and inversion algorithms

dde739b

Merge branch 'add-qm31' of github.com:lambdaclass/types-rs into add-qm31

451d863

add docs on multiplication and inversion algorithms

06ed0d5

tdelabro requested a review from 0xLucqs August 20, 2025 22:14

0xLucqs reviewed Aug 21, 2025

View reviewed changes

FrancoGiachetta added 5 commits August 21, 2025 09:24

add more docs for pack_into_felt method

16893d8

change QM31 representation to u32 coordinates

020c0dc

add some more docs

10b7cd3

fix typo

f287335

format

fd1a9af

gabrielbosio requested changes Aug 21, 2025

View reviewed changes

change method inner to to_coordinates

edd3fa5

fix typo and clippy

8f0d2fc

FrancoGiachetta mentioned this pull request Aug 21, 2025

Replace QM31 implementation for the one in starknet-types-core lambdaclass/cairo-vm#2179

Draft

6 tasks

add general documentation

5c9512e

fix typo

b65e34b

tdelabro requested changes Aug 22, 2025

View reviewed changes

fix typos

7f3d6ef

JulianGCalderon mentioned this pull request Aug 22, 2025

Bump Lambdaworks to 0.12.0 #151

Open

gabrielbosio reviewed Aug 22, 2025

View reviewed changes

gabrielbosio requested changes Aug 22, 2025

View reviewed changes

FrancoGiachetta added 2 commits August 22, 2025 17:45

improve documentation and format

6bad58f

improve documentation

035a87c

FrancoGiachetta changed the title ~~Add QM31Felt implementation~~ Add QM31 implementation Aug 25, 2025

Merge branch 'main' into add-qm31

4ca76ca

	pub fn inner(&self) -> [u32; 4] {
	pub fn to_coordinates(&self) -> [u32; 4] {

	fn inner_u64(&self) -> [u64; 4] {
	fn to_coordinates_u64(&self) -> [u64; 4] {

	//! If only a M31 was used by the verifier, then a 31 bit value wouldn't be enough to provide security
	//! If only an M31 was used by the verifier, then a 31 bit value wouldn't be enough to provide security

	//! the verifier is able to generate challeges with a proper level of randomness, ensuring the security of the protocol.
	//! the verifier is able to generate challenges with a proper level of randomness, ensuring the security of the protocol.

		//! While the Cairo language's representation of QM31 consists of four `BoundedInt`s
		//! simulating a 31 bit value, this implementation uses four 32 bit values.

		//! The conversion to a Felt is done by using the four elements of the struct, refered to as coordinates, as bytes and then
		//! parsed as a little endian value. For a more efficient Felt representation, each coordinate is stored as a 36 bit. Hence,

Add QM31 implementation #149

Are you sure you want to change the base?

Add QM31 implementation #149

Uh oh!

Conversation

FrancoGiachetta commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Pull Request type

What is the current behavior?

What is the new behavior?

Does this introduce a breaking change?

Other information

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

0xLucqs Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FrancoGiachetta Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tdelabro commented Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FrancoGiachetta commented Aug 22, 2025

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!

Add `QM31` implementation #149

Add `QM31` implementation #149

FrancoGiachetta commented Aug 12, 2025 •

edited

Loading

0xLucqs Aug 21, 2025 •

edited

Loading

FrancoGiachetta Aug 21, 2025 •

edited

Loading

tdelabro commented Aug 21, 2025 •

edited

Loading

FrancoGiachetta Aug 22, 2025 •

edited

Loading