Escrow & Logic Benchmarks
Relevant source files
The following files were used as context for generating this wiki page:
The Escrow & Logic Benchmarks provide a performance assessment framework for the standardized Escrow contract and its accompanying Logic contract library. These benchmarks evaluate the execution costs of private operations involving private token transfers (AIP-20) and non-fungible tokens (AIP-721) held within a secure, key-managed escrow environment.
The system is designed to delegate release policies, participant discovery, and key distribution to a "Logic" contract while maintaining a minimal, reusable "Escrow" contract that safely holds private balances. Benchmarks measure critical paths such as key derivation, address prediction, and asset withdrawal through authorized logic intermediaries.
Sources: src/escrow_contract/README.md:1-12, README.md:46-52
Architecture Overview
The architecture follows a separation of concerns between the storage of private assets (Escrow) and the business logic governing those assets (Logic). The Escrow contract is a private-only contract that requires specific encryption and nullification keys to manage private balances.
Component Interaction
- Escrow Contract: A minimal contract designed to hold private balances. It has no public state and requires initialization with master public keys derived from a secret key.
- Logic Contract: A contract that implements specific business rules (e.g., vesting, clawbacks). It "owns" the escrow and uses the Logic library to interact with it.
- Logic Library: A set of standardized helper functions used by Logic contracts to find, share, and withdraw from Escrows.
This diagram shows the relationship between the Logic contract, the Logic library, the Escrow contract, and the underlying assets.
Sources: src/escrow_contract/README.md:1-25, src/ts/test/escrow.test.ts:98-115
Benchmark Execution Flows
Benchmarks are implemented as TypeScript classes extending a base Benchmark class, simulating realistic multi-party interactions in a test environment using TestWallet and AztecNode.
Logic Contract Benchmarking
The LogicContractBenchmark focuses on the administrative and cryptographic overhead of managing escrows. It evaluates the cost of deriving public keys from secrets and predicting escrow addresses.
This sequence shows the administrative functions evaluated during logic benchmarking.
Sources: benchmarks/logic_contract.benchmark.ts:68-87, src/ts/test/escrow.test.ts:167-190
Escrow Contract Benchmarking
The EscrowContractBenchmark measures the cost of actual asset movements. It simulates a "Logic Mock" account calling the Escrow's withdrawal functions.
| Benchmark Name | Operation | Context |
|---|---|---|
| (partial) withdraw | escrow.withdraw() | Withdraws a portion of private tokens, involving change note creation. |
| withdraw | escrow.withdraw() | Full withdrawal of private token balance. |
| withdraw_nft | escrow.withdraw_nft() | Withdrawal of a specific NFT ID from escrow to recipient. |
Sources: benchmarks/escrow_contract.benchmark.ts:77-101, src/escrow_contract/README.md:27-52
Key Functions and Data Structures
Master Secret Keys
The system relies on a set of four master secret keys for private state management:
nsk_m: Master Nullifier Secret Keyivsk_m: Master Incoming Viewing Secret Keyovsk_m: Master Outgoing Viewing Secret Keytsk_m: Master Tagging Secret Key
Sources: src/ts/test/escrow.test.ts:70-75, benchmarks/logic_contract.benchmark.ts:25-30
Library API Benchmarked
The following library methods are central to the benchmark suite:
| Function | Type | Description |
|---|---|---|
_get_escrow | Private | Computes the escrow address using escrow_class_id and master_secret_keys. |
_share_escrow | Private | Emits an encrypted private log containing escrow details for a recipient. |
_withdraw | Private | Triggers a private transfer from the Escrow to a recipient for fungible tokens. |
_withdraw_nft | Private | Triggers a private transfer for a specific NFT ID. |
_secret_keys_to_public_keys | Unconstrained | Utility to derive the corresponding public keys required for contract deployment. |
Sources: src/escrow_contract/README.md:66-135, benchmarks/logic_contract.benchmark.ts:68-85
Technical Implementation Details
Escrow Address Derivation
The Escrow contract address is deterministic. It is derived using the contract's classId, a salt (often the Logic contract address), and the publicKeys. This allows a Logic contract to interact with an Escrow without it being publicly deployed.
Logic for predicting the Escrow address as used in benchmarks.
Sources: src/ts/test/escrow.test.ts:98-105, src/ts/test/utils.ts:316-335
Benchmark Setup Configuration
Benchmarks utilize the setupTestSuite utility to initialize a local Aztec node and PXE. For performance accuracy, the proverEnabled flag is set to true, which ensures that proof generation time is included in the metrics.
Sources: src/ts/test/utils.ts:46-55, benchmarks/logic_contract.benchmark.ts:41-45
Conclusion
The Escrow & Logic Benchmarks validate that the standardized escrow pattern—separating asset security from business logic—can be executed efficiently within the Aztec private execution environment. By measuring key derivation, encrypted event sharing, and private asset withdrawals, the benchmarks ensure that developers can implement complex financial logic (like vesting or clawbacks) without incurring prohibitive gas or proof-generation costs.