§1 Same fee, two different people

This is not a marginal effect. It is the dominant term in what a liquidity provider actually earns. It has a name — loss-versus-rebalancing — and every dashboard in this industry reports fee APR as though it did not exist. Fee APR is a gross number. Nobody publishes the net one, because nobody measures which trades were which.

§2 Every existing answer is a guess made first

• By volatility Charge more when the tape is moving. Retail trades in volatility too.
• By size Charge more for size. The best-informed trade of the day can be small.
• By address Charge more for addresses that look like bots. A fresh EOA costs nothing to make.

Every one of them is a proxy. Every proxy is gameable. And all of them end up taxing the retail buyer in order to insure against the arbitrageur.

§3 So the pool stops guessing. It waits.

1. A bond, on top of the ordinary fee

   Every swap posts BOND_BPS basis points, taken in afterSwap from the currency you did not name. It is held, not taken.

2. The pool writes down what happened

   The tick before your swap, the tick after, and the block number. Nothing else. It has no opinion about you.

3. After WINDOW blocks, anybody can settle

   The hook reads its own current tick and asks one question: how much of your impact came back?

4. The bond splits on the answer

   All of it came back — the whole bond returns to you. None of it — the whole bond is donated to the providers who were in range. Some of it — split, in proportion.

5. Collect it promptly, or it decays

   A verdict collected within GRACE blocks of becoming available is worth all of itself. After that it decays in a straight line to nothing at DEADLINE. refund = bond × ratio × weight.

A retail buyer the market shrugs off gets everything back, and has paid the ordinary fee and nothing else — less than they would pay in any pool priced to survive arbitrageurs. An arbitrageur who moves the price and is right pays the bond, to precisely the people they took it from. Nobody is banned. Nobody is scored on how they look. The pool never needs to know who you are, because it finds out what you did.

§4 What it deliberately does not do

It does not gate beforeInitialize and it does not gate liquidity. The hook flags are 0x1044 — afterInitialize, afterSwap and afterSwapReturnsDelta — and nothing else. Every one of them fires after the thing it observes has already happened, so none of them can refuse anything. The Uniswap interface can open this pool, mint a real position, and let the provider leave whenever they like. A hook that can refuse a withdrawal is a hook whose promises are worth nothing.

There is no owner. There is no upgrade path. There is no address anywhere in the contract that can be changed after it is deployed.

Status Nothing is deployed. There are no contract addresses to publish, no pool to trade, and no numbers on this page that came from a chain.

Mechanism

Six things happen, in order. Five of them are on-chain and one of them is you remembering to come back, reasonably promptly.

§1 The bond

1. When the pool opens, the hook writes down the price

   afterInitialize, once, and only that. It exists to close a hole: pre is the tick the previous swap left behind, so with no opening tick the very first swap would be judged against itself — pre == post, zero impact, full refund whatever it did. This is the only reason the hook needs to know a pool was created at all, and it still cannot refuse to let one be.

2. The swap executes normally

   No beforeSwap. The hook is not consulted before your trade and cannot price it, delay it, or refuse it. You pay the ordinary pool fee, at the ordinary rate, to the ordinary place.

3. afterSwap holds back BOND_BPS

   The bond is taken from the unspecified currency — the one you did not name. On an exact-input swap that is the side you receive, so you get slightly less than quoted. On an exact-output swap it is the side you pay, so you pay slightly more. Either way it is your money, and either way you can have it back.

   Mechanically: the hook calls take to move the bond out of the pool and into itself, which leaves it owing the pool exactly that much, and returns an int128 that credits exactly that much back. The hook's position inside the lock nets to zero, which is the only thing v4 checks.

4. The pool writes down the trace

   pre — the tick your swap started from. post — the tick it ended at. block.number. And tx.origin, as the claimant.

   pre is the tick the previous swap left behind, or the opening tick if yours is the first. Minting, burning and donating never move the tick, so the pool is its own record of where it was — no oracle, no snapshot, no separate storage to keep honest.

5. After WINDOW blocks, settle(id) is open to anyone

   The refund always goes to the claimant, never to the caller. There is nothing to be gained by settling somebody else's trade and nothing to be lost by letting them settle yours.

6. The verdict splits the bond

   refund = bond × ratio × weight to the claimant. toProviders = bond − refund, donate()d to the in-range liquidity providers of that exact pool. Not a treasury. Not the deployer. The people who were standing there when it happened.

   The weight is the second half of the answer and it is covered in §3. In short: collect inside GRACE and it is 1.

