Aztec Privacy Model
Relevant source files
The following files were used as context for generating this wiki page:
The Aztec Privacy Model is a technical framework within the Aztec Network that enables confidential asset management through the use of private and public state transitions. It provides a robust foundation for building privacy-preserving applications, such as the Token Contract, NFT Contract, and Escrow Standard, by allowing developers to manage sensitive data via private balances and encrypted logs while maintaining compatibility with public network operations.
Sources: README.md:5-10, src/token_contract/README.md:1-5
Core Architectural Concepts
The Aztec privacy model is built around the dual existence of public and private states. Contracts in the Aztec Standards repository utilize specific primitives to manage these states, ensuring that transfers and ownership can remain hidden from the public ledger or be revealed when necessary.
Private and Public Balances
Contracts like the Token and NFT implementations maintain distinct storage for private and public ownership. Public state is visible and accessible via the global network state, while private state is managed through "notes" that are encrypted and only accessible by holders of specific secret keys.
Sources: src/token_contract/README.md:15-20, src/nft_contract/README.md:10-15
Sentinel Addresses and Magic Values
The system uses specific magic values to represent the private realm within public event logs. For instance, the PRIVATE_ADDRESS is a sentinel value used in Transfer events to indicate that a balance change has moved into or out of the private side.
Sources: src/ts/test/utils.ts:634-637
| Component | Description |
|---|---|
| Private State | Managed through encrypted notes; content is hidden from the public blockchain. |
| Public State | Transparent state similar to traditional blockchains (e.g., Ethereum). |
| Authwit | Authorization witnesses used to permit third-party callers to execute actions on behalf of a user. |
| Encrypted Logs | Private communication channel used to share note details with recipients. |
| Sources: src/ts/test/utils.ts:310-330, src/escrow_contract/README.md:5-15 |
Key Management and Confidentiality
Privacy in Aztec is enforced through a hierarchical key system. These keys are required to discover, read, and spend private assets.
Key Types and Derivation
The system utilizes master secret keys which are derived from a seed. These keys include:
- Nullifier Secret Key (nsk_m): Used to spend private notes.
- Incoming Viewing Secret Key (ivsk_m): Used to decrypt incoming logs and discover new notes.
- Outgoing Viewing Secret Key (ovsk_m): Used to track sent transactions.
- Tagging Secret Key (tsk_m): Used for transaction tagging.
Sources: src/ts/test/escrow.test.ts:75-90, src/escrow_contract/README.md:120-130
Note Discovery Flow
This diagram illustrates how a user discovers a private note sent to them using their secret keys.
The discovery process involves the recipient scanning the network for logs and using their ivsk_m to derive a shared secret through ECDH, subsequently decrypting the log via AES-128-CBC.
Sources: src/ts/test/utils.ts:760-800, src/escrow_contract/README.md:10-15
Private Asset Transfers
Aztec Standards support various transfer modes that bridge the gap between private and public states.
Transfer Variations
- Private to Private: Completely confidential; no public events are emitted other than nullifiers.
- Private to Public: A "shielding" exit where tokens move from a private note to a public balance.
- Public to Private: A "shielding" entrance where public tokens are converted into private notes.
- Commitment-based Transfers: Uses partial notes and commitments to allow asynchronous or multi-step privacy entrances/exits.
Sources: src/nft_contract/README.md:35-80, src/ts/test/token.test.ts:130-150
Commitment Initialization Flow
Commitments act as a "privacy entrance." A user can initialize a transfer commitment, which returns a partial note utilized for a future transfer.
Sources: src/nft_contract/README.md:100-110
This flow shows the transition of assets regardless of the starting state into a private commitment.
Sources: src/ts/test/token.test.ts:110-120, src/nft_contract/README.md:40-50
The Escrow Privacy Pattern
The Escrow Standard demonstrates a sophisticated application of the Aztec Privacy Model. It separates the Escrow Contract (which holds assets) from the Logic Contract (which defines the release policy).
Components of the Escrow System
- Escrow Contract: A minimal, private contract that must be set up with keys to hold private balances. It only allows
withdrawandwithdraw_nftcalls from the owner. - Logic Contract: Manages the sharing of escrow keys and details to participants through private logs.
- Logic Library: Facilitates the derivation of keys and the secure sharing of escrow addresses.
Sources: src/escrow_contract/README.md:5-30
Interaction Architecture
The Escrow contract is identified by an address derived from an AztecAddress encoded into the contract instance salt, making it immutable.
The diagram shows how the Logic contract acts as an intermediary, using the Logic Library to manage the underlying private Escrow contract.
Sources: src/escrow_contract/README.md:35-60, src/ts/test/escrow.test.ts:120-140
Technical Implementation Details
AES-128-CBC Decryption
Decryption of raw private logs follows a specific algorithm where the shared secret is computed using the addressSecret and an ephemeral public key (ephPk) extracted from the ciphertext.
Sources: src/ts/test/utils.ts:763-780
Field Encoding
Ciphertext encoding in Aztec typically stores 31 bytes per field (skipping the first byte of a 32-byte buffer) to ensure compatibility with field characteristics, while plaintext uses all 32 bytes.
Sources: src/ts/test/utils.ts:705-725
| Function | Purpose | Location |
|---|---|---|
_get_escrow | Returns the escrow address for given keys and class ID. | src/escrow_contract/src/main.nr |
_share_escrow | Emits a private log with escrow details for participants. | src/escrow_contract/src/main.nr |
decryptRawPrivateLog | Technical utility to recover plaintext from encrypted network logs. | src/ts/test/utils.ts |
deriveKeys | Derives the full suite of Aztec secret/public keys from a scalar. | @aztec/stdlib/keys |
| Sources: src/escrow_contract/README.md:85-110, src/ts/test/utils.ts:755-760 |
Summary
The Aztec Privacy Model, as implemented in the Aztec Standards, provides a comprehensive methodology for managing confidential assets. By leveraging dual-state architectures, hierarchical key management, and standardized escrow patterns, it allows for sophisticated financial interactions that remain private by default. The reliance on encrypted logs and authorization witnesses (Authwit) ensures that users can delegate actions without compromising the fundamental privacy of their underlying asset notes.
Sources: README.md:1-5, src/escrow_contract/README.md:5-10