## Understanding the Uniswap v4 Architecture: A High-Level Overview Uniswap v4 introduces a powerful and modular architecture designed for enhanced efficiency, flexibility, and extensibility. This new design is built upon a layered system distributed across three primary GitHub repositories: `v4-core`, `v4-periphery`, and `universal-router`. Understanding the role of each repository and how their key contracts interact is fundamental to developing on or interacting with the protocol. This lesson provides a high-level architectural overview, breaking down each component and illustrating how they work together to facilitate token swaps and liquidity management. ## The `v4-core` Repository: The Singleton PoolManager At the heart of Uniswap v4 lies the `v4-core` repository. This repository contains the protocol's essential logic and is home to its single most important smart contract: the `PoolManager`. The `PoolManager` is a "singleton" contract, meaning only one instance of it will be deployed on a given blockchain. It serves as the central hub and ultimate source of truth for the entire protocol. Its primary responsibilities include: - **Asset Custody:** The `PoolManager` acts as the vault for all assets within Uniswap v4. All user-deposited tokens are held and locked within this single contract, a significant departure from previous versions where each pool was its own contract. - **Core Logic Execution:** It contains the fundamental logic required to execute swaps and manage liquidity positions. All calculations, state changes, and token transfers are ultimately handled by the `PoolManager`. - **Liquidity Management:** It tracks and manages all liquidity positions across every pool in the protocol. Crucially, the `PoolManager` is not designed for direct interaction by end-users. Its interface is complex and optimized for communication with other smart contracts, not for human-readable transactions. This design choice enhances security and protocol integrity by creating a clear boundary between core logic and user-facing interactions. ## The `v4-periphery` Repository: Interacting with the Core The `v4-periphery` repository provides a necessary abstraction layer between the user and the `v4-core`. It contains a collection of helper and intermediary contracts that offer a safer, more user-friendly way to interact with the powerful but restricted `PoolManager`. The two key contracts in this repository are: 1. **`V4Router`:** This contract is dedicated to handling token swaps. It provides the necessary functions to facilitate both simple single-hop swaps (e.g., WETH to USDC) and complex multi-hop swaps (e.g., WETH to DAI to USDC). When a user initiates a swap through this router, it translates the request into the appropriate low-level calls required by the `PoolManager`. 2. **`PositionManager`:** This contract is the primary interface for liquidity providers (LPs). It simplifies the process of adding, modifying, and removing liquidity from pools. Just like the `V4Router`, it acts as an intermediary, taking user-friendly inputs and communicating them securely to the `PoolManager` to manage liquidity positions. ## The `universal-router` Repository: A Gateway to All Versions The `universal-router` repository represents the highest level of abstraction, providing a single, unified entry point for users. Its purpose is to streamline the user experience by enabling interactions not just with Uniswap v4, but with previous versions of the protocol as well. The key contract here is the **`V4SwapRouter`**. This contract is designed to provide the best possible trade execution by intelligently routing swaps across multiple Uniswap versions. For example, a user looking to trade WETH for USDC could have their order split and routed through pools on Uniswap V2, V3, and V4 simultaneously to achieve the optimal price. This universal entry point simplifies the swapping process for users and aggregators, who no longer need to manage interactions with multiple distinct router contracts. ## How It All Works Together: A Typical Swap Flow The layered architecture of Uniswap v4 becomes clear when tracing the path of a typical transaction. The flow ensures a separation of concerns, where each layer has a distinct responsibility. For a standard token swap, the interaction chain is as follows: 1. **User to Universal Router:** A user initiates a swap by calling a function on the `V4SwapRouter` contract. 2. **Universal Router to Periphery:** The `V4SwapRouter` processes the request and, for the V4 portion of the trade, calls the appropriate function on the `V4Router` contract in the periphery. 3. **Periphery to Core:** The `V4Router` communicates the validated and formatted swap details to the `PoolManager` contract. 4. **Core Execution:** The `PoolManager` executes the core swap logic, performs the required token transfers within its own vault, and finalizes the transaction. This can be summarized as: `User` → `V4SwapRouter` → `V4Router` → `PoolManager` Similarly, a liquidity provider would interact through a parallel flow: `Liquidity Provider` → `PositionManager` → `PoolManager` This modular, layered design makes Uniswap v4 more secure, organized, and easier to build upon, with clear entry points for users and distinct responsibilities for each component of the system.