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

新しい市場を作る · Uniswap v4

このコースの 6 / 940 分

レッスン6 — 変わる手数料

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

Shadowbook は、自分の v4-periphery の中の v4-core(59d3ecf、v4.0.0 から 12 コミット後)でビルドする。そこでも LPFeeLibrary.sol と Pool.sol は同じで、Hooks.sol と PoolManager.sol の違いは swap と流動性のパラメータ構造体の置き場所(types/PoolOperation.sol)だけだ。以下の v4-core の行は v4.0.0 で引く。

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

同じプール、同じ hook なのに、ある swap は 102 bp、次の swap は 30 bp を払う

ふつう、プールの LP 手数料はキーに固定されている。

例外は、キーの手数料が動的手数料のフラグ 0x800000 のときだ。そのプールは手数料 0 で始まり、hook が手数料を決める。方法は 2 つある。

  • updateDynamicLPFee で保存する
  • beforeSwap から上書きのフラグ 0x400000 つきで返して、その swap だけに使わせる

v4-core が返された手数料を使うのは、動的手数料のプールでフラグが立っているときだけだ。100% を超えれば revert する。

これを使う hook を 2 つ読む。

Summon は、株の市場の状態から 0.30% か 1.00% を返す。

Shadowbook の DirectionalFee は、プールの価格を keeper が送る参照価格に近づける swap に、高い手数料を返す。

なぜ、そういう swap から多く取るのか?

LP の古い気配を取っていくのが、そういう swap だからだ。

このレッスンでは両方を読み、実際のトレースから手数料を読み取る。トレースでは、ある swap が 10200 pips(102 bp)、次の swap が 3000(30 bp)を払う。

  • プールが動的手数料になる仕組みと、hook が何もしないうちの手数料
  • hook が手数料を決める 2 つの方法と、beforeSwap から返された手数料に v4-core が適用する規則
  • Summon の 2 つの手数料と、それぞれが適用されるとき
  • DirectionalFee:コードが定義するとおりのパラメータ、向きと距離の測り方、保証していること
  • swap が実際に払った手数料をどこで見るか

プールの手数料は、何で「動的」になるのか

フラグと上限は LPFeeLibrary にある(libraries/LPFeeLibrary.sol L14-L25):

/// @notice An lp fee of exactly 0b1000000... signals a dynamic fee pool. This isn't a valid static fee as it is > MAX_LP_FEE
uint24 public constant DYNAMIC_FEE_FLAG = 0x800000;

/// @notice the second bit of the fee returned by beforeSwap is used to signal if the stored LP fee should be overridden in this swap
// only dynamic-fee pools can return a fee via the beforeSwap hook
uint24 public constant OVERRIDE_FEE_FLAG = 0x400000;

/// @notice mask to remove the override fee flag from a fee returned by the beforeSwaphook
uint24 public constant REMOVE_OVERRIDE_MASK = 0xBFFFFF;

/// @notice the lp fee is represented in hundredths of a bip, so the max is 100%
uint24 public constant MAX_LP_FEE = 1000000;

手数料の単位は、1 ベーシスポイントの 100 分の 1(「pips」)だ。3000 が 0.30%、1_000_000 が 100%。

キーの fee がちょうど 0x800000 なら、そのプールは動的だ。レッスン1 と 3 で見たとおり、initialize は手数料 0 で始め(getInitialLPFee)、hook がなければ拒む(isValidHookAddress)。

フラグを必須にしたい hook は、beforeInitialize で確かめられる。DirectionalFee はそうしている:if (!LPFeeLibrary.isDynamicFee(key.fee)) revert NotDynamicFee();(src/DirectionalFee.sol L194)。

Summon に、この検査は要らない。ラウンドはフラグである SummonPool.FEE でキーを組み立て、初期化できるのはラウンドだけだからだ(レッスン4)。

hook は手数料をどう決めるのか:方法は 2 つ

1 つ目:保存する。

hook が updateDynamicLPFee を呼ぶ(PoolManager.sol L337-L344):

