# Uniswap v4 pools, events and errors

Source: https://docs.hedgehood.io/hedgefun-v2/integration/pools

## Uniswap v4 pools

Every graduated launch trades in one Uniswap v4 pool: the token against its stock, fee 0.20%, tick spacing 60, on
`HedgeFunV2Hook`. One hook instance serves every pool; each pool has its own ledger inside it.

If you have integrated other v4 launch hooks, three things here are different and worth checking before you
assume them: fees are held in the hook until anyone sweeps them; the pool holds two locked positions, not one;
and the buy tax is taken before the swap, so a price-limited buy reverts.

### The pool

| | |
| --- | --- |
| currencies | the token and the stock; which is `currency0` depends on address order, read `poolKey()` from the vault or `stockIsCurrency0InTokenPool()` from the treasury |
| fee | `lpFee` 2000 (0.20%), frozen per pool; the factory accepts 1 to 3000 for future launches |
| tick spacing | 60 |
| hook | `HedgeFunV2Hook`, `version()` 3, address flags `0x28CC` |
| created | at graduation, by the factory, initialised at the curve's terminal price |
| registration | the factory registers the pool and its vault with `registerGraduatedWithVault` before initialisation; a pool the factory did not register cannot be initialised on this hook |

### The two locked positions

`V2LiquidityVault`, one per pool, owns both positions directly; there is no LP token.

| position | contents | range |
| --- | --- | --- |
| full range, salt 0 | 70% of the raise in stock, with about 8.20% of supply in tokens at the reference setting | the usable extremes |
| single-sided, salt 1 | about 12.49% of supply in tokens, no stock | from the next usable tick on the token side of spot to the usable extreme |

The vault has no function that removes liquidity, makes an arbitrary call or upgrades. `collectFees()` is its
only liquidity operation and runs with zero liquidity delta. Rounding residue stays in `lockedSeedTokens` and is
never reported as fees. Both positions count toward the pool's depth as the price moves into the surplus range.

### The hook's callbacks

| callback | what it does |
| --- | --- |
| `beforeInitialize` | answers only for a pool the factory registered, and only to the registered vault. Nobody opens a pool on this hook that the factory did not launch |
| `beforeAddLiquidity` | admits only the pool's vault (`NotSeeder` otherwise). A third-party position would be a way to sell without paying the tax |
| `beforeRemoveLiquidity` | reverts `HookNotImplemented` for everyone. That is the lock |
| `beforeSwap` | on an exact-input buy (stock in, token out) by anyone but the treasury: takes `floor(paid × taxBps / 10000)` of the stock before the swap, mints it as a stock claim to the hook, emits `Taxed`, and lets `paid − tax` meet the pool. Returns a zero delta otherwise |
| `afterSwap` | on a sell: takes the tax from the gross stock output. On an exact-output buy at the flat rate: takes `r / (1 − r)` of the stock input. On an exact-input buy: verifies the swap filled exactly `paid − tax` and reverts `PartialFillRefused` if it did not. The treasury's own swaps pass untaxed |

Permissions: `BEFORE_INITIALIZE`, `BEFORE_ADD_LIQUIDITY`, `BEFORE_SWAP`, `BEFORE_SWAP_RETURNS_DELTA`,
`AFTER_SWAP`, `AFTER_SWAP_RETURNS_DELTA`. Exact-output sells are refused (`ExactOutputRefused`).

### Where fees sit

The tax is booked as ERC-6909 stock claims owned by the hook, per pool (`accruedStock`, `owedProtocol`,
`owedCreator`, `owedTreasury`). Nothing is paid per trade. `sweep(poolId)`, callable by anyone, pays the
protocol's, the creator's and the treasury's shares in one call, each currency on its own leg; `sweepTipBps` is 0.
On a vault pool no fee is ever held in the token, so `Swept.tokenBurned` is 0.

The pool's own 0.20% fee accrues to the vault's positions in the input currency of each swap. `collectFees()`
moves the stock side to the treasury's `buybackStock` and burns the token side.

### What the hook does not do

- It does not gate who may swap. Anyone may trade the pool through any v4 router.
- It does not tax transfers of the token. `HedgeFunToken` is a plain ERC20 and the hook sees swaps only.
- It does not run an opening window on a graduated pool: `registerGraduatedWithVault` refuses one, so the buy
  rate is the flat tax from the first swap, and `buyRateBps(poolId)` equals `sellRateBps(poolId)`.
