# safe-global/safe-smart-account architecture

> Architecture diagram of the GitHub repository safe-global/safe-smart-account, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/safe-global/safe-smart-account
- Repository: https://github.com/safe-global/safe-smart-account

## Overview

##### Main Components
- Smart Contract Modules: Represented in the “contracts” folder, these are organized in subdirectories (accessors, base, common, examples, external, handler, interfaces, libraries, proxies, etc.). They form the core of the Safe Smart Account logic.
- Deployment & Task Scripts: The “src” directory contains scripts for contract deployments (in deploy/) and management tasks (in tasks/). These coordinate building, verifying, and deploying the contracts across various networks.
- Formal Verification and Auditing: The “certora” directory holds configuration files, specs, harnesses, and patches for performing formal verification and mutation testing using Certora. Also include the “docs” folder that comprises audit reports and formal verification documents.
- Configuration & Infrastructure: Files like hardhat.config.ts, .env.sample, package.json, GitHub workflow files, and continuous integration scripts provide project configuration, deployment parameters, and CI/CD integration.

##### Relationships and Interactions
- External Dependencies: Include external tools like the Safe deployments repository, Etherscan, and Certora (deterministic deployment via singleton factory and replay protection setups).

##### Architectural Patterns and Design Principles
- Modularity: The separation into different folders (contracts, src for deployment, test suites, certora for formal verification, etc.) emphasizes a modular approach.
- Deterministic Deployment: Notably, the README mentions deploying contracts deterministically (using safe-singleton-factory) and the need for replay protection as per EIP-155.
- Extensibility: With directories for examples (contracts/examples) and extensible handlers (contracts/handler/extensible), the design supports future enhancements and customization.
- Continuous Integration/Delivery: The inclusion of GitHub workflows, Husky pre-commit hooks, and configuration for automated testing/verification reflects a CI/CD oriented design.

##### Relevant Technologies, Frameworks, and Libraries
- Solidity (version 0.7.6 as per deployment notes) for the smart contracts.
- Hardhat for development, testing, and deployment workflows.
- Certora for formal verification and mutation testing.
- Node.js and npm for package management.
- GitHub Actions (workflows) and Husky hooks for code quality and CI integration.
- ERC-4337 compatibility tools for handling advanced smart account features.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Smart Contract Core
    subgraph "Smart Contract Core"
        Contracts["Smart Contract Modules"]:::smartcontract
    end

    %% Deployment & Management
    subgraph "Deployment & Management"
        Deploy["Deployment Scripts"]:::deployment
        Tasks["Task Management Scripts"]:::deployment
        Config["Configuration & Infrastructure"]:::ci
    end

    %% Testing & Verification
    subgraph "Testing & Verification"
        Tests["Testing Suite"]:::test
        Benchmark["Benchmarking Scripts"]:::test
        FormalVer["Formal Verification & Certification"]:::verification
        Auditing["Auditing Documents"]:::verification
    end

    %% Relationships
    Contracts -->|"deploys"| Deploy
    Deploy -->|"triggers"| Tasks
    Config -->|"supports"| Deploy
    Config -->|"supports"| Tests
    Contracts -->|"testedBy"| Tests
    Tests -->|"benchmarks"| Benchmark
    Contracts -->|"verifiedBy"| FormalVer
    FormalVer -->|"audits"| Auditing

    %% External Dependencies (Not clickable)
    External["External Dependencies: Etherscan, Certora Tools, Safe Deployments"]:::ci
    Deploy ---|"integrates with"| External

    %% Click Events
    click Contracts "https://github.com/safe-global/safe-smart-account/tree/main/contracts"
    click Deploy "https://github.com/safe-global/safe-smart-account/tree/main/src/deploy"
    click Tasks "https://github.com/safe-global/safe-smart-account/tree/main/src/tasks"
    click Tests "https://github.com/safe-global/safe-smart-account/tree/main/test"
    click Benchmark "https://github.com/safe-global/safe-smart-account/tree/main/benchmark"
    click FormalVer "https://github.com/safe-global/safe-smart-account/tree/main/certora"
    click Auditing "https://github.com/safe-global/safe-smart-account/tree/main/docs"
    click Config "https://github.com/safe-global/safe-smart-account/blob/main/hardhat.config.ts"

    %% Styles
    classDef smartcontract fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef deployment fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef ci fill:#FA8072,stroke:#000,stroke-width:2px;
    classDef test fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef verification fill:#FFD700,stroke:#000,stroke-width:2px;
```
