Struct PoolProfiler 

pub struct PoolProfiler {
    pub pool: SharedPool,
    pub tick_map: TickMap,
    pub state: PoolState,
    pub analytics: PoolAnalytics,
    pub last_processed_event: Option<BlockPosition>,
    pub last_processed_ts: Option<UnixNanos>,
    pub is_initialized: bool,
    /* private fields */
}

A DeFi pool state tracker and event processor for UniswapV3-style AMM pools.

The PoolProfiler provides complete pool state management including:

• Liquidity position tracking and management.
• Tick crossing and price movement simulation.
• Fee accumulation and distribution tracking.
• Protocol fee calculation.
• Pool state validation and maintenance.

This profiler can both process historical events and execute new operations, making it suitable for both backtesting and simulation scenarios.

Usage

Create a new profiler with a pool definition, initialize it with a starting price, then either process historical events or execute new pool operations to simulate trading activity and analyze pool behavior.

Fields

pool: SharedPool

Pool definition.

tick_map: TickMap

Tick map managing liquidity distribution across price ranges.

state: PoolState

Global pool state including current price, tick, and cumulative flows with fees.

analytics: PoolAnalytics

Analytics counters tracking pool operations and performance metrics.

last_processed_event: Option<BlockPosition>

The block position of the last processed event.

last_processed_ts: Option<UnixNanos>

The event timestamp of the last processed event.

is_initialized: bool

Flag indicating whether the pool has been initialized with a starting price.

Implementations

impl PoolProfiler

pub fn new(pool: SharedPool) -> Self

Creates a new PoolProfiler instance for tracking pool state and events.

Panics

Panics if the pool’s tick spacing is not set.

pub fn initialize( &mut self, price_sqrt_ratio_x96: U160, ) -> Result<(), PoolProfilerError>

Initializes the pool with a starting price and activates the profiler.

Errors

Returns PoolProfilerError::AlreadyInitialized if the profiler has already been initialized, or PoolProfilerError::InitialTickMismatch if the pool config carries an initial_tick that disagrees with the tick derived from price_sqrt_ratio_x96.

pub fn check_if_initialized( &self, event_kind: PoolEventKind, ) -> Result<(), PoolProfilerError>

Returns an error if the pool has not been initialized.

Errors

Returns PoolProfilerError::NotInitialized when Self::initialize or Self::restore_from_snapshot has not been called yet.

pub fn process(&mut self, event: &DexPoolData) -> Result<()>

Processes a historical pool event and updates internal state.

Handles all types of pool events (swaps, mints, burns, fee collections), and updates the profiler’s internal state accordingly. This is the main entry point for processing historical blockchain events.

Errors

This function returns an error if:

• Pool is not initialized.
• Event contains invalid data (tick ranges, amounts).
• Mathematical operations overflow.

pub fn process_swap(&mut self, swap: &PoolSwap) -> Result<()>

Processes a historical swap event from blockchain data.

Replays the swap by simulating it through Self::simulate_swap_through_ticks, then verifies the simulation results against the actual event data. If mismatches are detected (tick or liquidity), the pool state is corrected to match the event values and warnings are logged.

This self-healing approach ensures pool state stays synchronized with on-chain reality even if simulation logic differs slightly from actual contract behavior.

Use Case

Historical event processing when rebuilding pool state from blockchain events.

Errors

This function returns an error if:

• Pool initialization checks fail.
• Swap simulation fails (see Self::simulate_swap_through_ticks errors).

pub fn execute_swap( &mut self, sender: Address, recipient: Address, block: BlockPosition, zero_for_one: bool, amount_specified: I256, sqrt_price_limit_x96: U160, ) -> Result<PoolSwap>

Executes a new simulated swap and returns the resulting event.

This is the public API for forward simulation of swap operations. It delegates the core swap mathematics to Self::simulate_swap_through_ticks, then wraps the results in a PoolSwap event structure with full metadata.

Errors

Returns errors from Self::simulate_swap_through_ticks:

• Pool metadata missing or invalid
• Price limit violations
• Arithmetic overflow in fee or liquidity calculations

pub fn simulate_swap_through_ticks( &self, amount_specified: I256, zero_for_one: bool, sqrt_price_limit_x96: U160, traverse_empty_ranges: bool, ) -> Result<SwapQuote>