function updateDynamicLPFee(PoolKey memory key, uint24 newDynamicLPFee) external {
    if (!key.fee.isDynamicFee() || msg.sender != address(key.hooks)) {
        UnauthorizedDynamicLPFeeUpdate.selector.revertWith();
    }
    newDynamicLPFee.validate();
    PoolId id = key.toId();
    _pools[id].setLPFee(newDynamicLPFee);
}

呼べるのは、そのプールの hook だけだ。手数料は、hook が次に変えるまで残る。unlock は要らない(レッスン2)。

2 つ目:swap ごとに返す。

beforeSwap は、3 つ目の戻り値として手数料を返す。PoolManager がそれを読むのは、動的手数料のプールのときだけだ(libraries/Hooks.sol L260-L262):

// dynamic fee pools that want to override the cache fee, return a valid fee with the override flag. If override flag
// is set but an invalid fee is returned, the transaction will revert. Otherwise the current LP fee will be used
if (key.fee.isDynamicFee()) lpFeeOverride = result.parseFee();

そして swap がそれを使うのは、上書きのフラグが立っているときだけだ(libraries/Pool.sol L300-L308):

// if the beforeSwap hook returned a valid fee override, use that as the LP fee, otherwise load from storage
// lpFee, swapFee, and protocolFee are all in pips
{
    uint24 lpFee = params.lpFeeOverride.isOverride()
        ? params.lpFeeOverride.removeOverrideFlagAndValidate()
        : slot0Start.lpFee();

    swapFee = protocolFee == 0 ? lpFee : uint16(protocolFee).calculateSwapFee(lpFee);
}

removeOverrideFlagAndValidate はフラグのビットを落として validate を呼ぶ。MAX_LP_FEE を超えていれば、LPFeeTooLarge(fee) で revert する(LPFeeLibrary.sol L41-L45、L72-L78)。

まとめると、こうなる。

hook が返すもの固定手数料のプール動的手数料のプール
0x400000 のない手数料無視無視され、保存された手数料を使う
0x400000 つきで、フラグを落とすと 1_000_000 以下無視この swap に使う。何も保存しない
0x400000 つきで、フラグを落とすと 1_000_000 超無視swap が LPFeeTooLarge で revert

「大きすぎる手数料は、読み飛ばされるだけでは?」と思うかもしれない。

IHooks を読むと、そう見える。返す手数料を「only used if three conditions are met」(3 つの条件を満たすときだけ使われる)と説明し、3 つ目を「the value is less than or equal to the maximum fee (1 million)」(値が上限の 100 万以下)としている(interfaces/IHooks.sol L102)。

でも、最後の行は正確に押さえてほしい。フラグが立っていれば、大きすぎる値は読み飛ばされない。上の Hooks.sol のコメントのとおり、swap が revert する。

(注:LP 手数料に加えて、プールにはプロトコル手数料がありうる。swapFee は両者を合わせたもので、Swap イベントの最後のフィールドはこの swapFee だ(PoolManager.sol L239-L248)。両プロジェクトのテストでプロトコル手数料を設定するのは DirectionalFee の 1 件だけなので、下のトレースではイベントの fee が LP 手数料だ。)

Summon も DirectionalFee も、swap ごとに返す方法を使う。updateDynamicLPFee は呼ばない。だから、プールに保存された手数料は 0 のままだ。

レッスン3 の演習 B で、hook が BEFORE_SWAP を失ったプールが手数料 0 で取引されたのは、このためだ。

Summon:0.30% か 1.00%、それだけ

定数はこうだ(src/SummonPool.sol L16-L17):

uint24 internal constant OPEN_FEE = 3000; // 0.30%, while the listing exchange is open
uint24 internal constant CLOSED_FEE = 10_000; // 1.00%, while it is closed or the guard is quiet

beforeSwap は fee | LPFeeLibrary.OVERRIDE_FEE_FLAG を返す(src/SummonHook.sol L84)。どちらを返すかは、_swapFee の最後の 2 行が選ぶ(L111-L113):

