signoff!: list::Range

BREAKING CHANGE: Remove the implementation of `DeprecatedSnippet` for
`u128::range::Range`, implement `BasicSnippet` directly.

Author: jan-ferdinand

tasm-lib/benchmarks/tasmlib_list_range.json

@@ -2,21 +2,21 @@
   {
     "name": "tasmlib_list_range",
     "benchmark_result": {
-      "clock_cycle_count": 914,
-      "hash_table_height": 78,
+      "clock_cycle_count": 549,
+      "hash_table_height": 66,
       "u32_table_height": 39,
-      "op_stack_table_height": 763,
+      "op_stack_table_height": 311,
       "ram_table_height": 49
     },
     "case": "CommonCase"
   },
   {
     "name": "tasmlib_list_range",
     "benchmark_result": {
-      "clock_cycle_count": 4809,
-      "hash_table_height": 78,
+      "clock_cycle_count": 2804,
+      "hash_table_height": 66,
       "u32_table_height": 41,
-      "op_stack_table_height": 4043,
+      "op_stack_table_height": 1541,
       "ram_table_height": 254
     },
     "case": "WorstCase"

tasm-lib/src/assertion_error_ids.md

@@ -63,3 +63,4 @@ often.
 |  520..530 | [`u128::Sub`](arithmetic/u128/sub.rs)                                                       |
 |  530..540 | [`u128::ShiftLeft`](arithmetic/u128/shift_left.rs)                                          |
 |  540..550 | [`u128::ShiftRight`](arithmetic/u128/shift_right.rs)                                        |
+|  550..560 | [`list::Range`](list/range.rs)                                                              |

tasm-lib/src/list/range.rs

@@ -1,81 +1,67 @@
 use std::collections::HashMap;
 
-use itertools::Itertools;
 use triton_vm::prelude::*;
 
-use crate::empty_stack;
 use crate::list::new::New;
-use crate::list::set_length::SetLength;
-use crate::list::LIST_METADATA_SIZE;
-use crate::prelude::DataType;
-use crate::rust_shadowing_helper_functions;
-use crate::traits::deprecated_snippet::DeprecatedSnippet;
-use crate::InitVmState;
-
-/// Generates a list containing all integers between the minimum (inclusive lower bound) and the
-/// supremum (exclusive upper bound).
-#[derive(Debug, Default, Copy, Clone, Eq, PartialEq)]
+use crate::prelude::*;
+use crate::traits::basic_snippet::Reviewer;
+use crate::traits::basic_snippet::SignOffFingerprint;
+
+/// Generates a list containing all integers between the minimum (inclusive
+/// lower bound) and the supremum (exclusive upper bound).
+///
+/// ### Behavior
+///
+/// ```text
+/// BEFORE: _ [minimum: u32] [supremum: u32]
+/// AFTER:  _ *list
+/// ```
+///
+/// ### Preconditions
+///
+/// - all input arguments are properly [`BFieldCodec`] encoded
+/// - the `minimum` is less than or equal to the `supremum`
+///
+/// ### Postconditions
+///
+/// - `*list` is a pointer to a [`BFieldCodec`] encoded list of properly encoded
+///   `u32`s
+#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Hash)]
 pub struct Range;
 
 impl Range {
-    fn init_state(minimum: u32, supremum: u32) -> InitVmState {
-        let mut stack = empty_stack();
-        stack.push(BFieldElement::new(minimum as u64));
-        stack.push(BFieldElement::new(supremum as u64));
-        InitVmState::with_stack(stack)
-    }
+    pub const INVALID_ERROR_ID: i128 = 550;
 }
 
-impl DeprecatedSnippet for Range {
-    fn entrypoint_name(&self) -> String {
-        "tasmlib_list_range".into()
-    }
-
-    fn input_field_names(&self) -> Vec<String>
-    where
-        Self: Sized,
-    {
-        vec!["minimum".to_string(), "supremum".to_string()]
-    }
-
-    fn input_types(&self) -> Vec<DataType> {
-        vec![DataType::U32, DataType::U32]
-    }
-
-    fn output_field_names(&self) -> Vec<String>
-    where
-        Self: Sized,
-    {
-        vec!["*list".to_string()]
+impl BasicSnippet for Range {
+    fn inputs(&self) -> Vec<(DataType, String)> {
+        ["minimum", "supremum"]
+            .map(|s| (DataType::U32, s.to_string()))
+            .to_vec()
     }
 
-    fn output_types(&self) -> Vec<DataType> {
-        vec![DataType::List(Box::new(DataType::U32))]
+    fn outputs(&self) -> Vec<(DataType, String)> {
+        let list_type = DataType::List(Box::new(DataType::U32));
+        vec![(list_type, "*list".to_string())]
     }
 
-    fn stack_diff(&self) -> isize
-    where
-        Self: Sized,
-    {
-        -1
+    fn entrypoint(&self) -> String {
+        "tasmlib_list_range".into()
     }
 
-    fn function_code(&self, library: &mut crate::library::Library) -> String {
+    fn code(&self, library: &mut Library) -> Vec<LabelledInstruction> {
         let new_list = library.import(Box::new(New));
-        let set_length = library.import(Box::new(SetLength));
 
-        let entrypoint = self.entrypoint_name();
+        let entrypoint = self.entrypoint();
         let inner_loop = format!("{entrypoint}_loop");
 
         triton_asm!(
             // BEFORE: _ minimum supremum
             // AFTER:  _ *list
             {entrypoint}:
-                hint supremum = stack[0]
-                hint minimum = stack[1]
-                dup 0 push 1 add dup 2  // _ minimum supremum (supremum + 1) minimum
+                dup 0 addi 1 dup 2      // _ minimum supremum (supremum + 1) minimum
                 lt                      // _ minimum supremum (minimum <= supremum)
-                assert
+                assert error_id {Self::INVALID_ERROR_ID}
 
                 // calculate length
                 dup 0 dup 2             // _ minimum supremum supremum minimum
@@ -84,152 +70,121 @@ impl DeprecatedSnippet for Range {
 
                 // create list object
                 call {new_list}         // _ minimum supremum length *list
-                dup 1                   // _ minimum supremum length *list length
-                call {set_length}       // _ minimum supremum length *list
-                call {inner_loop}       // _ minimum supremum 0 *list
-
-                // clean up stack
-                swap 3 pop 3            // _ *list
+                dup 0 place 4           // _ *list minimum supremum length *list
+                write_mem 1             // _ *list minimum supremum *list[0]
+                call {inner_loop}       // _ *list supremum supremum *list[n]
+                pop 3                   // _ *list
                 return
 
-            // BEFORE:    _ minimum supremum length *list
-            // INVARIANT: _ minimum supremum (length - i) *list
-            // AFTER:     _ minimum supremum 0 *list
+            // BEFORE:    _ minimum     supremum *list[0]
+            // INVARIANT: _ (minimum+i) supremum *list[i]
+            // AFTER:     _ supremum    supremum *list[n]
             {inner_loop}:
-                // compute termination condition
-                dup 1 push 0 eq         // _ minimum supremum index *list (index == 0)
-                skiz return
-
-                // decrement index
-                swap 1 push -1 add      // _ minimum supremum *list (index - 1)
-
-                // value to write
-                dup 3 dup 1 add         // _ minimum supremum *list (index - 1) (minimum + index - 1)
+                dup 2 dup 2 eq          // _ (minimum+i) supremum *list[i] (minimum+i == supremum)
+                skiz return             // _ (minimum+i) supremum *list[i]
 
-                // address to write to
-                dup 2                   // _ minimum supremum *list (index - 1) (minimum + index - 1) *list
-                push {LIST_METADATA_SIZE}
-                hint list_metadata_size = stack[0]
-                add                     // _ minimum supremum *list (index - 1) (minimum + index - 1) *list_start
-                dup 2 add               // _ minimum supremum *list (index - 1) (minimum + index - 1) *element
+                dup 2 place 1           // _ (minimum+i) supremum (minimum+i) *list[i]
+                write_mem 1             // _ (minimum+i) supremum *list[i+1]
 
-                write_mem 1             // _ minimum supremum *list (index - 1) (*element + 1)
-                pop 1 swap 1            // _ minimum supremum (index - 1) *list
+                pick 2 addi 1 place 2   // _ (minimum+i+1) supremum *list[i+1]
                 recurse
         )
-        .iter()
-        .join("\n")
     }
 
-    fn crash_conditions(&self) -> Vec<String>
-    where
-        Self: Sized,
-    {
-        vec![
-            "minimum not u32".to_string(),
-            "supremum not u32".to_string(),
-            "minimum larger than supremum".to_string(),
-        ]
+    fn sign_offs(&self) -> HashMap<Reviewer, SignOffFingerprint> {
+        let mut sign_offs = HashMap::new();
+        sign_offs.insert(Reviewer("ferdinand"), 0xf536cdedd1ce0903.into());
+        sign_offs
     }
+}
 
-    fn gen_input_states(&self) -> Vec<InitVmState>
-    where
-        Self: Sized,
-    {
-        vec![
-            Self::init_state(0, 1),
-            Self::init_state(0, 10),
-            Self::init_state(5, 15),
-            Self::init_state(12, 12), // should generate empty list
-        ]
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::rust_shadowing_helper_functions::dyn_malloc::dynamic_allocator;
+    use crate::test_prelude::*;
+
+    impl Range {
+        fn set_up_initial_state(&self, minimum: u32, supremum: u32) -> FunctionInitialState {
+            let mut stack = self.init_stack_for_isolated_run();
+            stack.push(bfe!(minimum));
+            stack.push(bfe!(supremum));
+
+            FunctionInitialState {
+                stack,
+                ..Default::default()
+            }
+        }
     }
 
-    fn common_case_input_state(&self) -> InitVmState
-    where
-        Self: Sized,
-    {
-        Self::init_state(0, 45)
-    }
+    impl Function for Range {
+        fn rust_shadow(
+            &self,
+            stack: &mut Vec<BFieldElement>,
+            memory: &mut HashMap<BFieldElement, BFieldElement>,
+        ) {
+            let supremum = pop_encodable::<u32>(stack);
+            let minimum = pop_encodable::<u32>(stack);
+            assert!(minimum <= supremum);
 
-    fn worst_case_input_state(&self) -> InitVmState
-    where
-        Self: Sized,
-    {
-        Self::init_state(0, 250)
-    }
+            let list_pointer = dynamic_allocator(memory);
+            let list = (minimum..supremum).collect_vec();
+            encode_to_memory(memory, list_pointer, &list);
 
-    fn rust_shadowing(
-        &self,
-        stack: &mut Vec<BFieldElement>,
-        _std_in: Vec<BFieldElement>,
-        _secret_in: Vec<BFieldElement>,
-        memory: &mut HashMap<BFieldElement, BFieldElement>,
-    ) where
-        Self: Sized,
-    {
-        let supremum: u32 = stack.pop().unwrap().value().try_into().unwrap();
-        let minimum: u32 = stack.pop().unwrap().value().try_into().unwrap();
-        let num_elements: usize = (supremum - minimum).try_into().unwrap();
-
-        let safety_offset = LIST_METADATA_SIZE;
-        let length = num_elements;
-
-        // allocate space
-        let list_pointer = rust_shadowing_helper_functions::dyn_malloc::dynamic_allocator(memory);
-
-        // initialize list
-        rust_shadowing_helper_functions::list::list_new(list_pointer, memory);
-        rust_shadowing_helper_functions::list::list_set_length(list_pointer, length, memory);
-
-        // write elements
-        for i in minimum..supremum {
-            memory.insert(
-                list_pointer + BFieldElement::new(safety_offset as u64 + i as u64 - minimum as u64),
-                BFieldElement::new(i as u64),
-            );
+            stack.push(list_pointer);
         }
 
-        // leave list address on stack
-        stack.push(list_pointer);
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use triton_vm::error::InstructionError;
-
-    use super::*;
-    use crate::execute_with_terminal_state;
-    use crate::test_helpers::test_rust_equivalence_multiple_deprecated;
+        fn pseudorandom_initial_state(
+            &self,
+            seed: [u8; 32],
+            bench_case: Option<BenchmarkCase>,
+        ) -> FunctionInitialState {
+            let (minimum, supremum) = match bench_case {
+                Some(BenchmarkCase::CommonCase) => (0, 45),
+                Some(BenchmarkCase::WorstCase) => (0, 250),
+                None => {
+                    let mut rng = StdRng::from_seed(seed);
+                    let supremum = rng.gen_range(0..=400);
+                    let minimum = rng.gen_range(0..=supremum);
+                    (minimum, supremum)
+                }
+            };
+
+            self.set_up_initial_state(minimum, supremum)
+        }
 
-    #[test]
-    fn new_snippet_test() {
-        test_rust_equivalence_multiple_deprecated(&Range, true);
+        fn corner_case_initial_states(&self) -> Vec<FunctionInitialState> {
+            [(0, 0), (0, 1), (0, 10), (5, 15), (15, 15)]
+                .map(|(min, sup)| self.set_up_initial_state(min, sup))
+                .to_vec()
+        }
     }
 
     #[test]
-    fn bad_range_test() {
-        let init_state = Range::init_state(13, 12);
-        let snippet = Range;
-        let terminal_state = execute_with_terminal_state(
-            Program::new(&snippet.link_for_isolated_run()),
-            &init_state.public_input,
-            &init_state.stack,
-            &NonDeterminism::default(),
-            None,
+    fn rust_shadow() {
+        ShadowedFunction::new(Range).test();
+    }
+
+    #[proptest]
+    fn invalid_range_crashes_vm(
+        #[strategy(1_u32..)] minimum: u32,
+        #[strategy(..#minimum)] supremum: u32,
+    ) {
+        test_assertion_failure(
+            &ShadowedFunction::new(Range),
+            Range.set_up_initial_state(minimum, supremum).into(),
+            &[Range::INVALID_ERROR_ID],
         );
-        let err = terminal_state.unwrap_err();
-        assert!(matches!(err, InstructionError::AssertionFailed(_)));
     }
 }
 
 #[cfg(test)]
 mod benches {
     use super::*;
-    use crate::snippet_bencher::bench_and_write;
+    use crate::test_prelude::*;
 
     #[test]
     fn benchmark() {
-        bench_and_write(Range);
+        ShadowedFunction::new(Range).bench();
     }
 }