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.

  1. You swapThrough Uniswap's router, like any v4 pool.
  2. PoolManager calls the hookbeforeSwap, before any pricing happens.
  3. Detector updatesOnly on the first swap of a block.
  4. Hook prices the swapCurve, fee, and spread if with the trend.
  5. PoolManager settlesTokens move; the hook's books are updated.
One swap. The hook does all of its work inside Uniswap's beforeSwap call and hands back the amounts; Uniswap's PoolManager moves the tokens.

The steps

  1. 1
    You send a swap through Uniswap's router, exactly as for any v4 pool.
  2. 2
    The PoolManager calls the hook's beforeSwap.
  3. 3
    If 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.
  4. 4
    The hook prices your swap: the base fee, the curve, and the spread if you are trading with a confirmed trend.
  5. 5
    The hook hands the amounts back. The PoolManager takes your tokens and pays you.
  6. 6
    The 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.

A quote is for one block. The spread can change when a new block is sampled. Take the quote and swap in the same block, or set a slippage limit, as the app does. Integrators: see INTEGRATING.md (opens in a new tab).

Safety rails inside the hook

RailWhat it prevents
The hook keeps its own record of its balancesSomeone sending tokens to the hook to shift the price it reads
Swaps are blocked while liquidity is being added or removedA trade slipping in against half-updated balances
The hook accepts one pool, set when it is deployedSomeone attaching it to a pool of their choosing
Extreme prices are clamped or skippedThe detector making a swap fail
1,000 shares are locked for ever at the first depositThe 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.

Unichain Sepolia · chain 1301 · testnetLaunch app