本文へ移動
← Uniswap v4 で市場を作る — PoolManager と hook を 2 つの公開プロジェクトから読む
第 2 部 — プール自身のルール: 誰が、いつ、いくらで

新しい市場を作る · Uniswap v4

このコースの 5 / 940 分

レッスン5 — 株の市場を知っているプール

出典: Uniswap/v4-core v4.0.0、psyto/summon-stocks b1dd190、fabrknt/market-state v0.4.0(cbfc651、このレッスンが読む Summon の版がサブモジュールで固定しているタグ)。

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

guard が黙っても swap は止まらない。手数料が 1.00% に上がるだけだ

トークン化された株は、上場している取引所で止まっていても、オンチェーンでは取引できてしまう。

SummonHook の beforeSwap は、この隙間を埋める。swap のたびに 3 つの情報源を読む。

  • 株のトークン:乗数と、予定されている変更
  • 発行体の登録簿:一時停止と、そちらの乗数
  • オフチェーンの guard が書く market-state の登録簿:停止中か、その理由、最後に確認した時刻、いつまで取引できないか

コーポレートアクションの期間中、乗数が古いとき、発行体が一時停止しているとき、2 つの登録簿の乗数が食い違うとき、株が売買停止中のときと再開時刻の前。このどれかなら、swap は revert する。

「じゃあ guard が黙ったら、取引も止まるのでは?」と思うかもしれない。

プールでは止まらない。取引時間外のとき、または guard が許された時間より長く状態を確認していないとき、swap は 0.30% ではなく 1.00% で通る。

つまり guard が黙ると、手数料が上がるだけだ。swap は止まらない。

このレッスンでは規則を順に読み、株式分割後の realign の流れと、hook の revert が swap した人にどう届くかを見る。最後に、自分でテストを 1 つ書く。

  • market-state の登録簿:guard が何を書くか、updatedAt と resumeAfter の意味
  • SummonHook の規則を適用される順に、それぞれが出すエラーと、それを確かめるテストとともに
  • guard が黙ったときに正確に何が起きるか:swap の場合と、約定の場合
  • 株式分割後にプールの価格をどう合わせ直すか(realign)、ラウンド自身の swap がなぜ規則を飛ばすか
  • PoolManager が hook の revert をどう包むか、テストで正確なエラーをどう確かめるか

hook は、何を見て判断しているのか

guard の登録簿。

market-state は小さなパッケージだ。

中身は 2 つ。Nasdaq Trader の売買停止フィードと取引時間を読むオフチェーンの guard と、guard がオンチェーンに書く登録簿だ。

README は Solidity 側をこう説明している(README L15-L18):「MarketStateCheck.requireOpen reverts when a token is halted, before its resumption time, or when the guard has not confirmed its state within maxStateAge. A guard that goes quiet therefore stops trading.」

(MarketStateCheck.requireOpen は、トークンが停止中のとき、再開時刻の前、guard が maxStateAge 以内に状態を確認していないときに revert する。だから guard が黙れば取引が止まる。)

この最後の一文は、あとでもう一度出てくる。

トークンごとの状態はこうだ(src/MarketStateRegistry.sol L9-L22):

uint8 public constant REASON_NONE = 0;
uint8 public constant REASON_PRIMARY_HALT = 1; // halted or suspended on the primary listing exchange
uint8 public constant REASON_BAD_PRINT = 2; // reference price moved outside the band
uint8 public constant REASON_SESSION_CLOSED = 3; // scenario only trades during a session
uint8 public constant REASON_CORPORATE_ACTION = 4; // issuer-announced pause around an action
uint8 public constant REASON_MANUAL = 5;
uint8 public constant REASON_ISSUER_PAUSED = 6;

struct State {
    bool halted;
    uint8 reason;
    uint64 updatedAt; // last time the guard confirmed this state (heartbeat)
    uint64 resumeAfter; // even when not halted, no trading before this time
}

guard は、何かが変わったときに setState を、何も変わっていないことを確かめるときに heartbeat を呼ぶ(L62-L77)。どちらも updatedAt をブロックの時刻にする。

setState は停止中のときだけ reason を保存する。それ以外では REASON_NONE を保存する。

トークン。

B20 の株トークンは multiplier() を持つ。1 トークンが何株に当たるかで、1e18 倍の値だ。

もう 1 つが effectiveAt()。予定された乗数の変更が効く時刻で、なければ 0 だ(src/SummonRound.sol L28-L32)。

発行体の登録簿。

getOracleParams(token) は、発行体の乗数と一時停止のフラグを返す(L34-L37)。

