wp-evm-amm-math 0.1.3

//! Fee-growth math: fee growth inside a tick range and tokens owed.
//!
//! All subtraction uses `wrapping_sub` to match the EVM's
//! modular-2^256 arithmetic for fee growth accumulators.

use alloy_primitives::U256;

/// Q128 constant (2^128).
const Q128: U256 = U256::from_limbs([0, 0, 1, 0]);

/// Calculate the fee growth inside a position's tick range.
///
/// Mirrors Uniswap V3's [`Tick.getFeeGrowthInside`] — same 3-branch
/// structure (below-range / above-range / inside-range) with all
/// subtractions in `wrapping_sub` to match Solidity unchecked
/// modular-2^256 arithmetic. Fee-growth accumulators are
/// monotonically increasing mod 2^256, so wrapping is the correct
/// semantics for accumulator deltas.
///
/// Unlike the Solidity version (which reads `Tick.Info.feeGrowthOutsideXX128`
/// from a storage mapping), this is a pure function — callers must
/// pass the per-tick `feeGrowthOutside` values explicitly.
///
/// [`Tick.getFeeGrowthInside`]: https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/Tick.sol
///
/// # Arguments
/// * `tick_lower` — lower tick of the position
/// * `tick_upper` — upper tick of the position
/// * `tick_current` — current tick of the pool
/// * `fee_growth_global_0x128` — pool's `feeGrowthGlobal0X128`
/// * `fee_growth_global_1x128` — pool's `feeGrowthGlobal1X128`
/// * `fee_growth_outside_0x128_lower` — `Tick.Info(tick_lower).feeGrowthOutside0X128`
/// * `fee_growth_outside_1x128_lower` — `Tick.Info(tick_lower).feeGrowthOutside1X128`
/// * `fee_growth_outside_0x128_upper` — `Tick.Info(tick_upper).feeGrowthOutside0X128`
/// * `fee_growth_outside_1x128_upper` — `Tick.Info(tick_upper).feeGrowthOutside1X128`
///
/// # Returns
///
/// `(fee_growth_inside_0x128, fee_growth_inside_1x128)` — the per-token
/// fee growth accumulator restricted to the position's range.
#[allow(clippy::too_many_arguments)]
pub fn get_fee_growth_inside(
    tick_lower: i32,
    tick_upper: i32,
    tick_current: i32,
    fee_growth_global_0x128: U256,
    fee_growth_global_1x128: U256,
    fee_growth_outside_0x128_lower: U256,
    fee_growth_outside_1x128_lower: U256,
    fee_growth_outside_0x128_upper: U256,
    fee_growth_outside_1x128_upper: U256,
) -> (U256, U256) {
    if tick_current < tick_lower {
        // Below range.
        (
            fee_growth_outside_0x128_lower.wrapping_sub(fee_growth_outside_0x128_upper),
            fee_growth_outside_1x128_lower.wrapping_sub(fee_growth_outside_1x128_upper),
        )
    } else if tick_current >= tick_upper {
        // Above range.
        (
            fee_growth_outside_0x128_upper.wrapping_sub(fee_growth_outside_0x128_lower),
            fee_growth_outside_1x128_upper.wrapping_sub(fee_growth_outside_1x128_lower),
        )
    } else {
        // Inside range.
        (
            fee_growth_global_0x128
                .wrapping_sub(fee_growth_outside_0x128_lower)
                .wrapping_sub(fee_growth_outside_0x128_upper),
            fee_growth_global_1x128
                .wrapping_sub(fee_growth_outside_1x128_lower)
                .wrapping_sub(fee_growth_outside_1x128_upper),
        )
    }
}