- It does not spike the sell rate after a buy-back: `spikeBps` is 0 on v2.
- It does not convert fees. There is no token-denominated fee inventory and no owner conversion step.

### The exact-input buy that reverts

Because `beforeSwap` has already taken the tax on the full payment, a buy that stops early at the caller's
`sqrtPriceLimitX96` would have paid tax on stock it never traded. `afterSwap` refuses it with
`PartialFillRefused()`, which the PoolManager wraps as `CustomRevert.WrappedError(hook, afterSwap.selector,
PartialFillRefused(), HookCallFailed())`. Bound the price with a minimum output, as `HedgeFunV2TradeRouter` does,
and the revert never occurs. Sells are taxed on what filled and may stop at a limit.
[Errors](https://docs.hedgehood.io/hedgefun-v2/integration/pools#errors) shows how to decode it.

## Events to index

| contract | event | what it tells an indexer |
| --- | --- | --- |
| factory | `Launched(id, symbol, token, treasury, hook, stock, creator)` | a new launch |
| factory | `CurveLaunched(id, curve, saleBps, virtualStock)` | the curve and its fixed target |
| factory | `Graduated(id, sqrtPriceX96, liquidity, stockSeeded, tokenSeeded, tokenBurned)` | the crossing; `tokenBurned` is 0 on v2 |
| factory | `GraduationCapitalSplit(id, lpStock, treasuryStock, treasuryBooked)` | the 70/30 amounts and whether the treasury booked at once |
| factory | `Listed`, `ListingGatesSet`, `DefaultsSet`, `PublicLaunchSet`, `LauncherSet`, `BandCeilingSet` | owner actions |
| curve | `Bought(caller, recipient, stockSpent, tokensOut, burned)` | a curve buy; `burned` is the opening premium |
| curve | `Sold(caller, recipient, tokenIn, stockOut, fee)` | a curve sell |
| curve | `TradeFeesAccrued(buying, fee, protocolFee, creatorFee, treasuryFee)` | the split of one trade's tax |
| curve | `FeesClaimed(recipient, amount)`, `Ready()`, `Released(stockAmount, tokenAmount)`, `OpeningTaxExemptionsFixed(recipients)` | claims; the graduation hand-off; the frozen exemptions |
| curve deployer | `CurveConfigSet`, `OpeningTaxExemptionsSet` | the creator's window and exemptions |
| treasury deployer | `StrategyKindSet`, `EngineConfigSet`, `KindRegistered`, `EngineKindRegistered`, `PolicyRegistered`, `PolicyDisabled`, `LpBpsSet`, `TreasuryCodeBound` | the creator's kind choices and the registry |
| hook | `Registered(id, token, stock, treasury, protocol, creator, rates)` | the pool's frozen rates |
| hook | `Taxed(id, selling, inToken, moved, tax, rateBps)` | one pool trade's tax. `moved` is the stock the swap moved; on a buy the trader paid `moved + tax` |
| hook | `Swept(id, tokenBurned, stockToTreasury, stockToProtocol, stockToCreator)` | a payout; `tokenBurned` is 0 on a vault pool |
| hook | `Claimed`, `CreatorProposed`, `CreatorVetoed`, `CreatorChanged`, `ProtocolChanged` | payout administration |
| vault | `Seeded(liquidity, amount0, amount1)`, `SurplusSeeded(lower, upper, liquidity, tokens)`, `SeedTokensLocked(amount)` | the two positions |
| vault | `FeesCollected(stockToTreasury, tokenBurned)` | pool fees: stock to the buy-back budget, tokens burned |
| treasury, Lots family | `LotBooked(id, qty, cost, fromTax)`, `ProfitTaken(qty, cost, price, usdgToReserve, stockToBurn)`, `Stopped(qty, cost, price)`, `Buyback(stockSpent, tokenBurned)` | the lot rule |
| treasury, Spot and Rebalance | `StrategyExecuted`, `KeeperRewardPaid`, `GainToBuyback(gain, toBuyback, avgCost, price)` | an engine action, its reward and the share of the gain sent to the burn |
| trade router | `Bought(id, buyer, paymentAsset, recipient, paymentIn, tokensOut, stockRefund)`, `Sold(id, seller, outputAsset, tokensSpent, outputAmount, tokenRefund)` | routed trades |
| native router | `NativeBought(id, buyer, nativeIn, tokensOut, stockRefund)`, `NativeSold(id, seller, nativeOut, tokenRefund)` | the same trade, attributed to the user |
| launch router | `NativeLaunchedAndBought(id, creator, launchFee, nativeBuyIn, tokensOut, stockRefund)` | a one-payment launch |
| upgrade controller | `UpgradeScheduled(treasury, implementation, codeHash, dataHash, readyAt)`, `UpgradeExecuted`, `UpgradeCancelled` | the two-day notice and its outcome |

Curve, router and hook events are layers of one execution; count volume once. A native trade's underlying router
event names the native router as caller; attribute it to `NativeBought.buyer`. Keep three burns apart in a supply
chart: the opening premium (`Bought.burned`), buy-backs (`Buyback.tokenBurned`) and pool-fee burns
(`FeesCollected.tokenBurned`). Graduation burns nothing, and locked LP is not a supply reduction. Topic hashes are
in `abi/SURFACE.md` in the contracts repository; generate them against the deployed commit.

## Errors

| error | from | when |
| --- | --- | --- |
| `Restated()` | factory | a default, listing, gate or registered choice moved since `predict` |
| `NotListed()`, `NotOpen()`, `BadRequest()` | factory | the stock is not listed; public launch is closed and the caller is not an authorised launcher; a field is out of its bounds |
| `Unseedable()`, `SeedOverspent()` | factory | the terms would leave the v4 seed empty, tiny or unpriceable; the seed spent more than its budget |
| `NotReady()` | factory | `graduate(id)` on a curve that is not `Ready` |
| `BadCurveConfig()` | curve deployer | a `saleBps` other than 7931, or a window over 180 s |
| `BadEngineConfig()`, `StopInsideExecutionFriction()`, `BadPolicy()` | treasury deployer | engine words outside their floors; a stop inside `slippage + pool fee + reward`; a disabled or mismatched policy |
| `TreasuryDeployFailed()` | treasury deployer | a constructor refused what the registry could not check by name (Cycle's rung floor) |
| `StageChanged(actual)` | router | the curve graduated between the quote and the call; quote again |
| `Expired()`, `TooLittle(got)`, `TooLittleStock(got)` | router, curve | past the deadline; under `minFinalOut`; under `minStockReceived` |
| `PartialFill(spent)` | router | input left unused and `allowPartialFill` was false |
| `BadPath()`, `WrongPool()`, `BadAmount()` | router | a discontinuous or repeated route; a pool the factory's V3 factory did not create; a zero amount |
| `Closed()`, `Slippage()`, `Insolvent()`, `GraduationFailed()`, `UnsupportedTransfer()` | curve | trading after graduation; under the caller's minimum; a solvency check; the graduation callback failed and the buy rolled back; a fee-on-transfer or surcharging stock |
| `NotSeeder()`, `WrongPool()`, `HookNotImplemented()`, `ExactOutputRefused()` | hook | liquidity from anyone but the vault; a pool the factory never registered; a liquidity removal; an exact-output sell |
| `PartialFillRefused()` | hook, wrapped by v4 | an exact-input buy stopped by a price limit |
| `NotDue()`, `Unhealthy()`, `Cooldown()`, `Slippage()` | treasury | nothing to do; `health()` is false; the buy-back pace; a sale that moved nothing |
| `UseBuyback()`, `UseExecute()` | treasury | Buy-back has no `execute()`; the inherited v1 selectors are off on v2 |
| `AlreadySeeded()`, `NotSeeded()`, `Busy()`, `InexactTransfer()` | vault | a second seed; a collect before seeding; a reentrant callback; a transfer that did not move the exact amount |
| `NotReady()`, `InvalidUpgrade()`, `NotOwner()` | upgrade controller | before `readyAt`; the candidate's code hash, calldata hash, config hash or schema does not match; a caller other than the owner |

### `PartialFillRefused`, wrapped by v4

On an exact-input buy the hook has already taken the tax on the full payment in `beforeSwap`. If the swap then
stops at the caller's `sqrtPriceLimitX96`, `afterSwap` reverts `PartialFillRefused()` so the buyer is not taxed on
stock that never traded. The PoolManager wraps it: the revert a caller sees is

```
CustomRevert.WrappedError(address hook, bytes4 afterSwap.selector, bytes PartialFillRefused(), bytes HookCallFailed())
```

Decode the inner reason, or match on the `WrappedError` selector with the hook's address. A router that bounds
the price with a minimum output, as `HedgeFunV2TradeRouter` does, is never affected; a third-party router that
uses a price limit on a buy is. Sells are taxed on what actually filled and may stop at a limit.

Selectors for every error are in `REFERENCE.md` and `abi/SURFACE.md` in the contracts repository at the deployed
commit.
