Uniswap V3 — concentrated liquidity

MODULE 00 Mental model · V2 → V3

Why full-range liquidity wastes capital, what "concentrated" really changes, and the structural consequences: ticks, fee tiers, NFT positions.

The analogy

Imagine a market stall that must stock every possible price for a good — from $0.01 to infinity — even though it only ever sells around $3,000. Most of the inventory just sits there, never touched, earning nothing. That's a Uniswap V2 liquidity provider. V3 lets the stall owner stock only the prices that actually trade, so the same capital does far more work.

V2 baseline — the constant product

The canonical enforcement, from UniswapV2Pair.sol (swap), checks the invariant on the post-swap balances (adjusted for the 0.3% fee):

uint balance0Adjusted = balance0 * 1000 - amount0In * 3;
uint balance1Adjusted = balance1 * 1000 - amount1In * 3;
require(
  balance0Adjusted * balance1Adjusted >= uint(_reserve0) * _reserve1 * (1000**2),
  "UniswapV2: K"
);

The capital-efficiency problem (quantified)

If an LP concentrates the same capital into a price range [P_a, P_b] instead of (0, ∞), the effective depth multiplies. The general efficiency multiplier E relative to full-range V2 is:

The structural consequences

Architecture: core vs periphery

• Core (v3-core): UniswapV3Factory, UniswapV3Pool — minimal, unopinionated, immutable. Holds funds and the math; uses callbacks (uniswapV3SwapCallback, uniswapV3MintCallback) so it never trusts the caller's accounting.
• Periphery (v3-periphery): NonfungiblePositionManager (wraps positions as NFTs), SwapRouter (multi-hop, slippage, deadlines). Replaceable, user-friendly, where opinions live.

MODULE 01 Mathematical foundations

Q64.96 fixed-point, why store √P, square-and-multiply exponentiation, and the local constant product.

1.1 · Q number format

The EVM has no floating point. V3 uses fixed-point: a real number times a power of two, stored as an integer. Qm.n means m integer bits and n fractional bits. Q64.96 = 64 integer + 96 fractional = 160 bits total (fits a uint160); Q128.128 = 256 bits.

1.2 · Why store the square root of price

V3 stores sqrtPriceX96 = √P · 2^96, not P. Reason: swap math relates amounts to differences in √P (Module 3), so storing √P means the hot path never computes a square root on-chain — only multiply/divide. Square roots in the EVM are expensive; differences of a stored √P are cheap.

1.3 · Square-and-multiply

Computing 1.0001^tick for tick up to ~887,272 by repeated multiplication would cost hundreds of thousands of multiplications. Square-and-multiply does it in O(log tick): write the exponent in binary, square the base each bit, and multiply the running product whenever a bit is set.

13 = 1101 in binary  (bits: 8 + 4 + 1)
square chain:  b^1 → b^2 → b^4 → b^8
bit 0 (1): set  → multiply in b^1     result = b^1
bit 1 (0): skip
bit 2 (1): set  → multiply in b^4     result = b^1 · b^4 = b^5
bit 3 (1): set  → multiply in b^8     result = b^5 · b^8 = b^13   ✓
4 squarings + 3 multiplies instead of 12 multiplies

TickMath.getSqrtRatioAtTick (Module 2.2) is a hard-coded square-and-multiply: each precomputed hex constant is 1.0001^(−2^i) in Q128.128, multiplied in only when the matching bit of tick is set.

1.4 · The constant product, locally

V3 still uses x·y = k, but only within a tick range and with virtual reserves. From L = √(x·y) and √P = √(y/x) we derive the two relations the whole protocol leans on:

L is the position's liquidity — the depth of the curve. It stays constant during any swap that does not cross a tick; only √P, x and y move.

MODULE 02 Ticks & the tick bitmap

tick↔price, the hard-coded TickMath, tick spacing, the ±887272 limits, and the bitmap that makes swaps cheap.

2.1 · What a tick is