Core read-only swap simulation engine implementing UniswapV3 mathematics.

This method performs a complete swap simulation without modifying pool state, working entirely on stack-allocated local copies of state variables. It returns a SwapQuote containing all swap results and profiling data, including a complete audit trail of crossed ticks.

Algorithm Overview

1. Iterative price curve traversal: Walks through liquidity ranges until the input/output amount is exhausted or the price limit is reached
2. Tick crossing tracking: When crossing initialized tick boundaries, records the crossing in crossed_ticks vector with complete state snapshot (tick, direction, fee growth)
3. Local liquidity updates: Tracks liquidity changes in local variables by reading liquidity_net from tick map (read-only, no mutations)
4. Fee calculation: Splits fees between LPs and protocol, accumulates in local variables
5. Quote assembly: Returns SwapQuote with amounts, prices, fees, and crossed tick data

When traverse_empty_ranges is set, the walk continues across zero-liquidity ranges to sqrt_price_limit_x96 even after the amount is exhausted. This reproduces a historical swap whose recorded amount (the on-chain consumed amount) runs out at the last liquid tick before an empty range to the boundary; forward simulation leaves it unset so the swap stops where the amount is spent, matching UniswapV3.

Errors

Returns error if:

• Pool fee is not configured
• Fee growth arithmetic overflows when scaling by liquidity
• Swap step calculations fail

Panics

Panics if the pool fee has not been initialized.

pub fn apply_swap_quote(&mut self, swap_quote: &SwapQuote)

Applies a swap quote to the pool state (mutations only, no simulation).

Panics

Panics if applying a tick-crossing liquidity delta overflows or underflows, which indicates internal tick-map inconsistency rather than a recoverable replay error.

pub fn wrap_liquidity_error(err: Error, location: PoolEventLocation) -> Error

Wraps a low-level LiquidityMathError into a PoolProfilerError carrying the supplied event location, leaving non-liquidity errors untouched.

pub fn quote_swap( &self, amount_specified: I256, zero_for_one: bool, sqrt_price_limit_x96: Option<U160>, ) -> Result<SwapQuote>

Returns a swap quote without modifying pool state.

This method simulates a swap and provides detailed profiling metrics including:

• Amounts of tokens that would be exchanged
• Price before and after the swap
• Fee breakdown (LP fees and protocol fees)
• List of crossed ticks with state snapshots

Errors

Returns error if:

• Pool fee is not configured
• Fee growth arithmetic overflows when scaling by liquidity
• Swap step calculations fail

pub fn swap_exact_in( &self, amount_in: U256, zero_for_one: bool, sqrt_price_limit_x96: Option<U160>, ) -> Result<SwapQuote>

Simulates an exact input swap (know input amount, calculate output amount).

Errors

Returns error if pool is not initialized, input is zero, or price limit is invalid

pub fn swap_exact_out( &self, amount_out: U256, zero_for_one: bool, sqrt_price_limit_x96: Option<U160>, ) -> Result<SwapQuote>

Simulates an exact output swap (know output amount, calculate required input amount).

Errors

Returns error if pool is not initialized, output is zero, price limit is invalid, or insufficient liquidity exists to fulfill the exact output amount

pub fn swap_to_lower_sqrt_price( &self, sqrt_price_limit_x96: U160, ) -> Result<SwapQuote>

Simulates a swap to move the pool price down to a target price.

Errors

Returns error if pool is not initialized or price limit is invalid.

pub fn swap_to_higher_sqrt_price( &self, sqrt_price_limit_x96: U160, ) -> Result<SwapQuote>

Simulates a swap to move the pool price up to a target price.

Errors

Returns error if pool is not initialized or price limit is invalid.

pub fn size_for_impact_bps( &self, impact_bps: u32, zero_for_one: bool, ) -> Result<U256>

Finds the maximum trade size that produces a target slippage (including fees).

Uses binary search to find the largest trade size that results in slippage at or below the target. The method iteratively simulates swaps at different sizes until it converges to the optimal size within the specified tolerance.

Returns

The maximum trade size (U256) that produces the target slippage

Errors

Returns error if:

• Impact is zero or exceeds 100% (10000 bps)
• Pool is not initialized
• Swap simulations fail

pub fn size_for_impact_bps_detailed( &self, impact_bps: u32, zero_for_one: bool, ) -> Result<SizeForImpactResult>

