How cork-technology/depeg-swap works
Project type and purpose
• Type: A DeFi smart-contract protocol written in Solidity, with a modular core for assets, swaps, flash-swaps, liquidators, and PSM (Peg Stability Module).
• Purpose: Enable on-chain “depeg” swap functionality and liquidations, supporting integrations with Uniswap V2, Cow-Protocol, etc., with full testing, deployment, and formal verification.
File structure
• Top-level folders:
– contracts: Solidity modules (core logic, dummy implementations, interfaces, libraries, readers, tokens, offchain-helpers).
– ignition: TypeScript deployment modules for various environments.
– script: Deployment and utility scripts (Foundry & Hardhat).
– lib: External submodules (OpenZeppelin, prb-math, permit2, uni-v2 core/periphery).
– test: Both Hardhat/TS tests and Foundry (forge) unit/integration/formal tests.
• Config & tooling:
– hardhat.config.ts, foundry.toml, remappings.txt, package.json, GitHub Actions workflow, Prettier, Husky hooks.
• Key patterns:
– Modular smart-contract architecture (separate core modules + interface adapters).
– Dual build/test environments (Foundry + Hardhat).
– Formal verification with Kontrol as a separate pipeline.
Pull README insights
• Build steps (forge install/build, optimized IR).
• Kontrol for property-based proofs.
• Standard test commands (forge test).
A. On-chain Smart-Contract Layer
1. ModuleCore – dynamic module loader
2. LvCore – vault and collateral management
3. AssetFactory/Asset – ERC-4626 wrappers
4. FlashSwapRouter – flash-swap entrypoint
5. Liquidators (Uniswap V2, Cow-Protocol submodules)
6. PsmCore – peg stability module
7. Offchain-helpers – adapters for oracles, pricing
8. Libraries (prb-math, uni-v2 math, BokkyPooBahDateTime, etc.)
B. Off-chain Tooling & Deployment
1. Foundry (forge build, forge test, ignition modules)
2. Hardhat (deployment scripts, ethers.js interactions)
3. Kontrol (formal verification build & prove)
4. Ignition modules (core.ts, uniV2.ts, lib.ts)
5. CI/CD (GitHub Actions: unit.yaml, pre-commit, pre-push hooks)
C. External Services & Protocols
1. Ethereum (Mainnet, Testnet)
2. Uniswap V2 factory & router (via interfaces)
3. Cow-Protocol on-chain contracts
4. Permit2
D. Testing Frameworks
1. Hardhat/TypeScript tests under test/contracts
2. Forge unit/integration tests under test/forge
3. Formal proofs under kontrol
Relationships and data flows
– Developer → Tooling (Foundry/Hardhat/Kontrol) → On-chain deployment
– Front-end (not in repo) or scripts → FlashSwapRouter → Core modules → External protocols
– ModuleCore ↔ dynamic modules (LvCore, PsmCore, Asset, Liquidators)
– Tests invoke contracts via Foundry/Hardhat against local EVM fork
• CI pipeline: Push → GitHub Actions → build/test → artifacts/reporting → (optionally) Kontrol proofs
Architectural patterns
• Modular plugin pattern: ModuleCore + pluggable logic modules
• Interface-library separation: clean upgradeability & reusability
• Dual build/test engines: Foundry for speed, Hardhat for TS integration
• Formal verification as a separate proof pipeline