v4-security-foundations

Name: v4-security-foundations
Author: Uniswap

219stars33forks

How to install v4-security-foundations?

uniswap/uniswap-ai/v4-security-foundations

$npx -y skills add Uniswap/uniswap-ai --skill v4-security-foundations

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# v4 Hook Security Foundations
2
3	Security-first guide for building Uniswap v4 hooks. Hook vulnerabilities can drain user funds—understand these concepts before writing any hook code.
4
5	## Threat Model
6
7	Before writing code, understand the v4 security context:
8
9	\| Threat Area \| Description \| Mitigation \|
10	\| ----------------------- \| ---------------------------------------------------------- \| ---------------------------------------------- \|
11	\| Caller Verification \| Only `PoolManager` should invoke hook functions \| Verify `msg.sender == address(poolManager)` \|
12	\| Sender Identity \| `msg.sender` always equals PoolManager, never the end user \| Use `sender` parameter for user identity \|
13	\| Router Context \| The `sender` parameter identifies the router, not the user \| Implement router allowlisting \|
14	\| State Exposure \| Hook state is readable during mid-transaction execution \| Avoid storing sensitive data on-chain \|
15	\| Reentrancy Surface \| External calls from hooks can enable reentrancy \| Use reentrancy guards; minimize external calls \|
16
17	## Permission Flags Risk Matrix
18
19	All 14 hook permissions with associated risk levels:
20
21	\| Permission Flag \| Risk Level \| Description \| Security Notes \|
22	\| --------------------------------- \| ---------- \| --------------------------- \| ----------------------------- \|
23	\| `beforeInitialize` \| LOW \| Called before pool creation \| Validate pool parameters \|
24	\| `afterInitialize` \| LOW \| Called after pool creation \| Safe for state initialization \|
25	\| `beforeAddLiquidity` \| MEDIUM \| Before LP deposits \| Can block legitimate LPs \|
26	\| `afterAddLiquidity` \| LOW \| After LP deposits \| Safe for tracking/rewards \|
27	\| `beforeRemoveLiquidity` \| HIGH \| Before LP withdrawals \| Can trap user funds \|
28	\| `afterRemoveLiquidity` \| LOW \| After LP withdrawals \| Safe for tracking \|
29	\| `beforeSwap` \| HIGH \| Before swap execution \| Can manipulate prices \|
30	\| `afterSwap` \| MEDIUM \| After swap execution \| Can observe final state \|
31	\| `beforeDonate` \| LOW \| Before donations \| Access control only \|
32	\| `afterDonate` \| LOW \| After donations \| Safe for tracking \|
33	\| `beforeSwapReturnDelta` \| CRITICAL \| Returns custom swap amounts \| NoOp attack vector \|
34	\| `afterSwapReturnDelta` \| HIGH \| Modifies post-swap amounts \| Can extract value \|
35	\| `afterAddLiquidityReturnDelta` \| HIGH \| Modifies LP token amounts \| Can shortchange LPs \|
36	\| `afterRemoveLiquidityReturnDelta` \| HIGH \| Modifies withdrawal amounts \| Can steal funds \|
37
38	### Risk Thresholds
39
40	- LOW: Unlikely to cause fund loss
41	- MEDIUM: Requires careful implementation
42	- HIGH: Can cause fund loss if misimplemented
43	- CRITICAL: Can enable complete fund theft
44
45	## CRITICAL: NoOp Rug Pull Attack
46
47	The `BEFORE_SWAP_RETURNS_DELTA` permission (bit 10) is the most dangerous hook permission. A malicious hook can:
48
49	1. Return a delta claiming it handled the entire swap
50	2. PoolManager accepts this and settles the trade
51	3. Hook keeps all input tokens without providing output
52	4. User loses entire swap amount
53
54	### Attack Pattern
55
56	```solidity
57	// MALICIOUS - DO NOT USE
58	function beforeSwap(
59	address,
60	PoolKey calldata,
61	IPoolManager.SwapParams calldata params,
62	bytes calldata
63	) external override returns (bytes4, BeforeSwapDelta, uint24) {
64	// Claim to handle the swap but steal tokens
65	int128 amountSpecified = int128(params.amountSpecified);
66	BeforeSwapDelta delta = toBeforeSwapDelta(amountSpecified, 0);
67	return (BaseHook.beforeSwap.selector, delta, 0);
68	}
69	```
70
71	### Detection
72
73	Before interacting with ANY hook that has `beforeSwapReturnDelta: true`:
74
75	1. Audit the hook code - Verify legitimate use case
76	2. Check ownership - Is it upgradeable? By whom?
77	3. Verify track record - Has it been audited by reputable firms?
78	4. Start small - Test with minimal amounts first
79
80	### Legitimate Uses
81
82	NoOp patterns are valid for:
83
84	- Just-in-time liquidity (JIT)
85	- Custom AMM curves
86	- Intent-based trad

People who liked this also viewed