// 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;

ここに来た時点で、s.halted は取引時間外しかありえない。それ以外の停止は、規則 3(レッスン5)がすでに拒んでいる。

realign の中のラウンド自身の swap は、常に OPEN_FEE だ。

手数料は、swap そのものには左右されない。大きさにも、向きにも。

test_swapFeeRisesWhileClosed(test/SummonRound.t.sol L909-L924)は、同じスナップショットから 100 USDC で 3 回買う。

  1. 取引時間中
  2. 取引時間外と記録したあと
  3. guard が 301 秒黙ったあと

時間外の買いを、取引時間中の買いと assertApproxEqRel(closed * 1e18 / open, uint256(990_000e18) / 997_000, 1e15) で比べる。

この比はどこから来るのか。0.30% ではなく 1.00% なら、受け取りは 990,000/997,000 倍になる。それを 0.1% の誤差で確かめている。

DirectionalFee:参照価格に近づける swap ほど高い

DirectionalFee は Shadowbook の 2 つ目の hook で、ふつうの流動性プール向けだ。コントラクトのコメントが規則を述べている(src/DirectionalFee.sol L20-L26):

/// A swap whose direction moves the pool price toward the reference pays `towardFloor` or `slope`
/// times the distance, whichever is more, up to `maxFee`: those are the swaps that take the LPs'
/// stale quotes. A swap in the other direction, and every swap while the reference is missing or
/// older than `maxAge`, pays `baseFee`. Direction and distance are taken from the pool price
/// before the swap, and one fee applies to the whole swap: a swap large enough to cross the
/// reference pays the toward fee on all of it, including the part past the reference. The fee
/// never depends on the swap's size, so `getFee` quotes it exactly.

(プールの価格を参照価格に近づける向きの swap は、towardFloor と「slope × 距離」の大きい方を、maxFee を上限に払う。LP の古い気配を取っていくのはこうした swap だからだ。逆向きの swap と、参照価格がないか maxAge より古いあいだのすべての swap は baseFee を払う。向きと距離は swap 前のプール価格で決まり、swap 全体に 1 つの手数料がかかる。参照価格を越えるほど大きい swap は、越えた部分も含めて全体に近づける向きの手数料を払う。手数料は swap の大きさに左右されないので、getFee は正確な値を示せる。)

参照価格は、プール自身の単位での平方根価格だ。keeper がそれを観測した時刻と、通し番号がつく。

keeper は setRef(sqrtPriceX96, asOf, seq) で送る。未来の・古すぎる・順番が逆の更新は拒まれる(L114-L126)。

パラメータは、コードでこう宣言されている(L54-L58):

uint24 public baseFee; // away from the reference, and whenever the reference is unusable
uint24 public towardFloor; // least a swap toward the reference pays
uint24 public slope; // fee per bp of distance, in hundredths of a bp: 100 = 1x the distance
uint24 public maxFee; // most any swap pays
uint32 public maxAge; // seconds

決めるのはオーナーだ。_setFees は baseFee <= towardFloor <= maxFee <= MAX_FEE(MAX_FEE = 50_000、5%)を求める(L135-L141、L37):「a swap toward the reference never pays less than one away from it」(近づける swap が遠ざける swap より安くなることはない)。

手数料そのものはこうだ(L163-L172):

/// zeroForOne lowers the pool price, so it moves toward a reference below the pool price.
function _fee(uint160 sqrtPriceX96, bool zeroForOne) internal view returns (uint24) {
    Ref memory r = ref;
    if (r.updatedAt == 0 || block.timestamp - r.updatedAt > maxAge) return baseFee;
    if (zeroForOne ? sqrtPriceX96 <= r.sqrtPriceX96 : sqrtPriceX96 >= r.sqrtPriceX96) return baseFee;
    uint256 f = _distBps(sqrtPriceX96, r.sqrtPriceX96) * slope;
    if (f < towardFloor) f = towardFloor;
    if (f > maxFee) f = maxFee;
    return uint24(f);
}