登録簿のないチェーンでは、アドレスが address(0) になりうる(L60)。

hook 自身は、設定を持たない。

レッスン4 と同じくファクトリーでラウンドを見つけ、アドレス(round.deps())と上限(round.params() の cooldownSeconds、maxGuardAge)をラウンドから読む。

テストでは、それぞれ 3600 秒と 300 秒だ(test/SummonRound.t.sol L112-L121)。

どの swap を、どの順で拒むのか

beforeSwap は手数料を選ぶ。その途中で、swap をそもそも許すかを決める(src/SummonHook.sol L76-L85):

function beforeSwap(address sender, PoolKey calldata key, IPoolManager.SwapParams calldata, bytes calldata)
    external
    view
    returns (bytes4, BeforeSwapDelta, uint24)
{
    if (msg.sender != poolManager) revert NotPoolManager();
    SummonRound round = SummonRound(_roundOf(key));
    uint24 fee = sender == address(round) ? SummonPool.OPEN_FEE : _swapFee(round);
    return (IHooks.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, fee | LPFeeLibrary.OVERRIDE_FEE_FLAG);
}

手数料とフラグはレッスン6 で扱う。規則は _swapFee にある(L87-L114):

/// The fee a swap pays now (§5.5 rules 1-5); reverts where swaps stop. The round's own swap inside
/// `realign` skips these rules.
function _swapFee(SummonRound round) internal view returns (uint24) {
    SummonRound.Params memory p = round.params();
    // 1. corporate action window, the same one the fill conditions use
    uint256 eff = IB20AssetMin(p.token).effectiveAt();
    if (eff != 0 && block.timestamp + p.cooldownSeconds >= eff && block.timestamp <= eff + p.cooldownSeconds) {
        revert CorporateActionWindow(eff);
    }
    // 2. the pool was priced at another multiplier
    uint256 m = IB20AssetMin(p.token).multiplier();
    if (m != round.poolMultiplier()) revert StaleMultiplier(round.poolMultiplier(), m);
    // 2a. the issuer's registry: paused, or disagreeing with the token, stops swaps as it stops fills (Codex r3 #4)
    address reg = round.deps().oracleRegistry;
    if (reg != address(0)) {
        (uint256 rm, bool paused) = IOracleParams(reg).getOracleParams(p.token);
        if (paused) revert IssuerPaused();
        if (rm != m) revert MultiplierMismatch(rm, m);
    }
    // 3. halted, or not yet resumed
    MarketStateRegistry ms = MarketStateRegistry(round.deps().marketState);
    MarketStateRegistry.State memory s = ms.stateOf(p.token);
    if (s.halted && s.reason != ms.REASON_SESSION_CLOSED()) revert MarketHalted(s.reason);
    if (block.timestamp < s.resumeAfter) revert MarketHalted(s.reason);
    // 4. closed, or the guard has not confirmed the state lately
    if (s.halted || uint256(s.updatedAt) + p.maxGuardAge < block.timestamp) return SummonPool.CLOSED_FEE;
    return SummonPool.OPEN_FEE;
}

表にすると、こうなる。

規則swap が止まるときエラーテスト
1乗数の変更が今から前後 cooldownSeconds 以内に予定されているCorporateActionWindow(effectiveAt)test_swapStopsInCorporateActionWindow
2トークンの乗数が、プールの値付けに使った乗数と違うStaleMultiplier(pool, token)test_realignAfterMultiplierChange
2a発行体の登録簿が一時停止しているIssuerPaused()test_swapStopsWhileTheIssuerPauses
2a発行体の登録簿とトークンで乗数が食い違うMultiplierMismatch(registry, token)swap のテストはなし(下を参照)
3取引時間外以外の理由で売買停止中MarketHalted(reason)test_swapStopsWhileHalted
3resumeAfter より前MarketHalted(reason)test_swapStopsWhileHalted
4止まらない: 取引時間外、または guard が黙っている(手数料 1.00%)test_swapFeeRisesWhileClosed

コードには、見落としやすい点が 4 つある。

期間は前後両方向。

規則 1 は、effectiveAt の cooldownSeconds 前から cooldownSeconds 後まで拒む。テストでは前後 1 時間ずつだ。

コメントには「the same one the fill conditions use」(約定の条件と同じ期間)とある。そのとおり、ラウンドの _inActionWindow も同じ式だ(src/SummonRound.sol L526-L528)。

取引時間外は、売買停止ではない。

guard は取引時間外を、REASON_SESSION_CLOSED つきの halted として記録する。規則 3 はこれを通し、規則 4 が時間外の手数料を取る。