Base 1.0001 means each tick is one basis point (0.01%) of price change. Ticks are integers; "the current tick" is the greatest i whose price is ≤ the current price.

2.2 · TickMath (the real code)

getSqrtRatioAtTick(int24 tick) is square-and-multiply over the bits of |tick|. Each constant is 1.0001^(−2^k) in Q128.128; a constant is multiplied in only if bit k is set, then the result is inverted if tick > 0 and shifted to Q64.96:

uint256 absTick = tick < 0 ? uint256(-int256(tick)) : uint256(int256(tick));
uint256 ratio = absTick & 0x1 != 0
    ? 0xfffcb933bd6fad37aa2d162d1a594001       // 1.0001^(-1) in Q128.128
    : 0x100000000000000000000000000000000;     // 1.0 in Q128.128
if (absTick & 0x2  != 0) ratio = (ratio * 0xfff97272373d413259a46990580e213a) >> 128;
if (absTick & 0x4  != 0) ratio = (ratio * 0xfff2e50f5f656932ef12357cf3c7fdcc) >> 128;
// … one line per bit, up to 0x80000 …
if (tick > 0) ratio = type(uint256).max / ratio;   // invert for positive ticks
// round up, then shift Q128.128 → Q64.96
sqrtPriceX96 = uint160((ratio >> 32) + (ratio % (1 << 32) == 0 ? 0 : 1));

getTickAtSqrtRatio goes the other way: a most-significant-bit log computation (binary search) returning the greatest tick with sqrtRatio ≤ input — the off-by-one direction matters for the bitmap.

2.3–2.5 · Spacing, fee tiers, limits

Position boundaries must be divisible by tickSpacing. Wider spacing = fewer initializable ticks = cheaper swaps (fewer crossings) but coarser liquidity. The limits come from fitting √P into a uint160:

So the price range is ~2^{-128} to 2^{128}; swaps clamp against MIN_SQRT_RATIO / MAX_SQRT_RATIO.

2.6 · The tick bitmap (in depth)

The pool tracks which ticks are initialized (referenced by some position) in a mapping(int16 => uint256) — one 256-bit word per 256 (compressed) ticks. A tick's place decomposes into a word position and a bit position:

function flipTick(mapping(int16 => uint256) storage self, int24 tick, int24 tickSpacing) internal {
    int24 compressed = tick / tickSpacing;
    (int16 wordPos, uint8 bitPos) = position(compressed);
    uint256 mask = 1 << bitPos;
    self[wordPos] ^= mask;                       // toggle the bit
}

function nextInitializedTickWithinOneWord(
    mapping(int16 => uint256) storage self, int24 tick, int24 tickSpacing, bool lte
) internal view returns (int24 next, bool initialized) {
    int24 compressed = tick / tickSpacing;
    if (lte) {                                    // searching left (price down)
        (int16 wordPos, uint8 bitPos) = position(compressed);
        uint256 mask = (1 << bitPos) - 1 + (1 << bitPos);   // all bits ≤ current
        uint256 masked = self[wordPos] & mask;
        initialized = masked != 0;
        next = initialized
            ? (compressed - int24(bitPos - BitMath.mostSignificantBit(masked))) * tickSpacing
            : (compressed - int24(bitPos)) * tickSpacing;
    } else { /* search right (price up): least-significant-bit of the upper mask */ }
}

The swap loop calls nextInitializedTickWithinOneWord each step to jump straight to the next tick that actually has liquidity, instead of scanning all 887k ticks — the single biggest gas win in the swap path.

MODULE 03 Liquidity & reserves

Virtual vs real reserves, the three price regions, and the amount-delta formulas with their rounding directions.

3.1–3.2 · L, virtual vs real reserves

A concentrated position on [P_a, P_b] behaves like a much larger full-range V2 position while price is in range. The trick: add offset terms so the local curve looks like a shifted constant product. Virtual reserves are what the curve "pretends" exist; real reserves are what's actually deposited.

