Skip to content

Smart Contracts

Architecture Overview

ZeroLedger's smart contract system consists of five main contracts designed for modularity, security, and gas efficiency:

  • Vault: Core contract managing commitments and transactions
  • Forwarder: Meta-transaction and batching support (permissionless)
  • ProtocolManager: Protocol-level parameter management (fees, TVL limits)
  • Administrator: Manages administrative functions and protocol governance
  • InvoiceFactory: Creates one-time proxy contracts for private invoicing

All contracts can be found in the official contracts repo

Core Contracts

Vault Contract

The Vault contract is the heart of the ZeroLedger system, responsible for:

  • Commitment Storage: Managing cryptographic commitments using Poseidon hashes
  • Transaction Processing: Handling deposits, spends, and withdrawals
  • Proof Verification: Verifying PLONK zero-knowledge proofs on-chain
  • State Management: Maintaining the global state of all commitments

State Management

mapping(address => mapping(uint256 => address)) public commitments;

Each commitment is stored with:

  • Owner: The address that owns the commitment (stored openly)
  • Amount: The hidden amount committed with Poseidon hash
  • Metadata: Optional encrypted metadata for recipients

Security Features

  • Reentrancy Protection: Guards against reentrancy attacks
  • Access Control: Proper authorization for all functions
  • Input Validation: Comprehensive validation of all inputs
  • Emergency Pause: Ability to pause the contract in emergencies

Forwarder Contract

The Forwarder contract is permissionless and extends the OZ meta-transaction contract, enabling meta-transactions and advanced transaction patterns:

Meta-transaction Support

  • Gasless Transactions: Users can execute transactions without paying gas directly
  • Batch Operations: Multiple operations in a single transaction
  • Paymaster Integration: Third-party gas payment support
  • Signature Verification: EIP-712 and ERC1271 compliant signature verification via solady signature checker based on EIP-6492

Batch Operations

function executeBatch(
  ForwardRequest[] calldata requests,
  bytes[] calldata signatures
) external;

Supports batching of:

  • Multiple deposits
  • Multiple spends
  • Mixed operations
  • Cross-contract calls

Protocol Manager Contract

The Protocol Manager handles protocol-level parameters:

Fee Management

  • Fee Rates: Configurable fees for deposit, spend, and withdraw operations
  • Fee Collection: Collected fees can be withdrawn to dedicated treasury address
  • Fee Updates: Dynamic fee adjustments through governance

TVL Management

  • TVL Limits: Maximum allowed Total Value Locked in Vault contract per token
  • Risk Management: Prevents excessive capital concentration

Administrator Contract

The Administrator contract manages protocol governance and administrative functions. It extends OZ AccessManager:

Multisig Governance

All administrative functions are managed through multisig wallets, ensuring no single entity can make critical changes:

  • Admin Multisig: Controls protocol roles management
  • Maintainer Multisig: Controls protocol contract upgrades
  • Security Council Multisig: Manages emergency pauses and security functions
  • Treasury Manager Multisig: Controls fee parameters and treasury operations

Role Management

  • MAINTAINER: Contract upgrade authorization
  • SECURITY_COUNCIL: Emergency pause capabilities
  • TREASURY_MANAGER: Fee configuration and treasury operations
  • DEFAULT_ADMIN_ROLE: Top-level administrative access

InvoiceFactory Contract

The InvoiceFactory contract enables private payment invoicing through deterministic proxy deployment:

Contract Properties

  • Exclusive Deployment: Only InvoiceFactory can deploy invoice proxy contracts
  • Deterministic Addresses: Uses CREATE2 to compute invoice proxy addresses before deployment
  • One-Time Usage: Each invoice proxy can only be executed once
  • Predefined Commitments: Invoice proxies store commitment data at creation time
  • Trustless Execution: Anyone can deploy and execute an invoice once sufficient tokens are detected

Deployment Information

Network Deployments

Base Sepolia Testnet

  • Vault: 0x65BBAb4F6f9c0b55dfd4C753696FF4733dC96625
  • ProtocolManager: 0xfe4E6293E2ca5B4DB25De8A0674D9f4765b7056C
  • Forwarder: 0xCbB01c4A7375983171f12951f1ec18C02efB78f4
  • Administrator: 0xbc487E983ea0e75F6E29e8107De26f2feaa548fb
  • InvoiceFactory: 0x854Ef2c618b2c72044efB68F8Dc72e08C253152c

Security

  • Audited Dependencies: Uses OpenZeppelin and Solady contracts
  • Reentrancy Protection: Built-in guards against reentrancy attacks
  • Access Control: Proper authorization mechanisms with multisig governance
  • Zero-Knowledge Proofs: Cryptographic privacy guarantees
  • Emergency Pause: Security council can pause contracts in emergencies