# bancorprotocol/carbon-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/bancorprotocol/carbon-contracts
- Repository: https://github.com/bancorprotocol/carbon-contracts

## Overview

##### Project type and purpose
- This is a decentralized protocol of Ethereum/EVM smart contracts (Carbon v1.0) for automating on-chain trading strategies (linked/ranged orders, MEV resistance, asymmetric liquidity, etc.).
- Alongside the core contracts, it includes deployment tooling (Hardhat‐Deploy), test suites (unit, nightly stress, deployment tests), helpers, and configuration for multiple networks.

##### File structure
- Top-level config: .env.example, hardhat.config.ts, foundry.toml, package.json, pnpm-lock.yaml, tsconfig.json, lint/formatter configs, GitHub workflows for CI, nightly runs, health checks.
- components/: TypeScript builders & abstractions for interacting with compiled contracts.
- contracts/: Solidity modules grouped by feature domain:
- carbon/ (CarbonController, Pairs, Strategies)
- token/ (ERC20, burnable tokens)
- fees/ (FeeBurner)
- voucher/ (Voucher)
- utility/ (math, upgradeable, proxy delegate)
- pol, vortex, voucher each with interface definitions.
- data/: named accounts and token-overrides JSON for deployment parameterization.
- deploy/: Hardhat-Deploy scripts organized by network (network vs mainnet, sequential numbered migrations) and accompanying deployment tests.
- deployments/: JSON artifacts per chain (mainnet, testnets, L2s), including proxy & implementation addresses, ABIs, typechain types.
- scripts/: ad-hoc TS scripts for maintenance tasks (enableTrading, timer).
- test/: exhaustive suites—forge tests, Hardhat tests, accuracy datasets, helpers, matchers—to validate contract logic and deployment flows.
- utils/: shared TS modules (Deploy wrappers, Logger, Roles, Time utilities, chainIds, RPC URLs).

##### Extracted insights from README
- Uses hardhat-deploy to manage deterministic, repeatable deployments and upgrades (Transparent Proxy pattern via ProxyAdmin).
- Supports multi-network deploy, verification (Etherscan), Tenderly forks, and licensed artifact publishing.
- High test coverage (99%+ statements) with nightly stress tests and deployment E2E tests.
- README outlines commands for testing, coverage, deployments, and how to configure .env.

##### Diagramming the architecture
- On-Chain Smart Contracts:
- CarbonController (strategy orchestration)
- CarbonVortex (AMM core)
- CarbonBatcher (batched trades)
- FeeBurner (fee handling)
- Voucher (reward token)
- ProxyAdmin & Transparent Proxies for upgradability
- Interfaces & Libraries: Utility contracts (MathEx, Upgradeable base, OnlyProxyDelegate)
- Off-Chain Tooling:
- Deployment Engine (Hardhat‐Deploy scripts)
- TypeScript Components (components/, utils/)
- Testing Frameworks (Forge, Hardhat tests)
- Configuration (data/, .env, named-accounts)
- External Services: Etherscan (verification), Tenderly (forks), GitHub Actions (CI, nightly).

b. Relationships & interactions
- Deployment Engine → writes JSON artifacts → on-chain ProxyAdmin & proxies → links to implementation contracts per network.
- CarbonController ↔ CarbonVortex: Controller invokes Vortex for AMM operations.
- CarbonBatcher calls Controller and Vortex to batch trades.
- FeeBurner hooked into Controller/Vortex to collect & burn fees.
- Voucher contract mints/burns reward tokens during trades.
- Off-chain components utilize TypeChain bindings to read/write contract state.
- Tests simulate on-chain flows via local Hardhat/Forked network.

c. Architectural patterns & principles
- Modular Solidity code organized by domain (separation of concerns).
- Transparent Proxy upgradability via ProxyAdmin.
- Hardhat-Deploy’s named deployments and fixture migrations.
- Test-first development with extensive coverage.
- CI/CD via GitHub Actions ensuring health, nightly stress, coverage.

