# timeless-fi/bunni-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/timeless-fi/bunni-v2
- Repository: https://github.com/timeless-fi/bunni-v2

## Overview

##### Project Type & Purpose
- This is a smart contract project focused on a decentralized exchange (DEX) concept. Its aim is to enable enhanced liquidity management (beyond Uniswap v3’s concentrated liquidity) by dynamically “shapeshifting” its liquidity.
- The README and file structure indicate that the project is a full on-chain solution that leverages multiple libraries and deployment scripts, with heavy emphasis on solidity-based core logic and testing (including Medusa fuzzing).

##### File Structure
- Top-Level Directories:
– lib: Contains external and internal libraries (e.g., v4-core, solmate, solady, clones-with-immutable-args) that offer contracts and utilities from other projects (such as Uniswap’s v4-core) to be integrated.
– src: Holds the core business logic split into subdirectories like:
▪ base – Likely foundational contracts or utilities.
▪ interfaces – Contract interfaces for external interactions.
▪ ldf and ldf/managed – Code related to liquidity distribution frameworks (LDF), possibly to manage liquidity “shapeshifting.”
▪ lib – Additional internal libraries, including components that might be shared among core contracts.
▪ periphery – Likely to include ancillary contracts (supporting trading, quoting, or routing logic).
▪ types – Common type definitions.
– script: Contains deployment and orchestration scripts (evident from DeployLibraries.s.sol, DeployCore.s.sol, etc.) used with Foundry to deploy different modules.
– test, fuzz, snapshots: Show comprehensive testing (unit tests, fuzzing setups with Medusa) and state snapshot files for regression analysis.
- Deployment files (.env.example, foundry.toml, GitHub workflows) indicate integration with CI/CD and environment setups.

##### Components
– Core DEX Contracts:
▪ BunniHub, BunniHook, BunniZone, BunniQuoter (as identified from the deployment instructions).
– Math & Logic Libraries:
▪ BunniSwapMath, RebalanceLogic, and any additional libraries (e.g., BunniHookLogic) deployed as linked libraries.
– Liquidity Distribution Framework (LDF) Components:
▪ Contracts found under src/ldf and src/ldf/managed for managing liquidity positions dynamically.
– Interfaces Layer:
▪ Contracts in src/interfaces defining the external API for interacting with the DEX.
– Periphery Components:
▪ Contracts in src/periphery, which perhaps offer user-facing functions, quoting, or routing services.
– External Dependencies:
▪ Referenced libraries from lib (e.g., v4-core, solmate, solady) which tie the project to established protocols and standards.
– Deployment & Scripting:
▪ Components from the script folder showing the order: first deploy Libraries, then LDFs, then Core, and finally the Quoter and other ancillary contracts.
– Testing & Fuzzing Tools:
▪ The fuzz folder, Medusa configuration, and test suite structure which support robustness of the implementation.

b. Relationships & Interactions:
– Indicate the interface boundaries between on-chain contracts (e.g., contracts in the “interfaces” directory) and the external front-ends or integration layers.
– Document the interaction with external packages/libraries such as Uniswap v4-core and other community libraries (as depicted in the lib folder).
– If applicable, indicate testing and fuzzing tools as separate components used during development, with noted flows from fuzz scripts to testing suites.

c. Architectural Patterns & Principles:
– Modularized Design: The separation into src, lib, and script directories demonstrates clear separation of concerns (core logic vs. libraries vs. deployment mechanics).
– Use of Linked Libraries: Highlight the use of deploy-time linking in contracts (e.g., the Foundry deployment commands reference libraries explicitly).
– Test-driven & Fuzzing-oriented Development: The presence of fuzz, Medusa, and a detailed test folder emphasizes an architecture focusing on security and correctness.

