feat: nullified note retrieval in get_notes and view_notes (#4238)

Supercedes AztecProtocol/aztec-packages#4208,
which was closed as that one was created from a fork and we therefore
cannot run CI there.

Fixes AztecProtocol/aztec-packages#3755.

Author: superstar0402

aztec/src/note/note_getter.nr

@@ -8,7 +8,7 @@ use dep::protocol_types::constants::{
 };
 use crate::context::PrivateContext;
 use crate::note::{
-    note_getter_options::{NoteGetterOptions, Select, Sort, SortOrder, Comparator},
+    note_getter_options::{NoteGetterOptions, Select, Sort, SortOrder, Comparator, NoteStatus},
     note_interface::NoteInterface,
     note_viewer_options::NoteViewerOptions,
     utils::compute_note_hash_for_read_or_nullify,
@@ -135,6 +135,7 @@ unconstrained fn get_note_internal<Note, N>(storage_slot: Field, note_interface:
         [],
         1, // limit
         0, // offset
+        NoteStatus.ACTIVE,
         placeholder_note,
         placeholder_fields
     )[0].unwrap() // Notice: we don't allow dummies to be returned from get_note (singular).
@@ -159,6 +160,7 @@ unconstrained fn get_notes_internal<Note, N, FILTER_ARGS>(
         sort_order,
         options.limit,
         options.offset,
+        options.status,
         placeholder_opt_notes,
         placeholder_fields
     );
@@ -187,6 +189,7 @@ unconstrained pub fn view_notes<Note, N>(
         sort_order,
         options.limit,
         options.offset,
+        options.status,
         placeholder_opt_notes,
         placeholder_fields
     )

aztec/src/note/note_getter_options.nr

@@ -53,6 +53,17 @@ impl Sort {
     }
 }
 
+struct NoteStatusEnum {
+    ACTIVE: u2,
+    ACTIVE_OR_NULLIFIED: u2,
+}
+
+global NoteStatus = NoteStatusEnum {
+    ACTIVE: 1,
+    ACTIVE_OR_NULLIFIED: 2,
+    // TODO 4217: add 'NULLIFIED'
+};
+
 fn return_all_notes<Note, N>(
     notes: [Option<Note>; MAX_READ_REQUESTS_PER_CALL],
     _p: Field
@@ -68,6 +79,7 @@ struct NoteGetterOptions<Note, N, FILTER_ARGS> {
     offset: u32,
     filter: fn ([Option<Note>; MAX_READ_REQUESTS_PER_CALL], FILTER_ARGS) -> [Option<Note>; MAX_READ_REQUESTS_PER_CALL],
     filter_args: FILTER_ARGS,
+    status: u2,
 }
 // docs:end:NoteGetterOptions
 
@@ -85,6 +97,7 @@ impl<Note, N, FILTER_ARGS> NoteGetterOptions<Note, N, FILTER_ARGS> {
             offset: 0,
             filter: return_all_notes,
             filter_args: 0,
+            status: NoteStatus.ACTIVE,
         }
     }
 
@@ -101,6 +114,7 @@ impl<Note, N, FILTER_ARGS> NoteGetterOptions<Note, N, FILTER_ARGS> {
             offset: 0,
             filter,
             filter_args,
+            status: NoteStatus.ACTIVE,
         }
     }
 
@@ -120,16 +134,22 @@ impl<Note, N, FILTER_ARGS> NoteGetterOptions<Note, N, FILTER_ARGS> {
         *self
     }
 
-    // This method lets you set a limit for the maximum number of notes to be retrieved in a single query result. 
+    // This method lets you set a limit for the maximum number of notes to be retrieved in a single query result.
     pub fn set_limit(&mut self, limit: u32) -> Self {
         assert(limit <= MAX_READ_REQUESTS_PER_CALL as u32);
         self.limit = limit;
         *self
     }
 
