v4 Hook Security Foundations

Security-first guide for building Uniswap v4 hooks. Hook vulnerabilities can drain user funds—understand these concepts before writing any hook code.

Threat Model

Before writing code, understand the v4 security context:

Threat Area	Description	Mitigation
Caller Verification	Only PoolManager should invoke hook functions	Verify msg.sender == address(poolManager)
Sender Identity	msg.sender always equals PoolManager, never the end user	Use sender parameter for user identity
Router Context	The sender parameter identifies the router, not the user	Implement router allowlisting
State Exposure	Hook state is readable during mid-transaction execution	Avoid storing sensitive data on-chain
Reentrancy Surface	External calls from hooks can enable reentrancy	Use reentrancy guards; minimize external calls

Permission Flags Risk Matrix

All 14 hook permissions with associated risk levels:

Permission Flag	Risk Level	Description	Security Notes
beforeInitialize	LOW	Called before pool creation	Validate pool parameters
afterInitialize	LOW	Called after pool creation	Safe for state initialization
beforeAddLiquidity	MEDIUM	Before LP deposits	Can block legitimate LPs
afterAddLiquidity	LOW	After LP deposits	Safe for tracking/rewards
beforeRemoveLiquidity	HIGH	Before LP withdrawals	Can trap user funds
afterRemoveLiquidity	LOW	After LP withdrawals	Safe for tracking
beforeSwap	HIGH	Before swap execution	Can manipulate prices
afterSwap	MEDIUM	After swap execution	Can observe final state
beforeDonate	LOW	Before donations	Access control only
afterDonate	LOW	After donations	Safe for tracking
beforeSwapReturnDelta	CRITICAL	Returns custom swap amounts	NoOp attack vector
afterSwapReturnDelta	HIGH	Modifies post-swap amounts	Can extract value
afterAddLiquidityReturnDelta	HIGH	Modifies LP token amounts	Can shortchange LPs
afterRemoveLiquidityReturnDelta	HIGH	Modifies withdrawal amounts	Can steal funds

Risk Thresholds

• LOW: Unlikely to cause fund loss
• MEDIUM: Requires careful implementation
• HIGH: Can cause fund loss if misimplemented
• CRITICAL: Can enable complete fund theft

CRITICAL: NoOp Rug Pull Attack

The BEFORE_SWAP_RETURNS_DELTA permission (bit 10) is the most dangerous hook permission. A malicious hook can:

1. Return a delta claiming it handled the entire swap
2. PoolManager accepts this and settles the trade
3. Hook keeps all input tokens without providing output
4. User loses entire swap amount

Attack Pattern

// MALICIOUS - DO NOT USE
function beforeSwap(
    address,
    PoolKey calldata,
    IPoolManager.SwapParams calldata params,
    bytes calldata
) external override returns (bytes4, BeforeSwapDelta, uint24) {
    // Claim to handle the swap but steal tokens
    int128 amountSpecified = int128(params.amountSpecified);
    BeforeSwapDelta delta = toBeforeSwapDelta(amountSpecified, 0);
    return (BaseHook.beforeSwap.selector, delta, 0);
}

Detection

Before interacting with ANY hook that has beforeSwapReturnDelta: true:

1. Audit the hook code - Verify legitimate use case
2. Check ownership - Is it upgradeable? By whom?
3. Verify track record - Has it been audited by reputable firms?
4. Start small - Test with minimal amounts first

Legitimate Uses

NoOp patterns are valid for:

• Just-in-time liquidity (JIT)
• Custom AMM curves
• Intent-based trading systems
• RFQ/PMM integrations

But each requires careful implementation and audit.

Delta Accounting Fundamentals

v4 uses a credit/debit system through the PoolManager:

Core Invariant

For every transaction: sum(deltas) == 0

The PoolManager tracks what each address owes or is owed. At transaction end, all debts must be settled.

Key Functions

