> Aztec.nr API reference, v6.0.0 (mainnet and testnet). Index: https://docs.aztec.network/aztec-nr-api/mainnet/llms.txt # Struct PublicMutable Module: `noir_aztec::state_vars` ```rust pub struct PublicMutable { /* private fields */ } ``` Mutable public values. This is one of the most basic public state variables. It is equivalent to a non-`immutable` non-`constant` Solidity state variable. It represents a public value of type `T` that can be written to repeatedly over the lifetime of the contract, allowing the last value that was written to be read. ## Access Patterns A value stored in a `PublicMutable` can be read and written from public contract functions. It is not possible to read or write a `PublicMutable` from private contract functions. A common pattern is to have these functions enqueue a public self calls in which the required operation is performed. For an immutable variant which can be read from private functions, see [`PublicImmutable`](/aztec-nr-api/mainnet/noir_aztec/state_vars/struct.PublicImmutable.md). For a mutable (with restrictions) variant which can be read from private functions see [`DelayedPublicMutable`](/aztec-nr-api/mainnet/noir_aztec/state_vars/struct.DelayedPublicMutable.md). ## Privacy `PublicMutable` provides zero privacy. All write and read operations are public: the entire network can see these accesses and the data involved. ## Use Cases 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. Note that contracts having public values does not necessarily mean 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`](/aztec-nr-api/mainnet/noir_aztec/macros/functions/fn.only_self.md) attribute is very useful when implementing this. ## Examples Declaring a `PublicMutable` in the contract's [`#[storage]`](/aztec-nr-api/mainnet/noir_aztec/macros/storage/fn.storage.md) struct requires specifying the type `T` that is stored in the variable: ```rust #[storage] struct Storage { total_supply: PublicMutable, public_balances: Map, C>, vote_tallies: Map, C>, } ``` ## Requirements The type `T` stored in the `PublicMutable` must implement the [`Packable`](/aztec-nr-api/mainnet/protocol_types/traits/trait.Packable.md) 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`](/aztec-nr-api/mainnet/noir_aztec/state_vars/struct.PublicImmutable.md) and [`DelayedPublicMutable`](/aztec-nr-api/mainnet/noir_aztec/state_vars/struct.DelayedPublicMutable.md) are examples of public state variables that *can* be read privately by restricting mutation. ## Implementations ```rust impl PublicMutable ``` ```rust pub fn read(self) -> T where T: Packable ``` Returns the current value. If [`write`](/aztec-nr-api/mainnet/noir_aztec/state_vars/struct.PublicMutable.md#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());`. 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` in the `PublicMutable`. #### Examples A public getter that returns the current value: ```rust #[external("public")] fn get_total_supply() -> u128 { self.storage.total_supply.read() } ``` An [`only_self`](/aztec-nr-api/mainnet/noir_aztec/macros/functions/fn.only_self.md) helper that asserts a condition a private function requires: ```rust #[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. ```rust pub fn write(self, value: T) where T: Packable ``` Stores a new value. The old value is overridden and cannot be recovered. The new value can be immediately retrieved by [`read`](/aztec-nr-api/mainnet/noir_aztec/state_vars/struct.PublicMutable.md#read). #### Examples A public setter that updates the current value: ```rust #[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); } ``` An [`only_self`](/aztec-nr-api/mainnet/noir_aztec/macros/functions/fn.only_self.md) helper that updates public state triggered by a private function: ```rust #[external("private")] fn vote_for_proposal(election_id: ElectionId, votes: u128) { // validate the sender can cast this many votes - this remains private self.enqueue_self._tally_vote(election_id, votes); } #[external("public")] #[only_self] fn _tally_vote(election_id: ElectionId, votes: u128) { let current = self.storage.vote_tallies.at(election_id).read(); self.storage.vote_tallies.at(election_id).write(current + votes); } ``` #### Cost The `SSTORE` AVM opcode is invoked a number of times equal to `T`'s packed length. ```rust impl PublicMutable ``` ```rust pub unconstrained fn read(self) -> T where T: Packable ``` Returns the value at the anchor block. If [`write`](/aztec-nr-api/mainnet/noir_aztec/state_vars/struct.PublicMutable.md#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());`. 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` in the `PublicMutable`. #### Examples ```rust #[external("utility")] fn get_total_supply() -> u128 { self.storage.total_supply.read() } ``` ## Trait implementations ```rust impl StateVariable for PublicMutable where T: Packable ``` ```rust pub fn new(context: Context, storage_slot: Field) -> Self ``` ```rust pub fn get_storage_slot(self) -> Field ```