Escrow Contract Implementation
Relevant source files
The following files were used as context for generating this wiki page:
The Escrow Contract is a minimal, private-by-design component of the Aztec Standards library. Its primary purpose is to hold private balances of tokens (AIP-20) and NFTs (AIP-721) securely while delegating the logic for fund release, participant discovery, and key management to external "Logic" contracts. This separation ensures that while the Escrow handles the sensitive task of managing private states and nullifiers, the business rules governing those assets remain flexible and customizable.
The implementation relies on a "Logic Library" to facilitate the interaction between Logic contracts and Escrow instances. Because private balances require specific encryption and nullification keys to be viewed or spent, the system includes standardized mechanisms for deriving public keys from secrets and sharing these details privately between authorized participants.
Sources: src/escrow_contract/README.md:3-9, README.md:55-60
Architecture and Components
The architecture consists of three primary layers: the standardized Escrow contract itself, the Logic Library providing helper methods, and the external Logic contract that implements specific use cases like vesting or clawbacks.
Component Overview
| Component | Role | Description |
|---|---|---|
| Escrow Contract | Asset Custodian | A minimal private contract that holds private token/NFT balances. It has no storage and is identified by a salt containing the owner's address. |
| Logic Contract | Policy Enforcer | An external contract (e.g., Vesting, DAO) that "owns" the escrow and determines when withdrawals are permitted. |
| Logic Library | Standardization | A set of Noir library methods used by Logic contracts to manage keys, derive addresses, and execute withdrawals. |
Sources: src/escrow_contract/README.md:11-20, src/escrow_contract/README.md:39-47
Relationship Diagram
The following diagram illustrates the relationship between the Logic contract, the Escrow contract, and the underlying assets.
Key Management and Address Derivation
Escrow contracts are unique in that they must be "setup with keys" to handle private balances. The address of an Escrow is deterministic, derived from the contract class ID and a salt. In this implementation, the salt is typically the AztecAddress of the Logic contract, ensuring an immutable 1:1 or N:1 relationship between Logic and Escrows.
Key Derivation Flow
The Logic Library provides methods to derive the necessary keys to interact with private state.
Key Data Structures
The system uses MasterSecretKeys and PublicKeys to manage privacy. These keys include:
- Nullifier Hiding Key (nsk_m): Used to spend private notes.
- Incoming Viewing Key (ivsk_m): Used to detect and decrypt incoming notes.
- Outgoing Viewing Key (ovsk_m): Used to track outgoing transactions.
- Tagging Key (tsk_m): Used for note discovery.
Sources: src/ts/test/escrow.test.ts:102-114, src/ts/test/utils.ts:391-400
Core Functions and Methods
Escrow Contract Methods
The Escrow contract exposes only two private functions, both restricted to be called by the corresponding Logic contract.
| Function | Parameters | Description |
|---|---|---|
withdraw | token, amount, recipient | Transfers private token balance to the recipient's private balance. |
withdraw_nft | nft, token_id, recipient | Transfers a specific private NFT to the recipient's private balance. |
Sources: src/escrow_contract/README.md:23-37, benchmarks/escrow_contract.benchmark.ts:101-118
Logic Library Methods
These helper functions are used within Logic contracts to standardize escrow management.
_share_escrow: Emits a private log containing the escrow address and master secret keys. This allows authorized participants (like a recipient) to find and utilize the escrow contract._withdraw: Standardized wrapper to trigger thewithdrawfunction on the Escrow contract._withdraw_nft: Standardized wrapper for NFT withdrawals.
Sources: src/escrow_contract/README.md:73-108, src/ts/test/escrow.test.ts:211-225
Deployment and Initialization
The Escrow contract does not require public deployment or traditional initialization storage. Instead, it is identified by its contract instance salt.
Deployment Workflow
- Class Registration: The Escrow contract class ID must be known (derived from the artifact).
- Key Generation: The Logic contract or deployer generates a secret key.
- Address Prediction: The Escrow address is predicted using the Logic contract address as the salt and the derived public keys.
- Registration: For testing and PXE interaction, the contract is registered with the derived secret key to allow the PXE to decrypt notes belonging to the escrow.
Technical Specifications
The Escrow contract implementation is written in Noir and integrates with the Aztec network protocol.
Dependencies
The contract depends on the following internal and external libraries:
aztec-nr/aztec: Core Aztec smart contract framework.token_contract: For AIP-20 token standard compliance.nft_contract: For AIP-721 NFT standard compliance.
Sources: src/escrow_contract/Nargo.toml:8-12
Security Considerations
The Logic Library provides the tools for secure implementation, but the Logic contract itself must ensure that:
- Authorization: Only valid logic (e.g., meeting vesting criteria) triggers a withdrawal.
- Privacy: Key sharing (
_share_escrow) must only be performed with authorized recipients to prevent balance leaks or unauthorized nullification.
Sources: src/escrow_contract/README.md:57-65
Summary
The Escrow Contract Implementation provides a robust, standardized foundation for building privacy-preserving financial applications on Aztec. By separating the asset custody (Escrow) from the business logic (Logic Contract) and providing a standardized Logic Library for key and address management, it allows developers to focus on application-specific rules without re-implementing complex private state logic.