Escrow Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Escrow Architecture is a modular system designed for the Aztec Network to securely manage private token and NFT balances. It separates the concerns of fund custody from the business logic governing fund release. The system consists of two primary components: a minimal, private Escrow Contract that holds assets and a Logic Contract (supported by a Logic Library) that defines the rules for distribution and handles key management.
This architecture is specifically designed to leverage Aztec's privacy features, ensuring that transfers into and out of the escrow remain confidential. The Escrow Contract itself does not require public deployment and relies on specific encryption and nullification keys to interact with private balances.
Sources: src/escrow_contract/README.md:3-9, README.md:46-51
Core Components
The system is split into three functional layers to ensure flexibility and security.
1. Escrow Contract
The Escrow Contract is a minimal private contract. Its primary role is to act as a vault for private balances of AIP-20 tokens and AIP-721 NFTs. It is characterized by:
- Privacy: It does not need to be publicly deployed and operates entirely within private functions.
- Immutable Ownership: The owner (the Logic Contract) is defined via an
AztecAddressencoded into the contract instance salt. - Statelessness: It does not maintain internal storage and lacks an initialization function.
Sources: src/escrow_contract/README.md:13-20, src/ts/test/escrow.test.ts:161-163
2. Logic Library
A set of contract library methods that standardizes the interaction between Logic Contracts and Escrows. It provides helpers for deriving addresses, sharing keys securely, and executing withdrawals.
Sources: src/escrow_contract/README.md:50-53, README.md:49-51
3. Logic Contract
The Logic Contract implements the specific policy for an application (e.g., linear vesting, clawbacks). It "owns" one or more Escrow contracts and manages participant roles, conditions (timestamps, amounts), and key distribution.
Sources: src/escrow_contract/README.md:41-48, benchmarks/logic_contract.benchmark.ts:46-50
Key Management and Discovery
Because the Escrow Contract holds private balances, authorized callers need access to the escrow's master secret keys (nullifier, viewing, and tagging) to read or spend those balances.
The following diagram illustrates the relationship between the Logic Contract, the Escrow, and the participants.
The Logic Contract manages how these details are shared with participants using private logs.
Sources: src/escrow_contract/README.md:5-7, src/ts/test/escrow.test.ts:221-230, src/escrow_contract/README.md:44-48
Technical Specifications
Data Structures
The system utilizes specific structures for key management within the Logic Library.
| Structure | Description | Key Fields |
|---|---|---|
MasterSecretKeys | A set of secret keys required to interact with private state. | nsk_m, ivsk_m, ovsk_m, tsk_m |
PublicKeys | Derived from secret keys, used for address derivation and encryption. | npk_m, ivpk_m, ovpk_m, tpk_m |
EscrowDetailsLogContent | Data emitted in private logs to allow participants to discover the escrow. | escrow_address, master_secret_keys |
Sources: src/ts/test/escrow.test.ts:74-79, src/escrow_contract/README.md:118-121, src/ts/test/utils.ts:316-320
Core API Functions
Escrow Contract Functions
These functions are private and can typically only be invoked by the authorized Logic Contract.
| Function | Purpose | Parameters |
|---|---|---|
withdraw | Transfers private token balance to a recipient. | token, amount, recipient |
withdraw_nft | Transfers a private NFT to a recipient. | nft, token_id, recipient |
Sources: src/escrow_contract/README.md:25-40, benchmarks/escrow_contract.benchmark.ts:100-112
Logic Library Helpers
The library facilitates the implementation of the Logic Contract.
| Helper | Purpose | Source File |
|---|---|---|
_get_escrow | Computes the escrow address based on keys and class ID. | src/escrow_contract/README.md:56-65 |
_share_escrow | Emits a private log to share keys with a participant. | src/escrow_contract/README.md:68-78 |
_secret_keys_to_public_keys | Derives public keys from master secrets. | src/escrow_contract/README.md:118-123 |
Sequence of Operations
The typical lifecycle of an escrow involves deployment, key sharing, and eventual withdrawal.
The address derivation ensures that the Escrow address is deterministically linked to the Logic Contract through the salt and the provided public keys.
Sources: src/ts/test/escrow.test.ts:98-115, src/ts/test/utils.ts:400-410, src/escrow_contract/README.md:68-78
Implementation Example: Deployment Logic
In the test suite and benchmarks, the escrow is deployed using the Logic Contract address as a salt to ensure a unique, deterministic binding between the controller and the vault.
// Example from test suite illustrating the binding
const escrowClassId = (await getContractClassFromArtifact(EscrowContractArtifact)).id;
const logic = (await deployLogic(wallet, alice, escrowClassId)) as TestLogicContract;
// Use the logic contract address as the salt for the escrow contract
const escrowSalt = new Fr(logic.address.toBigInt());
const escrow = (await deployEscrowWithPublicKeysAndSalt(
escrowKeys.publicKeys,
wallet,
alice,
escrowSalt,
)) as EscrowContract;
Sources: src/ts/test/escrow.test.ts:98-115, benchmarks/logic_contract.benchmark.ts:57-65
Conclusion
The Escrow Architecture provides a standardized, privacy-preserving method for asset custody on Aztec. By decoupling the logic from the escrow itself, developers can create complex financial instruments—such as vesting schedules or conditional payments—without compromising the confidentiality of the assets or the parties involved. The system relies heavily on the secure sharing of master secret keys through private logs, allowing decentralized participants to interact with private contract state.
Sources: src/escrow_contract/README.md:3-11, README.md:46-53