At the boundaries one real reserve hits zero: at P = P_b, x_real = 0 (all token1); at P = P_a, y_real = 0 (all token0).

3.3 · The three regions

3.4 · Amount deltas (the code)

SqrtPriceMath.getAmount0Delta / getAmount1Delta compute how much token moves between two √P for a given L. Side by side — note token0 has the product of both √P in the denominator, token1 is just the difference:

Derivation: Δx = L/√P_a − L/√P_b = L(√P_b − √P_a)/(√P_a√P_b) from x = L/√P; Δy = L√P_b − L√P_a from y = L√P. They differ because token0 lives in the 1/√P world and token1 in the √P world.

MODULE 04 Positions & fee growth

The Position struct, mint/burn/collect's two-step design, and the feeGrowthInside accounting that isolates a range's fees.

4.1 · The Position struct

struct Info {
    uint128 liquidity;                 // L contributed by this position
    uint256 feeGrowthInside0LastX128;  // snapshot of in-range fee growth, token0
    uint256 feeGrowthInside1LastX128;  // snapshot, token1
    uint128 tokensOwed0;               // fees credited, not yet collected
    uint128 tokensOwed1;
}

Keyed by keccak256(owner, tickLower, tickUpper) — that's why positions are non-fungible: two LPs with different ranges hold fundamentally different things, so the periphery wraps each as an ERC-721.

4.2 · mint / burn / collect (two-step)

mint updates both ticks via Tick.update (flipping the bitmap if a tick becomes initialized), writes the position, then calls uniswapV3MintCallback so the caller pays — the pool verifies tokens arrived rather than trusting the caller. burn does not transfer tokens; it reduces liquidity and credits tokensOwed. collect is the actual withdrawal. The split lets an LP burn and re-mint without forced transfers, and batches fee collection.

4.3 · Fee growth accounting (the clever part)

feeGrowthGlobal0X128 is a monotonically increasing accumulator: total fees per unit of liquidity, ever. To find fees earned inside a range, subtract the "outside" growth of the two boundary ticks:

The subtraction isolates exactly the growth that happened while price was inside the range — the mechanism behind every fee question in Module 6.

MODULE 05 Swaps · the state machine

The swap loop, computeSwapStep, crossing a tick, the edge-of-tick case, and exact-in vs exact-out.

5.1 · Entry & state

swap(recipient, zeroForOne, amountSpecified, sqrtPriceLimitX96, data). zeroForOne = selling token0 for token1 (price falls). amountSpecified > 0 = exact input, < 0 = exact output. sqrtPriceLimitX96 caps how far price may move. The loop carries a SwapState (remaining amount, current √P, current tick, accumulated fees, active liquidity).

5.2–5.3 · The loop & computeSwapStep

while (state.amountSpecifiedRemaining != 0 && state.sqrtPriceX96 != sqrtPriceLimitX96) {
    StepComputations memory step;
    step.sqrtPriceStartX96 = state.sqrtPriceX96;
    // 1) find the next initialized tick within one word (bitmap)
    (step.tickNext, step.initialized) =
        tickBitmap.nextInitializedTickWithinOneWord(state.tick, tickSpacing, zeroForOne);
    step.sqrtPriceNextX96 = TickMath.getSqrtRatioAtTick(step.tickNext);
    // 2) swap within this tick range up to the next tick or the limit
    (state.sqrtPriceX96, step.amountIn, step.amountOut, step.feeAmount) =
        SwapMath.computeSwapStep(
            state.sqrtPriceX96,
            (zeroForOne ? step.sqrtPriceNextX96 < sqrtPriceLimitX96 : step.sqrtPriceNextX96 > sqrtPriceLimitX96)
                ? sqrtPriceLimitX96 : step.sqrtPriceNextX96,
            state.liquidity, state.amountSpecifiedRemaining, fee);
    // 3) update remaining amounts & global fee growth …
    // 4) if we reached the next tick exactly, cross it
    if (state.sqrtPriceX96 == step.sqrtPriceNextX96 && step.initialized) {
        int128 liquidityNet = ticks.cross(step.tickNext, feeGrowthGlobal0X128, feeGrowthGlobal1X128);
        if (zeroForOne) liquidityNet = -liquidityNet;
        state.liquidity = LiquidityMath.addDelta(state.liquidity, liquidityNet);
        state.tick = zeroForOne ? step.tickNext - 1 : step.tickNext;
    }
}

