uniswap-v3-architecture

name: Uniswap V3 Architecture description: This skill should be used when the user asks about "Uniswap V3 architecture", "protocol overview", "V3 vs V2 differences", "concentrated liquidity introduction", or needs a high-level understanding of how Uniswap V3 works. version: 0.1.0

Uniswap V3 Architecture

Overview

Uniswap V3 is a concentrated liquidity AMM that revolutionizes capital efficiency by allowing liquidity providers to allocate capital within specific price ranges. Unlike V2's constant product formula across the entire price curve, V3 enables LPs to concentrate liquidity where trading actually occurs.

┌─────────────────────────────────────────────────────────────────────────────┐
│                           UNISWAP V3 ARCHITECTURE                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                         PERIPHERY LAYER                              │    │
│  │  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────┐    │    │
│  │  │ NonfungiblePos   │  │   SwapRouter     │  │    Quoter      │    │    │
│  │  │    Manager       │  │                  │  │                │    │    │
│  │  │ (ERC721 wrapper) │  │ (Swap execution) │  │ (Price quotes) │    │    │
│  │  └────────┬─────────┘  └────────┬─────────┘  └────────────────┘    │    │
│  └───────────│──────────────────────│─────────────────────────────────┘    │
│              │                      │                                       │
│              │    Callbacks         │    Callbacks                          │
│              ▼                      ▼                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                          CORE LAYER                                  │    │
│  │  ┌──────────────────────────────────────────────────────────────┐   │    │
│  │  │                    UniswapV3Pool                              │   │    │
│  │  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │   │    │
│  │  │  │   slot0     │ │  Liquidity  │ │     Observations[]      │ │   │    │
│  │  │  │ sqrtPriceX96│ │  Positions  │ │     (TWAP Oracle)       │ │   │    │
│  │  │  │ tick, fee   │ │  Ticks      │ │                         │ │   │    │
│  │  │  └─────────────┘ └─────────────┘ └─────────────────────────┘ │   │    │
│  │  │                                                               │   │    │
│  │  │  mint() │ burn() │ swap() │ collect() │ flash()              │   │    │
│  │  └──────────────────────────────────────────────────────────────┘   │    │
│  │                              ▲                                       │    │
│  │                              │ deploys                               │    │
│  │  ┌──────────────────────────────────────────────────────────────┐   │    │
│  │  │                   UniswapV3Factory                            │   │    │
│  │  │         createPool(tokenA, tokenB, fee) → pool                │   │    │
│  │  └──────────────────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

V2 vs V3 Comparison

Capital Efficiency

V2: Liquidity spread across entire price curve (0 to ∞)
    ┌────────────────────────────────────┐
    │▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓│  Uniform depth
    └────────────────────────────────────┘
    $0                                  $∞

V3: Liquidity concentrated in chosen ranges
    ┌────────────────────────────────────┐
    │        ▓▓▓▓▓▓▓▓▓▓▓▓▓▓              │  Up to 4000x more
    │      ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓            │  capital efficient
    │    ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓          │
    └────────────────────────────────────┘
         [tickLower]    [tickUpper]

Key Differences

Core Contracts

UniswapV3Pool

The pool contract manages all liquidity and swap operations for a single token pair at a specific fee tier.

// Key state variables
struct Slot0 {
    uint160 sqrtPriceX96;           // Current sqrt(price) in Q64.96
    int24 tick;                      // Current tick (derived from sqrtPrice)
    uint16 observationIndex;         // Most recent oracle observation
    uint16 observationCardinality;   // Current oracle array size
    uint16 observationCardinalityNext;
    uint8 feeProtocol;              // Protocol fee configuration
    bool unlocked;                   // Reentrancy guard
}

// Immutable parameters
address public immutable factory;
address public immutable token0;
address public immutable token1;
uint24 public immutable fee;
int24 public immutable tickSpacing;
uint128 public immutable maxLiquidityPerTick;

UniswapV3Factory

Creates new pools with deterministic addresses via CREATE2.

interface IUniswapV3Factory {
    function createPool(
        address tokenA,
        address tokenB,
        uint24 fee
    ) external returns (address pool);

    function getPool(
        address tokenA,
        address tokenB,
        uint24 fee
    ) external view returns (address pool);
}

