wp_evm_v3_provider/

position_views.rs

//! Batch position-view reads and current-fee augmentation for V3-family NFPM positions.
//!
//! Hoisted from the CLI presenter so V3-fork facades can expose the same
//! resilient batch pipeline without duplicating Multicall3 decode/math logic.

use alloy_primitives::{aliases::I24, Address, U256};
use alloy_provider::{network::Ethereum, Provider};
use alloy_sol_types::SolCall;
use anyhow::Result;
use wp_evm_multicall::{aggregate3, IMulticall3};
use wp_evm_v3_core::position::PositionView;
use wp_evm_v3_interfaces::periphery::nfpm::INonfungiblePositionManagerView;

/// Per-position fee data produced by Phase 2 + fee-growth math.
/// `None` on `pool` / `fees` indicates the corresponding pool read
/// reverted (uninitialized pool, NFPM mismatch, etc.) — entry's
/// position data still emits, just without fee augmentation.
#[derive(Debug, Clone)]
pub struct PositionFees {
    pub pool: Address,
    pub current_tick: i32,
    pub sqrt_price_x96: U256,
    pub in_range: bool,
    pub current_owed_0: U256,
    pub current_owed_1: U256,
}

/// One entry in the output — either decoded values or an error string.
///
/// Per-entry success/error discrimination keeps the batch resilient:
/// a single bad token ID (nonexistent / burned / non-NFPM contract)
/// does not abort the whole multicall.
#[derive(Debug, Clone)]
pub struct PositionViewEntry<V> {
    /// The token ID echoed back from the input.
    pub token_id: U256,
    /// Decoded `(view, owner)` on success, error message on failure.
    pub result: std::result::Result<(V, Address), String>,
    /// `Some(fees)` only when `--with-fees` was set AND Phase 2
    /// succeeded for this position. `None` otherwise.
    pub fees: Option<PositionFees>,
}

/// Phase 1: dispatch NFPM `positions(tokenId)` + `ownerOf(tokenId)`
/// for every token ID via a single Multicall3 RPC, decode each
/// (success or per-entry error), and return the entries.
///
/// Split out from the original `fetch_and_render_positions` so Slice E's
/// `--with-fees` upgrade can splice a Phase-2 pool batch between
/// fetch and render without forking this helper.
pub async fn position_views<P: Provider<Ethereum>>(
    provider: &P,
    multicall: Address,
    nfpm: Address,
    token_ids: &[U256],
) -> Result<Vec<PositionViewEntry<PositionView>>> {
    let mut calls: Vec<IMulticall3::Call3> = Vec::with_capacity(token_ids.len() * 2);
    for tid in token_ids {
        calls.extend(build_token_calls(nfpm, *tid));
    }

    let raw_results = aggregate3(provider, multicall, calls).await?;
    let expected = token_ids.len() * 2;
    anyhow::ensure!(
        raw_results.len() == expected,
        "multicall returned {} results for {} token IDs; expected {}",
        raw_results.len(),
        token_ids.len(),
        expected,
    );

    Ok(token_ids
        .iter()
        .zip(raw_results.chunks(2))
        .map(|(tid, chunk)| decode_one_position(*tid, chunk))
        .collect())
}

fn build_token_calls(nfpm: Address, token_id: U256) -> [IMulticall3::Call3; 2] {
    let mk = |data: Vec<u8>| IMulticall3::Call3 {
        target: nfpm,
        allowFailure: true,
        callData: data.into(),
    };
    [
        mk(INonfungiblePositionManagerView::positionsCall { tokenId: token_id }.abi_encode()),
        mk(INonfungiblePositionManagerView::ownerOfCall { tokenId: token_id }.abi_encode()),
    ]
}

fn decode_one_position(
    token_id: U256,
    chunk: &[IMulticall3::Result],
) -> PositionViewEntry<PositionView> {
    debug_assert_eq!(chunk.len(), 2);
    match try_decode(token_id, chunk) {
        Ok(decoded) => PositionViewEntry { token_id, result: Ok(decoded), fees: None },
        Err(err) => PositionViewEntry { token_id, result: Err(err.to_string()), fees: None },
    }
}

fn try_decode(token_id: U256, chunk: &[IMulticall3::Result]) -> Result<(PositionView, Address)> {
    let need = |idx: usize, label: &str| -> Result<&[u8]> {
        let r = &chunk[idx];
        if !r.success {
            anyhow::bail!("{label} reverted (token may not exist or NFPM mismatch)");
        }
        Ok(r.returnData.as_ref())
    };

    let positions_ret =
        INonfungiblePositionManagerView::positionsCall::abi_decode_returns(need(0, "positions")?)?;
    let owner =
        INonfungiblePositionManagerView::ownerOfCall::abi_decode_returns(need(1, "ownerOf")?)?;

    let view = PositionView::from_nfpm_returns(token_id, &positions_ret);
    Ok((view, owner))
}

