Uniswap V4 Hooks

Uniswap V4 Hook Development

Build against one pinned, compatible dependency graph. Start from a pinned revision of the Uniswap V4 template or pin v4-core, v4-periphery, and the hook library to known-compatible revisions. Do not combine examples from different releases.

As of 2026-02-06 v4-periphery no longer contains BaseHook or HookMiner (PR #510). Use @openzeppelin/uniswap-hooks (what Uniswap/v4-template pins) or Uniswap/v4-hooks-public; both expose the same _before*/_after* internal-override API. HookMiner also remains at v4-periphery/test/shared/HookMiner.sol.

Before editing, inspect the project's foundry.lock, .gitmodules, and remappings. Read Hooks.sol, IHooks.sol, PoolOperation.sol, BaseHook.sol, and HookMiner.sol at those installed revisions. The links at the end are for discovery; the project's pinned dependency graph is the source of truth.

Architecture

Uniswap V4 keeps pools in a singleton PoolManager. A PoolKey selects one hook contract or no hook. The same hook contract can serve multiple pools.

The least significant 14 bits of the hook address encode callback permissions. PoolManager.initialize rejects an invalid hook address, and a maintained BaseHook validates the deployed address against getHookPermissions() in its constructor. Deploy a production hook with CREATE2 and a salt mined for the required low-bit pattern.

In a callback:

• msg.sender is PoolManager.
• The callback's sender argument is the immediate caller of the PoolManager operation. It is commonly a router, not the end user.
• hookData is caller-controlled unless a trusted integration authenticates and binds it to the operation.

An authentic PoolManager callback does not prove that the pool is authorized. Anyone can attempt to initialize a PoolKey that names the hook. A hook must either support permissionless pool creation or validate the complete intended PoolKey or PoolId. Initialization-sensitive hooks must also validate the initial price and every other required pool parameter.

Permission Flags

The constants below are defined by v4-core/src/libraries/Hooks.sol.

The four return-delta flags do not enable callbacks by themselves. Each one requires its corresponding callback flag.

uint160 flags = Hooks.BEFORE_SWAP_FLAG
    | Hooks.AFTER_SWAP_FLAG
    | Hooks.AFTER_SWAP_RETURNS_DELTA_FLAG;

Callback Interface

Import ModifyLiquidityParams and SwapParams from v4-core/src/types/PoolOperation.sol. They are top-level types, not members of IPoolManager.

For liquidity callbacks, liquidityDelta > 0 selects the add path and liquidityDelta <= 0 selects the remove path. A zero-liquidity modification can therefore invoke remove callbacks to collect fees without withdrawing principal.

Every callback must return its external callback selector. Non-delta callback responses must contain at least the 32-byte selector word. beforeSwap must return exactly 96 bytes. When an after-callback return delta is enabled, its response must be exactly 64 bytes.

BaseHook Pattern

When the project's pinned dependency graph uses OpenZeppelin's hook library, override the internal _before* and _after* functions of its BaseHook. The inherited external entry points already enforce onlyPoolManager.

The import path below assumes the Uniswap/v4-template remapping @openzeppelin/uniswap-hooks/=lib/uniswap-hooks/. OpenZeppelin's own README recommends @openzeppelin/uniswap-hooks/=lib/uniswap-hooks/src/, under which the same file is @openzeppelin/uniswap-hooks/base/BaseHook.sol. The path depends on your remapping; check it before treating a "file not found" as a missing dependency.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import {BaseHook} from "@openzeppelin/uniswap-hooks/src/base/BaseHook.sol";
import {Hooks} from "@uniswap/v4-core/src/libraries/Hooks.sol";
import {IPoolManager} from "@uniswap/v4-core/src/interfaces/IPoolManager.sol";
import {PoolKey} from "@uniswap/v4-core/src/types/PoolKey.sol";
import {PoolId, PoolIdLibrary} from "@uniswap/v4-core/src/types/PoolId.sol";
import {BalanceDelta} from "@uniswap/v4-core/src/types/BalanceDelta.sol";
import {BeforeSwapDelta, BeforeSwapDeltaLibrary} from "@uniswap/v4-core/src/types/BeforeSwapDelta.sol";
import {SwapParams} from "@uniswap/v4-core/src/types/PoolOperation.sol";

contract MyHook is BaseHook {
    using PoolIdLibrary for PoolKey;

    mapping(PoolId poolId => uint256 count) public swapCount;

    constructor(IPoolManager manager) BaseHook(manager) {}

    function getHookPermissions() public pure override returns (Hooks.Permissions memory) {
        return Hooks.Permissions({
            beforeInitialize: false,
            afterInitialize: false,
            beforeAddLiquidity: false,
            afterAddLiquidity: false,
            beforeRemoveLiquidity: false,
            afterRemoveLiquidity: false,
            beforeSwap: true,
            afterSwap: true,
            beforeDonate: false,
            afterDonate: false,
            beforeSwapReturnDelta: false,
            afterSwapReturnDelta: false,
            afterAddLiquidityReturnDelta: false,
            afterRemoveLiquidityReturnDelta: false
        });
    }

    function _beforeSwap(address, PoolKey calldata, SwapParams calldata, bytes calldata)
        internal
        pure
        override
        returns (bytes4, BeforeSwapDelta, uint24)
    {
        return (BaseHook.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, 0);
    }

    function _afterSwap(address, PoolKey calldata key, SwapParams calldata, BalanceDelta, bytes calldata)
        internal
        override
        returns (bytes4, int128)
    {
        swapCount[key.toId()]++;
        return (BaseHook.afterSwap.selector, 0);
    }
}

Keep these three things in exact agreement:

1. The callbacks implemented by the contract.
2. The booleans returned by getHookPermissions().
3. The low-bit flags used to mine the deployed address.

Dynamic LP Fees

A beforeSwap callback can override the LP fee only when the pool's PoolKey uses LPFeeLibrary.DYNAMIC_FEE_FLAG. Return the desired fee combined with LPFeeLibrary.OVERRIDE_FEE_FLAG. The fee component must be at most LPFeeLibrary.MAX_LP_FEE, where 1_000_000 represents 100%. A total swap fee of 100% is valid only for exact input when the post-hook native-pool amount is nonzero. Exact output at that boundary reverts while its post-hook native-pool amount remains positive. If a specified return delta reduces that amount exactly to zero, core skips the native curve and the hook must deliver and settle the complete exchange. A dynamic-fee policy that uses the native curve for exact output must remain below the boundary after protocol and LP fees are combined. Returning a value without a valid override flag leaves the pool's current dynamic fee in effect.

Bound every input used to calculate a fee. Test the zero fee, maximum fee, and both exact-input and exact-output paths.

Access Control

Do not treat the callback sender as the end user. For standard router flows it identifies the router. An allowlist on sender is therefore a router allowlist, not a user allowlist.

If the hook needs end-user authorization, use a router that enforces the authorization and passes authenticated context, or verify authorization carried in hookData. Bind that authorization to the chain, hook, pool, operation, payer, recipient, economic limits, nonce, and deadline. Trusting a router address or decoded user address alone does not authenticate its caller.

Oracle and TWAP Hooks

The current pool tick can be manipulated within a transaction. A production TWAP needs a complete observation design: bounded storage, correct cumulative tick growth between writes, interpolation, wraparound handling, and defined behavior when history is insufficient.

Do not ship an afterSwap array append plus an unfinished consult function. Use a tested observation implementation compatible with the project's pinned dependency graph, or test the complete implementation as a separate accounting system.

For external price sources, verify units, decimals, freshness, observation windows, manipulation resistance, invalid-value behavior, and sequencer or cross-chain liveness when applicable. Test stale, reverted, delayed, and out-of-order updates.

Return Deltas and Custom Accounting

Return deltas are denominated from the hook's perspective:

• Positive means the hook is owed or takes currency.
• Negative means the hook owes or sends currency.
• BeforeSwapDelta contains specified and unspecified currency amounts. These are not fixed to currency0 and currency1.
• afterSwap returns only the hook delta for the unspecified currency.
• Liquidity return deltas contain currency0 and currency1 amounts.

For both afterAddLiquidity and afterRemoveLiquidity, including zero-liquidity fee collection, trace principal, feesAccrued, the returned hook delta, the resulting caller delta, hook inventory, and settlement in both currencies. Core subtracts the returned hook delta from the caller's aggregate delta and accounts it to the hook.

For a swap, the specified currency depends on both zeroForOne and whether amountSpecified is exact input (negative) or exact output (positive):

Derive the leg (currency0Specified = (amountSpecified < 0) == zeroForOne); selecting it by direction alone is correct only for exact input. A nonzero specified delta may reduce the amount executed by the native pool, but it cannot cross zero and change the swap from exact input to exact output or the reverse. Reaching exactly zero is allowed. At that boundary the native swap is skipped and the hook acts as the complete exchange, so it must provide and settle the output while enforcing pricing and slippage.

Returning a delta changes PoolManager accounting; it does not transfer tokens or prove that output inventory exists. A positive returned delta credits the hook inside the PoolManager; the hook must take() that credit in the same callback, or the currency's delta stays nonzero and the operation reverts with CurrencyNotSettled(). Every address/currency delta opened during the unlock must be zero before the unlock returns. For ERC-20 payment, call sync(currency), transfer the tokens, then call settle() or settleFor(). For native payment, sync the native currency before calling settle{value: amount}() or settleFor{value: amount}() by first calling poolManager.sync(Currency.wrap(address(0))); this prevents a stale ERC-20 sync from misclassifying settlement. Use take and claims deliberately.

Trace clear and direct transfers or donations before settlement. Do not use an absolute token balance as proof of per-pool reserves or settlement.

Do not model a replacement curve as two return values alone. Use a maintained custom-accounting or custom-curve base, then prove pricing, inventory, settlement, slippage, rounding, and solvency for every path.