§2 The verdict

A swap moves the price from pre to post. Some blocks later the price is at now. The only question the contract answers is how much of that move came back.

§3 The weight, and the one thing you can still game

The ratio says what the trade was. It does not say when anybody asked. And when somebody asks turns out to matter, because the reading has to be taken live — nothing on chain can read a tick from a block that has already passed. There is no historical price to consult. The pool's tick is a current value or it is nothing.

So the trader chooses the moment the question is asked, and over a long enough deadline that choice is worth real money. Wait, and sooner or later ordinary drift carries the price back past where you left it — at which point a trade that genuinely was informed collects a ratio of 1 for a move that never actually reverted on its own merits. That option cannot be removed. It can be made not worth having.

The same ramp is what retires an abandoned bond, which is the other job it is doing. There is no cliff at the deadline and nothing in the contract that turns on a single block — the value drains away continuously instead of vanishing at one.

Be clear about what this does not fix. Inside the grace window the option is free: a trader watching their own position who sees a favourable tick forty minutes in will take it, and there is no answer to that beyond WINDOW being long enough for the price to have said something. The ramp prices the patient version of the strategy, not the quick one.

§4 The simulator

The arithmetic below is a direct port of Reversion.ratio, Reversion.split and weightAt, integer-for-integer in the same fixed point, including the clamp, the zero-impact case and the order in which preview composes them. Move the controls and the verdict moves with them.

§5 Where the forfeit goes

donate(), into the same pool key, in the same currency the bond was taken in. That means it accrues to whoever holds in-range liquidity at that moment, in proportion to how much of it they hold. It is not routed through a treasury, it does not touch the deployer, and there is no fee on it.

If nobody is in range, donate reverts. The hook catches that, parks the value as stranded0 / stranded1, and emits Stranded. Anyone can call sweepStranded() afterwards to retry. It is never handed back to the trader, who has just demonstrated they did not deserve it.

The Docket

A pending verdict is an asset. The Docket makes that explicit: it turns a bond awaiting judgment into an ERC-721 you can hold, transfer or sell, and it keeps the running public record of how every address's trades turned out.

§1 The receipt

Every swap already produces a trade id inside the hook, whether or not you do anything about it. Minting the matching receipt is optional, costs gas, and is deliberately kept out of the swap itself — a trader who never touches the Docket is paid exactly the same. What it changes is who gets paid: the hook asks the Docket holderOf(id) at settlement, and if a receipt exists the refund goes to whoever holds it.

function claimantOf(uint256 id) public view returns (address) {
    address h = DOCKET.holderOf(id);
    return h == address(0) ? pending[id].trader : h;
}

claim(id) mints it, and only the original trader can call it, only while the trade is unsettled and unclaimed. The token id is the trade id. After that it is an ordinary ERC-721: transfer it, approve it, sell it.

Which means you can sell the verdict before it arrives. You bought, you would rather have the bond back now than probably-the-bond-back later, and somebody else disagrees with you about what the price is going to do. That disagreement has a price, and this is where it gets one.

The metadata is generated on chain — tokenURI returns a base64 data URI with an SVG drawn from the trade's own numbers: three points, where the price was, where this trade put it, and where it is now, which is the whole argument in one line. Status reads PENDING, READY or SETTLED, and the attributes carry the opening block, the impact in ticks and the reverted percentage.

§2 The ledger

The Docket also keeps a standing per address: trades settled, bonds posted, and bonds refunded. It is appended to by the bound hook at settlement and by nothing else. There is no way to edit it, no way to delete a line, and no address that can.

It is written against the address that made the trade — never against whoever ended up holding the receipt, because a receipt can be sold and the trade it describes cannot be. So selling your claim moves the money and not the record. The hook is explicit about this: the refund goes to claimantOf(id) while the line goes to p.trader.

function standing(address who) external view returns (
    uint256 trades, uint256 posted, uint256 refunded, uint256 score
);
// score = posted == 0 ? 1e18 : (refunded * 1e18) / posted

An address with no history scores 1e18, because an address that has done nothing has taken nothing from anyone. Treat a perfect score with no trades behind it as exactly the information it is.

§3 The shape of the record

Posted and refunded are denominated in whichever currency each bond was taken in, which depends on the direction of the trade and whether it was exact-input or exact-output. Any interface that renders this ledger has to say which, or the column is meaningless.

§4 The pool's own ledger

