degenbot.uniswap.v3_pool_calc
=============================

.. py:module:: degenbot.uniswap.v3_pool_calc

.. autoapi-nested-parse::

   Calculation mixin for Uniswap V3 concentrated-liquidity pools.

   Provides calculation methods that operate on state held by V3PoolState.
   All methods are read-only with respect to pool state — they compute
   results based on current state but don't modify it.

   These methods match the Uniswap V3 contract's math:
   - calculate_tokens_out_from_tokens_in / calculate_tokens_in_from_tokens_out:
     degenbot interface (delegated to the Rust-routed
     simulate_exact_input_swap / simulate_exact_output_swap)
   - get_absolute_price / get_absolute_exchange_rate / get_nominal_price / get_nominal_rate: pricing

   See: contract_reference/uniswap/V3/UniswapV3Factory.sol
   (UniswapV3Pool swap, Oracle, Tick, TickBitmap, SqrtPriceMath, SwapMath)





Module Contents
---------------

.. py:class:: UniswapV3PoolCalc

   Calculation methods matching the Uniswap V3 contract.

   All methods operate on state held by the concrete class via V3PoolState.

   Class variables that V3 subclasses may override:
   - FEE_DENOMINATOR
   - TICK_STRUCT_TYPES
   - SLOT0_STRUCT_TYPES


   .. py:property:: tokens
      :type: tuple[degenbot.erc20.Erc20Token, degenbot.erc20.Erc20Token]

      :abstractmethod:


      Tokens.

      :returns: The token pair held by this pool.


   .. py:property:: state
      :type: degenbot.uniswap.v3_types.UniswapV3PoolState

      :abstractmethod:


      State.

      :returns: The current pool state.


   .. py:method:: simulate_exact_input_swap(token_in: degenbot.erc20.Erc20Token, token_in_quantity: int, sqrt_price_limit_x96: int | None = None, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> degenbot.uniswap.v3_types.UniswapV3PoolSimulationResult
      :abstractmethod:


      Exact-input swap simulation (routed to the Rust seam).



   .. py:method:: simulate_exact_output_swap(token_out: degenbot.erc20.Erc20Token, token_out_quantity: int, sqrt_price_limit_x96: int | None = None, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> degenbot.uniswap.v3_types.UniswapV3PoolSimulationResult
      :abstractmethod:


      Exact-output swap simulation (routed to the Rust seam).



   .. py:attribute:: FEE_DENOMINATOR
      :value: 1000000



   .. py:method:: calculate_tokens_out_from_tokens_in(token_in: degenbot.erc20.Erc20Token, token_in_quantity: int, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> int

      Calculate expected token OUTPUT for a given INPUT at current pool state.

      :returns: The expected output token amount.

      :raises DegenbotValueError: If token_in is not held by this pool.
      :raises IncompleteSwap: If the swap cannot fulfill the full input amount.



   .. py:method:: calculate_tokens_in_from_tokens_out(token_out: degenbot.erc20.Erc20Token, token_out_quantity: int, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> int

      Calculate required token INPUT for a target OUTPUT at current pool state.

      :returns: The required input token amount.

      :raises DegenbotValueError: If token_out is not held by this pool.
      :raises IncompleteSwap: If the swap cannot fulfill the full output amount.



   .. py:method:: get_absolute_price(token: degenbot.erc20.Erc20Token, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> fractions.Fraction

      Get the absolute price for the given token, expressed in units of the other.

      :returns: The absolute price as a Fraction.



   .. py:method:: get_absolute_exchange_rate(token: degenbot.erc20.Erc20Token, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> fractions.Fraction

      Get the absolute exchange rate for the given token.

      A V3 pool encodes the token1/token0 exchange rate in sqrt_price_x96,
      so it can be directly obtained.

      :returns: The absolute exchange rate as a Fraction.

      :raises DegenbotValueError: If the token is not held by this pool.



   .. py:method:: get_nominal_price(token: degenbot.erc20.Erc20Token, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> fractions.Fraction

      Get the nominal price, corrected for decimals.

      :returns: The nominal price as a Fraction.



   .. py:method:: get_nominal_rate(token: degenbot.erc20.Erc20Token, override_state: degenbot.uniswap.v3_types.UniswapV3PoolState | None = None) -> fractions.Fraction

      Get the nominal rate of exchange, corrected for decimal place values.

      :returns: The nominal exchange rate as a Fraction.