/// Compute uncollected token amounts from fee-growth deltas.
///
/// **Synthetic helper** — Uniswap V3 inlines this math in
/// [`Position.update`] without exposing a named getter. Extracted here
/// so the R9 batch reader can compute current fees off-chain without
/// duplicating the formula at the consumer site.
///
/// Formula:
/// ```text
/// tokens_owed = liquidity * (fee_growth_inside_now - fee_growth_inside_last) / Q128
/// ```
///
/// Subtraction is wrapping (matches Solidity unchecked); the
/// `mul_div` step prefers full-precision and falls back to
/// `wrapping_mul >> 128` only when the U256 quotient would
/// overflow — that fallback matches EVM `unchecked` semantics
/// for the extreme upper edge.
///
/// [`Position.update`]: https://github.com/Uniswap/v3-core/blob/main/contracts/libraries/Position.sol
pub fn get_tokens_owed(
    fee_growth_inside_0_last_x128: U256,
    fee_growth_inside_1_last_x128: U256,
    liquidity: u128,
    fee_growth_inside_0x128: U256,
    fee_growth_inside_1x128: U256,
) -> (U256, U256) {
    let liq = U256::from(liquidity);

    let delta_0 = fee_growth_inside_0x128.wrapping_sub(fee_growth_inside_0_last_x128);
    let delta_1 = fee_growth_inside_1x128.wrapping_sub(fee_growth_inside_1_last_x128);

    // Wrapping mul then divide by Q128.  Since delta < 2^256 and
    // liquidity < 2^128, the product fits in 384 bits which is
    // less than 512.  But we only need the lower 256 bits of
    // (delta * liq) / 2^128.  Using wrapping_mul and >> 128
    // matches the EVM behaviour.
    //
    // However for accuracy we use full_math::mul_div when possible.
    // If that fails (overflow), fall back to wrapping.
    let tokens_owed_0 = mul_div_or_wrapping(delta_0, liq, Q128);
    let tokens_owed_1 = mul_div_or_wrapping(delta_1, liq, Q128);

    (tokens_owed_0, tokens_owed_1)
}