Finds the maximum trade size with search diagnostics. This is the detailed version of Self::size_for_impact_bps that returns extensive information about the search process.It is useful for debugging, monitoring, and analyzing search behavior in production.

Returns

Detailed result with size and search diagnostics

Errors

Returns error if:

• Impact is zero or exceeds 100% (10000 bps)
• Pool is not initialized
• Swap simulations fail

pub fn process_mint(&mut self, update: &PoolLiquidityUpdate) -> Result<()>

Processes a mint (liquidity add) event from historical data.

Updates pool state when liquidity is added to a position, validates ticks, and delegates to internal liquidity management methods.

Errors

This function returns an error if:

• Pool is not initialized.
• Tick range is invalid or not properly spaced.
• Position updates fail.

pub fn execute_mint( &mut self, recipient: Address, block: BlockPosition, tick_lower: i32, tick_upper: i32, liquidity: u128, ) -> Result<PoolLiquidityUpdate>

Executes a simulated mint (liquidity addition) operation.

Calculates required token amounts for the specified liquidity amount, updates pool state, and returns the resulting mint event.

Errors

This function returns an error if:

• Pool is not initialized.
• Tick range is invalid.
• Amount calculations fail.

pub fn process_burn(&mut self, update: &PoolLiquidityUpdate) -> Result<()>

Processes a burn (liquidity removal) event from historical data.

Updates pool state when liquidity is removed from a position. Uses negative liquidity delta to reduce the position size and tracks withdrawn amounts.

Errors

This function returns an error if:

• Pool is not initialized.
• Tick range is invalid.
• Position updates fail.

pub fn execute_burn( &mut self, recipient: Address, block: BlockPosition, tick_lower: i32, tick_upper: i32, liquidity: u128, ) -> Result<PoolLiquidityUpdate>

Executes a simulated burn (liquidity removal) operation.

Calculates token amounts that would be withdrawn for the specified liquidity, updates pool state, and returns the resulting burn event.

Errors

This function returns an error if:

• Pool is not initialized.
• Tick range is invalid.
• Amount calculations fail.
• Insufficient liquidity in position.

pub fn process_collect(&mut self, collect: &PoolFeeCollect) -> Result<()>

Processes a fee collect event from historical data.

Updates position state when accumulated fees are collected. Finds the position and delegates fee collection to the position object.

Note: Tick validation is intentionally skipped to match Uniswap V3 behavior. Invalid positions have no fees to collect, so they’re silently ignored.

Errors

This function returns an error if:

• Pool is not initialized.

pub fn process_fee_protocol_update( &mut self, update: &PoolFeeProtocolUpdate, ) -> Result<()>

Applies a protocol-fee configuration change from a SetFeeProtocol event.

Repacks the new per-token denominators into PoolState::fee_protocol so subsequent swap and flash fee splitting uses the correct setting. Not gated on pool initialization, since a protocol-fee change is independent of the pool’s price/liquidity state.

Errors

This function does not currently return an error; the Result keeps the signature uniform with the other process_* event handlers.

pub fn process_fee_protocol_collect( &mut self, collect: &PoolFeeProtocolCollect, ) -> Result<()>

Applies a protocol-fee withdrawal from a CollectProtocol event.

Decrements the accrued protocol-fee balances by the withdrawn amounts, leaving the on-chain remainder (Uniswap V3 keeps one wei in each slot to save gas). Saturating subtraction guards against replay accrual lagging behind the on-chain balance. Not gated on pool initialization, since the protocol-fee balances are independent of the pool’s price/liquidity state.

Errors

This function does not currently return an error; the Result keeps the signature uniform with the other process_* event handlers.

pub fn process_flash(&mut self, flash: &PoolFlash) -> Result<()>

Processes a flash loan event from historical data.

Errors

Returns an error if:

• Pool has no active liquidity.
• Fee growth arithmetic overflows.

pub fn execute_flash( &mut self, sender: Address, recipient: Address, block: BlockPosition, amount0: U256, amount1: U256, ) -> Result<PoolFlash>

Executes a simulated flash loan operation and returns the resulting event.

Errors

Returns an error if:

• Mathematical operations overflow when calculating fees.
• Pool has no active liquidity.
• Fee growth arithmetic overflows.

Panics

