Token Transfers & Balances
Relevant source files
The following files were used as context for generating this wiki page:
The Token Transfers & Balances system in the Aztec Standards library provides a standardized implementation of fungible assets (AIP-20) that leverage Aztec's unique privacy features. Unlike traditional account-based models, this system manages two distinct types of balances: public balances, which are transparent on-chain, and private balances, which utilize Note-based encryption to maintain confidentiality.
The core functionality encompasses minting, burning, and transferring assets between these different privacy domains. It also introduces advanced primitives such as "partial notes" (commitments) and authwitness-guaranteed interactions, allowing for complex asynchronous or delegated transfer logic while preserving user privacy.
Sources: README.md:20-24, src/ts/test/token.test.ts:133-145
Dual-Domain Balance Architecture
The system operates across two distinct storage models: the Public Domain (transparent) and the Private Domain (confidential).
Public and Private Balances
- Public Balances: Managed similarly to ERC-20 tokens where balances are stored in a public mapping and are visible to all network participants.
- Private Balances: Managed using a UTXO-like model where funds are represented by encrypted "notes." Only the owner (or authorized parties) can view or spend these balances.
The following table summarizes the balance tracking methods available in the standard:
| Method | Domain | Description |
|---|---|---|
balance_of_public(address) | Public | Returns the transparent balance of an account. |
balance_of_private(address) | Private | Returns the sum of available note values for an account (requires local decryption). |
total_supply() | Global | Returns the total sum of tokens across both domains. |
| Sources: src/ts/test/token.test.ts:141-147, src/ts/test/utils.ts:133-146 |
Balance Flow Logic
The system allows tokens to flow seamlessly between the Public and Private domains through specific transfer functions.
The diagram above shows the possible transitions of funds between public storage, private note storage, and intermediate commitment states.
Sources: benchmarks/token_contract.benchmark.ts:89-123, src/ts/test/token.test.ts:153-162
Transfer Mechanisms
The system provides various methods to move assets depending on the desired privacy level and authorization requirements.
Standard Transfers
- Public to Public: Standard transparent transfer.
- Private to Private: Fully confidential transfer; no public events are emitted, and balances are updated via note nullification and creation.
- Shielding (Public to Private): Moves transparent funds into the private domain.
- Unshielding (Private to Public): Moves confidential funds into the public domain, making them transparent.
Sources: src/ts/test/token.test.ts:169-231, benchmarks/token_contract.benchmark.ts:98-106
Commitment-Based Transfers (Partial Notes)
Partial notes allow a sender to prepare a transfer that the recipient can later finalize. This is useful for asynchronous interactions or when the sender wants to lock funds to a specific commitment without immediately creating a full note.
initialize_transfer_commitment: Generates a partial note for a recipient.transfer_public_to_commitment: Funds a previously initialized commitment from a public balance.transfer_private_to_commitment: Funds a commitment using private notes.
Sources: src/ts/test/token.test.ts:153-162, src/ts/test/utils.ts:327-345
Authorization with AuthWitness
Transfers can be authorized by a user to be executed by a third party (caller) using an AuthWitness. This is critical for interactions with other contracts, such as vaults or escrows.
This sequence demonstrates how a third party can execute a transfer on behalf of a user without the user being the immediate transaction sender.
Sources: src/ts/test/token.test.ts:178-197, src/ts/test/utils.ts:285-310
Vault and Escrow Interactions
Token balances and transfers are the foundation for higher-level standards like Tokenized Vaults and Escrows.
Tokenized Vaults (AIP-4626)
The Vault contract manages balances by issuing "shares" in exchange for "assets." It supports multiple transfer combinations:
- deposit_public_to_private: Deposit transparent assets, receive confidential shares.
- withdraw_private_to_public_exact: Burn confidential shares, receive transparent assets.
Sources: src/ts/test/tokenized_vault.test.ts:145-210, README.md:27-33
Escrow Withdrawals
The Escrow standard allows a logic contract to spend private balances held by an escrow address.
withdraw(token, amount, recipient): Moves private tokens from the escrow's private balance to a recipient's private balance.- This operation requires the Escrow contract to possess its own encryption and nullification keys.
Sources: src/escrow_contract/README.md:17-30, src/ts/test/escrow.test.ts:342-355
Security and Integrity Constants
The system uses specific magic values and constants to ensure cross-contract compatibility and log integrity.
| Constant | Value | Description |
|---|---|---|
PRIVATE_ADDRESS | 0x1ea7e0...64n | A sentinel address (sha224 of 'PRIVATE_ADDRESS') used in public events to signify a balance moved to/from the private domain. |
MAX_U128_VALUE | 2**128 - 1 | The maximum capacity for a standard token note value. |
MESSAGE_CIPHERTEXT_LEN | 17 | The length in fields of a private log used to transmit partial note data. |
| Sources: src/ts/test/utils.ts:430-435, src/ts/test/utils.ts:114, src/ts/test/utils.ts:468 |
Token Transfers & Balances form the core of the Aztec Standards ecosystem, providing the necessary primitives to maintain privacy-preserving state transitions. By supporting dual-domain balances and complex authorization patterns, the system enables developers to build privacy-first DeFi applications such as yield-bearing vaults and sophisticated escrow logic while ensuring auditability through public total supply tracking.