> 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/access-control-implementation.md). # Access Control Implementation ## Access Control Implementation The role-based access control system is implemented using OpenZeppelin's AccessControl and AccessControlUpgradeable contracts. This provides a standardized and audited approach to role management. #### CanonicalBridge Role Flow {% @mermaid/diagram content="graph LR Admin\[Admin/Owner] Pauser\[PAUSER\_ROLE] Starter\[STARTER\_ROLE] WithdrawAuth\[WITHDRAW\_AUTHORITY\_ROLE] ClaimAuth\[CLAIM\_AUTHORITY\_ROLE] WithdrawCanceller\[WITHDRAW\_CANCELLER\_ROLE] FraudWindowSetter\[FRAUD\_WINDOW\_SETTER\_ROLE] ``` Admin -->|Grants| Pauser Admin -->|Grants| Starter Admin -->|Grants| WithdrawAuth Admin -->|Grants| ClaimAuth Admin -->|Grants| WithdrawCanceller Admin -->|Grants| FraudWindowSetter Pauser -->|emergency pause|L1Bridge[L1 CanonicalBridge] Starter -->|resume operations|L1Bridge WithdrawAuth -->|authorize withdrawals|L1Bridge ClaimAuth -->|withdraw funds|L1Bridge WithdrawCanceller -->|cancel suspicious withdraws|L1Bridge FraudWindowSetter -->|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,WithdrawAuth,ClaimAuth,WithdrawCanceller,FraudWindowSetter role class Admin admin" %} ``` **Code Implementation:**\ The role checks are implemented using modifiers in the CanonicalBridge contract: ```solidity // Example role check implementation function authorizeWithdraw(WithdrawMessage calldata message) external onlyRole(WITHDRAW_AUTHORITY_ROLE) whenNotPaused { // Implementation details } ``` This pattern ensures that only authorized entities can perform sensitive operations. The `onlyRole` modifier checks that the caller has the required role before executing the function body. ### Treasury Role Flow {% @mermaid/diagram content="graph LR Admin\[Admin/Owner] Depositor\[DEPOSITOR\_ROLE] WithdrawAuth\[WITHDRAW\_AUTHORITY\_ROLE] Pauser\[PAUSER\_ROLE] Starter\[STARTER\_ROLE] Upgrader\[UPGRADER\_ROLE] Emergency\[EMERGENCY\_ROLE] ``` Admin -->|Grants| Depositor Admin -->|Grants| WithdrawAuth Admin -->|Grants| Pauser Admin -->|Grants| Starter Admin -->|Grants| Upgrader Admin -->|Grants| Emergency Depositor -->|deposit|Treasury[Treasury] WithdrawAuth -->|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,WithdrawAuth,Pauser,Starter,Upgrader,Emergency role class Admin admin" %} ``` **Technical Implementation Details:** * **Role Definition**: Roles are defined as bytes32 constants using keccak256 hashes: ```solidity bytes32 public constant DEPOSITOR_ROLE = keccak256("DEPOSITOR_ROLE"); bytes32 public constant WITHDRAW_AUTHORITY_ROLE = keccak256("WITHDRAW_AUTHORITY_ROLE"); ``` * **Role Storage**: Role assignments are stored in a mapping structure that tracks which addresses have which roles. * **Role Checks**: Role checks are performed using the `onlyRole` modifier, which reverts the transaction if the caller doesn't have the required role. * **Administrative Control**: The DEFAULT\_ADMIN\_ROLE has the authority to grant and revoke all other roles, providing centralized role management. ## Administrative Functions Deep Dive ### Role Management The DEFAULT\_ADMIN\_ROLE has the authority to grant and revoke all other roles. This is implemented using OpenZeppelin's AccessControl contract: ```solidity // Grant a role function grantRole(bytes32 role, address account) public override onlyRole(getRoleAdmin(role)) { _grantRole(role, account); } // Revoke a role function revokeRole(bytes32 role, address account) public override onlyRole(getRoleAdmin(role)) { _revokeRole(role, account); } ``` These functions ensure that only authorized entities can modify role assignments. The `getRoleAdmin` function returns the admin role for a given role, which is typically the DEFAULT\_ADMIN\_ROLE. ### System Upgrades The Treasury contract implements the UUPS (Universal Upgradeable Proxy Standard) pattern for upgradeability: ```solidity // Upgrade implementation function _authorizeUpgrade(address newImplementation) internal override onlyRole(UPGRADER_ROLE) { // Additional upgrade logic if needed } ``` This function is called during the upgrade process and ensures that only entities with the UPGRADER\_ROLE can upgrade the contract. The UUPS pattern allows for upgrading the contract logic while maintaining the same contract address and state. ### Emergency Controls The PAUSER\_ROLE and STARTER\_ROLE control the operational state of the contracts: ```solidity // Pause operations function pause() external onlyRole(PAUSER_ROLE) { _pause(); } // Unpause operations function unpause() external onlyRole(STARTER_ROLE) { _unpause(); } ``` These functions allow for quickly pausing the contract in emergency situations and resuming operations when the emergency is resolved. The separation of these roles ensures that a single compromised entity cannot both pause and unpause the contract. ### Withdrawal Authorization The WITHDRAW\_AUTHORITY\_ROLE authorizes withdrawals: ```solidity function authorizeWithdraw(WithdrawMessage calldata message) external onlyRole(WITHDRAW_AUTHORITY_ROLE) whenNotPaused { // Validate message // Start fraud window // Emit event } ``` This function is called by the Withdrawal Relayer to initiate the withdrawal process. It validates the withdrawal message, starts the fraud window, and emits an event for tracking. The role restriction ensures that only authorized entities can initiate withdrawals. ### Withdrawal Cancellation The WITHDRAW\_CANCELLER\_ROLE can cancel suspicious withdrawals: ```solidity function deleteWithdrawMessage(WithdrawMessage calldata message) external onlyRole(WITHDRAW_CANCELLER_ROLE) { // Validate message exists // Delete message // Emit event } ``` This function allows the Bridge Troll to cancel suspicious withdrawals during the fraud window. It validates that the withdrawal exists, deletes it from the system, and emits an event for tracking. This provides a critical security mechanism for preventing fraudulent withdrawals. ### Security Configuration The FRAUD\_WINDOW\_SETTER\_ROLE configures the fraud window duration: ```solidity function setFraudWindowDuration(uint256 durationSeconds) external onlyRole(FRAUD_WINDOW_SETTER_ROLE) { // Validate duration (minimum 1 day) // Set new duration // Emit event } ``` This function allows for adjusting the fraud window duration based on security needs. It enforces a minimum duration of 1 day to ensure a reasonable security buffer and emits an event for tracking. The role restriction ensures that only authorized entities can modify this critical security parameter. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.eclipse.xyz/architecture/eclipse-architecture/eclipse-canonical-bridge/access-control-implementation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.