wp_evm_v3_provider/

hydrate.rs

//! Chain I/O for the v3 family.
//!
//! This is the **only module in this crate that reads from a provider**.
//! `data`, `quote`, and `plan` are all pure. Consumers hydrate a `PoolState`
//! once via `pool_state(...)` and then call `quote::*` / `plan::*` any
//! number of times against the in-memory snapshot.
//!
//! Both `pool_state` and `position_state` use `wp-evm-multicall::aggregate3`
//! to batch all view calls into a **single Multicall3 RPC** — pool state
//! fans 6 calls (`token0`, `token1`, `fee`, `tickSpacing`, `liquidity`,
//! `slot0`); position state fans 2 (`positions(tokenId)`, `ownerOf(tokenId)`).
//! Aligns hydrate with the `wpe pool view` / `wpe position view` CLI
//! pattern; ABI bindings come from `wp-evm-v3-interfaces` (`pool::*` +
//! `periphery::nfpm`) — no inline `sol!` duplication.
//!
//! Multicall3 address is read from `config.multicall` so chains that
//! deploy at non-canonical addresses work without code changes.

use alloy_primitives::{Address, U256};
use alloy_provider::{network::Ethereum, Provider};
use alloy_sol_types::SolCall;
use anyhow::{Context, Result};
use wp_evm_base::{chain::Chain, evm::sign_extend_i24};
use wp_evm_multicall::{aggregate3, IMulticall3};
use wp_evm_v3_core::data::{PoolState, PositionState};
use wp_evm_v3_interfaces::periphery::nfpm::INonfungiblePositionManagerView;
use wp_evm_v3_interfaces::pool::{
    immutables::IUniswapV3PoolImmutables, state::IUniswapV3PoolState,
};

/// Hydrate a `PoolState` from on-chain data via a single Multicall3 RPC.
///
/// Reads token addresses, fee, tickSpacing, liquidity, and slot0 in one
/// batched call. The returned `PoolState.ticks` is intentionally empty
/// in this phase — quote functions can exact-in small amounts that
/// stay within the current tick. Phase 4 extends this with a windowed
/// tickBitmap scan so large swaps that cross ticks can be quoted purely
/// from in-memory state (see `populate_ticks`).
#[tracing::instrument(skip_all, fields(pool = %pool), err)]
pub async fn pool_state<P: Provider<Ethereum>>(
    provider: &P,
    multicall: Address,
    pool: Address,
) -> Result<PoolState> {
    let mk = |data: Vec<u8>| IMulticall3::Call3 {
        target: pool,
        allowFailure: false,
        callData: data.into(),
    };

    let calls = vec![
        mk(IUniswapV3PoolImmutables::token0Call {}.abi_encode()),
        mk(IUniswapV3PoolImmutables::token1Call {}.abi_encode()),
        mk(IUniswapV3PoolImmutables::feeCall {}.abi_encode()),
        mk(IUniswapV3PoolImmutables::tickSpacingCall {}.abi_encode()),
        mk(IUniswapV3PoolState::liquidityCall {}.abi_encode()),
        mk(IUniswapV3PoolState::slot0Call {}.abi_encode()),
    ];

    let raw = aggregate3(provider, multicall, calls).await?;
    anyhow::ensure!(
        raw.len() == 6,
        "pool_state multicall returned {} results, expected 6",
        raw.len(),
    );

    let token0 =
        IUniswapV3PoolImmutables::token0Call::abi_decode_returns(raw[0].returnData.as_ref())
            .context("decode token0")?;
    let token1 =
        IUniswapV3PoolImmutables::token1Call::abi_decode_returns(raw[1].returnData.as_ref())
            .context("decode token1")?;
    let fee = IUniswapV3PoolImmutables::feeCall::abi_decode_returns(raw[2].returnData.as_ref())
        .context("decode fee")?;
    let spacing =
        IUniswapV3PoolImmutables::tickSpacingCall::abi_decode_returns(raw[3].returnData.as_ref())
            .context("decode tickSpacing")?;
    let liquidity =
        IUniswapV3PoolState::liquidityCall::abi_decode_returns(raw[4].returnData.as_ref())
            .context("decode liquidity")?;
    let slot0 = IUniswapV3PoolState::slot0Call::abi_decode_returns(raw[5].returnData.as_ref())
        .context("decode slot0")?;

    Ok(PoolState {
        token0,
        token1,
        fee: fee.to::<u32>(),
        tick_spacing: sign_extend_i24(spacing),
        sqrt_price_x96: U256::from(slot0.sqrtPriceX96),
        liquidity,
        tick: sign_extend_i24(slot0.tick),
        ticks: vec![],
    })
}

