OracleBand

How it works

A thin pool can be walked anywhere. Buy through the last tick of liquidity and the pool will quote you a price no other venue would, and whatever reads that pool afterwards, a lending market, a vault, another pool's oracle, inherits the number. The pool is not wrong: it faithfully reports what it was paid.

It is simply alone. This hook gives the pool a second opinion. Before and after every swap it compares the pool price against a reference from an {IPriceOracle} and rejects the swap if the result lands outside a band around it: deviation = |poolPrice / referencePrice - 1|, rejected when deviation > maxDeviationBps The check runs on both sides of the swap, and the pair is what makes it hard to defeat.

The `beforeSwap` check refuses to trade from a price that is already outside the band, so a pool pushed out of line in one transaction cannot be traded against in the next. The `afterSwap` check refuses to leave the pool outside the band, which is what stops the walk in the first place. Neither check can be satisfied by splitting a large swap into small ones, because the constraint is on the resulting price rather than on the size of the trade.

Prices are compared in `sqrtPriceX96`, squared back through `FullMath` so the comparison is on the actual price ratio and not on an approximation of it that drifts as the deviation grows. Liquidity operations are untouched. A provider can always withdraw, including while the band is refusing swaps, which is the property that makes it safe to sit behind one.

The obvious objection: this makes the pool depend on an oracle, and oracles fail. So the hook treats failure as refusal rather than as permission. A feed older than `maxStaleness` halts swapping instead of waving it through, and a feed that reverts propagates rather than being caught.

A pool that would rather trade blind than not trade should not use this hook, and the fee-based hooks in this catalogue are the oracle-free alternative.

Using it

Uniswap v4 removed hookData from initialize, so per-pool parameters arrive out of band. Fix them for a pool key whose pool does not exist yet, then initialize. Nobody can change them afterwards, including you.

hook.configure(
    key,
    OracleBandHook.Config({
        oracle: /* address */ 0,
        maxDeviationBps: /* uint32 */ 0,
        maxStaleness: /* uint32 */ 0
    })
);

poolManager.initialize(key, startingSqrtPriceX96);

Parameters

From TypeScript

npm i @hookforge/sdk

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

const hook = getHook("oracle-band");
const key  = poolKeyFor({
  hook: hookAddress("oracle-band", 8453),   // Base
  currencyA: USDC, currencyB: WETH,
  tickSpacing: 60,
});

What it reverts with

The callbacks it claims

Uniswap v4 reads a hook's permissions from the low fourteen bits of its own address, which is why deploying one means mining a CREATE2 salt. This hook claims 3, so every deployment of it has an address ending in 0x10c0.

• beforeInitialize
• afterInitialize
• beforeAddLiquidity
• afterAddLiquidity
• beforeRemoveLiquidity
• afterRemoveLiquidity
• beforeSwap
• afterSwap
• beforeDonate
• afterDonate
• beforeSwapReturnsDelta
• afterSwapReturnsDelta
• afterAddLiquidityReturnsDelta
• afterRemoveLiquidityReturnsDelta

It says what it is, on-chain

Nothing about a hook's address tells an indexer, a wallet, a router or an agent what the pool does, which is why hook discovery today is a curated list. This hook answers for itself, in one eth_call, with no registry in the loop.

cast call $HOOK "hookName()(string)"    # OracleBand
cast call $HOOK "specURI()(string)"     # https://oracle-band.pages.dev/hook.json
cast call $HOOK "hookTags()(string[])"  # risk, oracle, manipulation-resistance, no-admin

Build, test and deploy

git clone --recurse-submodules https://github.com/nirholas/oracle-band
cd oracle-band
forge build && forge test

# Dry run: mines the salt, prints the address, sends nothing.
forge script script/Deploy.s.sol --rpc-url $RPC_URL

# For real.
forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast --verify