Merge branch 'next' into merge-train/barretenberg

Author: AztecBot

noir-projects/aztec-nr/aztec/src/state_vars/mod.nr

@@ -1,4 +1,12 @@
 //! Storage for contract state.
+//!
+//! Contracts store their state in _state variables_. In Solidity, a state variable is simply any value declared inside
+//! a contract, e.g. `contract Token { uint256 totalSupply; }`, and they can be one of many kinds (primitive values,
+//! mappings, arrays, immutable, etc.).
+//!
+//! Due to Aztec contracts being able to store both public and private state, there are many more different types of
+//! state variables, each with their nuance and use cases. Understanding these is key to understanding how a contract
+//! works.
 
 pub mod map;
 pub mod owned_state_variable;

noir-projects/aztec-nr/aztec/src/state_vars/public_mutable.nr

@@ -2,42 +2,80 @@ use crate::context::{PublicContext, UtilityContext};
 use crate::state_vars::state_variable::StateVariable;
 use dep::protocol_types::traits::Packable;
 
-/// # PublicMutable
+/// Mutable public values.
 ///
-/// PublicMutable is a public state variable type for values that can be read
-/// and written within public [external](crate::macros::functions::external) functions of your smart contract.
+/// This is the most basic public state variable. It is equivalent to a non-`immutable` non-`constant` Solidity state
+/// variable.
 ///
-/// You can declare a state variable of type PublicMutable within your contract's
-/// [storage](crate::macros::storage::storage) struct:
+/// ## Access Patterns
 ///
-/// E.g.:
-/// `your_variable: PublicMutable<T, Context>`
-/// or:
-/// `your_mapping: Map<Field, PublicMutable<T, Context>>`
+/// A value stored in a `PublicMutable` can be read and written from public contract functions. It is not possible to
+/// read or write another contract's `PublicMutable` values directly: the only way to achieve this is to call a public
+/// function on that contract.
 ///
-/// The methods of PublicMutable are:
-/// - `read`
-/// - `write`
-/// (see the methods' own doc comments for more info).
+/// It is not possible to read or write a `PublicMutable` from private contract functions. It is possible however for a
+/// private function to [enqueue a public call to itself](crate::contract_self::ContractSelf::enqueue_self) in which it
+/// performs the required operation.
 ///
-/// ## Example.
+/// For an immutable variant which can be read from private functions, see
+/// [PublicImmutable](crate::state_vars::PublicImmutable).
 ///
-/// A voting contract's proposal count can be represented as a PublicMutable<u64>.
-/// The count can be read by anyone to see how many proposals exist, and incremented
-/// when new proposals are submitted.
+/// For a mutable (with restrictions) variant which can be read from private functions see
+/// [DelayedPublicMutable](crate::state_vars::DelayedPublicMutable).
 ///
-/// # Generic Parameters:
+/// ## Privacy
 ///
-/// * `T` - The type of value stored (must implement Packable).
-/// * `Context` - The execution context (PublicContext or UtilityContext).
+/// `PublicMutable` provides zero privacy. All write and read operations are public: the entire network can see these
+/// accesses and the data involved.
 ///
-/// # Advanced
+/// ## Use Cases
 ///
-/// Unlike private state variables which use notes, PublicMutable stores values
-/// directly in Aztec's public data tree. This enables direct read and write
-/// access to the current state during public function execution.
+/// This is suitable for any kind of global state that needs to be accessible by everyone. For example, a token may have
+/// a public total supply, or a voting contract may have public vote tallies.
 ///
