Get Notes
Overview
NoteGetterOptions
NoteGetterOptions encapsulates a set of configurable options for filtering and retrieving a selection of notes from a data oracle. Developers can design instances of NoteGetterOptions, to determine how notes should be filtered and returned to the functions of their smart contracts.
You can view the implementation here (GitHub link).
selects: BoundedVec<Option<Select>, N>
selects is a collection of filtering criteria, specified by Select { property_selector: PropertySelector, comparator: u8, value: Field } structs. It instructs the data oracle to find notes whose serialized field (as specified by the PropertySelector) matches the provided value, according to the comparator. The PropertySelector is in turn specified as having an index (nth position of the selected field in the serialized note), an offset (byte offset inside the selected serialized field) and length (bytes to read of the field from the offset). These values are not expected to be manually computed, but instead specified by passing functions autogenerated from the note definition.
sorts: BoundedVec<Option<Sort>, N>
sorts is a set of sorting instructions defined by Sort { property_selector: PropertySelector, order: u2 } structs. This directs the data oracle to sort the matching notes based on the value of the specified PropertySelector and in the indicated order. The value of order is 1 for DESCENDING and 2 for ASCENDING.
limit: u32
When the limit is set to a non-zero value, the data oracle will return a maximum of limit notes.
offset: u32
This setting enables us to skip the first offset notes. It's particularly useful for pagination.
preprocessor: fn ([Option<Note>; MAX_NOTE_HASH_READ_REQUESTS_PER_CALL], PREPROCESSOR_ARGS) -> [Option<Note>; MAX_NOTE_HASH_READ_REQUESTS_PER_CALL]
Developers have the option to provide a custom preprocessor.
This allows specific logic to be applied to notes that meet the criteria outlined above.
The preprocessor takes the notes returned from the oracle and preprocessor_args as its parameters.
An important distinction from the filter function described below is that preprocessor is applied first and unlike filter it is applied in an unconstrained context.
preprocessor_args: PREPROCESSOR_ARGS
preprocessor_args provides a means to furnish additional data or context to the custom preprocessor.
filter: fn ([Option<Note>; MAX_NOTE_HASH_READ_REQUESTS_PER_CALL], FILTER_ARGS) -> [Option<Note>; MAX_NOTE_HASH_READ_REQUESTS_PER_CALL]
Just like preprocessor just applied in a constrained context (correct execution is proven) and applied after the preprocessor.
filter_args: FILTER_ARGS
filter_args provides a means to furnish additional data or context to the custom filter.
status: u2
status allows the caller to retrieve notes that have been nullified, which can be useful to prove historical data. Note that when querying for both active and nullified notes the caller cannot know if each note retrieved has or has not been nullified.
Methods
Several methods are available on NoteGetterOptions to construct the options in a more readable manner:
fn new() -> NoteGetterOptions<Note, N, Field>
This function initializes a NoteGetterOptions that simply returns the maximum number of notes allowed in a call.
fn with_filter(filter, filter_args) -> NoteGetterOptions<Note, N, FILTER_ARGS>
This function initializes a NoteGetterOptions with a filter and filter_args.
.select
This method adds a Select criterion to the options.
.sort
This method adds a Sort criterion to the options.
.set_limit
This method lets you set a limit for the maximum number of notes to be retrieved.
.set_offset
This method sets the offset value, which determines where to start retrieving notes.
.set_status
This method sets the status of notes to retrieve (active or nullified).
Examples
Example 1
The following code snippet creates an instance of NoteGetterOptions, which has been configured to find the cards that belong to an account with nullifying key hash equal to account_npk_m_hash. The returned cards are sorted by their points in descending order, and the first offset cards with the highest points are skipped.
pub fn create_npk_card_getter_options<let M: u32>(
account: AztecAddress,
offset: u32,
) -> NoteGetterOptions<CardNote, M, Field, Field>
where
CardNote: Packable<N = M>,
{
let mut options = NoteGetterOptions::new();
options
.select(CardNote::properties().owner, Comparator.EQ, account)
.sort(CardNote::properties().points, SortOrder.DESC)
.set_offset(offset)
}
Source code: noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr#L14-L28
The first value of .select and .sort indicates the property of the note we're looking for. For this we use helper functions that are autogenerated from the note definition. CardNote that has the following fields:
// We derive the Serialize trait because this struct is returned from a contract function. When returned,
// the struct is serialized using the Serialize trait and added to a hasher via the `add_to_hasher` utility.
// We use a hash rather than the serialized struct itself to keep circuit inputs constant.
#[derive(Eq, Serialize, Deserialize, Packable)]
#[note]
pub struct CardNote {
points: u8,
randomness: Field,
owner: AztecAddress,
}
Source code: noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/types/card_note.nr#L7-L18
CardNote::properties() will return a struct with the values to pass for each field, which are related to their indices inside the CardNote struct, internal offset and length.
In the example, .select(CardNote::properties().npk_m_hash, Comparator.EQ, account_npk_m_hash) matches notes which have the npk_m_hash field set to account_npk_m_hash. In this case we're using the equality comparator, but other operations exist in the Comparator utility struct.
.sort(0, SortOrder.DESC) sorts the 0th field of CardNote, which is points, in descending order.
There can be as many conditions as the number of fields a note type has. The following example finds cards whose fields match the three given values:
pub fn create_exact_card_getter_options<let M: u32>(
points: u8,
secret: Field,
account: AztecAddress,
) -> NoteGetterOptions<CardNote, M, Field, Field>
where
CardNote: Packable<N = M>,
{
let mut options = NoteGetterOptions::new();
options
.select(CardNote::properties().points, Comparator.EQ, points as Field)
.select(CardNote::properties().randomness, Comparator.EQ, secret)
.select(CardNote::properties().owner, Comparator.EQ, account)
}
Source code: noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr#L30-L45
While selects lets us find notes with specific values, filter lets us find notes in a more dynamic way. The function below picks the cards whose points are at least min_points, although this now can be done by using the select function with a GTE comparator:
pub fn filter_min_points(
cards: [Option<RetrievedNote<CardNote>>; MAX_NOTE_HASH_READ_REQUESTS_PER_CALL],
min_points: u8,
) -> [Option<RetrievedNote<CardNote>>; MAX_NOTE_HASH_READ_REQUESTS_PER_CALL] {
let mut selected_cards = [Option::none(); MAX_NOTE_HASH_READ_REQUESTS_PER_CALL];
let mut num_selected = 0;
for i in 0..cards.len() {
if cards[i].is_some() & cards[i].unwrap_unchecked().note.get_points() >= min_points {
selected_cards[num_selected] = cards[i];
num_selected += 1;
}
}
selected_cards
}
Source code: noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr#L47-L62
We can use it as a filter to further reduce the number of the final notes:
pub fn create_cards_with_min_points_getter_options<let M: u32>(
min_points: u8,
) -> NoteGetterOptions<CardNote, M, Field, u8>
where
CardNote: Packable<N = M>,
{
NoteGetterOptions::with_filter(filter_min_points, min_points).sort(
CardNote::properties().points,
SortOrder.ASC,
)
}
Source code: noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr#L64-L76
One thing to remember is, filter will be applied on the notes after they are picked from the database, so it is more efficient to use select with comparators where possible. Another side effect of this is that it's possible that the actual notes we end up getting are fewer than the limit.
The limit is MAX_NOTE_HASH_READ_REQUESTS_PER_CALL by default. But we can set it to any value smaller than that:
pub fn create_largest_card_getter_options<let M: u32>() -> NoteGetterOptions<CardNote, M, Field, Field>
where
CardNote: Packable<N = M>,
{
let mut options = NoteGetterOptions::new();
options.sort(CardNote::properties().points, SortOrder.DESC).set_limit(1)
}
Source code: noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr#L78-L86
Example 2
An example of how we can use a Comparator to select notes when calling a Noir contract from aztec.js is below.
contract.methods.read_note_values(Comparator.GTE, 5).simulate({ from: defaultAddress }),
Source code: yarn-project/end-to-end/src/e2e_note_getter.test.ts#L54-L56
In this example, we use the above typescript code to invoke a call to our Noir contract below. This Noir contract function takes an input to match with, and a comparator to use when fetching and selecting notes from storage.
#[utility]
unconstrained fn read_note(comparator: u8, amount: Field) -> BoundedVec<CardNote, 10> {
let mut options = NoteViewerOptions::new();
storage.set.view_notes(options.select(CardNote::properties().points, comparator, amount))
}
Source code: noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/main.nr#L111-L117