/// 4-call pool-globals decode result. Used by the dedup'd Phase 2 to
/// share globals across positions in the same pool.
#[derive(Debug, Clone)]
pub struct PoolGlobals {
    pub current_tick_i24: I24,
    pub sqrt_price_x96: U256,
    pub fg_global_0: U256,
    pub fg_global_1: U256,
}

/// Pool-state ABI plug for the position-fee engine. One impl per family ABI,
/// always on a LOCAL unit struct (orphan-safe). Decode-only: the engine owns
/// the single aggregate3 so the dedup batch (4·K + 2·N) stays one multicall.
pub trait PoolFeeGrowthSource {
    fn pool_globals_calls(&self, pool: Address) -> [IMulticall3::Call3; 4];
    fn tick_calls(
        &self,
        pool: Address,
        tick_lower: I24,
        tick_upper: I24,
    ) -> [IMulticall3::Call3; 2];
    fn decode_pool_globals(&self, chunk: &[IMulticall3::Result]) -> Option<PoolGlobals>;
    /// (lower0, lower1, upper0, upper1) fee-growth-outside for the two ticks.
    fn decode_tick_outside(
        &self,
        chunk: &[IMulticall3::Result],
    ) -> Option<(U256, U256, U256, U256)>;
}

/// V3-family pool-state ABI adapter for the shared position-fee engine.
pub struct V3PoolFeeGrowthSource;

impl PoolFeeGrowthSource for V3PoolFeeGrowthSource {
    fn pool_globals_calls(&self, pool: Address) -> [IMulticall3::Call3; 4] {
        use wp_evm_v3_interfaces::pool::state::IUniswapV3PoolState;

        let mk = |data: Vec<u8>| IMulticall3::Call3 {
            target: pool,
            allowFailure: true,
            callData: data.into(),
        };
        [
            mk(IUniswapV3PoolState::slot0Call {}.abi_encode()),
            mk(IUniswapV3PoolState::liquidityCall {}.abi_encode()),
            mk(IUniswapV3PoolState::feeGrowthGlobal0X128Call {}.abi_encode()),
            mk(IUniswapV3PoolState::feeGrowthGlobal1X128Call {}.abi_encode()),
        ]
    }

    fn tick_calls(
        &self,
        pool: Address,
        tick_lower: I24,
        tick_upper: I24,
    ) -> [IMulticall3::Call3; 2] {
        use wp_evm_v3_interfaces::pool::state::IUniswapV3PoolState;

        let mk = |data: Vec<u8>| IMulticall3::Call3 {
            target: pool,
            allowFailure: true,
            callData: data.into(),
        };
        [
            mk(IUniswapV3PoolState::ticksCall { tick: tick_lower }.abi_encode()),
            mk(IUniswapV3PoolState::ticksCall { tick: tick_upper }.abi_encode()),
        ]
    }

    fn decode_pool_globals(&self, chunk: &[IMulticall3::Result]) -> Option<PoolGlobals> {
        use wp_evm_v3_interfaces::pool::state::IUniswapV3PoolState;

        if chunk.iter().any(|r| !r.success) {
            return None;
        }
        let slot0 =
            IUniswapV3PoolState::slot0Call::abi_decode_returns(&chunk[0].returnData).ok()?;
        let _liquidity =
            IUniswapV3PoolState::liquidityCall::abi_decode_returns(&chunk[1].returnData).ok()?;
        let fg_global_0 =
            IUniswapV3PoolState::feeGrowthGlobal0X128Call::abi_decode_returns(&chunk[2].returnData)
                .ok()?;
        let fg_global_1 =
            IUniswapV3PoolState::feeGrowthGlobal1X128Call::abi_decode_returns(&chunk[3].returnData)
                .ok()?;
        Some(PoolGlobals {
            current_tick_i24: slot0.tick,
            sqrt_price_x96: U256::from(slot0.sqrtPriceX96),
            fg_global_0,
            fg_global_1,
        })
    }

    fn decode_tick_outside(
        &self,
        chunk: &[IMulticall3::Result],
    ) -> Option<(U256, U256, U256, U256)> {
        use wp_evm_v3_interfaces::pool::state::IUniswapV3PoolState;

        if chunk.iter().any(|r| !r.success) {
            return None;
        }
        let tick_lower_info =
            IUniswapV3PoolState::ticksCall::abi_decode_returns(&chunk[0].returnData).ok()?;
        let tick_upper_info =
            IUniswapV3PoolState::ticksCall::abi_decode_returns(&chunk[1].returnData).ok()?;
        Some((
            tick_lower_info.feeGrowthOutside0X128,
            tick_lower_info.feeGrowthOutside1X128,
            tick_upper_info.feeGrowthOutside0X128,
            tick_upper_info.feeGrowthOutside1X128,
        ))
    }
}