Separately from the per-address record, the hook itself exposes four all-time totals and one derived figure. These are plain public state on Verdict, not on the Docket, and they need no indexer to read.

function ledger() external view returns (
    uint256 trades,        // every trade ever bonded
    uint256 bonded,        // total posted
    uint256 refunded,      // total returned to traders
    uint256 toProviders,   // total forfeited, INCLUDING anything still parked
    uint256 held,          // bonded - refunded - toProviders
    uint256[2] parked      // forfeited but not yet delivered: [currency0, currency1]
);

held is the honest one. It is every bond that has been posted and not yet judged — capital sitting in the contract because its window has not elapsed, or because nobody has bothered to settle it. If that number is large and growing, people are forgetting to come back, and the decay ramp is quietly moving their money to the providers.

parked is the one that will catch an indexer out. toProviders counts everything forfeited, including value that never reached anybody because no liquidity was in range at the moment it was donated. That residue sits in parked until somebody calls sweepStranded(). If you want the amount providers have actually received, subtract one from the other.

Technical reference

Solidity 0.8.26, Uniswap v4. Read the source before you read this page; this page is only here to save you time.

§1 Contracts

No addresses are published on this site because none exist. Any address presented elsewhere as a Hindsight contract, today, is not one.

§2 Hook flags — 0x1044

The PoolManager reads the low 14 bits of a hook's address to decide which callbacks to fire. The permissions are not configuration; they are the address. Three bits are set. Here is every bit, and why it is set or clear.

bit 13 ← → bit 0  ·  0x1000 | 0x40 | 0x04 = 0x1044

The three that are set

bit 12 · afterInitialize · 0x1000

Writes down the tick the pool opened at, once, and nothing else. It exists because of a hole it would otherwise leave: pre is the tick the previous swap left behind, so without an opening tick the very first swap in the pool would be judged against itself — pre == post, an impact of zero, and by the zero-impact rule a full refund no matter what it did. The opening trade would be free.

It still cannot refuse anything. It runs once the pool already exists, it returns its selector for every pool whether bound or not, and it only writes if the pool is the bound one and nothing has been recorded yet.

bit 6 · afterSwap · 0x0040

Where the bond is held and the trace is written down. After the swap, so it cannot price, delay or refuse the trade it is looking at.

bit 2 · afterSwapReturnsDelta · 0x0004

Required for afterSwap's returned int128 to be applied at all. Without this bit the hook could observe a swap but not hold anything back from it.

The three that matter most by being clear

beforeInitialize (bit 13) is clear, so nothing here can refuse to let the pool exist — anyone, including the Uniswap interface, can open it. beforeAddLiquidity (bit 11) and beforeRemoveLiquidity (bit 9) are clear, so providers need no permission to arrive and — the important one — none to leave. Every callback this hook does receive fires after the fact it observes, which is the same property the whole mechanism is built on.

The constructor refuses to exist anywhere else:

uint160 public constant FLAGS = 0x1044;

// in the constructor
if (uint160(address(this)) & 0x3FFF != FLAGS) revert BadFlags();

The four reverting stubs — beforeSwap, beforeInitialize, beforeAddLiquidity, beforeRemoveLiquidity — exist only to say out loud, in code, what the address bits already say: they revert with NeverCalled(), because the PoolManager will never call them.

§3 The afterSwap delta

afterSwap returns (bytes4, int128). The int128 is applied to the unspecified currency — the side the trader did not name. The hook determines which side that is with exactly the same test v4-core uses, because if the two disagree the bond lands on the wrong side of the trade:

bool onCurrency1 = (params.amountSpecified < 0) == params.zeroForOne;

int128 unspec = onCurrency1 ? delta.amount1() : delta.amount0();
uint256 mag   = unspec < 0 ? uint256(uint128(-unspec)) : uint256(uint128(unspec));
uint256 bond  = (mag * BOND_BPS) / 10_000;

POOL_MANAGER.take(onCurrency1 ? CURRENCY1 : CURRENCY0, address(this), bond);
return (IV4Hooks.afterSwap.selector, int128(uint128(bond)));

take moves the bond out of the pool and into the hook, which leaves the hook owing the pool exactly that much. The returned delta credits exactly that much back. The hook's position inside the lock nets to zero, which is the only thing v4 checks.

If the computed bond rounds to zero — a trade small enough that mag × BOND_BPS / 10 000 == 0 — the hook returns a zero delta and opens no trade. There is nothing to settle and no receipt to claim.