computeSwapStep moves √P as far as the remaining amount allows, bounded by the next tick or the limit. The fee is taken from the input. Exact-in consumes input and produces output; exact-out targets an output and back-computes input — same code path, routed by the sign of amountSpecified.

5.4 · Crossing a tick (liquidityNet vs liquidityGross)

Each tick stores liquidityNet — the signed change to active liquidity when crossed (a position adds +L at its lower tick, −L at its upper). Tick.cross applies it and flips feeGrowthOutside. liquidityGross tracks total referencing liquidity for bookkeeping (when it hits zero the tick uninitializes). When crossing left (zeroForOne), the sign is negated.

5.5 · The edge-of-tick case (your specific question)

As a swap pushes price to a range boundary, one real reserve of in-range positions goes to zero. The crucial distinction: price (√P) moves continuously across the boundary, but active liquidity L jumps discretely at the crossing.

single position L=1,000,000 on [tickLo, tickHi]; price rising (oneForZero)
... swap consumes token1 in, pays token0 out, √P climbs toward √P(tickHi)
at √P = √P(tickHi):  x_real = L(1/√P_hi − 1/√P_hi) = 0   → position now 100% token1
computeSwapStep returns sqrtPriceX96 == sqrtPriceNextX96  → reached the tick exactly
Tick.cross(tickHi):  liquidityNet here is −L (it's this position's UPPER bound)
state.liquidity += (−L)  → active L drops to whatever the NEXT range holds (maybe 0)
√P keeps moving continuously into the next range; L is now the next range's depth

5.6 · Exact-in vs exact-out side by side

MODULE 06 Fees

Where the fee is taken, the rigorous proof that only in-range LPs earn, protocol fees — and why there are no liquidators in an AMM.

6.1 · Accrual

In computeSwapStep the fee is skimmed from the input each step and added to feeGrowthGlobalX128 as feeAmount · 2^128 / liquidity — i.e. fee per unit of active liquidity. So only the liquidity that was active during that step shares in it.

6.2 · In-range vs out-of-range (proved, not asserted)

From Module 4.3, a position's earned fee is L · (f_inside,now − f_inside,last). While price is outside the range, f_inside does not change — the feeGrowthOutside subtraction holds the inside-accumulator flat — so the difference contributes zero. Therefore:

• Liquidity parked in a range where swaps happen outside earns nothing — provably, from the accumulator, not by assertion.
• When a swap occurs at a price inside a range, only positions whose ranges include that price are "active," and they split that step's fee pro-rata by liquidity (because the global accrual is per-unit-L and only their L is active).

6.3 · Protocol fees

setFeeProtocol sets a fraction (e.g. 1/4 to 1/10) of the swap fee to divert to the protocol; it's skimmed in computeSwapStep before the rest goes to LPs, accumulated in protocolFees, and withdrawn by the owner via collectProtocol.

MODULE 07 Pool lifecycle & admin

Factory CREATE2 pool creation, initialization, owner-gated functions, and why core immutability is a feature.

7.1 · Factory & pool creation

UniswapV3Factory.createPool(tokenA, tokenB, fee) orders the tokens (token0 = lower address), looks up the tickSpacing for that fee, and deploys via CREATE2 with a deterministic salt:

pool = address(new UniswapV3Pool{salt: keccak256(abi.encode(token0, token1, fee))}());

