# compound-finance/compound-protocol architecture

> Architecture diagram of the GitHub repository compound-finance/compound-protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/compound-finance/compound-protocol
- Repository: https://github.com/compound-finance/compound-protocol

## Overview

##### Project Type and Purpose
- This is an open-source blockchain protocol (Compound Protocol) combined with an off-chain scenario runner and toolchain.
- On-chain: A suite of Solidity smart contracts (cTokens, Comptroller, Governance, InterestRateModels, Math libraries, etc.) that implement lending/borrowing markets on Ethereum.
- Off-chain: A Node.js–based scenario runner (REPL, DSL parser, builders, runner), deployment scripts, unit tests (Jest), integration specs (scenario folder), formal verification specs (Certora), CI/CD (CircleCI, Docker).

##### File Structure Highlights
- contracts/    → Solidity source for on-chain protocol components
- scenario/    → Scenario runner code (TypeScript), DSL grammar, parser, builders, REPL interface
- script/     → CLI scripts for compile, deploy, verify, gas reporting, scenarios
- spec/       → High-level integration (spec/scenario) and formal verification (spec/certora) tests
- tests/       → Unit and fuzz tests against contracts using Jest and Saddle
- networks/    → JSON configs and ABIs for supported Ethereum networks
- Dockerfile & .circleci/config.yml → Containerization and CI pipeline definitions
- saddle.config.js, jest.config.js, webpack.config.js → Toolchain configuration

##### Key README Insights
- Core contracts: CToken family, Comptroller, GovernorAlpha, InterestRateModel, libraries (SafeMath, Exponential, ErrorReporter).
- Off-chain tools: REPL & scenario runner, Solidity compilation via Saddle, deployment & verification via CLI scripts, integration with Certora.
- CI/CD: CircleCI badge, Docker instructions.
- Testing: yarn test (unit), yarn coverage, integration specs, formal proof specs.

a. Main Components (suggest separate on-chain vs off-chain zones):
- On-Chain Protocol Layer
- CToken contracts (CErc20, CEther)
- Comptroller (risk & collateral engine)
- Governance token (COMP) & GovernorAlpha contract
- InterestRateModel contracts
- PriceOracle & Proxy, Timelock, Unitroller, Maximillion, supporting libraries
- Off-Chain Tooling Layer
- Scenario Runner (Parser → Builder → Runner → World)
- REPL & CLI Scripts (deploy, verify, match, coverage, gasReport)
- Unit Tests (Jest + Saddle)
- Integration Specs (scenario definitions, sim folder)
- Formal Verification (Certora CVL specs)
- Infrastructure & External Services
- Ethereum Networks (Mainnet, Testnets via Infura/Ganache)
- Etherscan API (for verification)
- CI/CD (CircleCI using Docker)
- Developer environment (Node.js, Yarn/NPM, TypeScript, Webpack)

b. Relationships & Data Flows
1. Developer writes/edits Solidity in contracts/ → Saddle compiles → ABI/ bytecode.
2. Deployment scripts (script/) connect to Ethereum (via Infura or local Ganache) → deploy contracts → generate network ABIs in networks/.
3. Scenario Runner (scenario/) loads ABIs + networks config → Parser reads .pegjs grammar → Builder constructs domain objects → Runner executes transactions against a simulated chain → emits Events & Values.
4. REPL provides interactive shell connecting scenario world to live/forked networks.
5. Unit tests invoke contract methods directly via Saddle, assertions via Jest.
6. Integration specs execute high-level scenarios (spec/scenario) using scenario runner.
7. Formal specs (spec/certora) feed CVL to Certora CLI to prove contract invariants.
8. CI pipeline (CircleCI): checks out code → builds Docker image → runs lint, compile, unit tests, integration specs, coverage → publishes badges.

