レッスン5 — 株の市場を知っているプール
出典: Uniswap/v4-core
v4.0.0、psyto/summon-stocksb1dd190、fabrknt/market-statev0.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 |
| 3 | resumeAfter より前 | 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)は、この流れを通しで確かめる。
- トークンの乗数を
2e18にすると、swap が revert する(StaleMultiplier)。 realignは、期間中と、発行体の登録簿がまだ1e18のあいだは拒まれる。- 両方がそろうと成功する。
プールの平方根価格は √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は hookselectorはコールバック(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 だ。