tools-only v4 Security Foundations
Security-first guide for building Uniswap v4 hooks. Hook vulnerabilities can drain user funds -- understand these concepts before writing any hook code.
Invocation
/v4-security-foundations
Or describe your requirements naturally:
Review the security of my v4 hook before deployment
What It Does
This skill helps you:
- Understand the v4 threat model: Caller verification, sender identity, router context, state exposure, and reentrancy surfaces
- Assess permission risk: All 14 hook permissions mapped to risk levels from LOW to CRITICAL
- Prevent NoOp rug pull attacks: Detect and avoid the most dangerous hook vulnerability (
beforeSwapReturnDelta) - Implement access control: PoolManager verification, router allowlisting, and user identity patterns
- Audit before deployment: Pre-deployment checklist with risk scoring and audit tier recommendations
Threat Model
| 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 |
| tx.origin Phishing | tx.origin exposes the original signer, enabling relay attacks |
Never use tx.origin for authorization |
Permission Flags Risk Matrix
| Permission Flag | Risk Level | Security Notes |
|---|---|---|
beforeInitialize |
LOW | Validate pool parameters |
afterInitialize |
LOW | Safe for state initialization |
beforeAddLiquidity |
MEDIUM | Can block legitimate LPs |
afterAddLiquidity |
LOW | Safe for tracking/rewards |
beforeRemoveLiquidity |
HIGH | Can trap user funds |
afterRemoveLiquidity |
LOW | Safe for tracking |
beforeSwap |
HIGH | Can manipulate prices |
afterSwap |
MEDIUM | Can observe final state |
beforeDonate |
LOW | Access control only |
afterDonate |
LOW | Safe for tracking |
beforeSwapReturnDelta |
CRITICAL | NoOp attack vector |
afterSwapReturnDelta |
HIGH | Can extract value |
afterAddLiquidityReturnDelta |
HIGH | Can shortchange LPs |
afterRemoveLiquidityReturnDelta |
HIGH | Can steal funds |
Key Topics Covered
- NoOp rug pull attacks: How
BEFORE_SWAP_RETURNS_DELTAcan be exploited, detection methods, and legitimate use cases (JIT liquidity, custom AMM curves, intent-based trading) - Delta accounting: The credit/debit system, settlement patterns, and common mistakes
- Access control patterns: PoolManager verification, router allowlisting, and the
msg.sendertrap - Token handling hazards: Fee-on-transfer, rebasing, ERC-777, pausable, and low-decimal tokens
- Security checklist: 13-point pre-deployment checklist covering all critical areas
- Risk scoring: Calculate your hook's risk score (0-33) with audit tier recommendations
Related Resources
- Uniswap Hooks Plugin - Parent plugin
- Uniswap v4 Docs - Official documentation
- v4-core Repository - Source code
- Hook Permissions Guide - Permission reference