# se7en-seas/boring-vault architecture

> Architecture diagram of the GitHub repository se7en-seas/boring-vault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/se7en-seas/boring-vault
- Repository: https://github.com/se7en-seas/boring-vault

## Overview

##### Project type and purpose
- This is a Solidity/Ethereum smart‐contract project (using Foundry) implementing the “Boring Vault” architecture with three pluggable onchain components—Manager, Teller, Accountant—and a core vault contract. It includes offchain scripts for Merkle tree generation and deployments across multiple EVM chains.

##### Top‐level structure to architecture domains
- Onchain Contracts (src/)
- src/base – core contracts: BoringVault, ManagerWithMerkleVerification, TellerWithMultiAssetSupport, AccountantWithRateProviders, Roles, Drones, micro-managers.
- src/atomic-queue – atomic withdrawal queue implementation used by the Teller.
- src/base/DecodersAndSanitizers – per-protocol modules that sanitize strategy calls.
- src/interfaces – external protocol interfaces (Aave, Curve, EigenLayer, etc.).
- Offchain Processes (script/, leafs/, resources/)
- script/MerkleRootCreation – builds Merkle trees from strategist leaf JSONs.
- leafs/… – strategist-specific leaf definitions (Decoder addresses, Targets, Selectors, PackedArguments).
- script/ArchitectureDeployments – orchestrates deployment JSONs.
- deployments/… – JSON artifacts recording deployed addresses by network.
- Tooling & CI
- foundry.toml, forge CLI (build/test)
- .github/workflows/test.yml – continuous integration.
- lib/ – onchain libraries (openzeppelin, solmate, OAppAuth, ccip).
- test/ – unit and integration tests.

##### Main components and relationships
- Core Vault (BoringVault)
- Connects to Manager to validate and execute strategy calls via Merkle proofs.
- Exposes deposit/withdraw hooks used internally by the Teller.
- ManagerWithMerkleVerification
- Reads onchain Merkle root (set at deployment).
- Verifies proofs against Strategist leafs JSON (offchain prepared).
- Delegates calls through DecodersAndSanitizers → Target contracts.
- TellerWithMultiAssetSupport
- Calls into BoringVault for share accounting.
- Uses atomic-queue for permissioned withdrawals.
- Enforces shareLockPeriod & refund logic.
- Queries Accountant for exchange rates.
- AccountantWithRateProviders
- Accepts offchain‐computed share price updates (via oracles/scripts).
- Enforces rate‐limit and bound‐limit on updates.
- Pauses vault on anomalous updates.
- Offchain Merkle & Rate Pipeline
- Strategist authors leaf definitions under leafs/.
- MerkleRootCreation scripts produce a Merkle root and JSON proof store.
- Deployment scripts push root & contract addresses onto each network.
- Offchain oracles (Chainlink, custom) compute share rates → Accountant.