Swaps against any pool key that is not the bound one pass through untouched. isBoundPool compares both currencies, the fee, the tick spacing and the hook address; anything else gets a zero delta and no record.

§4 Settlement arithmetic

function ratio(int24 pre, int24 post, int24 now_) internal pure returns (uint256) {
    int256 impact = int256(post) - int256(pre);
    if (impact == 0) return ONE;              // moved nothing, so nothing stuck

    int256 back = int256(post) - int256(now_);
    if ((impact > 0 && back <= 0) || (impact < 0 && back >= 0)) return 0;

    uint256 a = uint256(back > 0 ? back : -back);
    uint256 b = uint256(impact > 0 ? impact : -impact);
    if (a >= b) return ONE;
    return (a * ONE) / b;
}

function split(uint256 bond, uint256 r) internal pure returns (uint256 refund, uint256 forfeit) {
    refund  = (bond * r) / ONE;
    forfeit = bond - refund;
}

ONE is 1e18. Division truncates, so the refund rounds down and the remainder goes to the providers — at most one wei per settlement, and always in the direction that cannot leave the contract short.

The weight

The ratio says what the trade was. The weight says what the verdict is worth by the time somebody collects it, and the two multiply.

function weightAt(uint64 openedAt) public view returns (uint256) {
    uint256 full = uint256(openedAt) + WINDOW + GRACE;
    if (block.number <= full) return 1e18;
    uint256 dead = uint256(openedAt) + DEADLINE;
    if (block.number >= dead) return 0;
    return ((dead - block.number) * 1e18) / (dead - full);
}

Flat at 1e18 through WINDOW + GRACE, then a straight line to zero at DEADLINE. Note that it does not care whether the trade is settleable yet — a trade inside its window still has full weight, it simply cannot be settled.

This ramp is doing two jobs at once. It retires abandoned bonds without a cliff, so nothing in the contract turns on a single block. And it prices the one thing a trader can still game: you choose when the price is read. Nothing on chain can read a tick from a block that has already passed, so the reading has to be live, and the option to wait for a friendlier one cannot be removed. It can only be made not worth having.

preview composes the two, and it is worth reading the order carefully — the weight is applied to the refund, and the forfeit is whatever is left of the bond, so both truncations land on the providers' side:

ready = block.number >= p.openedAt + WINDOW;
uint256 weight = weightAt(p.openedAt);
if (weight == 0) {
    // Past the deadline the answer is fixed and the price is irrelevant.
    return (0, 0, p.bond, ready);
}
(, int24 now_,,) = POOL_MANAGER.getSlot0(_key().toId());
ratio = Reversion.ratio(p.pre, p.post, now_);
(refund,) = Reversion.split(p.bond, ratio);
refund = (refund * weight) / 1e18;
toProviders = p.bond - refund;

Rows computed from weightAt at WINDOW = 300, GRACE = 300, DEADLINE = 216 000. Block counts converted at 12 seconds a block, which is a convention, not a guarantee.

§5 Function reference

settle(uint256 id) → (uint256 refund, uint256 toProviders)

Reads the pool's current tick, computes the ratio, splits the bond, donates the forfeit, pays the claimant, writes the Docket record, emits Settled. Callable by anyone; the refund always goes to claimantOf(id) and never to the caller.

Reverts NoSuchTrade · AlreadySettled · TooEarly(readyAt)

The pool is paid before the trader is, so every interaction with the PoolManager finishes before control leaves the contract.

settleMany(uint256[] calldata ids)

A loop over settle. Any one failure reverts the batch, so filter with settleable first.

preview(uint256 id) → (uint256 ratio, uint256 weight, uint256 refund, uint256 toProviders, bool ready)

What the trade pays out if settled at this block. Callable before the window elapses — ready tells you whether settle would currently succeed. Once the weight has reached zero it returns (0, 0, 0, bond, ready) without reading the price at all.

ratio is the reversion on its own and weight is the decay on its own; the refund is the product of the two and the bond. They are returned separately so a trader can see which of the two is costing them — but do not compute bond × ratio and expect refund.

Reverts NoSuchTrade

weightAt(uint64 openedAt) → uint256

The decay multiplier at this block, in 1e18 fixed point. 1e18 through openedAt + WINDOW + GRACE, then linear to 0 at openedAt + DEADLINE. Takes the open block rather than an id, so it can be evaluated for a hypothetical trade.

claimantOf(uint256 id) → address

