Since the mainnet launch of Uniswap v4, the Hook mechanism has become one of the most-discussed innovations in DeFi. The memecoin launchpad Flaunch on Base leverages Hooks to achieve fixed presale pricing and automatic listing and liquidation mechanisms; the liquidity protocol Bunni v2 uses Hooks to build programmable liquidity and restaking models; tokens like SATO, uPEG (Unipeg), and Slonks, which revolve around Hook-based gameplay, have also seen tens-of-times price surges in short periods this year.
On the flip side of the Hook ecosystem's prosperity, attacks targeting Hook implementation flaws have also increased significantly. This article will start with the Hook mechanism in Uniswap v4, gradually analyze its core call stack, and help project teams understand potential vulnerabilities.
Uniswap v4 Hook Security
1. Introduction
The most significant architectural change in Uniswap v4 compared to v3 is the introduction of the Hook mechanism: it allows developers to attach custom contracts to lifecycle events of liquidity pools, injecting arbitrary logic at nodes such as swap, add/remove liquidity, and initialization.
Key changes in v4 are as follows:
- Singleton Pattern: All pool states are centrally managed by a single PoolManager contract, no longer deploying separate contracts for each pool.
- Flash Accounting: Intermediate balance changes during a transaction are recorded only in transient storage, with final settlement occurring only at the end of the transaction.
- Hook Mechanism: Each pool can be bound to a Hook contract. The PoolManager will call back to this contract at key nodes (beforeInitialize, beforeSwap, afterAddLiquidity, etc.).
- Hook Immutability: Once a pool is initialized, the bound Hook address is permanently fixed (The Hook address bound to a pool cannot be changed, but whether the Hook contract itself is upgradeable depends on its implementation).
In the v3 era, developers only needed to trust the Uniswap protocol itself; in the v4 era, the security of each pool depends on the Hook it's bound to. Hooks expand AMM from a fixed financial primitive to a programmable financial infrastructure, but the security model has also fragmented from "protocol-level" to "pool-level."
2. Hook Architecture
2.1 PoolManager and the unlock/callback Model
The core contract of v4 is the singleton PoolManager. Any operation that changes a pool's state (swap, add/remove liquidity) must first call PoolManager.unlock() to obtain one-time callback permission, then perform the specific action within unlockCallback(). At the end of the entire process, the PoolManager will verify whether the ledger balances:
If NonzeroDeltaCount != 0, it directly reverts. This is the core constraint of v4's flash accounting. Any Hook can temporarily unbalance the accounts during execution but must settle itself before the transaction ends; otherwise, the entire transaction rolls back.
Each pool is uniquely identified by a PoolKey structure, which includes a hooks field:
PoolId is calculated as keccak256(PoolKey), so different hook addresses will result in different pools. This also means the PoolManager does not verify whether a Hook address has been used for other pools; the same Hook contract can be bound to multiple pools simultaneously.
2.2 Hook Permission Bits Encoded in the Address
A counterintuitive design in v4 is: Hook permissions are not determined by a variable inside the contract but by the deployment address of the Hook contract.
The PoolManager checks the lower 14 bits of the Hook address to determine if the Hook needs to be called at a certain lifecycle point:
For example, BEFORE_SWAP_FLAG = 1 << 7. If bit 7 of the Hook address is 1, the PoolManager will call the Hook's beforeSwap() before a swap; otherwise, even if the Hook contract implements beforeSwap(), it will never be called by the PoolManager.
This means the Hook must be deployed via CREATE2 + salt to calculate an address where the lower bits exactly match the target permissions. Uniswap officially provides the HookMiner tool for this purpose:
Mismatches between permission bits and function implementation can lead to two types of issues:
(1) A hook function is implemented, but the address does not encode the corresponding permission bit—The PoolManager will never call that function, rendering the logic useless.
(2) The address encodes a permission bit, but the hook does not implement the corresponding function—The PoolManager may revert during the callback (causing DoS) or fail on return value verification, preventing the related operation from executing.
This is also a natural obstacle to Hook upgrades: If a Hook is upgradable via a proxy, the deployment address remains unchanged during upgrades, so post-upgrade, only existing hook function implementations can be modified, not new hook types added. To reserve future extensibility, all possible permission bits must be pre-mined during initial deployment.
2.3 BaseHook and a Commonly Overlooked Access Control Trap
The BaseHook abstract contract provided by earlier versions of the Uniswap v4 periphery allows developers to inherit it for custom Hook implementation. One important role of BaseHook is to provide the onlyPoolManager modifier for the unlockCallback() function:
However—here lies a design trap that is very easy to overlook—early versions of BaseHook only added onlyPoolManager to unlockCallback, providing no protection for other hook callback functions (beforeSwap, afterSwap, beforeAddLiquidity, etc.). Access control for these functions must be explicitly added by the Hook developer.
3. Hook Lifecycle Code Walkthrough
Using an exact-input swap as an example, the following analyzes the complete call stack from when a user initiates a transaction to settlement.
3.1 Pool Initialization and Hook Binding
Anyone can call PoolManager.initialize() to create a new pool:
isValidHookAddress only checks the compatibility of the address permission bits with the fee field. It does not verify whether the Hook is already used in other pools, nor does it check if the Hook "wants" to accept this PoolKey. If the Hook design does not include whitelisting or single-pool binding logic in beforeInitialize, anyone can construct a new pool using the same Hook but with an arbitrary token pair, triggering all subsequent callbacks of the Hook.
3.2 beforeSwap and BeforeSwapDelta
The swap process entry is PoolManager.swap(). Before executing the core swap logic, it calls Hooks.beforeSwap():
The return value of beforeSwap is a triple (bytes4, BeforeSwapDelta, uint24):
- bytes4: Must equal IHooks.beforeSwap.selector, otherwise PoolManager directly reverts.
- BeforeSwapDelta: The delta adjustments for the specified token and unspecified token that the Hook makes for this swap.
- uint24: Dynamic LP fee override value (only effective when the pool has dynamic fees enabled).
BeforeSwapDelta is an alias for int256, with the high 128 bits being the delta for the specified token (the token the user specified the amount for) and the low 128 bits being the delta for the unspecified token:
Note that the semantic of BeforeSwapDelta is: the Hook should return a positive value for collecting fees and a negative value for refunding tokens. Developers can easily get the sign wrong. Simultaneously, the correspondence between specified and unspecified depends on params.zeroForOne and the sign of amountSpecified. Slight carelessness in writing can lead to token misplacement.
The PoolManager directly adds the specifiedDelta returned by beforeSwap to the amountToSwap:
This line implies a crucial semantic: the Hook can intercept the swap amount. When hookDeltaSpecified equals -params.amountSpecified, amountToSwap directly becomes zero, meaning the Hook completely takes over this swap—this is the so-called Async Hook or Custom Curve Hook.
Async Hooks are the highest-risk design pattern in v4: they essentially replace Uniswap's swap logic with the Hook's own logic. If the Hook has vulnerabilities or is malicious itself, user funds are no longer constrained by Uniswap's native pricing logic but rely primarily on the correctness of the Hook's own implementation.
3.3 Delta Settlement and NonzeroDeltaCount
The deltas returned by beforeSwap and afterSwap do not immediately trigger transfers but are recorded in the PoolManager's internal ledger:
Whenever the cumulative delta for a token changes from zero to non-zero, NonzeroDeltaCount increments; when it returns to zero, it decrements. As mentioned in 2.1, if NonzeroDeltaCount != 0 at the end of unlock(), the entire transaction reverts.
The Hook balances its delta through two actions: settle() (transferring to the PoolManager) and take() (taking from the PoolManager):
The security semantics brought by this mechanism are clear: everyone must eventually balance the accounts. However, it only guarantees "account conservation," not "account correctness." If the Hook returns a maliciously constructed delta in beforeSwap, the PoolManager will faithfully account for this delta. As long as it's eventually settled and balanced, the transaction succeeds—even if this means the Hook can, by forging business states, cause the system to incorrectly believe an attacker has certain asset rights, which the PoolManager cannot recognize as an error at the business level.
A previous security incident involving Cork Protocol was due to a vulnerability in its Hook, and it had been audited by four firms before the attack. In retrospect, we found:
- Three of the four audits did not include the CorkHook contract in their scope.
- The only firm that audited CorkHook identified some code issues and submitted improvement suggestions but did not fully cover access control problems.
- Another auditor explicitly suggested in their report: "an interesting follow-up engagement would be to prove the invariants for the CorkHook functions that are being invoked by different components verified within the scope of this engagement." This suggestion appears highly pertinent in hindsight.
This exposes a new blind spot in audits in the v4 Hook era: the explosion in protocol complexity makes scope definition itself a security decision. The interaction chain between Hooks and other protocol contracts is very long. Auditing the Hook contract alone is insufficient to discover cross-contract combinatorial issues; conversely, auditing peripheral contracts while excluding the Hook from scope misses the largest attack surface in the v4 era.
4. Reflections
Looking at the protocol mechanisms alongside the Cork attack post-mortem, several core points of the v4 Hook security model can be summarized:
(1) If Hook callback functions rely on the calling context provided by PoolManager, they should explicitly restrict calls to only PoolManager. BaseHook does not do this for developers. This is the design trap in v4 that most easily conflicts with general contract auditing experience.
(2) The binding relationship between a Hook and a pool is not restricted by PoolManager. Developers must implement pool whitelisting or single-pool binding in beforeInitialize themselves.
(3) The permission bits of the Hook address must strictly match the function implementation. The calculated address should pre-include all permission bits that might be needed in the future.
(4) Async / Custom Curve Hooks are essentially completely custom swap implementations. They have no Uniswap protocol-level protection and must be audited to the standard of "fully autonomous financial contracts."
(5) "Conservation" in delta accounting does not equal "correctness." NonzeroDeltaCount == 0 only guarantees the final ledger is balanced, not that the ledger's content hasn't been maliciously manipulated.
(6) Token type confusion across markets is a new type of attack surface in the v4 era. When a protocol allows users to create markets, semantic validation of tokens is mandatory and cannot rely solely on interface checks.
Each Hook is an independent trust domain, and the security of each pool is determined by the Hook it's bound to. Therefore, the complexity of Hook security audits is no longer "auditing one piece of code" but "auditing a complete sub-protocol"—this change signifies a methodological upgrade for both project teams and auditors.
View Original Text