-/// docs:start:public_mutable_struct
+/// Note that contracts having public values does not necessarily mean the the actions that update these values must
+/// themselves be wholly public. For example, the token could allow for private minting and burning, and casting a vote
+/// could be kept private: these private functions would enqueue a public function that writes to the `PublicMutable`.
+///
+/// Similarly, private functions can enqueue a public call in which the `PublicMutable` is checked to meet some
+/// condition. For example, a private action might be executable only if the vote count has exceeded some threshold, in
+/// which case the private function would enqueue a public function that reads from the `PublicMutable`.
+///
+/// Such patterns preserve the privacy of the account that executed the action, as well as details related to the
+/// private execution itself, but they _do_ reveal that the transaction interacted with the `PublicMutable` value (and
+/// hence that the contract was called), as all accesses to it are public. The
+/// [only_self](crate::macros::functions::only_self) attribute is very useful when implementing this.
+///
+/// ## Examples
+///
+/// Declaring a `PublicMutable` in the the contract's [storage](crate::macros::storage::storage) struct requires
+/// specifying the type `T` that is stored in the variable:
+///
+/// ```noir
+/// #[storage]
+/// struct Storage<Context> {
+///     total_supply: PublicMutable<u128, Context>,
+///     public_balances: Map<AztecAddress, PublicMutable<u128, Context>, Context>,
+///
+///     vote_tallies: Map<ElectionId, PublicMutable<u128, Context>, Context>,
+/// }
+/// ```
+///
+/// ## Requirements
+///
+/// The type `T` stored in the `PublicMutable` must implement the `Packable` trait.
+///
+/// ## Implementation Details
+///
+/// Values are packed and stored directly in the public storage tree, with no overhead. A `PublicMutable` therefore
+/// takes up as many storage slots as the packing length of the stored type `T`.
+///
+/// Private reads are not possible because private functions do not have access to the current network state, only the
+/// _past_ state at the anchor block. They _can_ perform historical reads of `PublicMutable` values at past times, but
+/// they have no way to guarantee that the value has not changed since then.
+/// [PublicImmutable](crate::state_vars::PublicImmutable) and
+/// [DelayedPublicMutable](crate::state_vars::DelayedPublicMutable) are examples of public state variables that _can_ be
+/// read privately by restricting mutation.
 pub struct PublicMutable<T, Context> {
     context: Context,
     storage_slot: Field,
@@ -58,33 +96,90 @@ where
 }
 
 impl<T> PublicMutable<T, PublicContext> {
-    /// Reads the current value stored in this PublicMutable state variable.
+    /// Returns the current value.
     ///
-    /// # Returns
+    /// If [write](PublicMutable::write) has never been called, then this returns the default empty public storage
+    /// value, which is all zeroes - equivalent to `let t = T::unpack(std::mem::zeroed());`.
     ///
-    /// * `T` - The current value stored in this PublicMutable.
+    /// It is not possible to detect if a `PublicMutable` has ever been initialized or not other than by testing for the
+    /// zero sentinel value. For a more robust solution, store an `Option<T>` in the `PublicMutable`.
     ///
-    /// docs:start:public_mutable_struct_read
+    /// ## Examples
+    ///
+    /// A public getter that returns the current value:
+    /// ```noir
+    /// #[external("public")]
+    /// fn get_total_supply() -> u128 {
+    ///     self.storage.total_supply.read()
+    /// }
+    /// ```
+    ///
+    /// An [only_self](crate::macros::functions::only_self) helper that asserts a condition a private function requires:
+    /// ```noir
+    /// #[external("private")]
+    /// fn execute_proposal(election_id: ElectionId) {
+    ///     self.enqueue_self._assert_vote_passed(election_id);
+    ///
+    ///     // execute the proposal - this remains private
+    /// }
+    ///
+    /// #[external("public")]
+    /// #[only_self]
+    /// fn _assert_vote_passed(election_id: ElectionId) {
+    ///     assert(self.storage.vote_tallies.at(election_id).read() >= VOTE_PASSED_THRESHOLD);
+    /// }
+    /// ```
+    ///
+    /// ## Cost
+    ///
+    /// The `SLOAD` AVM opcode is invoked a number of times equal to `T`'s packed length.
     pub fn read(self) -> T
     where
         T: Packable,
     {
         self.context.storage_read(self.storage_slot)
     }
 
-    /// Writes a new value to this PublicMutable state variable.
+    /// Stores a new value.
+    ///
+    /// The old value is overridden and cannot be recovered. The new value can be immediately retrieved by
+    /// [read](PublicMutable::read).
+    ///
+    /// ## Examples
+    ///
+    /// A public setter that updates the current value:
+    /// ```noir
+    /// #[external("public")]
+    /// fn mint_tokens(recipient: AztecAddress, amount: u128) {
+    ///     let current_recipient_balance = self.storage.public_balances.at(recipient).read();
+    ///     self.storage.public_balances.at(recipient).write(current_recipient_balance + amount);
+    ///
+    ///     let current_supply = self.storage.total_supply.read();
+    ///     self.storage.total_supply.write(current_supply + amount);
+    /// }
+    /// ```
     ///
-    /// # Arguments
+    /// An [only_self](crate::macros::functions::only_self) helper that updates public state trigered by a private
+    /// function:
+    /// ```noir
+    /// #[external("private")]
+    /// fn vote_for_proposal(election_id: ElectionId, votes: u128) {
+    ///     // validate the sender can cast this many votes - this remains private
     ///
-    /// * `value` - The new value to store in this PublicMutable.
+    ///     self.enqueue_self._tally_vote(election_id, votes);
+    /// }
     ///
-    /// # Advanced
+    /// #[external("public")]
+    /// #[only_self]
+    /// fn _tally_vote(election_id: ElectionId, votes: u128) {
+    ///     let current = self.storage.vote_tallies.read();
+    ///     self.storage.vote_tallies.write(current + votes);
+    /// }
+    /// ```
     ///
-    /// This function updates the value stored in Aztec's public data tree.
-    /// The new value becomes immediately available to subsequent reads within
-    /// the same transaction.
+    /// ## Cost
     ///
-    /// docs:start:public_mutable_struct_write
+    /// The `SSTORE` AVM opcode is invoked a number of times equal to `T`'s packed length.
     pub fn write(self, value: T)
     where
         T: Packable,
@@ -94,15 +189,22 @@ impl<T> PublicMutable<T, PublicContext> {
 }
 
 impl<T> PublicMutable<T, UtilityContext> {
-    /// Reads the current value stored in this PublicMutable state variable.
+    /// Returns the value at the anchor block.
     ///
-    /// Notice that this function is executable only within a UtilityContext, which
-    /// is an unconstrained environment on the user's local device.
+    /// If [write](PublicMutable::write) has never been called, then this returns the default empty public storage
+    /// value, which is all zeroes - equivalent to `let t = T::unpack(std::mem::zeroed());`.
     ///
-    /// # Returns
+    /// It is not possible to detect if a `PublicMutable` has ever been initialized or not other than by testing for the
+    /// zero sentinel value. For a more robust solution, store an `Option<T>` in the `PublicMutable`.
     ///
-    /// * `T` - The current value stored in this PublicMutable.
+    /// ## Examples
     ///
+    /// ```noir
+    /// #[external("utility")]
+    /// fn get_total_supply() -> u128 {
+    ///     self.storage.total_supply.read()
+    /// }
+    /// ```
     pub unconstrained fn read(self) -> T
     where
         T: Packable,