Panics if the pool fee has not been set.

pub fn liquidity_utilization_rate(&self) -> f64

Calculates the liquidity utilization rate for the pool.

The utilization rate measures what percentage of total deployed liquidity is currently active (in-range and earning fees) at the current price tick.

pub fn get_active_liquidity(&self) -> u128

Returns the pool’s active liquidity tracked by the tick map.

This represents the effective liquidity available for trading at the current price. The tick map maintains this value efficiently by updating it during tick crossings as the price moves through different ranges.

Returns

The active liquidity (u128) at the current tick from the tick map

pub fn get_total_liquidity_from_active_positions(&self) -> u128

Calculates total liquidity by summing all individual positions at the current tick.

This computes liquidity by iterating through all positions and summing those that span the current tick. Unlike Self::get_active_liquidity, which returns the maintained tick map value, this method performs a fresh calculation from position data.

pub fn get_total_liquidity(&self) -> U256

Calculates total liquidity across all positions, regardless of range status.

pub fn restore_from_snapshot(&mut self, snapshot: PoolSnapshot) -> Result<()>

Restores the profiler state from a saved snapshot.

This method allows resuming profiling from a previously saved state, enabling incremental processing without reprocessing all historical events.

Errors

Returns an error if:

• Tick insertion into the tick map fails.

Panics

Panics if the pool’s tick spacing is not set.

pub fn get_active_tick_values(&self) -> Vec<i32>

Gets a list of all initialized tick values.

Returns tick values that have been initialized (have liquidity positions). Useful for understanding the liquidity distribution across price ranges.

pub fn get_active_tick_count(&self) -> usize

Gets the number of active ticks.

pub fn get_tick(&self, tick: i32) -> Option<&PoolTick>

Gets tick information for a specific tick value.

Returns the tick data structure containing liquidity and fee information for the specified tick, if it exists.

pub fn get_current_tick(&self) -> i32

Gets the current tick position of the pool.

Returns the tick that corresponds to the current pool price. The pool must be initialized before calling this method.

pub fn get_total_tick_count(&self) -> usize

Gets the total number of ticks tracked by the tick map.

Returns count of all ticks that have ever been initialized, including those that may no longer have active liquidity.

Returns

Total tick count in the tick map

pub fn get_position( &self, owner: &Address, tick_lower: i32, tick_upper: i32, ) -> Option<&PoolPosition>

Gets position information for a specific owner and tick range.

Looks up a position by its unique key (owner + tick range) and returns the position data if it exists.

pub fn get_active_positions(&self) -> Vec<&PoolPosition>

Returns a list of all currently active positions.

Active positions are those with liquidity > 0 whose tick range includes the current pool tick, meaning they have tokens actively deployed in the pool and are earning fees from trades at the current price.

Returns

A vector of references to active PoolPosition objects.

pub fn get_all_positions(&self) -> Vec<&PoolPosition>

Returns a list of all positions tracked by the profiler.

This includes both active and inactive positions, regardless of their liquidity or tick range relative to the current pool tick.

Returns

A vector of references to all PoolPosition objects.

pub fn get_all_position_keys(&self) -> Vec<(Address, i32, i32)>

Returns position keys for all tracked positions.

pub fn extract_snapshot(&self) -> Result<PoolSnapshot>

Extracts a complete snapshot of the current pool state.

Extracts and bundles the complete pool state including global variables, all liquidity positions, and the full tick distribution into a portable PoolSnapshot structure. This snapshot can be serialized, persisted to database, or used to restore pool state later.

Errors

Returns an error if no events have been processed yet, since there is no event watermark to anchor the snapshot to.

pub fn get_total_active_positions(&self) -> usize

Gets the count of positions that are currently active.

Active positions are those with liquidity > 0 and whose tick range includes the current pool tick (meaning they have tokens in the pool).

pub fn get_total_inactive_positions(&self) -> usize

Gets the count of positions that are currently inactive.

Inactive positions are those that exist but don’t span the current tick, meaning their liquidity is entirely in one token or the other.

pub fn estimate_balance_of_token0(&self) -> U256

Estimates the total amount of token0 in the pool.

Calculates token0 balance by summing:

• Token0 amounts from all active liquidity positions
• Accumulated trading fees (approximated from fee growth)
• Protocol fees collected