/// Try mul_div; fall back to wrapping shift for extreme values.
fn mul_div_or_wrapping(a: U256, b: U256, d: U256) -> U256 {
    crate::full_math::mul_div(a, b, d).unwrap_or_else(|_| {
        // Fallback: wrapping_mul >> 128
        a.wrapping_mul(b) >> 128
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_fee_growth_inside_in_range() {
        let (fg0, fg1) = get_fee_growth_inside(
            -100, // tick_lower
            100,  // tick_upper
            0,    // tick_current
            U256::from(1000u64),
            U256::from(2000u64),
            U256::from(100u64),
            U256::from(200u64),
            U256::from(200u64),
            U256::from(300u64),
        );
        // 1000 - 100 - 200 = 700
        assert_eq!(fg0, U256::from(700u64));
        // 2000 - 200 - 300 = 1500
        assert_eq!(fg1, U256::from(1500u64));
    }

    #[test]
    fn test_fee_growth_wrapping_below() {
        // tick < lower, lower_outside=10, upper_outside=20
        // result = 10 - 20 = wraps
        let (fg0, _) = get_fee_growth_inside(
            -100,
            100,
            -200,
            U256::from(1000u64),
            U256::from(1000u64),
            U256::from(10u64),
            U256::from(10u64),
            U256::from(20u64),
            U256::from(20u64),
        );
        let expected = U256::from(10u64).wrapping_sub(U256::from(20u64));
        assert_eq!(fg0, expected);
    }

    #[test]
    fn test_fee_growth_wrapping_above() {
        let (fg0, _) = get_fee_growth_inside(
            -100,
            100,
            200,
            U256::from(1000u64),
            U256::from(1000u64),
            U256::from(30u64),
            U256::from(30u64),
            U256::from(5u64),
            U256::from(5u64),
        );
        let expected = U256::from(5u64).wrapping_sub(U256::from(30u64));
        assert_eq!(fg0, expected);
    }

    #[test]
    fn test_tokens_owed_zero_liquidity() {
        let (t0, t1) =
            get_tokens_owed(U256::ZERO, U256::ZERO, 0, U256::from(1000u64), U256::from(2000u64));
        assert_eq!(t0, U256::ZERO);
        assert_eq!(t1, U256::ZERO);
    }

    #[test]
    fn test_tokens_owed_basic() {
        // delta = Q128, liquidity = 1 -> owed = 1
        let (t0, _) = get_tokens_owed(U256::ZERO, U256::ZERO, 1, Q128, U256::ZERO);
        assert_eq!(t0, U256::from(1u64));
    }

    #[test]
    fn test_tokens_owed_wrapping_sub() {
        // fee_growth_inside_last > fee_growth_inside (wraps)
        // This should not panic.
        let (t0, _) =
            get_tokens_owed(U256::from(100u64), U256::ZERO, 0, U256::from(50u64), U256::ZERO);
        // With zero liquidity, result is zero regardless.
        assert_eq!(t0, U256::ZERO);
    }

    #[test]
    fn test_fee_growth_wraps_lower_gt_upper() {
        // Current tick is inside range.
        // fee_growth_outside_lower (500) > fee_growth_outside_upper (100).
        // fee_growth_inside = global - lower_outside - upper_outside
        //                   = 1000 - 500 - 100 = 400
        let (fg0, _) = get_fee_growth_inside(
            -100,                // tick_lower
            100,                 // tick_upper
            0,                   // tick_current (inside range)
            U256::from(1000u64), // global_0
            U256::from(0u64),    // global_1
            U256::from(500u64),  // outside_0_lower
            U256::from(0u64),    // outside_1_lower
            U256::from(100u64),  // outside_0_upper
            U256::from(0u64),    // outside_1_upper
        );
        assert_eq!(fg0, U256::from(400u64));

        // Now test the wrapping case: when global < sum of outsides
        // global=50, lower_outside=30, upper_outside=40
        // 50 - 30 - 40 = -20, which wraps to U256::MAX - 19
        let (fg0_wrap, _) = get_fee_growth_inside(
            -100,
            100,
            0,
            U256::from(50u64),
            U256::from(0u64),
            U256::from(30u64),
            U256::from(0u64),
            U256::from(40u64),
            U256::from(0u64),
        );
        let expected =
            U256::from(50u64).wrapping_sub(U256::from(30u64)).wrapping_sub(U256::from(40u64));
        assert_eq!(fg0_wrap, expected);
    }

    #[test]
    fn test_tokens_owed_unit_liquidity_q128_growth() {
        // 1 unit of liquidity, fee_growth delta = Q128
        // tokens_owed = (Q128 - 0) * 1 / Q128 = 1
        let (t0, t1) = get_tokens_owed(U256::ZERO, U256::ZERO, 1, Q128, Q128);
        assert_eq!(t0, U256::from(1u64));
        assert_eq!(t1, U256::from(1u64));
    }

    #[test]
    fn fuzz_fee_growth_inside_no_panic() {
        use rand::{rngs::StdRng, SeedableRng};
        fn test_rng() -> StdRng {
            StdRng::from_os_rng()
        }
        use rand::Rng;

        let mut rng = test_rng();
        for _ in 0..1000 {
            let tick_lower: i32 = rng.random_range(-500_000..500_000);
            let tick_upper: i32 = rng.random_range((tick_lower + 1)..=500_000);
            let tick_current: i32 = rng.random_range(-500_000..=500_000);

            // Random U256 fee growth values (use random u128 pairs for diversity).
            let global_0 = U256::from(rng.random::<u128>());
            let global_1 = U256::from(rng.random::<u128>());
            let outside_0_lower = U256::from(rng.random::<u128>());
            let outside_1_lower = U256::from(rng.random::<u128>());
            let outside_0_upper = U256::from(rng.random::<u128>());
            let outside_1_upper = U256::from(rng.random::<u128>());

            // Must never panic — wrapping arithmetic handles all cases.
            let _ = get_fee_growth_inside(
                tick_lower,
                tick_upper,
                tick_current,
                global_0,
                global_1,
                outside_0_lower,
                outside_1_lower,
                outside_0_upper,
                outside_1_upper,
            );
        }
    }

    #[test]
    fn fuzz_fee_growth_inside_deterministic_branch() {
        use rand::{rngs::StdRng, SeedableRng};
        fn test_rng() -> StdRng {
            StdRng::from_os_rng()
        }
        use rand::Rng;

        // Verify the correct branch is taken based on tick_current position.
        let mut rng = test_rng();
        for _ in 0..1000 {
            let tick_lower: i32 = rng.random_range(-500_000..0);
            let tick_upper: i32 = rng.random_range(1..=500_000);

            let global_0 = U256::from(rng.random::<u128>());
            let global_1 = U256::from(rng.random::<u128>());
            let outside_0_lower = U256::from(rng.random::<u128>());
            let outside_1_lower = U256::from(rng.random::<u128>());
            let outside_0_upper = U256::from(rng.random::<u128>());
            let outside_1_upper = U256::from(rng.random::<u128>());

            // Below range
            let tick_below = tick_lower - 1;
            let (fg0_below, fg1_below) = get_fee_growth_inside(
                tick_lower,
                tick_upper,
                tick_below,
                global_0,
                global_1,
                outside_0_lower,
                outside_1_lower,
                outside_0_upper,
                outside_1_upper,
            );
            assert_eq!(
                fg0_below,
                outside_0_lower.wrapping_sub(outside_0_upper),
                "below-range token0 formula wrong at tick_below={tick_below}"
            );
            assert_eq!(
                fg1_below,
                outside_1_lower.wrapping_sub(outside_1_upper),
                "below-range token1 formula wrong at tick_below={tick_below}"
            );

            // Above range
            let tick_above = tick_upper;
            let (fg0_above, fg1_above) = get_fee_growth_inside(
                tick_lower,
                tick_upper,
                tick_above,
                global_0,
                global_1,
                outside_0_lower,
                outside_1_lower,
                outside_0_upper,
                outside_1_upper,
            );
            assert_eq!(
                fg0_above,
                outside_0_upper.wrapping_sub(outside_0_lower),
                "above-range token0 formula wrong at tick_above={tick_above}"
            );
            assert_eq!(
                fg1_above,
                outside_1_upper.wrapping_sub(outside_1_lower),
                "above-range token1 formula wrong at tick_above={tick_above}"
            );

            // Inside range
            let tick_inside: i32 = rng.random_range(tick_lower..tick_upper);
            let (fg0_inside, fg1_inside) = get_fee_growth_inside(
                tick_lower,
                tick_upper,
                tick_inside,
                global_0,
                global_1,
                outside_0_lower,
                outside_1_lower,
                outside_0_upper,
                outside_1_upper,
            );
            assert_eq!(
                fg0_inside,
                global_0.wrapping_sub(outside_0_lower).wrapping_sub(outside_0_upper),
                "inside-range token0 formula wrong at tick_inside={tick_inside}"
            );
            assert_eq!(
                fg1_inside,
                global_1.wrapping_sub(outside_1_lower).wrapping_sub(outside_1_upper),
                "inside-range token1 formula wrong at tick_inside={tick_inside}"
            );
        }
    }

    #[test]
    fn fuzz_tokens_owed_no_panic() {
        use rand::{rngs::StdRng, SeedableRng};
        fn test_rng() -> StdRng {
            StdRng::from_os_rng()
        }
        use rand::Rng;

        let mut rng = test_rng();
        for _ in 0..1000 {
            let fg_inside_0_last = U256::from(rng.random::<u128>());
            let fg_inside_1_last = U256::from(rng.random::<u128>());
            let fg_inside_0 = U256::from(rng.random::<u128>());
            let fg_inside_1 = U256::from(rng.random::<u128>());
            let liquidity: u128 = rng.random();

            // Must never panic.
            let _ = get_tokens_owed(
                fg_inside_0_last,
                fg_inside_1_last,
                liquidity,
                fg_inside_0,
                fg_inside_1,
            );
        }
    }

    #[test]
    fn fuzz_tokens_owed_zero_liquidity_always_zero() {
        use rand::{rngs::StdRng, SeedableRng};
        fn test_rng() -> StdRng {
            StdRng::from_os_rng()
        }
        use rand::Rng;

        let mut rng = test_rng();
        for _ in 0..1000 {
            let fg_inside_0_last = U256::from(rng.random::<u128>());
            let fg_inside_1_last = U256::from(rng.random::<u128>());
            let fg_inside_0 = U256::from(rng.random::<u128>());
            let fg_inside_1 = U256::from(rng.random::<u128>());

            let (t0, t1) = get_tokens_owed(
                fg_inside_0_last,
                fg_inside_1_last,
                0, // zero liquidity
                fg_inside_0,
                fg_inside_1,
            );
            assert_eq!(t0, U256::ZERO, "zero liquidity must yield zero tokens_owed_0");
            assert_eq!(t1, U256::ZERO, "zero liquidity must yield zero tokens_owed_1");
        }
    }

    /// Structural reference test for the inside-range formula
    /// (`inside = global - outside_lower - outside_upper`). The values
    /// are synthetic placeholders — **not lifted from a real mainnet
    /// position** — the test asserts the function computes the same
    /// formula it documents, locking the inside-range arithmetic against
    /// silent behavior drift.
    ///
    /// **Future hardening — derive from a real mainnet position:**
    /// 1. Pick a known mainnet V3 position with non-zero
    ///    feeGrowthInside0/1LastX128 and fully-populated outside ticks.
    /// 2. Read pool's `feeGrowthGlobal0X128` + `feeGrowthGlobal1X128`.
    /// 3. Read `ticks(tick_lower).feeGrowthOutside0/1X128` and
    ///    `ticks(tick_upper).feeGrowthOutside0/1X128`.
    /// 4. Read `slot0().tick` for `tick_current`.
    /// 5. Replace `expected_*` below with literal on-chain-derived values.
    #[test]
    fn uniswap_reference_vector_in_range() {
        let tick_lower: i32 = -276_320;
        let tick_upper: i32 = -276_300;
        let tick_current: i32 = -276_310; // inside range

        let global_0_x128 =
            U256::from_str_radix("1234567890123456789012345678901234567890", 10).unwrap();
        let global_1_x128 =
            U256::from_str_radix("9876543210987654321098765432109876543210", 10).unwrap();
        let outside_0_lower_x128 = U256::from_str_radix("100000000000000000000", 10).unwrap();
        let outside_1_lower_x128 = U256::from_str_radix("200000000000000000000", 10).unwrap();
        let outside_0_upper_x128 = U256::from_str_radix("50000000000000000000", 10).unwrap();
        let outside_1_upper_x128 = U256::from_str_radix("150000000000000000000", 10).unwrap();

        let (inside_0, inside_1) = get_fee_growth_inside(
            tick_lower,
            tick_upper,
            tick_current,
            global_0_x128,
            global_1_x128,
            outside_0_lower_x128,
            outside_1_lower_x128,
            outside_0_upper_x128,
            outside_1_upper_x128,
        );

        // Inside-range branch: inside = global - outside_lower - outside_upper.
        let expected_0 =
            global_0_x128.wrapping_sub(outside_0_lower_x128).wrapping_sub(outside_0_upper_x128);
        let expected_1 =
            global_1_x128.wrapping_sub(outside_1_lower_x128).wrapping_sub(outside_1_upper_x128);

        assert_eq!(inside_0, expected_0);
        assert_eq!(inside_1, expected_1);
    }

    #[test]
    fn fuzz_tokens_owed_monotonic_in_liquidity() {
        use rand::{rngs::StdRng, SeedableRng};
        fn test_rng() -> StdRng {
            StdRng::from_os_rng()
        }
        use rand::Rng;

        // For a fixed positive fee growth delta, increasing liquidity
        // should yield non-decreasing tokens owed.
        let mut rng = test_rng();
        for _ in 0..1000 {
            let delta: u64 = rng.random_range(1..=u64::MAX);
            let fg_inside_0 = U256::from(delta);
            let liq_a: u128 = rng.random_range(1..u64::MAX as u128);
            let liq_b: u128 = rng.random_range(liq_a..=u64::MAX as u128);

            let (t0_a, _) = get_tokens_owed(U256::ZERO, U256::ZERO, liq_a, fg_inside_0, U256::ZERO);
            let (t0_b, _) = get_tokens_owed(U256::ZERO, U256::ZERO, liq_b, fg_inside_0, U256::ZERO);
            assert!(
                t0_b >= t0_a,
                "tokens_owed must be monotonic in liquidity: liq_a={liq_a}, liq_b={liq_b}, \
                 delta={delta}, t0_a={t0_a}, t0_b={t0_b}"
            );
        }
    }
}