From 80a4165170d96719f569dfe187c3b005575bace0 Mon Sep 17 00:00:00 2001 From: James Zaki Date: Mon, 26 Feb 2024 15:58:47 +0000 Subject: [PATCH] docs: re-split notes and fixes --- .../writing_contracts/storage/notes.md | 78 +++++++++++++++++ docs/docs/learn/concepts/storage/notes.md | 87 +------------------ docs/sidebars.js | 1 + 3 files changed, 82 insertions(+), 84 deletions(-) create mode 100644 docs/docs/developers/contracts/writing_contracts/storage/notes.md diff --git a/docs/docs/developers/contracts/writing_contracts/storage/notes.md b/docs/docs/developers/contracts/writing_contracts/storage/notes.md new file mode 100644 index 000000000000..88b050a872d7 --- /dev/null +++ b/docs/docs/developers/contracts/writing_contracts/storage/notes.md @@ -0,0 +1,78 @@ +--- +title: Using Notes +--- + +Some optionally background resources on notes can be seen here: +- [High level network architecture](../../../../learn/about_aztec/technical_overview#high-level-network-architecture), specifically the Private Execution Environment +- [Transaction lifecycle (simple diagram)](../../../../learn/concepts/transactions#simple-example-of-the-private-transaction-lifecycle) +- [Public and Private state](../../../../learn/concepts/hybrid_state/main) + +Outside of this there are many more details to discover that will be skipped over for now: +- Private and public contexts +- Encryption keys and events +- Oracle's role in using notes +- Value Serialization/Deserialization + +This explainer will go through some examples that touch on what has been covered [here](../../../../learn/concepts/storage/notes). + +#### Some code context +The way Aztec (`aztec-packages` monorepo) benefits from the Noir language is via three important components: +- `Aztec-nr` - a Noir framework enabling contracts on Aztec, written in Noir. Includes useful Note implementations. +- `noir contracts` - , example Aztec contracts +- `noir-protocol-circuits` - a crate containing essential circuits for the protocol (public circuits and private wrappers) + +A lot of what we will look at will be in [aztec-nr/aztec/src/note](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note), specifically the lifecycle and note interface. +Looking at the noir circuits in these components, you will see references to the distinction between public/private execution and state. + +### Lifecycle functions +Inside the [lifecycle]( +https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/lifecycle.nr) circuits we see the functions to create and destroy a note, implemented as insertions of note hashes and nullifiers respectively. + +We also see a function to create a note hash from the public context, a way of creating a private variable from a public call (run in the sequencer). + +### Note Interface functions +To see a [note_interface](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) implementation, we will look at a simple [ValueNote](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/value-note/src/value_note.nr). + +#### Computing hashes and nullifiers +A few key functions in the note interface are around computing the note hash and nullifier, with logic to get/use secret keys from the private context. + +In the ValueNote implementation you'll notice that it uses the `pedersen_hash` function. This is currently required by the protocol, but may be updated to another hashing function, like poseidon. + +As a convenience, the outer [note/utils.nr](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/utils.nr) contains an implementation of a function required by Aztec contracts using private storage: `compute_note_hash_and_nullifier` + +#### Serialization and deserialization +Serialization/deserialization of content is used to convert between the Note's variables and a generic array of Field elements. The Field type is understood and used by lower level crypographic libraries. +This is analogous to the encoding/decoding between variables and bytes in solidity. + +For example in ValueNote, the `serialize_content` function simply returns: the value, owner address (as a field) and the note randomness; as an array of Field elements. + +### Value as a sum of Note +We recall that multiple notes are associated with a "slot" (or ID), and so the value of a numerical note (like ValueNote) is the sum of each note's value. +The helper function in [balance_utils](https://github.com/AztecProtocol/aztec-packages/blob/#include_/noir-projects/aztec-nr/value-note/src/balance_utils.nr) implements this logic taking a `Set` of `ValueNotes`. + +A couple of things worth clarifying: +- A `Set` takes a Generic type, specified here as `ValueNote`, but can be any `Note` type (for all notes in the set). +- A `Set` of notes also specifies *the* slot of all Notes that it holds. + +### Abstracting Notes +The Aztec.nr framework includes an [easy_private_state](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/easy-private-state/src/easy_private_state.nr) for use in contracts. + +The struct is an `EasyPrivateUint` that contains a Context, Set of ValueNotes, and storage_slot (used when setting the Set). + +The `add` function shows the simplicity of appending a new note to all existing ones. On the other hand, `sub` (subtraction), needs to first add up all existing values (consuming them in the process), and then insert a single new value of the difference between the sum and parameter. + +----- + +### Apply +To see this in action, try one of the [Tutorials](../../../tutorials/main) + +### Further reading + +- [Proof of prior notes](../../writing_contracts/historical_data/archive_tree/how_to_prove_history) - public/private reading of public/private proof of state (public or private) + +### References +- [Notes explainer](../../../../learn/concepts/storage/notes) + +Related: +- ["Stable" state variable](https://github.com/AztecProtocol/aztec-packages/issues/4130) +- [Code: Aztec-Patterns](https://github.com/defi-wonderland/aztec-patterns) diff --git a/docs/docs/learn/concepts/storage/notes.md b/docs/docs/learn/concepts/storage/notes.md index 0d63b85c3e83..addb241b213a 100644 --- a/docs/docs/learn/concepts/storage/notes.md +++ b/docs/docs/learn/concepts/storage/notes.md @@ -18,9 +18,8 @@ This article will restrict its focus to how private variables are implemented wi Under the hood, the Aztec protocol handles some important details around public and private function calls. Notably around calls between them and relevant delays to avoid race conditions around state reads/writes (more [here](../pxe/acir_simulator#simulating-functions)). Whilst it just works for us under the hood, a detailed explanation of the transaction lifecycle can be found [here](../transactions#simple-example-of-the-private-transaction-lifecycle). -## Private variables in Aztec -### Definition -State variables in an Aztec contract are defined inside a struct specifically named `Storage`, and must satisfy the [Note Interface](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) and contain a [Note header](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/note/note_header.nr). +## Private state variables in Aztec +State variables in an Aztec contract are defined inside a struct specifically named `Storage`, and must satisfy the [Note Interface](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) and contain a [Note header](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/aztec-nr/aztec/src/note/note_header.nr). The Note header struct contains the contract address which the value is effectively siloed to, a nonce to ensure unique Note hashes, and a storage "slot" (or ID) to associate multiple notes. @@ -62,87 +61,7 @@ Note: only those with appropriate keys/information will be able to successfully To update a value, its previous note hash(es) are nullified. The new note value is updated in the PXE, and the updated note hash inserted into the note hash tree. This also increments the nonce. -## Using Noir - -Some optionally background resources on notes can be seen here: -- [High level network architecture](../../about_aztec/technical_overview#high-level-network-architecture), specifically the Private Execution Environment -- [Transaction lifecycle (simple diagram)](../transactions#simple-example-of-the-private-transaction-lifecycle) -- [Public and Private state](../hybrid_state/main) - -Outside of this there are many more details to discover that will be skipped over for now: -- Private and public contexts -- Encryption keys and events -- Oracle's role in using notes -- Value Serialization/Deserialization - -This explainer will go through some examples that touch on what has been covered so far. - -#### Some code context -The way Aztec (`aztec-packages` monorepo) benefits from the Noir language is via three important components: -- `Aztec-nr` - a Noir framework enabling contracts on Aztec, written in Noir. Includes useful Note implementations. -- `noir contracts` - , example Aztec contracts -- `noir-protocol-circuits` - a crate containing essential circuits for the protocol (public circuits and private wrappers) - -A lot of what we will look at will be in [aztec-nr/aztec/src/note](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/note), specifically the lifecycle and note interface. -Looking at the noir circuits in these components, you will see references to the distinction between public/private execution and state. - -### Lifecycle functions -Inside the [lifecycle]( -https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/note/lifecycle.nr) circuits we see the functions to create and destroy a note, implemented as insertions of note hashes and nullifiers respectively. - -We also see a function to create a note hash from the public context, a way of creating a private variable from a public call (run in the sequencer). - -### Note Interface functions -To see a [note_interface](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/note/note_interface.nr) implementation, we will look at a simple [ValueNote](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/value-note/src/value_note.nr). - -#### Computing hashes and nullifiers -A few key functions in the note interface are around computing the note hash and nullifier, with logic to get/use secret keys from the private context. - -In the ValueNote implementation you'll notice that it uses the `pedersen_hash` function. This is currently required by the protocol, but may be updated to another hashing function, like poseidon. - -As a convenience, the outer [note/utils.nr](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/note/utils.nr) contains an implementation of a function required by Aztec contracts using private storage: `compute_note_hash_and_nullifier` - -#### Serialization and deserialization -Serialization/deserialization of content is used to convert between the Note's variables and a generic array of Field elements. The Field type is understood and used by lower level crypographic libraries. -This is analogous to the encoding/decoding between variables and bytes in solidity. - -For example in ValueNote, the `serialize_content` function simply returns: the value, owner address (as a field) and the note randomness; as an array of Field elements. - -### Value as a sum of Note -We recall that multiple notes are associated with a "slot" (or ID), and so the value of a numerical note (like ValueNote) is the sum of each note's value. -The helper function in [balance_utils](https://github.com/AztecProtocol/aztec-packages/blob/#include_/noir-projects/aztec-nr/value-note/src/balance_utils.nr) implements this logic taking a `Set` of `ValueNotes`. - -A couple of things worth clarifying: -- A `Set` takes a Generic type, specified here as `ValueNote`, but can be any `Note` type (for all notes in the set). -- A `Set` of notes also specifies *the* slot of all Notes that it holds. - -### Abstracting Notes -The Aztec.nr framework includes an [easy_private_state](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/easy-private-state/src/easy_private_state.nr) for use in contracts. - -The struct is an `EasyPrivateUint` that contains a Context, Set of ValueNotes, and storage_slot (used when setting the Set). - -The `add` function shows the simplicity of appending a new note to all existing ones. On the other hand, `sub` (subtraction), needs to first add up all existing values (consuming them in the process), and then insert a single new value of the difference between the sum and parameter. - ------ - -### Apply -To see this in action, try one of the [Tutorials](../../../developers/tutorials/main) ### Further reading -- [Proof of prior notes](https://docs.aztec.network/developers/contracts/syntax/historical_access/how_to_prove_history) - public/private reading of public/private proof of state (public or private) - -### References -1. [learn/concepts/hybrid_state/main#private-state](https://docs.aztec.network/learn/concepts/hybrid_state/main#private-state) -1. [learn/concepts/storage/trees/main#note-hash-tree](https://docs.aztec.network/learn/concepts/storage/trees/main#note-hash-tree) -1. [learn/concepts/storage/storage_slots#private-state-slots](https://docs.aztec.network/learn/concepts/storage/storage_slots#private-state-slots---slots-arent-real) -1. [developers/contracts/syntax/storage/main](https://docs.aztec.network/developers/contracts/syntax/storage/main) - 1. [developers/contracts/syntax/storage/private_state](https://docs.aztec.network/developers/contracts/syntax/storage/private_state) - 1. [developers/contracts/syntax/storage/storage_slots](https://docs.aztec.network/developers/contracts/syntax/storage/storage_slots) -1. [developers/contracts/syntax/context#the-private-context](https://docs.aztec.network/developers/contracts/syntax/context#the-private-context) -1. [developers/wallets/main#recipient-encryption-keys](https://docs.aztec.network/developers/wallets/main#recipient-encryption-keys) - - -Related: -- ["Stable" state variable](https://github.com/AztecProtocol/aztec-packages/issues/4130) -- [Code: Aztec-Patterns](https://github.com/defi-wonderland/aztec-patterns) +- [Using Notes Explainer](../../../developers/contracts/writing_contracts/storage/notes) diff --git a/docs/sidebars.js b/docs/sidebars.js index 5342a35edc6f..c3c42d714e55 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -363,6 +363,7 @@ const sidebars = { }, items: [ "developers/contracts/writing_contracts/storage/define_storage", + "developers/contracts/writing_contracts/storage/notes", "developers/contracts/writing_contracts/storage/storage_slots", ], },