# aave-dao/aave-umbrella architecture

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

- Interactive diagram: https://gitdiagram.com/aave-dao/aave-umbrella
- Repository: https://github.com/aave-dao/aave-umbrella

## Overview

##### Main Components and Their Responsibilities
- Umbrella Contract – This is the central orchestrator. It monitors reserve deficits across connected pools, calculates/estimates the required coverage funds, and triggers the slashing mechanism.
- StakeToken – This contract represents the upgraded token that holds reserve assets. It tracks an exchange rate, adjusts for slashing events, and is responsible for user withdrawals (through a cooldown mechanism). There is also an aspect of the “waToken (StataTokenV2)” extension used here.
- RewardsController – This component manages the incentives for StakeToken holders. It allocates and distributes multiple types of reward tokens (up to eight, as noted in the README) and manages the claims process.

##### Their Interactions and Integration with Other Systems
- That when a deficit is detected, the Umbrella contract coordinates with the StakeToken contracts (which hold the protected assets) to trigger a slashing event.
- StakeToken component to the RewardsController (you might show a callback or hook mechanism) where rewards are calculated and later claimed by the stakeholders.
- Optionally, indicate that each “market” or pool protected by the Umbrella system can have one or more StakeTokens created.

##### Architectural and Design Patterns
- Modularity: The design clearly separates the concerns – Umbrella (orchestration and monitoring), StakeToken (asset management), and RewardsController (incentive distribution).
- Upgradability and Extension: The system uses extensions (e.g., the StataTokenV2) to evolve token logic, which may be represented as an additional subcomponent or “module” within the StakeToken node.
- Formal Verification: The presence of directories such as “certora” and related scripts/specifications imply that formal verification or automated testing plays a role in ensuring correctness.

##### Technical Environment and Tools (Optional for Context)
- You could also represent the deployment pipeline, including deployment scripts (e.g. deploy.sh, scripts/deploy/…) and CI workflows (files in .github/workflows).

##### Be Detailed Yet Focused
- Be sure to capture both the high-level flow (e.g., from deficit detection to reward distribution) and logical groupings (core modules, extensions, and integration with external protocols).

- Central block “Umbrella Contract” interacting with blocks “StakeToken” and “RewardsController”.
- Periphery blocks representing “Aave Pools/External Reserves” sending data/information into the Umbrella.
- Annotations noting that the StakeToken supports dynamic exchange rates and integrates a cooldown mechanism for withdrawals.
- A sidebar noting the development infrastructure (testing frameworks, certora specs, CI workflows, deployments) for a complete architectural overview.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Components
    subgraph "External Components"
        Pools["Aave Pools/External Reserve Sources"]:::external
    end

    %% On-Chain Components
    subgraph "On-Chain Components"
        Umbrella["Umbrella Contract"]:::onchain
        StakeToken["StakeToken Contract (StataTokenV2)"]:::onchain
        Rewards["RewardsController"]:::onchain
        
        UmbrellaInterfaces["Umbrella Interfaces"]:::onchain
        StakeExtension["StataTokenV2 Extension"]:::onchain
        RewardsInterfaces["RewardsController Interfaces"]:::onchain
    end

    %% Development & Verification
    subgraph "Development & Verification"
        Foundry["Foundry"]:::dev
        Certora["Certora"]:::dev
        ForgeStd["Forge-std"]:::dev
        CICD["CI/CD Tools (Makefile,GitHubWorkflows,audits)"]:::dev
    end

    %% Connections between On-Chain Components and External Components
    Pools -->|"deficit_detection"| Umbrella
    Umbrella -->|"trigger_slashing"| StakeToken
    StakeToken -->|"reward_callback"| Rewards
    Rewards -->|"claim_reconciliation"| StakeToken

    %% Subcomponent relationships
    Umbrella -->|"interfaces"| UmbrellaInterfaces
    StakeToken -->|"extension"| StakeExtension
    Rewards -->|"interfaces"| RewardsInterfaces

    %% Connection from development tools to on-chain contracts
    CICD ---|"deploy_verify"| Umbrella

    %% Click Events for Component Mapping
    click Umbrella "https://github.com/aave-dao/aave-umbrella/tree/main/contracts/umbrella"
    click UmbrellaInterfaces "https://github.com/aave-dao/aave-umbrella/tree/main/contracts/umbrella/interfaces"
    click StakeToken "https://github.com/aave-dao/aave-umbrella/tree/main/contracts/stakeToken"
    click StakeExtension "https://github.com/aave-dao/aave-umbrella/tree/main/contracts/stakeToken/extension"
    click Rewards "https://github.com/aave-dao/aave-umbrella/tree/main/contracts/rewards"
    click RewardsInterfaces "https://github.com/aave-dao/aave-umbrella/tree/main/contracts/rewards/interfaces"

    %% Styles
    classDef onchain fill:#b3ffcc,stroke:#339966,stroke-width:2px;
    classDef dev fill:#cce5ff,stroke:#2a75bb,stroke-width:2px;
    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
```
