Add mod builtin

.github/workflows/rust.yml

@@ -251,7 +251,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        special_features: ["", "extensive_hints"]
+        special_features: ["", "extensive_hints", "mod_builtin"]
         target: [ test#1, test#2, test#3, test#4, test-no_std#1, test-no_std#2, test-no_std#3, test-no_std#4, test-wasm ]
     name: Run tests
     runs-on: ubuntu-22.04

CHANGELOG.md

@@ -2,6 +2,25 @@
 
 #### Upcoming Changes
 
+* feat(BREAKING): Add mod builtin [#1673](https://github.com/lambdaclass/cairo-vm/pull/1673)
+
+  Main Changes:
+  * Add the new `ModBuiltinRunner`, implementing the builtins `add_mod` & `mul_mod`
+  * Add temporary feature `mod_builtin` which adds `add_mod` & `mul_mod` to the `all_cairo` & `all_solidity` layouts so that the new builtins may be used in them. This feature will be removed once these builtins are properly added to the correct layouts
+  * Add method `VirtualMachine::fill_memory` in order to perform the new builtin's main logic from within hints
+  * Add hints to run arithmetic circuits using `add_mod` and/or `mul_mod` builtins
+
+  Other Changes:
+  * BREAKING: BuiltinRunner method signature change from
+  `air_private_input(&self, memory: &Memory) -> Vec<PrivateInput>` to `pub fn air_private_input(&self, segments: &MemorySegmentManager) -> Vec<PrivateInput>`
+  * Add `MayleRelocatable::sub_usize`
+  * Implement `Add<u32> for Relocatable`
+  * Add `Memory::get_usize`
+  * BREAKING: Clean up unused/duplicated code from builtins module:
+    * Remove unused method `get_memory_segment_addresses` from all builtin runners & the enum
+    * Remove empty implementations of `deduce_memory_cell` & `add_validation_rules` from all builtin runners
+    * Remove duplicated implementation of `final_stack` from all builtin runners except output and move it to the enum implementation
+
 * BREAKING: Remove `CairoRunner::add_additional_hash_builtin` & `VirtualMachine::disable_trace`[#1658](https://github.com/lambdaclass/cairo-vm/pull/1658)
 
 * feat: output builtin add_attribute method [#1691](https://github.com/lambdaclass/cairo-vm/pull/1691)

Makefile

@@ -49,6 +49,10 @@ PROOF_BENCH_DIR=cairo_programs/benchmarks
 PROOF_BENCH_FILES:=$(wildcard $(PROOF_BENCH_DIR)/*.cairo)
 PROOF_COMPILED_BENCHES:=$(patsubst $(PROOF_BENCH_DIR)/%.cairo, $(PROOF_BENCH_DIR)/%.json, $(PROOF_BENCH_FILES))
 
+MOD_BUILTIN_TEST_PROOF_DIR=cairo_programs/mod_builtin_feature/proof
+MOD_BUILTIN_TEST_PROOF_FILES:=$(wildcard $(MOD_BUILTIN_TEST_PROOF_DIR)/*.cairo)
+COMPILED_MOD_BUILTIN_PROOF_TESTS:=$(patsubst $(MOD_BUILTIN_TEST_PROOF_DIR)/%.cairo, $(MOD_BUILTIN_TEST_PROOF_DIR)/%.json, $(MOD_BUILTIN_TEST_PROOF_FILES))
+
 $(TEST_PROOF_DIR)/%.json: $(TEST_PROOF_DIR)/%.cairo
 	cairo-compile --cairo_path="$(TEST_PROOF_DIR):$(PROOF_BENCH_DIR)" $< --output $@ --proof_mode
 
@@ -61,6 +65,9 @@ $(TEST_PROOF_DIR)/%.trace $(TEST_PROOF_DIR)/%.memory $(TEST_PROOF_DIR)/%.air_pub
 $(PROOF_BENCH_DIR)/%.json: $(PROOF_BENCH_DIR)/%.cairo
 	cairo-compile --cairo_path="$(TEST_PROOF_DIR):$(PROOF_BENCH_DIR)" $< --output $@ --proof_mode
 
+$(MOD_BUILTIN_TEST_PROOF_DIR)/%.json: $(MOD_BUILTIN_TEST_PROOF_DIR)/%.cairo
+	cairo-compile --cairo_path="$(MOD_BUILTIN_TEST_PROOF_DIR):$(MOD_BUILTIN_TEST_PROOF_DIR)" $< --output $@ --proof_mode
+
 # ======================
 # Run without proof mode
 # ======================
@@ -87,6 +94,10 @@ PRINT_TEST_DIR=cairo_programs/print_feature
 PRINT_TEST_FILES:=$(wildcard $(PRINT_TEST_DIR)/*.cairo)
 COMPILED_PRINT_TESTS:=$(patsubst $(PRINT_TEST_DIR)/%.cairo, $(PRINT_TEST_DIR)/%.json, $(PRINT_TEST_FILES))
 
+MOD_BUILTIN_TEST_DIR=cairo_programs/mod_builtin_feature
+MOD_BUILTIN_TEST_FILES:=$(wildcard $(MOD_BUILTIN_TEST_DIR)/*.cairo)
+COMPILED_MOD_BUILTIN_TESTS:=$(patsubst $(MOD_BUILTIN_TEST_DIR)/%.cairo, $(MOD_BUILTIN_TEST_DIR)/%.json, $(MOD_BUILTIN_TEST_FILES))
+
 NORETROCOMPAT_DIR:=cairo_programs/noretrocompat
 NORETROCOMPAT_FILES:=$(wildcard $(NORETROCOMPAT_DIR)/*.cairo)
 COMPILED_NORETROCOMPAT_TESTS:=$(patsubst $(NORETROCOMPAT_DIR)/%.cairo, $(NORETROCOMPAT_DIR)/%.json, $(NORETROCOMPAT_FILES))
@@ -228,8 +239,8 @@ run:
 check:
 	cargo check
 
-cairo_test_programs: $(COMPILED_TESTS) $(COMPILED_BAD_TESTS) $(COMPILED_NORETROCOMPAT_TESTS) $(COMPILED_PRINT_TESTS)
-cairo_proof_programs: $(COMPILED_PROOF_TESTS)
+cairo_test_programs: $(COMPILED_TESTS) $(COMPILED_BAD_TESTS) $(COMPILED_NORETROCOMPAT_TESTS) $(COMPILED_PRINT_TESTS) $(COMPILED_MOD_BUILTIN_TESTS)
+cairo_proof_programs: $(COMPILED_PROOF_TESTS) $(COMPILED_MOD_BUILTIN_PROOF_TESTS)
 cairo_bench_programs: $(COMPILED_BENCHES)
 cairo_1_test_contracts: $(CAIRO_1_COMPILED_CASM_CONTRACTS)
 cairo_2_test_contracts: $(CAIRO_2_COMPILED_CASM_CONTRACTS)

cairo-vm-cli/Cargo.toml

@@ -24,3 +24,4 @@ rstest = "0.17.0"
 default = ["with_mimalloc"]
 with_mimalloc = ["cairo-vm/with_mimalloc", "dep:mimalloc"]
 with_tracer = ["cairo-vm/with_tracer", "cairo-vm-tracer"]
+mod_builtin = ["cairo-vm/mod_builtin"]

cairo_programs/mod_builtin_feature/common/modulo.cairo

@@ -0,0 +1,124 @@
+// This file is a copy of common/modulo.cairo + added structs from common/cairo_builtins.cairo so that we can run modulo programs in CI
+from starkware.cairo.common.math import safe_div, unsigned_div_rem
+from starkware.cairo.common.registers import get_label_location
+
+// Represents a 384-bit unsigned integer d0 + 2**96 * d1 + 2**192 * d2 + 2**288 * d3
+// where each di is in [0, 2**96).
+struct UInt384 {
+    d0: felt,
+    d1: felt,
+    d2: felt,
+    d3: felt,
+}
+
+// Specifies the Add and Mul Mod builtins memory structure.
+struct ModBuiltin {
+    // The modulus.
+    p: UInt384,
+    // A pointer to input values, the intermediate results and the output.
+    values_ptr: UInt384*,
+    // A pointer to offsets inside the values array, defining the circuit.
+    // The offsets array should contain 3 * n elements.
+    offsets_ptr: felt*,
+    // The number of operations to perform.
+    n: felt,
+}
+
+const BATCH_SIZE = 1;
+
+// Returns the smallest felt 0 <= q < rc_bound such that x <= q * y.
+func div_ceil{range_check_ptr}(x: felt, y: felt) -> felt {
+    let (q, r) = unsigned_div_rem(x, y);
+    if (r != 0) {
+        return q + 1;
+    } else {
+        return q;
+    }
+}
+
+// Fills the first instance of the add_mod and mul_mod builtins and calls the fill_memory hint to
+// fill the rest of the instances and the missing values in the values table.
+//
+// This function uses a hardcoded value of batch_size=8, and asserts the instance definitions use
+// the same value.
+func run_mod_p_circuit_with_large_batch_size{
+    range_check_ptr, add_mod_ptr: ModBuiltin*, mul_mod_ptr: ModBuiltin*
+}(
+    p: UInt384,
+    values_ptr: UInt384*,
+    add_mod_offsets_ptr: felt*,
+    add_mod_n: felt,
+    mul_mod_offsets_ptr: felt*,
+    mul_mod_n: felt,
+) {
+    const BATCH_SIZE = 8;
+    let add_mod_n_instances = div_ceil(add_mod_n, BATCH_SIZE);
+    assert add_mod_ptr[0] = ModBuiltin(
+        p=p,
+        values_ptr=values_ptr,
+        offsets_ptr=add_mod_offsets_ptr,
+        n=add_mod_n_instances * BATCH_SIZE,
+    );
+
+    let mul_mod_n_instances = div_ceil(mul_mod_n, BATCH_SIZE);
+    assert mul_mod_ptr[0] = ModBuiltin(
+        p=p,
+        values_ptr=values_ptr,
+        offsets_ptr=mul_mod_offsets_ptr,
+        n=mul_mod_n_instances * BATCH_SIZE,
+    );
+
+    %{
+        from starkware.cairo.lang.builtins.modulo.mod_builtin_runner import ModBuiltinRunner
+        assert builtin_runners["add_mod_builtin"].instance_def.batch_size == ids.BATCH_SIZE
+        assert builtin_runners["mul_mod_builtin"].instance_def.batch_size == ids.BATCH_SIZE
+
+        ModBuiltinRunner.fill_memory(
+            memory=memory,
+            add_mod=(ids.add_mod_ptr.address_, builtin_runners["add_mod_builtin"], ids.add_mod_n),
+            mul_mod=(ids.mul_mod_ptr.address_, builtin_runners["mul_mod_builtin"], ids.mul_mod_n),
+        )
+    %}
+
+    let add_mod_ptr = &add_mod_ptr[add_mod_n_instances];
+    let mul_mod_ptr = &mul_mod_ptr[mul_mod_n_instances];
+    return ();
+}
+
+// Fills the first instance of the add_mod and mul_mod builtins and calls the fill_memory hint to
+// fill the rest of the instances and the missing values in the values table.
+//
+// This function uses a hardcoded value of batch_size=1, and asserts the instance definitions use
+// the same value.
+func run_mod_p_circuit{add_mod_ptr: ModBuiltin*, mul_mod_ptr: ModBuiltin*}(
+    p: UInt384,
+    values_ptr: UInt384*,
+    add_mod_offsets_ptr: felt*,
+    add_mod_n: felt,
+    mul_mod_offsets_ptr: felt*,
+    mul_mod_n: felt,
+) {
+    assert add_mod_ptr[0] = ModBuiltin(
+        p=p, values_ptr=values_ptr, offsets_ptr=add_mod_offsets_ptr, n=add_mod_n
+    );
+
+    assert mul_mod_ptr[0] = ModBuiltin(
+        p=p, values_ptr=values_ptr, offsets_ptr=mul_mod_offsets_ptr, n=mul_mod_n
+    );
+
+    %{
+        from starkware.cairo.lang.builtins.modulo.mod_builtin_runner import ModBuiltinRunner
+        assert builtin_runners["add_mod_builtin"].instance_def.batch_size == 1
+        assert builtin_runners["mul_mod_builtin"].instance_def.batch_size == 1
+
+        ModBuiltinRunner.fill_memory(
+            memory=memory,
+            add_mod=(ids.add_mod_ptr.address_, builtin_runners["add_mod_builtin"], ids.add_mod_n),
+            mul_mod=(ids.mul_mod_ptr.address_, builtin_runners["mul_mod_builtin"], ids.mul_mod_n),
+        )
+    %}
+
+    let add_mod_ptr = &add_mod_ptr[add_mod_n];
+    let mul_mod_ptr = &mul_mod_ptr[mul_mod_n];
+    return ();
+}

cairo_programs/mod_builtin_feature/mod_builtin.cairo

@@ -0,0 +1,53 @@
+%builtins range_check add_mod mul_mod
+// TODO: Import directly from common library once released
+from cairo_programs.mod_builtin_feature.common.modulo import ModBuiltin, UInt384, run_mod_p_circuit
+// from starkware.common.cairo_builtins import ModBuiltin, UInt384
+// from starkware.cairo.common.modulo import run_mod_p_circuit
+from starkware.cairo.common.registers import get_label_location
+from starkware.cairo.common.alloc import alloc
+
+func main{range_check_ptr, add_mod_ptr: ModBuiltin*, mul_mod_ptr: ModBuiltin*}() {
+    alloc_locals;
+
+    let p = UInt384(d0=1, d1=1, d2=0, d3=0);
+    let x1 = UInt384(d0=1, d1=0, d2=0, d3=0);
+    let x2 = UInt384(d0=2, d1=1, d2=0, d3=0);
+    let x3 = UInt384(d0=2, d1=0, d2=0, d3=0);
+    let res = UInt384(d0=1, d1=0, d2=0, d3=0);
+
+    let (local values_arr: UInt384*) = alloc();
+    assert values_arr[0] = x1;
+    assert values_arr[1] = x2;
+    assert values_arr[2] = x3;
+    assert values_arr[7] = res;
+
+    let (local add_mod_offsets_arr: felt*) = alloc();
+    assert add_mod_offsets_arr[0] = 0;   // x1
+    assert add_mod_offsets_arr[1] = 12;  // x2 - x1
+    assert add_mod_offsets_arr[2] = 4;   // x2
+    assert add_mod_offsets_arr[3] = 16;  // (x2 - x1) * x3
+    assert add_mod_offsets_arr[4] = 20;  // x1 * x3
+    assert add_mod_offsets_arr[5] = 24;  // (x2 - x1) * x3 + x1 * x3
+
+    let (local mul_mod_offsets_arr: felt*) = alloc();
+    assert mul_mod_offsets_arr[0] = 12;  // x2 - x1
+    assert mul_mod_offsets_arr[1] = 8;   // x3
+    assert mul_mod_offsets_arr[2] = 16;  // (x2 - x1) * x3
+    assert mul_mod_offsets_arr[3] = 0;   // x1
+    assert mul_mod_offsets_arr[4] = 8;   // x3
+    assert mul_mod_offsets_arr[5] = 20;  // x1 * x3
+    assert mul_mod_offsets_arr[6] = 8;   // x3
+    assert mul_mod_offsets_arr[7] = 28;  // ((x2 - x1) * x3 + x1 * x3) / x3 = x2 mod p
+    assert mul_mod_offsets_arr[8] = 24;  // (x2 - x1) * x3 + x1 * x3
+
+    run_mod_p_circuit(
+        p=p,
+        values_ptr=values_arr,
+        add_mod_offsets_ptr=add_mod_offsets_arr,
+        add_mod_n=2,
+        mul_mod_offsets_ptr=mul_mod_offsets_arr,
+        mul_mod_n=3,
+    );
+
+    return ();
+}

cairo_programs/mod_builtin_feature/mod_builtin_failure.cairo

@@ -0,0 +1,53 @@
+%builtins range_check add_mod mul_mod
+// TODO: Import directly from common library once released
+from cairo_programs.mod_builtin_feature.common.modulo import ModBuiltin, UInt384, run_mod_p_circuit
+// from starkware.common.cairo_builtins import ModBuiltin, UInt384
+// from starkware.cairo.common.modulo import run_mod_p_circuit
+from starkware.cairo.common.registers import get_label_location
+from starkware.cairo.common.alloc import alloc
+
+func main{range_check_ptr, add_mod_ptr: ModBuiltin*, mul_mod_ptr: ModBuiltin*}() {
+    alloc_locals;
+
+    let p = UInt384(d0=1, d1=1, d2=0, d3=0);
+    let x1 = UInt384(d0=1, d1=0, d2=0, d3=0);
+    let x2 = UInt384(d0=2, d1=1, d2=0, d3=0);
+    let x3 = UInt384(d0=2, d1=0, d2=0, d3=0);
+    let res = UInt384(d0=2, d1=0, d2=0, d3=0);
+
+    let (local values_arr: UInt384*) = alloc();
+    assert values_arr[0] = x1;
+    assert values_arr[1] = x2;
+    assert values_arr[2] = x3;
+    assert values_arr[7] = res;
+
+    let (local add_mod_offsets_arr: felt*) = alloc();
+    assert add_mod_offsets_arr[0] = 0;   // x1
+    assert add_mod_offsets_arr[1] = 12;  // x2 - x1
+    assert add_mod_offsets_arr[2] = 4;   // x2
+    assert add_mod_offsets_arr[3] = 16;  // (x2 - x1) * x3
+    assert add_mod_offsets_arr[4] = 20;  // x1 * x3
+    assert add_mod_offsets_arr[5] = 24;  // (x2 - x1) * x3 + x1 * x3
+
+    let (local mul_mod_offsets_arr: felt*) = alloc();
+    assert mul_mod_offsets_arr[0] = 12;  // x2 - x1
+    assert mul_mod_offsets_arr[1] = 8;   // x3
+    assert mul_mod_offsets_arr[2] = 16;  // (x2 - x1) * x3
+    assert mul_mod_offsets_arr[3] = 0;   // x1
+    assert mul_mod_offsets_arr[4] = 8;   // x3
+    assert mul_mod_offsets_arr[5] = 20;  // x1 * x3
+    assert mul_mod_offsets_arr[6] = 8;   // x3
+    assert mul_mod_offsets_arr[7] = 28;  // ((x2 - x1) * x3 + x1 * x3) / x3 = x2 mod p
+    assert mul_mod_offsets_arr[8] = 24;  // (x2 - x1) * x3 + x1 * x3
+
+    run_mod_p_circuit(
+        p=p,
+        values_ptr=values_arr,
+        add_mod_offsets_ptr=add_mod_offsets_arr,
+        add_mod_n=2,
+        mul_mod_offsets_ptr=mul_mod_offsets_arr,
+        mul_mod_n=3,
+    );
+
+    return ();
+}

cairo_programs/mod_builtin_feature/mod_builtin_large_batch_size.cairo

@@ -0,0 +1,53 @@
+%builtins range_check add_mod mul_mod
+// TODO: Import directly from common library once released
+from cairo_programs.mod_builtin_feature.common.modulo import ModBuiltin, UInt384, run_mod_p_circuit_with_large_batch_size
+// from starkware.common.cairo_builtins import ModBuiltin, UInt384
+// from starkware.cairo.common.modulo import run_mod_p_circuit_with_large_batch_size
+from starkware.cairo.common.registers import get_label_location
+from starkware.cairo.common.alloc import alloc
+
+func main{range_check_ptr, add_mod_ptr: ModBuiltin*, mul_mod_ptr: ModBuiltin*}() {
+    alloc_locals;
+
+    let p = UInt384(d0=1, d1=1, d2=0, d3=0);
+    let x1 = UInt384(d0=1, d1=0, d2=0, d3=0);
+    let x2 = UInt384(d0=2, d1=1, d2=0, d3=0);
+    let x3 = UInt384(d0=2, d1=0, d2=0, d3=0);
+    let res = UInt384(d0=1, d1=0, d2=0, d3=0);
+
+    let (local values_arr: UInt384*) = alloc();
+    assert values_arr[0] = x1;
+    assert values_arr[1] = x2;
+    assert values_arr[2] = x3;
+    assert values_arr[7] = res;
+
+    let (local add_mod_offsets_arr: felt*) = alloc();
+    assert add_mod_offsets_arr[0] = 0;   // x1
+    assert add_mod_offsets_arr[1] = 12;  // x2 - x1
+    assert add_mod_offsets_arr[2] = 4;   // x2
+    assert add_mod_offsets_arr[3] = 16;  // (x2 - x1) * x3
+    assert add_mod_offsets_arr[4] = 20;  // x1 * x3
+    assert add_mod_offsets_arr[5] = 24;  // (x2 - x1) * x3 + x1 * x3
+
+    let (local mul_mod_offsets_arr: felt*) = alloc();
+    assert mul_mod_offsets_arr[0] = 12;  // x2 - x1
+    assert mul_mod_offsets_arr[1] = 8;   // x3
+    assert mul_mod_offsets_arr[2] = 16;  // (x2 - x1) * x3
+    assert mul_mod_offsets_arr[3] = 0;   // x1
+    assert mul_mod_offsets_arr[4] = 8;   // x3
+    assert mul_mod_offsets_arr[5] = 20;  // x1 * x3
+    assert mul_mod_offsets_arr[6] = 8;   // x3
+    assert mul_mod_offsets_arr[7] = 28;  // ((x2 - x1) * x3 + x1 * x3) / x3 = x2 mod p
+    assert mul_mod_offsets_arr[8] = 24;  // (x2 - x1) * x3 + x1 * x3
+
+    run_mod_p_circuit_with_large_batch_size(
+        p=p,
+        values_ptr=values_arr,
+        add_mod_offsets_ptr=add_mod_offsets_arr,
+        add_mod_n=2,
+        mul_mod_offsets_ptr=mul_mod_offsets_arr,
+        mul_mod_n=3,
+    );
+
+    return ();
+}