/// Hydrate a `PositionState` for a v3 NFT position via a single
/// Multicall3 RPC.
///
/// Reads `positions(tokenId)` (12-tuple) + `ownerOf(tokenId)` from the
/// NFPM at `config.position_mgr`. Multicall3 is dispatched at
/// `config.multicall`. `tokensOwed*` carries NFPM's stored snapshot —
/// only fresh when the position was just touched. For current
/// (live-accrued) fees, use `wpe position view --with-fees` which
/// runs the full Phase-2 fee-growth math.
#[tracing::instrument(skip_all, fields(token_id = %token_id), err)]
pub async fn position_state<P: Provider<Ethereum>>(
    provider: &P,
    multicall: Address,
    position_manager: Address,
    token_id: U256,
) -> Result<PositionState> {
    let mk = |data: Vec<u8>| IMulticall3::Call3 {
        target: position_manager,
        allowFailure: false,
        callData: data.into(),
    };

    let calls = vec![
        mk(INonfungiblePositionManagerView::positionsCall { tokenId: token_id }.abi_encode()),
        mk(INonfungiblePositionManagerView::ownerOfCall { tokenId: token_id }.abi_encode()),
    ];

    let raw = aggregate3(provider, multicall, calls).await?;
    anyhow::ensure!(
        raw.len() == 2,
        "position_state multicall returned {} results, expected 2",
        raw.len(),
    );

    let pos = INonfungiblePositionManagerView::positionsCall::abi_decode_returns(
        raw[0].returnData.as_ref(),
    )
    .context("decode positions")?;
    let owner = INonfungiblePositionManagerView::ownerOfCall::abi_decode_returns(
        raw[1].returnData.as_ref(),
    )
    .context("decode ownerOf")?;

    Ok(PositionState {
        token_id,
        owner,
        token0: pos.token0,
        token1: pos.token1,
        fee: pos.fee.to(),
        tick_lower: sign_extend_i24(pos.tickLower),
        tick_upper: sign_extend_i24(pos.tickUpper),
        liquidity: pos.liquidity,
        fees_owed_0: U256::from(pos.tokensOwed0),
        fees_owed_1: U256::from(pos.tokensOwed1),
    })
}

