# uniswap/v4-core architecture

> Architecture diagram of the GitHub repository uniswap/v4-core, 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/uniswap/v4-core
- Repository: https://github.com/uniswap/v4-core

## Overview

##### Project Type and Purpose
- This is a blockchain-focused smart contract project for an automated market maker protocol (AMM). Its main purpose is to manage pool logic and execution of pool actions (swaps, liquidity modifications, mint, burn, etc.) via a singleton PoolManager.
- The README emphasizes the “unlock” mechanism where integrators call the PoolManager and then execute various pool actions via an unlock callback. It also underlines the support for customizable pool hooks (callbacks before/after certain actions).

##### Analyzing the File Structure
- Top-level directories such as “src” hold the core contracts, including the PoolManager contract, interfaces, libraries (like Position.sol and Pool.sol), and test utilities.
- The “test” folder (and nested “test/js-scripts” and “test/libraries”) supports the Foundry testing framework used for simulating and verifying contract behavior.
- The “lib” directory contains external dependencies (e.g., OpenZeppelin, solmate, forge-std) which are essential for development, testing, and security.
- Configuration files (e.g., foundry.toml, echidna.config.yml) indicate testing, deployment, and auditing practices.

##### Key Components
a. Core Components:
- PoolManager Contract: The central singleton managing pool state.
- Pool Actions: Represented as individual functions like swap, modifyLiquidity, mint, burn, donate, etc., which are invoked on the PoolManager.
- Unlock Mechanism: Illustrate the “unlock” flow where the integrator initiates pool actions and later calls the unlockCallback.

b. External Interactions and Integrator Contracts:
- Callback Contracts: Display how external integrator contracts implement the IUnlockCallback interface to interact with PoolManager.
- Hook Contracts: Show optional hooks added during pool initialization that implement before/after callbacks for pool events (initialize, add liquidity, remove liquidity, swap, donate).

c. Supporting Components:
- Interfaces & Libraries: Include nodes for “interfaces” (e.g., IPoolManager, IUnlockCallback) and “libraries” (e.g., Position, Pool) showing how they support the core operations.
- Testing Suite: Although not central to the protocol execution, include a reference to the testing structure (src/test and test folders) to denote how functionalities are validated.
- External Dependencies: Optionally, indicate the integration of libraries from “lib” (like OpenZeppelin and solmate) which support security and utility functions.

##### Relationships and Interactions
- A loop or transactional flow within the unlock phase where multiple pool actions (swap, modifyLiquidity, etc.) are executed until the “delta” error condition is resolved.
- Testing interactions (e.g., test scripts simulating pool operations) if desired, though focus primarily on the core architecture.

##### Architectural Patterns and Design Principles
- Singleton Pattern: Clearly denote the PoolManager as a singular, central contract controlling state.
- Callback/Hook Pattern: Emphasize the decoupled integration points where external contracts can inject custom logic.
- Transaction Atomicity: Briefly note that operations are designed to reset state (via “delta”) at the end of an unlock, ensuring consistency within each transaction.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interactions
    subgraph "External Interactions"
        IC["Integrator Contract"]:::external
        CC["IUnlockCallback Interface"]:::external
        HC["Hook Contracts"]:::external
    end

    %% Core Contracts
    subgraph "Core Contracts"
        PM["PoolManager Contract"]:::core
        UM["Unlock Mechanism"]:::action
        PA["Pool Actions (swap,modifyLiquidity,mint,burn,donate)"]:::action
    end

    %% Supporting Components
    subgraph "Supporting Components"
        LIB["Libraries: Pool & Position"]:::support
        TS["Testing Suite"]:::support
        ED["External Dependencies"]:::support
    end

    %% Relationships
    IC -->|"calls_unlock"| PM
    PM -->|"triggers"| UM
    UM -->|"executes"| PA
    PM -->|"invokes_before/after"| HC
    PM -->|"calls_callback"| CC
    TS -->|"simulates"| PM
    PM -->|"utilizes"| LIB
    PM -->|"relies_on"| ED

    %% Click Events
    click PM "https://github.com/uniswap/v4-core/blob/main/src/PoolManager.sol"
    click UM "https://github.com/uniswap/v4-core/blob/main/src/PoolManager.sol"
    click PA "https://github.com/uniswap/v4-core/blob/main/src/PoolManager.sol"
    click CC "https://github.com/uniswap/v4-core/tree/main/src/interfaces/callback"
    click HC "https://github.com/uniswap/v4-core/tree/main/src/interfaces/external"
    click LIB "https://github.com/uniswap/v4-core/tree/main/src/libraries"
    click TS "https://github.com/uniswap/v4-core/tree/main/test"
    click ED "https://github.com/uniswap/v4-core/tree/main/lib"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1565c0,stroke-width:2px;
    classDef external fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef action fill:#f8bbd0,stroke:#c2185b,stroke-width:2px;
    classDef support fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;
```
