本文へ移動
← Uniswap v4 で市場を作る — PoolManager と hook を 2 つの公開プロジェクトから読む
第 1 部 — プール、unlock、hook のアドレス

新しい市場を作る · Uniswap v4

このコースの 3 / 935 分

レッスン3 — hook の権限はアドレスに書かれている

出典: Uniswap/v4-core v4.0.0、Uniswap/v4-periphery c6e4754(Shadowbook が固定している版)、psyto/summon-stocks d4debb7、fabrknt/shadowbook 7d07439。

読了目安:約 15 分(手を動かすと 35 分)

ビットが 1 つ欠けると、swap のルールが黙って消える

PoolManager は、hook にどのコールバックが欲しいかを尋ねない。hook のアドレスの下位 14 ビットを読み、1 ビットを 1 つのコールバックに対応させる。

だから権限は、hook をデプロイした時点で決まる。

デプロイとはつまり、ちょうど正しいビットを持つアドレスにコントラクトが置かれる、CREATE2 の salt を探すことだ。

「ビットを間違えたらどうなるの?」と思うかもしれない。

hook はコンストラクタで自分のアドレスを確かめられる。確かめなければ、ビットが欠けても何も起きずに素通りする。

このレッスンでは仕組みを読み、最後に両プロジェクトでビットをわざと壊す。

  • Hooks.sol の 14 個のフラグビットと、それを読む hasPermission
  • v4-core の 2 つの検査:isValidHookAddress(initialize が確かめる)と validateHookPermissions(hook のコンストラクタ用)
  • Shadowbook と DirectionalFee での getHookPermissions の使い方と、それを使わない SummonHook
  • 各プロジェクトが salt を見つける方法と、ビットとコードが食い違ったときに起きること

PoolManager は、どのコールバックを呼ぶかをどう決めるのか

ライブラリ自身がはっきり書いている(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.

(v4 は、hook のコントラクトがデプロイされたアドレスの下位ビットを見て、どの hook を呼ぶかを決める。たとえば 0x…2400 なら下位ビットは 10 0100 0000 0000 で、before initialize と after add liquidity が使われる。)

フラグの一覧はこうだ(L26-L46)。

ビットフラグビットフラグ
13BEFORE_INITIALIZE6AFTER_SWAP
12AFTER_INITIALIZE5BEFORE_DONATE
11BEFORE_ADD_LIQUIDITY4AFTER_DONATE
10AFTER_ADD_LIQUIDITY3BEFORE_SWAP_RETURNS_DELTA
9BEFORE_REMOVE_LIQUIDITY2AFTER_SWAP_RETURNS_DELTA
8AFTER_REMOVE_LIQUIDITY1AFTER_ADD_LIQUIDITY_RETURNS_DELTA
7BEFORE_SWAP0AFTER_REMOVE_LIQUIDITY_RETURNS_DELTA

1 つのフラグを確かめる関数は、これだけだ(L336-L338)。

function hasPermission(IHooks self, uint160 flag) internal pure returns (bool) {
    return uint160(address(self)) & flag != 0;
}

呼び出し箇所は、すべてこれを通る。たとえば 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)));
    }
}

ビットが立っていなければ、hook は呼ばれない。

revert もしない。

レッスン2 のトレースで、hook は 0x0500000000000000000000000000000000002880 にいた。

下位 14 ビットは 0x2880 = 10 1000 1000 0000。つまりビット 13・11・7 で、BEFORE_INITIALIZE・BEFORE_ADD_LIQUIDITY・BEFORE_SWAP だ。

トレースに出てきた 3 つのコールバックそのものである。

v4-core は何を確かめ、何を確かめられないのか

検査は 2 つある。

1 つ目は、プールを作るとき。