beforeSwap は、PoolManager からプールの今の価格を読み、これを上書きのフラグつきで返す(L199-L209):

function beforeSwap(address, PoolKey calldata key, SwapParams calldata params, bytes calldata)
    external
    view
    onlyPoolManager
    returns (bytes4, BeforeSwapDelta, uint24)
{
    if (PoolId.unwrap(key.toId()) != PoolId.unwrap(poolId)) revert WrongPool();
    (uint160 sqrtPriceX96,,,) = poolManager.getSlot0(poolId);
    uint24 fee = _fee(sqrtPriceX96, params.zeroForOne);
    return (IHooks.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, fee | LPFeeLibrary.OVERRIDE_FEE_FLAG);
}

距離は、|P / R − 1| をベーシスポイントで表したものだ。2 つの平方根価格から計算する(d = |p / r − 1| として、参照価格より上なら 2d + d²、下なら 2d − d²)。

手数料が LP に有利な側にずれるよう切り上げ、50,000 bp で頭打ちにする(_distBps、L174-L187)。

「とんでもない価格が来たら、beforeSwap が revert するのでは?」と思うかもしれない。

しない。頭打ちがあるので「距離 × slope」はあふれない。そして maxFee が 5% 以下なので、結果は v4-core にとって有効な値だ。

README の言葉では「no price or parameter can make beforeSwap revert」(どんな価格やパラメータでも beforeSwap は revert しない)、「Swaps are never refused」(swap が拒まれることはない)だ(README L147-L152)。

テストは、デモの既定値(「30 bp base and floor, 1× the distance, at most 300 bp」、基本と下限が 30 bp、距離の 1 倍、上限 300 bp、README L156)に、60 秒の maxAge を使う(test/DirectionalFee.t.sol L23-L27):

uint24 constant BASE = 3_000; // 30 bp
uint24 constant FLOOR = 3_000; // 30 bp
uint24 constant SLOPE = 100; // 1x the distance
uint24 constant MAXF = 30_000; // 300 bp
uint32 constant MAX_AGE = 60;

slope の単位は、距離 1 ベーシスポイントあたりの pips だ。100 なら、1 bp 動かすと手数料も 1 bp。

例で見る。プールが 1:1 で、参照価格が 1% 下にあるとする。

  • token0 を売る swap は価格を参照価格に近づけ、約 101 bp を払う。
  • token0 を買う swap は、基本の 30 bp だ。

テストはこうだ(L107-L114):

function test_refBelow_sellingToken0IsToward() public {
    _ref(_sqrtAt(-100)); // reference 1% below the pool
    (uint24 down, uint24 up) = hook.getFee(key);
    assertEq(up, BASE, "away");
    assertApproxEqAbs(down, 10_100, 100, "toward: 1x of 101 bp (1 / 0.99 - 1)");
    assertEq(_swapFee(true), down);
    assertEq(_swapFee(false), BASE);
}

_swapFee は実際に swap し、手数料を hook からではなく PoolManager の Swap イベントから読み戻す(L78-L95)。だからこのテストは、swap が実際に払った額を確かめている。

keeper が間違えたらどうなるのか。README は信頼の前提をこう書いている:「Given those, a wrong or compromised keeper cannot make the pool worse for LPs than a plain pool at baseFee: a bad reference only moves swaps between baseFee and a higher fee.」

(それらが与えられれば、keeper が間違っても乗っ取られても、LP にとってプールが baseFee のふつうのプールより悪くなることはない。悪い参照価格は swap を baseFee とそれより高い手数料のあいだで動かすだけだ、README L153-L155。)

並べると、情報源が黙ったときの動きが正反対だ

SummonDirectionalFee
入力株の市場の状態keeper の参照価格に対するプールの価格
手数料0.30% か 1.00%baseFee、または max(towardFloor, slope × 距離) を maxFee まで
向きで変わるか変わらない変わる
情報源が古いとき高い方(1.00%)低い方(baseFee)
swap を拒むか拒む(レッスン5 の場合)拒まない