d. Key technologies & frameworks
- Solidity (contracts), Hardhat & Hardhat-Deploy (deployments/tests), Forge (additional tests), TypeScript (scripts/components), pnpm (package manager), Etherscan API, Tenderly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% On-Chain Layer
    subgraph "On-Chain Smart Contracts"
        direction TB
        CC["CarbonController"]:::contract
        CV["CarbonVortex"]:::contract
        CB["CarbonBatcher"]:::contract
        FB["FeeBurner"]:::contract
        VCH["Voucher"]:::contract
        subgraph "Utility Libraries"
            direction TB
            ME["MathEx"]:::library
            UP["Upgradeable"]:::library
            PD["OnlyProxyDelegate"]:::library
        end
    end

    %% Proxies & Admin Layer
    subgraph "Upgradability"
        direction TB
        PA["ProxyAdmin"]:::proxy
        TP["TransparentProxies"]:::proxy
    end

    %% Artifacts Storage
    ART["Deployments Artifacts"]:::artifacts

    %% Off-Chain Tooling Layer
    subgraph "Off-Chain Tooling"
        direction TB
        DE["Deployment Engine"]:::tool
        CM["TypeScript Components"]:::tool
        UT["Shared Utilities & Configs"]:::tool
        DP["Deployment Parameters"]:::tool
        MS["Maintenance Scripts"]:::tool
        subgraph "Testing Frameworks"
            direction TB
            HH["Hardhat Tests"]:::test
            FG["Forge Tests"]:::test
            DT["Deployment Tests"]:::test
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        ES["Etherscan"]:::external
        TL["Tenderly"]:::external
        GH["GitHub Actions"]:::external
    end

    %% Relationships
    DE -->|deploys via| PA
    PA -->|manages| TP
    TP -->|points to| CC
    TP -->|points to| CV
    TP -->|points to| CB
    CC -->|"orchestrates"| CV
    CB -->|"batches calls to"| CC
    CB -->|"batches calls to"| CV
    CC -->|"collects fees via"| FB
    CV -->|"burn fees via"| FB
    CC -->|"mints rewards via"| VCH
    CV -->|"utilizes libraries"| ME
    CC -->|"inherits from"| UP
    CC -->|"guarded by"| PD
    CM -->|interacts with| CC
    CM -->|interacts with| CV
    CM -->|interacts with| CB
    CM -->|interacts with| FB
    CM -->|interacts with| VCH
    UT -->|provides| CM
    DP -->|parameters for| DE
    MS -->|run maintenance| CC
    MS -->|run maintenance| CV
    DE -->|writes| ART
    DT -->|validates deployments in| ART
    HH -->|tests contracts via| CM
    FG -->|tests contracts via| CM
    GH -->|triggers| HH
    GH -->|triggers| FG
    GH -->|triggers| DT
    GH -->|runs health| GH

    ES -->|verifies on-chain| ART
    TL -->|forks network for| HH

    %% Click Events
    click CC "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/carbon/CarbonController.sol"
    click CV "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/vortex/CarbonVortex.sol"
    click CB "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/carbon/CarbonBatcher.sol"
    click FB "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/helpers/FeeBurner.sol"
    click VCH "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/voucher/Voucher.sol"
    click PA "https://github.com/bancorprotocol/carbon-contracts/blob/dev/deploy/scripts/network/0001-ProxyAdmin.ts"
    click PA "https://github.com/bancorprotocol/carbon-contracts/blob/dev/deployments/mainnet/types/@openzeppelin/contracts/proxy/transparent/ProxyAdmin.ts"
    click ME "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/utility/MathEx.sol"
    click UP "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/utility/Upgradeable.sol"
    click PD "https://github.com/bancorprotocol/carbon-contracts/blob/dev/contracts/utility/OnlyProxyDelegate.sol"
    click DE "https://github.com/bancorprotocol/carbon-contracts/tree/dev/deploy/"
    click DT "https://github.com/bancorprotocol/carbon-contracts/tree/dev/deploy/tests/network"
    click DT "https://github.com/bancorprotocol/carbon-contracts/tree/dev/deploy/tests/mainnet"
    click ART "https://github.com/bancorprotocol/carbon-contracts/tree/dev/deployments/"
    click CM "https://github.com/bancorprotocol/carbon-contracts/blob/dev/components/ContractBuilder.ts"
    click CM "https://github.com/bancorprotocol/carbon-contracts/blob/dev/components/Contracts.ts"
    click UT "https://github.com/bancorprotocol/carbon-contracts/blob/dev/utils/Constants.ts"
    click UT "https://github.com/bancorprotocol/carbon-contracts/blob/dev/utils/Deploy.ts"
    click UT "https://github.com/bancorprotocol/carbon-contracts/blob/dev/utils/Logger.ts"
    click UT "https://github.com/bancorprotocol/carbon-contracts/blob/dev/utils/Roles.ts"
    click UT "https://github.com/bancorprotocol/carbon-contracts/blob/dev/utils/Time.ts"
    click UT "https://github.com/bancorprotocol/carbon-contracts/blob/dev/utils/rpcUrls.json"
    click UT "https://github.com/bancorprotocol/carbon-contracts/blob/dev/utils/chainIds.json"
    click DP "https://github.com/bancorprotocol/carbon-contracts/blob/dev/data/named-accounts.ts"
    click DP "https://github.com/bancorprotocol/carbon-contracts/blob/dev/data/token-overrides.json"
    click MS "https://github.com/bancorprotocol/carbon-contracts/blob/dev/scripts/enableTrading.ts"
    click MS "https://github.com/bancorprotocol/carbon-contracts/blob/dev/scripts/timer.ts"
    click HH "https://github.com/bancorprotocol/carbon-contracts/tree/dev/test/"
    click FG "https://github.com/bancorprotocol/carbon-contracts/tree/dev/test/forge"
    click DE "https://github.com/bancorprotocol/carbon-contracts/blob/dev/hardhat.config.ts"
    click DE "https://github.com/bancorprotocol/carbon-contracts/blob/dev/foundry.toml"
    click DE "https://github.com/bancorprotocol/carbon-contracts/blob/dev/.env.example"
    click GH "https://github.com/bancorprotocol/carbon-contracts/blob/dev/.github/workflows/ci.yml"
    click GH "https://github.com/bancorprotocol/carbon-contracts/blob/dev/.github/workflows/health.yml"
    click GH "https://github.com/bancorprotocol/carbon-contracts/blob/dev/.github/workflows/nightly.yml"

    %% Styles
    classDef contract fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef proxy fill:#F3D0FF,stroke:#8A2BE2,color:#8A2BE2
    classDef library fill:#E8F0C8,stroke:#6A994E,color:#6A994E
    classDef tool fill:#DFFFE0,stroke:#00A152,color:#00A152
    classDef artifacts fill:#FFF5BA,stroke:#FFB200,color:#FFB200
    classDef test fill:#FFE0D0,stroke:#FF4500,color:#FF4500
    classDef external fill:#FFE8D0,stroke:#FF8C00,color:#FF8C00
```
