# Hierarchical Safe Implementation Architecture ## Introduction This document outlines two robust approaches to implementing hierarchical control structures using Gnosis Safe. Each design serves different organizational needs and security requirements, offering unique advantages for specific use cases. ## The Challenge Organizations need secure and flexible asset management systems that provide: - Clear hierarchical control - Granular permissions - Defined operational boundaries - Emergency controls - Recovery mechanisms ## Design Approaches ### Option 1: Role-Based Single Safe Ideal for organizations that need robust role-based control within a single treasury. ```mermaid graph TB %% Core Safe Structure Safe[("Safe Multisig 3/5")] --> Modules %% Module Layer Modules --> Roles["Roles ModuleAccess Control"] Modules --> Guard["Guard ModuleLimits & Checks"] Modules --> Recovery["Recovery Module4/7 Guardians"] %% Role Hierarchy Roles --> AdminRole["Admin Role• Full Access• No Limits"] AdminRole --> ManagerRole["Manager Role• 100 ETH Daily• Token Management"] ManagerRole --> OperatorRole["Operator Role• 10 ETH Daily• Basic Operations"] ManagerRole --> DelegateRole["Delegate Role• 1 ETH Daily• Time Limited"] %% Styling classDef safe fill:#f9f,stroke:#333,stroke-width:4px,rx:10px classDef module fill:#bbf,stroke:#333,stroke-width:2px classDef role fill:#efe,stroke:#333,stroke-width:2px classDef delegate fill:#fff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5 %% Apply styles class Safe safe class Roles,Guard,Recovery module class AdminRole,ManagerRole,OperatorRole role class DelegateRole delegate ``` **Key Benefits:** - Streamlined operations - Lower gas costs - Simpler maintenance - Clear role hierarchy ### Option 2: Nested Safe Structure Perfect for large organizations requiring physical separation of concerns and multiple security layers. ```mermaid graph TD %% Top Level Structure TopSafe[Top Safe 2/3Treasury & Governance] --> |Signer| Boss[Boss EOAUltimate Control] TopSafe --> |Signer| Recovery[Recovery ContractEmergency Control] TopSafe --> |Signer| L2Safe[L2 Safe 3/5 Operations] TopSafe --> |Monthly Funds| L2Safe %% L2 Safe Internal Structure L2Safe --> Modules[L2 Modules] Modules --> Roles[Roles Module] Modules --> Guard[Guard Module Limits & Checks] %% L2 Role Hierarchy Roles --> AdminRole[Admin Role50 ETH Daily] AdminRole --> ManagerRole[Manager Role 10 ETH Daily] ManagerRole --> OperatorRole[Operator Role 1 ETH Daily] ManagerRole --> DelegateRole[Delegate Role 0.1 ETH Daily] classDef topLevel fill:#f9f,stroke:#333,stroke-width:2px classDef l2Level fill:#bbf,stroke:#333,stroke-width:2px classDef module fill:#ddf,stroke:#333,stroke-width:1px classDef role fill:#efe,stroke:#333,stroke-width:1px class TopSafe,Boss,Recovery topLevel class L2Safe,Modules l2Level class Roles,Guard module class AdminRole,ManagerRole,OperatorRole,DelegateRole role ``` **Key Benefits:** - Physical separation of assets - Multiple security layers - Isolated risk management - Ultimate override capability - Separate recovery mechanisms per layer ## Implementation Guide ### When to Choose Each Option #### Choose Role-Based Single Safe When: - Single treasury management is sufficient - Role-based permissions meet security needs - Quick execution is priority - Team is centralized #### Choose Nested Structure When: - Physical separation of funds is required - Multiple security layers are needed - Different teams manage different operations - Ultimate override capability is essential - Multiple recovery paths are required ## Technical Implementation ### Role-Based Setup 1. Deploy Safe contract 2. Enable Zodiac modules for roles 3. Configure permission hierarchy 4. Set up guards and limits 5. Can be accomplished no-code ### Nested Structure Setup 1. Deploy Top Safe (Master Treasury) 2. Deploy L2 Safe (Operations) 3. Configure cross-safe interactions 4. Set up modular controls per level 5. Might require some custom code ## Production Considerations ### Role-Based Considerations - Module upgrade strategy - Permission management - Guard configurations - Recovery procedures ### Nested Structure Considerations - Cross-safe communication - Funding workflows - Emergency procedures - Multiple recovery paths - Maintainance ## References - [Zodiac Documentation](https://github.com/gnosisguild/zodiac-modifier-roles) - [Safe Modules Documentation](https://docs.safe.global/advanced/smart-account-modules) - [Mimir](https://evm-docs.mimir.global/) ## Appendix: Detailed Transaction Flows ### Role-Based Transactions ```mermaid sequenceDiagram participant Admin participant Manager participant Operator participant Safe participant Guard participant Chain Note over Admin, Chain: Admin Transfer (No Limits) Admin->>Safe: Large Transfer Safe->>Guard: Check Role & Approval Req Guard->>Guard: Admin Role = Full Rights Guard-->>Safe: Needs 3/5 Approval Safe->>Safe: Collect 3/5 Safe->>Chain: Execute Note over Admin, Chain: Manager Standard Op Manager->>Safe: Token Swap Safe->>Guard: Check Role & Limits Guard->>Guard: Check if Pre-approved Op Guard-->>Safe: Within 100 ETH + Needs 2/5 Safe->>Safe: Collect 2/5 Safe->>Chain: Execute ``` ### Nested Safe Transactions ```mermaid sequenceDiagram participant L2Safe as L2 Safe (3/5) participant TopSafe as Top Safe (2/3) participant Boss as Boss EOA participant Chain as Chain Note over L2Safe, Chain: Request Funding from Top Safe L2Safe->>TopSafe: Propose Funding Request TopSafe->>Boss: Review Request Boss-->>TopSafe: Approve TopSafe->>TopSafe: Collect 2/3 TopSafe->>Chain: Transfer Funds to L2 Chain-->>L2Safe: Funds Received ``` ```mermaid sequenceDiagram participant Op as Operator participant L2Safe as L2 Safe (3/5) participant Guard as Guard participant Chain as Chain Note over Op, Chain: Standard L2 Operations Op->>L2Safe: Submit Tx (<10 ETH) L2Safe->>Guard: Check Role & Limits Guard-->>L2Safe: Needs 3/5 L2Safe->>L2Safe: Collect 3/5 L2Safe->>Chain: Execute ``` **Additional Architectural documentation can be provided on demand**