Deterministic addresses let anyone compute a pool's address off-chain from (token0, token1, fee) without a registry lookup. enableFeeAmount(fee, tickSpacing) adds new fee/spacing tiers (owner-only).

7.2 · Initialization

initialize(sqrtPriceX96) sets the starting price and tick once; a pool must be initialized before any mint or swap. This bootstraps slot0 (the packed current price, tick, and oracle state).

7.3 · Admin / immutability

Owner-gated: setFeeProtocol, collectProtocol, and factory setOwner. Critically, core is immutable — there is no admin who can move user funds, pause the pool, or change the math. The only owner powers are the protocol-fee switch and collecting already-accrued protocol fees. Immutability is the feature: users get a permanent guarantee the rules can't change under them.

MODULE 08 The price oracle (TWAP)

The observation ring buffer, the tick accumulator, computing a TWAP, and why it uses the log-price.

8.1 · Observations

Each pool keeps a ring buffer of Observations: a timestamp, a tick accumulator (cumulative sum of the current tick × seconds), a cumulative 1/liquidity, and an init flag. observe(secondsAgos[]) interpolates between stored observations to return accumulators at past times.

8.2 · The tick accumulator & TWAP

Two observations give the average tick over the window by a simple difference-over-time. Convert back to a price with P = 1.0001^{\bar i}.

8.3 · Why log-price, why it exists

Averaging the tick (log price) rather than the price means the TWAP is a geometric mean — robust to asymmetric spikes and cheap to accumulate (just add tick × Δt). On-chain TWAP exists so other protocols can read a manipulation-resistant price: moving a TWAP requires sustaining a manipulated price across time (and paying arbitrage), not just a single-block push. Its limitation: it lags, and very short windows are cheaper to manipulate.

MODULE 09 Building your own DEX

A build order, the correctness pitfalls and how to test them, what to reuse vs re-derive, non-EVM porting, and invariant tests.

9.1 · Recommended build order

1. Fixed-point + math libs (Modules 1, 3.4): FullMath.mulDiv, TickMath, SqrtPriceMath. Get these bit-exact first.
2. Ticks + bitmap (Module 2): Tick.update/cross, TickBitmap.flipTick/nextInitializedTickWithinOneWord.
3. Positions + fee growth (Module 4): the accumulator accounting.
4. mint/burn/collect with callbacks.
5. The swap loop (Module 5) — last and slowest; it composes everything above.
6. Oracle (Module 8) and factory/init (Module 7).

9.2 · Top correctness pitfalls & how to test

9.3 · Reuse vs re-derive

Reuse the battle-tested libs: TickMath, SqrtPriceMath, FullMath. FullMath.mulDiv(a, b, denominator) computes a·b/denominator at full 512-bit precision — it splits the 512-bit product across two words and does long division, so a·b can exceed 2^256 without overflow. Re-deriving this from scratch is the most common source of value-leaking bugs, so reuse it.

9.4 · Non-EVM porting (conceptual)

• Account model: on Solana there's no contract storage of mappings — ticks/positions become program-derived accounts (PDAs); the bitmap becomes a set of fixed-size accounts.
• Compute budget: the swap loop must bound tick crossings per transaction; a long crossing run can exceed the compute limit.
• Fixed-point libs: no native 256-bit mulDiv — you implement the 512-bit trick or use u128 with care.
• No callbacks: the EVM mint/swap callback pattern is replaced by pre-funded transfers/CPI ordering.

9.5 · Minimal invariant tests

• Reserve conservation: sum of all positions' real reserves at the current price ≈ pool token balances (minus fees/protocol fees).
• Liquidity conservation: a swap that doesn't cross a tick leaves active L unchanged.
• Fee-growth monotonicity: feeGrowthGlobal never decreases.
• No-arb round trip: swap A→B→A returns ≤ the input (fees make it strictly less) — never more.
• Tick consistency: getTickAtSqrtRatio(getSqrtRatioAtTick(i)) == i for all valid i.