# syv-labs/surge-periphery architecture

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

- Interactive diagram: https://gitdiagram.com/syv-labs/surge-periphery
- Repository: https://github.com/syv-labs/surge-periphery

## Overview

##### Project type and purpose
- This is a periphery-layer smart-contract repository for the “Surge” automated-market-maker (AMM) protocol.
- It provides user-facing contracts (routers, position manager, quoter, NFT descriptor, etc.) and utility libraries for interacting with the core Surge pools.

##### File structure
- Top level:
- contracts/ – on-chain Solidity code subdivided into:
– base, examples, interfaces, libraries, lens
- hardhat.config.ts, package.json, tsconfig.json – Hardhat + TypeScript config
- test/ – TypeScript tests and shared fixtures
- contracts/libraries/ – reusable path-encoding, tick math, price math, safe transfer
- contracts/lens/ – off-chain “view” contracts for swap/tick data (not to be deployed on-chain)
- contracts/interfaces/ – interfaces for core protocol and external tokens
- contracts/examples/ – demo flash-swap, etc.
- tests/ – comprehensive spec files and JSON snapshots

##### README for additional insights
- Key on-chain components: SwapRouter, NonfungiblePositionManager, Quoter/V2, NFT descriptor, TickLens, PairFlash
- Off-chain tools: lens contracts, Hardhat+Waffle tests
- Design: stateless routers, ERC721-based position manager, off-chain quoter views, OZ upgradeable patterns