resumeAfter は、停止中でなくても効く。

登録簿のコメントのとおりだ。停止のあと、guard は株を「開いている」としつつ、ある時刻までは取引させないことができる。

エラーはそれでも MarketHalted(s.reason)。停止中でなければ setState は REASON_NONE を保存しているので、MarketHalted(0) になる。

MultiplierMismatch には、swap のテストがない。

約定の側にはある(test_registryMultiplierMismatch)。swap の側にはない。

なぜわかるのか。作業用のコピーでその行をコメントアウトしても、SummonRoundTest の 52 件がすべて通ったからだ。拒む行の残り 5 つは、どれも外すとテストが失敗した。

その後(2026-11-14)。 Summon のコミット 8a8b464 で test_swapStopsWhileTheRegistryDisagrees が加わった(test/SummonRound.t.sol L975-L984、そのコミットでの行)。hook が拒むことを確かめるテストも、引数なしの vm.expectRevert() ではなく、包まれた正確なエラーを期待するようになった。このレッスンと演習は b1dd190 のままだ。

(注:規則は最新の状態を読むので、作られたプールの swap はどれも、この外部呼び出しの分のガスを払う。レッスン2 のトレースでは、hook の beforeSwap は 17430 ガスだった。)

guard が黙ると、swap は高くなり、約定は止まる

規則 4 は、updatedAt + maxGuardAge とブロックの時刻を比べる。

guard が書かなくなると、状態は古くなる。最後が「開いている」だった古い状態なら、CLOSED_FEE になる。swap は 1.00% で続く。

test_swapFeeRisesWhileClosed の最後のコメントにも、そうある(test/SummonRound.t.sol L920-L923):

vm.revertToState(snap);
// a guard that has gone quiet counts as closed too
vm.warp(vm.getBlockTimestamp() + 301);
assertEq(_buy(router, key, usdcIs0), closed);

では、最後が「停止中」だった古い状態なら?

そのときは、やはり拒む。規則 3 は規則 4 より先に走り、updatedAt を見ないからだ。

約定は、もっと厳しい。

ラウンドは market-state 自身の読み手で市場を確かめる。こちらは、黙った guard を拒否として扱う(src/MarketStateCheck.sol L14-L20):

function requireOpen(MarketStateRegistry registry, address token, uint256 maxStateAge) internal view {
    MarketStateRegistry.State memory s = registry.stateOf(token);
    if (s.halted) revert MarketHalted(s.reason);
    // a token the guard never wrote has updatedAt 0, so it is stale too
    if (uint256(s.updatedAt) + maxStateAge < block.timestamp) revert MarketStateStale(s.updatedAt);
    if (block.timestamp < s.resumeAfter) revert NotYetResumed(s.resumeAfter);
}

