A swap, step by step
What happens between pressing Swap and receiving your tokens: how the hook plugs into Uniswap v4, where the liquidity sits, and why a quote always matches what you get.
What a hook is
Uniswap v4 keeps every pool inside one contract, the PoolManager. A pool can name a hook: a contract the PoolManager calls at set moments, such as just before a swap. Most hooks adjust a fee. Poincaré goes further and replaces the pricing: it works out the swap itself and tells the PoolManager the amounts.
- You swapThrough Uniswap's router, like any v4 pool.
- PoolManager calls the hookbeforeSwap, before any pricing happens.
- Detector updatesOnly on the first swap of a block.
- Hook prices the swapCurve, fee, and spread if with the trend.
- PoolManager settlesTokens move; the hook's books are updated.
The steps
- 1You send a swap through Uniswap's router, exactly as for any v4 pool.
- 2The PoolManager calls the hook's
beforeSwap. - 3If this is the first swap of the block, the hook reads its price and updates the detector. Later swaps in the block reuse that result.
- 4The hook prices your swap: the base fee, the curve, and the spread if you are trading with a confirmed trend.
- 5The hook hands the amounts back. The PoolManager takes your tokens and pays you.
- 6The hook records the new balances in its own books.
Source: PoincareHook.sol (opens in a new tab). The detector costs about 96,000 gas on the first swap of a block and nothing extra after that.
Where the liquidity sits
In a normal v4 pool, LPs choose a price range and hold a position of their own. Here, LPs deposit both tokens into the hook and receive shares, an ordinary token. Each share is a claim on the same pot.
- Why: the hook prices every swap on its own curve, so liquidity placed the usual way would never be used.
- What you gain: fees and spread land in the pot, so every share grows in step. Nothing to claim, no range to manage.
- What you give up: you cannot concentrate liquidity in a price range, so each dollar is used less intensively than in a managed v4 position.
Add or remove liquidity on the Pool screen. An example strategy shows how a bot could size a position by regime.
Why a quote equals what you get
The detector's calculation lives in one read-only function. A swap runs it and saves the result. A quote runs the very same function and saves nothing. Because both use one piece of code, a quote from PoincareLens matches the swap to the smallest unit, even in a new block where nobody has traded yet.
Safety rails inside the hook
| Rail | What it prevents |
|---|---|
| The hook keeps its own record of its balances | Someone sending tokens to the hook to shift the price it reads |
| Swaps are blocked while liquidity is being added or removed | A trade slipping in against half-updated balances |
| The hook accepts one pool, set when it is deployed | Someone attaching it to a pool of their choosing |
| Extreme prices are clamped or skipped | The detector making a swap fail |
| 1,000 shares are locked for ever at the first deposit | The first depositor manipulating the share price |
Most of these came out of the two security reviews. The findings and fixes are listed in SECURITY.md (opens in a new tab), and every code fix has a test that fails without it.