Slipstream Swapping

Swaps in Slipstream traverse through ticks, consuming liquidity in each price range. This skill covers the swap mechanics.

Overview

┌──────────────────────────────────────────────────────────────┐
│                     SWAP EXECUTION                           │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  Price Movement During Swap                                  │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │                                                         │ │
│  │  tickA        tickB        tickC        tickD           │ │
│  │    ▼           ▼           ▼           ▼               │ │
│  │  ──┬───────────┬───────────┬───────────┬──             │ │
│  │    │  Liq: 50  │  Liq: 80  │  Liq: 30  │               │ │
│  │    │           │           │           │               │ │
│  │  [START]──────────────────────────►[END]                │ │
│  │    Price moves through ticks as swap executes           │ │
│  │                                                         │ │
│  └─────────────────────────────────────────────────────────┘ │
│                                                              │
│  Swap Steps:                                                 │
│  1. Start at current tick/price                              │
│  2. Compute max amount to next initialized tick              │
│  3. Execute partial swap, collect fees                       │
│  4. If tick crossed: update liquidity, repeat                │
│  5. Continue until amount exhausted or price limit hit       │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Swap Function

// CLPool.sol

/// @notice Execute a swap
/// @param recipient Address to receive output tokens
/// @param zeroForOne Direction: true = token0→token1, false = token1→token0
/// @param amountSpecified Amount (positive = exact input, negative = exact output)
/// @param sqrtPriceLimitX96 Price limit to stop swap
/// @param data Callback data
/// @return amount0 Token0 delta (negative = sent, positive = received)
/// @return amount1 Token1 delta (negative = sent, positive = received)
function swap(
    address recipient,
    bool zeroForOne,
    int256 amountSpecified,
    uint160 sqrtPriceLimitX96,
    bytes calldata data
) external lock returns (int256 amount0, int256 amount1) {
    require(amountSpecified != 0, "AS");

    Slot0 memory slot0Start = slot0;
    require(slot0Start.unlocked, "LOK");

    // Validate price limit
    require(
        zeroForOne
            ? sqrtPriceLimitX96 < slot0Start.sqrtPriceX96 && sqrtPriceLimitX96 > MIN_SQRT_RATIO
            : sqrtPriceLimitX96 > slot0Start.sqrtPriceX96 && sqrtPriceLimitX96 < MAX_SQRT_RATIO,
        "SPL"
    );

    slot0.unlocked = false;

    // Initialize swap state
    SwapCache memory cache = SwapCache({
        liquidityStart: liquidity,
        blockTimestamp: _blockTimestamp(),
        feeProtocol: zeroForOne ? slot0Start.feeProtocol % 16 : slot0Start.feeProtocol >> 4,
        secondsPerLiquidityCumulativeX128: 0,
        tickCumulative: 0,
        computedLatestObservation: false
    });

    bool exactInput = amountSpecified > 0;

    SwapState memory state = SwapState({
        amountSpecifiedRemaining: amountSpecified,
        amountCalculated: 0,
        sqrtPriceX96: slot0Start.sqrtPriceX96,
        tick: slot0Start.tick,
        feeGrowthGlobalX128: zeroForOne ? feeGrowthGlobal0X128 : feeGrowthGlobal1X128,
        liquidity: cache.liquidityStart,
        stakedLiquidity: stakedLiquidity
    });

    // Execute swap loop
    while (state.amountSpecifiedRemaining != 0 && state.sqrtPriceX96 != sqrtPriceLimitX96) {
        StepComputations memory step;

        step.sqrtPriceStartX96 = state.sqrtPriceX96;

        // Find next initialized tick
        (step.tickNext, step.initialized) = tickBitmap.nextInitializedTickWithinOneWord(
            state.tick,
            tickSpacing,
            zeroForOne
        );

        // Clamp to valid tick range
        if (step.tickNext < MIN_TICK) step.tickNext = MIN_TICK;
        else if (step.tickNext > MAX_TICK) step.tickNext = MAX_TICK;

        step.sqrtPriceNextX96 = TickMath.getSqrtRatioAtTick(step.tickNext);

        // Compute swap step
        (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
            );

        // Update amounts
        if (exactInput) {
            state.amountSpecifiedRemaining -= (step.amountIn + step.feeAmount).toInt256();
            state.amountCalculated = state.amountCalculated.sub(step.amountOut.toInt256());
        } else {
            state.amountSpecifiedRemaining += step.amountOut.toInt256();
            state.amountCalculated = state.amountCalculated.add((step.amountIn + step.feeAmount).toInt256());
        }

        // Update fee growth
        if (state.liquidity > 0) {
            // Split fees between staked and unstaked
            (uint256 unstakedFeeAmount, uint256 stakedFeeAmount) = splitFees(
                step.feeAmount,
                state.liquidity,
                state.stakedLiquidity
            );

            // Unstaked fees go to fee growth
            state.feeGrowthGlobalX128 += FullMath.mulDiv(
                unstakedFeeAmount,
                FixedPoint128.Q128,
                state.liquidity - state.stakedLiquidity
            );

            // Staked fees go to gauge
            if (stakedFeeAmount > 0) {
                gaugeFees.token0 += zeroForOne ? uint128(stakedFeeAmount) : 0;
                gaugeFees.token1 += zeroForOne ? 0 : uint128(stakedFeeAmount);
            }
        }

        // Cross tick if reached
        if (state.sqrtPriceX96 == step.sqrtPriceNextX96) {
            if (step.initialized) {
                // Update oracle if needed
                if (!cache.computedLatestObservation) {
                    (cache.tickCumulative, cache.secondsPerLiquidityCumulativeX128) =
                        observations.observeSingle(...);
                    cache.computedLatestObservation = true;
                }

                // Cross tick - update liquidity
                int128 liquidityNet = ticks.cross(
                    step.tickNext,
                    zeroForOne ? state.feeGrowthGlobalX128 : feeGrowthGlobal0X128,
                    zeroForOne ? feeGrowthGlobal1X128 : state.feeGrowthGlobalX128,
                    ...
                );

                // Update liquidity
                if (zeroForOne) liquidityNet = -liquidityNet;
                state.liquidity = LiquidityMath.addDelta(state.liquidity, liquidityNet);

                // Update staked liquidity similarly
                int128 stakedLiquidityNet = ...;
                state.stakedLiquidity = LiquidityMath.addDelta(state.stakedLiquidity, stakedLiquidityNet);
            }

            state.tick = zeroForOne ? step.tickNext - 1 : step.tickNext;
        } else if (state.sqrtPriceX96 != step.sqrtPriceStartX96) {
            state.tick = TickMath.getTickAtSqrtRatio(state.sqrtPriceX96);
        }
    }

    // Write oracle observation if tick changed
    if (state.tick != slot0Start.tick) {
        (slot0.sqrtPriceX96, slot0.tick, slot0.observationIndex, slot0.observationCardinality) =
            (
                state.sqrtPriceX96,
                state.tick,
                observations.write(...),
                cache.observationCardinalityNext
            );
    } else {
        slot0.sqrtPriceX96 = state.sqrtPriceX96;
    }

    // Update global state
    if (cache.liquidityStart != state.liquidity) liquidity = state.liquidity;
    if (zeroForOne) feeGrowthGlobal0X128 = state.feeGrowthGlobalX128;
    else feeGrowthGlobal1X128 = state.feeGrowthGlobalX128;

    // Calculate final amounts
    (amount0, amount1) = zeroForOne == exactInput
        ? (amountSpecified - state.amountSpecifiedRemaining, state.amountCalculated)
        : (state.amountCalculated, amountSpecified - state.amountSpecifiedRemaining);

    // Transfer tokens
    if (zeroForOne) {
        if (amount1 < 0) TransferHelper.safeTransfer(token1, recipient, uint256(-amount1));

        uint256 balance0Before = balance0();
        ISwapCallback(msg.sender).uniswapV3SwapCallback(amount0, amount1, data);
        require(balance0Before.add(uint256(amount0)) <= balance0(), "IIA");
    } else {
        if (amount0 < 0) TransferHelper.safeTransfer(token0, recipient, uint256(-amount0));

        uint256 balance1Before = balance1();
        ISwapCallback(msg.sender).uniswapV3SwapCallback(amount0, amount1, data);
        require(balance1Before.add(uint256(amount1)) <= balance1(), "IIA");
    }

    slot0.unlocked = true;

    emit Swap(msg.sender, recipient, amount0, amount1, state.sqrtPriceX96, state.liquidity, state.tick);
}