– For a full-stack on-chain project like Bunni v2, emphasize the boundary between on-chain core logic (smart contracts) and off-chain deployment/testing infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment & Scripting
    subgraph "Deployment & Scripting"
        DS["Deployment Scripts"]:::deployment
    end

    %% Testing & Fuzzing Tools
    subgraph "Testing & Fuzzing"
        TS["Testing Suite"]:::testing
        FZ["Fuzzing Tools"]:::testing
    end

    %% On-Chain Smart Contracts
    subgraph "On-Chain Smart Contracts"
        %% Core DEX Contracts
        subgraph "Core DEX Contracts"
            BH["BunniHub"]:::core
            BHH["BunniHook"]:::core
            BZN["BunniZone"]:::core
            BQ["BunniQuoter"]:::core
        end

        %% Liquidity Distribution Framework (LDF)
        subgraph "Liquidity Distribution Framework (LDF)"
            LDF["LDF Components"]:::ldf
            MLDF["Managed LDF"]:::ldf
        end

        %% Interfaces Layer
        subgraph "Interfaces"
            INT["Interface Contracts"]:::interface
        end

        %% Math & Logic Libraries
        subgraph "Math & Logic Libraries"
            ML["BunniSwapMath, RebalanceLogic, BunniHookLogic"]:::lib
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        V4["Uniswap v4-core"]:::external
        SM["solmate"]:::external
        SA["solady"]:::external
    end

    %% Relationships: Deployment triggers on-chain deployments
    DS -->|"deploys"| ML
    DS -->|"deploys"| LDF
    DS -->|"deploys"| MLDF
    DS -->|"deploys"| BH
    DS -->|"deploys"| BHH
    DS -->|"deploys"| BZN
    DS -->|"deploys"| BQ

    %% Core DEX Contracts use Math & Logic Libraries
    BH -->|"links"| ML
    BHH -->|"links"| ML
    BZN -->|"links"| ML
    BQ -->|"links"| ML

    %% Liquidity Distribution Framework interacts with Core DEX Contracts
    LDF -->|"manages"| BH
    MLDF -->|"manages"| BH
    LDF -->|"manages"| BQ
    MLDF -->|"manages"| BQ

    %% Interface layer interacts with Core DEX Contracts
    INT -->|"calls"| BH
    INT -->|"calls"| BQ

    %% External Dependencies provide foundational code for Libraries
    V4 -->|"provides"| ML
    SM -->|"provides"| ML
    SA -->|"provides"| ML

    %% Testing & Fuzzing validates deployed contracts
    TS -->|"tests"| BH
    TS -->|"tests"| BQ
    FZ -->|"fuzzes"| BH
    FZ -->|"fuzzes"| BQ

    %% Click Events
    click BH "https://github.com/timeless-fi/bunni-v2/tree/main/src/base"
    click BHH "https://github.com/timeless-fi/bunni-v2/tree/main/src/base"
    click BZN "https://github.com/timeless-fi/bunni-v2/tree/main/src/base"
    click BQ "https://github.com/timeless-fi/bunni-v2/tree/main/src/periphery"
    click ML "https://github.com/timeless-fi/bunni-v2/tree/main/src/lib"
    click LDF "https://github.com/timeless-fi/bunni-v2/tree/main/src/ldf"
    click MLDF "https://github.com/timeless-fi/bunni-v2/tree/main/src/ldf/managed"
    click INT "https://github.com/timeless-fi/bunni-v2/tree/main/src/interfaces"
    click V4 "https://github.com/timeless-fi/bunni-v2/tree/main/lib/v4-core"
    click SM "https://github.com/timeless-fi/bunni-v2/tree/main/lib/solmate"
    click SA "https://github.com/timeless-fi/bunni-v2/tree/main/lib/solady"
    click DS "https://github.com/timeless-fi/bunni-v2/tree/main/script"
    click TS "https://github.com/timeless-fi/bunni-v2/tree/main/test"
    click FZ "https://github.com/timeless-fi/bunni-v2/tree/main/fuzz"

    %% Styles
    classDef deployment fill:#bbf,stroke:#333,stroke-width:2px;
    classDef testing fill:#cfc,stroke:#333,stroke-width:2px;
    classDef core fill:#fdd,stroke:#333,stroke-width:2px;
    classDef ldf fill:#dfd,stroke:#333,stroke-width:2px;
    classDef interface fill:#ffd,stroke:#333,stroke-width:2px;
    classDef lib fill:#ddf,stroke:#333,stroke-width:2px;
    classDef external fill:#f9d,stroke:#333,stroke-width:2px;
```
