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 | Feature | V2 | V3 | |---------|-----|-----| | Liquidity range | Full curve (0 to ∞) | Custom tick ranges | | LP tokens | Fungible ERC20 | Non-fungible ERC721 | | Fee tiers | Single (0.3%) | Multiple (0.01%, 0.05%, 0.3%, 1%) | | Capital efficiency | 1x | Up to 4000x | | Oracle | Cumulative price | Cumulative tick (more robust) | | Position composability | Limited | Full NFT composability | ## Core Contracts ### UniswapV3Pool The pool contract manages all liquidity and swap operations for a single token pair at a specific fee tier. ```solidity // 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. ```solidity 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. ```solidity 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. ```solidity 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. ```solidity 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