Function	Purpose	Direction
take(currency, to, amount)	Withdraw tokens from PoolManager	You receive tokens
settle(currency)	Pay tokens to PoolManager	You send tokens
sync(currency)	Update PoolManager balance tracking	Preparation for settle

Settlement Pattern

// Correct pattern: sync before settle
poolManager.sync(currency);
currency.transfer(address(poolManager), amount);
poolManager.settle(currency);

Common Mistakes

1. Forgetting sync: Settlement fails without sync
2. Wrong order: Must sync → transfer → settle
3. Partial settlement: Leaves transaction in invalid state
4. Double settlement: Causes accounting errors

Access Control Patterns

PoolManager Verification

Every hook callback MUST verify the caller:

modifier onlyPoolManager() {
    require(msg.sender == address(poolManager), "Not PoolManager");
    _;
}

function beforeSwap(
    address sender,
    PoolKey calldata key,
    IPoolManager.SwapParams calldata params,
    bytes calldata hookData
) external override onlyPoolManager returns (bytes4, BeforeSwapDelta, uint24) {
    // Safe to proceed
}

Why This Matters

Without this check:

• Anyone can call hook functions directly
• Attackers can manipulate hook state
• Funds can be drained through fake callbacks

Router Verification Patterns

The sender parameter is the router, not the end user. For hooks that need user identity:

Allowlisting Pattern

mapping(address => bool) public allowedRouters;

function beforeSwap(
    address sender,  // This is the router
    PoolKey calldata key,
    IPoolManager.SwapParams calldata params,
    bytes calldata hookData
) external override onlyPoolManager returns (bytes4, BeforeSwapDelta, uint24) {
    require(allowedRouters[sender], "Router not allowed");
    // Proceed with swap
}

User Identity via hookData

function beforeSwap(
    address sender,
    PoolKey calldata key,
    IPoolManager.SwapParams calldata params,
    bytes calldata hookData
) external override onlyPoolManager returns (bytes4, BeforeSwapDelta, uint24) {
    // Decode user address from hookData (router must include it)
    address user = abi.decode(hookData, (address));
    // CAUTION: Router must be trusted to provide accurate user
}

msg.sender Trap

// WRONG - msg.sender is always PoolManager in hooks
function beforeSwap(...) external {
    require(msg.sender == someUser); // Always fails or wrong
}

// CORRECT - Use sender parameter
function beforeSwap(address sender, ...) external {
    require(allowedRouters[sender], "Invalid router");
}

Token Handling Hazards

Not all tokens behave like standard ERC-20s:

Token Type	Hazard	Mitigation
Fee-on-transfer	Received amount < sent amount	Measure actual balance changes
Rebasing	Balance changes without transfers	Avoid storing raw balances
ERC-777	Transfer callbacks enable reentrancy	Use reentrancy guards
Pausable	Transfers can be blocked	Handle transfer failures gracefully
Blocklist	Specific addresses blocked	Test with production addresses
Low decimals	Precision loss in calculations	Use appropriate scaling

Safe Balance Check Pattern

function safeTransferIn(
    IERC20 token,
    address from,
    uint256 amount
) internal returns (uint256 received) {
    uint256 balanceBefore = token.balanceOf(address(this));
    token.safeTransferFrom(from, address(this), amount);
    received = token.balanceOf(address(this)) - balanceBefore;
}

Base Hook Template

Start with all permissions disabled. Enable only what you need:

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

import {BaseHook} from "v4-periphery/src/base/hooks/BaseHook.sol";
import {Hooks
how to use v4-security-foundations
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use v4-security-foundations on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add v4-security-foundations
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/uniswap/uniswap-ai --skill v4-security-foundationscopy
The skills CLI fetches v4-security-foundations from GitHub repository uniswap/uniswap-ai and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/v4-security-foundations
Reload or restart Cursor to activate v4-security-foundations. Access the skill through slash commands (e.g., /v4-security-foundations) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?