# 深入理解 Uniswap v3 合约代码 （二）

###### tags: `uniswap` `solidity` `logarithm` `uniswap-v3` `tick` `periphery` `contract`

## Uniswap-v3-periphery

[Uniswap-v3-core](https://hackmd.io/TDPPCAIgRRqVDPwsSm6Kfw)合约定义的是基础方法，而Uniswap-v3-periphery合约才是我们平常直接交互的合约。

比如，众所周知Uniswap v3头寸是一个NFT，这个NFT就是在periphery合约中创建和管理的，在core合约中并没有任何NFT的概念。

### NonfungiblePositionManager.sol

头寸管理合约，全局仅有一个，负责管理所有交易对的头寸，主要包括以下几个方法：

* [createAndInitializePoolIfNecessary](#createAndInitializePoolIfNecessary)：创建并初始化合约
* [mint](#mint)：创建头寸
* [increaseLiquidity](#increaseLiquidity)：添加流动性
* [decreaseLiquidity](#decreaseLiquidity)：减少流动性
* [burn](#burn)：销毁头寸
* [collect](#collect)：取回代币

需要特别注意，该合约继承了`ERC721`，可以mint NFT。因为每个Uniswap v3的头寸（由`owner`、`tickLower`和`tickUpper`确定）是唯一的，因此非常适合用NFT表示。

#### createAndInitializePoolIfNecessary

我们在[Uniswap-v3-core](https://hackmd.io/TDPPCAIgRRqVDPwsSm6Kfw)中提到，一个交易对合约被创建后，需要初始化才能使用。

本方法就把这一系列操作合并成一个方法：创建并初始化交易对。

/// @inheritdoc IPoolInitializer
function createAndInitializePoolIfNecessary(
    address token0,
    address token1,
    uint24 fee,
    uint160 sqrtPriceX96
) external payable override returns (address pool) {
    require(token0 < token1);
    pool = IUniswapV3Factory(factory).getPool(token0, token1, fee);

    if (pool == address(0)) {
        pool = IUniswapV3Factory(factory).createPool(token0, token1, fee);
        IUniswapV3Pool(pool).initialize(sqrtPriceX96);
    } else {
        (uint160 sqrtPriceX96Existing, , , , , , ) = IUniswapV3Pool(pool).slot0();
        if (sqrtPriceX96Existing == 0) {
            IUniswapV3Pool(pool).initialize(sqrtPriceX96);
        }
    }
}

首先根据交易对代币（`token`和`token1`）和手续费`fee`获取`pool`对象：

* 如果不存在，则调用Uniswap-v3-core工厂合约`createPool`创建该交易对并初始化
* 如果已存在，则根据额`slot0`判断是否已经初始化（价格），如果没有则调用Uniswap-v3-core的`initialize`方法进行初始化。

#### mint

创建新头寸，方法接受的参数如下：

* `token0`：代币0
* `token1`：代币1
* `fee`：手续费等级（需符合工厂合约中定义的手续费等级）
* `tickLower`：价格区间低点
* `tickUpper`：价格区间高点
* `amount0Desired`：希望存入的代币0数量
* `amount1Desired`：希望存入的代币1数量
* `amount0Min`：最少存入的`token0`数量（防止被frontrun）
* `amount1Min`：最少存入的`token1`数量（防止被frontrun）
* `recipient`：头寸接收者
* `deadline`：截止时间（超过该时间后请求无效）（防止重放攻击）

返回：

* `tokenId`：每个头寸会分配一个唯一的`tokenId`，代表NFT
* `liquidity`：头寸的流动性
* `amount0`：`token0`的数量
* `amount1`：`token1`的数量

/// @inheritdoc INonfungiblePositionManager
function mint(MintParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (
        uint256 tokenId,
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1
    )
{
    IUniswapV3Pool pool;
    (liquidity, amount0, amount1, pool) = addLiquidity(
        AddLiquidityParams({
            token0: params.token0,
            token1: params.token1,
            fee: params.fee,
            recipient: address(this),
            tickLower: params.tickLower,
            tickUpper: params.tickUpper,
            amount0Desired: params.amount0Desired,
            amount1Desired: params.amount1Desired,
            amount0Min: params.amount0Min,
            amount1Min: params.amount1Min
        })
    );

首先通过[addLiquidity](#addLiquidity)方法完成流动性添加，获得实际得到的流动性`liquidity`，消耗的`amount0`、`amount1`，以及交易对`pool`。

    _mint(params.recipient, (tokenId = _nextId++));

通过`ERC721`合约的`_mint`方法，向接收者`recipient`铸造NFT，`tokenId`从1开始递增。

    bytes32 positionKey = PositionKey.compute(address(this), params.tickLower, params.tickUpper);
    (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) = pool.positions(positionKey);

    // idempotent set
    uint80 poolId =
        cachePoolKey(
            address(pool),
            PoolAddress.PoolKey({token0: params.token0, token1: params.token1, fee: params.fee})
        );

    _positions[tokenId] = Position({
        nonce: 0,
        operator: address(0),
        poolId: poolId,
        tickLower: params.tickLower,
        tickUpper: params.tickUpper,
        liquidity: liquidity,
        feeGrowthInside0LastX128: feeGrowthInside0LastX128,
        feeGrowthInside1LastX128: feeGrowthInside1LastX128,
        tokensOwed0: 0,
        tokensOwed1: 0
    });

    emit IncreaseLiquidity(tokenId, liquidity, amount0, amount1);
}

最后，保存头寸信息到`_positions`中。

#### increaseLiquidity

为一个头寸添加流动性。需注意，可以修改头寸的代币数量，但是不能修改价格区间。

参数如下：

* `tokenId`：创建头寸时返回的`tokenId`，即NFT的`tokenId`
* `amount0Desired`：希望添加的`token0`数量
* `amount1Desired`：希望添加的`token1`数量
* `amount0Min`：最少添加的`token0`数量（防止被frontrun）
* `amount1Min`：最少添加的`token1`数量（防止被frontrun）
* `deadline`：截止时间（超过该时间后请求无效）（防止重放攻击）

/// @inheritdoc INonfungiblePositionManager
function increaseLiquidity(IncreaseLiquidityParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1
    )
{
    Position storage position = _positions[params.tokenId];

    PoolAddress.PoolKey memory poolKey = _poolIdToPoolKey[position.poolId];

    IUniswapV3Pool pool;
    (liquidity, amount0, amount1, pool) = addLiquidity(
        AddLiquidityParams({
            token0: poolKey.token0,
            token1: poolKey.token1,
            fee: poolKey.fee,
            tickLower: position.tickLower,
            tickUpper: position.tickUpper,
            amount0Desired: params.amount0Desired,
            amount1Desired: params.amount1Desired,
            amount0Min: params.amount0Min,
            amount1Min: params.amount1Min,
            recipient: address(this)
        })
    );

首先根据`tokenId`获取头寸信息；与[mint](#mint)方法一样，这里调用[addLiquidity](#addLiquidity)添加流动性，返回添加成功的流动性`liquidity`，所消耗的`amount0`和`amount1`，以及交易对合约`pool`。

    bytes32 positionKey = PositionKey.compute(address(this), position.tickLower, position.tickUpper);

    // this is now updated to the current transaction
    (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) = pool.positions(positionKey);

    position.tokensOwed0 += uint128(
        FullMath.mulDiv(
            feeGrowthInside0LastX128 - position.feeGrowthInside0LastX128,
            position.liquidity,
            FixedPoint128.Q128
        )
    );
    position.tokensOwed1 += uint128(
        FullMath.mulDiv(
            feeGrowthInside1LastX128 - position.feeGrowthInside1LastX128,
            position.liquidity,
            FixedPoint128.Q128
        )
    );

    position.feeGrowthInside0LastX128 = feeGrowthInside0LastX128;
    position.feeGrowthInside1LastX128 = feeGrowthInside1LastX128;
    position.liquidity += liquidity;

    emit IncreaseLiquidity(params.tokenId, liquidity, amount0, amount1);
}

根据`pool`对象里的最新头寸信息，更新本合约的头寸状态，比如`token0`和`token1`的可取回代币数`tokensOwed0`和`tokensOwed1`，以及头寸当前流动性等。

> `tokensOwed0`, `tokensOwed1`, `feeGrowthInside0LastX128`，`feeGrowthInside1LastX128`和`liquidity`这几个数据在`pool.positions`方法都能够获取到，不知道这里为什么要再算一次。

#### decreaseLiquidity

移除流动性，可以移除部分或者所有流动性，移除后的代币将以待取回代币形式记录，需要再次调用[collect](#collect)方法取回代币。

参数如下：

* `tokenId`：创建头寸时返回的`tokenId`，即NFT的`tokenId`
* `liquidity`：希望移除的流动性数量
* `amount0Min`：最少移除的`token0`数量（防止被frontrun）
* `amount1Min`：最少移除的`token1`数量（防止被frontrun）
* `deadline`：截止时间（超过该时间请求无效）（防止重放攻击）

/// @inheritdoc INonfungiblePositionManager
function decreaseLiquidity(DecreaseLiquidityParams calldata params)
    external
    payable
    override
    isAuthorizedForToken(params.tokenId)
    checkDeadline(params.deadline)
    returns (uint256 amount0, uint256 amount1)
{

注意，这里使用`isAuthorizedForToken` modifer：

modifier isAuthorizedForToken(uint256 tokenId) {
    require(_isApprovedOrOwner(msg.sender, tokenId), 'Not approved');
    _;
}

确认当前用户具备操作该`tokenId`的权限，否则禁止移除。

    require(params.liquidity > 0);
    Position storage position = _positions[params.tokenId];

    uint128 positionLiquidity = position.liquidity;
    require(positionLiquidity >= params.liquidity);

确认头寸流动性大于等于待移除流动性。

    PoolAddress.PoolKey memory poolKey = _poolIdToPoolKey[position.poolId];
    IUniswapV3Pool pool = IUniswapV3Pool(PoolAddress.computeAddress(factory, poolKey));
    (amount0, amount1) = pool.burn(position.tickLower, position.tickUpper, params.liquidity);

    require(amount0 >= params.amount0Min && amount1 >= params.amount1Min, 'Price slippage check');

调用[Uniswap-v3-core](https://hackmd.io/TDPPCAIgRRqVDPwsSm6Kfw)的[burn](https://hackmd.io/TDPPCAIgRRqVDPwsSm6Kfw#burn)方法销毁流动性，返回该流动性对应的`token0`和`token1`的代币数量`amount0`和`amount1`，确认其符合`amount0Min`和`amount1Min`的限制。

    bytes32 positionKey = PositionKey.compute(address(this), position.tickLower, position.tickUpper);
    // this is now updated to the current transaction
    (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) = pool.positions(positionKey);

    position.tokensOwed0 +=
        uint128(amount0) +
        uint128(
            FullMath.mulDiv(
                feeGrowthInside0LastX128 - position.feeGrowthInside0LastX128,
                positionLiquidity,
                FixedPoint128.Q128
            )
        );
    position.tokensOwed1 +=
        uint128(amount1) +
        uint128(
            FullMath.mulDiv(
                feeGrowthInside1LastX128 - position.feeGrowthInside1LastX128,
                positionLiquidity,
                FixedPoint128.Q128
            )
        );

    position.feeGrowthInside0LastX128 = feeGrowthInside0LastX128;
    position.feeGrowthInside1LastX128 = feeGrowthInside1LastX128;
    // subtraction is safe because we checked positionLiquidity is gte params.liquidity
    position.liquidity = positionLiquidity - params.liquidity;

    emit DecreaseLiquidity(params.tokenId, params.liquidity, amount0, amount1);
}

与[increaseLiquidity](#increaseLiquidity)相同，此处计算头寸的待取回代币等信息。

#### burn

销毁头寸NFT。仅当该头寸的流动性为0，并且待取回代币数量都是0时，才能销毁NFT。

同样，调用该方法需要验证当前用户拥有`tokenId`的权限。

/// @inheritdoc INonfungiblePositionManager
function burn(uint256 tokenId) external payable override isAuthorizedForToken(tokenId) {
    Position storage position = _positions[tokenId];
    require(position.liquidity == 0 && position.tokensOwed0 == 0 && position.tokensOwed1 == 0, 'Not cleared');
    delete _positions[tokenId];
    _burn(tokenId);
}

#### collect

取回待领取代币。

参数如下：

* `tokenId`：创建头寸时返回的`tokenId`，即NFT的`tokenId`
* `recipient`：代币接收者
* `amount0Max`：最多领取的`token0`代币数量
* `amount1Max`：最多领取的`token1`代币数量

/// @inheritdoc INonfungiblePositionManager
function collect(CollectParams calldata params)
    external
    payable
    override
    isAuthorizedForToken(params.tokenId)
    returns (uint256 amount0, uint256 amount1)
{
    require(params.amount0Max > 0 || params.amount1Max > 0);
    // allow collecting to the nft position manager address with address 0
    address recipient = params.recipient == address(0) ? address(this) : params.recipient;

    Position storage position = _positions[params.tokenId];

    PoolAddress.PoolKey memory poolKey = _poolIdToPoolKey[position.poolId];

    IUniswapV3Pool pool = IUniswapV3Pool(PoolAddress.computeAddress(factory, poolKey));

    (uint128 tokensOwed0, uint128 tokensOwed1) = (position.tokensOwed0, position.tokensOwed1);

获取待取回代币数量。

    // trigger an update of the position fees owed and fee growth snapshots if it has any liquidity
    if (position.liquidity > 0) {
        pool.burn(position.tickLower, position.tickUpper, 0);
        (, uint256 feeGrowthInside0LastX128, uint256 feeGrowthInside1LastX128, , ) =
            pool.positions(PositionKey.compute(address(this), position.tickLower, position.tickUpper));

        tokensOwed0 += uint128(
            FullMath.mulDiv(
                feeGrowthInside0LastX128 - position.feeGrowthInside0LastX128,
                position.liquidity,
                FixedPoint128.Q128
            )
        );
        tokensOwed1 += uint128(
            FullMath.mulDiv(
                feeGrowthInside1LastX128 - position.feeGrowthInside1LastX128,
                position.liquidity,
                FixedPoint128.Q128
            )
        );

        position.feeGrowthInside0LastX128 = feeGrowthInside0LastX128;
        position.feeGrowthInside1LastX128 = feeGrowthInside1LastX128;
    }

如果该头寸含有流动性，则触发一次头寸状态的更新，这里使用`burn` 0流动性来触发。这是因为Uniswap-v3-core只在`mint`和`burn`时才更新头寸状态，而`collect`方法可能在`swap`之后被调用，可能会导致头寸状态不是最新的。

    // compute the arguments to give to the pool#collect method
    (uint128 amount0Collect, uint128 amount1Collect) =
        (
            params.amount0Max > tokensOwed0 ? tokensOwed0 : params.amount0Max,
            params.amount1Max > tokensOwed1 ? tokensOwed1 : params.amount1Max
        );

    // the actual amounts collected are returned
    (amount0, amount1) = pool.collect(
        recipient,
        position.tickLower,
        position.tickUpper,
        amount0Collect,
        amount1Collect
    );

    // sometimes there will be a few less wei than expected due to rounding down in core, but we just subtract the full amount expected
    // instead of the actual amount so we can burn the token
    (position.tokensOwed0, position.tokensOwed1) = (tokensOwed0 - amount0Collect, tokensOwed1 - amount1Collect);

    emit Collect(params.tokenId, recipient, amount0Collect, amount1Collect);
}

调用Uniswap-v3-core的`collect`方法取回代币，并更新头寸的待取回代币数量。

### SwapRouter.sol

交换代币，包括以下几个方法：

* [exactInputSingle](#exactInputSingle)：单步交换，指定输入代币数量，尽可能多地获得输出代币
* [exactInput](#exactInput)：多步交换，指定输入代币数量，尽可能多地获得输出代币
* [exactOutputSingle](#exactOutputSingle)：单步交换，指定输出代币数量，尽可能少地提供输入代币
* [exactOutput](#exactOutput)：多步交换，指定输出代币数量，尽可能少地提供输入代币

另外，该合约也实现了：

* [uniswapV3SwapCallback](#uniswapV3SwapCallback)：交换回调方法
* [exactInputInternal](#exactInputInternal)：单步交换，内部方法，指定输入代币数量，尽可能多地获得输出代币
* [exactOutputInternal](#exactOutputInternal)：单步交换，内部方法，指定输出代币数量，尽可能少地提供输入代币

#### exactInputSingle

单步交换，指定输入代币数量，尽可能多地获得输出代币。

参数如下：

* `tokenIn`：输入代币地址
* `tokenOut`：输出代币地址
* `fee`：手续费等级
* `recipient`：输出代币接收者
* `deadline`：截止时间，超过该时间请求无效
* `amountIn`：输入的代币数量
* `amountOutMinimum`：最少收到的输出代币数量
* `sqrtPriceLimitX96`：（最高或最低）限制价格

返回：

* `amountOut`：输出代币数量

/// @inheritdoc ISwapRouter
function exactInputSingle(ExactInputSingleParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (uint256 amountOut)
{
    amountOut = exactInputInternal(
        params.amountIn,
        params.recipient,
        params.sqrtPriceLimitX96,
        SwapCallbackData({path: abi.encodePacked(params.tokenIn, params.fee, params.tokenOut), payer: msg.sender})
    );
    require(amountOut >= params.amountOutMinimum, 'Too little received');
}

该方法实际上调用[exactInputInternal](#exactInputInternal)，最后确认输出代币数量`amountOut`符合最小输出代币要求`amountOutMinimum`。

注意，`SwapCallbackData`中的`path`按照[Path.sol](#Pathsol)中定义的格式编码。

#### exactInput

多步交换，指定输入代币数量，尽可能多地获得输出代币。

参数如下：

* `path`：交换路径，格式请参考：[Path.sol](#Pathsol)
* `recipient`：输出代币收款人
* `deadline`：交易截止时间
* `amountIn`：输入代币数量
* `amountOutMinimum`：最少输出代币数量

返回：

* `amountOut`：输出代币

/// @inheritdoc ISwapRouter
function exactInput(ExactInputParams memory params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (uint256 amountOut)
{
    address payer = msg.sender; // msg.sender pays for the first hop

    while (true) {
        bool hasMultiplePools = params.path.hasMultiplePools();

        // the outputs of prior swaps become the inputs to subsequent ones
        params.amountIn = exactInputInternal(
            params.amountIn,
            hasMultiplePools ? address(this) : params.recipient, // for intermediate swaps, this contract custodies
            0,
            SwapCallbackData({
                path: params.path.getFirstPool(), // only the first pool in the path is necessary
                payer: payer
            })
        );

        // decide whether to continue or terminate
        if (hasMultiplePools) {
            payer = address(this); // at this point, the caller has paid
            params.path = params.path.skipToken();
        } else {
            amountOut = params.amountIn;
            break;
        }
    }

    require(amountOut >= params.amountOutMinimum, 'Too little received');
}

在多步交换中，需要按照交换路径，拆成多个单步交换，循环进行，直到路径结束。

如果是第一步交换，则`payer`为合约调用方，否则，`payer`为当前`SwapRouter`合约。

在循环中首先根据[hasMultiplePools](#hasMultiplePools)判断路径`path`中是否剩余2个及以上的池子。如果有，则中间交换步骤的收款地址设置为当前`SwapRouter`合约，否则设置为入口参数`recipient`。

每一步交换后，将当前交换路径`path`的前20+3个字节删除，即弹出（pop）最前面的token+fee信息，进入下一次交换，并将每一步交换的输出作为下一次交换的输入。

每一步交换调用[exactInputInternal](#exactInputInternal)进行。

多步交换后，确认最后的`amountOut`满足最小输出代币要求`amountOutMinimum`。

#### exactOutputSingle

单步交换，指定输出代币数量，尽可能少地提供输入代币。

参数如下：

* `tokenIn`：输入代币地址
* `tokenOut`：输出代币地址
* `fee`：手续费等级
* `recipient`：输出代币收款人
* `deadline`：请求截止时间
* `amountOut`：输出代币数量
* `amountInMaximum`：最大输入代币数量
* `sqrtPriceLimitX96`：最大或最小代币价格

返回：

* `amountIn`：实际输入代币数量

/// @inheritdoc ISwapRouter
function exactOutputSingle(ExactOutputSingleParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (uint256 amountIn)
{
    // avoid an SLOAD by using the swap return data
    amountIn = exactOutputInternal(
        params.amountOut,
        params.recipient,
        params.sqrtPriceLimitX96,
        SwapCallbackData({path: abi.encodePacked(params.tokenOut, params.fee, params.tokenIn), payer: msg.sender})
    );

    require(amountIn <= params.amountInMaximum, 'Too much requested');
    // has to be reset even though we don't use it in the single hop case
    amountInCached = DEFAULT_AMOUNT_IN_CACHED;
}

调用[exactOutputInternal](#exactOutputInternal)完成单步交换，并确认实际输入代币数量`amountIn`小于等于最大输入代币数量`amountInMaximum`。

#### exactOutput

多步交换，指定输出代币数量，尽可能少地提供输入代币。

参数如下：

* `path`：交换路径，格式请参考：[Path.sol](#Path)
* `recipient`：输出代币收款人
* `deadline`：请求截止时间
* `amountOut`：指定输出代币数量
* `amountInMaximum`：最大输入代币数量

/// @inheritdoc ISwapRouter
function exactOutput(ExactOutputParams calldata params)
    external
    payable
    override
    checkDeadline(params.deadline)
    returns (uint256 amountIn)
{
    // it's okay that the payer is fixed to msg.sender here, as they're only paying for the "final" exact output
    // swap, which happens first, and subsequent swaps are paid for within nested callback frames
    exactOutputInternal(
        params.amountOut,
        params.recipient,
        0,
        SwapCallbackData({path: params.path, payer: msg.sender})
    );

    amountIn = amountInCached;
    require(amountIn <= params.amountInMaximum, 'Too much requested');
    amountInCached = DEFAULT_AMOUNT_IN_CACHED;
}

调用[exactOutputInternal](#exactOutputInternal)完成交换，注意，该方法会在回调方法中继续完成下一步交换，因此不需要像[exactInput](#exactInput)使用循环交易。

最后确认实际输入代币数量`amountIn`小于等于最大输入代币数量`amountInMaximum`。

#### exactInputInternal

单步交换，内部方法，指定输入代币数量，尽可能多地获得输出代币。

/// @dev Performs a single exact input swap
function exactInputInternal(
    uint256 amountIn,
    address recipient,
    uint160 sqrtPriceLimitX96,
    SwapCallbackData memory data
) private returns (uint256 amountOut) {
    // allow swapping to the router address with address 0
    if (recipient == address(0)) recipient = address(this);

如果没有指定`recipient`，则默认为当前`SwapRouter`合约地址。这是因为在多步交换时，需要将中间代币保存在当前`SwapRouter`合约。

    (address tokenIn, address tokenOut, uint24 fee) = data.path.decodeFirstPool();

根据[decodeFirstPool](#decodeFirstPool)解析`path`中第一个池子的信息。

    bool zeroForOne = tokenIn < tokenOut;

因为Uniswap v3池子`token0`地址小于`token1`，根据两个代币地址判断当前是否由`token0`交换到`token1`。注意，`tokenIn`可以是`token0`或`token1`。

    (int256 amount0, int256 amount1) =
        getPool(tokenIn, tokenOut, fee).swap(
            recipient,
            zeroForOne,
            amountIn.toInt256(),
            sqrtPriceLimitX96 == 0
                ? (zeroForOne ? TickMath.MIN_SQRT_RATIO + 1 : TickMath.MAX_SQRT_RATIO - 1)
                : sqrtPriceLimitX96,
            abi.encode(data)
        );

调用[swap](#swap)方法，获得完成本次交换所需的`amount0`和`amount1`。如果是从`token0`交换`token1`，则`amount1`是负数；反之，`amount0`是负数。

如果没有指定`sqrtPriceLimitX96`，则默认为最低或最高价格，因为在多步交换中，无法指定每一步的价格。

    return uint256(-(zeroForOne ? amount1 : amount0));

返回`amountOut`。

#### exactOutputInternal

单步交换，内部方法，指定输出代币数量，尽可能少地提供输入代币。

/// @dev Performs a single exact output swap
function exactOutputInternal(
    uint256 amountOut,
    address recipient,
    uint160 sqrtPriceLimitX96,
    SwapCallbackData memory data
) private returns (uint256 amountIn) {
    // allow swapping to the router address with address 0
    if (recipient == address(0)) recipient = address(this);

    (address tokenOut, address tokenIn, uint24 fee) = data.path.decodeFirstPool();

    bool zeroForOne = tokenIn < tokenOut;

这部分代码与[exactInputInternal](#exactInputInternal)类似。

    (int256 amount0Delta, int256 amount1Delta) =
        getPool(tokenIn, tokenOut, fee).swap(
            recipient,
            zeroForOne,
            -amountOut.toInt256(),
            sqrtPriceLimitX96 == 0
                ? (zeroForOne ? TickMath.MIN_SQRT_RATIO + 1 : TickMath.MAX_SQRT_RATIO - 1)
                : sqrtPriceLimitX96,
            abi.encode(data)
        );

调用[Uniswap-v3-core](https://hackmd.io/TDPPCAIgRRqVDPwsSm6Kfw)的`swap`方法完成单步交换，注意，因为是指定输出代币数量，此处需要使用`-amountOut.toInt256()`。
返回的`amount0Delta`和`amount1Delta`为完成本次交换所需的`token0`数量和实际输出的`token1`数量。

    uint256 amountOutReceived;
    (amountIn, amountOutReceived) = zeroForOne
        ? (uint256(amount0Delta), uint256(-amount1Delta))
        : (uint256(amount1Delta), uint256(-amount0Delta));
    // it's technically possible to not receive the full output amount,
    // so if no price limit has been specified, require this possibility away
    if (sqrtPriceLimitX96 == 0) require(amountOutReceived == amountOut);
}

#### uniswapV3SwapCallback

swap的回调方法，实现`IUniswapV3SwapCallback.uniswapV3SwapCallback`接口。

参数如下：

* `amount0Delta`：本次交换产生的`amount0`（对应代币为`token0`）；对于合约而言，如果大于0，则表示应输入代币；如果小于0，则表示应收到代币
* `amount1Delta`：本次交换产生的`amount1`（对应代币为`token1`）；对于合约而言，如果大于0，则表示应输入代币；如果小于0，则表示应收到代币
* `_data`：回调参数，这里为`SwapCallbackData`类型

/// @inheritdoc IUniswapV3SwapCallback
function uniswapV3SwapCallback(
    int256 amount0Delta,
    int256 amount1Delta,
    bytes calldata _data
) external override {
    require(amount0Delta > 0 || amount1Delta > 0); // swaps entirely within 0-liquidity regions are not supported
    SwapCallbackData memory data = abi.decode(_data, (SwapCallbackData));
    (address tokenIn, address tokenOut, uint24 fee) = data.path.decodeFirstPool();
    CallbackValidation.verifyCallback(factory, tokenIn, tokenOut, fee);

解析回调参数`_data`，根据[decodeFirstPool](#decodeFirstPool)获得交易路径上的第一个交易对信息。

    (bool isExactInput, uint256 amountToPay) =
        amount0Delta > 0
            ? (tokenIn < tokenOut, uint256(amount0Delta))
            : (tokenOut < tokenIn, uint256(amount1Delta));

根据不同输入，有以下几种交易组合：

|场景|说明|amount0Delta > 0|amount1Delta > 0|tokenIn < tokenOut|isExactInput|amountToPay|
|---|---|---|---|---|---|---|
|1|输入指定数量`token0`，输出尽可能多`token1`|true|false|true|true|amount0Delta|
|2|输入尽可能少`token0`，输出指定数量`token1`|true|false|true|false|amount0Delta|
|3|输入指定数量`token1`，输出尽可能多`token0`|false|true|false|true|amount1Delta|
|4|输入尽可能少`token1`，输出指定数量`token0`|false|true|false|false|amount1Delta|

    if (isExactInput) {
        pay(tokenIn, data.payer, msg.sender, amountToPay);
    } else {
        // either initiate the next swap or pay
        if (data.path.hasMultiplePools()) {
            data.path = data.path.skipToken();
            exactOutputInternal(amountToPay, msg.sender, 0, data);
        } else {
            amountInCached = amountToPay;
            tokenIn = tokenOut; // swap in/out because exact output swaps are reversed
            pay(tokenIn, data.payer, msg.sender, amountToPay);
        }
    }

* 如果`isExactInput`，即指定输入代币的场景，上表中的场景1和场景3，则直接向`SwapRouter`合约转账`amount0Delta`（场景1）或`amount1Delta`（场景3）（都是正数）。
* 如果是指定输出代币的场景
- 如果是多步交换，则移除前23的字符（pop最前面的token+fee），将需要的输入作为下一步的输出，进入下一步交换
- 如果是单步交换（或最后一步），则`tokenIn`与`tokenOut`交换，并向`SwapRouter`合约转账

### LiquidityManagement.sol

#### uniswapV3MintCallback

添加流动性的回调方法。

参数如下：

* `amount0Owed`：应转账的`token0`数量
* `amount1Owed`：应转账的`token1`数量
* `data`：在`mint`方法中传入的回调参数

/// @inheritdoc IUniswapV3MintCallback
function uniswapV3MintCallback(
    uint256 amount0Owed,
    uint256 amount1Owed,
    bytes calldata data
) external override {
    MintCallbackData memory decoded = abi.decode(data, (MintCallbackData));
    CallbackValidation.verifyCallback(factory, decoded.poolKey);

    if (amount0Owed > 0) pay(decoded.poolKey.token0, decoded.payer, msg.sender, amount0Owed);
    if (amount1Owed > 0) pay(decoded.poolKey.token1, decoded.payer, msg.sender, amount1Owed);
}

首先反向解析回调参数`MintCallbackData`，并确认该方法是被指定的交易对合约调用，因为该方法是一个`external`方法，可以被外部调用，因此需要确认调用方。

最后，向调用方转入指定的代币数量。

#### addLiquidity

给已初始化的交易对（池子）添加流动性。

/// @notice Add liquidity to an initialized pool
function addLiquidity(AddLiquidityParams memory params)
    internal
    returns (
        uint128 liquidity,
        uint256 amount0,
        uint256 amount1,
        IUniswapV3Pool pool
    )
{
    PoolAddress.PoolKey memory poolKey =
        PoolAddress.PoolKey({token0: params.token0, token1: params.token1, fee: params.fee});

    pool = IUniswapV3Pool(PoolAddress.computeAddress(factory, poolKey));

根据`factory`、`token0`、`token1`和`fee`获取交易对`pool`。

    // compute the liquidity amount
    {
        (uint160 sqrtPriceX96, , , , , , ) = pool.slot0();
        uint160 sqrtRatioAX96 = TickMath.getSqrtRatioAtTick(params.tickLower);
        uint160 sqrtRatioBX96 = TickMath.getSqrtRatioAtTick(params.tickUpper);

        liquidity = LiquidityAmounts.getLiquidityForAmounts(
            sqrtPriceX96,
            sqrtRatioAX96,
            sqrtRatioBX96,
            params.amount0Desired,
            params.amount1Desired
        );
    }

从`slot0`获取当前价格`sqrtPriceX96`，根据`tickLower`和`tickUpper`计算区间的最低价格`sqrtRatioAX96`和最高价格`sqrtRatioBX96`。

根据[getLiquidityForAmounts](#getLiquidityForAmounts)计算能够获得的最大流动性。

    (amount0, amount1) = pool.mint(
        params.recipient,
        params.tickLower,
        params.tickUpper,
        liquidity,
        abi.encode(MintCallbackData({poolKey: poolKey, payer: msg.sender}))
    );

使用[Uniswap-v3-core](https://hackmd.io/TDPPCAIgRRqVDPwsSm6Kfw)的`mint`方法添加流动性，并返回实际消耗的`amount0`和`amount1`。

我们在Uniswap-v3-core的`mint`方法中提到，调用方需实现[uniswapV3MintCallback](#LiquidityManagement.uniswapV3MintCallback)接口。这里传入`MintCallbackData`作为回调参数，在`uniswapV3MintCallback`方法中可以反向解析出来，以便获取交易对和用户信息。

require(amount0 >= params.amount0Min && amount1 >= params.amount1Min, 'Price slippage check');

最后，确认实际消耗的`amount0`和`amount1`满足`amount0Min`和`amount1Min`的最低要求。

### LiquidityAmounts.sol

#### getLiquidityForAmount0

根据`amount0`和价格区间计算流动性。

根据Uniswap-v3-core的`getAmount0Delta`中的公式：

$$
amount0 = x_b - x_a = L \cdot (\frac{1}{\sqrt{P_b}} - \frac{1}{\sqrt{P_a}}) = L \cdot (\frac{\sqrt{P_a} - \sqrt{P_b}}{\sqrt{P_a} \cdot \sqrt{P_b}})
$$

可得：

$$
L = amount0 \cdot (\frac{\sqrt{P_a} \cdot \sqrt{P_b}}{\sqrt{P_a} - \sqrt{P_b}})
$$

/// @notice Computes the amount of liquidity received for a given amount of token0 and price range
/// @dev Calculates amount0 * (sqrt(upper) * sqrt(lower)) / (sqrt(upper) - sqrt(lower))
/// @param sqrtRatioAX96 A sqrt price representing the first tick boundary
/// @param sqrtRatioBX96 A sqrt price representing the second tick boundary
/// @param amount0 The amount0 being sent in
/// @return liquidity The amount of returned liquidity
function getLiquidityForAmount0(
    uint160 sqrtRatioAX96,
    uint160 sqrtRatioBX96,
    uint256 amount0
) internal pure returns (uint128 liquidity) {
    if (sqrtRatioAX96 > sqrtRatioBX96) (sqrtRatioAX96, sqrtRatioBX96) = (sqrtRatioBX96, sqrtRatioAX96);
    uint256 intermediate = FullMath.mulDiv(sqrtRatioAX96, sqrtRatioBX96, FixedPoint96.Q96);
    return toUint128(FullMath.mulDiv(amount0, intermediate, sqrtRatioBX96 - sqrtRatioAX96));
}

#### getLiquidityForAmount1

根据`amount1`和价格区间计算流动性。

根据Uniswap-v3-core的`getAmount1Delta`公式：

$$
amount1 = y_b - y_a = L \cdot \Delta{\sqrt{P}} = L \cdot (\sqrt{P_b} - \sqrt{P_a})
$$

可得：

$$
L = \frac{amount1}{\sqrt{P_b} - \sqrt{P_a}}
$$

/// @notice Computes the amount of liquidity received for a given amount of token1 and price range
/// @dev Calculates amount1 / (sqrt(upper) - sqrt(lower)).
/// @param sqrtRatioAX96 A sqrt price representing the first tick boundary
/// @param sqrtRatioBX96 A sqrt price representing the second tick boundary
/// @param amount1 The amount1 being sent in
/// @return liquidity The amount of returned liquidity
function getLiquidityForAmount1(
    uint160 sqrtRatioAX96,
    uint160 sqrtRatioBX96,
    uint256 amount1
) internal pure returns (uint128 liquidity) {
    if (sqrtRatioAX96 > sqrtRatioBX96) (sqrtRatioAX96, sqrtRatioBX96) = (sqrtRatioBX96, sqrtRatioAX96);
    return toUint128(FullMath.mulDiv(amount1, FixedPoint96.Q96, sqrtRatioBX96 - sqrtRatioAX96));
}

#### getLiquidityForAmounts

根据当前价格，计算能够返回的最大流动性。

* 因为当$\sqrt{P}$增大时，需要消耗$x$，因此如果当前价格低于价格区间低点时，需要完全根据$x$即`amount0`计算流动性
* 反之，如果当前价格高于价格区间高点，需要根据$y$即`amount1`计算流动性

如下图所示：

$$
p,...,\overbrace{p_a,...,p_b}^{amount0}
$$

$$
\overbrace{p_a,...}^{amount1},p,\overbrace{...,p_b}^{amount0}
$$

$$
\overbrace{p_a,...,p_b}^{amount1},...,p
$$

其中，$p$表示当前价格，$p_a$表示区间低点，$p_b$表示区间高点。

/// @notice Computes the maximum amount of liquidity received for a given amount of token0, token1, the current
/// pool prices and the prices at the tick boundaries
/// @param sqrtRatioX96 A sqrt price representing the current pool prices
/// @param sqrtRatioAX96 A sqrt price representing the first tick boundary
/// @param sqrtRatioBX96 A sqrt price representing the second tick boundary
/// @param amount0 The amount of token0 being sent in
/// @param amount1 The amount of token1 being sent in
/// @return liquidity The maximum amount of liquidity received
function getLiquidityForAmounts(
    uint160 sqrtRatioX96,
    uint160 sqrtRatioAX96,
    uint160 sqrtRatioBX96,
    uint256 amount0,
    uint256 amount1
) internal pure returns (uint128 liquidity) {
    if (sqrtRatioAX96 > sqrtRatioBX96) (sqrtRatioAX96, sqrtRatioBX96) = (sqrtRatioBX96, sqrtRatioAX96);

    if (sqrtRatioX96 <= sqrtRatioAX96) {
        liquidity = getLiquidityForAmount0(sqrtRatioAX96, sqrtRatioBX96, amount0);
    } else if (sqrtRatioX96 < sqrtRatioBX96) {
        uint128 liquidity0 = getLiquidityForAmount0(sqrtRatioX96, sqrtRatioBX96, amount0);
        uint128 liquidity1 = getLiquidityForAmount1(sqrtRatioAX96, sqrtRatioX96, amount1);

        liquidity = liquidity0 < liquidity1 ? liquidity0 : liquidity1;
    } else {
        liquidity = getLiquidityForAmount1(sqrtRatioAX96, sqrtRatioBX96, amount1);
    }
}

### Path.sol

在Uniswap v3 [SwapRouter](#SwapRoutersol)中，交易路径被编码为一个`bytes`类型字符串，其格式为：

$$
\overbrace{token_0}^{20}\overbrace{fee_0}^{3}\overbrace{token_1}^{20}\overbrace{fee_1}^{3}\overbrace{token_2}^{20}...
$$

其中，$token_n$的长度为20个字节（bytes），$fee_n$的长度为3个字节，上述路径表示：从`token0`交换到`token1`，使用手续费等级为`fee0`的池子（`token0`、`token1`、`fee0`），继续交换到`token2`，使用手续费等级为`fee1`的池子（`token1`、`token2`、`fee1`）。

交易路径`path`示例如下：

$$
0x\overbrace{ca90cf0734d6ccf5ef52e9ec0a515921a67d6013}^{token0,20bytes}\overbrace{0001f4}^{fee,3bytes}\overbrace{68b3465833fb72a70ecdf485e0e4c7bd8665fc45}^{token1,20bytes}
$$

#### hasMultiplePools

判断交易路径是否经过多个池子（2个及以上）。

/// @notice Returns true iff the path contains two or more pools
/// @param path The encoded swap path
/// @return True if path contains two or more pools, otherwise false
function hasMultiplePools(bytes memory path) internal pure returns (bool) {
    return path.length >= MULTIPLE_POOLS_MIN_LENGTH;
}

我们从上述路径编码可知，如果经过2个池子，至少包含3个代币，则路径长度至少需要$20+3+20+3+20=66$个字节。代码中`MULTIPLE_POOLS_MIN_LENGTH`即等于66。

#### numPools

计算路径中的池子数量。

算法为：

$$
num = \frac{length - 20}{20 + 3}
$$

/// @notice Returns the number of pools in the path
/// @param path The encoded swap path
/// @return The number of pools in the path
function numPools(bytes memory path) internal pure returns (uint256) {
    // Ignore the first token address. From then on every fee and token offset indicates a pool.
    return ((path.length - ADDR_SIZE) / NEXT_OFFSET);
}

#### decodeFirstPool

解析第一个path的信息，包括`token0`，`token1`和`fee`。

分别返回字符串中0-19子串（`token0`，转`address`类型），20-22子串（`fee`，转`uint24`类型），和23-42子串（`token1`，转`address`类型）。请参考`BytesLib.sol`的[toAddress](#toAddress)和[toUint24](#toUint24)方法。

/// @notice Decodes the first pool in path
/// @param path The bytes encoded swap path
/// @return tokenA The first token of the given pool
/// @return tokenB The second token of the given pool
/// @return fee The fee level of the pool
function decodeFirstPool(bytes memory path)
    internal
    pure
    returns (
        address tokenA,
        address tokenB,
        uint24 fee
    )
{
    tokenA = path.toAddress(0);
    fee = path.toUint24(ADDR_SIZE);
    tokenB = path.toAddress(NEXT_OFFSET);
}

#### getFirstPool

返回第一个池子的路径，即返回前43（即20+3+20）个字符组成的子字符串。

/// @notice Gets the segment corresponding to the first pool in the path
/// @param path The bytes encoded swap path
/// @return The segment containing all data necessary to target the first pool in the path
function getFirstPool(bytes memory path) internal pure returns (bytes memory) {
    return path.slice(0, POP_OFFSET);
}

#### skipToken

跳过当前路径上的第一个`token+fee`，即跳过前20+3个字符。

/// @notice Skips a token + fee element from the buffer and returns the remainder
/// @param path The swap path
/// @return The remaining token + fee elements in the path
function skipToken(bytes memory path) internal pure returns (bytes memory) {
    return path.slice(NEXT_OFFSET, path.length - NEXT_OFFSET);
}

### BytesLib.sol

#### toAddress

从字符串的指定序号起，读取一个地址（20个字符）：

function toAddress(bytes memory _bytes, uint256 _start) internal pure returns (address) {
    require(_start + 20 >= _start, 'toAddress_overflow');
    require(_bytes.length >= _start + 20, 'toAddress_outOfBounds');
    address tempAddress;

    assembly {
        tempAddress := div(mload(add(add(_bytes, 0x20), _start)), 0x1000000000000000000000000)
    }

    return tempAddress;
}

因为变量`_bytes`类型为`bytes`，根据[ABI定义](https://docs.soliditylang.org/en/develop/abi-spec.html)，`bytes`的第一个32字节存储字符串的长度（length），因此需要先跳过前面32字节，即`add(_bytes, 0x20)`；`add(add(_bytes, 0x20), _start)`表示定位到字符串指定序号`_start`；`mload`读取从该序号起的32个字节，因为`address`类型只有20字节，因此需要`div 0x1000000000000000000000000`，即右移12字节。

假设`_strat = 0`，`_bytes`的分布如下图所示：

$$
0x\overbrace{0000000...2b}^{length,32bytes}\underbrace{\overbrace{ca90cf0734d6ccf5ef52e9ec0a515921a67d6013}^{address, 20 bytes}\overbrace{0001f468b3465833fb72a70e}^{div,12 bytes}}_{mload, 32bytes}cdf485e0e4c7bd8665fc45
$$

#### toUint24

从字符串的指定序号起，读取一个`uint24`（24位，即3个字符）：

function toUint24(bytes memory _bytes, uint256 _start) internal pure returns (uint24) {
    require(_start + 3 >= _start, 'toUint24_overflow');
    require(_bytes.length >= _start + 3, 'toUint24_outOfBounds');
    uint24 tempUint;

    assembly {
        tempUint := mload(add(add(_bytes, 0x3), _start))
    }

    return tempUint;
}

因为`_bytes`前32个字符表示字符串长度；`mload`读取32字节，可以确保从`_start`开始的3个字节在读取出来的32字节的最低位，赋值给类型为`uint24`的变量将只保留最低位的3个字节。

假设`_strat = 0`，`_bytes`的分布如下图所示：

$$
0x\overbrace{000000}^{0x3+\_start}\underbrace{0...2b\overbrace{ca90cf0734d6ccf5ef52e9ec0a515921a67d6013}^{address1,20bytes}\overbrace{0001f4}^{fee,3bytes}}_{mload,32bytes}\overbrace{68b3465833fb72a70ecdf485e0e4c7bd8665fc45}^{address2,20bytes}
$$

### OracleLibrary.sol

根据白皮书公式5.3-5.5，计算$t_1$至$t_2$时间内的几何平均价格如下：

$$
\log_{1.0001}(P_{t_1,t_2}) = \frac{\sum^{t_2}_{i=t_1} \log_{1.0001}(P_i)}{t_2 - t_1} \tag{5.3}
$$

$$
\log_{1.0001}(P_{t_1,t_2}) = \frac{a_{t_2} - a_{t_1}}{t_2 - t_1} \tag{5.4}
$$

$$
P_{t_1,t_2} = 1.0001^{\frac{a_{t_2} - a_{t_1}}{t_2 - t_1}} \tag{5.5}
$$

本合约提供价格预言机相关方法，包括如下方法：

* [consult](#consult)：查询从一段时间前到现在的几何平均价格（以`tick`形式）
* [getQuoteAtTick](#getQuoteAtTick)：根据`tick`计算代币价格

#### consult

查询从一段时间前到现在的几何平均价格（以`tick`形式）。

参数如下：

* `pool`: 交易对池子地址
* `period`：以秒计数的区间

返回：

* `timeWeightedAverageTick`：时间加权平均价格

/// @notice Fetches time-weighted average tick using Uniswap V3 oracle
/// @param pool Address of Uniswap V3 pool that we want to observe
/// @param period Number of seconds in the past to start calculating time-weighted average
/// @return timeWeightedAverageTick The time-weighted average tick from (block.timestamp - period) to block.timestamp
function consult(address pool, uint32 period) internal view returns (int24 timeWeightedAverageTick) {
    require(period != 0, 'BP');

    uint32[] memory secondAgos = new uint32[](2);
    secondAgos[0] = period;
    secondAgos[1] = 0;

构造两个监测点，第一个为`period`时间之前，第二个为现在。

    (int56[] memory tickCumulatives, ) = IUniswapV3Pool(pool).observe(secondAgos);
    int56 tickCumulativesDelta = tickCumulatives[1] - tickCumulatives[0];

根据`IUniswapV3Pool.observe`方法获取累积`tick`，即公式5.4中的$a_{t_2}$和$a_{t_1}$。

$$
tickCumulativesDelta = a_{t_2} - a_{t_1}
$$

    timeWeightedAverageTick = int24(tickCumulativesDelta / period);

$$
timeWeightedAverageTick = \frac{tickCumulativesDelta}{t_2 - t_1}
$$

    // Always round to negative infinity
    if (tickCumulativesDelta < 0 && (tickCumulativesDelta % period != 0)) timeWeightedAverageTick--;

如果`tickCumulativesDelta`为负数，并且无法被`period`整除，则将平均价格-1。

#### getQuoteAtTick

/// @notice Given a tick and a token amount, calculates the amount of token received in exchange
/// @param tick Tick value used to calculate the quote
/// @param baseAmount Amount of token to be converted
/// @param baseToken Address of an ERC20 token contract used as the baseAmount denomination
/// @param quoteToken Address of an ERC20 token contract used as the quoteAmount denomination
/// @return quoteAmount Amount of quoteToken received for baseAmount of baseToken
function getQuoteAtTick(
    int24 tick,
    uint128 baseAmount,
    address baseToken,
    address quoteToken
) internal pure returns (uint256 quoteAmount) {
    uint160 sqrtRatioX96 = TickMath.getSqrtRatioAtTick(tick);

    // Calculate quoteAmount with better precision if it doesn't overflow when multiplied by itself
    if (sqrtRatioX96 <= type(uint128).max) {
        uint256 ratioX192 = uint256(sqrtRatioX96) * sqrtRatioX96;
        quoteAmount = baseToken < quoteToken
            ? FullMath.mulDiv(ratioX192, baseAmount, 1 << 192)
            : FullMath.mulDiv(1 << 192, baseAmount, ratioX192);
    } else {
        uint256 ratioX128 = FullMath.mulDiv(sqrtRatioX96, sqrtRatioX96, 1 << 64);
        quoteAmount = baseToken < quoteToken
            ? FullMath.mulDiv(ratioX128, baseAmount, 1 << 128)
            : FullMath.mulDiv(1 << 128, baseAmount, ratioX128);
    }
}

根据Uniswap-v3-core的`getSqrtRatioAtTick`方法计算`tick`对应的$\sqrt{P}$，即$\sqrt{\frac{token1}{token0}}$。

如果`baseToken < quoteToken`，则`baseToken`为`token0`，`quoteToken`为`token1`：

$$
quoteAmount = baseAmount \cdot (\sqrt{P})^2
$$

反之，`baseToken`为`token1`，`quoteToken`为`token0`：

$$
quoteAmount = \frac{baseAmount}{(\sqrt{P})^2}
$$