# cork-technology/depeg-swap architecture

> Architecture diagram of the GitHub repository cork-technology/depeg-swap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cork-technology/depeg-swap
- Repository: https://github.com/cork-technology/depeg-swap

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer"]:::dev
    Developer -->|uses| Foundry
    Developer -->|uses| Hardhat
    Developer -->|uses| Kontrol
    Developer --> Hooks

    subgraph "Off-chain Tooling & Deployment"
        Foundry["Foundry (forge build/test)"]:::tools
        Hardhat["Hardhat (TS & ethers.js)"]:::tools
        Kontrol["Kontrol (formal verification)"]:::ci
        subgraph Ignition
            moduleCore["core.ts"]:::tools
            moduleLib["lib.ts"]:::tools
            moduleUniV2["uniV2.ts"]:::tools
        end
        Foundry --> moduleCore
        Foundry --> moduleLib
        Foundry --> moduleUniV2
        Hardhat --> scriptDeploy
    end

    scriptDeploy["deploy.ts"]:::tools

    subgraph "Testing Frameworks"
        HHTests["Hardhat/TS Tests"]:::test
        ForgeTests["Forge Tests"]:::test
        Formals["Formal Proofs"]:::ci
    end

    Foundry --> ForgeTests
    Hardhat --> HHTests
    Kontrol --> Formals

    subgraph "On-chain Smart-Contract Layer"
        MC["ModuleCore"]:::contract
        LC["LvCore"]:::contract
        AF["AssetFactory/Asset"]:::contract
        FSR["FlashSwapRouter"]:::contract
        LQ["Liquidators"]:::contract
        CP["Cow-Protocol Adapter"]:::contract
        PSM["PsmCore"]:::contract
        OC["Offchain-helpers"]:::contract
        LIB["Libraries"]:::lib

        MC --> LC
        MC --> AF
        MC --> PSM
        MC --> LQ
        LC --> AF
        FSR --> MC
        LQ --> MC
        CP --> LQ
        OC --> MC
        LIB --> MC
    end

    scriptDeploy --> FSR
    scriptDeploy --> MC

    subgraph "External Services & Protocols"
        ETH["Ethereum"]:::external
        UNI2["Uniswap V2"]:::external
        UNI4["UniV4"]:::external
        PERMIT2["Permit2"]:::external
        COW["Cow-Protocol"]:::external
    end

    FSR --> ETH
    FSR --> UNI2
    FSR --> COW
    OC --> UNI4
    OC --> PERMIT2
    LQ --> UNI2

    subgraph "CI/CD & Hooks"
        GH["GitHub Actions"]:::ci
        Hooks["Husky Hooks"]:::ci
        GH -->|run_build/test| Foundry
        GH -->|run_build/test| Hardhat
        GH -->|run_proofs| Kontrol
    end

    click MC "https://github.com/cork-technology/depeg-swap/tree/main/contracts/core"
    click LC "https://github.com/cork-technology/depeg-swap/tree/main/contracts/core/assets"
    click AF "https://github.com/cork-technology/depeg-swap/tree/main/contracts/core/assets"
    click FSR "https://github.com/cork-technology/depeg-swap/blob/main/contracts/core/flash-swaps/FlashSwapRouter.sol"
    click LQ "https://github.com/cork-technology/depeg-swap/tree/main/contracts/core/liquidators"
    click CP "https://github.com/cork-technology/depeg-swap/tree/main/contracts/core/liquidators/cow-protocol"
    click PSM "https://github.com/cork-technology/depeg-swap/blob/main/contracts/core/PsmCore.sol"
    click OC "https://github.com/cork-technology/depeg-swap/tree/main/contracts/offchain-helpers"
    click scriptDeploy "https://github.com/cork-technology/depeg-swap/blob/main/script/hardhat-scripts/deploy.ts"

    classDef contract fill:#D0E1F9,stroke:#0366d6
    classDef tools fill:#D6F5D6,stroke:#2a9d8f
    classDef test fill:#FDE2E4,stroke:#E63946
    classDef external fill:#E0E0E0,stroke:#A8A8A8
    classDef ci fill:#FFEFDB,stroke:#e29578
    classDef lib fill:#FFE4B5,stroke:#D2691E
    classDef dev fill:#ffffff,stroke:#000000
```