The Docket holder of the receipt, if one has been minted; otherwise the original trader recorded at swap time.

settleable(address who, uint256 from, uint256 to) → uint256[]

Every trade of who's in the id range that can be settled right now. Ids start at one, and a from of zero is treated as one. to is clamped to nextId. For wallets and scripts only — it is linear in the range and should never be called on-chain.

sweepStranded()

Retries a donation that had nobody in range to receive it. Anyone may call it, and it can only ever move value towards the providers. Emits Swept on success; silently re-parks the value on failure.

ledger() → (trades, bonded, refunded, toProviders, held, uint256[2] parked)

All-time totals. held = bonded − refunded − toProviders is every bond posted and not yet judged.

toProviders counts everything forfeited, including value that has not actually reached anybody because nobody was in range when it was donated. parked is that residue, in currency0 and currency1 respectively, and sweepStranded retries it. Subtract parked from toProviders if you want the amount that has genuinely been delivered.

poolKey() → PoolKey  ·  isBoundPool(PoolKey) → bool

The exact key the hook will donate into, and the test it applies to decide whether a swap is one of its own.

pending(uint256 id) → (bond, pre, post, onCurrency1, settled, trader, openedAt)

The raw record. Public mapping, no accessor needed.

donateToPool(bool is1, uint256 amount)  ·  unlockCallback(bytes)

Internal plumbing with external visibility — the first so a failed donation can be caught, the second because the PoolManager requires it. Both reject every caller but the one that is allowed (NotSelf, NotPoolManager).

Events

event Opened(uint256 indexed id, address indexed trader, uint128 bond, bool onCurrency1, int24 pre, int24 post);
event Settled(uint256 indexed id, address indexed to, uint256 ratio, uint256 refunded, uint256 toProviders);
event Stranded(uint256 amount0, uint256 amount1);
event Swept(uint256 amount0, uint256 amount1);

Opened and Settled are jointly enough to reconstruct the whole history off-chain: who traded, what they moved, what came back, and what it cost them. No indexer-only state.

Errors

BadFlags · BadParams · NotPoolManager · NotSelf · NoSuchTrade · AlreadySettled · TooEarly(uint64 readyAt) · BondTooLarge · TransferFailed · NeverCalled

§6 Immutable parameters

There is no owner, no onlyOwner, no proxy, no initializer, no timelock and no pause. Every one of the above is immutable, which means it lives in the deployed bytecode and not in storage. Changing one requires deploying a different contract at a different address, which is a different pool that nobody's liquidity is in.

§7 Integration notes

If you are providing liquidity

• Mint a normal v4 position through any interface that supports v4, including the Uniswap one. There is no allow-list, no lockup, no vesting, and no callback on add or remove.
• Forfeits arrive as donate(), which credits in-range liquidity at that instant. Out-of-range liquidity earns nothing from a forfeit, exactly as it earns nothing from a fee.
• You are not obliged to settle anybody's trade, and settling does not pay you — the refund goes to the claimant regardless of who calls. Your one reason to settle somebody else's trade is to fix the verdict at a block of your choosing rather than theirs, and the first call wins. The decay ramp is what makes that a convenience rather than a necessity: a trader who waits for a friendlier price pays for the wait out of the same bond.
• Forfeits arrive whether or not anybody settles promptly. A bond left to run all the way to DEADLINE is donated in full.
• The hook cannot stop you leaving. That is the entire content of bits 9 and 8 being clear.

If you are trading

• Swap from an EOA. The receipt is made out to tx.origin, which through a 4337 bundle or a keeper-fired Safe module is not you.
• You do not need extra slippage tolerance. The live Uniswap V4Quoter (0x52F0E24D1c21C8A0cB1e5a5dD6198556BD9E1203) simulates the hook as part of quoting, so the number the interface shows you already has the bond deducted. Verified on a mainnet fork by quoting a swap and then executing it with amountOutMinimum set to the quote exactly — zero tolerance — and it succeeds.
• Budget about 59 000 extra gas for the swap: 109 938 against 51 220 for the identical pool with no hook, measured in steady state on a mainnet fork. Settling later is a separate transaction and a separate cost.
• Note the id from the Opened event, or find your open trades later with settleable. Then come back after WINDOW and call settle — and do it inside GRACE, because after that every block costs you part of the refund.
• There is no hookData. Nothing about the swap call is non-standard, which is why an off-the-shelf router can make it.

Questions

The hostile ones first, since they are the only interesting ones.