/// Read `(token0, token1)` from an NFPM via a typed `positions(tokenId)`
/// eth_call. Hoisted from the CLI v3 increase-liquidity command — single
/// eth_call, byte-identical `(token0, token1)` to the prior raw read.
pub async fn position_token_pair<P: Provider<Ethereum>>(
    provider: &P,
    nfpm: Address,
    token_id: U256,
) -> Result<(Address, Address)> {
    // Read via the pure ABI codec from wp-evm-v3-interfaces (the interface crate
    // stays a dependency-light pure codec — no `#[sol(rpc)]`, no async deps). The
    // rpc machinery lives here in the provider via alloy-contract's
    // `SolCallBuilder`, which is exactly what generated `sol!` bindings call.
    let ret = alloy_contract::SolCallBuilder::new_sol(
        provider,
        &nfpm,
        &INonfungiblePositionManagerView::positionsCall { tokenId: token_id },
    )
    .call()
    .await
    .context("eth_call positions")?;
    Ok((ret.token0, ret.token1))
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Enumeration {
    /// Successfully decoded token IDs from Phase 2.
    pub token_ids: Vec<U256>,
    /// Phase-1 `Multicall3.getBlockNumber()` result: snapshot block.
    pub block_number: U256,
    /// Phase-1 `balanceOf(owner)` result: number of indices requested.
    pub expected_count: u64,
    /// Phase-2 indices whose `tokenOfOwnerByIndex` call reverted or failed to decode.
    pub failed_indices: Vec<u64>,
}

impl Enumeration {
    fn empty(block_number: U256) -> Self {
        Self { token_ids: Vec::new(), block_number, expected_count: 0, failed_indices: Vec::new() }
    }
}

/// Enumerate an owner's NFPM token IDs at a single pinned block.
///
/// ERC721Enumerable: `balanceOf` + `tokenOfOwnerByIndex` calldata is
/// target-independent, so this one fn serves every CLMM family's NFPM.
/// Phase 1 (balanceOf + getBlockNumber, allowFailure:false) pins the snapshot;
/// Phase 2 (tokenOfOwnerByIndex 0..N, allowFailure:true) records reverts in
/// `failed_indices` (the Phase-1<->2 transfer-out race contract).
pub async fn enumerate_owner_token_ids<P: Provider<Ethereum>>(
    provider: &P,
    multicall: Address,
    nfpm: Address,
    owner: Address,
    chain: Chain,
) -> Result<Enumeration> {
    let calls = vec![
        IMulticall3::Call3 {
            target: nfpm,
            allowFailure: false,
            callData: INonfungiblePositionManagerView::balanceOfCall { owner }.abi_encode().into(),
        },
        IMulticall3::Call3 {
            target: multicall,
            allowFailure: false,
            callData: IMulticall3::getBlockNumberCall {}.abi_encode().into(),
        },
    ];

    let raw = aggregate3(provider, multicall, calls).await?;
    anyhow::ensure!(raw.len() == 2, "phase1 multicall returned {} results, expected 2", raw.len());

    let balance = INonfungiblePositionManagerView::balanceOfCall::abi_decode_returns(
        raw[0].returnData.as_ref(),
    )
    .context("decode balanceOf")?;
    let block_number =
        IMulticall3::getBlockNumberCall::abi_decode_returns(raw[1].returnData.as_ref())
            .context("decode getBlockNumber")?;

    let expected_count: u64 = balance.try_into().with_context(|| {
        format!(
            "balanceOf returned {balance} (exceeds u64) — does NFPM point at a real ERC-721? \
             Chain: {chain}; NFPM: {nfpm:#x}",
        )
    })?;

    if expected_count == 0 {
        return Ok(Enumeration::empty(block_number));
    }

    let calls: Vec<IMulticall3::Call3> = (0..expected_count)
        .map(|i| IMulticall3::Call3 {
            target: nfpm,
            allowFailure: true,
            callData: INonfungiblePositionManagerView::tokenOfOwnerByIndexCall {
                owner,
                index: U256::from(i),
            }
            .abi_encode()
            .into(),
        })
        .collect();

    let raw = aggregate3(provider, multicall, calls).await?;
    anyhow::ensure!(
        raw.len() == expected_count as usize,
        "phase2 multicall returned {} results, expected {}",
        raw.len(),
        expected_count,
    );

    let mut token_ids = Vec::with_capacity(raw.len());
    let mut failed_indices = Vec::new();
    for (idx, r) in raw.iter().enumerate() {
        if !r.success {
            failed_indices.push(idx as u64);
            continue;
        }
        match INonfungiblePositionManagerView::tokenOfOwnerByIndexCall::abi_decode_returns(
            r.returnData.as_ref(),
        ) {
            Ok(token_id) => token_ids.push(token_id),
            Err(_) => failed_indices.push(idx as u64),
        }
    }

    Ok(Enumeration { token_ids, block_number, expected_count, failed_indices })
}

#[cfg(test)]
mod tests {
    use super::*;
    use alloy_primitives::{address, Bytes};
    use alloy_sol_types::SolCall;

    fn ok(return_data: Vec<u8>) -> IMulticall3::Result {
        IMulticall3::Result { success: true, returnData: Bytes::from(return_data) }
    }

    fn failed() -> IMulticall3::Result {
        IMulticall3::Result { success: false, returnData: Bytes::new() }
    }

    #[tokio::test]
    async fn enumerate_reports_phase2_failed_indices() {
        use alloy::transports::mock::Asserter;
        use alloy_provider::ProviderBuilder;

        let asserter = Asserter::new();
        let provider = ProviderBuilder::new().connect_mocked_client(asserter.clone());
        let multicall = address!("cA11bde05977b3631167028862bE2a173976CA11");
        let nfpm = address!("00000000000000000000000000000000000000f1");
        let owner = address!("00000000000000000000000000000000000000a1");

        let phase1_returns = vec![
            ok(INonfungiblePositionManagerView::balanceOfCall::abi_encode_returns(&U256::from(
                3u64,
            ))),
            ok(IMulticall3::getBlockNumberCall::abi_encode_returns(&U256::from(123u64))),
        ];
        asserter.push_success(&IMulticall3::aggregate3Call::abi_encode_returns(&phase1_returns));

        let phase2_returns = vec![
            ok(INonfungiblePositionManagerView::tokenOfOwnerByIndexCall::abi_encode_returns(
                &U256::from(11u64),
            )),
            ok(INonfungiblePositionManagerView::tokenOfOwnerByIndexCall::abi_encode_returns(
                &U256::from(22u64),
            )),
            failed(),
        ];
        asserter.push_success(&IMulticall3::aggregate3Call::abi_encode_returns(&phase2_returns));

        let enumeration =
            enumerate_owner_token_ids(&provider, multicall, nfpm, owner, Chain::Ethereum)
                .await
                .expect("enumeration succeeds");

        assert_eq!(enumeration.expected_count, 3);
        assert_eq!(enumeration.block_number, U256::from(123u64));
        assert_eq!(enumeration.token_ids, vec![U256::from(11u64), U256::from(22u64)]);
        assert_eq!(enumeration.failed_indices, vec![2]);
    }

    #[tokio::test]
    async fn enumerate_empty_wallet_short_circuits() {
        use alloy::transports::mock::Asserter;
        use alloy_provider::ProviderBuilder;

        let asserter = Asserter::new();
        let provider = ProviderBuilder::new().connect_mocked_client(asserter.clone());
        let multicall = address!("cA11bde05977b3631167028862bE2a173976CA11");
        let nfpm = address!("00000000000000000000000000000000000000f1");
        let owner = address!("00000000000000000000000000000000000000a1");

        let phase1_returns = vec![
            ok(INonfungiblePositionManagerView::balanceOfCall::abi_encode_returns(&U256::ZERO)),
            ok(IMulticall3::getBlockNumberCall::abi_encode_returns(&U256::from(456u64))),
        ];
        asserter.push_success(&IMulticall3::aggregate3Call::abi_encode_returns(&phase1_returns));

        let enumeration =
            enumerate_owner_token_ids(&provider, multicall, nfpm, owner, Chain::Ethereum)
                .await
                .expect("enumeration succeeds");

        assert_eq!(enumeration.expected_count, 0);
        assert_eq!(enumeration.block_number, U256::from(456u64));
        assert!(enumeration.token_ids.is_empty());
        assert!(enumeration.failed_indices.is_empty());
    }

    #[tokio::test]
    async fn position_token_pair_decodes_v3_pair() {
        use alloy::transports::mock::Asserter;
        use alloy_provider::ProviderBuilder;
        let ret = INonfungiblePositionManagerView::positionsReturn {
            nonce: alloy_primitives::aliases::U96::ZERO,
            operator: Address::ZERO,
            token0: Address::with_last_byte(0xAA),
            token1: Address::with_last_byte(0xBB),
            fee: alloy_primitives::aliases::U24::from(500u32),
            tickLower: alloy_primitives::aliases::I24::try_from(-100i32).unwrap(),
            tickUpper: alloy_primitives::aliases::I24::try_from(100i32).unwrap(),
            liquidity: 1u128,
            feeGrowthInside0LastX128: U256::ZERO,
            feeGrowthInside1LastX128: U256::ZERO,
            tokensOwed0: 0u128,
            tokensOwed1: 0u128,
        };
        let asserter = Asserter::new();
        asserter.push_success(&alloy_primitives::Bytes::from(
            INonfungiblePositionManagerView::positionsCall::abi_encode_returns(&ret),
        ));
        let provider = ProviderBuilder::new().connect_mocked_client(asserter);
        let (t0, t1) =
            position_token_pair(&provider, Address::ZERO, U256::from(1u64)).await.unwrap();
        assert_eq!(t0, Address::with_last_byte(0xAA));
        assert_eq!(t1, Address::with_last_byte(0xBB));
    }

    #[test]
    fn nfpm_enumerable_selectors_match_across_families() {
        use wp_evm_algebra_interfaces::periphery::nfpm::IAlgebraNonfungiblePositionManager;
        use wp_evm_ramses_interfaces::periphery::nfpm::IRamsesNonfungiblePositionManager;
        use wp_evm_velodrome_interfaces::periphery::nfpm::IVelodromeNonfungiblePositionManager;

        assert_eq!(
            INonfungiblePositionManagerView::balanceOfCall::SELECTOR,
            IAlgebraNonfungiblePositionManager::balanceOfCall::SELECTOR,
        );
        assert_eq!(
            INonfungiblePositionManagerView::balanceOfCall::SELECTOR,
            IRamsesNonfungiblePositionManager::balanceOfCall::SELECTOR,
        );
        assert_eq!(
            INonfungiblePositionManagerView::balanceOfCall::SELECTOR,
            IVelodromeNonfungiblePositionManager::balanceOfCall::SELECTOR,
        );
        assert_eq!(
            INonfungiblePositionManagerView::tokenOfOwnerByIndexCall::SELECTOR,
            IAlgebraNonfungiblePositionManager::tokenOfOwnerByIndexCall::SELECTOR,
        );
        assert_eq!(
            INonfungiblePositionManagerView::tokenOfOwnerByIndexCall::SELECTOR,
            IRamsesNonfungiblePositionManager::tokenOfOwnerByIndexCall::SELECTOR,
        );
        assert_eq!(
            INonfungiblePositionManagerView::tokenOfOwnerByIndexCall::SELECTOR,
            IVelodromeNonfungiblePositionManager::tokenOfOwnerByIndexCall::SELECTOR,
        );
    }
}