/// Output of `build_dedup_call_plan`. Carries enough metadata to
/// route decoded results back to source positions.
#[derive(Debug)]
struct DedupCallPlan {
    /// Multicall3 call vector. Layout: `4*unique_pools.len()` globals
    /// (slot0, liquidity, feeGrowthGlobal0X128, feeGrowthGlobal1X128
    /// per pool), followed by `2*targets.len()` per-position tick
    /// calls (`ticks(lower)`, `ticks(upper)`).
    pub calls: Vec<IMulticall3::Call3>,
    /// Pool addresses in first-appearance order. `unique_pools[k]`'s
    /// 4 globals occupy `calls[4*k .. 4*(k+1)]`.
    pub unique_pools: Vec<Address>,
    /// For each input target (in order), the index into `unique_pools`
    /// telling the decoder which pool's globals to read for that
    /// position's fee math.
    pub position_to_pool_idx: Vec<usize>,
}

/// Build the dedup'd Phase-2 call plan from `(target_idx, pool,
/// tick_pair)` triples. K unique pools × 4 globals + N positions ×
/// 2 ticks. Pure function — no provider dependency, fully testable.
fn build_dedup_call_plan<S: PoolFeeGrowthSource>(
    targets: &[(usize, Address, (i32, i32))],
    source: &S,
) -> DedupCallPlan {
    use std::collections::HashMap;

    // First pass: collect unique pools in first-appearance order.
    // BTreeMap-ordered would be deterministic but breaks the
    // "first-appearance" property; HashMap + sidecar Vec preserves it.
    let mut unique_pools: Vec<Address> = Vec::new();
    let mut pool_to_idx: HashMap<Address, usize> = HashMap::new();
    for (_, pool, _) in targets {
        if !pool_to_idx.contains_key(pool) {
            pool_to_idx.insert(*pool, unique_pools.len());
            unique_pools.push(*pool);
        }
    }

    // Per-position pool index, for the decoder.
    let position_to_pool_idx: Vec<usize> =
        targets.iter().map(|(_, pool, _)| pool_to_idx[pool]).collect();

    // Build calls: 4*K globals + 2*N tick calls.
    let mut calls: Vec<IMulticall3::Call3> =
        Vec::with_capacity(4 * unique_pools.len() + 2 * targets.len());

    for pool in &unique_pools {
        calls.extend(source.pool_globals_calls(*pool));
    }
    for (_, pool, (tick_lower, tick_upper)) in targets {
        let tl = i32_to_i24_truncating(*tick_lower);
        let tu = i32_to_i24_truncating(*tick_upper);
        calls.extend(source.tick_calls(*pool, tl, tu));
    }

    DedupCallPlan { calls, unique_pools, position_to_pool_idx }
}

/// Truncating `i32 → I24` matching Solidity int24 cast semantics.
///
/// **Infallible by construction.** Takes the low 3 bytes of the i32's
/// big-endian representation; alloy's `I24::from_be_bytes::<3>` then
/// sign-extends within int24 range.
///
/// For any `PositionView` produced via `PositionView::from_nfpm_returns`
/// (which sign-extends from on-chain `int24` via
/// `wp_evm_base::evm::sign_extend_i24`), this is a lossless round-trip
/// — the `i32` is always in `[-2^23, 2^23)`. For pathological inputs
/// outside that range (e.g. a future test or refactor that constructs
/// `PositionView` directly with a wonky tick), the truncation matches
/// what Solidity does on `int24(largeInt)` cast. Worst case: that one
/// entry's `fees` reflect a different tick than intended (silently
/// wrong if the truncated tick is initialized in the pool, `None` if
/// not). Bad data stays contained to that one entry — **per-entry
/// resilience preserved** without aborting the whole batch.
///
/// Mirrors the byte-truncation pattern used by Slice B's
/// `i24_to_be_bytes` in `wp-evm-v3-core::position`.
fn i32_to_i24_truncating(tick: i32) -> I24 {
    let bytes = tick.to_be_bytes();
    I24::from_be_bytes::<3>([bytes[1], bytes[2], bytes[3]])
}

/// Scalar inputs required by the shared fee-growth engine.
#[derive(Debug, Clone, Copy)]
pub struct FeeMathInputs {
    pub tick_lower: i32,
    pub tick_upper: i32,
    pub liquidity: u128,
    pub fee_growth_inside_0_last_x128: U256,
    pub fee_growth_inside_1_last_x128: U256,
    pub tokens_owed_0_stale: u128,
    pub tokens_owed_1_stale: u128,
}

