charli3_dendrite 1.4.7.dev0__tar.gz → 1.4.8.dev0__tar.gz

{charli3_dendrite-1.4.7.dev0 → charli3_dendrite-1.4.8.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: charli3_dendrite
-Version: 1.4.7.dev0
+Version: 1.4.8.dev0
 Summary: 
 License-File: LICENSE
 Author: Elder Millenial

{charli3_dendrite-1.4.7.dev0 → charli3_dendrite-1.4.8.dev0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "charli3_dendrite"
-version = "1.4.7-dev0"
+version = "1.4.8-dev0"
 description = ""
 authors = ["Elder Millenial <eldermillenial@protonmail.com>"]
 readme = "README.md"
@@ -49,7 +49,7 @@ module = ["pycardano", "pycardano.*", "dotenv", "nox"]
 ignore_missing_imports = true
 
 [tool.bumpversion]
-current_version = "1.4.7-dev0"
+current_version = "1.4.8-dev0"
 parse = """(?x)
     (?P<major>\\d+)\\.
     (?P<minor>\\d+)\\.

{charli3_dendrite-1.4.7.dev0 → charli3_dendrite-1.4.8.dev0}/src/charli3_dendrite/dexs/amm/amm_types.py

@@ -5,6 +5,7 @@ from typing import ClassVar
 
 from charli3_dendrite.dataclasses.models import Assets
 from charli3_dendrite.dexs.amm.amm_base import AbstractPoolState
+from charli3_dendrite.dexs.core.errors import InvalidPoolError
 
 N_COINS = 2
 
@@ -269,7 +270,7 @@ class AbstractStableSwapPoolState(AbstractPoolState):
             ValueError: If the input asset is invalid or if multiple input
               assets are provided.
         """
-        volume_fee: int = 0
+        volume_fee: int | float = 0
         if self.volume_fee is not None:
             if isinstance(self.volume_fee, (int, float)):
                 volume_fee = self.volume_fee
@@ -336,7 +337,7 @@ class AbstractStableSwapPoolState(AbstractPoolState):
             ValueError: If the output asset is invalid or if multiple output
             assets are provided.
         """
-        volume_fee: int = 0
+        volume_fee: int | float = 0
         if self.volume_fee is not None:
             if isinstance(self.volume_fee, (int, float)):
                 volume_fee = self.volume_fee
@@ -390,48 +391,172 @@ class AbstractCommonStableSwapPoolState(AbstractStableSwapPoolState):
 
 
 class AbstractConstantLiquidityPoolState(AbstractPoolState):
-    """Represents the state of a constant liquidity pool automated market maker (AMM).
-
-    This class serves as a base for constant liquidity pool implementations, providing
-    methods to calculate the input and output asset amounts for swaps.
+    """State of a single-band concentrated-liquidity ("constant liquidity") AMM pool.
+
+    A concentrated-liquidity position holds liquidity only within one
+    ``[sqrt_lower, sqrt_upper]`` price band. Inside the band the curve is a constant
+    product on VIRTUAL reserves ``(a_v, b_v)`` extrapolated from the band bounds; a
+    swap large enough to push the price past the band is capped at the band's
+    available output (a single UTxO cannot fill beyond its range). This base
+    implements that math against the standard ``reserve_a``/``reserve_b``/``unit_a``/
+    ``unit_b``/``volume_fee`` interface — exactly as
+    :class:`AbstractConstantProductPoolState` does for plain CPP and
+    :class:`AbstractStableSwapPoolState` does for stable swaps. Concrete CLMM DEXs
+    (Dano, Sundae V4) supply only the per-band datum specifics via the two hooks
+    below (``_sqrt_price_bounds`` and, where they net fees/carve-outs, the
+    ``reserve_a``/``reserve_b`` overrides), mirroring how the stable base exposes
+    ``amp``/``_get_ann``.
     """
 
+    fee_basis: int = 10000
+
+    # ── per-DEX hooks (the analogue of the stable base's amp/_get_ann) ────────
+    def _sqrt_price_bounds(self) -> tuple[tuple[int, int], tuple[int, int]]:
+        """Return ``((lower_num, lower_den), (upper_num, upper_den))``.
+
+        The square-root price band bounds as exact integer ratios, read from the
+        pool datum: ``lower`` is ``sqrt(P_a)``, ``upper`` is ``sqrt(P_b)``.
+        """
+        raise NotImplementedError
+
+    @property
+    def _lp_fee_rate(self) -> int:
+        """LP fee rate in ``fee_basis`` units — the only fee affecting swap output.
+
+        Defaults to ``volume_fee`` (which surfaces ``fee``); a concentrated-liquidity
+        position carries one symmetric LP fee. Override if a DEX encodes a per-side
+        fee list. Any platform/protocol fee skims the LP's cut, not the swapper's
+        output, so it is deliberately excluded here.
+        """
+        fee = self.volume_fee
+        if fee is None:
+            return 0
+        if isinstance(fee, (list, tuple)):
+            return int(fee[0])
+        return int(fee)
+
+    # ── generic single-band CLMM math ────────────────────────────────────────
+    def virtual_reserves(self) -> tuple[int, int]:
+        """Virtual reserves ``(a_v, b_v)`` of the active band (aligned to a, b).
+
+        The constant-product reserves the band's liquidity ``L`` is equivalent to
+        within ``[sqrt_lower, sqrt_upper]`` (the Uniswap-V3 single-band identity
+        ``a_v = a + L/sqrt(P_b)``, ``b_v = b + L*sqrt(P_a)``), solved in exact integer
+        arithmetic. The ``a_v / b_v`` ratio is the band's marginal price.
+        """
+        a, b = self.reserve_a, self.reserve_b
+        (pa_n, pa_d), (pb_n, pb_d) = self._sqrt_price_bounds()
+        den_ab = pa_d * pb_d
+        num_ab = pa_n * pb_n
+        diff = b * den_ab - a * num_ab
+        big = math.isqrt(diff * diff + 4 * a * b * pa_d * pa_d * pb_n * pb_n)
+        liq_num = b * den_ab + a * num_ab + big
+        liq_den = 2 * (pb_n * pa_d - pb_d * pa_n)
+        # ceilDiv for each virtual-reserve offset (``-(-n // d)``).
+        a_v = -(-(liq_num * pb_d) // (liq_den * pb_n)) + a
+        b_v = -(-(liq_num * pa_n) // (liq_den * pa_d)) + b
+        return a_v, b_v
+
     def get_amount_out(
         self,
         asset: Assets,
         precise: bool = True,
     ) -> tuple[Assets, float]:
-        """Calculate the output amount for a given input in a constant liquidity pool.
+        """Output amount + price impact for an input ``asset`` (capped at the band).
 
         Args:
             asset (Assets): The input asset amount for the swap.
-            precise (bool): If True: the output rounded to the nearest integer.
+            precise (bool): Accepted for interface parity; the output is always the
+                integer floor (a single band trades whole units).
 
         Returns:
-            tuple[Assets, float]: Tuple containing the output asset and float value.
-
-        Raises:
-            NotImplementedError: This method is not implemented in the base class.
+            tuple[Assets, float]: The output asset and the price-impact ratio.
         """
-        error_msg = "CLPP amount out is not yet implemented."
-        raise NotImplementedError(error_msg)
+        if len(asset) != 1 or asset.unit() not in (self.unit_a, self.unit_b):
+            error_msg = f"Invalid input asset for pool: {asset}"
+            raise ValueError(error_msg)
+
+        a_v, b_v = self.virtual_reserves()
+        if asset.unit() == self.unit_a:
+            in_v, out_v, out_real, out_unit = a_v, b_v, self.reserve_b, self.unit_b
+        else:
+            in_v, out_v, out_real, out_unit = b_v, a_v, self.reserve_a, self.unit_a
+
+        amount_in = asset.quantity()
+        off_fee = self.fee_basis - self._lp_fee_rate
+        denominator = in_v * self.fee_basis + amount_in * off_fee
+        if denominator <= 0:
+            # Degenerate band (virtual in-reserve 0) probed with zero input: no
+            # output, no division. Guarding above the floor-division lets a
+            # parked-band probe return (0, 0.0) rather than ZeroDivisionError.
+            return Assets(**{out_unit: 0}), 0.0
+        numerator = out_v * denominator - in_v * out_v * self.fee_basis
+        # Capacity cap: one band holds only ``out_real`` of the output token; a
+        # larger swap would push price past the band, which this UTxO cannot fill.
+        # Cap the fill (order-book convention) rather than raise — callers route
+        # the remainder to other bands. A band parked at its edge has
+        # ``out_real == 0`` and correctly yields zero output.
+        expected_out = min(numerator // denominator, out_real)
+        out_assets = Assets(**{out_unit: expected_out})
+        if not precise:
+            out_assets.root[out_unit] = expected_out
+
+        if amount_in == 0 or expected_out == 0:
+            return out_assets, 0.0
+        spot = out_v / in_v
+        effective = expected_out / amount_in
+        return out_assets, 1.0 - (effective / spot)
 
     def get_amount_in(
         self,
         asset: Assets,
         precise: bool = True,
     ) -> tuple[Assets, float]:
-        """Calculate input amount needed for desired output in constant liquidity pool.
+        """Minimum input + price impact to obtain a desired output ``asset``.
+
+        Algebraic inverse of :meth:`get_amount_out` in-band:
+        ``in_min = ceil(in_v * basis * out / ((out_v - out) * offFee))``.
 
         Args:
             asset (Assets): The desired output asset amount for the swap.
-            precise (bool): If True: the output rounded to the nearest integer.
+            precise (bool): Accepted for interface parity; the input is always the
+                integer ceiling (the minimal whole-unit input).
 
         Returns:
-            tuple[Assets, float]: Tuple containing required input asset and float value.
+            tuple[Assets, float]: The required input asset and the price-impact ratio.
 
         Raises:
-            NotImplementedError: This method is not implemented in the base class.
+            InvalidPoolError: If the desired output exceeds the band's available
+                reserve (it cannot be filled from this UTxO).
         """
-        error_msg = "CLPP amount in is not yet implemented."
-        raise NotImplementedError(error_msg)
+        if len(asset) != 1 or asset.unit() not in (self.unit_a, self.unit_b):
+            error_msg = f"Invalid output asset for pool: {asset}"
+            raise ValueError(error_msg)
+        desired_out = asset.quantity()
+        if desired_out <= 0:
+            error_msg = "desired output must be positive"
+            raise ValueError(error_msg)
+
+        a_v, b_v = self.virtual_reserves()
+        off_fee = self.fee_basis - self._lp_fee_rate
+        if asset.unit() == self.unit_b:
+            out_real, in_v, out_v, in_unit = self.reserve_b, a_v, b_v, self.unit_a
+        else:
+            out_real, in_v, out_v, in_unit = self.reserve_a, b_v, a_v, self.unit_b
+        if desired_out >= out_real:
+            error_msg = (
+                f"Desired output {desired_out} exceeds available reserve {out_real}"
+            )
+            raise InvalidPoolError(error_msg)
+        amount_in = -(
+            -(in_v * self.fee_basis * desired_out) // ((out_v - desired_out) * off_fee)
+        )
+        in_assets = Assets(**{in_unit: amount_in})
+        if not precise:
+            in_assets.root[in_unit] = amount_in
+
+        if amount_in == 0:
+            return in_assets, 0.0
+        spot = out_v / in_v
+        effective = desired_out / amount_in
+        return in_assets, 1.0 - (effective / spot)

{charli3_dendrite-1.4.7.dev0 → charli3_dendrite-1.4.8.dev0}/src/charli3_dendrite/dexs/amm/dano.py

@@ -45,7 +45,7 @@ from charli3_dendrite.dataclasses.datums import OrderType
 from charli3_dendrite.dataclasses.datums import PoolDatum
 from charli3_dendrite.dataclasses.models import Assets
 from charli3_dendrite.dataclasses.models import PoolSelector
-from charli3_dendrite.dexs.amm.amm_base import AbstractPoolState
+from charli3_dendrite.dexs.amm.amm_types import AbstractConstantLiquidityPoolState
 from charli3_dendrite.dexs.core.errors import InvalidPoolError
 from charli3_dendrite.utility import asset_to_value
 
@@ -361,8 +361,16 @@ class DanoOrderDatum(OrderDatum):
         raise NotImplementedError("Dano does not use order datums")
 
 
-class DanoCLMMState(AbstractPoolState):
-    """State of a single Dano concentrated-liquidity pool."""
+class DanoCLMMState(AbstractConstantLiquidityPoolState):
+    """State of a single Dano concentrated-liquidity pool.
+
+    The single-band CLMM math (``virtual_reserves`` + ``get_amount_out``/
+    ``get_amount_in`` + the capacity cap) is inherited from
+    :class:`AbstractConstantLiquidityPoolState`; this class supplies only the
+    Dano-specific datum parsing, active-reserve carve-outs, and direct-spend
+    tx-building. The LP fee is surfaced as ``fee`` in :meth:`post_init` so the
+    base reads it via ``volume_fee``/``_lp_fee_rate``.
+    """
 
     fee: int = 0  # populated from datum.lp_fee_rate in post_init
 
@@ -562,143 +570,22 @@ class DanoCLMMState(AbstractPoolState):
         """Active reserve of tokenY, net of platform fees."""
         return self.raw_y - self._datum.platform_fee_y
 
-    # --- math (port of utils.ts:calculateConcentratedPoolSwap) -------------
-
-    def _virtual_reserves(self) -> tuple[int, int]:
-        """Compute virtual reserves (xV, yV) used by the CLMM invariant.
-
-        Mirrors `calcLiquidity` + the xV/yV step in utils.ts.
-        """
-        d = self._datum
-        x = self.reserve_a
-        y = self.reserve_b
-        pa_n, pa_d = d.sqrt_lower_price.numerator, d.sqrt_lower_price.denominator
-        pb_n, pb_d = d.sqrt_upper_price.numerator, d.sqrt_upper_price.denominator
-
-        den_a_den_b = pa_d * pb_d
-        num_a_num_b = pa_n * pb_n
-
-        diff = y * den_a_den_b - x * num_a_num_b
-        big = isqrt(diff * diff + 4 * x * y * pa_d * pa_d * pb_n * pb_n)
-
-        liq_num = y * den_a_den_b + x * num_a_num_b + big
-        liq_den = 2 * (pb_n * pa_d - pb_d * pa_n)
-
-        # ceilDiv equivalents
-        x_v = -(-(liq_num * pb_d) // (liq_den * pb_n)) + x
-        y_v = -(-(liq_num * pa_n) // (liq_den * pa_d)) + y
-        return x_v, y_v
-
-    def _swap_out(
-        self,
-        amount_in: int,
-        in_virtual: int,
-        out_virtual: int,
-        out_real: int,
-    ) -> tuple[int, int]:
-        """Port of utils.ts:getPoolChange. Returns (out_amount, platform_fee)."""
-        lp_fee = (amount_in * self._datum.lp_fee_rate) // FEE_BASIS
-        platform_fee = (lp_fee * self.platform_fee_rate) // FEE_BASIS
-        off_fee = FEE_BASIS - self._datum.lp_fee_rate
-
-        denominator = in_virtual * FEE_BASIS + amount_in * off_fee
-        numerator = out_virtual * denominator - in_virtual * out_virtual * FEE_BASIS
-        expected_out = numerator // denominator
-
-        # Concentrated-liquidity capacity cap. A single range holds only
-        # ``out_real`` of the output token; a larger swap would push the price
-        # past this range's ``[sqrt_lower, sqrt_upper]`` band, which this UTxO
-        # cannot fill. Return the capacity (the maximum obtainable output)
-        # rather than raising, mirroring the order-book convention
-        # (``ob_base`` get_amount_out caps the fill at ``available``). Callers
-        # route any remainder to other ranges, and recover the minimal input
-        # for this capped output via ``get_amount_in``. A range parked at its
-        # band edge has ``out_real == 0`` and correctly yields zero output.
-        expected_out = min(expected_out, out_real)
-
-        return expected_out, platform_fee
-
-    def get_amount_out(self, asset: Assets) -> tuple[Assets, float]:
-        """Return the output amount and price impact for a given input asset."""
-        d = self._datum
-        if len(asset) != 1 or asset.unit() not in (d.unit_x, d.unit_y):
-            raise ValueError(f"Invalid input asset for pool: {asset}")
-
-        x_v, y_v = self._virtual_reserves()
-        if asset.unit() == d.unit_x:
-            in_v, out_v, out_real, out_unit = x_v, y_v, self.reserve_b, d.unit_y
-        else:
-            in_v, out_v, out_real, out_unit = y_v, x_v, self.reserve_a, d.unit_x
-
-        out_qty, _ = self._swap_out(asset.quantity(), in_v, out_v, out_real)
-        out_assets = Assets(**{out_unit: out_qty})
-
-        # Price impact: 1 - (effective_price / spot_price)
-        # Approximated against virtual reserves.
-        if asset.quantity() == 0 or out_qty == 0:
-            return out_assets, 0.0
-        spot = out_v / in_v
-        effective = out_qty / asset.quantity()
-        price_impact = 1.0 - (effective / spot)
-        return out_assets, price_impact
-
-    def get_amount_in(self, asset: Assets) -> tuple[Assets, float]:
-        """Algebraic inverse of get_amount_out.
-
-        Given a desired output ``asset`` quantity, return the minimum input
-        amount required and the price-impact ratio.
-
-        Derivation (from spec § Redeemer: Swap, X→Y direction):
-            expected_out = Yv - floor(Xv*Yv*basis / (Xv*basis + dx*offFee))
-        Solving for ``dx`` such that expected_out >= desired_out and
-        rounding up gives:
-            dx_min = ceil(Xv*basis*desired_out / ((Yv - desired_out) * offFee))
-        The Y→X case is symmetric (swap the roles of Xv and Yv).
-        """
+    # --- math (single-band CLMM curve inherited from the base) -------------
+    # ``virtual_reserves()`` + ``get_amount_out()``/``get_amount_in()`` + the
+    # capacity cap live on ``AbstractConstantLiquidityPoolState``; Dano supplies
+    # only the band bounds below. ``unit_a``/``unit_b`` == tokenX/tokenY and
+    # ``reserve_a``/``reserve_b`` are the active (carve-out-netted) reserves, so
+    # the base reproduces the original utils.ts:calculateConcentratedPoolSwap
+    # port exactly. The tx-build path (``compute_pool_change``) keeps its own
+    # virtual-reserve computation because it must net an in-tx staking reward.
+
+    def _sqrt_price_bounds(self) -> tuple[tuple[int, int], tuple[int, int]]:
+        """Band sqrt-price bounds: ``((lower_n, lower_d), (upper_n, upper_d))``."""
         d = self._datum
-        if len(asset) != 1 or asset.unit() not in (d.unit_x, d.unit_y):
-            raise ValueError(f"Invalid output asset for pool: {asset}")
-        desired_out = asset.quantity()
-        if desired_out <= 0:
-            raise ValueError("desired output must be positive")
-
-        x_v, y_v = self._virtual_reserves()
-        pool_in_lp_x, pool_in_lp_y = self.active_liquidity()
-        off_fee = FEE_BASIS - d.lp_fee_rate
-
-        if asset.unit() == d.unit_y:
-            # User wants Y out, must pay X in.
-            if desired_out >= pool_in_lp_y:
-                raise InvalidPoolError(
-                    f"Desired Y output {desired_out} exceeds available "
-                    f"Y reserve {pool_in_lp_y}",
-                )
-            in_v, out_v = x_v, y_v
-            in_unit = d.unit_x
-            amount_in = -(
-                -(x_v * FEE_BASIS * desired_out) // ((y_v - desired_out) * off_fee)
-            )
-        else:
-            # User wants X out, must pay Y in.
-            if desired_out >= pool_in_lp_x:
-                raise InvalidPoolError(
-                    f"Desired X output {desired_out} exceeds available "
-                    f"X reserve {pool_in_lp_x}",
-                )
-            in_v, out_v = y_v, x_v
-            in_unit = d.unit_y
-            amount_in = -(
-                -(y_v * FEE_BASIS * desired_out) // ((x_v - desired_out) * off_fee)
-            )
-
-        in_assets = Assets(**{in_unit: amount_in})
-
-        if amount_in == 0:
-            return in_assets, 0.0
-        spot = out_v / in_v
-        effective = desired_out / amount_in
-        price_impact = 1.0 - (effective / spot)
-        return in_assets, price_impact
+        return (
+            (d.sqrt_lower_price.numerator, d.sqrt_lower_price.denominator),
+            (d.sqrt_upper_price.numerator, d.sqrt_upper_price.denominator),
+        )
 
     # --- spec-driven helpers ----------------------------------------------