move data types

Author: critesjosh

docs/docs/developers/guides/smart_contracts/data_types.md

@@ -0,0 +1,132 @@
+---
+title: Get Notes
+sidebar_position: 4
+tags: [private-state, smart-contracts, notes]
+description: Learn how to get notes from a data oracle in Aztec.nr.
+---
+
+## 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)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_getter_options.nr).
+
+### `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`](#filter-fn-optionnote-max_note_hash_read_requests_per_call-filter_args---optionnote-max_note_hash_read_requests_per_call) and [`filter_args`](#filter_args-filter_args).
+
+### `.select`
+
+This method adds a [`Select`](#selects-boundedvecoptionselect-n) criterion to the options.
+
+### `.sort`
+
+This method adds a [`Sort`](#sorts-boundedvecoptionsort-n) 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.
+
+#include_code state_vars-NoteGetterOptionsSelectSortOffset /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr rust
+
+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:
+
+#include_code state_vars-CardNote /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/types/card_note.nr rust
+
+`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:
+
+#include_code state_vars-NoteGetterOptionsMultiSelects /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr rust
+
+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:
+
+#include_code state_vars-OptionFilter /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr rust
+
+We can use it as a filter to further reduce the number of the final notes:
+
+#include_code state_vars-NoteGetterOptionsFilter /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr rust
+
+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:
+
+#include_code state_vars-NoteGetterOptionsPickOne /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/options.nr rust
+
+#### Example 2
+
+An example of how we can use a Comparator to select notes when calling a Noir contract from aztec.js is below.
+
+#include_code state_vars-NoteGetterOptionsComparatorExampleTs /yarn-project/end-to-end/src/e2e_note_getter.test.ts typescript
+
+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.
+
+#include_code state_vars-NoteGetterOptionsComparatorExampleNoir /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/main.nr rust

docs/docs/developers/guides/smart_contracts/get_notes.md

@@ -21,4 +21,10 @@ For example, the following is the storage struct for the NFT contract:
 
 #include_code storage_struct /noir-projects/noir-contracts/contracts/app/nft_contract/src/main.nr rust
 
+:::info
+
+The `Context` parameter is injected into storage and contract functions. It provides information about the current execution mode (e.g. private or public).
+
+:::
+
 Read more about the data types available in the [Data Types](./data_types.md) page.