レッスン2 — PoolManager、unlock とフラッシュ会計
出典: Uniswap/v4-core
v4.0.0、psyto/summon-stocksd4debb7、fabrknt/shadowbook7d07439。読了目安:約 12 分(手を動かすと 35 分)
unlock が戻る前に、すべての差分がゼロでなければならない
v4 では PoolManager を 1 回呼ぶだけでは、swap も流動性の追加もできない。
まず unlock を呼ぶ。すると PoolManager が、呼び出し元をコールバックする。
そのコールバックの中では、swap も流動性の変更も、「いくら払うべきか・いくら受け取れるか」を通貨ごとに書き留めるだけだ。
支払いは sync → 送金 → settle。受け取りは take。
そして unlock が戻る前に、すべてがゼロに打ち消し合っていなければ revert する。
実際のトレースでは、alice が 100 USDC を売る場面を見る。ルーターが払うべき USDC は -100000000、受け取れる株は +404972057。settle と take で、両方がゼロに戻る。settle を 1 つ外すと、テストは CurrencyNotSettled() で落ちる。
このレッスンでは、v4-core でこの仕組みを読み、Summon の swap ルーターとプールへの初期流動性の投入をその上でたどり、テストの実際のコールトレースを読む。
unlock、unlockCallbackとonlyWhenUnlockedの門番- 通貨ごとの差分(delta):どこに置かれ、符号は何を意味し、
unlockがどのカウンタを確かめるか sync・settle・takeと、送金の前にsyncが来る理由- Summon の
SummonSwapとSummonRoundがそれぞれ 1 回のunlockをどう使うか、そして hook が同じ会計にどう加わるか
なぜ、いきなり swap を呼べないのか
残高を動かすものが、すべて 1 つの modifier の後ろにあるからだ(PoolManager.sol L95-L98)。
modifier onlyWhenUnlocked() {
if (!Lock.isUnlocked()) ManagerLocked.selector.revertWith();
_;
}
swap、modifyLiquidity、donate、take、settle、mint、burn のすべてに、これがついている。
ロックを外す方法は、unlock だけだ(PoolManager.sol L103-L113)。
function unlock(bytes calldata data) external override returns (bytes memory result) {
if (Lock.isUnlocked()) AlreadyUnlocked.selector.revertWith();
Lock.unlock();
// the caller does everything in this callback, including paying what they owe via calls to settle
result = IUnlockCallback(msg.sender).unlockCallback(data);
if (NonzeroDeltaCount.read() != 0) CurrencyNotSettled.selector.revertWith();
Lock.lock();
}
したがって呼び出し元は、unlockCallback(bytes) を実装したコントラクトでなければならない(IUnlockCallback.sol L9)。
では、ロックなしで呼べる関数はあるのか。インターフェースに明記されている(IPoolManager.sol L108-L110):「The only functions callable without an unlocking are initialize and updateDynamicLPFee」(unlock なしで呼べるのは initialize と updateDynamicLPFee だけ)。
swap はトークンを動かさない。差分を書き留めるだけだ
コールバックの中の swap は、トークンを動かさない。
最後に、結果を呼び出し元の勘定に記録するだけだ(PoolManager.sol L224):_accountPoolBalanceDelta(key, swapDelta, msg.sender);。これが通貨ごとに _accountDelta を呼ぶ(L366-L376)。
function _accountDelta(Currency currency, int128 delta, address target) internal {
if (delta == 0) return;
(int256 previous, int256 next) = currency.applyDelta(target, delta);
if (next == 0) {
NonzeroDeltaCount.decrement();
} else if (previous == 0) {
NonzeroDeltaCount.increment();
}
}
(アドレス, 通貨) ごとの差分は、transient storage に置かれる(CurrencyDelta.sol L28-L41 の tload / tstore)。ゼロでない差分の個数も同じだ(NonzeroDeltaCount.sol)。
どちらも、トランザクションの終わりで消える。
だから unlock は、カウンタ 1 つがゼロかどうかを見るだけで済む。
符号は、どちら向きなのか。呼び出し元から見たものだ。swap が返すのは「the balance delta of the address swapping」(swap した者の残高差分、IPoolManager.sol L159)だ。
- 負なら、呼び出し元が
PoolManagerに借りがある。 - 正なら、
PoolManagerが呼び出し元に借りがある。
入力額を固定する swap(exact input)は、amountSpecified を負で渡す(L149)。
なぜ、送金の前に sync が要るのか
精算に使う呼び出しは 3 つある。
take(currency, to, amount)(L289-L295)は、トークンを送り出し、呼び出し元の差分に-amountを足す。正の差分を消す。sync(currency)(L277-L286)は、その通貨のPoolManagerの現在残高を記録する。settle()(L298-L300、本体は_settleL347-L363)は、sync以降に入ってきた分を呼び出し元に計上する。
uint256 reservesBefore = CurrencyReserves.getSyncedReserves();
uint256 reservesNow = currency.balanceOfSelf();
paid = reservesNow - reservesBefore;
CurrencyReserves.resetCurrency();
...
_accountDelta(currency, paid.toInt128(), recipient);
だから順序は sync → 送金 → settle だ。
settle には、誰がトークンを送ったかは見えない。前回の sync から残高が増えたことしか分からない。
インターフェースも、sync は「MUST be called before any ERC20 tokens are sent into the contract」(ERC20 トークンを送り込む前に必ず呼ぶ、IPoolManager.sol L183-L186)と書いている。
(注:ネイティブ通貨の場合、settle は代わりに msg.value を数える。)
トークンを動かさずに差分に触れる呼び出しが、あと 2 つある。ERC-6909 のクレームの mint と burn だ(L320-L335)。
クレームを mint すると借りが増え、burn すると貸しが増える。下で Shadowbook が使う。
Summon の swap ルーターを呼び出し順に
SummonSwap.swapExactIn(src/SummonSwap.sol L56-L64)は、まず対象が Summon のラウンドが作ったプールであることを確かめる。それから依頼をまとめて unlock する。
amountOut = abi.decode(poolManager.unlock(abi.encode(Call(msg.sender, key, zeroForOne, amountIn, minOut, to))), (uint256));
実際の処理は、コールバックの中にある(L66-L90、抜粋)。
function unlockCallback(bytes calldata data) external returns (bytes memory) {
if (msg.sender != address(poolManager)) revert NotPoolManager();
Call memory c = abi.decode(data, (Call));
BalanceDelta delta = poolManager.swap(c.key, IPoolManager.SwapParams({
zeroForOne: c.zeroForOne,
amountSpecified: -int256(uint256(c.amountIn)),
sqrtPriceLimitX96: c.zeroForOne ? TickMath.MIN_SQRT_PRICE + 1 : TickMath.MAX_SQRT_PRICE - 1
}), "");
(Currency cin, Currency cout) = c.zeroForOne ? (c.key.currency0, c.key.currency1) : (c.key.currency1, c.key.currency0);
(int128 dIn, int128 dOut) = c.zeroForOne ? (delta.amount0(), delta.amount1()) : (delta.amount1(), delta.amount0());
// a price limit can stop a swap early; the caller pays only what the pool took
uint256 paid = uint256(uint128(-dIn));
uint256 out = uint256(uint128(dOut));
if (out < c.minOut) revert TooLittleReceived(out, c.minOut);
poolManager.sync(cin);
if (!IERC20Pull(Currency.unwrap(cin)).transferFrom(c.payer, address(poolManager), paid)) revert TransferFailed();
poolManager.settle();
poolManager.take(cout, c.to, out);
return abi.encode(out);
}
上の符号の決まりどおり、-dIn がルーターの払うべき額、dOut が受け取れる額だ。
ほかに、見ておきたい点が 3 つある。
msg.sender の確認。 unlockCallback は誰でも呼べる。だからルーターは、PoolManager からの呼び出しだけを受け付ける。
ルーターは何も持たない。 入力はユーザーから直接 PoolManager へ送られる(transferFrom(c.payer, address(poolManager), paid))。だからルーターは「Holds nothing between calls」(呼び出しの間に何も持たない、L22-L25)。
スリッページの確認は、支払いより前にある。 失敗すれば、unlock 全体が revert する。
Summon は、1 回の unlock でプールを作って流動性を入れる
ラウンドが約定すると、USDC と株の一部がプールの初期流動性になる(src/SummonRound.sol L315):_seed(qLp, usdcLp)。
_seed(L465-L468)は、操作コードをつけて unlock する。
bytes memory r = IPoolManager(d.poolManager).unlock(abi.encode(OP_SEED, tokenAmt, usdcAmt));
ラウンドの unlockCallback(L413-L436)は、seed・unwind・realign の 3 つの操作を受け持つ。
seed では、同じコールバックの中でプールを作り、ポジションを入れる。
if (op == OP_SEED) {
uint160 sqrtP = tokenIs0 ? SummonPool.sqrtPriceX96(a, b) : SummonPool.sqrtPriceX96(b, a);
pm.initialize(key, sqrtP);
(uint256 tokenUsed, uint256 usdcUsed, uint128 l) = _addFullRange(pm, key, sqrtP, a, b);
return abi.encode(tokenUsed, usdcUsed, l);
}
「initialize にロックは要らないのでは?」と思うかもしれない。そのとおりだ。
それでもここで呼ぶことで、プールは最初のポジションと一緒に、1 つのトランザクションの中でだけ生まれる。
_addFullRange(L438-L451)は modifyLiquidity を呼び、負の差分を _settleOwed(L470-L476)で 1 つずつ払う。
function _settleOwed(IPoolManager pm, Currency c, int128 amount) internal returns (uint256 paid) {
if (amount >= 0) return 0;
paid = uint256(uint128(-amount));
pm.sync(c);
_push(Currency.unwrap(c), address(pm), paid);
pm.settle();
}
逆向きは unwindLP(L357-L370)だ。ポジションを外し、正の差分を _takeOwed(L478-L482)の take で受け取る。
hook も、同じ会計に加わる
hook は、呼び出し元の unlock の中で動く。だから差分を作ることも、消すこともできる。
Shadowbook は beforeSwap で、swap を自分の在庫から約定させる(src/Shadowbook.sol L232-L265)。
- 入力分は、自分に ERC-6909 のクレームを mint する(
poolManager.mint(address(this), cin.toId(), amountIn)、L257)。 - 出力分は、クレームを burn するか、実際のトークンを settle して払う(
_payOutと_settle、L285-L300)。
なぜ入力がクレームとして届くのか。理由はコントラクトのコメントにある(L31-L33):「the swapper settles after the hook returns, so the manager holds no real tokens yet」(swap する側は hook が戻ったあとで settle するので、その時点の manager はまだ実際のトークンを持っていない)。
hook が自分の差分を swap する側へどう渡すかは、後のレッスンで扱う。
ここでは、同じ規則が成り立つことだけ押さえてほしい。unlock の終わりには、すべての差分がゼロだ。
演習:実際のトレースで swap と初期流動性の投入を読む
d4debb7 の summon-stocks で、ラウンドを約定させてそのプールで swap するテスト(test/SummonRound.t.sol L847-L879)を、フルトレースつきで走らせる。
git checkout d4debb7 && git submodule update --init --recursive # if your checkout moved on
forge test --mt test_swapOnSummonedPool -vvvv
トレースは約 400 行ある。
まず、初期流動性の投入を探す。SummonRound::fill の下にある、最初の PoolManager::unlock だ。実際の出力を呼び出しだけに絞り、長い引数は … で切った。
├─ [564750] SummonRound::fill{value: 1}(…)
│ ├─ [300767] PoolManager::unlock(0x…01…01fc5aed09…77359400)
│ │ ├─ [298533] SummonRound::unlockCallback(…)
│ │ │ ├─ [41738] PoolManager::initialize(PoolKey({ currency0: 0x5991…76A9, currency1: 0xc718…0bB1, fee: 8388608, tickSpacing: 60, hooks: 0x0500000000000000000000000000000000002880 }), 38366396192605457038975870283)
│ │ │ │ ├─ [8787] 0x0500…2880::beforeInitialize(SummonRound: […], …)
│ │ │ ├─ [168519] PoolManager::modifyLiquidity(…, ModifyLiquidityParams({ tickLower: -887220, tickUpper: 887220, liquidityDelta: 4130081028, … }), 0x)
│ │ │ │ ├─ [2320] 0x0500…2880::beforeAddLiquidity(SummonRound: […], …)
│ │ │ ├─ [4105] PoolManager::sync(MockB20: [0x5991…76A9])
│ │ │ ├─ [23483] MockB20::transfer(PoolManager: […], 8528784649)
│ │ │ ├─ [2831] PoolManager::settle()
│ │ │ │ └─ ← [Return] 8528784649
│ │ │ ├─ [3995] PoolManager::sync(MockERC20: [0xc718…0bB1])
│ │ │ ├─ [21022] MockERC20::transfer(PoolManager: […], 2000000000)
│ │ │ ├─ [2721] PoolManager::settle()
│ │ │ │ └─ ← [Return] 2000000000
続いて最初の swap。alice が 100 USDC(100000000、小数 6 桁)を売って株を買う場面だ。
├─ [101504] SummonSwap::swapExactIn(…, false, 100000000, 1, 0x…0A11cE)
│ ├─ [498] SummonFactory::roundForPool(0x44765c…bc68) [staticcall]
│ ├─ [94722] PoolManager::unlock(…)
│ │ ├─ [92488] SummonSwap::unlockCallback(…)
│ │ │ ├─ [56353] PoolManager::swap(…, SwapParams({ zeroForOne: false, amountSpecified: -100000000, … }), 0x)
│ │ │ │ ├─ [17430] 0x0500…2880::beforeSwap(SummonSwap: […], …)
│ │ │ │ │ └─ ← [Return] 0x575e24b4, 0, 4197304
│ │ │ │ ├─ emit Swap(id: 0x44765c…bc68, sender: SummonSwap: […], amount0: 404972057, amount1: -100000000, …)
│ │ │ ├─ [1995] PoolManager::sync(MockERC20: [0xc718…0bB1])
│ │ │ ├─ [1381] MockERC20::transferFrom(0x…0A11cE, PoolManager: […], 100000000)
│ │ │ ├─ [2721] PoolManager::settle()
│ │ │ │ └─ ← [Return] 100000000
│ │ │ ├─ [25215] PoolManager::take(MockB20: [0x5991…76A9], 0x…0A11cE, 404972057)
コードと照らし合わせて読む。
unlock→unlockCallback→swap→ hook のbeforeSwap。hook は、呼び出し元の unlock の中で動いている。Swapイベントは、呼び出し元から見た swap の差分を載せている(emit Swap(id, msg.sender, delta.amount0(), delta.amount1(), …)、PoolManager.sol L239-L248)。ルーターが払うべき USDC が-100000000、受け取れる株が+404972057だ。settleはちょうど100000000を返し、takeはちょうど404972057を送る。両方の差分がゼロに戻るので、unlockは戻れる。- hook は手数料として
4197304を返した。これは3000 | 0x400000、つまり 0.30% にLPFeeLibrary.OVERRIDE_FEE_FLAG(LPFeeLibrary.sol L19)を立てた値だ。手数料のルールは後のレッスンで扱う。
次に、壊してみる。
手元の checkout ではなく、作業用のコピーでやってほしい。ルーターの settle をコメントアウトする。
# from the directory that holds your summon-stocks checkout (at d4debb7)
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
sed -i '' 's/^ poolManager.settle();$/ \/\/ poolManager.settle();/' src/SummonSwap.sol # GNU sed: sed -i without ''
forge test --mt test_swapOnSummonedPool -vvv
実際の出力はこうだ。
[FAIL: CurrencyNotSettled()] test_swapOnSummonedPool() (gas: 1975125)
│ │ └─ ← [Revert] CurrencyNotSettled()
│ └─ ← [Revert] CurrencyNotSettled()
└─ ← [Revert] CurrencyNotSettled()
「USDC は送ったのに、なぜ落ちるのか」と思うかもしれない。
USDC は PoolManager に届いている。でも settle がないので、計上されていない。
コールバックが戻った時点で、ルーターの USDC の差分は負のままだ。だから unlock は L111 で revert する。
編集は git checkout -- src で戻してほしい。
確認すること
- 自分のトレースの中で
unlock→unlockCallback→swap/modifyLiquidity→sync→ 送金 →settle→takeを見つけた。 -
syncが送金より前に来なければならない理由と、それがなければsettleが何を計上してしまうかを言える。 -
SummonSwap.unlockCallbackがmsg.senderを確かめる理由を説明できる。 -
settleを 1 つ外すとCurrencyNotSettled()になり、戻すとテストが再び通ることを確かめた。