From 3c1cd9eea6700e8e054744c28e3a7be14e8432a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Venturo?= Date: Wed, 31 Jan 2024 14:33:56 +0000 Subject: [PATCH 1/3] Move NoteGetterOptions one level out --- .../contracts/syntax/storage/private_state.md | 35 +++++++++---------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/docs/developers/contracts/syntax/storage/private_state.md b/docs/docs/developers/contracts/syntax/storage/private_state.md index 35429d74020..4c288290673 100644 --- a/docs/docs/developers/contracts/syntax/storage/private_state.md +++ b/docs/docs/developers/contracts/syntax/storage/private_state.md @@ -246,69 +246,69 @@ The key distinction is that this method is unconstrained. It does not perform a This function requires a `NoteViewerOptions`. The `NoteViewerOptions` is essentially similar to the [`NoteGetterOptions`](#notegetteroptions), except that it doesn't take a custom filter. -### NoteGetterOptions +## `NoteGetterOptions` `NoteGetterOptions` encapsulates a set of configurable options for filtering and retrieving a selection of notes from a [data oracle](../functions/oracles.md). 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](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec-nr/aztec/src/note/note_getter_options.nr). -#### `selects: BoundedVec, N>` +### `selects: BoundedVec, N>` `selects` is a collection of filtering criteria, specified by `Select { field_index: u8, value: Field, comparator: u3 }` structs. It instructs the data oracle to find notes whose (`field_index`)th field matches the provided `value`, according to the `comparator`. -#### `sorts: BoundedVec, N>` +### `sorts: BoundedVec, N>` `sorts` is a set of sorting instructions defined by `Sort { field_index: u8, order: u2 }` structs. This directs the data oracle to sort the matching notes based on the value of the specified field index and in the indicated order. The value of order is **1** for _DESCENDING_ and **2** for _ASCENDING_. -#### `limit: u32` +### `limit: u32` When the `limit` is set to a non-zero value, the data oracle will return a maximum of `limit` notes. -#### `offset: u32` +### `offset: u32` This setting enables us to skip the first `offset` notes. It's particularly useful for pagination. -#### `filter: fn ([Option; MAX_READ_REQUESTS_PER_CALL], FILTER_ARGS) -> [Option; MAX_READ_REQUESTS_PER_CALL]` +### `filter: fn ([Option; MAX_READ_REQUESTS_PER_CALL], FILTER_ARGS) -> [Option; MAX_READ_REQUESTS_PER_CALL]` Developers have the option to provide a custom filter. This allows specific logic to be applied to notes that meet the criteria outlined above. The filter takes the notes returned from the oracle and `filter_args` as its parameters. It's important to note that the process of applying the custom filter to get the final notes is not constrained. It's crucial to verify the returned notes even if certain assumptions are made in the custom filter. -#### `filter_args: FILTER_ARGS` +### `filter_args: FILTER_ARGS` `filter_args` provides a means to furnish additional data or context to the custom filter. -#### Methods +### Methods Several methods are available on `NoteGetterOptions` to construct the options in a more readable manner: -#### `fn new() -> NoteGetterOptions` +### `fn new() -> NoteGetterOptions` This function initializes a `NoteGetterOptions` that simply returns the maximum number of notes allowed in a call. -#### `fn with_filter(filter, filter_args) -> NoteGetterOptions` +### `fn with_filter(filter, filter_args) -> NoteGetterOptions` This function initializes a `NoteGetterOptions` with a [`filter`](#filter-fn-optionnote-max_read_requests_per_call-filter_args---optionnote-max_read_requests_per_call) and [`filter_args`](#filter_args-filter_args). -#### `.select` +### `.select` This method adds a [`Select`](#selects-boundedvecoptionselect-n) criterion to the options. -#### `.sort` +### `.sort` This method adds a [`Sort`](#sorts-boundedvecoptionsort-n) criterion to the options. -#### `.set_limit` +### `.set_limit` This method lets you set a limit for the maximum number of notes to be retrieved. -#### `.set_offset` +### `.set_offset` This method sets the offset value, which determines where to start retrieving notes. -#### Examples +### Examples -##### Example 1 +#### Example 1 The following code snippet creates an instance of `NoteGetterOptions`, which has been configured to find the cards that belong to `account_address`. The returned cards are sorted by their points in descending order, and the first `offset` cards with the highest points are skipped. @@ -342,7 +342,7 @@ The limit is `MAX_READ_REQUESTS_PER_CALL` by default. But we can set it to any v #include_code state_vars-NoteGetterOptionsPickOne /yarn-project/noir-contracts/contracts/docs_example_contract/src/options.nr rust -##### Example 2 +#### Example 2 An example of how we can use a Comparator to select notes when calling a Noir contract from aztec.js is below. @@ -351,4 +351,3 @@ An example of how we can use a Comparator to select notes when calling a Noir co 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 /yarn-project/noir-contracts/contracts/docs_example_contract/src/main.nr rust - From b97670eebd40d5782339adcaa23837ca2c3b991e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Venturo?= Date: Wed, 31 Jan 2024 14:49:14 +0000 Subject: [PATCH 2/3] Add simple API docs for status --- .../developers/contracts/syntax/storage/private_state.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/docs/developers/contracts/syntax/storage/private_state.md b/docs/docs/developers/contracts/syntax/storage/private_state.md index 4c288290673..6ac548f66e1 100644 --- a/docs/docs/developers/contracts/syntax/storage/private_state.md +++ b/docs/docs/developers/contracts/syntax/storage/private_state.md @@ -278,6 +278,10 @@ It's important to note that the process of applying the custom filter to get the `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. + ### Methods Several methods are available on `NoteGetterOptions` to construct the options in a more readable manner: @@ -306,6 +310,10 @@ This method lets you set a limit for the maximum number of notes to be retrieved This method sets the offset value, which determines where to start retrieving notes. +### `.set_status` + +This method sets the status value, which indicates the status of notes to retrieve (active or nullified). + ### Examples #### Example 1 From 881ae840afa39afaa56b40f38beba09736334437 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=A1s=20Venturo?= Date: Wed, 31 Jan 2024 14:59:26 +0000 Subject: [PATCH 3/3] Add clarification --- .../docs/developers/contracts/syntax/storage/private_state.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/developers/contracts/syntax/storage/private_state.md b/docs/docs/developers/contracts/syntax/storage/private_state.md index 6ac548f66e1..d636459720a 100644 --- a/docs/docs/developers/contracts/syntax/storage/private_state.md +++ b/docs/docs/developers/contracts/syntax/storage/private_state.md @@ -280,7 +280,7 @@ It's important to note that the process of applying the custom filter to get the ### `status: u2` -`status` allows the caller to retrieve notes that have been nullified, which can be useful to prove historical data. +`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 @@ -312,7 +312,7 @@ This method sets the offset value, which determines where to start retrieving no ### `.set_status` -This method sets the status value, which indicates the status of notes to retrieve (active or nullified). +This method sets the status of notes to retrieve (active or nullified). ### Examples