Swap State

struct SwapState {
    int256 amountSpecifiedRemaining;  // Amount left to swap
    int256 amountCalculated;          // Output amount accumulated
    uint160 sqrtPriceX96;             // Current sqrt price
    int24 tick;                       // Current tick
    uint256 feeGrowthGlobalX128;      // Fee growth accumulator
    uint128 liquidity;                // Current liquidity
    uint128 stakedLiquidity;          // Current staked liquidity
}

struct StepComputations {
    uint160 sqrtPriceStartX96;  // Price at step start
    int24 tickNext;             // Next initialized tick
    bool initialized;           // Is tickNext initialized
    uint160 sqrtPriceNextX96;   // Price at tickNext
    uint256 amountIn;           // Input amount in this step
    uint256 amountOut;          // Output amount in this step
    uint256 feeAmount;          // Fee collected in this step
}

Swap Math

// SwapMath.sol

/// @notice Compute amounts for a single swap step
function computeSwapStep(
    uint160 sqrtRatioCurrentX96,
    uint160 sqrtRatioTargetX96,
    uint128 liquidity,
    int256 amountRemaining,
    uint24 feePips
) internal pure returns (
    uint160 sqrtRatioNextX96,
    uint256 amountIn,
    uint256 amountOut,
    uint256 feeAmount
) {
    bool zeroForOne = sqrtRatioCurrentX96 >= sqrtRatioTargetX96;
    bool exactIn = amountRemaining >= 0;

    if (exactIn) {
        // Calculate max input after fee
        uint256 amountRemainingLessFee = FullMath.mulDiv(
            uint256(amountRemaining),
            1e6 - feePips,
            1e6
        );

        // Calculate input amount to reach target price
        amountIn = zeroForOne
            ? SqrtPriceMath.getAmount0Delta(sqrtRatioTargetX96, sqrtRatioCurrentX96, liquidity, true)
            : SqrtPriceMath.getAmount1Delta(sqrtRatioCurrentX96, sqrtRatioTargetX96, liquidity, true);

        if (amountRemainingLessFee >= amountIn) {
            // Can reach target price
            sqrtRatioNextX96 = sqrtRatioTargetX96;
        } else {
            // Partial fill
            sqrtRatioNextX96 = SqrtPriceMath.getNextSqrtPriceFromInput(
                sqrtRatioCurrentX96,
                liquidity,
                amountRemainingLessFee,
                zeroForOne
            );
        }
    } else {
        // Exact output
        amountOut = zeroForOne
            ? SqrtPriceMath.getAmount1Delta(sqrtRatioTargetX96, sqrtRatioCurrentX96, liquidity, false)
            : SqrtPriceMath.getAmount0Delta(sqrtRatioCurrentX96, sqrtRatioTargetX96, liquidity, false);

        if (uint256(-amountRemaining) >= amountOut) {
            sqrtRatioNextX96 = sqrtRatioTargetX96;
        } else {
            sqrtRatioNextX96 = SqrtPriceMath.getNextSqrtPriceFromOutput(
                sqrtRatioCurrentX96,
                liquidity,
                uint256(-amountRemaining),
                zeroForOne
            );
        }
    }

    // Calculate final amounts
    bool max = sqrtRatioTargetX96 == sqrtRatioNextX96;

    if (zeroForOne) {
        amountIn = max && exactIn
            ? amountIn
            : SqrtPriceMath.getAmount0Delta(sqrtRatioNextX96, sqrtRatioCurrentX96, liquidity, true);
        amountOut = max && !exactIn
            ? amountOut
            : SqrtPriceMath.getAmount1Delta(sqrtRatioNextX96, sqrtRatioCurrentX96, liquidity, false);
    } else {
        amountIn = max && exactIn
            ? amountIn
            : SqrtPriceMath.getAmount1Delta(sqrtRatioCurrentX96, sqrtRatioNextX96, liquidity, true);
        amountOut = max && !exactIn
            ? amountOut
            : SqrtPriceMath.getAmount0Delta(sqrtRatioCurrentX96, sqrtRatioNextX96, liquidity, false);
    }

    // Cap output at exact output amount
    if (!exactIn && amountOut > uint256(-amountRemaining)) {
        amountOut = uint256(-amountRemaining);
    }

    // Calculate fee
    if (exactIn && sqrtRatioNextX96 != sqrtRatioTargetX96) {
        feeAmount = uint256(amountRemaining) - amountIn;
    } else {
        feeAmount = FullMath.mulDivRoundingUp(amountIn, feePips, 1e6 - feePips);
    }
}

