/v4-security-foundations

name: v4-security-foundations
description: Security-first Uniswap v4 hook development. Use when user mentions "v4 hooks", "hook security", "PoolManager", "beforeSwap", "afterSwap", or asks about V4 hook best practices, vulnerabilities, or audit requirements.
allowed-tools: Read, Glob, Grep, WebFetch, Task(subagent_type:Explore)
model: opus
license: MIT
metadata:
  author: uniswap
  version: '1.1.0'

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),