Skip to content

Latest commit

 

History

History
278 lines (193 loc) · 7.85 KB

zeusd-router.md

File metadata and controls

278 lines (193 loc) · 7.85 KB

ZeUSD Router

Product Overview

The ZeUSD Router is the primary gateway for users to interact with the ZeUSD protocol. It acts as a central hub that enables users to:

  • Create ZeUSD by depositing collateral or stable coins
  • Bridge ZeUSD across different blockchain networks
  • Burn ZeUSD to retrieve their collateral
  • Manage their positions and interactions with the protocol

Core Components

1. Access Control System

The access control system ensures secure and compliant protocol usage through multiple layers:

1.1 Administrative Control

  • DEFAULT_ADMIN_ROLE (Owner)
    • Highest level of access in the protocol
    • Can grant/revoke other roles
    • Controls critical protocol parameters
    • Manages emergency operations
  • ADMIN_ROLE (Admin)
    • Manages day-to-day operations
    • Controls whitelist
    • Updates protocol configurations
    • Monitor system health

1.2 User Access Management

  • Whitelist System
    • Ensures KYC/KYB compliance
    • Controls who can mint ZeUSD
    • Maintains regulatory standards
    • Tracks user permissions
  • Blacklist Integration
    • Blocks malicious actors
    • Enforces compliance requirements
    • Protects protocol security
    • Maintains system integrity

2. Protocol Integration Components

2.1 Collateral Vault Integration

The Collateral Vault manages all collateral positions in the protocol:

  • Tracks user deposits and positions
  • Calculates collateral ratios
  • Manages liquidation thresholds
  • Provides price feed integration

2.2 ZeUSD Token Management

Direct interface with the ZeUSD token contract for:

  • Minting new tokens based on collateral
  • Burning tokens during redemption
  • Managing token supply
  • Tracking user balances

2.3 LayerZero Cross-Chain Operations

Enables seamless cross-chain functionality through:

  • Secure message passing between chains
  • Token bridging capabilities
  • Cross-chain position management
  • Unified liquidity across networks

2.4 Sub Vault Interactions

Manages specialized vaults for different asset types:

  • RWA (Real World Asset) vaults
  • Stable coin vaults
  • Protocol-specific integrations
  • Custom asset handlers

Key Features

1. CDP Minting Engine

Users can create ZeUSD through two primary methods:

1.1 Direct Collateral Deposits

In this process:

  1. Users deposit supported collateral (e.g., ZTLN)
  2. System validates collateral and user eligibility
  3. Calculates appropriate ZeUSD amount based on:
    • Collateral value
    • Current oracle prices
    • LTV ratios
  4. Mints ZeUSD to user's wallet
  5. Records position in Collateral Vault

1.2 Stablecoin Deposits

In this process:

  1. Deposit supported stablecoins (e.g., USDC)
  2. System routes to appropriate SubVault
  3. SubVault invests in underlying protocol
  4. Mints equivalent ZeUSD based on deposit

1.3 Cross-Chain Bridging

When users want to move ZeUSD across chains:

This enables:

  • Seamless cross-chain movement
  • Unified liquidity across networks
  • Chain-agnostic usage
  • Optimized gas efficiency

2. Burning Mechanism

Users can redeem their ZeUSD for underlying collateral through a secure process:

2.1 Collateral Redemption

The system:

  1. Verifies user's ZeUSD balance
  2. Checks position exists and is active
  3. Burns specified ZeUSD amount
  4. Returns equivalent collateral
  5. Updates position records

2.2 Position Management

  • Tracks all user positions
  • Manages partial redemptions
  • Updates collateral ratios
  • Maintains position history

3. Security Framework

3.1 Access Protection

Multiple layers of security ensure safe operations:

   modifier whitelistedOnly() {
       if (!_whitelisted[msg.sender]) revert NotWhitelisted(msg.sender);
       _;
   }
   modifier notBlacklisted() {
       if (zeusdToken.isBlacklisted(msg.sender)) revert Blacklisted(msg.sender);
       _;
   }
   modifier whenNotPaused() {
       if (depositsPaused) revert DepositsArePaused();
       _;
   }

3.2 Operation Safeguards

  • Reentrancy Guards: Prevent multiple calls
  • Pause Mechanism: Emergency stops
  • Role Validation: Access control
  • Amount Validation: Input checking

Implementation Details

1. Mint With Collateral Flow

In this flow:

  1. User Initiation: User calls mintWithCollateral with their chosen collateral asset (e.g., ZTLN) and amount
  2. Access Verification: Router checks if user is whitelisted and not blacklisted
  3. SubVault Location: Gets the appropriate SubVault address for the collateral type
  4. Asset Validation: Verifies the collateral is supported by the SubVault
  5. Collateral Transfer: Transfers user's collateral to the designated SubVault
  6. Position Recording: Records the deposit details in CollateralVault for tracking
  7. Amount Calculation: Calculates how much ZeUSD to mint based on collateral value and LTV
  8. Token Minting: Mints the calculated amount of ZeUSD to user's wallet

2. Mint With Stable Flow

This process involves:

  1. User Request: User initiates stable token deposit (e.g., USDC)
  2. Access Checks: Verifies user's permission to use the protocol
  3. Vault Verification: Locates correct Sub Vault for the stable token
  4. Asset Validation: Confirms stable token is supported
  5. Token Transfer: Moves stable tokens to Sub Vault
  6. Protocol Integration: Sub Vault deposits stables into underlying protocol
  7. Record Keeping: Records the stable deposit in Collateral Vault
  8. ZeUSD Issuance: Mints equivalent ZeUSD based on stable deposit

3. Burn Flow

The burn process includes:

  1. Burn Request: User initiates burn of ZeUSD to reclaim their collateral
  2. Permission Check: Verifies user's authorization
  3. Vault Location: Identifies correct Sub Vault storing user's collateral
  4. Asset Verification: Confirms asset type matches original deposit
  5. Position Update: Marks the deposit as inactive in Collateral Vault
  6. Token Burning: Burns the specified amount of ZeUSD
  7. Collateral Release: Withdraws collateral from Sub Vault
  8. Return Assets: Transfers collateral back to user's wallet

Oracle Integration

The Router relies on price oracles through the Collateral Vault for calculating mint amounts:

  1. Price Discovery
    • Collateral prices from Chainlink oracles
    • Price validation and fallback mechanisms
    • Staleness checks and safety bounds
  2. Mint Amount Calculation

$$ mintAmount = \frac{{collateralAmount \times price \times LTV}}{{SCALE \times PRICE_DECIMALS}} $$

  1. Oracle Safety Measures
    • Price deviation checks
    • Minimum/maximum bounds
    • Heartbeat verification
    • Multiple oracle support for critical assets

Error Handling

  1. Custom Errors
error NotWhitelisted(address account);
error Blacklisted(address account);
error InvalidAddress(address address);
error ZeroAmount();
error DepositsArePaused();
error InsufficientBalance(string token);
  1. State Validation
  • Pre-condition checks
  • Balance verification
  • Allowance validation
  • Asset support verification

Upgradeability

The Router implements UUPS upgradeability pattern:

  • State variable organization
  • Implementation slot management
  • Proper initialization sequence
  • Storage gap for future upgrades