Uniswap v4 Hooks

Hooks are optional. A v4 pool works without one, using the same concentrated liquidity behavior as Uniswap v3. You need a hook only when you want to customize pool behavior at specific lifecycle points, such as:

• Running logic before or after a swap
• Gating who can add or remove liquidity
• Applying dynamic fees
• Building custom accounting or a custom curve

If your use case is a standard pool, you do not need to write or attach a hook.

A hook contract must be deployed to an address whose low bits encode exactly the permissions it implements. Each hook function maps to a flag stored in a specific bit of the 20-byte address, so you cannot deploy a hook to an arbitrary address.

To get a valid address you mine a CREATE2 salt that produces an address with the correct flag bits set, then deploy with that salt. The HookMiner helper library finds the salt:

uint160 flags = uint160(Hooks.AFTER_ADD_LIQUIDITY_FLAG | Hooks.AFTER_SWAP_FLAG);
bytes memory constructorArgs = abi.encode(POOLMANAGER);
(address hookAddress, bytes32 salt) =
    HookMiner.find(CREATE2_DEPLOYER, flags, type(PointsHook).creationCode, constructorArgs);

The deployment script then asserts that the deployed address matches the mined address. For local testing, Foundry's deployCodeTo cheatcode can place a hook at any address without mining. See Hook Deployment for the full walkthrough.

A hook declares its permissions through getHookPermissions, which returns a struct of boolean flags. The call permissions are:

• beforeInitialize / afterInitialize
• beforeAddLiquidity / afterAddLiquidity
• beforeRemoveLiquidity / afterRemoveLiquidity
• beforeSwap / afterSwap
• beforeDonate / afterDonate

There are also four return-delta permissions that let a hook adjust balances: beforeSwapReturnDelta, afterSwapReturnDelta, afterAddLiquidityReturnDelta, and afterRemoveLiquidityReturnDelta. A hook implements only the functions it needs, and those choices must match the flags encoded in its address. See the full flag list in Hooks.sol.

No. The hook is part of the PoolKey and is set once when the pool is created through PoolManager.initialize. It cannot be added, removed, or swapped afterward.

To use a different hook, or to add one to a pool that has none, you create a new pool with the desired hook in its key. A single hook contract can serve many pools, so you do not need to redeploy the hook itself.

Most hook development uses Foundry. The v4-template repository ships a preconfigured project with v4-core and v4-periphery already imported:

git clone https://github.com/uniswapfoundation/v4-template.git
cd v4-template
forge install
forge test

For unit tests you can deploy the hook to a valid address using the deployCodeTo cheatcode, which avoids mining during tests. You can also run a local Anvil node, deploy v4 and your hook with a Foundry script, and point the test suite at it:

forge test --rpc-url 127.0.0.1:8545

See Hooks Overview for the full local setup.

The address flags and the implemented functions must agree:

• If the address lacks a flag, the PoolManager never calls that hook function, so the logic silently does nothing.
• Permissions are validated against the address at deployment, so declaring permissions that do not match the mined address makes the deployment fail.

Mining the correct address and declaring matching permissions through getHookPermissions keeps the two in sync.