Hooks / Order flow and MEV

MarkoutFee

A fee that learns. The pool measures whether its own past trades turned out to be informed, and charges the next one accordingly.

MarkoutFee implements 3 of the fourteen Uniswap v4 callbacks: afterInitialize, beforeSwap, afterSwap.

How it works

Every dynamic-fee hook published so far prices a swap from something observable at the moment it arrives: the size, the recent volatility, the gas it bid, the distance from an oracle. All of those are proxies for the question that actually matters, which is whether the person on the other side knew something. None of them measure it, because at the moment a swap arrives that fact has not happened yet.

It has happened a few seconds later. If a swap pushed the price down and the price kept falling, the seller was right and the liquidity that filled them lost; that is an informed trade, and it is the cost the LP literature calls adverse selection. If the price came back, the swap was noise and the fee it paid was pure revenue.

This is the markout that every market maker computes on their own flow, and a pool has everything needed to compute it: the tick it was left at, and the tick it is at now. So this hook grades each swap after the fact. On the next swap it compares the current tick to the tick the previous swap left behind, decides whether that swap was informed, and folds the verdict into an exponentially weighted average.

The fee it quotes is: fee = baseFee + maxSurcharge * toxicity A pool whose flow is mostly retail converges toward `baseFee` and becomes cheap. A pool being picked off converges toward the cap and becomes expensive, without anybody deciding that, and without an oracle to manipulate or a governance process to capture. The score is public, so anything else on-chain can read a pool's measured toxicity rather than guessing at it.

Two details keep the measurement honest. A verdict is only recorded once `minHorizon` seconds have passed, because a comparison inside the same block is measuring the swap's own price impact rather than what happened next. And the verdict is graded by magnitude rather than treated as a coin flip: a move that continues by a tenth of a tick is weak evidence, a move that continues by a hundred ticks is strong, so the observation is scaled and clamped instead of being rounded to a yes or a no.

{FlowClassifierHook} measures a related quantity and deliberately does nothing with it; this hook is the other half of that pair, the one that acts on what it measures. The hook takes no fee for itself, custodies nothing, and has no privileged role. `baseFee`, the cap, the smoothing and the horizon are fixed before the pool exists and can never be changed.

Prior art

Dynamic fees keyed on realized volatility, swap size, price movement or an oracle gap are all well covered, and markout is the standard way a market maker grades its own flow off-chain. Computing markout on-chain, from the pool's own tick history, and feeding it back as the pool's fee, is the contribution here. It is the difference between reacting to a proxy for adverse selection and measuring the thing itself.

Where it does not help

The verdict on a swap arrives with the next swap, so a pool that trades once a day prices today's flow on yesterday's evidence, and a pool with no second swap never grades the first. It is a lagging signal by construction: a regime change is paid for at the old rate until the average catches up. Note also that a sustained one-directional run grades as informed, because every swap in it is followed by one pushing the same way. That is the intended reading rather than a flaw, but it does mean a pool tracking a strong trend will quote its trend-following flow expensively even when that flow is not picking anyone off.

Configuring a pool

Uniswap v4 removed hookData from initialize, so a hook that needs per-pool parameters has to receive them out of band. MarkoutFee takes them through configure, which anyone may call for a pool key whose pool does not exist yet, and which nobody may call afterwards. The parameters are part of what the pool is, so they are fixed for its lifetime.

// 1. Fix the terms, before the pool exists.
hook.configure(
    key,
    MarkoutFeeHook.Config({
        baseFee: /* uint24 */ 0,
        maxSurcharge: /* uint24 */ 0,
        alphaWad: /* uint64 */ 0,
        minHorizon: /* uint32 */ 0,
        saturationTicks: /* uint24 */ 0
    })
);

// 2. Initialize the pool. The hook rejects a pool it was never configured for.
poolManager.initialize(key, startingSqrtPriceX96);

Parameter	Type	Units
`baseFee`	`uint24`	hundredths of a bip (3000 = 0.30%)
`maxSurcharge`	`uint24`	hundredths of a bip (3000 = 0.30%)
`alphaWad`	`uint64`
`minHorizon`	`uint32`
`saturationTicks`	`uint24`	tick

From TypeScript

The SDK ships the catalogue, the address book and the pool-key helpers, so a client never hardcodes an address or recomputes a pool id by hand.

npm i @hookforge/sdk

import {getHook, hookAddress, poolKeyFor, poolId} from "@hookforge/sdk";

const hook = getHook("markout-fee");
const address = hookAddress("markout-fee", 1);
const key = poolKeyFor({hook: address, currencyA: USDC, currencyB: WETH, tickSpacing: 60, dynamicFee: true});
console.log(poolId(key));

What it reverts with

Error	Meaning
`FeeTooLarge(uint24)`	A fee was configured above the protocol maximum of 100%.
`InvalidSaturation()`	`saturationTicks` of zero would make every move maximally informed.
`InvalidSmoothing()`	`alphaWad` must be in (0, 1e18]: zero never learns, above one overshoots.
`NotDynamicFee()`	The hook was attempted to be initialized with a non-dynamic fee.
`PoolAlreadyInitialized()`	The pool already exists, so its configuration is final.
`PoolNotConfigured()`	The pool was initialized without a configuration for this hook.
`SurchargeTooLarge()`	`baseFee + maxSurcharge` must leave room under the 100% protocol maximum.

Addresses

No addresses published yet. The deploy script mines a deterministic address per chain, so the address a hook will occupy is known before it is deployed; this hook has not had that step run.

Source and verification

The contract is contracts/src/hooks/MarkoutFeeHook.sol, and everything on this page is generated from it: the prose is its NatSpec, the parameters are its configure ABI, the callbacks above are the flags it declares, and the tags are the strings its own hookTags() returns. A hook cannot be documented here as something it is not.

Ask the deployed contract what it is and it answers directly, with no registry in the loop:

cast call $HOOK "hookName()(string)"    # MarkoutFee
cast call $HOOK "specURI()(string)"     # https://hookforge.pages.dev/schema/hooks/markout-fee.json
cast call $HOOK "hookTags()(string[])"  # mev, dynamic-fee, markout, adverse-selection, oracle-free