# originprotocol/origin-dollar architecture

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

- Interactive diagram: https://gitdiagram.com/originprotocol/origin-dollar
- Repository: https://github.com/originprotocol/origin-dollar

## Overview

##### Project type & purpose
- This is a DeFi smart-contract monorepo for Origin Dollar (OUSD) and Origin Ether (OETH). It hosts on-chain business logic (vaults, tokens, strategies), multi-network deployment configs, on-chain verification (Certora, Slither), and off-chain automation (Hardhat tasks, Brownie scripts).

##### File-structure analysis
- Top-level:
- contracts/ – Solidity code, Hardhat config, deployments, docs, tests, tasks
- brownie/ – Python/Brownie scripts, ABI imports, allocations, world-state abstractions, tests
- certora/ – formal-verification specs & run scripts
- CI/CD (.github/workflows)
- Patterns:
- “contracts/contracts” by area: vault, strategies, governance, oracles, mocks
- “deployments” per network: mainnet, base, plume, sonic, holesky
- Hardhat tasks for daily ops, defender-actions, governance proposals
- Storage-layout snapshots for upgrade safety

a. Main components
1) On-chain core modules: VaultCore, VaultAdmin, Token contracts (OUSD/OETH/WOETH), Strategy modules, OracleRouter, Harvester, Dripper, Buyback, BridgeHelper, Zapper
2) Deployment & upgrade system: Hardhat + network configs + migrations vs Brownie scripts + Python world abstractions
3) Off-chain automation:
– Hardhat tasks & Defender-actions (JS/TS)
– Brownie harvest/allocation scripts (Python)
– Certora engine for invariant checks
– Slither static analyzer
4) External blockchains & services: Ethereum mainnet fork (Infura/Alchemy), Uniswap/Curve/Sushi on-chain protocols, Chainlink oracles, Aave/Morpho, CCIP
5) CI/CD pipelines (.github/workflows)
b. Relationships & interactions
– Off-chain tasks & scripts invoke Hardhat RPC (forked node) to call/deploy contracts
– Contracts call oracles & other DeFi protocols on-chain
– CI/CD triggers tests, lint, verification, and deployment on merge
– Certora & Slither scan contracts pre-merge
c. Architectural patterns
– Proxy/upgradable pattern (many “Proxy” contracts)
– Modular strategy plugins (4626-style)
– Governance timelocks & safe-modules for permissioned operations
– Forked development node for stateful integration tests
d. Key tech
– Solidity, Hardhat, Brownie (Python), PlantUML, Certora Specs, Slither, GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% On-chain Contracts
    subgraph "On-Chain Core Modules"
        direction TB
        VaultCore["VaultCore"]:::onchain
        VaultAdmin["VaultAdmin"]:::onchain
        OUSD["OUSD"]:::onchain
        OETH["OETH"]:::onchain
        WOETH["WOETH"]:::onchain
        subgraph "Strategies"
            direction TB
            NativeStaking["NativeStaking"]:::onchain
            Aerodrome["Aerodrome"]:::onchain
            Balancer["Balancer"]:::onchain
            Plume["Plume"]:::onchain
            Sonic["Sonic"]:::onchain
        end
        OracleRouter["OracleRouter"]:::onchain
        Harvester["Harvester"]:::onchain
        Dripper["Dripper"]:::onchain
        Buyback["Buyback"]:::onchain
        BridgeHelper["BridgeHelper"]:::onchain
        Zapper["Zapper"]:::onchain
    end

    %% Deployment & Upgrade Systems
    subgraph "Deployment & Upgrade"
        direction TB
        subgraph "Hardhat"
            HHDeployScripts["JS Migration Scripts"]:::infra
            HHArtifacts["Deployment Artifacts"]:::infra
        end
        subgraph "Brownie"
            BrownieScripts["Python Scripts"]:::infra
            WorldState["World-State Abstractions"]:::infra
        end
    end

    %% Off-Chain Automation & Verification
    subgraph "Off-Chain Automation & Verification"
        direction TB
        HardhatTasks["Hardhat Tasks"]:::tools
        DefenderActions["Defender Actions"]:::tools
        BrownieHarvest["Brownie Harvest Scripts"]:::tools
        Certora["Certora Specs & Engine"]:::tools
        Slither["Slither Static Analyzer"]:::tools
    end

    %% CI/CD & Docs
    subgraph "CI/CD & Documentation"
        direction TB
        CICD["GitHub Workflows"]:::tools
        PlantUML["PlantUML Diagrams"]:::docs
        StorageLayout["Storage Layout Snapshots"]:::infra
    end

    %% External Services
    subgraph "External Protocols & Services"
        direction TB
        EthNode["Ethereum Node (Infura/Alchemy)"]:::external
        Uniswap["Uniswap/Curve/Sushi"]:::external
        Chainlink["Chainlink Oracles"]:::external
        Aave["Aave/Morpho"]:::external
        CCIP["CCIP"]:::external
    end

    %% Relationships
    HardhatTasks -->|"calls RPC"| EthNode
    DefenderActions -->|"calls RPC"| EthNode
    BrownieHarvest -->|"calls RPC"| EthNode

    HardhatTasks --> VaultCore
    BrownieHarvest --> VaultCore

    VaultCore -->|calls| OracleRouter
    VaultCore -->|interacts| Harvester
    VaultCore -->|interacts| Dripper
    VaultCore -->|calls| Buyback
    VaultCore -->|calls| BridgeHelper
    VaultCore -->|calls| Zapper
    VaultCore -->|uses| Strategies

    OracleRouter --> Chainlink
    VaultCore --> Uniswap
    VaultCore --> Aave

    HHDeployScripts --> VaultCore
    BrownieScripts --> VaultCore

    CICD --> Slither
    CICD --> Certora
    CICD --> HHDeployScripts

    PlantUML --> VaultCore

    %% Click Events
    click VaultCore "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/vault/VaultCore.sol"
    click VaultAdmin "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/vault/VaultAdmin.sol"
    click OUSD "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/token/OUSD.sol"
    click OETH "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/token/OETH.sol"
    click WOETH "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/token/WOETH.sol"
    click NativeStaking "https://github.com/originprotocol/origin-dollar/tree/master/contracts/contracts/strategies/NativeStaking"
    click Aerodrome "https://github.com/originprotocol/origin-dollar/tree/master/contracts/contracts/strategies/aerodrome"
    click Balancer "https://github.com/originprotocol/origin-dollar/tree/master/contracts/contracts/strategies/balancer"
    click Plume "https://github.com/originprotocol/origin-dollar/tree/master/contracts/contracts/strategies/plume"
    click Sonic "https://github.com/originprotocol/origin-dollar/tree/master/contracts/contracts/strategies/sonic"
    click OracleRouter "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/oracle/OracleRouter.sol"
    click Harvester "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/harvest/Harvester.sol"
    click Dripper "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/harvest/Dripper.sol"
    click Buyback "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/buyback/Buyback.sol"
    click BridgeHelper "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/bridges/BridgeHelperModule.sol"
    click Zapper "https://github.com/originprotocol/origin-dollar/blob/master/contracts/contracts/zapper/Zapper.sol"
    click HHDeployScripts "https://github.com/originprotocol/origin-dollar/tree/master/contracts/deploy"
    click HHArtifacts "https://github.com/originprotocol/origin-dollar/tree/master/contracts/deployments"
    click BrownieScripts "https://github.com/originprotocol/origin-dollar/tree/master/brownie/scripts"
    click WorldState "https://github.com/originprotocol/origin-dollar/blob/master/brownie/world*.py"
    click HardhatTasks "https://github.com/originprotocol/origin-dollar/tree/master/contracts/tasks"
    click DefenderActions "https://github.com/originprotocol/origin-dollar/tree/master/contracts/scripts/defender-actions"
    click BrownieHarvest "https://github.com/originprotocol/origin-dollar/tree/master/brownie/scripts"
    click Certora "https://github.com/originprotocol/origin-dollar/tree/master/certora/specs"
    click Slither "https://github.com/originprotocol/origin-dollar/blob/master/contracts/slither.config.json"
    click CICD "https://github.com/originprotocol/origin-dollar/tree/master/.github/workflows"
    click PlantUML "https://github.com/originprotocol/origin-dollar/tree/master/contracts/docs/plantuml"
    click StorageLayout "https://github.com/originprotocol/origin-dollar/tree/master/contracts/storageLayout"

    %% Styles
    classDef onchain fill:#D0E8FF,stroke:#0B4F6C,color:#0B4F6C
    classDef infra fill:#E8F4D0,stroke:#4F6C0B,color:#4F6C0B
    classDef tools fill:#D0F0E8,stroke:#0B6C4F,color:#0B6C4F
    classDef external fill:#FFE8D0,stroke:#6C0B0B,color:#6C0B0B
    classDef docs fill:#F0D0FF,stroke:#6C0B6C,color:#6C0B6C
```