4 行目を見てほしい。外の情報源が黙ったときの既定が、逆になっている。

Summon は、何かおかしいかもしれないとみて高く取る。

DirectionalFee は、ふつうのプールに戻る。信用できない参照価格のせいで、誰かが多く払うべきではないからだ。

演習:トレースから手数料を読む

DirectionalFee。 7d07439 の shadowbook の checkout で:

forge test --mt test_refBelow_sellingToken0IsToward -vv
forge test --mt test_refBelow_sellingToken0IsToward -vvvv | grep -E "::getFee|Return\] 10200|0x575e24b4|emit Swap"

-vv で出るのは [PASS] test_refBelow_sellingToken0IsToward() (gas: 445329) だけだ。

なぜこれだけなのか。テストも hook も何もログに出さず、Foundry は通ったテストのトレースを -vvvv からしか出さないからだ。

2 つ目のコマンドの出力はこうだ(forge 1.7.1、2026-11-14)。キー・id・アドレスは … で切り、イベントの後半は省いた。

├─ [17745] 0x4444000000000000000000000000000000002080::getFee(PoolKey(…)) [staticcall]
│   └─ ← [Return] 10200 [1.02e4], 3000
│   │   │   │   │   └─ ← [Return] 0x575e24b4, 0, 4204504 [4.204e6]
│   │   │   │   ├─ emit Swap(id: 0x13806e…, sender: PoolSwapTest: […], amount0: -1000000000000 [-1e12], amount1: 989799020296 [9.897e11], …, fee: 10200 [1.02e4])
│   │   │   │   │   └─ ← [Return] 0x575e24b4, 0, 4197304 [4.197e6]
│   │   │   │   ├─ emit Swap(id: 0x13806e…, sender: PoolSwapTest: […], amount0: 997000979651 [9.97e11], amount1: -1000000000000 [-1e12], …, fee: 3000)

コードと照らして読む。

  1. getFee は、近づける向きを 10200(102 bp。101.01 bp を _distBps が切り上げた値)、遠ざける向きを 3000 と示す。
  2. 1 つ目の swap は token0 を売る(amount0 が負:swap する側が token0 を払う)。hook は 10200 | 0x400000 である 4204504 を返し、Swap イベントには fee: 10200 と記録される。
  3. 2 つ目の swap は token0 を買う。hook は 3000 | 0x400000 である 4197304 を返し、イベントには fee: 3000 と記録される。

Summon。 b1dd190 の summon-stocks の checkout で:

forge test --mt test_swapFeeRisesWhileClosed -vvvv | grep -E "0x575e24b4|emit Swap\(|setState|VM::warp"

同じように切り詰めた出力だ。

├─ [0] VM::warp(1800000060 [1.8e9])
│   │   │   │   │   └─ ← [Return] 0x575e24b4, 0, 4197304 [4.197e6]
│   │   │   │   ├─ emit Swap(id: 0x44765c…, sender: SummonSwap: […], amount0: 404972057 [4.049e8], amount1: -100000000 [-1e8], …, fee: 3000)
├─ [3722] MarketStateRegistry::setState(MockB20: […], true, 3, 0)
│   │   │   │   │   └─ ← [Return] 0x575e24b4, 0, 4204304 [4.204e6]
│   │   │   │   ├─ emit Swap(id: 0x44765c…, sender: SummonSwap: […], amount0: 402262830 [4.022e8], amount1: -100000000 [-1e8], …, fee: 10000 [1e4])
├─ [0] VM::warp(1800000361 [1.8e9])
│   │   │   │   │   └─ ← [Return] 0x575e24b4, 0, 4204304 [4.204e6]
│   │   │   │   ├─ emit Swap(id: 0x44765c…, sender: SummonSwap: […], amount0: 402262830 [4.022e8], amount1: -100000000 [-1e8], …, fee: 10000 [1e4])