initialize は isValidHookAddress を呼ぶ(PoolManager.sol L125、本体は Hooks.sol L108-L126)。拒むのは次の 3 つだ。

  • 「差分を返す」ビットがあるのに、対応する動作のビットがない(たとえば BEFORE_SWAP なしの BEFORE_SWAP_RETURNS_DELTA)
  • hook がないのに、動的手数料になっている
  • 手数料が動的でないのに、フラグが 1 つもない hook アドレス
return address(self) == address(0)
    ? !fee.isDynamicFee()
    : (uint160(address(self)) & ALL_HOOK_MASK > 0 || fee.isDynamicFee());

ただ、この検査には、コントラクトが実際にどのコールバックを実装しているかは分からない。

見ているのは、ビット同士が矛盾していないかだけだ。

2 つ目は、hook 自身のコンストラクタで。

v4-core は validateHookPermissions を用意している(Hooks.sol L82-L102)。

Permissions 構造体の 14 個の真偽値(L48-L63)を渡す。どれか 1 つでも自分のビットと合わなければ、HookAddressNotValid(address) で revert する。

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));
    }
}

検査は完全一致だ。ビットが余分でも、欠けているのと同じく失敗する。

3 つの hook、2 つの流儀:自分で確かめるか、確かめないか

Shadowbook は、権限をコードで宣言し、デプロイ時に確かめる。

(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;
}

Shadowbook の 2 つ目の hook である DirectionalFee も、2 つのフラグで同じことをする。

(src/DirectionalFee.sol L104-L110):p.beforeInitialize = true; p.beforeSwap = true;。

README も、デプロイする人に向けて同じ規則を書いている。「The address must carry exactly BEFORE_INITIALIZE and BEFORE_SWAP」(アドレスはちょうど BEFORE_INITIALIZE と BEFORE_SWAP を持たなければならない、README L192-L193)。

SummonHook は、確かめない。

getHookPermissions がなく、validateHookPermissions も呼ばない。

3 つのフラグは、doc コメント(src/SummonHook.sol L23)、デプロイスクリプト、テストに書かれているだけだ。コントラクトが実行するコードのどこにもない。

演習で効いてくるので、覚えておいてほしい。

その後(2026-11-14)。

このレッスンが読む d4debb7 の SummonHook は、権限を宣言していない。

下の演習 B で黙って素通りする失敗が見えたあと、Summon は両方を足した。コミット b1dd190 で SummonHook に getHookPermissions が加わり、コンストラクタで Hooks.validateHookPermissions を呼ぶようになった(src/SummonHook.sol L40-L53)。

普通のアドレスに hook をデプロイして HookAddressNotValid を期待するテストも加わった(test/SummonRound.t.sol L647-L655)。

このコミット以降は forge test が 58 件になる。演習 B の編集は黙って通らず、setUp で HookAddressNotValid(0x0500000000000000000000000000000000002800) になる(両方とも実際に走らせた)。

出力が合うよう、ここでの演習は d4debb7 のままにしている。

正しいビットのアドレスは、どう手に入れるのか:salt を探す

CREATE2 では、アドレスがデプロイ元・salt・初期化コードで決まる。

だから、下位 14 ビットが合うまで salt を試せばいい。

Summon は、自前のループを書いている。

(script/Deploy.s.sol L26-L28 と 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");
}

初期化コードのハッシュには、コンストラクタ引数も含まれる。

スクリプトは new SummonHook{salt: salt}(POOL_MANAGER, me) でデプロイし、続けて require(address(hook) == hookAddr, "hook address") で確かめる(L49-L55)。

CREATE2_DEPLOYER は 0x4e59b44847b379578588920cA78FbF26c0B4956C(L22)。v4-periphery の HookMiner のコメントにあるとおり、forge script が CREATE2 に使うデプロイ元だ(HookMiner.sol L17-L18)。

README には、結果がこう記録されている。「The deploy script finds a CREATE2 salt that puts the hook at an address with exactly its flags」(デプロイスクリプトは、hook をちょうど自分のフラグを持つアドレスに置く CREATE2 の salt を見つける、README L258-L259)。