6 picks

Type

v4-security-foundations

219stars33forks

View on GitHub

How to install v4-security-foundations?

uniswap/uniswap-ai/v4-security-foundations

$npx -y skills add Uniswap/uniswap-ai --skill v4-security-foundations

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# v4 Hook Security Foundations
2
3	Security-first guide for building Uniswap v4 hooks. Hook vulnerabilities can drain user funds—understand these concepts before writing any hook code.
4
5	## Threat Model
6
7	Before writing code, understand the v4 security context:
8
9	\| Threat Area \| Description \| Mitigation \|
10	\| ----------------------- \| ---------------------------------------------------------- \| ---------------------------------------------- \|
11	\| Caller Verification \| Only `PoolManager` should invoke hook functions \| Verify `msg.sender == address(poolManager)` \|
12	\| Sender Identity \| `msg.sender` always equals PoolManager, never the end user \| Use `sender` parameter for user identity \|
13	\| Router Context \| The `sender` parameter identifies the router, not the user \| Implement router allowlisting \|
14	\| State Exposure \| Hook state is readable during mid-transaction execution \| Avoid storing sensitive data on-chain \|
15	\| Reentrancy Surface \| External calls from hooks can enable reentrancy \| Use reentrancy guards; minimize external calls \|
16
17	## Permission Flags Risk Matrix
18
19	All 14 hook permissions with associated risk levels:
20
21	\| Permission Flag \| Risk Level \| Description \| Security Notes \|
22	\| --------------------------------- \| ---------- \| --------------------------- \| ----------------------------- \|
23	\| `beforeInitialize` \| LOW \| Called before pool creation \| Validate pool parameters \|
24	\| `afterInitialize` \| LOW \| Called after pool creation \| Safe for state initialization \|
25	\| `beforeAddLiquidity` \| MEDIUM \| Before LP deposits \| Can block legitimate LPs \|
26	\| `afterAddLiquidity` \| LOW \| After LP deposits \| Safe for tracking/rewards \|
27	\| `beforeRemoveLiquidity` \| HIGH \| Before LP withdrawals \| Can trap user funds \|
28	\| `afterRemoveLiquidity` \| LOW \| After LP withdrawals \| Safe for tracking \|
29	\| `beforeSwap` \| HIGH \| Before swap execution \| Can manipulate prices \|
30	\| `afterSwap` \| MEDIUM \| After swap execution \| Can observe final state \|
31	\| `beforeDonate` \| LOW \| Before donations \| Access control only \|
32	\| `afterDonate` \| LOW \| After donations \| Safe for tracking \|
33	\| `beforeSwapReturnDelta` \| CRITICAL \| Returns custom swap amounts \| NoOp attack vector \|
34	\| `afterSwapReturnDelta` \| HIGH \| Modifies post-swap amounts \| Can extract value \|
35	\| `afterAddLiquidityReturnDelta` \| HIGH \| Modifies LP token amounts \| Can shortchange LPs \|
36	\| `afterRemoveLiquidityReturnDelta` \| HIGH \| Modifies withdrawal amounts \| Can steal funds \|
37
38	### Risk Thresholds
39
40	- LOW: Unlikely to cause fund loss
41	- MEDIUM: Requires careful implementation
42	- HIGH: Can cause fund loss if misimplemented
43	- CRITICAL: Can enable complete fund theft
44
45	## CRITICAL: NoOp Rug Pull Attack
46
47	The `BEFORE_SWAP_RETURNS_DELTA` permission (bit 10) is the most dangerous hook permission. A malicious hook can:
48
49	1. Return a delta claiming it handled the entire swap
50	2. PoolManager accepts this and settles the trade
51	3. Hook keeps all input tokens without providing output
52	4. User loses entire swap amount
53
54	### Attack Pattern
55
56	```solidity
57	// MALICIOUS - DO NOT USE
58	function beforeSwap(
59	address,
60	PoolKey calldata,
61	IPoolManager.SwapParams calldata params,
62	bytes calldata
63	) external override returns (bytes4, BeforeSwapDelta, uint24) {
64	// Claim to handle the swap but steal tokens
65	int128 amountSpecified = int128(params.amountSpecified);
66	BeforeSwapDelta delta = toBeforeSwapDelta(amountSpecified, 0);
67	return (BaseHook.beforeSwap.selector, delta, 0);
68	}
69	```
70
71	### Detection
72
73	Before interacting with ANY hook that has `beforeSwapReturnDelta: true`:
74
75	1. Audit the hook code - Verify legitimate use case
76	2. Check ownership - Is it upgradeable? By whom?
77	3. Verify track record - Has it been audited by reputable firms?
78	4. Start small - Test with minimal amounts first
79
80	### Legitimate Uses
81
82	NoOp patterns are valid for:
83
84	- Just-in-time liquidity (JIT)
85	- Custom AMM curves
86	- Intent-based trad

People who liked this also viewed

6 picks

Type