# Core Design Principles

## Core Design Principles

The bridge architecture is built on three fundamental design principles that work together to create a secure and reliable system:

1. **Separated Concerns**
   * The system deliberately separates message processing from fund custody to enhance security
   * The CanonicalBridge contract handles user interactions and authorization logic but doesn't store funds
   * The Treasury contract acts as a secure vault, isolating ETH storage from bridge logic
   * This separation means that even if the bridge logic is compromised, funds remain secure in the Treasury
   * By requiring multiple compromised components for a successful attack, the system creates defense in depth
2. **Security-First Flow**
   * All fund movements associated with L2 withdrawal authorizations  (principle withdrawal amounts, relayer fees) go through a mandatory fraud detection window (default 7 days)
   * This time-lock mechanism allows for intervention if suspicious activity is detected
   * Trusted relayers serve as cross-chain messengers but with limited authority
   * Multiple security roles create checks and balances in the system
   * The Bridge Troll role provides an independent security monitor that can cancel suspicious withdrawals
3. **Distributed Trust Model**
   * No single entity has complete control over the cross-chain transfer process
   * Role-based access control (RBAC) distributes authority across multiple entities
   * The separation between L1 and L2 components creates natural security boundaries
   * Time-locked operations provide opportunity for security interventions
   * Emergency roles allow for crisis management without compromising normal operations

## Why This Architecture Matters

This architecture addresses common vulnerabilities in cross-chain bridges that have led to numerous exploits in the blockchain ecosystem:

* **Protection Against Flash Attacks**: The 7-day fraud window prevents immediate withdrawal of compromised funds, giving security teams time to respond
* **Defense in Depth**: Separation of concerns means attackers must compromise multiple components to steal funds
* **Governance Flexibility**: Role-based access control allows for different security models, from centralized to DAO-based governance
* **Upgradeability**: The UUPS pattern on the Treasury contract enables future improvements without migrating user assets to updated implementations
* **Emergency Response**: Dedicated emergency roles and pause functionality allow for rapid response to threats


---

# Agent Instructions: 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/core-design-principles.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.