Tick Crossing

// Tick.sol

/// @notice Cross a tick, updating state
function cross(
    mapping(int24 => Tick.Info) storage self,
    int24 tick,
    uint256 feeGrowthGlobal0X128,
    uint256 feeGrowthGlobal1X128,
    uint256 rewardGrowthGlobalX128,
    uint160 secondsPerLiquidityCumulativeX128,
    int56 tickCumulative,
    uint32 time
) internal returns (int128 liquidityNet, int128 stakedLiquidityNet) {
    Tick.Info storage info = self[tick];

    // Flip "outside" values
    // "Outside" means the side of the tick where current price is NOT
    info.feeGrowthOutside0X128 = feeGrowthGlobal0X128 - info.feeGrowthOutside0X128;
    info.feeGrowthOutside1X128 = feeGrowthGlobal1X128 - info.feeGrowthOutside1X128;
    info.rewardGrowthOutsideX128 = rewardGrowthGlobalX128 - info.rewardGrowthOutsideX128;

    info.secondsPerLiquidityOutsideX128 =
        secondsPerLiquidityCumulativeX128 - info.secondsPerLiquidityOutsideX128;
    info.tickCumulativeOutside = tickCumulative - info.tickCumulativeOutside;
    info.secondsOutside = time - info.secondsOutside;

    liquidityNet = info.liquidityNet;
    stakedLiquidityNet = info.stakedLiquidityNet;
}

Swap Direction

// zeroForOne = true:  Selling token0 for token1 (price decreases)
// zeroForOne = false: Selling token1 for token0 (price increases)

// Example: ETH/USDC pool (token0=USDC, token1=ETH)
// Buying ETH with USDC: zeroForOne = true
// Selling ETH for USDC: zeroForOne = false

// Amount specification:
// amountSpecified > 0: Exact input (selling exactly this much)
// amountSpecified < 0: Exact output (buying exactly this much)

Events

event Swap(
    address indexed sender,
    address indexed recipient,
    int256 amount0,
    int256 amount1,
    uint160 sqrtPriceX96,
    uint128 liquidity,
    int24 tick
);

Reference Files

• contracts/core/CLPool.sol - swap() function
• contracts/core/libraries/SwapMath.sol - Swap step calculations
• contracts/core/libraries/SqrtPriceMath.sol - Amount calculations
• contracts/core/libraries/Tick.sol - Tick crossing