# vertex-protocol/vertex-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/vertex-protocol/vertex-contracts
- Repository: https://github.com/vertex-protocol/vertex-contracts

## Overview

##### Project type and purpose
- This is a DeFi smart-contract ecosystem targeting EVM chains (“Vertex Protocol”).
- It consists of two related Solidity projects:
- Core protocol contracts (clearinghouse, engine, libraries, util, interfaces)
- LBA (Liquidity Bootstrap Auction) contracts

##### File structure
- Top-level folders:
- core/ – main EVM protocol code, Hardhat config, lint, compile, contract subfolders
- lba/ – auction-specific contracts, its own Hardhat config, env.ts for .env variables
- Subfolders under core/contracts and lba/contracts separate interfaces vs implementations
- Build tooling: hardhat.config.ts in each, package.json specifying scripts, tsconfig in lba

##### README for additional insights
- Confirms the two-project split and build commands
- Emphasizes Hardhat, Yarn, Node >=16, separate workflows for compile, lint, local node

##### Detail
- Shared interface libraries in a central “common” module
- Two project roots (core vs lba) and their Hardhat configs
- Don’t omit the generation of TS bindings and ABIs as part of the build pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Toolchain
    subgraph "Developer Toolchain"
        direction TB
        Yarn["Yarn & Node.js"]:::tool
        HardhatCLI["Hardhat CLI"]:::tool
        TypeChain["TypeChain"]:::tool
        ESLintCore["ESLint Rules (Core)"]:::tool
        PrettierCore["Prettier Config (Core)"]:::tool
        ESLintIgnoreCore["ESLint Ignore (Core)"]:::tool
        ESLintLBA["ESLint Rules (LBA)"]:::tool
        ESLintIgnoreLBA["ESLint Ignore (LBA)"]:::tool
        CI["CI Workflow"]:::tool
        README["Root README & Docs"]:::tool
    end

    %% Core Module
    subgraph "Core Protocol Module"
        direction TB
        CoreHardhatConfig["Hardhat Configuration"]:::config
        CorePackage["Package & Scripts"]:::config
        subgraph "Interfaces"
            direction TB
            ClearinghouseInterfaces["Clearinghouse Interfaces"]:::onchain
            EngineInterfaces["Engine Interfaces"]:::onchain
        end
        subgraph "Implementation"
            direction TB
            CommonContracts["Common Contracts"]:::onchain
            Libraries["Libraries"]:::onchain
            UtilContracts["Utility Contracts"]:::onchain
        end
    end

    %% LBA Module
    subgraph "LBA Module"
        direction TB
        LBAHardhatConfig["Hardhat Configuration"]:::config
        LBAPackage["Package & Scripts"]:::config
        LBAtsconfig["TypeScript Configuration"]:::config
        subgraph "Contracts"
            direction TB
            LBACOntracts["Auction Contracts"]:::onchain
            LBAInterfaces["LBA-specific Interfaces"]:::onchain
        end
        LBAEnv["Environment Configuration"]:::config
    end

    %% Build & ABI Generation
    subgraph "Build Pipeline"
        direction TB
        CompileCore["Hardhat Compile (Core)"]:::tool
        CompileLBA["Hardhat Compile (LBA)"]:::tool
        GenerateABICore["Generate ABIs & TS Bindings (Core)"]:::tool
        GenerateABILBA["Generate ABIs & TS Bindings (LBA)"]:::tool
    end

    %% Deployment Environments
    subgraph "EVM Environments"
        direction TB
        Mainnet["Ethereum Mainnet/Testnet"]:::external
        LocalNode["Local Hardhat Node"]:::external
    end

    %% Runtime Interactions
    subgraph "Runtime Interactions"
        direction TB
        ScriptsTests["Scripts/Tests"]:::tool
    end

    %% Connections
    Yarn --> HardhatCLI
    HardhatCLI --> CoreHardhatConfig
    HardhatCLI --> LBAHardhatConfig

    CoreHardhatConfig --> CompileCore
    CorePackage --> CompileCore
    CompileCore --> GenerateABICore
    GenerateABICore -->|deploy| Mainnet
    GenerateABICore -->|deploy| LocalNode

    LBAHardhatConfig --> CompileLBA
    LBAPackage --> CompileLBA
    LBAtsconfig --> CompileLBA
    CompileLBA --> GenerateABILBA
    GenerateABILBA -->|deploy| Mainnet
    GenerateABILBA -->|deploy| LocalNode

    Mainnet --> ScriptsTests
    LocalNode --> ScriptsTests
    ScriptsTests -->|JSON-RPC| Mainnet
    ScriptsTests -->|JSON-RPC| LocalNode

    %% Cross references
    LBAInterfaces --> ClearinghouseInterfaces
    LBACOntracts --> EngineInterfaces
    LBACOntracts --> Libraries

    %% Click Events
    click ClearinghouseInterfaces "https://github.com/vertex-protocol/vertex-contracts/tree/main/core/contracts/interfaces/clearinghouse"
    click EngineInterfaces "https://github.com/vertex-protocol/vertex-contracts/tree/main/core/contracts/interfaces/engine"
    click CommonContracts "https://github.com/vertex-protocol/vertex-contracts/tree/main/core/contracts/common"
    click Libraries "https://github.com/vertex-protocol/vertex-contracts/tree/main/core/contracts/libraries"
    click UtilContracts "https://github.com/vertex-protocol/vertex-contracts/tree/main/core/contracts/util"
    click CoreHardhatConfig "https://github.com/vertex-protocol/vertex-contracts/blob/main/core/hardhat.config.ts"
    click CorePackage "https://github.com/vertex-protocol/vertex-contracts/blob/main/core/package.json"
    click LBACOntracts "https://github.com/vertex-protocol/vertex-contracts/tree/main/lba/contracts"
    click LBAInterfaces "https://github.com/vertex-protocol/vertex-contracts/tree/main/lba/contracts/interfaces"
    click LBAEnv "https://github.com/vertex-protocol/vertex-contracts/blob/main/lba/env.ts"
    click LBAHardhatConfig "https://github.com/vertex-protocol/vertex-contracts/blob/main/lba/hardhat.config.ts"
    click LBAPackage "https://github.com/vertex-protocol/vertex-contracts/blob/main/lba/package.json"
    click LBAtsconfig "https://github.com/vertex-protocol/vertex-contracts/blob/main/lba/tsconfig.json"
    click ESLintCore "https://github.com/vertex-protocol/vertex-contracts/blob/main/core/.eslintrc.js"
    click PrettierCore "https://github.com/vertex-protocol/vertex-contracts/blob/main/core/.prettierrc"
    click ESLintIgnoreCore "https://github.com/vertex-protocol/vertex-contracts/blob/main/core/.eslintignore"
    click ESLintLBA "https://github.com/vertex-protocol/vertex-contracts/blob/main/lba/.eslintrc.js"
    click ESLintIgnoreLBA "https://github.com/vertex-protocol/vertex-contracts/blob/main/lba/.eslintignore"
    click CI "https://github.com/vertex-protocol/vertex-contracts/blob/main/.github/workflows/main.yml"
    click README "https://github.com/vertex-protocol/vertex-contracts/blob/main/README.md"

    %% Styles
    classDef onchain fill:#e0ffe0,stroke:#2d872d,stroke-width:1px
    classDef tool fill:#e0f0ff,stroke:#1a4580,stroke-width:1px
    classDef config fill:#fff0e0,stroke:#b35900,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#999999,stroke-width:1px
```