/// Phase 2: for every entry whose Phase-1 fetch succeeded, derive its
/// pool address (R7), build a dedup'd pool-call plan, dispatch one
/// Multicall3 RPC for all of them, decode + run fee-growth math,
/// attach `fees` to each entry.
///
/// Pool-global failures (`slot0`, `liquidity`, fee-growth globals)
/// leave fees unavailable for every position in that pool. Per-position
/// tick failures leave only that entry's `fees = None`. Whole-batch RPC
/// errors propagate up.
pub async fn populate_position_fees_with<P, V, S>(
    provider: &P,
    multicall: Address,
    entries: &mut [PositionViewEntry<V>],
    source: &S,
    derive_pool: impl Fn(&V) -> Option<Address>,
    extract: impl Fn(&V) -> FeeMathInputs,
) -> Result<()>
where
    P: Provider<Ethereum>,
    V: Clone,
    S: PoolFeeGrowthSource,
{
    use wp_evm_amm_math::fee_growth::get_fee_growth_inside;
    use wp_evm_base::evm::sign_extend_i24;

    // Collect (entry_idx, pool, view inputs) triples for every entry whose
    // Phase-1 fetch succeeded. Skip entries with unsupported (protocol,
    // chain) — caller (run) validates, but per-entry resilience is
    // preserved as a hard invariant.
    let mut targets: Vec<(usize, Address, V, FeeMathInputs)> = Vec::new();
    for (idx, entry) in entries.iter().enumerate() {
        if let Ok((view, _owner)) = &entry.result {
            let pool = match derive_pool(view) {
                Some(addr) => addr,
                None => continue,
            };
            targets.push((idx, pool, view.clone(), extract(view)));
        }
    }

    if targets.is_empty() {
        return Ok(());
    }

    // Build the dedup'd call plan: K unique pools × 4 globals +
    // N positions × 2 tick calls. Single Multicall3 RPC.
    let tick_targets: Vec<(usize, Address, (i32, i32))> = targets
        .iter()
        .map(|(idx, pool, _view, inputs)| (*idx, *pool, (inputs.tick_lower, inputs.tick_upper)))
        .collect();
    let plan = build_dedup_call_plan(&tick_targets, source);

    let raw = aggregate3(provider, multicall, plan.calls).await?;
    let expected = 4 * plan.unique_pools.len() + 2 * targets.len();
    anyhow::ensure!(
        raw.len() == expected,
        "phase-2 multicall returned {} results for K={} pools + N={} positions; expected {}",
        raw.len(),
        plan.unique_pools.len(),
        targets.len(),
        expected,
    );

    // Decode globals once per unique pool. Per-pool failure → None,
    // distributed to every position in that pool.
    let globals_section = &raw[..4 * plan.unique_pools.len()];
    let pool_globals: Vec<Option<PoolGlobals>> = (0..plan.unique_pools.len())
        .map(|k| source.decode_pool_globals(&globals_section[4 * k..4 * (k + 1)]))
        .collect();

    // Decode ticks per position. Per-position failure → None for that
    // entry only.
    let ticks_offset = 4 * plan.unique_pools.len();
    for (n, (entry_idx, pool, _view, inputs)) in targets.iter().enumerate() {
        let pool_idx = plan.position_to_pool_idx[n];
        let Some(globals) = &pool_globals[pool_idx] else {
            // Pool globals failed → this entry's fees stay None.
            continue;
        };
        let tick_chunk = &raw[ticks_offset + 2 * n..ticks_offset + 2 * (n + 1)];
        let Some((lower0, lower1, upper0, upper1)) = source.decode_tick_outside(tick_chunk) else {
            continue;
        };

        let current_tick = sign_extend_i24(globals.current_tick_i24);
        let in_range = inputs.tick_lower <= current_tick && current_tick < inputs.tick_upper;

        let (fg_inside_0, fg_inside_1) = get_fee_growth_inside(
            inputs.tick_lower,
            inputs.tick_upper,
            current_tick,
            globals.fg_global_0,
            globals.fg_global_1,
            lower0,
            lower1,
            upper0,
            upper1,
        );

        let (current_owed_0, current_owed_1) =
            current_tokens_owed(*inputs, fg_inside_0, fg_inside_1);

        entries[*entry_idx].fees = Some(PositionFees {
            pool: *pool,
            current_tick,
            sqrt_price_x96: globals.sqrt_price_x96,
            in_range,
            current_owed_0,
            current_owed_1,
        });
    }

    Ok(())
}

