Skip to main content

System Overview

Zenland uses a modular smart contract architecture:

Core Contracts

EscrowFactory

The main entry point for creating escrows. Responsibilities:
  • Deploy new escrow clones (EIP-1167)
  • Validate creation parameters
  • Collect protocol fees
  • Maintain isEscrow registry
Key Functions:

AgentRegistry

Manages agent registration, staking, and validation. Responsibilities:
  • Agent registration and deregistration
  • Stake management (add/withdraw)
  • MAV calculations
  • Two-stage agent validation
Key Functions:

FeeManager

Controls protocol fees and token whitelisting. Responsibilities:
  • Token whitelist management
  • Fee configuration per token
  • Fee quotation
Key Functions:

EscrowImplementation

The template contract cloned for each escrow. Responsibilities:
  • Hold escrowed funds
  • Enforce state machine
  • Process releases, refunds, splits
  • Handle dispute resolution

Design Patterns

Minimal Proxies (EIP-1167)

Each escrow is a lightweight clone:

CREATE2 Deterministic Addresses

Escrow addresses are predictable:
Benefits:
  • PDF can include the address before creation
  • User can verify they’re funding the right contract

Two-Stage Agent Validation

Agents are validated at:
  1. Creation: Is agent valid for this escrow?
  2. Invite: Is agent still valid when invited?
Why? Prevents agents from unstaking after being selected.

Checks-Effects-Interactions

All state changes follow the pattern:
  1. Checks: Validate inputs
  2. Effects: Update state
  3. Interactions: External calls last

Trust Boundaries

Factory-Escrow Trust

Agent-Escrow Trust


State Machine

Escrow states and transitions:

Security Considerations

Reentrancy Protection

All state-changing functions use ReentrancyGuard

Safe ERC20

OpenZeppelin’s SafeERC20 for all token operations

No Fee-On-Transfer Tokens

Whitelist excludes tokens with hidden fees

Immutable After Creation

Escrow rules cannot change after deployment

Smart Contract Details

View detailed contract specs →