# Component Relationships & Diagrams ## Component Relationships Explained The diagram below illustrates the user operations flow across the system components: {% @mermaid/diagram content="graph TB User((User)) L1Bridge\[L1 CanonicalBridge] Treasury\[Treasury] L2Bridge\[L2 Bridge Program] ``` User -->|Deposit ETH| L1Bridge L1Bridge -->|Store| Treasury User -->|Burn tokens| L2Bridge User -->|Claim withdrawal| L1Bridge Treasury -->|Release ETH| User classDef contract fill:#f9f,stroke:#333,stroke-width:2px classDef user fill:#dfd,stroke:#333,stroke-width:2px classDef program fill:#fdb,stroke:#333,stroke-width:2px class L1Bridge,Treasury contract class User user class L2Bridge program" %} ``` **Key Insights from this Diagram:** * **User Interaction Points**: Users interact directly with both L1 and L2 components depending on the operation they're performing. For deposits, they interact with the CanonicalBridge on L1. For initiating withdrawals, they interact with the L2 Bridge Program. For claiming withdrawals, they return to the CanonicalBridge on L1. * **Intermediary Role of CanonicalBridge**: The CanonicalBridge acts as an intermediary between users and the Treasury, never directly holding funds but controlling their movement through authorization. * **Isolation of Treasury**: The Treasury never interacts directly with L2 components, maintaining isolation between chains. This is a critical security feature that prevents L2 vulnerabilities from directly affecting L1 funds. * **Cross-Chain User Journey**: Users must perform actions on both chains to complete a full deposit-withdraw cycle. This is a fundamental aspect of cross-chain bridges that developers must understand when building applications that interact with the bridge. * **Separation of Deposit and Withdrawal Flows**: The diagram shows clear separation between deposit and withdrawal paths, which is a key security feature of the system. ## Cross-chain Trust Model The cross-chain trust model illustrates how authority and information flow between chains: {% @mermaid/diagram content="graph TB subgraph Ethereum L1 L1Bridge\[L1 CanonicalBridge] Treasury\[Treasury] WithdrawAuth\[Withdraw Authority] end ``` subgraph Eclipse L2 L2Bridge[L2 Bridge Program] DepositRelayer[Deposit Relayer] WithdrawRelayer[Withdraw Relayer] end %% Internal Trust L1Bridge -->|trusted depositor| Treasury Treasury -->|trusted authority| L1Bridge %% Cross-Chain Operations L1Bridge -->|emit deposit events| DepositRelayer DepositRelayer -->|mint authority| L2Bridge L2Bridge -->|emit burn events| WithdrawRelayer WithdrawRelayer -->|withdrawal authority| WithdrawAuth WithdrawAuth -->|authorize| L1Bridge classDef contract fill:#f9f,stroke:#333,stroke-width:2px classDef role fill:#bbf,stroke:#333,stroke-width:1px classDef program fill:#fdb,stroke:#333,stroke-width:2px class L1Bridge,Treasury contract class WithdrawAuth role class L2Bridge,DepositRelayer,WithdrawRelayer program" %} ``` **Key Security Insights:** * **Unidirectional Information Flow**: Information flows unidirectionally through relayers, preventing circular dependencies that could create security vulnerabilities. This design pattern is crucial for cross-chain systems to prevent feedback loops. * **Critical Security Checkpoint**: The Withdrawal Authority serves as a critical security checkpoint, being the only entity that can authorize withdrawals on L1. This concentrated authority point should be highly secured. * **Principle of Least Privilege**: Each component has limited scope and authority, implementing the principle of least privilege. For example, the Deposit Relayer can only observe events and request mints, not directly mint tokens or access funds. * **Security Boundary**: The separation between observation (relayers) and authorization (contracts) creates a security boundary. Relayers can observe events but cannot directly execute actions without proper authorization. * **Trust Minimization**: The system minimizes trust requirements by distributing authority and implementing checks and balances. No single entity can control the entire deposit or withdrawal process. ## Administrative Operations The administrative structure of the bridge is designed with careful consideration of security and operational needs. The role-based access control system ensures that administrative powers are distributed appropriately. ### CanonicalBridge Administration The CanonicalBridge implements a comprehensive role system: {% @mermaid/diagram content="graph TB Admin((DEFAULT\_ADMIN\_ROLE)) ``` subgraph L1 Bridge Roles PAUSER[PAUSER_ROLE] STARTER[STARTER_ROLE] WITHDRAW_AUTH[WITHDRAW_AUTHORITY_ROLE] CLAIM_AUTH["CLAIM_AUTHORITY_ROLE
(Bridge Contract)"] WITHDRAW_CANCEL["WITHDRAW_CANCELLER_ROLE
(Bridge Troll)"] FRAUD_WINDOW[FRAUD_WINDOW_SETTER_ROLE] end Admin -->|grant role| PAUSER Admin -->|grant role| STARTER Admin -->|grant role| WITHDRAW_AUTH Admin -->|grant role| CLAIM_AUTH Admin -->|grant role| WITHDRAW_CANCEL Admin -->|grant role| FRAUD_WINDOW PAUSER -->|emergency pause|L1Bridge[L1 CanonicalBridge] STARTER -->|resume operations|L1Bridge WITHDRAW_AUTH -->|authorize withdrawals|L1Bridge CLAIM_AUTH -->|withdraw funds|L1Bridge WITHDRAW_CANCEL -->|cancel suspicious withdraws|L1Bridge FRAUD_WINDOW -->|set security timeframe|L1Bridge classDef contract fill:#f9f,stroke:#333,stroke-width:2px classDef role fill:#bbf,stroke:#333,stroke-width:1px classDef admin fill:#dfd,stroke:#333,stroke-width:2px class L1Bridge contract class PAUSER,STARTER,WITHDRAW_AUTH,CLAIM_AUTH,WITHDRAW_CANCEL,FRAUD_WINDOW role class Admin admin" %} ``` **Administrative Role Analysis:** * **Root Administrative Authority**: The DEFAULT\_ADMIN\_ROLE is the highest authority, capable of granting and revoking all other roles. This role should be assigned to a highly secure entity, such as a multi-signature wallet or governance contract. * **Emergency Response Separation**: Emergency response is handled by separate PAUSER and STARTER roles, allowing for quick reaction to threats while maintaining separation of duties. This prevents a single compromised entity from both pausing and restarting the system. * **Withdrawal Authority**: The WITHDRAW\_AUTHORITY\_ROLE (typically assigned to the Withdrawal Relayer) is the only entity that can authorize withdrawals. This role is a critical security point and should be highly secured. * **Claim Authority**: The CLAIM\_AUTHORITY\_ROLE is typically assigned to an operational multisig wallet. The role allows the operational multisig to settle pending claims to users on their behalf. * **Independent Security Monitor**: The WITHDRAW\_CANCELLER\_ROLE (Bridge Troll) provides an independent security check, able to cancel suspicious withdrawals during the fraud window. This role should be assigned to a security-focused entity with sophisticated monitoring capabilities. * **Security Parameter Control**: The FRAUD\_WINDOW\_SETTER\_ROLE can adjust the security timeframe based on risk assessment. This role should be assigned to an entity with a deep understanding of security implications. ### **Security Considerations:** * **Multi-Signature Governance**: In production, the DEFAULT\_ADMIN\_ROLE should be assigned to a multi-signature wallet or governance contract to prevent single points of failure. * **Rapid Response Team**: The PAUSER\_ROLE should be assigned to entities that can respond quickly to emergencies, potentially with lower thresholds for action than the admin role. * **Security Expertise**: The WITHDRAW\_CANCELLER\_ROLE should be assigned to a security-focused entity with monitoring capabilities and expertise in identifying suspicious patterns. * **Role Separation**: Ideally, different roles should be assigned to different entities to maintain separation of duties and prevent concentration of power. ### Treasury Administration The Treasury implements its own role system: {% @mermaid/diagram content="graph TB Admin((DEFAULT\_ADMIN\_ROLE)) ``` subgraph Treasury Roles DEPOSITOR[DEPOSITOR_ROLE] WITHDRAW_AUTH[WITHDRAW_AUTHORITY_ROLE] PAUSER[PAUSER_ROLE] STARTER[STARTER_ROLE] UPGRADER[UPGRADER_ROLE] EMERGENCY[EMERGENCY_ROLE] end Admin -->|grant role| DEPOSITOR Admin -->|grant role| WITHDRAW_AUTH Admin -->|grant role| PAUSER Admin -->|grant role| STARTER Admin -->|grant role| UPGRADER Admin -->|grant role| EMERGENCY DEPOSITOR -->|deposit|Treasury[Treasury] WITHDRAW_AUTH -->|withdraw|Treasury PAUSER -->|pause|Treasury STARTER -->|unpause|Treasury UPGRADER -->|upgrade UUPS|Treasury EMERGENCY -->|emergency withdraw|Treasury classDef contract fill:#f9f,stroke:#333,stroke-width:2px classDef role fill:#bbf,stroke:#333,stroke-width:1px classDef admin fill:#dfd,stroke:#333,stroke-width:2px class Treasury contract class DEPOSITOR,WITHDRAW_AUTH,PAUSER,STARTER,UPGRADER,EMERGENCY role class Admin admin" %} ``` **Treasury Role Analysis:** * **Bridge Integration**: The DEPOSITOR\_ROLE is typically assigned to the CanonicalBridge contract, allowing it to deposit ETH into the Treasury during user deposits. * **Withdrawal Authorization**: The WITHDRAW\_AUTHORITY\_ROLE is typically assigned to the CanonicalBridge contract, allowing it to withdraw ETH from the Treasury when processing user withdrawals. * **Upgrade Control**: The UPGRADER\_ROLE controls the UUPS upgradeability mechanism, allowing for future improvements to the Treasury contract without disrupting user assets. * **Emergency Recovery**: The EMERGENCY\_ROLE provides a last-resort mechanism for fund recovery in extreme situations. This role should be highly secured and used only in genuine emergencies. ### **Implementation Guidance:** * **Administrative Separation**: The Treasury's DEFAULT\_ADMIN\_ROLE should be assigned to a different entity than the CanonicalBridge's admin to maintain separation of concerns. * **Secure Emergency Access**: The EMERGENCY\_ROLE should be assigned to a highly secure multi-signature wallet with strict governance, potentially requiring a higher threshold than normal operations. * **Transparent Upgrades**: The UPGRADER\_ROLE should follow a timelock mechanism for upgrades to allow for community review and ensure transparency in the upgrade process. * **Operational Continuity**: The PAUSER\_ROLE and STARTER\_ROLE should be assigned to entities that can respond quickly to emergencies while maintaining separation of duties. --- # 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/component-relationships-and-diagrams.md?ask= ``` 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.