c. Architectural Patterns & Principles
- Separation of concerns: on-chain protocol vs off-chain tooling
- DSL-based scenario testing pipeline (pegjs parser → domain builders)
- Plugin-style scripts (script/…) for deployment, coverage, verification
- Multi-stage CI pipeline containerized in Docker
- Config-driven network abstractions (networks/*.json)

d. Relevant Technologies & Frameworks
- Solidity, OpenZeppelin-style libraries
- Saddle (Solidity compile/deploy/test)
- Jest (unit testing)
- TypeScript & Webpack (scenario runner)
- pegjs (DSL grammar)
- Certora (formal verification)
- Docker, CircleCI

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer"]:::external

    subgraph "On-Chain Protocol Layer"
        CToken["cTokens (contracts/)"]:::onchain
        Comptroller["Comptroller (contracts/Comptroller.sol)"]:::onchain
        Governance["Governance (contracts/Governance/)"]:::onchain
        Interest["InterestRateModel (contracts/)"]:::onchain
        Lens["Lens (contracts/Lens/)"]:::onchain
        Libraries["Libraries (contracts/)"]:::onchain
        Oracle["PriceOracle & Proxy (contracts/)"]:::onchain
        Timelock["Timelock & Unitroller (contracts/)"]:::onchain
    end

    subgraph "Off-Chain Tooling Layer"
        ScenarioRunner["Scenario Runner (scenario/src/)"]:::offchain
        Grammar["DSL Grammar (scenario/Grammar.pegjs)"]:::offchain
        Builders["Builders (scenario/src/Builder/)"]:::offchain
        Parser["Parser & Core Engine (scenario/src/)"]:::offchain
        REPL["REPL Interface (scenario/src/Repl.ts)"]:::offchain
        CLIScripts["CLI Scripts (script/)"]:::offchain
        UnitTests["Unit Tests (tests/)"]:::offchain
        Integration["Integration Specs (spec/scenario/)"]:::offchain
        Formal["Formal Verification Specs (spec/certora/)"]:::offchain
        Configs["Toolchain Configs (saddle.config.js, jest.config.js, scenario/webpack.config.js)"]:::offchain
        Package["Package Definitions (package.json)"]:::offchain
    end

    subgraph "Infrastructure & External Services"
        Ethereum["Ethereum Networks (networks/)"]:::infra
        Infura["Infura/Ganache Nodes"]:::infra
        Etherscan["Etherscan API"]:::infra
        Certora["Certora CLI"]:::infra
        CI["CI/CD (CircleCI)"]:::infra
        Docker["Docker"]:::infra
    end

    Developer -->|writes code| CToken
    Developer -->|writes code| ScenarioRunner

    CToken -->|compiled by Saddle| CLIScripts
    CLIScripts -->|deploys contracts| Ethereum
    ScenarioRunner -->|loads ABIs & config| Ethereum

    Grammar -->|parsed by| Parser
    Parser -->|constructs domain objects| Builders
    Builders -->|executes scenarios| ScenarioRunner
    ScenarioRunner -->|executes txs| Ethereum

    REPL -->|interacts with| Ethereum
    UnitTests -->|tests contracts| CToken
    Integration -->|runs scenarios via| ScenarioRunner
    Formal -->|proves invariants on| CToken
    Formal -->|uses| Certora

    CI -->|runs in| Docker
    Docker -->|build & test| UnitTests
    Docker -->|run integration| Integration
    Docker -->|run formal| Formal

    CLIScripts -->|uses configs| Configs
    Developer -->|manages deps| Package

    click CToken "https://github.com/compound-finance/compound-protocol/tree/master/contracts/"
    click Comptroller "https://github.com/compound-finance/compound-protocol/blob/master/contracts/Comptroller.sol"
    click Governance "https://github.com/compound-finance/compound-protocol/tree/master/contracts/Governance/"
    click Interest "https://github.com/compound-finance/compound-protocol/tree/master/contracts/"
    click Lens "https://github.com/compound-finance/compound-protocol/tree/master/contracts/Lens/"
    click Libraries "https://github.com/compound-finance/compound-protocol/tree/master/contracts/"
    click Oracle "https://github.com/compound-finance/compound-protocol/tree/master/contracts/"
    click Timelock "https://github.com/compound-finance/compound-protocol/blob/master/contracts/Timelock.sol"
    click ScenarioRunner "https://github.com/compound-finance/compound-protocol/tree/master/scenario/src/"
    click Grammar "https://github.com/compound-finance/compound-protocol/blob/master/scenario/Grammar.pegjs"
    click Builders "https://github.com/compound-finance/compound-protocol/tree/master/scenario/src/Builder/"
    click Parser "https://github.com/compound-finance/compound-protocol/blob/master/scenario/src/Parser.ts"
    click REPL "https://github.com/compound-finance/compound-protocol/blob/master/scenario/src/Repl.ts"
    click CLIScripts "https://github.com/compound-finance/compound-protocol/tree/master/script/compile"
    click UnitTests "https://github.com/compound-finance/compound-protocol/tree/master/tests/"
    click Integration "https://github.com/compound-finance/compound-protocol/tree/master/spec/scenario/"
    click Formal "https://github.com/compound-finance/compound-protocol/tree/master/spec/certora/"
    click Ethereum "https://github.com/compound-finance/compound-protocol/tree/master/networks/"
    click CI "https://github.com/compound-finance/compound-protocol/blob/master/.circleci/config.yml"
    click Docker "https://github.com/compound-finance/compound-protocol/tree/master/Dockerfile"
    click Configs "https://github.com/compound-finance/compound-protocol/blob/master/saddle.config.js"

    classDef onchain fill:#e0ffe0,stroke:#006600
    classDef offchain fill:#e0f0ff,stroke:#004080
    classDef infra fill:#ffe0b3,stroke:#cc8400
    classDef external fill:#f0f0f0,stroke:#999999
```
