Lesson 3 — Hook permissions live in the address
Sources: Uniswap/v4-core
v4.0.0, Uniswap/v4-peripheryc6e4754(the version Shadowbook pins), psyto/summon-stocksd4debb7, fabrknt/shadowbook7d07439.About 15 minutes to read, 35 if you run everything.
Drop one bit, and the swap rules stop running. Nothing reverts.
The PoolManager never asks a hook which callbacks it wants. It reads the lowest 14 bits of the hook's address, one bit per callback.
So the permissions are fixed when the hook is deployed.
And deploying means searching for a CREATE2 salt that lands the contract on an address with exactly the right bits.
"What if the bits are wrong?" you might ask.
A hook can check its own address in its constructor. If it doesn't, a missing bit fails silently.
In this lesson we'll read how that works, then break the bits on purpose in both projects:
- The 14 flag bits in
Hooks.sol, and howhasPermissionreads them - The two checks in v4-core:
isValidHookAddress(checked byinitialize) andvalidateHookPermissions(for a hook's constructor) - How
getHookPermissionsis used in Shadowbook and DirectionalFee, and how SummonHook does without it - How each project finds a salt, and what happens when the bits and the code disagree
How does the PoolManager know which callbacks to call?
The library says it plainly (libraries/Hooks.sol L14-L17):
/// @notice V4 decides whether to invoke specific hooks by inspecting the least significant bits
/// of the address that the hooks contract is deployed to.
/// For example, a hooks contract deployed to address: 0x0000000000000000000000000000000000002400
/// has the lowest bits '10 0100 0000 0000' which would cause the 'before initialize' and 'after add liquidity' hooks to be used.
Here are the flags (L26-L46):
| bit | flag | bit | flag |
|---|---|---|---|
| 13 | BEFORE_INITIALIZE | 6 | AFTER_SWAP |
| 12 | AFTER_INITIALIZE | 5 | BEFORE_DONATE |
| 11 | BEFORE_ADD_LIQUIDITY | 4 | AFTER_DONATE |
| 10 | AFTER_ADD_LIQUIDITY | 3 | BEFORE_SWAP_RETURNS_DELTA |
| 9 | BEFORE_REMOVE_LIQUIDITY | 2 | AFTER_SWAP_RETURNS_DELTA |
| 8 | AFTER_REMOVE_LIQUIDITY | 1 | AFTER_ADD_LIQUIDITY_RETURNS_DELTA |
| 7 | BEFORE_SWAP | 0 | AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA |
And here's the test for one of them (L336-L338):
function hasPermission(IHooks self, uint160 flag) internal pure returns (bool) {
return uint160(address(self)) & flag != 0;
}
Every call site goes through it. Take beforeInitialize (L177-L181):
function beforeInitialize(IHooks self, PoolKey memory key, uint160 sqrtPriceX96) internal noSelfCall(self) {
if (self.hasPermission(BEFORE_INITIALIZE_FLAG)) {
self.callHook(abi.encodeCall(IHooks.beforeInitialize, (msg.sender, key, sqrtPriceX96)));
}
}
If the bit is off, the hook isn't called.
Nothing reverts.
In the trace from Lesson 2, the hook sat at 0x0500000000000000000000000000000000002880.
Its low 14 bits are 0x2880 = 10 1000 1000 0000. That's bits 13, 11 and 7: BEFORE_INITIALIZE, BEFORE_ADD_LIQUIDITY and BEFORE_SWAP.
Those are exactly the three callbacks you saw in the trace.
What does v4-core check, and what can't it check?
There are two checks.
The first runs at pool creation.
initialize calls isValidHookAddress (PoolManager.sol L125, body Hooks.sol L108-L126). It refuses three things:
- a "returns delta" bit without its action bit (for example
BEFORE_SWAP_RETURNS_DELTAwithoutBEFORE_SWAP) - a dynamic fee with no hook
- a hook address with no flag at all, unless the fee is dynamic
return address(self) == address(0)
? !fee.isDynamicFee()
: (uint160(address(self)) & ALL_HOOK_MASK > 0 || fee.isDynamicFee());
But it can't know which callbacks your contract actually implements.
It only checks that the bits are consistent with each other.
The second runs in the hook's own constructor.
v4-core offers validateHookPermissions (Hooks.sol L82-L102).
Give it the 14 booleans of a Permissions struct (L48-L63). It reverts with HookAddressNotValid(address) unless every one matches its bit:
function validateHookPermissions(IHooks self, Permissions memory permissions) internal pure {
if (
permissions.beforeInitialize != self.hasPermission(BEFORE_INITIALIZE_FLAG)
|| permissions.afterInitialize != self.hasPermission(AFTER_INITIALIZE_FLAG)
...
|| permissions.afterRemoveLiquidityReturnDelta
!= self.hasPermission(AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA_FLAG)
) {
HookAddressNotValid.selector.revertWith(address(self));
}
}
The check is exact. An extra bit fails as surely as a missing one.
Three hooks, two styles: check yourself, or don't
Shadowbook declares its permissions in code and checks them at deploy.
(src/Shadowbook.sol L123-L131):
Hooks.validateHookPermissions(IHooks(address(this)), getHookPermissions());
}
function getHookPermissions() public pure returns (Hooks.Permissions memory p) {
p.beforeInitialize = true;
p.beforeAddLiquidity = true;
p.beforeSwap = true;
p.beforeSwapReturnDelta = true;
}
DirectionalFee, Shadowbook's second hook, does the same with two flags.
(src/DirectionalFee.sol L104-L110): p.beforeInitialize = true; p.beforeSwap = true;.
The README states the same rule for deployers: "The address must carry exactly BEFORE_INITIALIZE and BEFORE_SWAP" (README L192-L193).
SummonHook doesn't check at all.
It has no getHookPermissions and doesn't call validateHookPermissions.
Its three flags are written in its doc comment (src/SummonHook.sol L23), in the deploy script and in the test. They're nowhere in code the contract runs.
Keep that in mind for the exercise.
Since then (2026-11-14).
At d4debb7, the version this lesson reads, SummonHook declares no permissions.
After exercise B below showed the silent failure, Summon added both. Commit b1dd190 gives SummonHook a getHookPermissions and calls Hooks.validateHookPermissions in its constructor (src/SummonHook.sol L40-L53).
It also adds a test that deploys the hook at an ordinary address and expects HookAddressNotValid (test/SummonRound.t.sol L647-L655).
From that commit on, forge test counts 58 tests. The edit in exercise B no longer passes silently. It fails in setUp with HookAddressNotValid(0x0500000000000000000000000000000000002800) (we ran both).
The exercises here stay on d4debb7 so their outputs match.
How do you get an address with the right bits? You search for a salt
CREATE2 makes the address a function of the deployer, a salt and the init code.
So you can try salts until the low 14 bits come out right.
Summon writes its own loop.
(script/Deploy.s.sol L26-L28 and L125-L133):
uint160 constant FLAG_MASK = (1 << 14) - 1;
// SummonHook's flags (§5.5): BEFORE_INITIALIZE | BEFORE_ADD_LIQUIDITY | BEFORE_SWAP
uint160 constant HOOK_FLAGS = (1 << 13) | (1 << 11) | (1 << 7);
...
function mineHookSalt(bytes32 initHash) public pure returns (bytes32 salt, address addr) {
for (uint256 i; i < 1_000_000; ++i) {
salt = bytes32(i);
addr = address(uint160(uint256(keccak256(abi.encodePacked(bytes1(0xff), CREATE2_DEPLOYER, salt, initHash)))));
if (uint160(addr) & FLAG_MASK == HOOK_FLAGS) return (salt, addr);
}
revert("no salt");
}
The init hash includes the constructor arguments.
The script deploys with new SummonHook{salt: salt}(POOL_MANAGER, me), then checks with require(address(hook) == hookAddr, "hook address") (L49-L55).
CREATE2_DEPLOYER is 0x4e59b44847b379578588920cA78FbF26c0B4956C (L22). As v4-periphery's HookMiner notes, that's the deployer forge script uses for CREATE2 (HookMiner.sol L17-L18).
The README records the result: "The deploy script finds a CREATE2 salt that puts the hook at an address with exactly its flags" (README L258-L259).
Shadowbook uses HookMiner from v4-periphery.
uint160 flags = uint160(
Hooks.BEFORE_INITIALIZE_FLAG | Hooks.BEFORE_ADD_LIQUIDITY_FLAG | Hooks.BEFORE_SWAP_FLAG
| Hooks.BEFORE_SWAP_RETURNS_DELTA_FLAG
);
...
(address at, bytes32 salt) = HookMiner.find(CREATE2_DEPLOYER, flags, type(Shadowbook).creationCode, args);
Shadowbook hook = new Shadowbook{salt: salt}(manager, owner, quoter, MIN_MID, MAX_MID, maxAge, CAP, WINDOW);
require(address(hook) == at, "hook address");
HookMiner.find (v4-periphery test/shared/HookMiner.sol L23-L41) is the same loop with two differences. It has one more condition, that nothing is deployed at the address yet. And it caps the search at 160,444 tries.
DirectionalFee's deploy calls the CREATE2 deployer directly with salt ++ initcode (Demo.s.sol L96-L110).
Tests skip the search.
Both test suites place the hook with Foundry's deployCodeTo, at an address they build from the flags:
- Summon at
(0x5 << 152) | flags(test/SummonRound.t.sol L95-L98) - Shadowbook at
FLAGS ^ (0x4444 << 144)(test/Shadowbook.t.sol L29-L32, L40, L49-L56)
deployCodeTo still runs the constructor. So Shadowbook's self-check runs in every test.
When the bits and the code disagree, which case is dangerous?
| case | what happens | where |
|---|---|---|
| The hook checks itself and the address is wrong | deploy reverts HookAddressNotValid(address) | Shadowbook, DirectionalFee |
| The address lacks a bit for a callback the code relies on | the PoolManager never calls it; nothing reverts | any hook without the self-check |
| The address has a bit for a callback the code does not handle | the call reverts, and with it the pool action | Shadowbook's unused callbacks revert HookNotImplemented (L302-L306) |
| The bits contradict each other | initialize reverts HookAddressNotValid | isValidHookAddress |
The second row is the dangerous one.
The exercise shows the first two.
Exercise: break the bits, in scratch copies
Work in fresh copies, not in your checkouts.
Start from the directory that holds both checkouts (the one you cloned into in Lesson 1):
git -C summon-stocks checkout d4debb7 && git -C summon-stocks submodule update --init --recursive
git -C shadowbook checkout 7d07439
rm -rf /tmp/shadowbook-scratch /tmp/summon-scratch # Lesson 2 left a copy here
cp -R shadowbook /tmp/shadowbook-scratch
cp -R summon-stocks /tmp/summon-scratch
rm -rf /tmp/shadowbook-scratch/cache/fuzz /tmp/summon-scratch/cache/fuzz # no fuzz failures replayed from earlier runs
A. Shadowbook asks for one more callback.
Add p.afterSwap = true; to getHookPermissions in src/Shadowbook.sol.
Now the code wants bit 6, while the test address still carries only bits 13, 11, 7 and 3:
function getHookPermissions() public pure returns (Hooks.Permissions memory p) {
p.beforeInitialize = true;
p.beforeAddLiquidity = true;
p.beforeSwap = true;
p.beforeSwapReturnDelta = true;
p.afterSwap = true; // added
}
cd /tmp/shadowbook-scratch
forge test --mc ShadowbookTest # the summary
forge test --mc ShadowbookTest -vvvv 2>&1 | grep HookAddressNotValid
What we got:
Ran 1 test for test/Shadowbook.t.sol:ShadowbookTest
[FAIL: StdCheats deployCodeTo(string,bytes,uint256,address): Failed to create runtime bytecode.] setUp() (gas: 0)
Suite result: FAILED. 0 passed; 1 failed; 0 skipped; finished in 2.40ms (0.00ns CPU time)
│ └─ ← [Revert] HookAddressNotValid(0x4444000000000000000000000000000000002888)
deployCodeTo hides the reason. The -vvvv trace shows it.
0x2888 is bits 13, 11, 7 and 3, without bit 6. So the constructor refused to deploy.
On a real deploy, this is where you'd mine a new salt with AFTER_SWAP_FLAG added to flags.
Undo with git checkout -- src. forge test is back to 49 passing.
B. Summon's hook loses BEFORE_SWAP.
In test/SummonRound.t.sol, drop (1 << 7) from the two hook addresses (setUp at L97, and a second deployment at L761):
- address hookAddr = address((uint160(0x5) << 152) | uint160((1 << 13) | (1 << 11) | (1 << 7)));
+ address hookAddr = address((uint160(0x5) << 152) | uint160((1 << 13) | (1 << 11)));
- dp.hook = address((uint160(0x6) << 152) | uint160((1 << 13) | (1 << 11) | (1 << 7)));
+ dp.hook = address((uint160(0x6) << 152) | uint160((1 << 13) | (1 << 11)));
cd /tmp/summon-scratch
forge test --mc SummonRoundTest
What we got (failing lines only):
[FAIL: next call did not revert as expected] test_realignAfterMultiplierChange() (gas: 1973974)
[FAIL: assertion failed: 406132602 >= 406132602] test_swapFeeRisesWhileClosed() (gas: 2033592)
[FAIL: next call did not revert as expected] test_swapStopsInCorporateActionWindow() (gas: 1981876)
[FAIL: next call did not revert as expected] test_swapStopsWhileHalted() (gas: 1966057)
[FAIL: next call did not revert as expected] test_swapStopsWhileTheIssuerPauses() (gas: 1983399)
Suite result: FAILED. 46 passed; 5 failed; 0 skipped; finished in 5.99ms (29.70ms CPU time)
"But surely something failed at deploy?" No.
Nothing failed at deploy, at initialize (bits 13 and 11 are still set) or at seeding.
test_swapOnSummonedPool still passes. Swaps work.
What's gone is every rule in beforeSwap:
- Swaps no longer stop for a halt, a pause or a corporate action.
- The fee no longer changes when the session closes. The same trade received the same
406132602of the stock both times.
On a dynamic-fee pool whose hook is never asked, the fee stays at the initial 0 (getInitialLPFee).
Undo with git checkout -- test. forge test is back to 57 passing.
What to check
- You can decode the low 14 bits of a hook address into its callbacks (try
0x…2880and0x…2888). - You saw
HookAddressNotValidfrom Shadowbook's constructor with one permission added. - You saw five SummonHook tests fail while the swap test still passed, and can say why nothing reverted.
- Both scratch copies are back to their full passing counts (49 and 57) after undoing the edits.
- For a hook of your own, you know which of the two styles you will use, and how your deploy script requires the mined address.