Component Relationships & Diagrams

Component Relationships Explained

The diagram below illustrates the user operations flow across the system components:

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:

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:

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:

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.