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

新しい市場を作る · Uniswap v4

このコースの 2 / 935 分

レッスン2 — PoolManager、unlock とフラッシュ会計

出典: Uniswap/v4-core v4.0.0、psyto/summon-stocks d4debb7、fabrknt/shadowbook 7d07439。

読了目安:約 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、本体は _settle L347-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)

コードと照らし合わせて読む。

  1. unlock → unlockCallback → swap → hook の beforeSwap。hook は、呼び出し元の unlock の中で動いている。
  2. Swap イベントは、呼び出し元から見た swap の差分を載せている(emit Swap(id, msg.sender, delta.amount0(), delta.amount1(), …)、PoolManager.sol L239-L248)。ルーターが払うべき USDC が -100000000、受け取れる株が +404972057 だ。
  3. settle はちょうど 100000000 を返し、take はちょうど 404972057 を送る。両方の差分がゼロに戻るので、unlock は戻れる。
  4. 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() になり、戻すとテストが再び通ることを確かめた。