From 16a2eca1dbc5e8f4ca99c46363ed00eaa54dc97e Mon Sep 17 00:00:00 2001 From: esau <152162806+sklppy88@users.noreply.github.com> Date: Tue, 6 Feb 2024 11:52:43 -0600 Subject: [PATCH] chore: update docs for historical state (#4461) Co-authored-by: Rahul Kothari --- .../history_lib_reference.md | 73 +++++++++++++------ .../historical_access/how_to_prove_history.md | 25 +++---- .../src/history/public_value_inclusion.nr | 52 ++++++------- .../inclusion_proofs_contract/src/main.nr | 14 +++- 4 files changed, 94 insertions(+), 70 deletions(-) diff --git a/docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md b/docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md index d7688909262..6e9a02ff22f 100644 --- a/docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md +++ b/docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md @@ -6,53 +6,53 @@ title: History Reference ## Note inclusion -Note inclusion proves that a note existed (its hash was included in a note hash tree) at a specific block number. +Note inclusion proves that a note existed (its hash was included in a note hash tree) at a specific block number. There exists a version that tests for note inclusion at current block number. It is recommended to use this version whenever possible to reduce cost. -## prove_note_inclusion +### prove_note_inclusion -`prove_note_inclusion` takes 4 parameters: +`prove_note_inclusion_at` takes 3 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| -| note_interface | NoteInterface | Interface for the note with necessary functionality| | note_with_header| Note | The note you are proving inclusion for | | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | -## prove_note_commitment_inclusion - -A **commitment**, also referred to as a **note hash** is a public acknowledgment of the existence of a note without revealing the content of the note. You can learn more about how to compress a note to a note hash [here](../../../../learn/concepts/storage/trees/main.md#example-note). - -`prove_note_commitment_inclusion` takes 3 parameters: +`prove_note_inclusion` takes 2 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| -| commitment | Field | Note commitment we are checking inclusion of | -| block_number | u32 | Block number for proving note's existence | -| context| PrivateContext | Private Context | +| note_with_header| Note | The note you are proving inclusion for | +| context | PrivateContext | Private context | ## Note validity -This proves that a note exists and has not been nullified at a specified block. +This proves that a note exists and has not been nullified at a specified block. Again as above, there exists a version that tests for validity at current block. It is recommended to use this version whenever possible to reduce cost. ### prove_note_validity -`prove_note_validity` takes 4 parameters: +`prove_note_validity_at` takes 3 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| -| note_interface | NoteInterface | Interface for the note with necessary functionality| | note_with_header| Note | The note you are proving inclusion for | | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | +`prove_note_validity` takes 2 parameters: + +| Name | Type | Description | +|-----------------|------------------------|-----------------------------------------------------| +| note_with_header| Note | The note you are proving inclusion for | +| context | PrivateContext | Private context | + ## Nullifier inclusion -This proves that a nullifier was included in a certain block (can be used to prove that a note had been nullified). +This proves that a nullifier was included in a certain block (can be used to prove that a note had been nullified). The same disclaimer above holds true for this, and subsequent functions that specify another version without a block_number argument. ### prove_nullifier_inclusion -`prove_nullifier_inclusion` takes 3 parameters: +`prove_nullifier_inclusion_at` takes 3 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| @@ -60,22 +60,39 @@ This proves that a nullifier was included in a certain block (can be used to pro | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | +`prove_nullifier_inclusion` takes 2 parameters: + +| Name | Type | Description | +|-----------------|------------------------|-----------------------------------------------------| +| nullifier | Field | The nullifier you are proving inclusion for | +| context | PrivateContext | Private context | + +### prove_note_is_nullified_at / prove_note_is_nullified + +Instead of passing the nullifier, you can check that a note has been nullified by passing the note. + ## Nullifier non inclusion This proves that a nullifier was not included in a certain block (can be used to prove that a note had not yet been nullified in a given block). -### prove_nullifier_non_inclusion +### prove_nullifier_not_included -`prove_nullifier_non_inclusion` takes 3 parameters: +`prove_nullifier_not_included_at` takes 3 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| | nullifier | Field | The nullifier you are proving inclusion for | | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | - - -### note_not_nullified + +`prove_nullifier_not_included` takes 2 parameters: + +| Name | Type | Description | +|-----------------|------------------------|-----------------------------------------------------| +| nullifier | Field | The nullifier you are proving inclusion for | +| context | PrivateContext | Private context | + +### prove_note_not_nullified_at / prove_note_not_nullified Instead of passing the nullifier, you can check that a note has not been nullified by passing the note. @@ -85,7 +102,7 @@ This proves that a public value exists at a certain block. ### prove_public_value_inclusion -`prove_public_value_inclusion` takes 4 parameters: +`prove_public_value_inclusion_at` takes 4 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| @@ -94,13 +111,21 @@ This proves that a public value exists at a certain block. | block_number | u32 | Block number for proving value's existence | | context | PrivateContext | Private context | +`prove_public_value_inclusion` takes 3 parameters: + +| Name | Type | Description | +|-----------------|------------------------|-----------------------------------------------------| +| value | Field | The public value you are proving inclusion for | +| storage_slot | Field | Storage slot the value exists in | +| context | PrivateContext | Private context | + ## Contract inclusion This proves that a contract exists in, ie had been deployed before or in, a certain block. ### prove_contract_inclusion -`prove_contract_inclusion` takes 7 parameters: +`prove_contract_inclusion_at` takes 7 parameters: | Name | Type | Description | |---------------------------|-----------------|-------------------------------------------------------| diff --git a/docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md b/docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md index 8441611dbf2..f5d91061ef0 100644 --- a/docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md +++ b/docs/docs/developers/contracts/syntax/historical_access/how_to_prove_history.md @@ -53,22 +53,17 @@ In this example, the user's notes are stored in a map called `private_values`. W ## 4. Prove that a note was included in a specified block -To prove that a note existed in a specified block, call `prove_note_inclusion` as shown in this example: +To prove that a note existed in a specified block, call `prove_note_inclusion_at` as shown in this example: #include_code prove_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust -This function takes in 4 arguments: +This function takes in 3 arguments: -1. The note interface (`ValueNoteMethods`) -2. The note (`maybe_note.unwrap_unchecked()`). Here, `unwrap_unchecked()` returns the inner value without asserting `self.is_some()` -3. The block number -4. Private context - -Note: for this to work, you will need to import `ValueNoteMethods` at the beginning of the contract: - -#include_code value_note_imports yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust +1. The note (`maybe_note.unwrap_unchecked()`). Here, `unwrap_unchecked()` returns the inner value without asserting `self.is_some()` +2. The block number +3. Private context -This will only prove the note existed, not whether or not the note has been nullified. You can prove that a note existed and had not been nullified in a specified block by using `prove_note_validity` which takes the same arguments: +This will only prove the note existed at the specific block number, not whether or not the note has been nullified. You can prove that a note existed and had not been nullified in a specified block by using `prove_note_validity_at` which takes the same arguments: #include_code prove_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust @@ -84,7 +79,7 @@ You can then compute this nullifier with `note.compute_nullifier(&mut context)`. ## 6. Prove that a nullifier was included in a specified block -Call `prove_nullifier_inclusion` like so: +Call `prove_nullifier_inclusion_at` like so: #include_code prove_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust @@ -93,10 +88,8 @@ This takes three arguments: 2. Block number 3. Private context -You can also prove that a nullifier was not included in a specified block by using `prove_nullifier_non_inclusion` which takes the same arguments: - -#include_code prove_nullifier_non_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust +You can also prove that a nullifier was not included in a specified block by using `prove_nullifier_not_included_at` which takes the same arguments. -## Prove contract inclusion, public value inclusion, and note commitment inclusion +## Prove contract inclusion, public value inclusion, and use current state in lookups To see what else you can do with the `history` library, check out the [reference](./history_lib_reference.md). diff --git a/yarn-project/aztec-nr/aztec/src/history/public_value_inclusion.nr b/yarn-project/aztec-nr/aztec/src/history/public_value_inclusion.nr index e1ca53711c5..fbbfe95b9a9 100644 --- a/yarn-project/aztec-nr/aztec/src/history/public_value_inclusion.nr +++ b/yarn-project/aztec-nr/aztec/src/history/public_value_inclusion.nr @@ -18,32 +18,6 @@ use crate::{ }, }; -pub fn prove_public_value_inclusion( - value: Field, // The value that we want to prove is in the public data tree - storage_slot: Field, // The storage slot in which the value is stored - contract_address: AztecAddress, // The contract we want to look into - context: PrivateContext -) { - _public_value_inclusion( - value, - storage_slot, - contract_address, - context.historical_header - ); -} - -pub fn prove_public_value_inclusion_at( - value: Field, // The value that we want to prove is in the public data tree - storage_slot: Field, // The storage slot in which the value is stored - contract_address: AztecAddress, // The contract we want to look into - block_number: u32, // The block at which we'll prove that the note exists - context: PrivateContext -) { - let header = context.get_header_at(block_number); - - _public_value_inclusion(value, storage_slot, contract_address, header); -} - fn _public_value_inclusion( value: Field, storage_slot: Field, @@ -88,3 +62,29 @@ fn _public_value_inclusion( // --> Now we have traversed the trees all the way up to archive root and that way verified that a specific // `value` was really set in a given contract storage slot at block `block_number` in public data tree. } + +pub fn prove_public_value_inclusion( + value: Field, // The value that we want to prove is in the public data tree + storage_slot: Field, // The storage slot in which the value is stored + contract_address: AztecAddress, // The contract we want to look into + context: PrivateContext +) { + _public_value_inclusion( + value, + storage_slot, + contract_address, + context.historical_header + ); +} + +pub fn prove_public_value_inclusion_at( + value: Field, // The value that we want to prove is in the public data tree + storage_slot: Field, // The storage slot in which the value is stored + contract_address: AztecAddress, // The contract we want to look into + block_number: u32, // The block at which we'll prove that the note exists + context: PrivateContext +) { + let header = context.get_header_at(block_number); + + _public_value_inclusion(value, storage_slot, contract_address, header); +} diff --git a/yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr b/yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr index a02bc09740f..1e0a2917cb1 100644 --- a/yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr +++ b/yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr @@ -39,8 +39,12 @@ contract InclusionProofs { nullifier_inclusion::{ prove_nullifier_inclusion, prove_nullifier_inclusion_at, + prove_note_is_nullified, + prove_note_is_nullified_at, }, nullifier_non_inclusion::{ + prove_nullifier_not_included, + prove_nullifier_not_included_at, prove_note_not_nullified, prove_note_not_nullified_at, }, @@ -101,7 +105,9 @@ contract InclusionProofs { // 2) Prove the note inclusion if (use_block_number) { + // docs:start:prove_note_inclusion prove_note_inclusion_at(maybe_note.unwrap_unchecked(), block_number, context); + // docs:end:prove_note_inclusion } else { prove_note_inclusion(maybe_note.unwrap_unchecked(), context); } @@ -169,13 +175,13 @@ contract InclusionProofs { let note = notes[0].unwrap(); // 2) Prove the note validity - // docs:start:prove_note_validity if (use_block_number) { + // docs:start:prove_note_validity prove_note_validity_at(note, block_number, &mut context); + // docs:end:prove_note_validity } else { prove_note_validity(note, &mut context); } - // docs:end:prove_note_validity } // docs:start:nullify_note @@ -199,13 +205,13 @@ contract InclusionProofs { use_block_number: bool, block_number: u32 // The block at which we'll prove that the nullifier not exists in the tree ) { - // docs:start:prove_nullifier_inclusion if (use_block_number) { + // docs:start:prove_nullifier_inclusion prove_nullifier_inclusion_at(nullifier, block_number, context); + // docs:end:prove_nullifier_inclusion } else { prove_nullifier_inclusion(nullifier, context); } - // docs:end:prove_nullifier_inclusion } #[aztec(private)]