From c267a9fdf6e0f9281577d13c92b428094836bf06 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 9 Jan 2024 21:35:07 +0900 Subject: [PATCH 01/21] historical trees docs --- .../contracts/syntax/historical_trees.md | 232 ++++++++++++++++++ docs/sidebars.js | 1 + .../inclusion_proofs_contract/src/main.nr | 28 +++ 3 files changed, 261 insertions(+) create mode 100644 docs/docs/dev_docs/contracts/syntax/historical_trees.md diff --git a/docs/docs/dev_docs/contracts/syntax/historical_trees.md b/docs/docs/dev_docs/contracts/syntax/historical_trees.md new file mode 100644 index 000000000000..b57f5c7425a9 --- /dev/null +++ b/docs/docs/dev_docs/contracts/syntax/historical_trees.md @@ -0,0 +1,232 @@ +--- +title: Historical Trees +--- + +When something happens on the Aztec Protocol, it is added to a historical tree. Aztec.nr allows developers to generate inclusion and non-inclusion proofs against the historical tree, allowing them to check whether or not something was included in a certain block. + +On this page you will learn: + +1. What are historical trees and inclusion proofs? +2. How you can integrate inclusion and non-inclusion proofs into your own smart contract + +# Historical trees on Aztec + +Historical trees are data structures for storing data in both public and private state. The Aztec protocol uses different trees for different types of data. You can learn more about trees in Aztec [here](../../../concepts/advanced/data_structures/trees.md). + +The historical trees library allows you to access: + +* Private notes +* Notes that have been nullified +* Notes that have not been nullified +* Public values +* Contracts + +Using historical trees, you can check that specific notes or nullifiers happened at specific blocks. This can be useful for things such as: + +* Verifying a timestamp that was created in a private context +* Checking eligibility based on historical events (eg for an airdrop) + +# How to integrate historical access and inclusion proofs into your smart contract + +Checking if a value was included in a certain block is called an inclusion proof. Similarly, checking that a value was not included is called a non-inclusion proof. + +In this section we will talk about how to integrate the different types of inclusion and non-inclusion proofs into your smart contract. + +## Note inclusion + +Note inclusion proves that someone owned a note at a specific block number. + +### 1. Import note_inclusion into your smart contract + +```rust +aztec::{ +history::{ + #include_code import_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw +} +} +``` +### 2. Call prove_note_inclusion + +`prove_note_inclusion` takes 4 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 | + +#### Example + +#include_code prove_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +### 3. You can also prove the note commitment with prove_note_commitment_inclusion + +`prove_note_commitment_inclusion takes 3 parameters: + +| Name | Type | Description | +|-----------------|------------------------|-----------------------------------------------------| +| commitment | Field | Note commitment we are checking inclusion of | +| block_number | u32 | Block number for proving note's existence | +| context| PrivateContexr | Private Context | + +#### Example + +#include_code prove_note_commitment_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +## Note validity + +This proves that a note exists and has not been nullified at a specified block. + +### 1. Import note_validity + +```rust +aztec::{ +history::{ + #include_code import_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw +} +} +``` +### 2. Call prove_note_validity + +`prove_note_validity` takes 4 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 | + +#### Example + +#include_code prove_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +## Nullifier inclusion + +This proves that a nullifier was included, ie a note had been nullified, in a certain block. + +### 1. Import nullifier_inclusion + +```rust +aztec::{ +history::{ + #include_code import_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw +} +} +``` + +### 2. Call prove_nullifier_inclusion + +`prove_nullifier_inclusion` 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 | + +#### Example + +#include_code prove_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +## Nullifier non inclusion + +This proves that a nullifier was not included, ie a note had not been nullified, in a certain block. + +### 1. Import nullifier_non_inclusion + +```rust +aztec::{ +history::{ + #include_code import_nullifier_non_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw +} +} +``` + +### 2. Call prove_nullifier_non_inclusion + +`prove_nullifier_non_inclusion` 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 | + +#### Example + +TODO #include_code prove_nullifier_non_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +### 3. Call note_not_nullified + +Instead of passing the nullifier, you can check that a note has not been nullified by passing the note. + +TODO #include_code prove_note_not_nullified yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +## Public value inclusion + +This proves that a public value exists at a certain block. + +### 1. Import public_value_inclusion + +```rust +aztec::{ +history::{ + #include_code import_public_value_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw +} +} +``` + +### 2. Call prove_public_value_inclusion + +`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 | +| block_number | u32 | Block number for proving value's existence | +| context | PrivateContext | Private context | + +### Example + +#include_code prove_public_value_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +## Contract inclusion + +This proves that a contract exists in, ie had been deployed before or in, a certain block. + +### 1. Import contract_inclusion + +```rust +aztec::{ +history::{ + #include_code import_contract_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw +} +} +``` + +### 2. Call prove_contract_inclusion + +`prove_contract_inclusion` takes 7 parameters: + +| Name | Type | Description | +|---------------------------|-----------------|-------------------------------------------------------| +| deployer_public_key | GrumpkinPoint | Public key of the contract deployer | +| contract_address_salt | Field | Unique identifier for the contract's address | +| function_tree_root | Field | Root of the contract's function tree | +| constructor_hash | Field | Hash of the contract's constructor | +| portal_contract_address | EthAddress | Ethereum address of the associated portal contract | +| block_number | u32 | Block number for proof verification | +| context | PrivateContext | Private context | + +If there is no associated portal contract, you can use a zero Ethereum address: + +```ts +new EthAddress(Buffer.alloc(EthAddress.SIZE_IN_BYTES)); +``` + +### Example + +TODO #include_code prove_contract_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index b65035ba968a..3ff5d9382523 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -326,6 +326,7 @@ const sidebars = { }, "dev_docs/contracts/syntax/events", "dev_docs/contracts/syntax/functions", + "dev_docs/contracts/syntax/historical_trees", "dev_docs/contracts/syntax/slow_updates_tree", "dev_docs/contracts/syntax/context", "dev_docs/contracts/syntax/globals", 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 6b5f635b2455..68e38ee75297 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 @@ -25,26 +25,38 @@ contract InclusionProofs { }, history::{ + // docs:start:import_contract_inclusion contract_inclusion::{ prove_contract_inclusion, }, + // docs:end:import_contract_inclusion + // docs:start:import_note_inclusion note_inclusion::{ prove_note_commitment_inclusion, prove_note_inclusion, }, + // docs:end:import_note_inclusion + // docs:start:import_note_validity note_validity::{ prove_note_validity, }, + // docs:end:import_note_validity + // docs:start:import_nullifier_inclusion nullifier_inclusion::{ prove_nullifier_inclusion, }, + // docs:end:import_nullifier_inclusion + // docs:start:import_nullifier_non_inclusion nullifier_non_inclusion::{ prove_nullifier_non_inclusion, prove_note_not_nullified, }, + // docs:end:import_nullifier_non_inclusion + // docs:start:import_public_value_inclusion public_value_inclusion::{ prove_public_value_inclusion, }, + // docs:end:import_public_value_inclusion }, }; use dep::value_note::value_note::{ValueNote, ValueNoteMethods, VALUE_NOTE_LEN}; @@ -110,15 +122,19 @@ contract InclusionProofs { // 2) Prove the note inclusion if maybe_note.is_some() { + // docs:start:prove_note_inclusion prove_note_inclusion( ValueNoteMethods, maybe_note.unwrap_unchecked(), block_number, context ); + // docs:end:prove_note_inclusion } else { // Note was not found so we will prove inclusion of the spare commitment + // docs:start:prove_note_commitment_inclusion prove_note_commitment_inclusion(spare_commitment, block_number, context); + // docs:end:prove_note_commitment_inclusion }; } @@ -140,15 +156,19 @@ contract InclusionProofs { // 3) Compute the nullifier from the note if maybe_note.is_some() { + // docs:start:prove_note_not_nullified prove_note_not_nullified( ValueNoteMethods, maybe_note.unwrap_unchecked(), block_number, context ); + // docs:end:prove_note_not_nullified } else { // Note was not found so we will use the spare nullifier + // docs:start:prove_nullifier_non_inclusion prove_nullifier_non_inclusion(spare_nullifier, block_number, context); + // docs:end:prove_nullifier_non_inclusion }; } @@ -164,7 +184,9 @@ contract InclusionProofs { let note = notes[0].unwrap(); // 2) Prove the note validity + // docs:start:prove_note_validity prove_note_validity(ValueNoteMethods, note, block_number, context); + // docs:end:prove_note_validity } #[aztec(private)] @@ -185,7 +207,9 @@ contract InclusionProofs { nullifier: Field, block_number: u32 // The block at which we'll prove that the nullifier not exists in the tree ) { + // docs:start:prove_nullifier_inclusion prove_nullifier_inclusion(nullifier, block_number, context); + // docs:end:prove_nullifier_inclusion } #[aztec(private)] @@ -193,12 +217,14 @@ contract InclusionProofs { public_value: Field, block_number: u32 // The block at which we'll prove that the public value exists ) { + // docs:start:prove_public_value_inclusion prove_public_value_inclusion( public_value, storage.public_value.storage_slot, block_number, context ); + // docs:end:prove_public_value_inclusion } // Proves that a contract exists at block `block_number`. @@ -218,6 +244,7 @@ contract InclusionProofs { portal_contract_address: EthAddress, block_number: u32 // The block at which we'll prove that the public value exists ) { + // docs:start:prove_contract_inclusion let proven_contract_address = prove_contract_inclusion( deployer_public_key, contract_address_salt, @@ -227,6 +254,7 @@ contract InclusionProofs { block_number, context ); + // docs:end:prove_contract_inclusion // Here typically the factory would add the contract address to its internal map of deployed contracts. } From 450d8201f5f095d9c9d3edeec07f05ef90d0bad1 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 9 Jan 2024 21:53:54 +0900 Subject: [PATCH 02/21] comment format --- .../contracts/inclusion_proofs_contract/src/main.nr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 68e38ee75297..557e7f99ef30 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 @@ -254,7 +254,7 @@ contract InclusionProofs { block_number, context ); - // docs:end:prove_contract_inclusion + // docs:end:prove_contract_inclusion // Here typically the factory would add the contract address to its internal map of deployed contracts. } From fe6f2d5345e631a6cfd3436fb6d07fddc53d9ac9 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Thu, 11 Jan 2024 20:52:47 +0900 Subject: [PATCH 03/21] added concepts section --- .../advanced/data_structures/trees.md | 36 ++++++++++++++++--- .../contracts/syntax/historical_trees.md | 27 ++++++-------- 2 files changed, 43 insertions(+), 20 deletions(-) diff --git a/docs/docs/concepts/advanced/data_structures/trees.md b/docs/docs/concepts/advanced/data_structures/trees.md index 658782ad010c..347a302084f8 100644 --- a/docs/docs/concepts/advanced/data_structures/trees.md +++ b/docs/docs/concepts/advanced/data_structures/trees.md @@ -14,7 +14,7 @@ Data includes: - Nullifiers to invalidate old private state ([Nullifier tree](#nullifier-tree)) - Public state ([Public State tree](#public-state-tree)) - Contracts ([Contract tree](#contract-tree)) -- Previous block headers ([Archive tree](#archive-tree)) +- Historical access ([Historical access tree](#historical-access-tree)) - Global Variables ```mermaid @@ -179,11 +179,39 @@ The contract tree contains information about every function of every contract de Aztec supports the ability to keep the logic of private functions of a smart contract private. In such cases, no information about the logic of that private function will be broadcast; only a randomized merkle root of that contract's data. ::: -## Archive Tree +## Historical Access Tree -A block includes the root to the Archive Tree (sometimes called the blocks tree). +The historical access tree is an append-only Merkle tree that stores the headers of all previous blocks in the chain as its leaves. -The leaves of the tree are hashes of previous block headers. This tree can be used to verify data of any of the trees above at some previous point in time by doing a membership check of the corresponding tree root in the block header and the block header hash in the blocks tree. +As private execution relies on proofs generated by the user, the current head is not known. We can then instead base the proofs on historical state. By including all prior headers (which include commitments to the state), the historical access tree allows us to easily prove that the historic state that a transaction was proven upon is valid. + +```mermaid +graph TD; + +PartialStateReference[Partial State Data
snapshot of note hash tree, nullifier tree, contract tree, public data tree] +StateReference[State Data Reference
snapshot of L1<>L2 message tree] +GlobalVariables[Global Network Variables
block number, timestamp, version, chain_id] +Header[Block Header Information
last snapshot of tree, hash of body] +Logs[Transaction Logs
encrypted & non-encrypted logs] +PublicDataWrite[Public Data Writes
] +ContractData[Contract Data
leaf, address] +TxEffect[Transaction Effects
note hashes, nullifiers, contracts, public writes] +Body[ Body
L1<>L2 messages, transaction effects] +HistoricalAccessTree[Historical Access Tree
used to validate user-generated proofs and access historical data] + +StateReference --- PartialStateReference +Header --- Body +Header --- StateReference +Header --- GlobalVariables +TxEffect --- ContractData +TxEffect --- PublicDataWrite +TxEffect --- Logs +Body --- TxEffect +HistoricalAccessTree --- Header + +``` + +It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../dev_docs/contracts/syntax/historical_trees.md). ## Trees of valid Kernel/Rollup circuit Verification Keys diff --git a/docs/docs/dev_docs/contracts/syntax/historical_trees.md b/docs/docs/dev_docs/contracts/syntax/historical_trees.md index b57f5c7425a9..9d1cef964666 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_trees.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_trees.md @@ -1,27 +1,22 @@ --- -title: Historical Trees +title: Historical Access Tree --- -When something happens on the Aztec Protocol, it is added to a historical tree. Aztec.nr allows developers to generate inclusion and non-inclusion proofs against the historical tree, allowing them to check whether or not something was included in a certain block. +The Aztec Protocol uses an append-only Merkle tree to store the headers of all previous blocks in the chain as its leaves. You can learn more about how it works in the [concepts section](../../../concepts/advanced/data_structures/trees.md#historical-access-tree). -On this page you will learn: +On this page you will learn how you can integrate inclusion and non-inclusion proofs into your own smart contract. -1. What are historical trees and inclusion proofs? -2. How you can integrate inclusion and non-inclusion proofs into your own smart contract +# Historical tree library -# Historical trees on Aztec +The historical tree library allows you to access: -Historical trees are data structures for storing data in both public and private state. The Aztec protocol uses different trees for different types of data. You can learn more about trees in Aztec [here](../../../concepts/advanced/data_structures/trees.md). +* [Private notes](#note-inclusion) +* [Notes that have been nullified](#nullifier-inclusion) +* [Notes that have not been nullified](#note-validity) +* [Public values](#public-value-inclusion) +* [Contracts](#contract-inclusion) -The historical trees library allows you to access: - -* Private notes -* Notes that have been nullified -* Notes that have not been nullified -* Public values -* Contracts - -Using historical trees, you can check that specific notes or nullifiers happened at specific blocks. This can be useful for things such as: +Using the historical access tree, you can check that specific notes or nullifiers happened at specific blocks. This can be useful for things such as: * Verifying a timestamp that was created in a private context * Checking eligibility based on historical events (eg for an airdrop) From 37dba09960d35f2ac85e3c2b5a905dce34d785fc Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Mon, 15 Jan 2024 08:57:22 +0000 Subject: [PATCH 04/21] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: josh crites Co-authored-by: Jan Beneš --- .../concepts/advanced/data_structures/trees.md | 2 +- .../contracts/syntax/historical_trees.md | 17 +++++++++-------- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/docs/concepts/advanced/data_structures/trees.md b/docs/docs/concepts/advanced/data_structures/trees.md index 347a302084f8..5eb60c453b13 100644 --- a/docs/docs/concepts/advanced/data_structures/trees.md +++ b/docs/docs/concepts/advanced/data_structures/trees.md @@ -183,7 +183,7 @@ Aztec supports the ability to keep the logic of private functions of a smart con The historical access tree is an append-only Merkle tree that stores the headers of all previous blocks in the chain as its leaves. -As private execution relies on proofs generated by the user, the current head is not known. We can then instead base the proofs on historical state. By including all prior headers (which include commitments to the state), the historical access tree allows us to easily prove that the historic state that a transaction was proven upon is valid. +As private execution relies on proofs generated by the user, the current block header is not known. We can instead base the proofs on historical state. By including all prior block headers (which include commitments to the state), the historical access tree allows us to easily prove that the historic state that a transaction is using for a proof is valid. ```mermaid graph TD; diff --git a/docs/docs/dev_docs/contracts/syntax/historical_trees.md b/docs/docs/dev_docs/contracts/syntax/historical_trees.md index 9d1cef964666..022ff0d052d5 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_trees.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_trees.md @@ -1,5 +1,5 @@ --- -title: Historical Access Tree +title: Accessing History --- The Aztec Protocol uses an append-only Merkle tree to store the headers of all previous blocks in the chain as its leaves. You can learn more about how it works in the [concepts section](../../../concepts/advanced/data_structures/trees.md#historical-access-tree). @@ -8,7 +8,7 @@ On this page you will learn how you can integrate inclusion and non-inclusion pr # Historical tree library -The historical tree library allows you to access: +The historical tree library allows you to access any of the following at a given block height before the current height: * [Private notes](#note-inclusion) * [Notes that have been nullified](#nullifier-inclusion) @@ -20,6 +20,7 @@ Using the historical access tree, you can check that specific notes or nullifier * Verifying a timestamp that was created in a private context * Checking eligibility based on historical events (eg for an airdrop) +* Verifying historic ownership / relinquishing of assets # How to integrate historical access and inclusion proofs into your smart contract @@ -37,7 +38,7 @@ Note inclusion proves that someone owned a note at a specific block number. aztec::{ history::{ #include_code import_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw -} + } } ``` ### 2. Call prove_note_inclusion @@ -63,7 +64,7 @@ history::{ |-----------------|------------------------|-----------------------------------------------------| | commitment | Field | Note commitment we are checking inclusion of | | block_number | u32 | Block number for proving note's existence | -| context| PrivateContexr | Private Context | +| context| PrivateContext | Private Context | #### Example @@ -79,7 +80,7 @@ This proves that a note exists and has not been nullified at a specified block. aztec::{ history::{ #include_code import_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw -} + } } ``` ### 2. Call prove_note_validity @@ -107,7 +108,7 @@ This proves that a nullifier was included, ie a note had been nullified, in a ce aztec::{ history::{ #include_code import_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw -} + } } ``` @@ -135,7 +136,7 @@ This proves that a nullifier was not included, ie a note had not been nullified, aztec::{ history::{ #include_code import_nullifier_non_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw -} + } } ``` @@ -198,7 +199,7 @@ This proves that a contract exists in, ie had been deployed before or in, a cert aztec::{ history::{ #include_code import_contract_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw -} + } } ``` From 54b21f154c7378ababd9262c54cfac374a927519 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Mon, 15 Jan 2024 19:15:12 +0900 Subject: [PATCH 05/21] diaxified --- .../advanced/data_structures/trees.md | 10 +- .../history_lib_reference.md} | 135 ++---------------- .../how_to_access_history.md | 97 +++++++++++++ docs/sidebars.js | 10 +- .../inclusion_proofs_contract/src/main.nr | 30 ++-- 5 files changed, 134 insertions(+), 148 deletions(-) rename docs/docs/dev_docs/contracts/syntax/{historical_trees.md => historical_access/history_lib_reference.md} (55%) create mode 100644 docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md diff --git a/docs/docs/concepts/advanced/data_structures/trees.md b/docs/docs/concepts/advanced/data_structures/trees.md index 5eb60c453b13..4ec122168f2c 100644 --- a/docs/docs/concepts/advanced/data_structures/trees.md +++ b/docs/docs/concepts/advanced/data_structures/trees.md @@ -14,7 +14,7 @@ Data includes: - Nullifiers to invalidate old private state ([Nullifier tree](#nullifier-tree)) - Public state ([Public State tree](#public-state-tree)) - Contracts ([Contract tree](#contract-tree)) -- Historical access ([Historical access tree](#historical-access-tree)) +- Historical access ([Archive tree](#archive-tree)) - Global Variables ```mermaid @@ -179,9 +179,9 @@ The contract tree contains information about every function of every contract de Aztec supports the ability to keep the logic of private functions of a smart contract private. In such cases, no information about the logic of that private function will be broadcast; only a randomized merkle root of that contract's data. ::: -## Historical Access Tree +## Archive Tree -The historical access tree is an append-only Merkle tree that stores the headers of all previous blocks in the chain as its leaves. +The archive tree is an append-only Merkle tree that stores the headers of all previous blocks in the chain as its leaves. As private execution relies on proofs generated by the user, the current block header is not known. We can instead base the proofs on historical state. By including all prior block headers (which include commitments to the state), the historical access tree allows us to easily prove that the historic state that a transaction is using for a proof is valid. @@ -197,7 +197,7 @@ PublicDataWrite[Public Data Writes
] ContractData[Contract Data
leaf, address] TxEffect[Transaction Effects
note hashes, nullifiers, contracts, public writes] Body[ Body
L1<>L2 messages, transaction effects] -HistoricalAccessTree[Historical Access Tree
used to validate user-generated proofs and access historical data] +HistoricalAccessTree[Archive Tree
used to validate user-generated proofs and access historical data] StateReference --- PartialStateReference Header --- Body @@ -211,7 +211,7 @@ HistoricalAccessTree --- Header ``` -It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../dev_docs/contracts/syntax/historical_trees.md). +It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../dev_docs/contracts/syntax/how_to_access_history). ## Trees of valid Kernel/Rollup circuit Verification Keys diff --git a/docs/docs/dev_docs/contracts/syntax/historical_trees.md b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md similarity index 55% rename from docs/docs/dev_docs/contracts/syntax/historical_trees.md rename to docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md index 022ff0d052d5..0c72a5cce245 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_trees.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md @@ -1,47 +1,14 @@ --- -title: Accessing History +title: History Reference --- -The Aztec Protocol uses an append-only Merkle tree to store the headers of all previous blocks in the chain as its leaves. You can learn more about how it works in the [concepts section](../../../concepts/advanced/data_structures/trees.md#historical-access-tree). - -On this page you will learn how you can integrate inclusion and non-inclusion proofs into your own smart contract. - -# Historical tree library - -The historical tree library allows you to access any of the following at a given block height before the current height: - -* [Private notes](#note-inclusion) -* [Notes that have been nullified](#nullifier-inclusion) -* [Notes that have not been nullified](#note-validity) -* [Public values](#public-value-inclusion) -* [Contracts](#contract-inclusion) - -Using the historical access tree, you can check that specific notes or nullifiers happened at specific blocks. This can be useful for things such as: - -* Verifying a timestamp that was created in a private context -* Checking eligibility based on historical events (eg for an airdrop) -* Verifying historic ownership / relinquishing of assets - -# How to integrate historical access and inclusion proofs into your smart contract - -Checking if a value was included in a certain block is called an inclusion proof. Similarly, checking that a value was not included is called a non-inclusion proof. - -In this section we will talk about how to integrate the different types of inclusion and non-inclusion proofs into your smart contract. + ## Note inclusion Note inclusion proves that someone owned a note at a specific block number. -### 1. Import note_inclusion into your smart contract - -```rust -aztec::{ -history::{ - #include_code import_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw - } -} -``` -### 2. Call prove_note_inclusion +## prove_note_inclusion `prove_note_inclusion` takes 4 parameters: @@ -52,13 +19,11 @@ history::{ | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | -#### Example +## prove_note_commitment_inclusion -#include_code prove_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust +A commitment is a public acknowledgment of the existence of a note without revealing the context of the note. -### 3. You can also prove the note commitment with prove_note_commitment_inclusion - -`prove_note_commitment_inclusion takes 3 parameters: +`prove_note_commitment_inclusion` takes 3 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| @@ -66,24 +31,11 @@ history::{ | block_number | u32 | Block number for proving note's existence | | context| PrivateContext | Private Context | -#### Example - -#include_code prove_note_commitment_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust - ## Note validity This proves that a note exists and has not been nullified at a specified block. -### 1. Import note_validity - -```rust -aztec::{ -history::{ - #include_code import_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw - } -} -``` -### 2. Call prove_note_validity +### prove_note_validity `prove_note_validity` takes 4 parameters: @@ -94,25 +46,11 @@ history::{ | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | -#### Example - -#include_code prove_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust - ## Nullifier inclusion This proves that a nullifier was included, ie a note had been nullified, in a certain block. -### 1. Import nullifier_inclusion - -```rust -aztec::{ -history::{ - #include_code import_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw - } -} -``` - -### 2. Call prove_nullifier_inclusion +### prove_nullifier_inclusion `prove_nullifier_inclusion` takes 3 parameters: @@ -122,25 +60,11 @@ history::{ | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | -#### Example - -#include_code prove_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust - ## Nullifier non inclusion This proves that a nullifier was not included, ie a note had not been nullified, in a certain block. -### 1. Import nullifier_non_inclusion - -```rust -aztec::{ -history::{ - #include_code import_nullifier_non_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw - } -} -``` - -### 2. Call prove_nullifier_non_inclusion +### prove_nullifier_non_inclusion `prove_nullifier_non_inclusion` takes 3 parameters: @@ -150,31 +74,16 @@ history::{ | block_number | u32 | Block number for proving note's existence | | context | PrivateContext | Private context | -#### Example - -TODO #include_code prove_nullifier_non_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust -### 3. Call note_not_nullified +### note_not_nullified Instead of passing the nullifier, you can check that a note has not been nullified by passing the note. -TODO #include_code prove_note_not_nullified yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust - ## Public value inclusion This proves that a public value exists at a certain block. -### 1. Import public_value_inclusion - -```rust -aztec::{ -history::{ - #include_code import_public_value_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw -} -} -``` - -### 2. Call prove_public_value_inclusion +### prove_public_value_inclusion `prove_public_value_inclusion` takes 3 parameters: @@ -185,25 +94,11 @@ history::{ | block_number | u32 | Block number for proving value's existence | | context | PrivateContext | Private context | -### Example - -#include_code prove_public_value_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust - ## Contract inclusion This proves that a contract exists in, ie had been deployed before or in, a certain block. -### 1. Import contract_inclusion - -```rust -aztec::{ -history::{ - #include_code import_contract_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw - } -} -``` - -### 2. Call prove_contract_inclusion +### prove_contract_inclusion `prove_contract_inclusion` takes 7 parameters: @@ -221,8 +116,4 @@ If there is no associated portal contract, you can use a zero Ethereum address: ```ts new EthAddress(Buffer.alloc(EthAddress.SIZE_IN_BYTES)); -``` - -### Example - -TODO #include_code prove_contract_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md new file mode 100644 index 000000000000..0eff658e86ac --- /dev/null +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md @@ -0,0 +1,97 @@ +--- +title: How to access history from a smart contract +--- + +The Aztec Protocol uses an append-only Merkle tree to store the headers of all previous blocks in the chain as its leaves. This is known as an archive tree. You can learn more about how it works in the [concepts section](../../../../concepts/advanced/data_structures/trees.md#archive-tree). + +# History library + +The history library allows you to access any of the following at a given block height before the current height: +s +* [Private notes](#note-inclusion) +* [Notes that have been nullified](#nullifier-inclusion) +* [Notes that have not been nullified](#note-validity) +* [Public values](#public-value-inclusion) +* [Contracts](#contract-inclusion) + +Using this library, you can check that specific notes or nullifiers happened at specific blocks. This can be useful for things such as: + +* Verifying a timestamp that was created in a private context +* Checking eligibility based on historical events (eg for an airdrop) +* Verifying historic ownership / relinquishing of assets + +**In this guide you will learn how to** +* Prove a note was included in a specified block +* Create a nullifier to prove it was not included in a specified block + +For a more extensive reference, go to [the reference page](./history_lib_reference.md). + +## 1. Import the `history` library from `aztec` + +```rust +aztec::{ + #include_code imports yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr raw +} +``` + +This imports all functions from the `history` library. You should only import the functions you will use in your contract. + +## 2. Create a note to prove inclusion of + +In general you will likely have the note you want to prove inclusion of. But if you are just experimenting you can create a note with a function like below: + +#include_code create_note yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +## 3. Get the note from the PXE + +Retrieve the note from the user's PXE. + +#include_code get_note_from_pxe yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +In this example, the user's notes are stored in a map called `private_values`. We retrieve this map, then select 1 note from it with the value of `1`. + +## 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: + +#include_code prove_note_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +This function takes in 4 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 + +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: + +#include_code prove_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +## 5. Create a nullifier to prove inclusion of + +You can easily nullify a note like so: + +#include_code nullify_note yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +This function gets a note from the PXE like we did in [step 3](#3-get-the-note-from-the-pxe) and nullifies it with `remove()`. + +You can then compute this nullifier with `note.compute_nullifier()`. + +## 6. Prove that a nullifier was included in a specified block + +Call `prove_nullifier_inclusion` like so: + +#include_code prove_nullifier_inclusion yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust + +This takes three arguments: +1. The nullifier +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 + +## Prove contract inclusion, public value inclusion, and note commitment inclusion + +To see what else you can do with the `history` library, check out the [reference](./history_lib_reference.md). \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 3ff5d9382523..78cfbf01509a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -326,8 +326,16 @@ const sidebars = { }, "dev_docs/contracts/syntax/events", "dev_docs/contracts/syntax/functions", - "dev_docs/contracts/syntax/historical_trees", + { + label: "Historical Access", + type: "category", + items: [ + "dev_docs/contracts/syntax/historical_access/how_to_access_history", + "dev_docs/contracts/syntax/historical_access/history_lib_reference", + ], + }, "dev_docs/contracts/syntax/slow_updates_tree", + "dev_docs/contracts/syntax/context", "dev_docs/contracts/syntax/globals", ], 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 557e7f99ef30..a11601c80bad 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 @@ -23,41 +23,30 @@ contract InclusionProofs { note_header::NoteHeader, utils as note_utils, }, - + // docs:start:imports history::{ - // docs:start:import_contract_inclusion contract_inclusion::{ prove_contract_inclusion, - }, - // docs:end:import_contract_inclusion - // docs:start:import_note_inclusion + }, note_inclusion::{ prove_note_commitment_inclusion, prove_note_inclusion, }, - // docs:end:import_note_inclusion - // docs:start:import_note_validity note_validity::{ prove_note_validity, }, - // docs:end:import_note_validity - // docs:start:import_nullifier_inclusion nullifier_inclusion::{ prove_nullifier_inclusion, }, - // docs:end:import_nullifier_inclusion - // docs:start:import_nullifier_non_inclusion nullifier_non_inclusion::{ prove_nullifier_non_inclusion, prove_note_not_nullified, }, - // docs:end:import_nullifier_non_inclusion - // docs:start:import_public_value_inclusion public_value_inclusion::{ prove_public_value_inclusion, }, - // docs:end:import_public_value_inclusion }, + // docs:end:imports }; use dep::value_note::value_note::{ValueNote, ValueNoteMethods, VALUE_NOTE_LEN}; @@ -96,6 +85,7 @@ contract InclusionProofs { storage.public_value.write(value); } + // docs:start:create_note // Creates a value note owned by `owner`. #[aztec(private)] fn create_note(owner: AztecAddress, value: Field) { @@ -103,6 +93,8 @@ contract InclusionProofs { let mut note = ValueNote::new(value, owner); owner_private_values.insert(&mut note, true); } + // docs:end:create_note + // Proves that the owner owned a ValueNote at block `block_number`. #[aztec(private)] @@ -114,11 +106,13 @@ contract InclusionProofs { // PXE performs note commitment inclusion check when you add a new note). spare_commitment: Field ) { + // docs:start:get_note_from_pxe // 1) Get the note from PXE. let private_values = storage.private_values.at(owner.to_field()); let options = NoteGetterOptions::new().select(1, owner.to_field()).set_limit(1); let notes = private_values.get_notes(options); let maybe_note = notes[0]; + // docs:end:get_note_from_pxe // 2) Prove the note inclusion if maybe_note.is_some() { @@ -132,9 +126,7 @@ contract InclusionProofs { // docs:end:prove_note_inclusion } else { // Note was not found so we will prove inclusion of the spare commitment - // docs:start:prove_note_commitment_inclusion prove_note_commitment_inclusion(spare_commitment, block_number, context); - // docs:end:prove_note_commitment_inclusion }; } @@ -189,6 +181,7 @@ contract InclusionProofs { // docs:end:prove_note_validity } + // docs:start:nullify_note #[aztec(private)] fn nullify_note(owner: AztecAddress) { let private_values = storage.private_values.at(owner.to_field()); @@ -198,6 +191,7 @@ contract InclusionProofs { private_values.remove(note); } + // docs:end:nullify_note // Proves nullifier existed at block `block_number`. // Note: I am not getting a nullifier of the note that was created in this contract in this function because it is @@ -217,14 +211,12 @@ contract InclusionProofs { public_value: Field, block_number: u32 // The block at which we'll prove that the public value exists ) { - // docs:start:prove_public_value_inclusion prove_public_value_inclusion( public_value, storage.public_value.storage_slot, block_number, context ); - // docs:end:prove_public_value_inclusion } // Proves that a contract exists at block `block_number`. @@ -244,7 +236,6 @@ contract InclusionProofs { portal_contract_address: EthAddress, block_number: u32 // The block at which we'll prove that the public value exists ) { - // docs:start:prove_contract_inclusion let proven_contract_address = prove_contract_inclusion( deployer_public_key, contract_address_salt, @@ -254,7 +245,6 @@ contract InclusionProofs { block_number, context ); - // docs:end:prove_contract_inclusion // Here typically the factory would add the contract address to its internal map of deployed contracts. } From 174fdeaba5106391df4962951f124deaacb6bfdb Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Mon, 15 Jan 2024 19:38:49 +0900 Subject: [PATCH 06/21] suggestions --- docs/docs/concepts/advanced/data_structures/trees.md | 2 +- .../syntax/historical_access/how_to_access_history.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/docs/concepts/advanced/data_structures/trees.md b/docs/docs/concepts/advanced/data_structures/trees.md index 4ec122168f2c..5373543ff15f 100644 --- a/docs/docs/concepts/advanced/data_structures/trees.md +++ b/docs/docs/concepts/advanced/data_structures/trees.md @@ -211,7 +211,7 @@ HistoricalAccessTree --- Header ``` -It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../dev_docs/contracts/syntax/how_to_access_history). +It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../dev_docs/contracts/syntax/historical_access/how_to_access_history). ## Trees of valid Kernel/Rollup circuit Verification Keys diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md index 0eff658e86ac..2a9ec98b19ad 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md @@ -19,6 +19,8 @@ Using this library, you can check that specific notes or nullifiers happened at * Verifying a timestamp that was created in a private context * Checking eligibility based on historical events (eg for an airdrop) * Verifying historic ownership / relinquishing of assets +* Proving existence of a value in public data tree at a given contract slot +* Proving that a contract was deployed in a given block with some parameters **In this guide you will learn how to** * Prove a note was included in a specified block @@ -94,4 +96,4 @@ You can also prove that a nullifier was not included in a specified block by usi ## Prove contract inclusion, public value inclusion, and note commitment inclusion -To see what else you can do with the `history` library, check out the [reference](./history_lib_reference.md). \ No newline at end of file +To see what else you can do with the `history` library, check out the [reference](./history_lib_reference.md). From b6caf924db63bb4e43b21fbc17e7456496946f2e Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Mon, 15 Jan 2024 20:24:10 +0900 Subject: [PATCH 07/21] fix build errors --- .../contracts/inclusion_proofs_contract/src/main.nr | 1 - 1 file changed, 1 deletion(-) 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 93d541da53fb..e6208ef966b6 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 @@ -95,7 +95,6 @@ contract InclusionProofs { } // docs:end:create_note - // Proves that the owner owned a ValueNote at block `block_number`. #[aztec(private)] fn test_note_inclusion_proof( From 2513fdb0d10a6a4364b4122d527a61d980e454ea Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 16 Jan 2024 10:58:25 +0000 Subject: [PATCH 08/21] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jan Beneš --- .../concepts/advanced/data_structures/trees.md | 14 +++++++------- .../historical_access/history_lib_reference.md | 6 +++--- .../historical_access/how_to_access_history.md | 18 +++++++++--------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/docs/concepts/advanced/data_structures/trees.md b/docs/docs/concepts/advanced/data_structures/trees.md index 5373543ff15f..e29c26e20fbc 100644 --- a/docs/docs/concepts/advanced/data_structures/trees.md +++ b/docs/docs/concepts/advanced/data_structures/trees.md @@ -181,23 +181,23 @@ Aztec supports the ability to keep the logic of private functions of a smart con ## Archive Tree -The archive tree is an append-only Merkle tree that stores the headers of all previous blocks in the chain as its leaves. +The archive tree is an append-only Merkle tree that stores hashes of headers of all previous blocks in the chain as its leaves. -As private execution relies on proofs generated by the user, the current block header is not known. We can instead base the proofs on historical state. By including all prior block headers (which include commitments to the state), the historical access tree allows us to easily prove that the historic state that a transaction is using for a proof is valid. +As private execution relies on proofs generated by the user, the current block header is not known. We can instead base the proofs on historical state. By including all prior block headers (which include commitments to the state), the historical access tree allows us to easily prove that the historical state that a transaction is using for a proof is valid. ```mermaid graph TD; -PartialStateReference[Partial State Data
snapshot of note hash tree, nullifier tree, contract tree, public data tree] -StateReference[State Data Reference
snapshot of L1<>L2 message tree] -GlobalVariables[Global Network Variables
block number, timestamp, version, chain_id] -Header[Block Header Information
last snapshot of tree, hash of body] +PartialStateReference[Partial State
snapshot of note hash tree, nullifier tree, contract tree, public data tree] +StateReference[State Reference
snapshot of L1<>L2 message tree] +GlobalVariables[Global Variables
block number, timestamp, version, chain_id] +Header[Block Header
last snapshot of tree, hash of body] Logs[Transaction Logs
encrypted & non-encrypted logs] PublicDataWrite[Public Data Writes
] ContractData[Contract Data
leaf, address] TxEffect[Transaction Effects
note hashes, nullifiers, contracts, public writes] Body[ Body
L1<>L2 messages, transaction effects] -HistoricalAccessTree[Archive Tree
used to validate user-generated proofs and access historical data] +ArchiveTree[Archive Tree
used to validate user-generated proofs and access historical data] StateReference --- PartialStateReference Header --- Body diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md index 0c72a5cce245..f85e717d4661 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md @@ -6,7 +6,7 @@ title: History Reference ## Note inclusion -Note inclusion proves that someone owned a note 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. ## prove_note_inclusion @@ -48,7 +48,7 @@ This proves that a note exists and has not been nullified at a specified block. ## Nullifier inclusion -This proves that a nullifier was included, ie a note had been nullified, in a certain block. +This proves that a nullifier was included in a certain block (can be used to prove that a note had been nullified). ### prove_nullifier_inclusion @@ -62,7 +62,7 @@ This proves that a nullifier was included, ie a note had been nullified, in a ce ## Nullifier non inclusion -This proves that a nullifier was not included, ie a note had not been nullified, in a certain block. +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 diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md index 2a9ec98b19ad..1e1aded41e56 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md @@ -6,25 +6,25 @@ The Aztec Protocol uses an append-only Merkle tree to store the headers of all p # History library -The history library allows you to access any of the following at a given block height before the current height: +The history library allows you to prove any of the following at a given block height before the current height: s -* [Private notes](#note-inclusion) -* [Notes that have been nullified](#nullifier-inclusion) -* [Notes that have not been nullified](#note-validity) -* [Public values](#public-value-inclusion) -* [Contracts](#contract-inclusion) +* [Note inclusion](#note-inclusion) +* [Nullifier inclusion](#nullifier-inclusion) +* [Note validity](#note-validity) +* [Existence of public value](#public-value-inclusion) +* [Contract inclusion](#contract-inclusion) -Using this library, you can check that specific notes or nullifiers happened at specific blocks. This can be useful for things such as: +Using this library, you can check that specific notes or nullifiers were part of Aztec network state at specific blocks. This can be useful for things such as: * Verifying a timestamp that was created in a private context -* Checking eligibility based on historical events (eg for an airdrop) +* Checking eligibility based on historical events (e.g. for an airdrop by proving that you owned a note) * Verifying historic ownership / relinquishing of assets * Proving existence of a value in public data tree at a given contract slot * Proving that a contract was deployed in a given block with some parameters **In this guide you will learn how to** * Prove a note was included in a specified block -* Create a nullifier to prove it was not included in a specified block +* Create a nullifier and prove it was not included in a specified block For a more extensive reference, go to [the reference page](./history_lib_reference.md). From c08ce222c08f2e5d177999c01a47352d4a204ebe Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 16 Jan 2024 11:05:56 +0000 Subject: [PATCH 09/21] timestamp -> minimum timestamp --- .../contracts/syntax/historical_access/how_to_access_history.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md index 1e1aded41e56..6ae5e794e09d 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md @@ -16,7 +16,7 @@ s Using this library, you can check that specific notes or nullifiers were part of Aztec network state at specific blocks. This can be useful for things such as: -* Verifying a timestamp that was created in a private context +* Verifying a minimum timestamp from a private context * Checking eligibility based on historical events (e.g. for an airdrop by proving that you owned a note) * Verifying historic ownership / relinquishing of assets * Proving existence of a value in public data tree at a given contract slot From dc8435d093554e54a9d9d12b0a2260b79dfe6ee9 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 16 Jan 2024 11:09:44 +0000 Subject: [PATCH 10/21] context -> content --- .../syntax/historical_access/history_lib_reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md index f85e717d4661..dae6565c2761 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md @@ -21,7 +21,7 @@ Note inclusion proves that a note existed (its hash was included in a note hash ## prove_note_commitment_inclusion -A commitment is a public acknowledgment of the existence of a note without revealing the context of the note. +A commitment is a public acknowledgment of the existence of a note without revealing the content of the note. `prove_note_commitment_inclusion` takes 3 parameters: @@ -116,4 +116,4 @@ If there is no associated portal contract, you can use a zero Ethereum address: ```ts new EthAddress(Buffer.alloc(EthAddress.SIZE_IN_BYTES)); -``` \ No newline at end of file +``` From 9a0849006c2c51af6d56a0c5f08abbbfcca3c5df Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 16 Jan 2024 11:10:33 +0000 Subject: [PATCH 11/21] 3 -> 4 parameters Co-authored-by: Rahul Kothari --- .../contracts/syntax/historical_access/history_lib_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md index dae6565c2761..29632b894c4b 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md @@ -85,7 +85,7 @@ This proves that a public value exists at a certain block. ### prove_public_value_inclusion -`prove_public_value_inclusion` takes 3 parameters: +`prove_public_value_inclusion` takes 4 parameters: | Name | Type | Description | |-----------------|------------------------|-----------------------------------------------------| From f1c66486310a453bbc4236d8ec771b150feedc7f Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 16 Jan 2024 11:20:21 +0000 Subject: [PATCH 12/21] added some info about note hash --- .../contracts/syntax/historical_access/history_lib_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md index 29632b894c4b..b798a129243b 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/history_lib_reference.md @@ -21,7 +21,7 @@ Note inclusion proves that a note existed (its hash was included in a note hash ## prove_note_commitment_inclusion -A commitment is a public acknowledgment of the existence of a note without revealing the content of the note. +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](../../../../concepts/advanced/data_structures/trees.md#example-note). `prove_note_commitment_inclusion` takes 3 parameters: From 79f0a95cb7523456252324a50e0f5c08fd8b0372 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 16 Jan 2024 20:47:46 +0900 Subject: [PATCH 13/21] valuenotemethods includecode --- .../syntax/historical_access/how_to_access_history.md | 4 ++++ .../contracts/inclusion_proofs_contract/src/main.nr | 3 ++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md index 6ae5e794e09d..10f85cef64c0 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md @@ -65,6 +65,10 @@ This function takes in 4 arguments: 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 + 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: #include_code prove_note_validity yarn-project/noir-contracts/contracts/inclusion_proofs_contract/src/main.nr rust 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 e6208ef966b6..1850e168a73e 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 @@ -48,8 +48,9 @@ contract InclusionProofs { }, // docs:end:imports }; + // docs:start:value_note_imports use dep::value_note::value_note::{ValueNote, ValueNoteMethods, VALUE_NOTE_LEN}; - + // docs:end:value_note_imports struct Storage { private_values: Map>, public_value: PublicState, From 154b9f2b179374b2f64b4eba6f72382fbb0a0ec6 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 23 Jan 2024 17:36:39 +0900 Subject: [PATCH 14/21] history -> archival blockchain data --- .../contracts/syntax/historical_access/how_to_access_history.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md index 10f85cef64c0..b105fdfc2f16 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md @@ -1,5 +1,5 @@ --- -title: How to access history from a smart contract +title: How to access archival blockchain data from smart contracts --- The Aztec Protocol uses an append-only Merkle tree to store the headers of all previous blocks in the chain as its leaves. This is known as an archive tree. You can learn more about how it works in the [concepts section](../../../../concepts/advanced/data_structures/trees.md#archive-tree). From ef6f481c7400de4db51a95b66ff4fb51def93b0d Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 23 Jan 2024 17:38:05 +0900 Subject: [PATCH 15/21] update how-to title to avoid confusion with slow updates tree --- .../contracts/syntax/historical_access/how_to_access_history.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md index b105fdfc2f16..ba331033ac4a 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md @@ -1,5 +1,5 @@ --- -title: How to access archival blockchain data from smart contracts +title: How to prove existence of historical notes and nullifiers --- The Aztec Protocol uses an append-only Merkle tree to store the headers of all previous blocks in the chain as its leaves. This is known as an archive tree. You can learn more about how it works in the [concepts section](../../../../concepts/advanced/data_structures/trees.md#archive-tree). From 8a3d5167119fcf6eddd2019f00ea7d00a3698d41 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 23 Jan 2024 17:39:22 +0900 Subject: [PATCH 16/21] update sidebar to match new title --- .../{how_to_access_history.md => how_to_prove_history.md} | 0 docs/sidebars.js | 4 ++-- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/docs/dev_docs/contracts/syntax/historical_access/{how_to_access_history.md => how_to_prove_history.md} (100%) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md similarity index 100% rename from docs/docs/dev_docs/contracts/syntax/historical_access/how_to_access_history.md rename to docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md diff --git a/docs/sidebars.js b/docs/sidebars.js index 78cfbf01509a..6e5a38365092 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -327,10 +327,10 @@ const sidebars = { "dev_docs/contracts/syntax/events", "dev_docs/contracts/syntax/functions", { - label: "Historical Access", + label: "Proving Historical Blockchain Data", type: "category", items: [ - "dev_docs/contracts/syntax/historical_access/how_to_access_history", + "dev_docs/contracts/syntax/historical_access/how_to_prove_history", "dev_docs/contracts/syntax/historical_access/history_lib_reference", ], }, From 906ffb09ce48c831584fac96327ba71499755835 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Tue, 23 Jan 2024 10:33:03 +0000 Subject: [PATCH 17/21] Update docs/docs/concepts/advanced/data_structures/trees.md Co-authored-by: Rahul Kothari --- docs/docs/concepts/advanced/data_structures/trees.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/advanced/data_structures/trees.md b/docs/docs/concepts/advanced/data_structures/trees.md index e29c26e20fbc..29aa6d5c365e 100644 --- a/docs/docs/concepts/advanced/data_structures/trees.md +++ b/docs/docs/concepts/advanced/data_structures/trees.md @@ -14,7 +14,7 @@ Data includes: - Nullifiers to invalidate old private state ([Nullifier tree](#nullifier-tree)) - Public state ([Public State tree](#public-state-tree)) - Contracts ([Contract tree](#contract-tree)) -- Historical access ([Archive tree](#archive-tree)) +- Archive tree for Historical access ([Archive tree](#archive-tree)) - Global Variables ```mermaid From 689dbbf9aa5ecd587bc30b8a1771e1b7dae1f908 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 24 Jan 2024 03:04:04 +0000 Subject: [PATCH 18/21] grammar nits Co-authored-by: josh crites --- .../contracts/syntax/historical_access/how_to_prove_history.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md index ba331033ac4a..82515be87008 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md @@ -7,7 +7,6 @@ The Aztec Protocol uses an append-only Merkle tree to store the headers of all p # History library The history library allows you to prove any of the following at a given block height before the current height: -s * [Note inclusion](#note-inclusion) * [Nullifier inclusion](#nullifier-inclusion) * [Note validity](#note-validity) @@ -81,7 +80,7 @@ You can easily nullify a note like so: This function gets a note from the PXE like we did in [step 3](#3-get-the-note-from-the-pxe) and nullifies it with `remove()`. -You can then compute this nullifier with `note.compute_nullifier()`. +You can then compute this nullifier with `note.compute_nullifier(&mut context)`. ## 6. Prove that a nullifier was included in a specified block From 65b9517cca412a45e95951df96d64d8eb18b38bc Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 24 Jan 2024 12:06:10 +0900 Subject: [PATCH 19/21] fix broken link --- .../syntax/historical_access/how_to_prove_history.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md index 82515be87008..4390b4493ae2 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md @@ -7,11 +7,11 @@ The Aztec Protocol uses an append-only Merkle tree to store the headers of all p # History library The history library allows you to prove any of the following at a given block height before the current height: -* [Note inclusion](#note-inclusion) -* [Nullifier inclusion](#nullifier-inclusion) -* [Note validity](#note-validity) -* [Existence of public value](#public-value-inclusion) -* [Contract inclusion](#contract-inclusion) +* [Note inclusion](./history_lib_reference.md#note-inclusion) +* [Nullifier inclusion](./history_lib_reference.md#nullifier-inclusion) +* [Note validity](./history_lib_reference.md#note-validity) +* [Existence of public value](./history_lib_reference.md#public-value-inclusion) +* [Contract inclusion](./history_lib_reference.md#contract-inclusion) Using this library, you can check that specific notes or nullifiers were part of Aztec network state at specific blocks. This can be useful for things such as: From dbfa14cbcaa8e95cb4bac1dcaae1b1feaddc7af7 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 24 Jan 2024 15:49:52 +0900 Subject: [PATCH 20/21] fix broken link --- docs/docs/concepts/advanced/data_structures/trees.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/advanced/data_structures/trees.md b/docs/docs/concepts/advanced/data_structures/trees.md index 29aa6d5c365e..d29f9c046697 100644 --- a/docs/docs/concepts/advanced/data_structures/trees.md +++ b/docs/docs/concepts/advanced/data_structures/trees.md @@ -211,7 +211,7 @@ HistoricalAccessTree --- Header ``` -It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../dev_docs/contracts/syntax/historical_access/how_to_access_history). +It can also be used to find information about notes, public state, and contracts that were included in a certain block using [inclusion and non-inclusion proofs](../../../dev_docs/contracts/syntax/historical_access/how_to_prove_history.md). ## Trees of valid Kernel/Rollup circuit Verification Keys From 1ce48d17ffbb6b6065fc65c9d21744b719a33412 Mon Sep 17 00:00:00 2001 From: Cat McGee Date: Wed, 24 Jan 2024 09:04:16 +0000 Subject: [PATCH 21/21] jan suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jan Beneš --- .../contracts/syntax/historical_access/how_to_prove_history.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md index 4390b4493ae2..28e3ea04ccf3 100644 --- a/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md +++ b/docs/docs/dev_docs/contracts/syntax/historical_access/how_to_prove_history.md @@ -2,7 +2,7 @@ title: How to prove existence of historical notes and nullifiers --- -The Aztec Protocol uses an append-only Merkle tree to store the headers of all previous blocks in the chain as its leaves. This is known as an archive tree. You can learn more about how it works in the [concepts section](../../../../concepts/advanced/data_structures/trees.md#archive-tree). +The Aztec Protocol uses an append-only Merkle tree to store hashes of the headers of all previous blocks in the chain as its leaves. This is known as an archive tree. You can learn more about how it works in the [concepts section](../../../../concepts/advanced/data_structures/trees.md#archive-tree). # History library