Shadowbook は、v4-periphery の HookMiner を使う。

(script/Demo.s.sol L58-L67)

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)も同じループだ。違いは 2 つ。条件が 1 つ多い(そのアドレスにまだ何もデプロイされていないこと)のと、試行の上限が 160,444 回であることだ。

DirectionalFee のデプロイは、CREATE2 のデプロイ元を salt ++ initcode で直接呼んでいる(Demo.s.sol L96-L110)。

テストは、探索を省く。

どちらのテストも Foundry の deployCodeTo で、フラグから組み立てたアドレスに hook を置く。

deployCodeTo もコンストラクタは実行する。だから Shadowbook の自己検査は、すべてのテストで走る。

ビットとコードが食い違ったとき、危ないのはどれか

場合起きること例
hook が自己検査していて、アドレスが違うデプロイが HookAddressNotValid(address) で revertShadowbook、DirectionalFee
コードが頼っているコールバックのビットがアドレスにないPoolManager はそれを呼ばない。何も revert しない自己検査のない hook すべて
コードが扱わないコールバックのビットがアドレスにあるその呼び出しが revert し、プールの操作ごと失敗するShadowbook の未使用コールバックは HookNotImplemented で revert(L302-L306)
ビット同士が矛盾しているinitialize が HookAddressNotValid で revertisValidHookAddress

危ないのは 2 行目だ。

演習では、1 行目と 2 行目を実際に起こす。

演習:作業用のコピーでビットを壊す

手元の checkout ではなく、新しく作ったコピーで作業する。

2 つの checkout がある場所(レッスン1 で clone した場所)から始める。

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 が、コールバックを 1 つ多く求める。

src/Shadowbook.sol の getHookPermissions に p.afterSwap = true; を足す。

コードはビット 6 を求めるが、テストのアドレスはビット 13・11・7・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

実際の出力:

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 は理由を隠す。-vvvv のトレースには出る。

0x2888 はビット 13・11・7・3 で、ビット 6 がない。だからコンストラクタがデプロイを拒んだ。

実際のデプロイなら、ここで flags に AFTER_SWAP_FLAG を足して salt を掘り直すことになる。

git checkout -- src で戻すと、forge test は再び 49 件通る。

B. Summon の hook から BEFORE_SWAP が抜ける。

test/SummonRound.t.sol の 2 つの hook アドレス(setUp の L97 と、2 つ目のデプロイの L761)から (1 << 7) を外す。

-        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

実際の出力(失敗した行だけ):

[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)

「さすがにデプロイのどこかで落ちるのでは?」と思うかもしれない。落ちない。

デプロイでも、initialize でも(ビット 13 と 11 は残っている)、初期流動性の投入でも、何も失敗していない。

test_swapOnSummonedPool も通る。swap は動くのだ。

消えたのは、beforeSwap のルールすべてだ。

  • 売買停止・一時停止・コーポレートアクションで、swap が止まらなくなった。
  • 市場が閉まっても、手数料が変わらなくなった。同じ取引で受け取った株の額が、2 回とも同じ 406132602 だった。

swap のときに hook に手数料を聞かない動的手数料プールでは、手数料は初期値の 0 のままだ(getInitialLPFee)。

git checkout -- test で戻すと、forge test は再び 57 件通る。

確認すること

  • hook アドレスの下位 14 ビットを、コールバックに読み替えられる(0x…2880 と 0x…2888 で試す)。
  • 権限を 1 つ足すと、Shadowbook のコンストラクタが HookAddressNotValid を出すのを見た。
  • SummonHook のテストが 5 件失敗する一方で swap のテストは通るのを見て、なぜ何も revert しなかったかを言える。
  • 編集を戻したあと、両方のコピーが元の件数(49 と 57)で通る。
  • 自分の hook ならどちらの流儀を使うか、デプロイスクリプトで掘ったアドレスをどう require するかが分かっている。