Callback Pattern

V3 uses callbacks to ensure atomic token transfers. When you call mint() or swap(), the pool calls back to your contract to receive tokens.

User Contract                    Pool Contract
     │                                │
     │──── mint(params) ─────────────>│
     │                                │ Updates state
     │                                │ Calculates amounts
     │<── uniswapV3MintCallback() ────│
     │                                │
     │ Transfer tokens to pool        │
     │                                │
     │──── [callback returns] ───────>│
     │                                │ Verifies balances
     │<─── [mint complete] ──────────│

Price and Tick System

Prices in V3 are represented as sqrt(price) in Q64.96 fixed-point format, and discretized into "ticks".

Price Formula:  price = 1.0001^tick

Tick Examples:
  tick = 0      → price = 1.0
  tick = 100    → price ≈ 1.01
  tick = -100   → price ≈ 0.99
  tick = 887272 → price ≈ 2^128 (max)

Tick Spacing by Fee:
  0.01% fee  → tickSpacing = 1
  0.05% fee  → tickSpacing = 10
  0.30% fee  → tickSpacing = 60
  1.00% fee  → tickSpacing = 200

Fee Growth Mechanism

Fees accumulate globally and are tracked per-position via fee growth accounting.

Global Fee Growth (per token):
  feeGrowthGlobal0X128  // Total fees per unit liquidity for token0
  feeGrowthGlobal1X128  // Total fees per unit liquidity for token1

Position Fee Calculation:
  feesOwed = (feeGrowthInside - feeGrowthInsideLast) × liquidity / 2^128

Oracle System

V3 pools store tick observations for on-chain TWAP calculations.

struct Observation {
    uint32 blockTimestamp;                     // When observation was recorded
    int56 tickCumulative;                      // Cumulative tick × time
    uint160 secondsPerLiquidityCumulativeX128; // Cumulative seconds/liquidity
    bool initialized;
}

// TWAP calculation
function observe(uint32[] secondsAgos)
    returns (int56[] tickCumulatives, uint160[] secondsPerLiquidityCumulatives);

// Example: Get TWAP over last hour
int24 twapTick = (tickCumulative_now - tickCumulative_1hour_ago) / 3600;
uint160 twapPrice = TickMath.getSqrtRatioAtTick(twapTick);

Periphery Contracts

NonfungiblePositionManager

Wraps V3 positions as ERC721 NFTs for easier management.

struct MintParams {
    address token0;
    address token1;
    uint24 fee;
    int24 tickLower;
    int24 tickUpper;
    uint256 amount0Desired;
    uint256 amount1Desired;
    uint256 amount0Min;
    uint256 amount1Min;
    address recipient;
    uint256 deadline;
}

function mint(MintParams calldata params)
    returns (uint256 tokenId, uint128 liquidity, uint256 amount0, uint256 amount1);

SwapRouter

Executes single and multi-hop swaps.

struct ExactInputSingleParams {
    address tokenIn;
    address tokenOut;
    uint24 fee;
    address recipient;
    uint256 deadline;
    uint256 amountIn;
    uint256 amountOutMinimum;
    uint160 sqrtPriceLimitX96;
}

function exactInputSingle(ExactInputSingleParams calldata params)
    returns (uint256 amountOut);

Reference Files

v3-core

• contracts/UniswapV3Pool.sol - Core pool implementation
• contracts/UniswapV3Factory.sol - Pool factory
• contracts/interfaces/IUniswapV3Pool.sol - Pool interface (composite)

v3-periphery

• contracts/NonfungiblePositionManager.sol - NFT position wrapper
• contracts/SwapRouter.sol - Swap execution
• contracts/lens/Quoter.sol - Price quotes

Key Architectural Decisions

1. Sqrt Price Storage: Storing sqrt(price) instead of price simplifies liquidity math
2. Q64.96 Format: 96 bits of precision for accurate calculations
3. Tick Spacing: Reduces storage by limiting initialized ticks
4. Callback Pattern: Ensures atomic operations without approvals in some cases
5. Observation Array: Ring buffer for gas-efficient oracle updates
6. CREATE2 Deployment: Deterministic pool addresses enable off-chain computation