a. Main components
- User/Frontend (web UI or scripts)
- On-chain Periphery Contracts
– SwapRouter
– NonfungiblePositionManager (ERC721 positions)
– Quoter & QuoterV2 (view only)
– TickLens (view only)
– NonfungibleTokenPositionDescriptor (SVG/metadata)
– PairFlash example
- Core Surge Protocol Contracts (external to this repo)
– Factory, Pool, Factory hooks
- Utility Libraries (deployed as libraries or linked via Solidity)
- Off-chain Test & Simulation Layer
– Hardhat test harness, shared TS fixtures
b. Relationships and interactions
- Frontend → SwapRouter (on-chain swap calls) → Core Pools
- Frontend → PositionManager → Core Pools + ERC20 approvals + WETH9 wrapper
- Frontend/SDK → Quoter/TickLens (static calls via JSON-RPC) → Core Pools
- PositionManager → NonfungibleTokenPositionDescriptor (on-chain metadata generation)
- All periphery contracts → Library code (linked at compile time)
- Test harness → Deploy Periphery + Core mocks → run tests/specs
c. Architectural patterns & design principles
- Modular “periphery” separation from core protocol
- Stateless router pattern (no storage)
- ERC721 for NFT liquidity positions
- Off-chain “lens” contracts for gas-free data fetching
- Use of SafeMath/tick-math libraries & OZ upgradeable proxies
d. Relevant technologies & frameworks
- Solidity 0.7.6, Hardhat, Waffle, TypeScript tests
- Yarn, Prettier, snapshot testing
- OpenZeppelin upgradeable libraries
- Ethers.js (via Hardhat) for tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain Layer
    User["User / Frontend Scripts"]:::offchain
    TestHarness["Test Harness (Hardhat + Waffle)"]:::offchain

    %% Periphery Contracts
    subgraph "Periphery Contracts"
        SwapRouter["SwapRouter"]:::onchain
        NonfungiblePositionManager["NonfungiblePositionManager"]:::onchain
        Quoter["Quoter (view)"]:::onchain
        QuoterV2["QuoterV2 (view)"]:::onchain
        TickLens["TickLens (view)"]:::onchain
        NFTDescriptor["NonfungibleTokenPositionDescriptor"]:::onchain
        PairFlash["PairFlash (example)"]:::onchain
    end

    %% Utility Libraries
    subgraph "Utility Libraries"
        Path["Path"]:::library
        TickMath["TickMath"]:::library
        PriceMath["PriceMath"]:::library
        TransferHelper["TransferHelper"]:::library
    end

    %% Interfaces
    Interfaces["Interfaces"]:::library

    %% Core Protocol
    subgraph "Core Protocol"
        Factory["Factory"]:::core
        Pool["Pool"]:::core
        Hooks["Factory Hooks"]:::core
    end
    Pool --> PoolStorage[("Pool Storage")]:::storage

    %% Call Flows
    User -->|transactions| SwapRouter
    User -->|transactions| NonfungiblePositionManager
    User -->|script calls| Quoter
    User -->|script calls| QuoterV2
    User -->|script calls| TickLens

    TestHarness -->|deploys & tests| SwapRouter
    TestHarness -->|deploys & tests| NonfungiblePositionManager
    TestHarness -->|calls view| Quoter
    TestHarness -->|calls view| TickLens

    SwapRouter -->|swap transactions| Factory
    SwapRouter -->|interacts| Pool

    NonfungiblePositionManager -->|mint/burn positions| Factory
    NonfungiblePositionManager -->|interacts| Pool
    NonfungiblePositionManager -->|generates metadata| NFTDescriptor

    Quoter ---->|view static calls| Factory
    Quoter ----> Pool

    QuoterV2 ----> Factory
    QuoterV2 ----> Pool

    TickLens ----> Pool

    PairFlash -->|flash-swap| Factory
    PairFlash -->|flash-swap| Pool

    %% Library Links
    SwapRouter -.-> Path
    SwapRouter -.-> TickMath
    SwapRouter -.-> PriceMath
    SwapRouter -.-> TransferHelper

    NonfungiblePositionManager -.-> Path
    NonfungiblePositionManager -.-> TickMath
    NonfungiblePositionManager -.-> PriceMath
    NonfungiblePositionManager -.-> TransferHelper

    Quoter -.-> TickMath
    QuoterV2 -.-> TickMath
    TickLens -.-> TickMath

    %% Click Events
    click SwapRouter "https://github.com/syv-labs/surge-periphery/blob/master/contracts/base/SwapRouter.sol"
    click NonfungiblePositionManager "https://github.com/syv-labs/surge-periphery/blob/master/contracts/base/NonfungiblePositionManager.sol"
    click Quoter "https://github.com/syv-labs/surge-periphery/blob/master/contracts/base/Quoter.sol"
    click QuoterV2 "https://github.com/syv-labs/surge-periphery/blob/master/contracts/base/QuoterV2.sol"
    click TickLens "https://github.com/syv-labs/surge-periphery/blob/master/contracts/lens/TickLens.sol"
    click NFTDescriptor "https://github.com/syv-labs/surge-periphery/blob/master/contracts/base/NonfungibleTokenPositionDescriptor.sol"
    click PairFlash "https://github.com/syv-labs/surge-periphery/blob/master/contracts/examples/PairFlash.sol"
    click Path "https://github.com/syv-labs/surge-periphery/blob/master/contracts/libraries/Path.sol"
    click TickMath "https://github.com/syv-labs/surge-periphery/blob/master/contracts/libraries/TickMath.sol"
    click PriceMath "https://github.com/syv-labs/surge-periphery/blob/master/contracts/libraries/PriceMath.sol"
    click TransferHelper "https://github.com/syv-labs/surge-periphery/blob/master/contracts/libraries/TransferHelper.sol"
    click Interfaces "https://github.com/syv-labs/surge-periphery/tree/master/contracts/interfaces/"
    click TestHarness "https://github.com/syv-labs/surge-periphery/tree/master/test/"

    %% Styles
    classDef onchain fill:#e0ffe0,stroke:#2d572c,stroke-width:2px
    classDef core fill:#e0f0ff,stroke:#1c4587,stroke-width:2px
    classDef offchain fill:#fff7cc,stroke:#b8860b,stroke-width:2px
    classDef library fill:#f0f0f0,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2
    classDef storage fill:#cccccc,stroke:#333333,stroke-width:2px,stroke-dasharray: 4 2
```