-    // This method sets the offset value, which determines where to start retrieving notes in the query results. 
+    // This method sets the offset value, which determines where to start retrieving notes in the query results.
     pub fn set_offset(&mut self, offset: u32) -> Self {
         self.offset = offset;
         *self
     }
+
+    // This method sets the status value, which determines whether to retrieve active or nullified notes.
+    pub fn set_status(&mut self, status: u2) -> Self {
+        self.status = status;
+        *self
+    }
 }

aztec/src/note/note_viewer_options.nr

@@ -1,6 +1,6 @@
 use dep::std::option::Option;
 use dep::protocol_types::constants::MAX_NOTES_PER_PAGE;
-use crate::note::note_getter_options::{Select, Sort, Comparator};
+use crate::note::note_getter_options::{Select, Sort, Comparator, NoteStatus};
 use crate::types::vec::BoundedVec;
 
 // docs:start:NoteViewerOptions
@@ -9,6 +9,7 @@ struct NoteViewerOptions<Note, N> {
     sorts: BoundedVec<Option<Sort>, N>,
     limit: u32,
     offset: u32,
+    status: u2,
 }
 // docs:end:NoteViewerOptions
 
@@ -19,12 +20,13 @@ impl<Note, N> NoteViewerOptions<Note, N> {
             sorts: BoundedVec::new(Option::none()),
             limit: MAX_NOTES_PER_PAGE as u32,
             offset: 0,
+            status: NoteStatus.ACTIVE,
         }
     }
-       
+
     // This method adds a `Select` criterion to the options.
-    // It takes a field_index indicating which field to select, 
-    // a value representing the specific value to match in that field, and 
+    // It takes a field_index indicating which field to select,
+    // a value representing the specific value to match in that field, and
     // a comparator (For possible values of comparators, please see the Comparator enum from note_getter_options)
     pub fn select(&mut self, field_index: u8, value: Field, comparator: Option<u3>) -> Self {
         self.selects.push(Option::some(Select::new(field_index, value, comparator.unwrap_or(Comparator.EQ))));
@@ -46,4 +48,10 @@ impl<Note, N> NoteViewerOptions<Note, N> {
         self.offset = offset;
         *self
     }
+
+    // This method sets the status value, which determines whether to retrieve active or nullified notes.
+    pub fn set_status(&mut self, status: u2) -> Self {
+        self.status = status;
+        *self
+    }
 }

aztec/src/oracle/notes.nr

@@ -32,6 +32,7 @@ fn get_notes_oracle<N, S>(
     _sort_order: [u2; N],
     _limit: u32,
     _offset: u32,
+    _status: u2,
     _return_size: u32,
     _placeholder_fields: [Field; S]
 ) -> [Field; S] {}
@@ -46,6 +47,7 @@ unconstrained fn get_notes_oracle_wrapper<N, S>(
     sort_order: [u2; N],
     limit: u32,
     offset: u32,
+    status: u2,
     mut placeholder_fields: [Field; S]
 ) -> [Field; S] {
     let return_size = placeholder_fields.len() as u32;
@@ -59,6 +61,7 @@ unconstrained fn get_notes_oracle_wrapper<N, S>(
         sort_order,
         limit,
         offset,
+        status,
         return_size,
         placeholder_fields
     )
@@ -75,6 +78,7 @@ unconstrained pub fn get_notes<Note, N, M, S, NS>(
     sort_order: [u2; M],
     limit: u32,
     offset: u32,
+    status: u2,
     mut placeholder_opt_notes: [Option<Note>; S], // TODO: Remove it and use `limit` to initialize the note array.
     placeholder_fields: [Field; NS] // TODO: Remove it and use `limit` to initialize the note array.
 ) -> [Option<Note>; S] {
@@ -88,6 +92,7 @@ unconstrained pub fn get_notes<Note, N, M, S, NS>(
         sort_order,
         limit,
         offset,
+        status,
         placeholder_fields
     );
     let num_notes = fields[0] as u32;