From uniswap-hooks
Guides secure Uniswap v4 hook development with threat models, permission risk matrix, caller verification, reentrancy guards, and PoolManager best practices.
npx claudepluginhub uniswap/uniswap-ai --plugin uniswap-hooksThis skill is limited to using the following tools:
Security-first guide for building Uniswap v4 hooks. Hook vulnerabilities can drain user funds—understand these concepts before writing any hook code.
Provides Solidity security patterns, common vulnerabilities like reentrancy and decimal mismatches, defensive code fixes, and pre-deploy audit checklists for contracts handling value.
Performs security scans for tokens (honeypots), EVM/Solana transactions pre-execution, DApps/URLs (phishing), signatures (EIP-712/personal_sign), and ERC20/Permit2 approvals.
Applies Solidity smart contract security best practices, prevents vulnerabilities like reentrancy, overflows, access control issues, and prepares for audits.
Share bugs, ideas, or general feedback.
Security-first guide for building Uniswap v4 hooks. Hook vulnerabilities can drain user funds—understand these concepts before writing any hook code.
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 |
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 |
The BEFORE_SWAP_RETURNS_DELTA permission (bit 10) is the most dangerous hook permission. A malicious hook can:
// 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);
}
Before interacting with ANY hook that has beforeSwapReturnDelta: true:
NoOp patterns are valid for:
But each requires careful implementation and audit.
v4 uses a credit/debit system through the PoolManager:
For every transaction: sum(deltas) == 0
The PoolManager tracks what each address owes or is owed. At transaction end, all debts must be settled.
| 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 |
// Correct pattern: sync before settle
poolManager.sync(currency);
currency.transfer(address(poolManager), amount);
poolManager.settle(currency);
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
}
Without this check:
The sender parameter is the router, not the end user. For hooks that need user identity:
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
}
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
}
// 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");
}
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 |
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;
}
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} from "v4-core/src/libraries/Hooks.sol";
import {IPoolManager} from "v4-core/src/interfaces/IPoolManager.sol";
import {PoolKey} from "v4-core/src/types/PoolKey.sol";
import {BeforeSwapDelta, BeforeSwapDeltaLibrary} from "v4-core/src/types/BeforeSwapDelta.sol";
contract SecureHook is BaseHook {
constructor(IPoolManager _poolManager) BaseHook(_poolManager) {}
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: false, // Enable only if needed
afterSwap: false, // Enable only if needed
beforeDonate: false,
afterDonate: false,
beforeSwapReturnDelta: false, // DANGER: NoOp attack vector
afterSwapReturnDelta: false, // DANGER: Can extract value
afterAddLiquidityReturnDelta: false,
afterRemoveLiquidityReturnDelta: false
});
}
// Implement only the callbacks you enabled above
}
See references/base-hook-template.md for a complete implementation template.
Before deploying any hook:
| # | Check | Status |
|---|---|---|
| 1 | All hook callbacks verify msg.sender == poolManager | [ ] |
| 2 | Router allowlisting implemented if needed | [ ] |
| 3 | No unbounded loops that can cause OOG | [ ] |
| 4 | Reentrancy guards on external calls | [ ] |
| 5 | Delta accounting sums to zero | [ ] |
| 6 | Fee-on-transfer tokens handled | [ ] |
| 7 | No hardcoded addresses | [ ] |
| 8 | Slippage parameters respected | [ ] |
| 9 | No sensitive data stored on-chain | [ ] |
| 10 | Upgrade mechanisms secured (if applicable) | [ ] |
| 11 | beforeSwapReturnDelta justified if enabled | [ ] |
| 12 | Fuzz testing completed | [ ] |
| 13 | Invariant testing completed | [ ] |
Hook callbacks execute inside the PoolManager's transaction context. Excessive gas consumption can make swaps revert or become economically unviable.
| Callback | Target Budget | Hard Ceiling | Notes |
|---|---|---|---|
beforeSwap | < 50,000 gas | 150,000 gas | Runs on every swap; keep lean |
afterSwap | < 30,000 gas | 100,000 gas | Analytics/tracking only |
beforeAddLiquidity | < 50,000 gas | 200,000 gas | May include access control |
afterAddLiquidity | < 30,000 gas | 100,000 gas | Reward tracking |
beforeRemoveLiquidity | < 50,000 gas | 200,000 gas | Lock validation |
afterRemoveLiquidity | < 30,000 gas | 100,000 gas | Tracking/accounting |
| Callbacks with external calls | < 100,000 gas | 300,000 gas | External DEX routing, oracles |
tstore/tload) for data that doesn't persist beyond the transaction. Requires Solidity >= 0.8.24 with EVM target set to cancun or later.string manipulation in callbacks; use bytes32 for identifiers.poolManager calls — repeated getSlot0() or getLiquidity() reads cost gas each time.# Profile a specific hook callback with Foundry
forge test --match-test test_beforeSwapGas --gas-report
# Snapshot gas usage across all tests
forge snapshot --match-contract MyHookTest
Calculate your hook's risk score (0-33):
| Category | Points | Criteria |
|---|---|---|
| Permissions | 0-14 | Sum of enabled permission risk levels |
| External Calls | 0-5 | Number and type of external interactions |
| State Complexity | 0-5 | Amount of mutable state |
| Upgrade Mechanism | 0-5 | Proxy, admin functions, etc. |
| Token Handling | 0-4 | Non-standard token support |
| Score | Risk Level | Recommendation |
|---|---|---|
| 0-5 | Low | Self-audit + peer review |
| 6-12 | Medium | Professional audit recommended |
| 13-20 | High | Professional audit required |
| 21-33 | Critical | Multiple audits required |
Never do these things in a hook:
msg.sender for user identity - It's always PoolManagerbeforeSwapReturnDelta without understanding NoOp attackstransfer() for ETH - Use call{value:}("")block.timestamp for randomnesstx.origin for authorization - It's a phishing vector; malicious contracts can relay calls with the original user's tx.origin| # | Item | Required For |
|---|---|---|
| 1 | Code review by security-focused developer | All hooks |
| 2 | Unit tests for all callbacks | All hooks |
| 3 | Fuzz testing with Foundry | All hooks |
| 4 | Invariant testing | Hooks with delta returns |
| 5 | Fork testing on mainnet | All hooks |
| 6 | Gas profiling | All hooks |
| 7 | Formal verification | Critical hooks |
| 8 | Slither/Mythril analysis | All hooks |
| 9 | External audit | Medium+ risk hooks |
| 10 | Bug bounty program | High+ risk hooks |
| 11 | Monitoring/alerting setup | All production hooks |
See references/audit-checklist.md for detailed audit requirements.
Learn from audited, production hooks:
| Project | Description | Notable Security Features |
|---|---|---|
| Flaunch | Token launch platform | Multi-sig admin, timelocks |
| EulerSwap | Lending integration | Isolated risk per market |
| Zaha TWAMM | Time-weighted AMM | Gradual execution reduces MEV |
| Bunni | LP management | Concentrated liquidity guards |