> For the complete documentation index, see [llms.txt](https://docs.eclipse.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eclipse.xyz/architecture/eclipse-architecture/eclipse-canonical-bridge/architecture.md).

# 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) <a href="#l2-components-eclipse" id="l2-components-eclipse"></a>

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 <a href="#security-components" id="security-components"></a>

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eclipse.xyz/architecture/eclipse-architecture/eclipse-canonical-bridge/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.