Update state-vars #11
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for aztec-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
nventuro
reviewed
Dec 3, 2025
| ``` | ||
|
|
||
| In Aztec.nr we instead define a `struct` (link to noir structs) that holds all state variables. we call this struct **the storage struct**, and it is identified by having the `#[storage]` macro (link to storage api ref) applied to it. | ||
| In Aztec.nr, we define a [`struct`](https://noir-lang.org/docs/noir/concepts/data_types/structs) that holds _all_ state variables. This struct is called **the storage struct**, and it is identified by having the `#[storage]` macro applied to it. |
Contributor
There was a problem hiding this comment.
(link to storage api ref)
This and other removed link suggestions would be quite valuable I think. I know we don't yet have the docs for them, but if we already know the structure of the docsite we can at least link to these empty pages. I worry if we just remove these notes we'll forget to add them back.
| ``` | ||
|
|
||
| The storage struct can have any name, but it is typically just called `Storage`. this struct must also have a generic type called C or Context - this is unfortunate boilerplate (link to api ref where we explain _why_ this must exist and what it means - which we don't think is something users need to know about, but some might be curious). | ||
| The storage struct can have _any_ name, but it is _typically_ named `Storage`. This struct must also have a generic type called `C` or `Context` - this is an unfortunate boilerplate parameter that provides execution mode information. |
Contributor
There was a problem hiding this comment.
Looking at our test suite I just realized we don't allow for any name other than Storage 🙃
| - For public state variables, storage slots are related to slots in the public data tree | ||
| - For private state variables, storage slots are metadata that gets included in the note hash | ||
|
|
||
| The purpose of slots is the same for both domains: they keep the values of different state values _separate_ so that they do not interfere with one another. |
Contributor
There was a problem hiding this comment.
Suggested change
| The purpose of slots is the same for both domains: they keep the values of different state values _separate_ so that they do not interfere with one another. | |
| The purpose of slots is the same for both domains: they keep the values of different state variables _separate_ so that they do not interfere with one another. |
This was a typo of mine in the original text.
| The purpose of slots is the same for both domains: they keep the values of different state values _separate_ so that they do not interfere with one another. | ||
|
|
||
| For example, a `Map<AztecAddress, PublicMutable<UintNote>>` can be accessed with an address to obtain a `PublicMutable` that corresponds to it. This is exactly equivalent to a Solidity `mapping (address => uint)`. | ||
| Storage slots are a low-level detail that developers don't typically need to concern themselves with. They are automatically allocated to each state variable by Aztec.nr. |
Contributor
There was a problem hiding this comment.
My original comment included something about it being dangerous to manually assign/use storage slots, I think we should keep it.
| `PublicMutable` is the simplest kind of public state variable: a value that can be read and written. It is essentially the same as a non-`immutable` or `constant` Solidity state variable. | ||
|
|
||
| because they reside in the network's public storage tree (link to foundational concepts), they can only be written to by public contract functions. it is possible to read _past_ values of a public state variable in a private contract function, but the current values of the network's public state tree are not accessible in those. this means that most public state variables cannot be read from a private function - though there's exceptions. | ||
| It **cannot be read or written to privately**, but it is possible to call private functions that enqueue a public call in which a `PublicMutable` is accessed. For example, a voting contract may allow private submission of votes which then enqueue a public call in which the vote count, represented as a `PublicMutable<u128>`, is incremented. This would let anyone see how many votes have been cast, while preserving the privacy of the account that cast the vote. |
Contributor
There was a problem hiding this comment.
Suggested change
| It **cannot be read or written to privately**, but it is possible to call private functions that enqueue a public call in which a `PublicMutable` is accessed. For example, a voting contract may allow private submission of votes which then enqueue a public call in which the vote count, represented as a `PublicMutable<u128>`, is incremented. This would let anyone see how many votes have been cast, while preserving the privacy of the account that cast the vote. | |
| It **cannot be read or written to privately**, but it is possible to have private functions enqueue a public call in which a `PublicMutable` is accessed. For example, a voting contract may allow private submission of votes which then enqueue a public call in which the vote count, represented as a `PublicMutable<u128>`, is incremented. This would let anyone see how many votes have been cast, while preserving the privacy of the account that cast the vote. |
| recipients learning about notes created for them is known as 'note discovery', which is a process aztecnr handles efficiently automatically. it does mean however that when a note is created, a _message_ with the content of note is created and needs to be delivered to a recipient via one of multiple means (link to messages). | ||
| Most often, nullifiers are used to mark a note as being spent, which prevents note double spends. The nullifier is typically computed as a **hash of the note contents concatenated with a private key of the note's owner**. These values are **immutable**, and only the owner knows their private keys, ensuring both determinism and secrecy. | ||
|
|
||
| ##### Note Lifecycle |
Contributor
There was a problem hiding this comment.
I do not agree with the removal of this section. Yes, it is long, and yes, it delays the explanation of state variables (which is what this article is about after all), but it is quite critical and it introduces lots of important concepts.
If anything, we could have a different page blather on about notes, nullifiers, lifecycle, delivery, etc, remove that entire section from this page, and just go 'if you don't know what we mean by notes and nullifiers, go read this thing first and then come back here'.
| - `MessageDelivery`: Either `CONSTRAINED_ONCHAIN` (verified in the circuit) or `UNCONSTRAINED_ONCHAIN` (cheaper but less secure) | ||
|
|
||
| - insertion: the transaction is sent to the network and gets included in a block. the note hash is inserted into the note hash tree - this is visible to the entire network, but the content of the note remains private. (link to protocol details - note hash tree insertion and tx effects) | ||
| - **`.discard()`**: Explicitly discards the note without emitting it (useful when you're reading but not sending) |
Contributor
There was a problem hiding this comment.
dicard is rarely, if ever, used. If reading a private mutable you still need to deliver the replacement note, failure to do so will lock you out of access to the state variable forever.
| #### Accessing the Note | ||
|
|
||
| - reading: while executing private contract function, the recipient fetches the note's content and metadata from their private database and shows that its hash exists in the note hash tree as part of the zero-knowledge proof. | ||
| After calling `.emit()` or `.discard()`, you can access the underlying note using the `.note` property: |
Contributor
There was a problem hiding this comment.
I'd not go crazy on this section since NoteEmission is about to change in its naming (for the better).
| | `PrivateImmutable` | no | no | no | Fixed configuration, one-way actions (e.g. initialization settings for a proposal) | | ||
| | `PrivateSet` | yes | yes | yes | Aggregated state others can add to, e.g. token balance (set of amount notes), nft collections (set of nft ids) | | ||
|
|
||
| ### How aztec-nr Abstracts Private State Variables |
Contributor
There was a problem hiding this comment.
Do you find this entire bit useless?
Comment on lines
+356
to
+364
| To update the value of a `PrivateMutable`, we can use the `replace` method: | ||
|
|
||
| ```rust | ||
| #[external("private")] | ||
| fn update_settings(new_value: u8) { | ||
| let owner = self.msg_sender(); | ||
| self.storage.user_settings.at(owner).replace(|_| SettingsNote::new(new_value, owner)).emit(owner, MessageDelivery.CONSTRAINED_ONCHAIN); | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
I'd maybe also include an example with e.g. a callcount to better motivate replace.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.