signoff!: u32::safe_mul

BREAKING CHANGE: Remove the implementation of `DeprecatedSnippet` for
`u32::safe_mul::SafeMul`, implement `BasicSnippet` directly.

Author: jan-ferdinand

tasm-lib/benchmarks/tasmlib_arithmetic_u32_safe_mul.json

@@ -15,7 +15,7 @@
     "benchmark_result": {
       "clock_cycle_count": 10,
       "hash_table_height": 12,
-      "u32_table_height": 32,
+      "u32_table_height": 33,
       "op_stack_table_height": 7,
       "ram_table_height": 0
     },

tasm-lib/src/arithmetic/u32/safe_mul.rs

@@ -1,192 +1,142 @@
-use rand::prelude::*;
+use std::collections::HashMap;
+
 use triton_vm::prelude::*;
 
-use crate::empty_stack;
 use crate::prelude::*;
-use crate::traits::deprecated_snippet::DeprecatedSnippet;
-use crate::InitVmState;
-
-/// If the inputs, are valid u32s, then the output is guaranteed to be to.
-/// Crashes on overflow.
-#[derive(Clone, Debug)]
+use crate::traits::basic_snippet::Reviewer;
+use crate::traits::basic_snippet::SignOffFingerprint;
+
+/// Multiply two `u32`s and crash on overflow.
+///
+/// ### Behavior
+///
+/// ```text
+/// BEFORE: _ [right: 32] [left: u32]
+/// AFTER:  _ [left · right: u32]
+/// ```
+///
+/// ### Preconditions
+///
+/// - all input arguments are properly [`BFieldCodec`] encoded
+/// - the product of `left` and `right` is less than or equal to [`u32::MAX`]
+///
+/// ### Postconditions
+///
+/// - the output is the product of the input
+/// - the output is properly [`BFieldCodec`] encoded
+#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash)]
 pub struct SafeMul;
 
