How compound-finance/compound-protocol works
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