Architecture

1. CanonicalBridge Contract

   • Serves as the primary user interface for deposits and withdrawal claims

   • Implements role-based access control for administrative functions

   • Manages the fraud detection window for all withdrawals

   • Communicates with the Treasury for fund management

   • Emits events that trigger cross-chain actions

   • Validates all deposit and withdrawal parameters

   • Maintains withdrawal state through the fraud window period

2. Treasury Contract

   • Securely holds all ETH collateral in isolation from business logic

   • Implements UUPS upgradeability pattern for future enhancements

   • Restricts access to funds through strict role-based permissions

   • Provides emergency withdrawal capabilities for extreme situations

   • Can be paused independently from the CanonicalBridge

   • Maintains a clean separation between deposit and withdrawal operations

   • Implements balance checks to prevent overdrafts

3. Deposit Relayer Service

   • Off-chain service that monitors L1 for deposit events

   • Validates deposit parameters before triggering L2 actions

   • Has no direct access to funds, only observational capabilities

   • Serves as a one-way messenger from L1 to L2

   • Implements retry mechanisms for reliability

   • Includes comprehensive logging and monitoring

   • Validates event parameters to prevent invalid minting on L2

4. Withdrawal Relayer Service

   • Off-chain service that receives withdrawal requests from L2

   • Holds the WITHDRAW_AUTHORITY_ROLE to authorize withdrawals

   • Initiates the fraud window period for each withdrawal

   • Cannot directly access funds, only authorize their movement

   • Implements thorough validation of burn events

   • Includes comprehensive logging and monitoring

   • Should be deployed with redundancy for reliability

L2 Components (Eclipse)

1. L2 Bridge Program

   • Handles minting of tokens when deposits are detected

   • Processes burn requests when users want to withdraw

   • Emits events that trigger L1 withdrawal authorizations

   • Maintains balance equivalence between L1 deposits and L2 tokens

   • Validates all mint and burn operations

   • Implements access controls to prevent unauthorized minting

   • Ensures proper token distribution to recipient addresses

2. Deposit Relayer (L2 side)

   • Receives deposit information from the L1 Deposit Relayer

   • Has authority to mint tokens on L2

   • Ensures proper token distribution to recipient addresses

   • Validates all incoming mint requests

   • Implements retry mechanisms for reliability

   • Includes comprehensive logging and monitoring

   • Maintains synchronization with the L1 Deposit Relayer

3. Withdrawal Relayer (L2 side)

   • Monitors L2 for burn events

   • Validates burn parameters

   • Communicates with the L1 Withdrawal Relayer to initiate withdrawals

   • Implements thorough validation of burn events

   • Includes comprehensive logging and monitoring

   • Should be deployed with redundancy for reliability

   • Ensures proper communication with the L1 Withdrawal Relayer

Security Components

1. Bridge Troll (Withdrawal Canceller)

   • Independent security entity with WITHDRAW_CANCELLER_ROLE

   • Monitors withdrawal authorizations for suspicious patterns

   • Can cancel any withdrawal during the fraud window

   • Supports automated cancellation of fraudulent withdrawals

   • Provides an independent check on the withdrawal process

2. Fraud Window

   • Time-lock mechanism (default 7 days, minimum 1 day)

   • Configurable by the FRAUD_WINDOW_SETTER_ROLE

   • Creates a buffer period for security interventions

   • Withdrawal status transitions from PROCESSING to PENDING after this period

   • Provides time for security monitoring and intervention

   • Balances security with user experience

   • Critical security parameter that should be carefully configured