##### Architectural patterns & principles
- Pluggable modules: core vault delegates Manager, Teller, Accountant.
- Least‐privilege strategies via Merkle‐tree allowlist.
- Permissioned and time-locked asset flows to mitigate MEV.
- Rate‐limited, bound‐limited offchain oracles for manipulation resistance.
- Multi-network deploy artifacts to support Arbitrum, Mainnet, Base, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Onchain Contracts
    subgraph "Onchain Contracts" 
        direction TB
        BV["BoringVault"]:::onchain
        MWMV["ManagerWithMerkleVerification"]:::onchain
        TWMAS["TellerWithMultiAssetSupport"]:::onchain
        AWRP["AccountantWithRateProviders"]:::onchain
        DnS["DecodersAndSanitizers"]:::onchain
        AQ["Atomic Withdrawal Queue"]:::onchain
        PI["External Protocol Interfaces"]:::onchain
        MM["Micro-Managers"]:::onchain
        R["Roles & Access Control"]:::onchain
        D["Drones"]:::onchain
        G["Governance Modules"]:::onchain
    end

    %% Offchain Processes & Data
    subgraph "Offchain Processes & Data"
        direction TB
        SL["Strategist Leaf Definitions"]:::offchain
        MTC["Merkle Tree Generation Scripts"]:::offchain
        DS["Deployment Orchestration Scripts"]:::offchain
        NA["Network Deployment Artifacts"]:::offchain
        OO["Offchain Oracle Rate Provider"]:::offchain
    end

    %% External Protocols & Oracles
    subgraph "External Protocols & Oracles"
        direction TB
        EXT_PROTO["Aave/Curve/EigenLayer etc."]:::external
        CL_ORA["Chainlink / Custom Oracles"]:::external
    end

    %% Tooling & CI
    subgraph "Tooling & CI"
        direction TB
        FOUNDRY["foundry.toml & Forge CLI"]:::tooling
        CI[".github/workflows/test.yml"]:::tooling
        LIBS["Library Dependencies (lib/)"]:::tooling
        TESTS["Unit & Integration Tests"]:::tooling
    end

    %% User Interaction
    User["User"]:::external

    %% Data Flows and Relationships
    SL -->|"leaf JSON"| MTC
    MTC -->|"produce Merkle Root & proofs"| MWMV
    DS -->|"deploy & set Merkle root"| BV
    DS -->|"deploy contracts"| MWMV
    DS -->|"deploy contracts"| TWMAS
    DS -->|"deploy contracts"| AWRP
    DS -->|"write artifacts"| NA
    User -->|"deposit()/withdraw()"| TWMAS
    TWMAS -->|"deposit()/withdraw()"| BV
    BV -->|"verifyProof() & delegate()"| MWMV
    MWMV -->|"sanitize & forward"| DnS
    DnS -->|"call target"| PI
    TWMAS -->|"use atomic queue"| AQ
    TWMAS -->|"queryRate() / updateRate()"| AWRP
    OO -->|"updateRate()"| AWRP
    AWRP -->|"pauseOnAnomaly"| BV
    EXT_PROTO --> PI
    CL_ORA --> OO

    %% Click Events
    click BV "https://github.com/se7en-seas/boring-vault/blob/main/src/base/BoringVault.sol"
    click MWMV "https://github.com/se7en-seas/boring-vault/blob/main/src/base/ManagerWithMerkleVerification.sol"
    click TWMAS "https://github.com/se7en-seas/boring-vault/blob/main/src/base/TellerWithMultiAssetSupport.sol"
    click AWRP "https://github.com/se7en-seas/boring-vault/blob/main/src/base/AccountantWithRateProviders.sol"
    click AQ "https://github.com/se7en-seas/boring-vault/tree/main/src/atomic-queue/"
    click DnS "https://github.com/se7en-seas/boring-vault/tree/main/src/base/DecodersAndSanitizers/"
    click PI "https://github.com/se7en-seas/boring-vault/tree/main/src/interfaces/"
    click MM "https://github.com/se7en-seas/boring-vault/tree/main/src/micro-managers/"
    click R "https://github.com/se7en-seas/boring-vault/tree/main/src/base/Roles/"
    click D "https://github.com/se7en-seas/boring-vault/tree/main/src/base/Drones/"
    click G "https://github.com/se7en-seas/boring-vault/tree/main/src/base/Governance/"
    click MTC "https://github.com/se7en-seas/boring-vault/tree/main/script/MerkleRootCreation/"
    click SL "https://github.com/se7en-seas/boring-vault/tree/main/leafs/"
    click DS "https://github.com/se7en-seas/boring-vault/tree/main/script/ArchitectureDeployments/"
    click NA "https://github.com/se7en-seas/boring-vault/tree/main/deployments/"
    click FOUNDRY "https://github.com/se7en-seas/boring-vault/blob/main/foundry.toml"
    click CI "https://github.com/se7en-seas/boring-vault/blob/main/.github/workflows/test.yml"
    click LIBS "https://github.com/se7en-seas/boring-vault/tree/main/lib/"
    click TESTS "https://github.com/se7en-seas/boring-vault/tree/main/test/"

    %% Styles
    classDef onchain fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef offchain fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef tooling fill:#e2e3e5,stroke:#333,stroke-width:1px
```
