How bancorprotocol/carbon-contracts works
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.