100 USDC の買いが 3 回。

  • 取引時間中: 3000 で、株を 404972057 単位(レッスン2 と同じ数字)。
  • 取引時間外(setState(…, true, 3, 0)、理由 3):10000 で 402262830。
  • guard が黙ったとき: 再び 10000 で、同じ 402262830。時計が guard の最後の heartbeat から 301 秒進んだ。heartbeat は _fillAfter が約定のときに送ったもので、maxGuardAge は 300 だ。

手数料を変えて、どのテストが気づくかを見る。 作業用のコピーで、checkout がある場所から:

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/CLOSED_FEE = 10_000;/CLOSED_FEE = 5_000;/' src/SummonPool.sol   # GNU sed: sed -i without ''
forge test --mc SummonRoundTest
[FAIL: assertion failed: 998089050869996198 !~= 992978936810431293 (max delta: 0.1000000000000000%, real delta: 0.5146246179177990%)] test_swapFeeRisesWhileClosed() (gas: 2111754)
Suite result: FAILED. 51 passed; 1 failed; 0 skipped; …

992978936810431293 は、990,000/997,000 を 1e18 単位で表したもので、テストが期待する比だ。0.50% では、時間外の買いは時間中の 0.998 倍だった。

時間外の手数料を固定しているテストは、これだけだ。git checkout -- src で戻す。

DirectionalFee でも、同じことができる。

shadowbook の新しいコピー(rm -rf /tmp/shadowbook-scratch && cp -R shadowbook /tmp/shadowbook-scratch && rm -rf /tmp/shadowbook-scratch/cache/fuzz)で、_fee の if (f < towardFloor) f = towardFloor; をコメントアウトする。そして forge test --mc DirectionalFeeTest を走らせる。

毎回新しいコピーで 6 回走らせた。5 回は 19 passed; 2 failed だった。

  • [FAIL: assertion failed: 600 != 3000] test_nearRef_towardPaysFloor()。5 bp 離れた参照価格は切り上げで 6 bp と測られ、1 倍で 600。下限の 3000 を下回る。
  • testFuzz_feeFormula。走らせるたびに反例が変わる。

fuzz の当たり方は毎回違う。fuzz の参照価格がたまたまプール価格から 30 bp 以内に落ちると、testFuzz_feeWithinBounds も失敗する(以前の私たちの実行ではそうなった)。6 回のうち 1 回は、下に書く別の理由で 3 件目が失敗した。

git checkout -- src で戻す。

固定した版の不安定なテスト(2026-11-14)。

7d07439 の testFuzz_distance は、2 つの平方根価格を [2**64, 2**128](両端を含む)に収めてから 2 乗する。だから、ちょうど 2**128 のとき桁あふれする。

そのため、ときどき単独で panic: arithmetic underflow or overflow (0x11) で失敗する。hook の _distBps は関係ない。

Forge は fuzz の失敗を cache/fuzz/ に保存し、同じディレクトリでの後の実行で再生する。このコースの作業用コピーがどれも cache/fuzz を消しているのは、そのためだ。

Shadowbook は 7ae1dd1 でこの範囲を直した(2 ** 128 - 1)。このレッスンは 7d07439 のままだ。

確認すること

  • 動的手数料のプールの、hook が何もしないうちの手数料と、hook がそれを変える 2 つの方法を言える。
  • 4197304、4204304、4204504 をフラグと手数料に分けられる。
  • 返した手数料が上書きのフラグなしのとき、固定手数料のプールのとき、1,000,000 を超えるときに何が起きるかを言える。
  • 参照価格がプールより下のとき DirectionalFee がどちらの向きに高く取るか、テストの設定で参照価格が 61 秒前のものなら何を取るかを言える。
  • 自分のトレースの Swap イベントで fee: 3000、fee: 10000、fee: 10200 を読み、Summon の時間外の手数料を変えるとそれを固定しているテストが失敗するのを見た。

次のレッスン7 は、手数料の先に進む。swap の値段を自分で決め、自分の在庫で約定させる hook を、beforeSwapReturnDelta とともに読む(Shadowbook)。