pub async fn populate_position_fees<P: Provider<Ethereum>>(
    provider: &P,
    multicall: Address,
    entries: &mut [PositionViewEntry<PositionView>],
    derive_pool: impl Fn(&PositionView) -> Option<Address>,
) -> Result<()> {
    populate_position_fees_with(
        provider,
        multicall,
        entries,
        &V3PoolFeeGrowthSource,
        derive_pool,
        |v| FeeMathInputs {
            tick_lower: v.tick_lower,
            tick_upper: v.tick_upper,
            liquidity: v.liquidity,
            fee_growth_inside_0_last_x128: v.fee_growth_inside_0_last_x128,
            fee_growth_inside_1_last_x128: v.fee_growth_inside_1_last_x128,
            tokens_owed_0_stale: v.tokens_owed_0_stale,
            tokens_owed_1_stale: v.tokens_owed_1_stale,
        },
    )
    .await
}

fn current_tokens_owed(
    inputs: FeeMathInputs,
    fee_growth_inside_0x128: U256,
    fee_growth_inside_1x128: U256,
) -> (U256, U256) {
    let (accrued_0, accrued_1) = wp_evm_amm_math::fee_growth::get_tokens_owed(
        inputs.fee_growth_inside_0_last_x128,
        inputs.fee_growth_inside_1_last_x128,
        inputs.liquidity,
        fee_growth_inside_0x128,
        fee_growth_inside_1x128,
    );
    (
        U256::from(inputs.tokens_owed_0_stale) + accrued_0,
        U256::from(inputs.tokens_owed_1_stale) + accrued_1,
    )
}

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

    #[test]
    fn current_tokens_owed_includes_stale_tokens_owed_snapshot() {
        use alloy_primitives::aliases::{I24, U24, U96};

        let positions_ret = INonfungiblePositionManagerView::positionsReturn {
            nonce: U96::ZERO,
            operator: Address::ZERO,
            token0: Address::ZERO,
            token1: Address::ZERO,
            fee: U24::from(500u32),
            tickLower: I24::try_from(0i32).unwrap(),
            tickUpper: I24::try_from(60i32).unwrap(),
            liquidity: 1u128,
            feeGrowthInside0LastX128: U256::ZERO,
            feeGrowthInside1LastX128: U256::ZERO,
            tokensOwed0: 7u128,
            tokensOwed1: 11u128,
        };
        let view = PositionView::from_nfpm_returns(U256::from(1u64), &positions_ret);
        let q128 = U256::from(1u64) << 128usize;

        let inputs = FeeMathInputs {
            tick_lower: view.tick_lower,
            tick_upper: view.tick_upper,
            liquidity: view.liquidity,
            fee_growth_inside_0_last_x128: view.fee_growth_inside_0_last_x128,
            fee_growth_inside_1_last_x128: view.fee_growth_inside_1_last_x128,
            tokens_owed_0_stale: view.tokens_owed_0_stale,
            tokens_owed_1_stale: view.tokens_owed_1_stale,
        };
        let (owed_0, owed_1) = current_tokens_owed(inputs, q128, q128);

        assert_eq!(owed_0, U256::from(8u64));
        assert_eq!(owed_1, U256::from(12u64));
    }

    /// Locks the post-dedup call layout: for `N` positions across `K`
    /// unique pools, Phase 2 issues exactly `4*K + 2*N` calls per multicall.
    /// The test inspects the call vector before dispatch so it doesn't need a real RPC.

    #[test]
    fn dedup_call_plan_emits_4k_plus_2n_calls() {
        let pool_a = address!("aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
        let pool_b = address!("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");

        // 3 positions: 2 in pool_a, 1 in pool_b → K=2, N=3 → 4*2 + 2*3 = 14 calls
        let targets: Vec<(usize, Address, (i32, i32))> =
            vec![(0, pool_a, (-1000, 1000)), (1, pool_a, (-2000, 2000)), (2, pool_b, (-500, 500))];

        let plan = build_dedup_call_plan(&targets, &V3PoolFeeGrowthSource);
        assert_eq!(plan.calls.len(), 14, "expected 4*K + 2*N = 4*2 + 2*3");
        assert_eq!(plan.unique_pools.len(), 2, "K = 2 unique pools");
        assert_eq!(plan.unique_pools[0], pool_a, "pool_a registered first");
        assert_eq!(plan.unique_pools[1], pool_b);
        assert_eq!(plan.position_to_pool_idx, vec![0, 0, 1]);
    }

    /// Single-pool wallet: 4 globals + 2*N tick calls. Best case for dedup.

    #[test]
    fn dedup_call_plan_single_pool_collapses_globals() {
        let pool = address!("cccccccccccccccccccccccccccccccccccccccc");
        let targets: Vec<(usize, Address, (i32, i32))> =
            (0..14).map(|i| (i, pool, (-1000 + i as i32 * 10, 1000 + i as i32 * 10))).collect();

        let plan = build_dedup_call_plan(&targets, &V3PoolFeeGrowthSource);
        // K = 1, N = 14 → 4 + 28 = 32 (was 84 pre-dedup; 62% savings).
        assert_eq!(plan.calls.len(), 32);
        assert_eq!(plan.unique_pools.len(), 1);
        assert_eq!(plan.position_to_pool_idx, vec![0; 14]);
    }

    /// All-distinct case: K = N. Call count is identical to pre-dedup
    /// (no degradation).

    #[test]
    fn dedup_call_plan_all_distinct_pools_no_degradation() {
        // 5 distinct pools, one position each. K = N = 5 → 4*5 + 2*5 = 30
        // (was 6*5 = 30 pre-dedup; identical).
        let targets: Vec<(usize, Address, (i32, i32))> = (0..5)
            .map(|i| {
                let mut bytes = [0u8; 20];
                bytes[19] = i as u8 + 1;
                (i, Address::from(bytes), (-100 * (i as i32 + 1), 100 * (i as i32 + 1)))
            })
            .collect();

        let plan = build_dedup_call_plan(&targets, &V3PoolFeeGrowthSource);
        assert_eq!(plan.calls.len(), 30);
        assert_eq!(plan.unique_pools.len(), 5);
    }

    #[test]
    fn decode_pool_globals_and_tick_chunk_decode_results_and_reverts_return_none() {
        use alloy_primitives::aliases::{I24, I56, U160};
        use wp_evm_v3_interfaces::pool::state::IUniswapV3PoolState;

        let ok = |return_data: Vec<u8>| IMulticall3::Result {
            success: true,
            returnData: return_data.into(),
        };

        let slot0 = IUniswapV3PoolState::slot0Return {
            sqrtPriceX96: U160::from(123u64),
            tick: I24::try_from(-42i32).unwrap(),
            observationIndex: 1,
            observationCardinality: 2,
            observationCardinalityNext: 3,
            feeProtocol: 0,
            unlocked: true,
        };
        let tick_lower = IUniswapV3PoolState::ticksReturn {
            liquidityGross: 10u128,
            liquidityNet: -5i128,
            feeGrowthOutside0X128: U256::from(100u64),
            feeGrowthOutside1X128: U256::from(200u64),
            tickCumulativeOutside: I56::try_from(-9i64).unwrap(),
            secondsPerLiquidityOutsideX128: U160::from(300u64),
            secondsOutside: 400,
            initialized: true,
        };
        let tick_upper = IUniswapV3PoolState::ticksReturn {
            liquidityGross: 20u128,
            liquidityNet: 5i128,
            feeGrowthOutside0X128: U256::from(101u64),
            feeGrowthOutside1X128: U256::from(201u64),
            tickCumulativeOutside: I56::try_from(9i64).unwrap(),
            secondsPerLiquidityOutsideX128: U160::from(301u64),
            secondsOutside: 401,
            initialized: true,
        };

        let chunk = [
            ok(IUniswapV3PoolState::slot0Call::abi_encode_returns(&slot0)),
            ok(IUniswapV3PoolState::liquidityCall::abi_encode_returns(&123_456u128)),
            ok(IUniswapV3PoolState::feeGrowthGlobal0X128Call::abi_encode_returns(&U256::from(
                1_000u64,
            ))),
            ok(IUniswapV3PoolState::feeGrowthGlobal1X128Call::abi_encode_returns(&U256::from(
                2_000u64,
            ))),
            ok(IUniswapV3PoolState::ticksCall::abi_encode_returns(&tick_lower)),
            ok(IUniswapV3PoolState::ticksCall::abi_encode_returns(&tick_upper)),
        ];

        let source = V3PoolFeeGrowthSource;
        let globals = source.decode_pool_globals(&chunk[..4]).expect("globals decode");
        let (lower0, lower1, upper0, upper1) =
            source.decode_tick_outside(&chunk[4..]).expect("ticks decode");
        assert_eq!(globals.current_tick_i24, slot0.tick);
        assert_eq!(globals.sqrt_price_x96, U256::from(slot0.sqrtPriceX96));
        assert_eq!(globals.fg_global_0, U256::from(1_000u64));
        assert_eq!(globals.fg_global_1, U256::from(2_000u64));
        assert_eq!(lower0, U256::from(100u64));
        assert_eq!(lower1, U256::from(200u64));
        assert_eq!(upper0, U256::from(101u64));
        assert_eq!(upper1, U256::from(201u64));

        let mut reverted_globals = chunk[..4].to_vec();
        reverted_globals[3].success = false;
        assert!(source.decode_pool_globals(&reverted_globals).is_none());

        let mut reverted_ticks = chunk[4..].to_vec();
        reverted_ticks[1].success = false;
        assert!(source.decode_tick_outside(&reverted_ticks).is_none());
    }

    /// Locks `i32_to_i24_truncating` as a lossless round-trip for any
    /// `i32` already in int24 range — i.e. for every value
    /// `PositionView::from_nfpm_returns` can produce. If a future
    /// refactor breaks this invariant, the test trips before silently
    /// corrupting Phase-2 pool calls.

    #[test]
    fn i32_to_i24_truncating_roundtrips_via_sign_extend() {
        use wp_evm_base::evm::sign_extend_i24;

        for tick in [-887_220i32, -8_388_608, -60, -1, 0, 1, 60, 887_220, 8_388_607] {
            let i24 = i32_to_i24_truncating(tick);
            assert_eq!(sign_extend_i24(i24), tick, "round-trip failed at tick={tick}");
        }
    }

    /// End-to-end fee-growth math lock against a frozen on-chain
    /// snapshot of Uniswap V3 Arbitrum mainnet position 5435993
    /// (PENDLE/WETH 0.30% pool, in-range, idle-since-mint).
    ///
    /// Inputs (read via `cast` on 2026-04-26):
    /// - NFPM positions(5435993) — see `view` below
    /// - Pool 0xdbaeb7f0...7852c slot0/globals/ticks(-76200)/ticks(-72780)
    ///
    /// Expected output (independently produced by the live CLI run):
    /// - current_owed_0 = 1_754_557_829_256_627_897 (≈ 1.7546 PENDLE)
    /// - current_owed_1 =       953_585_198_240_599 (≈ 0.000954 WETH)
    /// - in_range       = true
    /// - current_tick   = -74_964
    ///
    /// What this locks: the full Phase-2 composition —
    /// `decode_pool_globals` + `decode_tick_chunk` → `get_fee_growth_inside` (with Slice C's
    /// reordered params) → `get_tokens_owed` → `current_tokens_owed`
    /// (stale + delta) — against a real-world snapshot. Any future
    /// refactor that changes formula, param order, signed-extension
    /// semantics, or wrapping arithmetic will trip this.
    ///
    /// **NOT** a parity test against an independent oracle (e.g.
    /// simulated `collect()`); it locks the implementation against
    /// itself given a real-world input. For a third-party-truth
    /// parity check, fork integration tests against an `eth_call`
    /// `collect` simulation are the natural follow-up.

    #[test]
    fn arbitrum_position_5435993_math_snapshot_lock() {
        use alloy_primitives::aliases::{I24, I56, U160, U24, U96};
        use wp_evm_amm_math::fee_growth::get_fee_growth_inside;
        use wp_evm_base::evm::sign_extend_i24;
        use wp_evm_v3_interfaces::pool::state::IUniswapV3PoolState;

        // -------- Position state (from NFPM positions(5435993) on Arbitrum) --------
        let positions_ret = INonfungiblePositionManagerView::positionsReturn {
            nonce: U96::ZERO,
            operator: Address::ZERO,
            token0: address!("0c880f6761F1af8d9Aa9C466984b80DAb9a8c9e8"), // PENDLE
            token1: address!("82aF49447D8a07e3bd95BD0d56f35241523fBab1"), // WETH
            fee: U24::from(3_000u32),
            tickLower: I24::try_from(-76_200i32).unwrap(),
            tickUpper: I24::try_from(-72_780i32).unwrap(),
            liquidity: 137_776_574_478_361_638_142u128,
            feeGrowthInside0LastX128: U256::from_str_radix(
                "115792089237316195423570985008687907851891836270363301344313529832249190462215",
                10,
            )
            .unwrap(),
            feeGrowthInside1LastX128: U256::from_str_radix(
                "115792089237316195423570985008687907853268070783021718997865526573101277782114",
                10,
            )
            .unwrap(),
            tokensOwed0: 0u128,
            tokensOwed1: 0u128,
        };
        let view = PositionView::from_nfpm_returns(U256::from(5_435_993u64), &positions_ret);

        // -------- Pool state (from pool 0xdbaeb7f0...7852c on Arbitrum) --------
        let slot0 = IUniswapV3PoolState::slot0Return {
            sqrtPriceX96: U160::from_str_radix("1866984747909073049766330368", 10).unwrap(),
            tick: I24::try_from(-74_964i32).unwrap(),
            observationIndex: 1566,
            observationCardinality: 1800,
            observationCardinalityNext: 1800,
            feeProtocol: 102,
            unlocked: true,
        };
        let liquidity_pool = 0u128; // pool's current in-range liquidity — read but unused by fee math
        let fg_global_0 =
            U256::from_str_radix("3257941510536840956130253336502569755530", 10).unwrap();
        let fg_global_1 =
            U256::from_str_radix("90146056400431291924115652136134661340", 10).unwrap();
        let tick_lower_info = IUniswapV3PoolState::ticksReturn {
            liquidityGross: 1_025_821_222_695_237_314_208u128,
            liquidityNet: 1_025_821_222_695_237_314_208i128,
            feeGrowthOutside0X128: U256::from_str_radix(
                "3011970555915117741071824734093997682470",
                10,
            )
            .unwrap(),
            feeGrowthOutside1X128: U256::from_str_radix(
                "89996042868724336997184963186756559285",
                10,
            )
            .unwrap(),
            tickCumulativeOutside: I56::try_from(-6_183_495_934_001i64).unwrap(),
            secondsPerLiquidityOutsideX128: U160::from_str_radix(
                "1055476276114891623306785093325462239337919411",
                10,
            )
            .unwrap(),
            secondsOutside: 1_768_271_064,
            initialized: true,
        };
        let tick_upper_info = IUniswapV3PoolState::ticksReturn {
            liquidityGross: 527_757_663_279_894_400_755u128,
            liquidityNet: -178_735_004_268_239_931_963i128,
            feeGrowthOutside0X128: U256::from_str_radix(
                "1619785920262637406907822566892852684677",
                10,
            )
            .unwrap(),
            feeGrowthOutside1X128: U256::from_str_radix(
                "2061540973486906648897049606535835620",
                10,
            )
            .unwrap(),
            tickCumulativeOutside: I56::try_from(-3_908_878_221_061i64).unwrap(),
            secondsPerLiquidityOutsideX128: U160::from_str_radix("130589885041679980488482", 10)
                .unwrap(),
            secondsOutside: 58_739_145,
            initialized: true,
        };

        // -------- Round-trip the pool state through the Phase-2 decoders --------
        // Locks the multicall→struct path alongside the math.
        let ok = |data: Vec<u8>| IMulticall3::Result { success: true, returnData: data.into() };
        let chunk = [
            ok(IUniswapV3PoolState::slot0Call::abi_encode_returns(&slot0)),
            ok(IUniswapV3PoolState::liquidityCall::abi_encode_returns(&liquidity_pool)),
            ok(IUniswapV3PoolState::feeGrowthGlobal0X128Call::abi_encode_returns(&fg_global_0)),
            ok(IUniswapV3PoolState::feeGrowthGlobal1X128Call::abi_encode_returns(&fg_global_1)),
            ok(IUniswapV3PoolState::ticksCall::abi_encode_returns(&tick_lower_info)),
            ok(IUniswapV3PoolState::ticksCall::abi_encode_returns(&tick_upper_info)),
        ];
        let source = V3PoolFeeGrowthSource;
        let globals = source
            .decode_pool_globals(&chunk[..4])
            .expect("frozen Arbitrum pool globals must decode cleanly");
        let (lower0, lower1, upper0, upper1) = source
            .decode_tick_outside(&chunk[4..])
            .expect("frozen Arbitrum ticks must decode cleanly");

        // -------- Replicate `augment_with_fees`'s per-position math --------
        let current_tick = sign_extend_i24(globals.current_tick_i24);
        assert_eq!(current_tick, -74_964, "current_tick decoded from frozen slot0");

        let in_range = view.tick_lower <= current_tick && current_tick < view.tick_upper;
        assert!(in_range, "position 5435993 was in-range at the snapshot block");

        let (fg_inside_0, fg_inside_1) = get_fee_growth_inside(
            view.tick_lower,
            view.tick_upper,
            current_tick,
            globals.fg_global_0,
            globals.fg_global_1,
            lower0,
            lower1,
            upper0,
            upper1,
        );

        // Use current_tokens_owed (production helper) — locks the
        // (stale + delta) composition through the same code path
        // augment_with_fees uses, not a manual replication.
        let inputs = FeeMathInputs {
            tick_lower: view.tick_lower,
            tick_upper: view.tick_upper,
            liquidity: view.liquidity,
            fee_growth_inside_0_last_x128: view.fee_growth_inside_0_last_x128,
            fee_growth_inside_1_last_x128: view.fee_growth_inside_1_last_x128,
            tokens_owed_0_stale: view.tokens_owed_0_stale,
            tokens_owed_1_stale: view.tokens_owed_1_stale,
        };
        let (current_owed_0, current_owed_1) =
            current_tokens_owed(inputs, fg_inside_0, fg_inside_1);

        // -------- Assert against the live-CLI-produced reference --------
        assert_eq!(
            current_owed_0,
            U256::from(1_754_557_829_256_627_897u128),
            "current_owed_0 (PENDLE wei) drifted from frozen Arbitrum reference",
        );
        assert_eq!(
            current_owed_1,
            U256::from(953_585_198_240_599u128),
            "current_owed_1 (WETH wei) drifted from frozen Arbitrum reference",
        );
    }
}