Escrow Logic Library

Relevant source files

The following files were used as context for generating this wiki page:

• src/escrow_contract/README.md
• benchmarks/logic_contract.benchmark.ts
• src/ts/test/escrow.test.ts
• src/ts/test/utils.ts
• src/escrow_contract/Nargo.toml
• README.md

The Escrow Logic Library is a set of standardized contract library methods designed to facilitate and secure the management of private Escrow contracts. In the Aztec Standards architecture, the Escrow contract itself is a minimal, private-only primitive that holds balances, while the "Logic Contract" (utilizing this library) implements the specific policies, role assignments, and key sharing mechanisms for different use cases.

The library ensures that crucial elements such as encryption keys, contract class IDs, and participant discovery are handled correctly. It acts as the bridge between high-level application logic (like vesting or clawbacks) and the low-level private state of an Escrow, ensuring that private balances can be spent only by authorized callers through standardized interfaces.

Sources: src/escrow_contract/README.md:1-12, README.md:52-58

Architecture and Integration

The system follows a separation of concerns between the storage of assets and the rules governing their release. A Logic Contract acts as the owner of one or more Escrow instances.

System Flow

The following diagram illustrates how a Logic Contract interacts with the Escrow primitive using the Logic Library:

Key Library Functions

The library provides five primary methods to handle the lifecycle of an escrow, ranging from key derivation to executing private transfers.

Address and Key Management

These functions allow a Logic contract to predict escrow addresses and derive the necessary public keys for setup without exposing master secrets.

Function	Purpose	Parameters
_get_escrow	Predicts address based on keys and class ID	escrow_class_id, master_secret_keys
_secret_keys_to_public_keys	Derives PublicKeys from MasterSecretKeys	master_secret_keys
_share_escrow	Emits a private log to share escrow details	account, escrow, master_secret_keys

Sources: src/escrow_contract/README.md:65-98

Withdrawal Operations

The library standardizes how funds are moved from the private escrow to a recipient. These calls typically target AIP-20 (Token) and AIP-721 (NFT) compliant contracts.

• _withdraw: Used for fungible tokens. It requires the escrow address, the recipient account, the token address, and the amount.
• _withdraw_nft: Used for non-fungible tokens. It requires the NFT contract address and the specific token_id.

Sources: src/escrow_contract/README.md:100-131

Key Sharing and Discovery

Because Escrow contracts are fully private and do not have public storage, participants must be notified of the escrow's existence and provided with the keys necessary to view or interact with it.

Implementation Details

The Logic Library is intended to be used within Noir contracts. It relies on the aztec-nr library for private context management.

Dependency Structure

As defined in the project configuration, the escrow logic depends on both the Token and NFT standards to facilitate withdrawals.

[dependencies]
aztec = { git = "...", tag = "v4.0.0-devnet.1-patch.0" }
escrow_contract = { path = "../../../" }
token = { path = "../../../../token_contract" }
nft = { path = "../../../../nft_contract" }

Sources: src/escrow_contract/src/test/test_logic_contract/Nargo.toml:8-12

Integration Example (TypeScript/Testing)

In testing environments, the logic contract is typically initialized with the escrow_class_id to ensure it targets the correct contract bytecode when deriving addresses.

// From escrow.test.ts
escrowClassId = (await getContractClassFromArtifact(EscrowContractArtifact)).id;
logic = (await deployLogic(wallet, alice, escrowClassId)) as TestLogicContract;

Sources: src/ts/test/escrow.test.ts:88-101, src/ts/test/utils.ts:316-324

Security Considerations

While the Logic Library provides the tools for secure escrow management, the following risks must be managed by the developer implementing the Logic Contract:

1. Private Balance Loss: Incorrect implementation of the Logic Contract could lead to funds being locked or maliciously withdrawn.
2. Key Exposure: The _share_escrow method sends master secret keys. If the logic contract shares these with the wrong AztecAddress, privacy is compromised.
3. Address Salt: The Escrow address is determined by the AztecAddress of the owner (the Logic Contract) encoded into the contract salt. This makes the relationship immutable.

Sources: src/escrow_contract/README.md:25-29, src/escrow_contract/README.md:58-63

Conclusion

The Escrow Logic Library provides a standardized framework for building complex financial applications on Aztec. By abstracting the complexities of private key sharing and address derivation into a library, it allows developers to focus on the business logic of their Logic Contracts while maintaining the strict privacy requirements of the Aztec Network.