# derivexyz/v1-core architecture

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

- Interactive diagram: https://gitdiagram.com/derivexyz/v1-core
- Repository: https://github.com/derivexyz/v1-core

## Overview

##### Project type and purpose
- This is an on-chain derivatives protocol SDK written in Solidity, with a TypeScript Hardhat wrapper (“TestSystem”) for deployment, seeding, and integration testing.
- It exposes core option-market functionality (boards, strikes, open/close, settlement), liquidity pools, Greek caching, collateral management, and periphery adapters (GMX, SNX, Uniswap, Chainlink).

##### File-structure analysis
- Root: Hardhat config (hardhat.config.ts), package.json, tsconfig.json.
- /contracts: Solidity modules split into:
– core (OptionMarket, OptionGreekCache, OptionToken, ShortCollateral, LiquidityPool, SynthetixAdapter, PerpsV2Adapter)
– periphery wrappers/adapters (LyraAdapter, GWAVOracle, MultistepSwapper)
– governance-wrapper modules (GMX, SNX)
– interfaces (GMX, perpsV2) & libraries (BlackScholes, GWAV, Maths)
- /deployments: network-specific deployment manifests (mainnet-ovm, goerli-arbi, local, etc.)
- /scripts: TS scripts for deploy, seed, governance wraps, integration tests, and utility functions
- /test: Mocha/Chai integration & unit tests organized per contract module
- /test/utils: helper functions for fixtures, price mocks, event parsing
- /examples: sample deploy & interaction scripts

##### README insights
- The project publishes an NPM SDK (“@lyrafinance/protocol”) that a user imports into their contract or test harness.
- TestSystem.deploy() and .seed() spin up a full Lyra market on Hardhat.
- Guides for local, goerli-ovm, mainnet-ovm deployments and integration tests.

a. Main components:
1. Developer/Test Harness (TypeScript + Hardhat + TestSystem SDK)
2. Deployment layer (Hardhat Runtime Environment + Ethers.js)
3. On-chain Smart Contracts:
- Core modules: OptionMarket, OptionGreekCache, OptionToken, ShortCollateral, LiquidityPool
- Periphery: LyraAdapter, GWAVOracle, MultistepSwapper, KeeperHelper
- Governance wrappers: GMXWrapper, SNXWrapper
- External-protocol adapters: GMXAdapter, SynthetixAdapter, PerpsV2Adapter
4. External services:
- GMX protocol
- Synthetix (SNX, sETH, sUSD)
- Uniswap (for swaps)
- Chainlink oracles (price feeds)
5. Data stores: on-chain state in contract storage
6. Testing & CI: Mocha/Chai tests, Slither static analysis, GitHub Actions

b. Relationships & data flows:
- TS Scripts → deploy & seed → Contract factory calls → On-chain deployment
- TestSystem SDK → calls contract functions (openPosition, deposit, hedge, settle)
- Core modules inter-call each other: OptionMarket reads GreekCache, issues OptionToken, interacts with ShortCollateral & LiquidityPool
- Periphery adapters wrap core calls (multistep swaps, external integrations)
- Governance wrappers trigger upgrades or parameter tweaks on core modules
- Contracts call external protocols: e.g. GMXAdapter routes trades/liquidity on GMX, SynthetixAdapter routes collateral on Synthetix, Uniswap via MultistepSwapper
- Oracle modules fetch prices from Chainlink or GWAV feed

c. Architectural patterns & principles:
- Modular, pluggable smart-contract architecture (core vs periphery vs governance vs adapters)
- Facade pattern in periphery wrappers (simplify group calls)
- Adapter pattern for external protocols (GMXAdapter, SynthetixAdapter, PerpsV2Adapter)
- Dependency Injection via TestSystem for seamless testing & seeding
- Single-responsibility modules (each contract focuses on one domain)

