Public State

On this page we will look at how to manage public state in Aztec contracts. We will look at how to declare public state, how to read and write to it, and how to use it in your contracts.

For a higher level overview of the state model in Aztec, see the state model concepts page.

PublicMutable

The PublicMutable (formerly known as PublicState) struct is generic over the variable type T. The type must implement Serialize and Deserialize traits, as specified here:

serialize

#[derive_via(derive_serialize)]
pub trait Serialize<let N: u32> {
    fn serialize(self) -> [Field; N];
}

^{_{Source code: noir-projects/noir-protocol-circuits/crates/types/src/traits.nr#L157-L162}}

deserialize

#[derive_via(derive_deserialize)]
pub trait Deserialize<let N: u32> {
    fn deserialize(fields: [Field; N]) -> Self;
}

^{_{Source code: noir-projects/noir-protocol-circuits/crates/types/src/traits.nr#L175-L180}}

The struct contains a storage_slot which, similar to Ethereum, is used to figure out where in storage the variable is located. Notice that while we don't have the exact same state model as EVM chains it will look similar from the contract developers point of view.

You can find the details of PublicMutable in the implementation here (GitHub link).

For a version of PublicMutable that can also be read in private, head to SharedMutable.

info

An example using a larger struct can be found in the lending example (GitHub link)'s use of an Asset (GitHub link).

new

When declaring the storage for T as a persistent public storage variable, we use the PublicMutable::new() constructor. As seen below, this takes the storage_slot and the serialization_methods as arguments along with the Context, which in this case is used to share interface with other structures. You can view the implementation here (GitHub link).

Single value example

Say that we wish to add admin public state variable into our storage struct. In the struct we can define it as:

storage-leader-declaration

leader: PublicMutable<Leader, Context>,

^{_{Source code: noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr#L35-L37}}

Mapping example

Say we want to have a group of minters that are able to mint assets in our contract, and we want them in public storage, because access control in private is quite cumbersome. In the Storage struct we can add it as follows:

storage-minters-declaration

minters: Map<AztecAddress, PublicMutable<bool, Context>, Context>,

^{_{Source code: noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr#L52-L54}}

read

On the PublicMutable structs we have a read method to read the value at the location in storage.

Reading from our admin example

For our admin example from earlier, this could be used as follows to check that the stored value matches the msg_sender().

read_admin

assert(storage.admin.read().eq(context.msg_sender()), "caller is not admin");

^{_{Source code: noir-projects/noir-contracts/contracts/token_contract/src/main.nr#L188-L190}}

Reading from our minters example

As we saw in the Map earlier, a very similar operation can be done to perform a lookup in a map.

read_minter

assert(storage.minters.at(context.msg_sender()).read(), "caller is not minter");

^{_{Source code: noir-projects/noir-contracts/contracts/token_contract/src/main.nr#L200-L202}}

write

We have a write method on the PublicMutable struct that takes the value to write as an input and saves this in storage. It uses the serialization method to serialize the value which inserts (possibly multiple) values into storage.

Writing to our admin example

write_admin

storage.admin.write(new_admin);

^{_{Source code: noir-projects/noir-contracts/contracts/token_contract/src/main.nr#L111-L113}}

Writing to our minters example

write_minter

storage.minters.at(minter).write(approve);

^{_{Source code: noir-projects/noir-contracts/contracts/token_contract/src/main.nr#L191-L193}}

---

PublicImmutable

PublicImmutable is a type that is initialized from public once, typically during a contract deployment, but which can later be read from public, private and unconstrained execution contexts. This state variable is useful for stuff that you would usually have in immutable values in Solidity, e.g. this can be the name of a token or its number of decimals.

Just like the PublicMutable it is generic over the variable type T. The type MUST implement the Serialize and Deserialize traits.

storage-public-immutable-declaration

public_immutable: PublicImmutable<Leader, Context>,

^{_{Source code: noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr#L49-L51}}

You can find the details of PublicImmutable in the implementation here (GitHub link).

new

Is done exactly like the PublicMutable struct, but with the PublicImmutable struct.

storage-public-immutable-declaration

public_immutable: PublicImmutable<Leader, Context>,

^{_{Source code: noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr#L49-L51}}

initialize

This function sets the immutable value. It can only be called once.

initialize_decimals

storage.decimals.initialize(decimals);

^{_{Source code: noir-projects/noir-contracts/contracts/token_contract/src/main.nr#L101-L103}}

warning

A PublicImmutable's storage must only be set once via initialize. Attempting to override this by manually accessing the underlying storage slots breaks all properties of the data structure, rendering it useless.

initialize_public_immutable

#[public]
fn initialize_public_immutable(points: u8) {
    let mut new_leader = Leader { account: context.msg_sender(), points };
    storage.public_immutable.initialize(new_leader);

^{_{Source code: noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr#L92-L97}}

read

Returns the stored immutable value. This function is available in public, private and unconstrained contexts.

read_public_immutable

unconstrained fn get_public_immutable() -> Leader {
    storage.public_immutable.read()

^{_{Source code: noir-projects/noir-contracts/contracts/docs_example_contract/src/main.nr#L153-L156}}