Uniswap v4 Architecture: Understanding the Basics of the Protocol

Now let's see how pool creation works in the fourth version.

To create a new pool, the initialize() function is called on the PoolManager.sol smart contract. Information about the created pool is stored in the state of the pool manager smart contract.

At the same time, user operations, such as various types of swaps, go through the V4Router.sol smart contract, but all the low-level logic for processing operations on the pool takes place in the Pool.sol library, which is used by PoolManager.sol.

The singleton architecture provides significant gas savings, as creating a new pool only requires updating the state instead of deploying a new pool smart contract. Also, swapping through a chain of pools no longer requires physically transferring tokens through intermediate pools, which greatly reduces gas costs.

The protocol continues its tradition of splitting the codebase into two repositories, similar to previous versions:

• v4-core.
• v4-periphery.

Core is still responsible for pools, while periphery handles routing to the pools. There are also many additional smart contracts that, in one way or another, implement the logic of pools, the router, the LP token, and the mathematics.

The diagram below shows the list of smart contracts in the two repositories.

I’ve listed the names of the main smart contracts divided into 4 groups:

• Blue indicates the main smart contracts that implement the core protocol logic.
• Orange indicates smart contracts that are libraries.
• Pink indicates auxiliary smart contracts intended only for reading data from the blockchain.
• Green indicates auxiliary smart contracts. In our case, we have identified only the smart contract that describes the minimal hook logic.

The larger the smart contract name, the more important it is in the Uniswap code. There are several such smart contracts in the diagram:

• PoolManager.sol. The primary smart contract from the core group that manages token pools.
• V4Router.sol. A smart contract from the periphery group that is responsible for the initial processing of user operations before sending the call to the core group smart contracts.
• PositionManager.sol. A smart contract from the periphery group that is responsible for adding/removing liquidity and implementing the LP token (NFT) that represents a liquidity provider’s position. This is the entry point for the liquidity provider, allowing them to manage liquidity on the PoolManager.sol smart contract.

The PoolManager.sol smart contract implements the following functionality:

• modifyLiquidity(). Liquidity management function: adding, removing, and modifying liquidity. This function is usually called by the liquidity provider, but not directly — instead, through the PositionManager.sol smart contract.
• swap(). Asset swapping. This function is usually called by the user, but not directly — instead, through the V4Router.sol smart contract.
• donate(). Direct donations to liquidity providers. This is a way to increase liquidity in the pool bypassing the liquidity provider mechanism.
• mint()/burn(). Minting and burning ERC-6909 tokens, which confirm the presence of a user's assets in the protocol. After a swap, you can choose not to withdraw the token but instead mint its equivalent in ERC-6909. Minting ERC-6909 is always cheaper in gas than transferring any token.
• take()/settle(). Functions for borrowing and repaying assets. Used for flash loans and more. Allows taking assets from the pool as a loan and repaying them.
• sync(). For synchronizing the pool’s state with its current token reserves and price.

Storage Variables

The pool manager has acquired a neat mapping for managing multiple pools.

PoolId is a unique pool identifier, which is actually a bytes32. Essentially, the identifier is a hash of the pool parameters. To obtain the id, the PoolIdLibrary library is used, with a single function toId().

Pool.State is the entire current state of the pool — we’ll take a look at it a bit later.

PoolManager.sol also has two constants in storage that define the minimum and maximum tick boundaries.

All other storage variables are tucked away in the smart contracts that PoolManager.sol inherits from.

What PoolManager Inherits From

• NoDelegateCall.sol. Protection against delegated calls. Safeguards the unlock mechanism. When a callback is made, it’s not possible to execute the logic of another smart contract. In other words, delegateCall to PoolManager is prohibited for security reasons.
• ERC6909Claims.sol. Allows minting and burning a token equivalent to the user’s assets left inside the protocol.
• Extsload.sol and Exttload.sol. Allows the TransientStateLibrary.sol library to read and write data to temporary storage. The library itself is used from outside the core group smart contracts. It is used for intermediate calculations.

But that’s not all — if we recall the screenshot with the repository smart contracts, it showed a lot of logic moved into libraries.

In fact, there are many more libraries. But the most interesting one is the Pool.sol smart contract. This library handles all operations that can be applied to a pool: from modifying a liquidity provider’s position to swapping and changing tick information.

Pool.sol defines the state structure of the pool. We promised to take a look at the state structure earlier.

After that, you should get familiar with the libraries:

• StateLibrary.sol. Helps retrieve data from Slot0. Not used directly in PositionManager.sol, but clearly shows the structure of Slot0.
• Position.sol. Responsible for operations with liquidity providers’ positions.
• TickBitmap.sol and TickMath.sol. Auxiliary libraries for working with ticks.
• SwapMath.sol. Helps calculate swap results.
• Hooks.sol. Executes the hook logic: validation and execution.

These were the main libraries necessary for understanding; the rest can be explored in the code as needed.

In this section, we’ll break down the transaction call flow from the moment it’s sent by the user to its final execution on the smart contracts. All users can be conditionally divided into two types:

• A liquidity provider who supplies assets to an abstract token pool.
• A regular user performing a swap from one asset to another.

Each type of user will have a different entry point.

Liquidity providers must interact with the PositionManager.sol smart contract, which processes the operation data and forwards it to the pool manager smart contract.

Regular users use V4Router.sol, which processes the operation data and forwards it to the pool manager smart contract.