-impl DeprecatedSnippet for SafeMul {
-    fn entrypoint_name(&self) -> String {
-        "tasmlib_arithmetic_u32_safe_mul".to_string()
-    }
-
-    fn input_field_names(&self) -> Vec<String> {
-        vec!["lhs".to_string(), "rhs".to_string()]
-    }
-
-    fn input_types(&self) -> Vec<DataType> {
-        vec![DataType::U32, DataType::U32]
-    }
-
-    fn output_field_names(&self) -> Vec<String> {
-        vec!["lhs * rhs".to_string()]
-    }
-
-    fn output_types(&self) -> Vec<DataType> {
-        vec![DataType::U32]
-    }
-
-    fn stack_diff(&self) -> isize {
-        -1
-    }
-
-    fn function_code(&self, _library: &mut crate::library::Library) -> String {
-        let entrypoint = self.entrypoint_name();
-        format!(
-            "
-                // BEFORE: _ rhs lhs
-                // AFTER:  _ (lhs * rhs)
-                {entrypoint}:
-                    mul
-                    dup 0  // _ (lhs * rhs) (lhs * rhs)
-                    split  // _ (lhs * rhs) hi lo
-                    pop 1  // _ (lhs * rhs) hi
-                    push 0 // _ (lhs * rhs) hi 0
-                    eq     // _ (lhs * rhs) (hi == 0)
-                    assert // _ (lhs * rhs)
-                    return
-                    "
-        )
-    }
+impl SafeMul {
+    pub const OVERFLOW_ERROR_ID: i128 = 460;
+}
 
-    fn crash_conditions(&self) -> Vec<String> {
-        vec!["result overflows u32".to_string()]
+impl BasicSnippet for SafeMul {
+    fn inputs(&self) -> Vec<(DataType, String)> {
+        ["right", "left"]
+            .map(|s| (DataType::U32, s.to_string()))
+            .to_vec()
     }
 
-    fn gen_input_states(&self) -> Vec<InitVmState> {
-        let mut ret: Vec<InitVmState> = vec![];
-        for _ in 0..10 {
-            let mut stack = empty_stack();
-            let lhs = thread_rng().gen_range(0..(1 << 16));
-            let rhs = thread_rng().gen_range(0..(1 << 16));
-            let lhs = BFieldElement::new(lhs as u64);
-            let rhs = BFieldElement::new(rhs as u64);
-            stack.push(lhs);
-            stack.push(rhs);
-            ret.push(InitVmState::with_stack(stack));
-        }
-
-        ret
+    fn outputs(&self) -> Vec<(DataType, String)> {
+        vec![(DataType::U32, "left · right".to_string())]
     }
 
-    fn common_case_input_state(&self) -> InitVmState {
-        InitVmState::with_stack(
-            [
-                empty_stack(),
-                vec![BFieldElement::new(1 << 8), BFieldElement::new(1 << 9)],
-            ]
-            .concat(),
-        )
+    fn entrypoint(&self) -> String {
+        "tasmlib_arithmetic_u32_safe_mul".to_string()
     }
 
-    fn worst_case_input_state(&self) -> InitVmState {
-        InitVmState::with_stack(
-            [
-                empty_stack(),
-                vec![
-                    BFieldElement::new((1 << 15) - 1),
-                    BFieldElement::new((1 << 16) - 1),
-                ],
-            ]
-            .concat(),
+    fn code(&self, _: &mut Library) -> Vec<LabelledInstruction> {
+        triton_asm!(
+            // BEFORE: _ right left
+            // AFTER:  _ product
+            {self.entrypoint()}:
+                mul
+                dup 0  // _ product product
+                split  // _ product hi lo
+                pop 1  // _ product hi
+                push 0 // _ product hi 0
+                eq     // _ product (hi == 0)
+                assert error_id {Self::OVERFLOW_ERROR_ID}
+                return
         )
     }
 
-    fn rust_shadowing(
-        &self,
-        stack: &mut Vec<BFieldElement>,
-        _std_in: Vec<BFieldElement>,
-        _secret_in: Vec<BFieldElement>,
-        _memory: &mut std::collections::HashMap<BFieldElement, BFieldElement>,
-    ) {
-        let lhs: u32 = stack.pop().unwrap().try_into().unwrap();
-        let rhs: u32 = stack.pop().unwrap().try_into().unwrap();
-
-        let prod = lhs * rhs;
-        stack.push(BFieldElement::new(prod as u64));
+    fn sign_offs(&self) -> HashMap<Reviewer, SignOffFingerprint> {
+        let mut sign_offs = HashMap::new();
+        sign_offs.insert(Reviewer("ferdinand"), 0x3836d772ff7b6165.into());
+        sign_offs
     }
 }
 
 #[cfg(test)]
 mod tests {
-    use std::collections::HashMap;
-
-    use num::Zero;
-
     use super::*;
-    use crate::test_helpers::test_rust_equivalence_given_input_values_deprecated;
-    use crate::test_helpers::test_rust_equivalence_multiple_deprecated;
+    use crate::test_prelude::*;
 
-    #[test]
-    fn snippet_test() {
-        test_rust_equivalence_multiple_deprecated(&SafeMul, true);
-    }
+    impl Closure for SafeMul {
+        type Args = (u32, u32);
 
-    #[test]
-    fn safe_sub_simple_test() {
-        prop_safe_mul(1000, 1, Some(1000));
-        prop_safe_mul(10_000, 900, Some(9_000_000));
-        prop_safe_mul(1, 1, Some(1));
-        prop_safe_mul(10_000, 10_000, Some(100_000_000));
-        prop_safe_mul(u32::MAX, 1, Some(u32::MAX));
-        prop_safe_mul(1, u32::MAX, Some(u32::MAX));
-    }
+        fn rust_shadow(&self, stack: &mut Vec<BFieldElement>) {
+            let (right, left) = pop_encodable::<Self::Args>(stack);
+            let product = left.checked_mul(right).unwrap();
+            push_encodable(stack, &product);
+        }
 
-    #[should_panic]
-    #[test]
-    fn overflow_test() {
-        prop_safe_mul(1 << 16, 1 << 16, None);
-    }
+        fn pseudorandom_args(
+            &self,
+            seed: [u8; 32],
+            bench_case: Option<BenchmarkCase>,
+        ) -> Self::Args {
+            let Some(bench_case) = bench_case else {
+                let mut rng = StdRng::from_seed(seed);
+                let left = rng.gen_range(1..=u32::MAX);
+                let right = rng.gen_range(0..=u32::MAX / left);
+
+                return (right, left);
+            };
+
+            match bench_case {
+                BenchmarkCase::CommonCase => (1 << 8, 1 << 9),
+                BenchmarkCase::WorstCase => (1 << 15, 1 << 16),
+            }
+        }
 
-    #[should_panic]
-    #[test]
-    fn overflow_test_2() {
-        prop_safe_mul(1 << 31, 2, None);
+        fn corner_case_args(&self) -> Vec<Self::Args> {
+            [0, 1]
+                .into_iter()
+                .cartesian_product([0, 1, u32::MAX])
+                .collect()
+        }
     }
 
-    #[should_panic]
     #[test]
-    fn overflow_test_3() {
-        prop_safe_mul(2, 1 << 31, None);
+    fn rust_shadow() {
+        ShadowedClosure::new(SafeMul).test();
     }
 
-    fn prop_safe_mul(lhs: u32, rhs: u32, _expected: Option<u32>) {
-        let mut init_stack = empty_stack();
-        init_stack.push(BFieldElement::new(rhs as u64));
-        init_stack.push(BFieldElement::new(lhs as u64));
-
-        let expected = lhs.checked_mul(rhs);
-        let expected = [
-            empty_stack(),
-            vec![expected
-                .map(|x| BFieldElement::new(x as u64))
-                .unwrap_or_else(BFieldElement::zero)],
-        ]
-        .concat();
-
-        test_rust_equivalence_given_input_values_deprecated(
-            &SafeMul,
-            &init_stack,
-            &[],
-            HashMap::default(),
-            Some(&expected),
-        );
+    #[proptest]
+    fn overflow_crashes_vm(
+        #[strategy(1_u32..)] left: u32,
+        #[strategy(u32::MAX / #left..)]
+        #[filter(#left.checked_mul(#right).is_none())]
+        right: u32,
+    ) {
+        test_assertion_failure(
+            &ShadowedClosure::new(SafeMul),
+            InitVmState::with_stack(SafeMul.set_up_test_stack((left, right))),
+            &[SafeMul::OVERFLOW_ERROR_ID],
+        )
     }
 }
 
 #[cfg(test)]
 mod benches {
     use super::*;
-    use crate::snippet_bencher::bench_and_write;
+    use crate::test_prelude::*;
 
     #[test]
     fn safe_mul_benchmark() {
-        bench_and_write(SafeMul);
+        ShadowedClosure::new(SafeMul).bench();
     }
 }

tasm-lib/src/assertion_error_ids.md

@@ -55,3 +55,4 @@ often.
 |  430..440 | [`MerkleRoot`](hashing/merkle_root.rs)                                                      |                                                      
 |  440..450 | [`u64::Incr`](arithmetic/u64/incr.rs)                                                       |
 |  450..460 | [`u32::SafeAdd`](arithmetic/u32/safe_add.rs)                                                |
+|  460..470 | [`u32::SafeMul`](arithmetic/u32/safe_mul.rs)                                                |