ReserveStable

How it works

Every stable pool in production prices with a curve that is flat near parity and steep away from it, and every one of them shares a defect: the only force restoring balance is the price the curve happens to quote. When one side runs low, the pool makes it expensive to take more, and then it waits. Nothing pays anybody to bring the missing side back.

Arbitrage does it eventually, if an external venue happens to make it worth doing, and if it does not, the pool sits lopsided with its deep side useless and its shallow side unusable. This pool prices at parity and adjusts with a signed spread rather than a curve. A trade that takes from the scarce side pays a spread that grows as that side gets scarcer, from `baseSpreadBps` up to `maxSpreadBps`.

That much is ordinary. The part that is not: everything charged above the base rate goes into an explicit stability fund rather than to the providers, and a trade that takes from the *abundant* side is paid a rebate out of that fund. Restoring the balance is not merely cheaper than breaking it, it is profitable, and it is profitable in exact proportion to how badly the pool needs it.

The fund is what makes this safe rather than a subsidy with no source. It only ever grows from spread charged above the base rate, and no rebate can exceed it, so across any sequence of trades the pool pays out strictly less than it took in for this purpose. Providers cannot be made worse off than they would have been in the same pool charging a flat `baseSpreadBps` and nothing else, which is a property, not an aspiration: it follows from the fund being a separate balance that a rebate can only draw down.

The round trip does not pay either. `maxRebateBps` is capped at `maxSpreadBps - baseSpreadBps` at construction, so breaking the balance and restoring it costs the base spread twice and recovers at most what breaking it paid in. The fund is also empty when the pool is balanced, which is exactly when a round-tripper would want to start.

Underneath both of those sits a floor: no swap may leave either side holding less than `minSideBps` of the pool. That is the band. A pegged pool that will sell the last unit of one side at any price is a pool that can be emptied, and no spread schedule fixes that, because the last unit is worth more than any finite fee.

Reserves are normalized to eighteen decimals from the units given at construction, so a six-decimal stablecoin and an eighteen-decimal one are compared correctly rather than off by a factor of a trillion.

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.

poolManager.initialize(key, startingSqrtPriceX96);

Parameters

This hook takes no per-pool configuration.

From TypeScript

npm i @hookforge/sdk

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

const hook = getHook("reserve-stable");
const key  = poolKeyFor({
  hook: hookAddress("reserve-stable", 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 5, so every deployment of it has an address ending in 0x2a88.

• 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)"    # ReserveStable
cast call $HOOK "specURI()(string)"     # https://reserve-stable.pages.dev/hook.json
cast call $HOOK "hookTags()(string[])"  # curve, stablecoin, custom-curve, rebalancing, no-admin

Build, test and deploy

git clone --recurse-submodules https://github.com/nirholas/reserve-stable
cd reserve-stable
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

Try it

This is the hook running, not a picture of it. Connect a wallet on a chain it is deployed to, or bring the whole stack up locally in one command and use it with no funds and no wallet risk at all.

git clone --recurse-submodules https://github.com/nirholas/reserve-stable
cd reserve-stable

anvil &
forge script script/DeployLocal.s.sol --rpc-url http://127.0.0.1:8545 --broadcast \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

node web/build.mjs && npx serve web/dist