Both entry points, logically, inherit from the BaseActionsRouter.sol smart contract, which governs the processing of incoming operations.

It’s important to understand that at the time of writing this article, the second, third, and fourth versions of the protocol exist — and I think that’s not the limit! Swaps can be arranged into an entire chain of exchanges across different pools and different protocol versions.

Thus, it’s logical to have a layer between the protocol interface and the different versions of smart contracts. This layer is called UniversalRouter and is located in a separate repository.

The UniversalRouter.sol smart contract inherits from specific smart contracts (routers) that implement integration logic with each version of the protocol.

To trigger the routing mechanism through UniversalRouter.sol, you need to call the execute(bytes calldata commands, bytes[] calldata inputs, uint256 deadline) function. The function takes a set of command bytes (or user operations, such as a swap in UniV2), an array of input data (recipient address, amount, and so on for each command), and a deadline.

Below is pseudocode: how to encode the execute() call.

Multiple commands are encoded as follows:

Important! It’s worth noting the locations of the smart contracts. In the inheritance chain, the V4SwapRouter.sol smart contract inherits from the V4Router.sol smart contract, which is located in the periphery repository.

In this section, we’ll look at even more interesting mechanics used in the protocol.

Pool Unlocking

By default, token pools are “locked,” meaning operations with them are unavailable. The pool unlocking mechanism ensures that operations are executed atomically and that no one can interfere with the process. Essentially, this is protection against reentrancy attacks.

The unlock() function is responsible for unlocking the pool. At the same time, the unlock() function is the only entry point for the PoolManager.sol smart contract.

The unlocking mechanism is implemented using EIP-1153: Transient storage opcodes.

We’ve written about Transient Storage. If you want to learn more about it, look for it in our wiki under the EIPs folder.

The entire pool unlocking process is shown in the diagram below.

Any user action that reaches a routing smart contract (V4Router.sol, PositionManager.sol) first calls unlock() on the PoolManager.sol smart contract.

After unlocking, PoolManager.sol makes a callback through the unlockCallback() function. Then the user action is processed, and another call is made to PoolManager.sol to handle the user’s action.

At the end of the operation, the pool will be locked again and unavailable for operations. Thus, the one who unlocked the pool is the one who performs the operation.

The unlockCallback() function is located in the SafeCallback.sol smart contract, from which BaseActionsRouter.sol inherits.

The actual implementation of the function is located in BaseActionsRouter.sol.

It’s interesting to take a look at what the locking mechanism actually is, because transient storage is used to store the unlock state.

It’s simple: there’s a dedicated Lock.sol library, which sets the unlock flag using the new tstore and tload opcodes.

In this simple way, call atomicity is guaranteed. In the future, the library may be removed once the Solidity compiler introduces keywords for managing transient storage.

How Hooks Are Integrated

The theory is simple. You prepare your hook smart contract (to do this, you must inherit it from the abstract BaseHook.sol) and create a pool with this hook. Now all calls will automatically pass through this hook smart contract.

For this hook mechanism, it’s logical to assume that the pool manager smart contract must be able to do two things:

1. Know the hook of each pool (if it exists)
2. Be able to make calls to the hook smart contract

All hooks work on the same principle, so let’s look at the swap() function as an example.

In the code, triggering the hook before and after the operation looks simple and is done through a direct call to the beforeSwap()/afterSwap() functions.

Thus, the hook is executed before and after any user operation. Information about the hook’s address is stored in the PoolKey structure.

Important! Pay attention to the bytes calldata hookData parameter in the swap() function. This is an arbitrary set of bytes that can be passed along with the call to the hook.

Hook Codebase Architecture

If the hook execution flow should be clear, the smart contracts are a bit more complex.

Initially, when a swap is called, the function on PoolManager.sol takes a PoolKey parameter, which, in addition to token information, contains the address of the hook smart contract.

Important! The address of the hook smart contract is part of the unique pool identifier. That’s why the hook smart contract is set only once during pool initialization.

Then, to handle the hook call, a library is used that wraps all IHooks interfaces. This library validates the call and, if the hook is activated, forwards the call to the user’s CustomHook.sol smart contract, which inherits from the base BaseHook.sol implementation.

Hook Processing Library

The logic for processing a hook call is located in the Hooks.sol library.

If a hook is not defined, the call is effectively not executed, but the verification code is still present. Gas is spent on the check — there’s no way around it.

Initialization Hook

There is one important difference with the hook that is called during initialization. We know that the hook smart contract address is not random — it is created using the special HookMiner.sol library, which encodes into the hook’s address the list of functions (user actions, swaps, etc.) for which the hook is active.

Therefore, during pool initialization, the hook address is additionally verified.

Uniswap V4 continues to set trends in the technical implementation of DeFi applications. Combining all liquidity pools into a single smart contract not only reduces gas costs by eliminating the need to deploy new smart contracts but also simplifies “complex” swaps by removing the physical transfer of tokens between pools.

The V4 architecture, with management through PoolManager.sol, ensures atomic operations thanks to the unlocking mechanism (using EIP-1153), protecting against reentrancy attacks.

The new “hooks” feature adds flexibility, allowing developers to implement custom logic.

Uniswap V4 is not just an optimization but also a platform for innovation in DeFi, awaiting your contribution!

Thanks to this article, we’ve covered the basics of V4 while leaving room for further exploration — from deep dives into libraries such as Pool.sol, SwapMath.sol, and Hooks.sol to experimenting with hooks.