UniSwap V3协议浅析(上)

    // info stored for each initialized individual tick    struct Info {        // the total position liquidity that references this tick        uint128 liquidityGross;        // amount of net liquidity added (subtracted) when tick is crossed from left to right (right to left),        int128 liquidityNet;        // fee growth per unit of liquidity on the _other_ side of this tick (relative to the current tick)        // only has relative meaning, not absolute — the value depends on when the tick is initialized        uint256 feeGrowthOutside0X128;        uint256 feeGrowthOutside1X128;        // the cumulative tick value on the other side of the tick        int56 tickCumulativeOutside;        // the seconds per unit of liquidity on the _other_ side of this tick (relative to the current tick)        // only has relative meaning, not absolute — the value depends on when the tick is initialized        uint160 secondsPerLiquidityOutsideX128;        // the seconds spent on the other side of the tick (relative to the current tick)        // only has relative meaning, not absolute — the value depends on when the tick is initialized        uint32 secondsOutside;        // true iff the tick is initialized, i.e. the value is exactly equivalent to the expression liquidityGross != 0        // these 8 bits are set to prevent fresh sstores when crossing newly initialized ticks        bool initialized;    }

    /// @notice Derives max liquidity per tick from given tick spacing    /// @dev Executed within the pool constructor    /// @param tickSpacing The amount of required tick separation, realized in multiples of `tickSpacing`    ///     e.g., a tickSpacing of 3 requires ticks to be initialized every 3rd tick i.e., ..., -6, -3, 0, 3, 6, ...    /// @return The max liquidity per tick    function tickSpacingToMaxLiquidityPerTick(int24 tickSpacing) internal pure returns (uint128) {        int24 minTick = (TickMath.MIN_TICK / tickSpacing) * tickSpacing;        int24 maxTick = (TickMath.MAX_TICK / tickSpacing) * tickSpacing;        uint24 numTicks = uint24((maxTick - minTick) / tickSpacing) + 1;        return type(uint128).max / numTicks;    }

    /// @notice Retrieves fee growth data    /// @param self The mapping containing all tick information for initialized ticks    /// @param tickLower The lower tick boundary of the position    /// @param tickUpper The upper tick boundary of the position    /// @param tickCurrent The current tick    /// @param feeGrowthGlobal0X128 The all-time global fee growth, per unit of liquidity, in token0    /// @param feeGrowthGlobal1X128 The all-time global fee growth, per unit of liquidity, in token1    /// @return feeGrowthInside0X128 The all-time fee growth in token0, per unit of liquidity, inside the position's tick boundaries    /// @return feeGrowthInside1X128 The all-time fee growth in token1, per unit of liquidity, inside the position's tick boundaries    function getFeeGrowthInside(        mapping(int24 => Tick.Info) storage self,        int24 tickLower,        int24 tickUpper,        int24 tickCurrent,        uint256 feeGrowthGlobal0X128,        uint256 feeGrowthGlobal1X128    ) internal view returns (uint256 feeGrowthInside0X128, uint256 feeGrowthInside1X128) {        Info storage lower = self[tickLower];        Info storage upper = self[tickUpper];
        // calculate fee growth below        uint256 feeGrowthBelow0X128;        uint256 feeGrowthBelow1X128;        if (tickCurrent >= tickLower) {            feeGrowthBelow0X128 = lower.feeGrowthOutside0X128;            feeGrowthBelow1X128 = lower.feeGrowthOutside1X128;        } else {            feeGrowthBelow0X128 = feeGrowthGlobal0X128 - lower.feeGrowthOutside0X128;            feeGrowthBelow1X128 = feeGrowthGlobal1X128 - lower.feeGrowthOutside1X128;        }
        // calculate fee growth above        uint256 feeGrowthAbove0X128;        uint256 feeGrowthAbove1X128;        if (tickCurrent < tickUpper) {            feeGrowthAbove0X128 = upper.feeGrowthOutside0X128;            feeGrowthAbove1X128 = upper.feeGrowthOutside1X128;        } else {            feeGrowthAbove0X128 = feeGrowthGlobal0X128 - upper.feeGrowthOutside0X128;            feeGrowthAbove1X128 = feeGrowthGlobal1X128 - upper.feeGrowthOutside1X128;        }
        feeGrowthInside0X128 = feeGrowthGlobal0X128 - feeGrowthBelow0X128 - feeGrowthAbove0X128;        feeGrowthInside1X128 = feeGrowthGlobal1X128 - feeGrowthBelow1X128 - feeGrowthAbove1X128;    }

    /// @notice Updates a tick and returns true if the tick was flipped from initialized to uninitialized, or vice versa    /// @param self The mapping containing all tick information for initialized ticks    /// @param tick The tick that will be updated    /// @param tickCurrent The current tick    /// @param liquidityDelta A new amount of liquidity to be added (subtracted) when tick is crossed from left to right (right to left)    /// @param feeGrowthGlobal0X128 The all-time global fee growth, per unit of liquidity, in token0    /// @param feeGrowthGlobal1X128 The all-time global fee growth, per unit of liquidity, in token1    /// @param secondsPerLiquidityCumulativeX128 The all-time seconds per max(1, liquidity) of the pool    /// @param time The current block timestamp cast to a uint32    /// @param upper true for updating a position's upper tick, or false for updating a position's lower tick    /// @param maxLiquidity The maximum liquidity allocation for a single tick    /// @return flipped Whether the tick was flipped from initialized to uninitialized, or vice versa    function update(        mapping(int24 => Tick.Info) storage self,        int24 tick,        int24 tickCurrent,        int128 liquidityDelta,        uint256 feeGrowthGlobal0X128,        uint256 feeGrowthGlobal1X128,        uint160 secondsPerLiquidityCumulativeX128,        int56 tickCumulative,        uint32 time,        bool upper,        uint128 maxLiquidity    ) internal returns (bool flipped) {        Tick.Info storage info = self[tick];
        uint128 liquidityGrossBefore = info.liquidityGross;        uint128 liquidityGrossAfter = LiquidityMath.addDelta(liquidityGrossBefore, liquidityDelta);
        require(liquidityGrossAfter <= maxLiquidity, 'LO');
        flipped = (liquidityGrossAfter == 0) != (liquidityGrossBefore == 0);
        if (liquidityGrossBefore == 0) {            // by convention, we assume that all growth before a tick was initialized happened _below_ the tick            if (tick <= tickCurrent) {                info.feeGrowthOutside0X128 = feeGrowthGlobal0X128;                info.feeGrowthOutside1X128 = feeGrowthGlobal1X128;                info.secondsPerLiquidityOutsideX128 = secondsPerLiquidityCumulativeX128;                info.tickCumulativeOutside = tickCumulative;                info.secondsOutside = time;            }            info.initialized = true;        }
        info.liquidityGross = liquidityGrossAfter;
        // when the lower (upper) tick is crossed left to right (right to left), liquidity must be added (removed)        info.liquidityNet = upper            ? int256(info.liquidityNet).sub(liquidityDelta).toInt128()            : int256(info.liquidityNet).add(liquidityDelta).toInt128();    }

    /// @notice Clears tick data    /// @param self The mapping containing all initialized tick information for initialized ticks    /// @param tick The tick that will be cleared    function clear(mapping(int24 => Tick.Info) storage self, int24 tick) internal {        delete self[tick];    }

    /// @notice Transitions to next tick as needed by price movement    /// @param self The mapping containing all tick information for initialized ticks    /// @param tick The destination tick of the transition    /// @param feeGrowthGlobal0X128 The all-time global fee growth, per unit of liquidity, in token0    /// @param feeGrowthGlobal1X128 The all-time global fee growth, per unit of liquidity, in token1    /// @param secondsPerLiquidityCumulativeX128 The current seconds per liquidity    /// @param time The current block.timestamp    /// @return liquidityNet The amount of liquidity added (subtracted) when tick is crossed from left to right (right to left)    function cross(        mapping(int24 => Tick.Info) storage self,        int24 tick,        uint256 feeGrowthGlobal0X128,        uint256 feeGrowthGlobal1X128,        uint160 secondsPerLiquidityCumulativeX128,        int56 tickCumulative,        uint32 time    ) internal returns (int128 liquidityNet) {        Tick.Info storage info = self[tick];        info.feeGrowthOutside0X128 = feeGrowthGlobal0X128 - info.feeGrowthOutside0X128;        info.feeGrowthOutside1X128 = feeGrowthGlobal1X128 - info.feeGrowthOutside1X128;        info.secondsPerLiquidityOutsideX128 = secondsPerLiquidityCumulativeX128 - info.secondsPerLiquidityOutsideX128;        info.tickCumulativeOutside = tickCumulative - info.tickCumulativeOutside;        info.secondsOutside = time - info.secondsOutside;        liquidityNet = info.liquidityNet;    }

    struct Observation {        // the block timestamp of the observation        uint32 blockTimestamp;        // the tick accumulator, i.e. tick * time elapsed since the pool was first initialized        int56 tickCumulative; // tick index的时间加权累积值        // the seconds per liquidity, i.e. seconds elapsed / max(1, liquidity) since the pool was first initialized        uint160 secondsPerLiquidityCumulativeX128; //每个流动性的秒数，即自第一次初始化池以来经过的秒数/max(1,流动性)        // whether or not the observation is initialized        bool initialized; //是否初始化    }

    /// @notice Initialize the oracle array by writing the first slot. Called once for the lifecycle of the observations array    /// @param self The stored oracle array    /// @param time The time of the oracle initialization, via block.timestamp truncated to uint32    /// @return cardinality The number of populated elements in the oracle array    /// @return cardinalityNext The new length of the oracle array, independent of population    function initialize(Observation[65535] storage self, uint32 time)        internal        returns (uint16 cardinality, uint16 cardinalityNext){        self[0] = Observation({            blockTimestamp: time,            tickCumulative: 0,            secondsPerLiquidityCumulativeX128: 0,            initialized: true        });        return (1, 1);    }

    /// @notice Writes an oracle observation to the array    /// @dev Writable at most once per block. Index represents the most recently written element. cardinality and index must be tracked externally.    /// If the index is at the end of the allowable array length (according to cardinality), and the next cardinality    /// is greater than the current one, cardinality may be increased. This restriction is created to preserve ordering.    /// @param self The stored oracle array    /// @param index The index of the observation that was most recently written to the observations array    /// @param blockTimestamp The timestamp of the new observation    /// @param tick The active tick at the time of the new observation    /// @param liquidity The total in-range liquidity at the time of the new observation    /// @param cardinality The number of populated elements in the oracle array    /// @param cardinalityNext The new length of the oracle array, independent of population    /// @return indexUpdated The new index of the most recently written element in the oracle array    /// @return cardinalityUpdated The new cardinality of the oracle array    function write(        Observation[65535] storage self,        uint16 index,        uint32 blockTimestamp,        int24 tick,        uint128 liquidity,        uint16 cardinality,        uint16 cardinalityNext    ) internal returns (uint16 indexUpdated, uint16 cardinalityUpdated) {        Observation memory last = self[index];
        // early return if we've already written an observation this block        if (last.blockTimestamp == blockTimestamp) return (index, cardinality);
        // if the conditions are right, we can bump the cardinality        if (cardinalityNext > cardinality && index == (cardinality - 1)) {            cardinalityUpdated = cardinalityNext;        } else {            cardinalityUpdated = cardinality;        }
        indexUpdated = (index + 1) % cardinalityUpdated;        self[indexUpdated] = transform(last, blockTimestamp, tick, liquidity);    }

    /// @notice Prepares the oracle array to store up to `next` observations    /// @param self The stored oracle array    /// @param current The current next cardinality of the oracle array    /// @param next The proposed next cardinality which will be populated in the oracle array    /// @return next The next cardinality which will be populated in the oracle array    function grow(        Observation[65535] storage self,        uint16 current,        uint16 next    ) internal returns (uint16) {        require(current > 0, 'I');        // no-op if the passed next value isn't greater than the current next value        if (next <= current) return current;        // store in each slot to prevent fresh SSTOREs in swaps        // this data will not be used because the initialized boolean is still false        for (uint16 i = current; i < next; i++) self[i].blockTimestamp = 1;        return next;    }

    /// @notice comparator for 32-bit timestamps    /// @dev safe for 0 or 1 overflows, a and b _must_ be chronologically before or equal to time    /// @param time A timestamp truncated to 32 bits    /// @param a A comparison timestamp from which to determine the relative position of `time`    /// @param b From which to determine the relative position of `time`    /// @return bool Whether `a` is chronologically <= `b`    function lte(        uint32 time,        uint32 a,        uint32 b    ) private pure returns (bool) {        // if there hasn't been overflow, no need to adjust        if (a <= time && b <= time) return a <= b;
        uint256 aAdjusted = a > time ? a : a + 2**32;        uint256 bAdjusted = b > time ? b : b + 2**32;
        return aAdjusted <= bAdjusted;    }

    /// @notice Fetches the observations beforeOrAt and atOrAfter a target, i.e. where [beforeOrAt, atOrAfter] is satisfied.    /// The result may be the same observation, or adjacent observations.    /// @dev The answer must be contained in the array, used when the target is located within the stored observation    /// boundaries: older than the most recent observation and younger, or the same age as, the oldest observation    /// @param self The stored oracle array    /// @param time The current block.timestamp    /// @param target The timestamp at which the reserved observation should be for    /// @param index The index of the observation that was most recently written to the observations array    /// @param cardinality The number of populated elements in the oracle array    /// @return beforeOrAt The observation recorded before, or at, the target    /// @return atOrAfter The observation recorded at, or after, the target    function binarySearch(        Observation[65535] storage self,        uint32 time,        uint32 target,        uint16 index,        uint16 cardinality    ) private view returns (Observation memory beforeOrAt, Observation memory atOrAfter) {        uint256 l = (index + 1) % cardinality; // oldest observation        uint256 r = l + cardinality - 1; // newest observation        uint256 i;        while (true) {            i = (l + r) / 2;
            beforeOrAt = self[i % cardinality];
            // we've landed on an uninitialized tick, keep searching higher (more recently)            if (!beforeOrAt.initialized) {                l = i + 1;                continue;            }
            atOrAfter = self[(i + 1) % cardinality];
            bool targetAtOrAfter = lte(time, beforeOrAt.blockTimestamp, target);
            // check if we've found the answer!            if (targetAtOrAfter && lte(time, target, atOrAfter.blockTimestamp)) break;
            if (!targetAtOrAfter) r = i - 1;            else l = i + 1;        }    }

    /// @notice Fetches the observations beforeOrAt and atOrAfter a given target, i.e. where [beforeOrAt, atOrAfter] is satisfied    /// @dev Assumes there is at least 1 initialized observation.    /// Used by observeSingle() to compute the counterfactual accumulator values as of a given block timestamp.    /// @param self The stored oracle array    /// @param time The current block.timestamp    /// @param target The timestamp at which the reserved observation should be for    /// @param tick The active tick at the time of the returned or simulated observation    /// @param index The index of the observation that was most recently written to the observations array    /// @param liquidity The total pool liquidity at the time of the call    /// @param cardinality The number of populated elements in the oracle array    /// @return beforeOrAt The observation which occurred at, or before, the given timestamp    /// @return atOrAfter The observation which occurred at, or after, the given timestamp    function getSurroundingObservations(        Observation[65535] storage self,        uint32 time,        uint32 target,        int24 tick,        uint16 index,        uint128 liquidity,        uint16 cardinality    ) private view returns (Observation memory beforeOrAt, Observation memory atOrAfter) {        // optimistically set before to the newest observation        beforeOrAt = self[index];
        // if the target is chronologically at or after the newest observation, we can early return        if (lte(time, beforeOrAt.blockTimestamp, target)) {            if (beforeOrAt.blockTimestamp == target) {                // if newest observation equals target, we're in the same block, so we can ignore atOrAfter                return (beforeOrAt, atOrAfter);            } else {                // otherwise, we need to transform                return (beforeOrAt, transform(beforeOrAt, target, tick, liquidity));            }        }
        // now, set before to the oldest observation        beforeOrAt = self[(index + 1) % cardinality];        if (!beforeOrAt.initialized) beforeOrAt = self[0];
        // ensure that the target is chronologically at or after the oldest observation        require(lte(time, beforeOrAt.blockTimestamp, target), 'OLD');
        // if we've reached this point, we have to binary search        return binarySearch(self, time, target, index, cardinality);    }

    /// @dev Reverts if an observation at or before the desired observation timestamp does not exist.    /// 0 may be passed as `secondsAgo' to return the current cumulative values.    /// If called with a timestamp falling between two observations, returns the counterfactual accumulator values    /// at exactly the timestamp between the two observations.    /// @param self The stored oracle array    /// @param time The current block timestamp    /// @param secondsAgo The amount of time to look back, in seconds, at which point to return an observation    /// @param tick The current tick    /// @param index The index of the observation that was most recently written to the observations array    /// @param liquidity The current in-range pool liquidity    /// @param cardinality The number of populated elements in the oracle array    /// @return tickCumulative The tick * time elapsed since the pool was first initialized, as of `secondsAgo`    /// @return secondsPerLiquidityCumulativeX128 The time elapsed / max(1, liquidity) since the pool was first initialized, as of `secondsAgo`    function observeSingle(        Observation[65535] storage self,        uint32 time,        uint32 secondsAgo,        int24 tick,        uint16 index,        uint128 liquidity,        uint16 cardinality    ) internal view returns (int56 tickCumulative, uint160 secondsPerLiquidityCumulativeX128) {        if (secondsAgo == 0) {            Observation memory last = self[index];            if (last.blockTimestamp != time) last = transform(last, time, tick, liquidity);            return (last.tickCumulative, last.secondsPerLiquidityCumulativeX128);        }
        uint32 target = time - secondsAgo;
        (Observation memory beforeOrAt, Observation memory atOrAfter) =            getSurroundingObservations(self, time, target, tick, index, liquidity, cardinality);
        if (target == beforeOrAt.blockTimestamp) {            // we're at the left boundary            return (beforeOrAt.tickCumulative, beforeOrAt.secondsPerLiquidityCumulativeX128);        } else if (target == atOrAfter.blockTimestamp) {            // we're at the right boundary            return (atOrAfter.tickCumulative, atOrAfter.secondsPerLiquidityCumulativeX128);        } else {            // we're in the middle            uint32 observationTimeDelta = atOrAfter.blockTimestamp - beforeOrAt.blockTimestamp;            uint32 targetDelta = target - beforeOrAt.blockTimestamp;            return (                beforeOrAt.tickCumulative +                    ((atOrAfter.tickCumulative - beforeOrAt.tickCumulative) / observationTimeDelta) *                    targetDelta,                beforeOrAt.secondsPerLiquidityCumulativeX128 +                    uint160(                        (uint256(                            atOrAfter.secondsPerLiquidityCumulativeX128 - beforeOrAt.secondsPerLiquidityCumulativeX128                        ) * targetDelta) / observationTimeDelta                    )            );        }    }

    /// @notice Returns the accumulator values as of each time seconds ago from the given time in the array of `secondsAgos`    /// @dev Reverts if `secondsAgos` > oldest observation    /// @param self The stored oracle array    /// @param time The current block.timestamp    /// @param secondsAgos Each amount of time to look back, in seconds, at which point to return an observation    /// @param tick The current tick    /// @param index The index of the observation that was most recently written to the observations array    /// @param liquidity The current in-range pool liquidity    /// @param cardinality The number of populated elements in the oracle array    /// @return tickCumulatives The tick * time elapsed since the pool was first initialized, as of each `secondsAgo`    /// @return secondsPerLiquidityCumulativeX128s The cumulative seconds / max(1, liquidity) since the pool was first initialized, as of each `secondsAgo`    function observe(        Observation[65535] storage self,        uint32 time,        uint32[] memory secondsAgos,        int24 tick,        uint16 index,        uint128 liquidity,        uint16 cardinality    ) internal view returns (int56[] memory tickCumulatives, uint160[] memory secondsPerLiquidityCumulativeX128s) {        require(cardinality > 0, 'I');
        tickCumulatives = new int56[](secondsAgos.length);        secondsPerLiquidityCumulativeX128s = new uint160[](secondsAgos.length);        for (uint256 i = 0; i < secondsAgos.length; i++) {            (tickCumulatives[i], secondsPerLiquidityCumulativeX128s[i]) = observeSingle(                self,                time,                secondsAgos[i],                tick,                index,                liquidity,                cardinality            );        }    }