Token Contract (AIP-20) Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Token Contract implements the AIP-20 Aztec Token Standard, which provides an ERC-20-like interface tailored for the Aztec Network's unique privacy features. It supports a hybrid state model, allowing assets to exist in both public and private balances. This dual nature enables developers to build applications that balance transparency with confidentiality, supporting features like private transfers, public minting, and cross-state movements.
In the broader context of the Aztec Standards project, the Token Contract serves as the foundational primitive for more complex financial instruments. It can be extended or configured to act as a Tokenized Vault (AIP-4626), allowing for yield-bearing shares and asset management within a privacy-preserving framework.
Sources: README.md:1-42, src/ts/test/token.test.ts:1-20
Architecture and Hybrid State Model
The AIP-20 standard distinguishes between two types of ownership: public balances (stored in public state) and private balances (stored using UTXO-like notes in the private state). This architecture allows for various interaction patterns between different levels of privacy.
Balance Types
- Public Balances: Managed similarly to standard EVM tokens. Visible to all network participants.
- Private Balances: Managed using
uint_noteandbalance_setdependencies. These balances are confidential and require specific cryptographic keys to view or spend.
Sources: src/token_contract/Nargo.toml:1-12, README.md:32-37
State Flow Diagram
The following diagram illustrates the flow of tokens between different state environments (Public, Private, and Commitments).
The diagram shows how tokens can move between public state, private state, and an intermediate "commitment" state used for initializing transfers to recipients.
Sources: src/ts/test/token.test.ts:98-154, benchmarks/token_contract.benchmark.ts:60-120
Key Functions and Operations
Deployment and Initialization
The contract supports multiple deployment strategies depending on the initial requirements of the token.
| Method | Description | Parameters |
|---|---|---|
constructor_with_minter | Sets an authorized minter and basic metadata. | name, symbol, decimals, minter, admin |
constructor_with_initial_supply | Deploys with a pre-minted supply to a specific address. | name, symbol, decimals, supply, recipient, admin |
constructor_with_asset | Configures the token as a vault for an underlying asset. | name, symbol, decimals, asset_address, initial_deposit, admin |
Sources: src/ts/test/token.test.ts:46-96, src/ts/test/utils.ts:184-211
Transfer Mechanisms
AIP-20 provides several transfer methods to handle different privacy scenarios.
- Public Transfers: Standard transfers where both sender and recipient are public.
- Private Transfers: Uses notes to move value between private addresses without leaking the amount or participants.
- Cross-State Transfers: Functions like
transfer_public_to_privateallow users to "shield" tokens, whiletransfer_private_to_public"unshields" them. - Commitment-Based Transfers: A two-step process where a "partial note" is created via
initialize_transfer_commitment. This allows the recipient to claim the tokens privately later.
// Example: Creating a transfer commitment
const commitment = await initialize_transfer_commitment(to, completer);
// Finalizing the transfer to that commitment
await token.methods.transfer_public_to_commitment(owner, commitment, amount, nonce).send();
Sources: src/ts/test/token.test.ts:98-154, src/ts/test/utils.ts:314-343
Security and Authorization
The contract utilizes "Authwitness" (Authorization Witnesses) to allow third parties to execute actions on behalf of a user without possessing their private keys.
Authorization Flow
This flow is used for both public and private transfers, ensuring that even if a caller (like Carl) triggers the transaction, only the authorized amount and action can be executed.
Sources: src/ts/test/token.test.ts:156-224, src/ts/test/utils.ts:286-312
AIP-4626: Tokenized Vault Standard
When initialized via constructor_with_asset(), the contract implements the Tokenized Vault Standard. It issues yield-bearing shares (the AIP-20 tokens) in exchange for an underlying compliant asset.
Vault Interactions
| Action | Source State | Result State | Logic |
|---|---|---|---|
deposit | Assets (Pub/Priv) | Shares (Pub/Priv) | Transfers assets to vault; mints shares to user. |
withdraw | Shares (Pub/Priv) | Assets (Pub/Priv) | Burns shares; transfers underlying assets to user. |
mint/issue | Assets (Pub/Priv) | Shares (Pub/Priv) | User specifies exact shares to receive. |
redeem | Shares (Pub/Priv) | Assets (Pub/Priv) | User specifies exact shares to burn. |
Sources: src/ts/test/tokenized_vault.test.ts:1-200, README.md:39-46
Inflation Attack Protection
The standard implements protection against "inflation attacks" where an attacker manipulates the share price by donating assets to a vault with low total supply. This is mitigated by requiring an initial_deposit during deployment, which creates a minimum number of "locked" shares.
Sources: src/ts/test/tokenized_vault.test.ts:600-720, src/ts/test/utils.ts:213-245
Conclusion
The AIP-20 Token Contract is a versatile framework for asset representation on Aztec. By supporting hybrid public/private states and robust authorization through Authwitness, it provides the necessary primitives for private DeFi. Its ability to transition into an AIP-4626 vault further extends its utility, enabling standardized, privacy-preserving yield-bearing products.