呼んでいるのは src/SummonRound.sol L488-L489 だ(// 2. market state, fail closed)。

つまり guard が黙ると、新しい約定は止まる。でも、すでにあるプールの取引は止まらない。高くなるだけだ。

「さっきの README と逆では?」と思うかもしれない。

逆だ。そしてこれは設計上の選択で、SummonHook の説明に書かれている(L18-L23):「While the session is closed, or the guard has gone quiet, swaps pay a higher fee.」(取引時間外か guard が黙っているあいだ、swap は高い手数料を払う)。

登録簿自身の説明は「Readers fail closed when the guard goes quiet」(guard が黙ったら、読み手は拒否の側に倒れる、src/MarketStateRegistry.sol L5-L7)。

だから SummonHook を読む人は、その swap の経路が例外であることを知っておくべきだ。

株式分割のあと、最初の 1 人が半値で買えてしまう

乗数が変わったとする。たとえば、1 トークンが 2 株に当たるようになる 2 対 1 の分割だ。

プールは、古い乗数のままトークンに値を付けている。だから、最初に取引した人が半値で買えてしまう。

規則 2 は、プールの価格が合わせ直されるまで swap を止める。期間が過ぎれば、誰でも合わせ直せる(src/SummonRound.sol L372-L395、抜粋):

/// §5.5a: after a corporate action, re-prices the backers' pool by the multiplier's change, so the first
/// trader cannot take the difference. Anyone may call it once the action window has passed.
function realign() external nonReentrant {
    ...
    uint256 m = IB20AssetMin(p.token).multiplier();
    uint256 from = poolMultiplier;
    if (m == from) revert NothingToDo();
    uint256 eff = IB20AssetMin(p.token).effectiveAt();
    if (_inActionWindow(eff)) revert CorporateActionWindow(eff);
    if (d.oracleRegistry != address(0)) {
        (uint256 rm,) = IOracleParams(d.oracleRegistry).getOracleParams(p.token);
        if (rm != m) revert MultiplierMismatch(rm, m);
    }
    (uint256 t, uint256 u, uint128 l, uint160 sqrtP) = abi.decode(
        IPoolManager(d.poolManager).unlock(abi.encode(OP_REALIGN, m, from)), (uint256, uint256, uint128, uint160)
    );
    ...
    poolMultiplier = m;
    emit Realigned(from, m, sqrtP, l);
}

コールバックの中で(L425-L435)、ラウンドは 3 つのことをする。自分のポジションをすべて外す。空になったプールの価格を swap で動かす。新しい価格でポジションを戻す。

(uint256 t, uint256 u) = _removeAll(pm, key);
if (op == OP_UNWIND) return abi.encode(t, u);
// realign: the pool is empty now, so a swap moves its price and moves no tokens. The price is
// currency1 per currency0, so it scales by new/old multiplier when the token is currency0.
(uint160 sqrtNow,,,) = pm.getSlot0(key.toId());
uint160 target = tokenIs0 ? SummonPool.scaledSqrtPrice(sqrtNow, a, b) : SummonPool.scaledSqrtPrice(sqrtNow, b, a);
if (target != sqrtNow) {
    pm.swap(key, IPoolManager.SwapParams({zeroForOne: target < sqrtNow, amountSpecified: -1, sqrtPriceLimitX96: target}), "");
}
(uint256 tUsed, uint256 uUsed, uint128 l2) = _addFullRange(pm, key, target, t, u);
return abi.encode(t - tUsed, u - uUsed, l2, target);

「でも、その swap は規則 2 で拒まれるのでは?」と思うかもしれない。

拒まれる。この swap もほかの swap と同じく beforeSwap を通り、その時点では乗数はまだ古いからだ。

だから beforeSwap は sender == address(round) のとき規則を飛ばし、通常の手数料を返す。

(注:「the pool is empty now」(今プールは空)は、レッスン4 で外部の流動性を締め出すもう 1 つの理由だった。)

test_realignAfterMultiplierChange(test/SummonRound.t.sol L950-L998)は、この流れを通しで確かめる。

  1. トークンの乗数を 2e18 にすると、swap が revert する(StaleMultiplier)。
  2. realign は、期間中と、発行体の登録簿がまだ 1e18 のあいだは拒まれる。
  3. 両方がそろうと成功する。

プールの平方根価格は √2 倍動き、100 ドルで買えるトークンは前の約半分になる。

hook が revert したとき、swap した人には何が届くのか

hook 自身のエラーそのものではない。PoolManager は、hook の revert をそのまま通さない。callHook が包む(libraries/Hooks.sol L130-L136):

function callHook(IHooks self, bytes memory data) internal returns (bytes memory result) {
    bool success;
    assembly ("memory-safe") {
        success := call(gas(), self, 0, add(data, 0x20), mload(data), 0, 0)
    }
    // Revert with FailedHookCall, containing any error message to bubble up
    if (!success) CustomRevert.bubbleUpAndRevertWith(address(self), bytes4(data), HookCallFailed.selector);

包む先は、ERC-7751 のエラーだ(libraries/CustomRevert.sol L10-L11):

/// @dev ERC-7751 error for wrapping bubbled up reverts
error WrappedError(address target, bytes4 selector, bytes reason, bytes details);

4 つの欄の中身はこうだ。

  • target は hook
  • selector はコールバック(beforeSwap は 0x575e24b4)
  • reason は hook 自身の revert データ
  • details は HookCallFailed() のセレクタ

unlock も、SummonSwap のようなルーターもこれを捕まえない。だから、そのまま呼び出し元に届く。

Summon のテストはエラーを名指ししない。引数なしの vm.expectRevert() に、コメント(「the PoolManager wraps the hook's MarketHalted」)を添えているだけだ。

これは、どんな revert でも通ってしまう。演習では、正確なエラーを確かめる。

演習:自分のテストを書き、規則を外す

checkout がある場所から始める。

git -C summon-stocks fetch origin
git -C summon-stocks checkout b1dd190 && git -C summon-stocks submodule update --init --recursive
rm -rf /tmp/summon-scratch
cp -R summon-stocks /tmp/summon-scratch && cd /tmp/summon-scratch
rm -rf cache/fuzz   # no fuzz failures replayed from earlier runs

テストが試していない停止、異常な値付け(REASON_BAD_PRINT、2)のテストを足す。包まれたエラーを丸ごと確かめる。

cat > test/BadPrint.t.sol <<'EOF'
// SPDX-License-Identifier: Apache-2.0
pragma solidity 0.8.26;

import {PoolKey} from "v4-core/src/types/PoolKey.sol";
import {IHooks} from "v4-core/src/interfaces/IHooks.sol";
import {Hooks} from "v4-core/src/libraries/Hooks.sol";
import {CustomRevert} from "v4-core/src/libraries/CustomRevert.sol";
import {SummonHook} from "../src/SummonHook.sol";
import {SummonSwap} from "../src/SummonSwap.sol";
import {SummonRoundTest} from "./SummonRound.t.sol";

contract BadPrintTest is SummonRoundTest {
    function test_swapStopsOnABadPrint() public {
        (SummonSwap router, PoolKey memory key, bool usdcIs0) = _summoned();
        // the guard freezes the token: its reference price moved outside the band
        market.setState(address(token), true, market.REASON_BAD_PRINT(), 0);
        vm.prank(alice);
        vm.expectRevert(
            abi.encodeWithSelector(
                CustomRevert.WrappedError.selector,
                address(hook),
                IHooks.beforeSwap.selector,
                abi.encodeWithSelector(SummonHook.MarketHalted.selector, uint8(2)),
                abi.encodeWithSelector(Hooks.HookCallFailed.selector)
            )
        );
        router.swapExactIn(key, usdcIs0, 100e6, 1, alice);
    }
}
EOF
forge test --mt test_swapStopsOnABadPrint
forge test --mt test_swapStopsOnABadPrint -vvvv | grep -E "MarketHalted|WrappedError"

_summoned()(L894-L902)は、ラウンドを約定させ、ルーターとプールのキーを返す。

実際の出力はこうだ。時間は … で切り、トレースは最も内側の revert と、最初に包まれたものだけ残した。

Ran 1 test for test/BadPrint.t.sol:BadPrintTest
[PASS] test_swapStopsOnABadPrint() (gas: 1898907)
Suite result: ok. 1 passed; 0 failed; 0 skipped; …

    │   │   │   │   │   └─ ← [Revert] MarketHalted(2)
    │   │   │   │   └─ ← [Revert] WrappedError(0x0500000000000000000000000000000000002880, 0x575e24b4, 0x46510f530000000000000000000000000000000000000000000000000000000000000002, 0xa9e35b2f)

0x46510f53 は MarketHalted(uint8) で、後ろに理由の 2 が続く。0xa9e35b2f は HookCallFailed() だ(cast sig "MarketHalted(uint8)" で確かめられる)。

同じ WrappedError が、テストまでの各フレームで繰り返される。

次に、規則 3 の停止の検査(109 行目)を外して、自分のテストとテスト全体を走らせる。

sed -i '' '109s|^|//|' src/SummonHook.sol   # GNU sed: sed -i without ''
forge test --mt test_swapStopsOnABadPrint
forge test --mc SummonRoundTest
[FAIL: next call did not revert as expected] test_swapStopsOnABadPrint() (gas: 2006492)
Suite result: FAILED. 0 passed; 1 failed; 0 skipped; …

[FAIL: next call did not revert as expected] test_swapStopsWhileHalted() (gas: 2003663)
Suite result: FAILED. 51 passed; 1 failed; 0 skipped; …

swap は拒まれなかった。では、通常の手数料で通ったのか?

そうでもない。規則 4 はまだ halted を見て、1.00% を取る。

(注:この編集で test_swapStopsWhileHalted を -vvvv で走らせると、hook は 10000 | 0x400000 である 4204304 を返し、Swap イベントは fee: 10000 だ。)

git checkout -- src と rm test/BadPrint.t.sol で戻す。forge test は再び 58 件通る。

確認すること

  • beforeSwap が読む 3 つの情報源と、それぞれのどのフィールドを使うかを言える。
  • 拒む規則ごとに、エラーと、それを外したときに気づくテストを言え、swap のテストがないのはどれかを知っている。
  • guard が黙ったとき swap(1.00%)と約定(MarketStateStale)に何が起きるか、古い停止状態ではなぜ swap が拒まれるかを言える。
  • realign の中のラウンド自身の swap がなぜ規則を飛ばすかを説明できる。
  • 自分の test_swapStopsOnABadPrint が正確な WrappedError で通り、109 行目を外すと失敗し、作業用のコピーが 58 件通る状態に戻った。

次のレッスン6 では、手数料そのものを見る。hook が手数料をどう返すか、v4-core が何を確かめるか、そして向きで値付けする hook だ。