pub fn estimate_balance_of_token1(&self) -> U256

Estimates the total amount of token1 in the pool.

Calculates token1 balance by summing:

• Token1 amounts from all active liquidity positions
• Accumulated trading fees (approximated from fee growth)
• Protocol fees collected

pub fn set_fee_growth_global( &mut self, fee_growth_global_0: U256, fee_growth_global_1: U256, )

Sets the global fee growth for both tokens.

This is primarily used for testing to simulate specific fee growth scenarios. In production, fee growth is updated through swap operations.

Arguments

• fee_growth_global_0 - New global fee growth for token0
• fee_growth_global_1 - New global fee growth for token1

pub fn get_total_events(&self) -> u64

Returns the total number of events processed.

pub fn enable_reporting( &mut self, from_block: u64, total_blocks: u64, update_interval: u64, )

Enables progress reporting for pool profiler event processing.

When enabled, the profiler will automatically track and log progress as events are processed through the process() method.

pub fn finalize_reporting(&mut self)

Finalizes reporting and logs final statistics.

Should be called after all events have been processed to output the final summary of the profiler bootstrap operation.

Trait Implementations

impl Clone for PoolProfiler

fn clone(&self) -> PoolProfiler

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PoolProfiler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl DerefToPyAny for PoolProfiler

impl<'a, 'py> FromPyObject<'a, 'py> for PoolProfiler

where Self: Clone,

type Error = PyClassGuardError<'a, 'py>

The type returned in the event of a conversion error.

fn extract( obj: Borrowed<'a, 'py, PyAny>, ) -> Result<Self, <Self as FromPyObject<'a, 'py>>::Error>

Extracts Self from the bound smart pointer obj.

impl<'py> IntoPyObject<'py> for PoolProfiler

type Target = PoolProfiler

The Python output type

type Output = Bound<'py, <PoolProfiler as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

impl PyClass for PoolProfiler

const NAME: &str = "PoolProfiler"

Name of the class.

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for PoolProfiler

const MODULE: Option<&str>

Module which the class will be associated with.

const IS_BASETYPE: bool = false

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

const IS_IMMUTABLE_TYPE: bool = false

#[pyclass(immutable_type)]

const RAW_DOC: &'static CStr = /// A DeFi pool state tracker and event processor for UniswapV3-style AMM pools. /// /// The `PoolProfiler` provides complete pool state management including: /// - Liquidity position tracking and management. /// - Tick crossing and price movement simulation. /// - Fee accumulation and distribution tracking. /// - Protocol fee calculation. /// - Pool state validation and maintenance. /// /// This profiler can both process historical events and execute new operations, /// making it suitable for both backtesting and simulation scenarios. /// /// # Usage /// /// Create a new profiler with a pool definition, initialize it with a starting price, /// then either process historical events or execute new pool operations to simulate /// trading activity and analyze pool behavior.

Docstring for the class provided on the struct or enum.

const DOC: &'static CStr

Fully rendered class doc, including the text_signature if a constructor is defined.

type Layout = <<PoolProfiler as PyClassImpl>::BaseNativeType as PyClassBaseType>::Layout<PoolProfiler>

Description of how this class is laid out in memory

type BaseType = PyAny

Base class

type ThreadChecker = NoopThreadChecker

This handles following two situations:

type Inventory = Pyo3MethodsInventoryForPoolProfiler

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<PyObjectOffset>

Used to provide the dictoffset slot (equivalent to tp_dictoffset)

fn weaklist_offset() -> Option<PyObjectOffset>

Used to provide the weaklistoffset slot (equivalent to tp_weaklistoffset

impl PyStubType for PoolProfiler

fn type_output() -> TypeInfo

The type to be used in the output signature, i.e. return type of the Python function or methods.

fn type_input() -> TypeInfo

The type to be used in the input signature, i.e. the arguments of the Python function or methods.

impl PyTypeInfo for PoolProfiler

const NAME: &str = <Self as ::pyo3::PyClass>::NAME

👎Deprecated since 0.28.0:

prefer using ::type_object(py).name() to get the correct runtime value

Class name.

const MODULE: Option<&str> = <Self as ::pyo3::impl_::pyclass::PyClassImpl>::MODULE

👎Deprecated since 0.28.0:

prefer using ::type_object(py).module() to get the correct runtime value

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.