Uniswap v4 turned the most used AMM into a platform: anyone can attach custom code to a pool. That flexibility is why hooks are exciting, and why they deserve careful security review. This guide explains how hooks work and the mistakes auditors look for first.
What Uniswap v4 Hooks Are
Uniswap v4 went live on January 31, 2025, and its headline feature is hooks: external smart contracts that can be attached to individual pools to customize and extend their behavior. When a pool is created, its hook address becomes part of the pool's identity, and the PoolManager calls that hook at the lifecycle points the hook has enabled.
Hooks are optional. A pool without a hook behaves like a standard concentrated-liquidity pool. Each pool can have at most one hook, but a single hook contract can serve any number of pools. The hook is set once, in the PoolKey passed to PoolManager.initialize, and it cannot be added, removed, or replaced afterward.
That last property shapes the whole security model. Liquidity providers and traders in a pool depend on its hook for as long as the pool exists, so a bug, a reverting callback, or a malicious upgrade in the hook affects every pool that uses it.
How v4 Works Under the Hood
Uniswap v4 replaces the one-contract-per-pool design of earlier versions with a singleton: a single PoolManager contract holds the state and logic for every pool. Tokens no longer move between pool contracts on every hop of a multi-hop swap.
Instead, v4 uses flash accounting. A periphery contract unlocks the PoolManager and performs swaps and liquidity changes inside an unlock callback. Each operation updates a running balance called a delta, stored in transient storage made practical by EIP-1153. Only the net amounts are transferred at the end, and the PoolManager reverts the whole transaction if any delta is left unsettled.
Hooks run inside this flow. A beforeSwap or afterSwap callback executes while the PoolManager is unlocked and deltas are open, which is what gives hooks their power and what makes their accounting so sensitive.
Hook Functions and Address-Encoded Permissions
A hook can implement any combination of ten call points: before and after initialization, adding liquidity, removing liquidity, swapping, and donating. Four further return-delta permissions let a hook change the balances settled for swaps and liquidity changes.
Instead of storing permissions, v4 encodes them in the hook contract's address. Fourteen low bits of the 20-byte address act as flags, and the PoolManager reads them to decide which functions to call. Developers therefore mine a CREATE2 salt that produces an address with exactly the right bits. If a flag is missing, the PoolManager never calls that function, so the logic silently does nothing; declaring permissions that do not match the address makes deployment fail.
| Permission | When it runs or what it allows |
|---|---|
| beforeInitialize / afterInitialize | Once, around pool creation; the natural place to restrict which pools may use the hook |
| beforeAddLiquidity / afterAddLiquidity | Around liquidity deposits |
| beforeRemoveLiquidity / afterRemoveLiquidity | Around liquidity withdrawals |
| beforeSwap / afterSwap | Around every swap; beforeSwap can also override the fee in dynamic-fee pools |
| beforeDonate / afterDonate | Around donations to liquidity providers |
| Return-delta permissions | beforeSwap, afterSwap, afterAddLiquidity, and afterRemoveLiquidity may return deltas that change settled balances |
What Hooks Make Possible
Hooks let builders ship new market designs without deploying an entire AMM. Uniswap's documentation highlights custom pricing curves, yield and liquidity-mining programs, derivatives built on v4 liquidity, and lending integrations. Dynamic fees are another major use: a pool created as dynamic-fee can have its LP fee updated through updateDynamicLPFee on the PoolManager or overridden per swap from beforeSwap, for example based on volatility or order flow.
Pricing
- Custom curves
- Dynamic fees
- Oracle-informed fees
Liquidity
- Incentive programs
- Rebalancing strategies
- Access-controlled pools
Trading
- Limit and time-based orders
- MEV-aware execution
- Fee discounts by route
Integrations
- Lending hooks
- Derivatives
- Points and rewards
The Security Risks Auditors Check First
Uniswap's own hook security framework describes hooks as arbitrary logic sitting inside the core swap pipeline, where incorrect assumptions can compromise pool integrity, misprice trades, or expose liquidity providers to losses. These are the issues that come up most often in hook reviews.
Missing PoolManager access control
A deployed hook is a public contract, so anyone can call its callback functions directly. If beforeSwap or afterAddLiquidity updates internal state, an attacker can call it with fabricated parameters. Every callback must verify that msg.sender is the PoolManager. Uniswap's periphery and OpenZeppelin's Uniswap Hooks library provide an onlyPoolManager modifier for this.
Unrestricted pools sharing one hook
Anyone can initialize a new pool that points at your hook, including a pool with worthless or malicious tokens. If the hook keeps shared state such as rewards, oracle values, or accounting across pools, an attacker can use their own pool to corrupt it. Restrict which pools may attach in beforeInitialize and key internal state by pool ID.
function beforeInitialize(address, PoolKey calldata key, uint160)
external
override
onlyPoolManager // only the PoolManager may call the hook
returns (bytes4)
{
// only pools this hook was designed for may attach to it
require(isAllowedPair(key.currency0, key.currency1), "pool not allowed");
require(key.fee == LPFeeLibrary.DYNAMIC_FEE_FLAG, "dynamic fee required");
return IHooks.beforeInitialize.selector;
}The sender is the router, not the user
The sender argument a hook receives is the contract that called the PoolManager, usually a router, not the end user. Logic that grants discounts, enforces allowlists, or tracks positions per user cannot rely on it without additional, verified context such as trusted routers or authenticated hook data.
Delta accounting and custom curves
Return deltas let a hook take or give tokens during a swap or liquidity change. A rounding error, a sign mistake, or a stale value carried between callbacks can leak value on every trade. Hooks that hold liquidity themselves or deposit it elsewhere add more places for accounting to drift, and non-standard tokens such as fee-on-transfer or rebasing tokens can break assumptions silently.
Reverting callbacks can lock a pool
Because a pool can never change its hook, a callback that reverts permanently makes the related action impossible. A reverting beforeSwap stops trading; a reverting beforeRemoveLiquidity or afterRemoveLiquidity can trap liquidity providers' funds. Withdrawal paths in particular should be designed so that they cannot be blocked by external calls, oracles, or admin state.
Upgradeability and privileged roles
An upgradeable hook, or one with powerful admin functions, can change the behavior of every pool attached to it after users have deposited. Fee setters, pausers, and upgrade keys should be limited, time-locked, and visible to users, and the trust they imply should be documented.
A Security Checklist for Uniswap v4 Hooks
Before a hook goes to audit, and again before it receives real liquidity, these checks catch many of the most damaging problems.
Uniswap's hook security framework scores risk across dimensions such as complexity, custom math, external dependencies, and upgradeability, and maps the score to recommended audits, monitoring, bug bounties, and formal verification.
- Every callback is restricted to the PoolManager.
- beforeInitialize restricts which pools, tokens, and fee settings may use the hook.
- Internal state is keyed by pool ID and cannot be influenced through another pool.
- The mined address flags match the implemented functions exactly.
- Delta math is tested for rounding direction, signs, and settlement in every path.
- Liquidity withdrawal cannot be blocked by reverting hooks or external dependencies.
- Identity-based logic does not trust the router's sender without verified context.
- Dynamic fee logic is bounded and cannot be pushed to extreme values.
- Admin, upgrade, and pause powers are minimized, time-locked, and documented.
- Fuzz and invariant tests cover sequences of swaps and liquidity changes across pools.
How Kann Audits Reviews Hooks
Hook reviews sit at the intersection of AMM math, accounting, and access control, so Kann Audits Expert Security Audits assign researchers with DeFi and DEX experience. The review traces each enabled callback through the full unlock and settlement flow, tests delta accounting under adversarial sequences, checks pool validation and shared state, and confirms that liquidity can always be withdrawn.
Kann Audits has no partnership with or endorsement from Uniswap Labs or the Uniswap Foundation. This article is independent research based on public documentation and the v4 source code.
Questions About Uniswap v4 Hooks
Short answers to the questions builders ask most often about hooks and their security.
What are Uniswap v4 hooks?
Hooks are external smart contracts that can be attached to a Uniswap v4 pool to run custom logic at specific points in the pool's lifecycle, such as before or after a swap, a liquidity change, or a donation. Each pool can have one hook, and one hook can serve many pools.
How does a Uniswap v4 hook declare which functions it implements?
Permissions are encoded in the hook contract's address. Specific low bits of the address act as flags for each hook function, so the hook must be deployed to an address with exactly the right bits set, usually by mining a CREATE2 salt.
Can a hook be added to or removed from an existing pool?
No. The hook address is part of the pool key and is fixed when the pool is initialized. Using a different hook requires creating a new pool, which is why a hook that can revert or be upgraded maliciously is a permanent risk for the pools that use it.
Who can call a Uniswap v4 hook?
Anyone can call a deployed contract, so hook callbacks must verify that the caller is the PoolManager. Uniswap's periphery and OpenZeppelin's Uniswap Hooks library both provide an onlyPoolManager check for this purpose.
What are return deltas in Uniswap v4 hooks?
Return-delta permissions let a hook adjust the balances settled for a swap or liquidity change. They enable custom curves and custom accounting, but they also let a hook take or redirect value, so their math and trust assumptions need careful review.
Do Uniswap v4 hooks need a security audit?
Hooks run inside the core swap and liquidity path and often hold or route user funds, so most hooks that will carry real liquidity should be reviewed. Uniswap's own security framework helps teams score their hook's risk and choose audits, monitoring, bug bounties, and formal verification accordingly.
Primary references