State visibility and data flow
Aztec splits state into private notes (owned by accounts or contracts) and public storage. Designing a good app means deciding which data lives where and how it flows between the two worlds.
Private state
Represent balances and positions as notes. You prove ownership and validity privately and nullify notes on spend to prevent double‑use. Aztec.nr provides three helpers that hide the note mechanics behind a clean API:
PrivateMutable: a single updatable note, “replace” emits a nullifier for the old value and inserts a new one. See this file.PrivateImmutable: a single, never‑changing note initialized once. See this file.PrivateSet: a collection of notes where the “value” is an accumulation you define (sum, min, etc.). See this file
Read user secrets via PXE oracles during private execution, never try to pull secrets from public code.
Public state
Publish only what must be shared or coordinated across users (pool totals, price oracles, settlement queues). Use PublicMutable for regular storage and PublicImmutable for constructor‑like values:
- PublicMutable: generic public storage; read/write helpers. See this page for reference.
- PublicImmutable: initialized once in public, readable in public/private/utility. See this page for reference.
When you must read public values in private, use DelayedPublicMutable so the PXE can prove against a recent, guaranteed‑not‑yet‑changed value. This introduces a bounded “include by” timestamp but avoids leaking which exact public value you read.
See Delayed Public Mutable and check the design notes.
Data flow bridges
From private to public: validate secrets and compute effects privately, then enqueue a minimal public function that applies the update using commitments/nullifiers from the proof.
From public to private: read public data in private via archive‑tree membership proofs; avoid synchronous public reads from private functions.
Maps exist in both worlds and help structure storage. Keys are fields; values can be complex types. See the Map docs and token examples in aztec‑packages for read, write, and at usage.
Privacy considerations
Crossing private→public leaks information (arguments, events, messages). Crossing public→private can leak timing if you assert current values in public. Prefer DelayedPublicMutable for configs you must read in private and budget for include_by_timestamp. See the privacy considerations doc for a catalogue of leaky patterns and how to mitigate them.