add qm31 operations to VM

ohad-nir-starkware · ohad-nir-starkware · commit eb339d8b82a3 · 2025-02-10T20:49:49.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 #### Upcoming Changes
 
+* feat: implement an opcode that computes QM31 arithmetics (add, sub, mul, div) in the VM [#1938](https://github.com/lambdaclass/cairo-vm/pull/1938)
+
 * feat: add functions that compute packed reduced qm31 arithmetics to `math_utils` [#1944](https://github.com/lambdaclass/cairo-vm/pull/1944)
 
 * feat: set `encoded_instruction` to be u128 for opcode_extensions to come [#1940](https://github.com/lambdaclass/cairo-vm/pull/1940)
diff --git a/cairo_programs/stwo_exclusive_programs/qm31_opcodes_test.cairo b/cairo_programs/stwo_exclusive_programs/qm31_opcodes_test.cairo
@@ -0,0 +1,174 @@
+from starkware.cairo.common.alloc import alloc
+from starkware.cairo.common.bool import FALSE, TRUE
+
+func main{}() {
+    alloc_locals;
+
+    let (local qm31_op0_coordinates) = alloc();
+    assert qm31_op0_coordinates[0] =  1414213562;
+    assert qm31_op0_coordinates[1] =  1732050807;
+    assert qm31_op0_coordinates[2] =  1618033988;
+    assert qm31_op0_coordinates[3] =  1234567890;
+    let qm31_op0 = qm31_op0_coordinates[0] + qm31_op0_coordinates[1]*(2**36) + qm31_op0_coordinates[2]*(2**72) + qm31_op0_coordinates[3]*(2**108);
+
+    let (local qm31_op1_coordinates) = alloc();
+    assert qm31_op1_coordinates[0] =  1259921049;
+    assert qm31_op1_coordinates[1] =  1442249570;
+    assert qm31_op1_coordinates[2] =  1847759065;
+    assert qm31_op1_coordinates[3] =  2094551481;
+    let qm31_op1 = qm31_op1_coordinates[0] + qm31_op1_coordinates[1]*(2**36) + qm31_op1_coordinates[2]*(2**72) + qm31_op1_coordinates[3]*(2**108);
+
+    let (local qm31_add_dst_coordinates) = alloc();
+    assert qm31_add_dst_coordinates[0] =  526650964;
+    assert qm31_add_dst_coordinates[1] =  1026816730;
+    assert qm31_add_dst_coordinates[2] =  1318309406;
+    assert qm31_add_dst_coordinates[3] =  1181635724;
+    let qm31_add_dst = qm31_add_dst_coordinates[0] + qm31_add_dst_coordinates[1]*(2**36) + qm31_add_dst_coordinates[2]*(2**72) + qm31_add_dst_coordinates[3]*(2**108);
+
+    let (local qm31_mul_dst_coordinates) = alloc();
+    assert qm31_mul_dst_coordinates[0] =  947980980;
+    assert qm31_mul_dst_coordinates[1] =  1510986506;
+    assert qm31_mul_dst_coordinates[2] =  623360030;
+    assert qm31_mul_dst_coordinates[3] =  1260310989;
+    let qm31_mul_dst = qm31_mul_dst_coordinates[0] + qm31_mul_dst_coordinates[1]*(2**36) + qm31_mul_dst_coordinates[2]*(2**72) + qm31_mul_dst_coordinates[3]*(2**108);
+
+    let runner_output_mul_dst = run_qm31_operation_get_dst(is_mul=TRUE, op0=qm31_op0, op1=qm31_op1);
+    assert runner_output_mul_dst = qm31_mul_dst;
+    let runner_output_add_dst = run_qm31_operation_get_dst(is_mul=FALSE, op0=qm31_op0, op1=qm31_op1);
+    assert runner_output_add_dst = qm31_add_dst;
+
+    let runner_output_mul_op1 = run_qm31_operation_get_op1(is_mul=TRUE, dst=qm31_mul_dst, op0=qm31_op0);
+    assert runner_output_mul_op1 = qm31_op1;
+    let runner_output_add_op1 = run_qm31_operation_get_op1(is_mul=FALSE, dst=qm31_add_dst, op0=qm31_op0);
+    assert runner_output_add_op1 = qm31_op1;
+
+    let runner_output_mul_op0 = run_qm31_operation_get_op0(is_mul=TRUE, dst=qm31_mul_dst, op1=qm31_op1);
+    assert runner_output_mul_op0 = qm31_op0;
+    let runner_output_add_op0 = run_qm31_operation_get_op0(is_mul=FALSE, dst=qm31_add_dst, op1=qm31_op1);
+    assert runner_output_add_op0 = qm31_op0;
+
+    return ();
+}
+
+func run_qm31_operation_get_dst(
+    is_mul: felt,
+    op0: felt,
+    op1: felt,
+) -> felt {
+    let offset0 = 2**15;
+    let offset1 = (2**15)-4;
+    let offset2 = (2**15)-3;
+    
+    let flag_dst_base_fp = 0;
+    let flag_op0_base_fp = 1;
+    let flag_op1_imm = 0;
+    let flag_op1_base_fp = 1;
+    let flag_op1_base_ap = 0;
+    let flag_res_add = 0;
+    let flag_res_mul = is_mul;
+    let flag_PC_update_jump = 0;
+    let flag_PC_update_jump_rel = 0;
+    let flag_PC_update_jnz = 0;
+    let flag_ap_update_add = 0;
+    let flag_ap_update_add_1 = 0;
+    let flag_opcode_call = 0;
+    let flag_opcode_ret = 0;
+    let flag_opcode_assert_eq = 1;
+
+    let flag_num_qm31_add = flag_dst_base_fp+flag_op0_base_fp*(2**1)+flag_op1_imm*(2**2)+flag_op1_base_fp*(2**3)+flag_op1_base_ap*(2**4)+0*(2**6)+flag_opcode_assert_eq*(2**14);
+    let flag_num_qm31_mul = flag_dst_base_fp+flag_op0_base_fp*(2**1)+flag_op1_imm*(2**2)+flag_op1_base_fp*(2**3)+flag_op1_base_ap*(2**4)+1*(2**6)+flag_opcode_assert_eq*(2**14);
+    let qm31_opcode_extension_num = 3;
+    let qm31_add_instruction_num = offset0 + offset1*(2**16) + offset2*(2**32) + flag_num_qm31_add*(2**48) + qm31_opcode_extension_num*(2**63);
+    let qm31_mul_instruction_num = offset0 + offset1*(2**16) + offset2*(2**32) + flag_num_qm31_mul*(2**48) + qm31_opcode_extension_num*(2**63);
+    static_assert qm31_mul_instruction_num==32302772004019011584;
+    static_assert qm31_add_instruction_num==32284757605509529600;
+
+    if (is_mul == TRUE) {
+        dw 32302772004019011584;
+        return [ap];
+    }
+    dw 32284757605509529600;
+    return [ap];
+}
+
+func run_qm31_operation_get_op1(
+    is_mul: felt,
+    dst: felt,
+    op0: felt,
+) -> felt {
+    let offset0 = (2**15)-4;
+    let offset1 = (2**15)-3;
+    let offset2 = 2**15;
+    
+    let flag_dst_base_fp = 1;
+    let flag_op0_base_fp = 1;
+    let flag_op1_imm = 0;
+    let flag_op1_base_fp = 0;
+    let flag_op1_base_ap = 1;
+    let flag_res_add = 0;
+    let flag_res_mul = is_mul;
+    let flag_PC_update_jump = 0;
+    let flag_PC_update_jump_rel = 0;
+    let flag_PC_update_jnz = 0;
+    let flag_ap_update_add = 0;
+    let flag_ap_update_add_1 = 0;
+    let flag_opcode_call = 0;
+    let flag_opcode_ret = 0;
+    let flag_opcode_assert_eq = 1;
+
+    let flag_num_qm31_add = flag_dst_base_fp+flag_op0_base_fp*(2**1)+flag_op1_imm*(2**2)+flag_op1_base_fp*(2**3)+flag_op1_base_ap*(2**4)+0*(2**6)+flag_opcode_assert_eq*(2**14);
+    let flag_num_qm31_mul = flag_dst_base_fp+flag_op0_base_fp*(2**1)+flag_op1_imm*(2**2)+flag_op1_base_fp*(2**3)+flag_op1_base_ap*(2**4)+1*(2**6)+flag_opcode_assert_eq*(2**14);
+    let qm31_opcode_extension_num = 3;
+    let qm31_add_instruction_num = offset0 + offset1*(2**16) + offset2*(2**32) + flag_num_qm31_add*(2**48) + qm31_opcode_extension_num*(2**63);
+    let qm31_mul_instruction_num = offset0 + offset1*(2**16) + offset2*(2**32) + flag_num_qm31_mul*(2**48) + qm31_opcode_extension_num*(2**63);
+    static_assert qm31_mul_instruction_num==32305305291694374908;
+    static_assert qm31_add_instruction_num==32287290893184892924;
+
+    if (is_mul == TRUE) {
+        dw 32305305291694374908;
+        return [ap];
+    }
+    dw 32287290893184892924;
+    return [ap];
+}
+
+func run_qm31_operation_get_op0(
+    is_mul: felt,
+    dst: felt,
+    op1: felt,
+) -> felt {
+    let offset0 = (2**15)-4;
+    let offset1 = 2**15;
+    let offset2 = (2**15)-3;
+    
+    let flag_dst_base_fp = 1;
+    let flag_op0_base_fp = 0;
+    let flag_op1_imm = 0;
+    let flag_op1_base_fp = 1;
+    let flag_op1_base_ap = 0;
+    let flag_res_add = 0;
+    let flag_res_mul = is_mul;
+    let flag_PC_update_jump = 0;
+    let flag_PC_update_jump_rel = 0;
+    let flag_PC_update_jnz = 0;
+    let flag_ap_update_add = 0;
+    let flag_ap_update_add_1 = 0;
+    let flag_opcode_call = 0;
+    let flag_opcode_ret = 0;
+    let flag_opcode_assert_eq = 1;
+
+    let flag_num_qm31_add = flag_dst_base_fp+flag_op0_base_fp*(2**1)+flag_op1_imm*(2**2)+flag_op1_base_fp*(2**3)+flag_op1_base_ap*(2**4)+0*(2**6)+flag_opcode_assert_eq*(2**14);
+    let flag_num_qm31_mul = flag_dst_base_fp+flag_op0_base_fp*(2**1)+flag_op1_imm*(2**2)+flag_op1_base_fp*(2**3)+flag_op1_base_ap*(2**4)+1*(2**6)+flag_opcode_assert_eq*(2**14);
+    let qm31_opcode_extension_num = 3;
+    let qm31_add_instruction_num = offset0 + offset1*(2**16) + offset2*(2**32) + flag_num_qm31_add*(2**48) + qm31_opcode_extension_num*(2**63);
+    let qm31_mul_instruction_num = offset0 + offset1*(2**16) + offset2*(2**32) + flag_num_qm31_mul*(2**48) + qm31_opcode_extension_num*(2**63);
+    static_assert qm31_mul_instruction_num==32302490529042563068;
+    static_assert qm31_add_instruction_num==32284476130533081084;
+
+    if (is_mul == TRUE) {
+        dw 32302490529042563068;
+        return [ap];
+    }
+    dw 32284476130533081084;
+    return [ap];
+}
diff --git a/vm/src/tests/cairo_run_test.rs b/vm/src/tests/cairo_run_test.rs
@@ -568,6 +568,14 @@ fn blake2s_integration_tests() {
     run_program_simple(program_data.as_slice());
 }
 
+#[test]
+#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
+fn qm31_opcodes_test() {
+    let program_data =
+        include_bytes!("../../../cairo_programs/stwo_exclusive_programs/qm31_opcodes_test.json");
+    run_program_simple(program_data.as_slice());
+}
+
 #[test]
 #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
 fn relocate_segments() {
diff --git a/vm/src/types/instruction.rs b/vm/src/types/instruction.rs
@@ -80,6 +80,7 @@ pub enum Opcode {
 #[derive(Clone, Debug, Copy, PartialEq, Eq)]
 pub enum OpcodeExtension {
     Stone,
+    QM31Operations,
 }
 
 impl Instruction {
diff --git a/vm/src/vm/decoding/decoder.rs b/vm/src/vm/decoding/decoder.rs
@@ -105,6 +105,16 @@ pub fn decode_instruction(encoded_instr: u128) -> Result<Instruction, VirtualMac
 
     let opcode_extension = match opcode_extension_num {
         0 => OpcodeExtension::Stone,
+        3 => {
+            if res == Res::Add
+                || (op1_addr != Op1Addr::FP && op1_addr != Op1Addr::AP)
+                || pc_update != PcUpdate::Regular
+                || opcode != Opcode::AssertEq
+            {
+                return Err(VirtualMachineError::InvalidQM31AddMulFlags(flags));
+            }
+            OpcodeExtension::QM31Operations
+        }
         _ => {
             return Err(VirtualMachineError::InvalidOpcodeExtension(
                 opcode_extension_num,
diff --git a/vm/src/vm/errors/vm_errors.rs b/vm/src/vm/errors/vm_errors.rs
@@ -62,6 +62,10 @@ pub enum VirtualMachineError {
         "Failed to compute Res.MUL: Could not complete computation of non pure values {} * {}", (*.0).0, (*.0).1
     )]
     ComputeResRelocatableMul(Box<(MaybeRelocatable, MaybeRelocatable)>),
+    #[error(
+        "Failed to compute Res.ADD for QM31Operations: Could not complete computation of non pure values {} * {}", (*.0).0, (*.0).1
+    )]
+    ComputeResRelocatableQM31Add(Box<(MaybeRelocatable, MaybeRelocatable)>),
     #[error("Couldn't compute operand {}. Unknown value for memory cell {}", (*.0).0, (*.0).1)]
     FailedToComputeOperands(Box<(String, Relocatable)>),
     #[error("An ASSERT_EQ instruction failed: {} != {}.", (*.0).0, (*.0).1)]
@@ -138,6 +142,8 @@ pub enum VirtualMachineError {
     RelocationNotFound(usize),
     #[error("{} batch size is not {}", (*.0).0, (*.0).1)]
     ModBuiltinBatchSize(Box<(BuiltinName, usize)>),
+    #[error("QM31 add mul opcode invalid flags {0}")]
+    InvalidQM31AddMulFlags(u128),
 }
 
 #[cfg(test)]
diff --git a/vm/src/vm/vm_core.rs b/vm/src/vm/vm_core.rs

Original file line number	Diff line number	Diff line change
`@@ -80,6 +80,7 @@ pub enum Opcode {`
`80`	`80`	`#[derive(Clone, Debug, Copy, PartialEq, Eq)]`
`81`	`81`	`pub enum OpcodeExtension {`
`82`	`82`	`Stone,`
	`83`	`+ QM31Operations,`
`83`	`84`	`}`
`84`	`85`
`85`	`86`	`impl Instruction {`