d. Key technologies:
- Solidity (contracts)
- Hardhat + TypeScript (deployment, tests, SDK)
- Ethers.js (contract interfacing)
- Mocha/Chai (tests)
- Slither (static analysis)
- GMX, Synthetix, Uniswap, Chainlink integrations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain Components
    subgraph "Off-chain Components"
        direction TB
        scriptsDir["scripts/"]:::offchain
        examplesDir["examples/"]:::offchain
        deployTS["deployTestSystem.ts"]:::offchain
        deployTSGMX["deployTestSystemGMX.ts"]:::offchain
    end

    %% Deployment Layer
    subgraph "Deployment Layer" 
        direction TB
        HHConfig["hardhat.config.ts"]:::offchain
        deployScriptsDir["scripts/deploy/"]:::offchain
        deployGMX["deployGMXContracts.ts"]:::offchain
        deploySNX["deploySNXContracts.ts"]:::offchain
    end

    %% On-chain Core Contracts
    subgraph "Core Smart Contracts"
        direction TB
        OM["OptionMarket.sol"]:::core
        OGC["OptionGreekCache.sol"]:::core
        OT["OptionToken.sol"]:::core
        SC["ShortCollateral.sol"]:::core
        LP["LiquidityPool.sol"]:::core
    end

    %% Periphery Adapters & Wrappers
    subgraph "Periphery & Wrappers"
        direction TB
        LyraAd["LyraAdapter.sol"]:::periphery
        GWAV["GWAVOracle.sol"]:::periphery
        Swapper["MultistepSwapper.sol"]:::periphery
        Keeper["KeeperHelper.sol"]:::periphery
    end

    %% Governance Wrappers
    subgraph "Governance Wrappers"
        direction TB
        GMXWrap["contracts/governance-wrapper/modules/gmx/"]:::governance
        SNXWrap["contracts/governance-wrapper/modules/snx/"]:::governance
    end

    %% External Protocol Adapters
    subgraph "External Protocol Adapters"
        direction TB
        GMXAd["GMXAdapter.sol"]:::adapter
        SNXAd["SynthetixAdapter.sol"]:::adapter
        PerpsAd["PerpsV2Adapter.sol"]:::adapter
    end

    %% External Protocols & Oracles
    subgraph "External Protocols & Oracles"
        direction TB
        GMXProto["GMX Protocol"]:::external
        SNXProto["Synthetix (SNX, sETH, sUSD)"]:::external
        UniProto["Uniswap"]:::external
        Chainlink["Chainlink Oracles"]:::external
    end

    %% Deployment Manifests
    subgraph "Deployment Manifests"
        direction TB
        DeployMainnet["deployments/mainnet-ovm/"]:::manifests
        DeployGoerli["deployments/goerli-ovm/"]:::manifests
        DeployLocal["deployments/local/"]:::manifests
    end

    %% Tests & Utilities
    subgraph "Tests & CI"
        direction TB
        TestContracts["test/contracts/..."]:::tests
        TestPeriphery["test/contracts/periphery/"]:::tests
        TestIntegration["test/integration/"]:::tests
        TestUtils["test/utils/"]:::tests
        CI["GitHub Actions / Slither"]:::tests
    end

    %% Interactions
    scriptsDir -->|runs| HHConfig
    examplesDir -->|uses| HHConfig
    deployTS -->|uses| HHConfig
    deployTSGMX -->|uses| HHConfig

    HHConfig -->|executes| deployScriptsDir
    deployScriptsDir --> deployGMX
    deployScriptsDir --> deploySNX

    deployGMX -->|deploys| OM
    deployGMX --> OGC
    deployGMX --> OT
    deployGMX --> SC
    deployGMX --> LP

    deploySNX -->|deploys| OM
    deploySNX --> OGC
    deploySNX --> OT
    deploySNX --> SC
    deploySNX --> LP

    %% Runtime calls
    deployTS -->|init Market| OM
    deployTS -->|init Market| LP
    deployTS -->|seed Greeks| OGC

    %% SDK calls periphery
    deployTS --> LyraAd
    deployTS --> GWAV
    deployTS --> Swapper
    deployTS --> Keeper

    LyraAd -->|facade calls| OM
    GWAV -->|feeds| OGC
    Swapper -->|swap via| UniProto
    Keeper -->|keepers| OM

    %% Governance
    GMXWrap -->|upgrade| OM
    SNXWrap -->|upgrade| LP

    %% Adapters to external
    GMXAd -->|routes trades| GMXProto
    SNXAd -->|routes collateral| SNXProto
    PerpsAd -->|routes perps| SNXProto

    %% Core to adapters
    OM --> GMXAd
    OM --> SNXAd
    OM --> PerpsAd

    %% Oracles into core
    Chainlink -->|price feed| GWAV
    GWAV --> OGC
    OGC --> OM

    %% Testing & CI
    TestContracts -->|unit tests| OM
    TestPeriphery -->|integration tests| LyraAd
    TestIntegration -->|E2E| deployTS
    TestUtils -->|helpers| deployTS
    CI -->|runs| TestContracts
    CI --> TestPeriphery
    CI --> TestIntegration

    %% Styles
    classDef offchain fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef core fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef periphery fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef governance fill:#ffe0b2,stroke:#bf360c,color:#bf360c;
    classDef adapter fill:#ffe0b2,stroke:#ff6d00,color:#ff6d00;
    classDef external fill:#fff9c4,stroke:#f57f17,color:#f57f17;
    classDef manifests fill:#e0e0e0,stroke:#424242,color:#424242;
    classDef tests fill:#f3e5f5,stroke:#4a148c,color:#4a148c;

    %% Click Events
    click scriptsDir "https://github.com/derivexyz/v1-core/tree/master/scripts/"
    click examplesDir "https://github.com/derivexyz/v1-core/tree/master/examples/"
    click deployTS "https://github.com/derivexyz/v1-core/blob/master/test/utils/deployTestSystem.ts"
    click deployTSGMX "https://github.com/derivexyz/v1-core/blob/master/test/utils/deployTestSystemGMX.ts"
    click HHConfig "https://github.com/derivexyz/v1-core/blob/master/hardhat.config.ts"
    click deployScriptsDir "https://github.com/derivexyz/v1-core/tree/master/scripts/deploy/"
    click deployGMX "https://github.com/derivexyz/v1-core/blob/master/scripts/deploy/deployGMXContracts.ts"
    click deploySNX "https://github.com/derivexyz/v1-core/blob/master/scripts/deploy/deploySNXContracts.ts"
    click OM "https://github.com/derivexyz/v1-core/blob/master/contracts/OptionMarket.sol"
    click OGC "https://github.com/derivexyz/v1-core/blob/master/contracts/OptionGreekCache.sol"
    click OT "https://github.com/derivexyz/v1-core/blob/master/contracts/OptionToken.sol"
    click SC "https://github.com/derivexyz/v1-core/blob/master/contracts/ShortCollateral.sol"
    click LP "https://github.com/derivexyz/v1-core/blob/master/contracts/LiquidityPool.sol"
    click LyraAd "https://github.com/derivexyz/v1-core/blob/master/contracts/periphery/LyraAdapter.sol"
    click GWAV "https://github.com/derivexyz/v1-core/blob/master/contracts/periphery/GWAVOracle.sol"
    click Swapper "https://github.com/derivexyz/v1-core/blob/master/contracts/periphery/MultistepSwapper.sol"
    click Keeper "https://github.com/derivexyz/v1-core/blob/master/contracts/periphery/KeeperHelper.sol"
    click GMXWrap "https://github.com/derivexyz/v1-core/tree/master/contracts/governance-wrapper/modules/gmx/"
    click SNXWrap "https://github.com/derivexyz/v1-core/tree/master/contracts/governance-wrapper/modules/snx/"
    click GMXAd "https://github.com/derivexyz/v1-core/blob/master/contracts/synthetix/GMXAdapter.sol"
    click SNXAd "https://github.com/derivexyz/v1-core/blob/master/contracts/synthetix/SynthetixAdapter.sol"
    click PerpsAd "https://github.com/derivexyz/v1-core/blob/master/contracts/interfaces/perpsV2/PerpsV2Adapter.sol"
    click DeployMainnet "https://github.com/derivexyz/v1-core/tree/master/deployments/mainnet-ovm/"
    click DeployGoerli "https://github.com/derivexyz/v1-core/tree/master/deployments/goerli-ovm/"
    click DeployLocal "https://github.com/derivexyz/v1-core/tree/master/deployments/local/"
    click TestContracts "https://github.com/derivexyz/v1-core/tree/master/test/contracts/"
    click TestPeriphery "https://github.com/derivexyz/v1-core/tree/master/test/contracts/periphery/"
    click TestIntegration "https://github.com/derivexyz/v1-core/tree/master/test/integration/"
    click TestUtils "https://github.com/derivexyz/v1-core/tree/master/test/utils/"
```
