charli3_dendrite 1.5.12.dev0__tar.gz → 1.5.13.dev0__tar.gz

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/PKG-INFO

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

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/pyproject.toml

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

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/src/charli3_dendrite/__init__.py

@@ -19,6 +19,8 @@ from charli3_dendrite.dexs.amm.splash import SplashSSPState
 from charli3_dendrite.dexs.amm.sundae import SundaeSwapCPPState
 from charli3_dendrite.dexs.amm.sundae import SundaeSwapV3CPPState
 from charli3_dendrite.dexs.amm.sundae import SundaeSwapV3StableSwap
+from charli3_dendrite.dexs.amm.sundae_v4 import SundaeV4ConstantSumPool
+from charli3_dendrite.dexs.amm.sundae_v4 import SundaeV4Vault
 from charli3_dendrite.dexs.amm.vyfi import VyFiCPPState
 from charli3_dendrite.dexs.amm.wingriders import WingRidersCPPState
 from charli3_dendrite.dexs.amm.wingriders import WingRidersSSPState

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/src/charli3_dendrite/backend/backend_base.py

@@ -10,6 +10,7 @@ from pycardano import Address  # type: ignore
 from charli3_dendrite.dataclasses.models import Assets
 from charli3_dendrite.dataclasses.models import BlockList
 from charli3_dendrite.dataclasses.models import PoolStateList
+from charli3_dendrite.dataclasses.models import RedeemerRecord
 from charli3_dendrite.dataclasses.models import ScriptReference
 from charli3_dendrite.dataclasses.models import SwapTransactionList
 
@@ -205,6 +206,25 @@ class AbstractBackend(ABC):
         """
         pass
 
+    def get_redeemers(self, tx_hash: str) -> list[RedeemerRecord]:
+        """Every redeemer supplied in transaction ``tx_hash``.
+
+        Backends that cannot index redeemers leave this unimplemented.
+
+        Args:
+            tx_hash: The transaction hash (hex).
+
+        Returns:
+            The transaction's redeemers, in implementation-defined order
+            (db-sync orders by purpose then index). ``script_hash`` is ``""``
+            for a redeemer with no script, never ``None``.
+
+        Raises:
+            NotImplementedError: if the backend has no redeemer index.
+        """
+        msg = f"{type(self).__name__} cannot read transaction redeemers."
+        raise NotImplementedError(msg)
+
     @abstractmethod
     def get_axo_target(
         self,

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/src/charli3_dendrite/backend/blockfrost/__init__.py

@@ -18,6 +18,7 @@ from charli3_dendrite.dataclasses.models import Assets
 from charli3_dendrite.dataclasses.models import BlockList
 from charli3_dendrite.dataclasses.models import PoolStateInfo
 from charli3_dendrite.dataclasses.models import PoolStateList
+from charli3_dendrite.dataclasses.models import RedeemerRecord
 from charli3_dendrite.dataclasses.models import ScriptReference
 from charli3_dendrite.dataclasses.models import SwapTransactionList
 
@@ -283,6 +284,31 @@ class BlockFrostBackend(AbstractBackend):
                 )
         return None
 
+    def get_redeemers(self, tx_hash: str) -> list[RedeemerRecord]:
+        """Every redeemer of ``tx_hash``, resolving each datum by its hash.
+
+        Args:
+            tx_hash: The transaction hash (hex).
+
+        Returns:
+            The redeemers in the order the API lists them. ``script_hash`` is
+            ``""`` for a redeemer the API reports with no script, never
+            ``None``.
+        """
+        records = []
+        for item in self.api.transaction_redeemers(tx_hash, gather_pages=True):
+            cbor = self.api.script_datum_cbor(item.redeemer_data_hash).cbor
+            records.append(
+                RedeemerRecord(
+                    tx_hash=tx_hash,
+                    purpose=item.purpose,
+                    index=item.tx_index,
+                    script_hash=item.script_hash or "",
+                    data_cbor=cbor,
+                ),
+            )
+        return records
+
     def get_axo_target(
         self,
         assets: Assets,

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/src/charli3_dendrite/backend/dbsync/__init__.py

@@ -20,6 +20,7 @@ from charli3_dendrite.backend.dbsync.models import UTxOSelector
 from charli3_dendrite.dataclasses.models import Assets
 from charli3_dendrite.dataclasses.models import BlockList
 from charli3_dendrite.dataclasses.models import PoolStateList
+from charli3_dendrite.dataclasses.models import RedeemerRecord
 from charli3_dendrite.dataclasses.models import ScriptReference
 from charli3_dendrite.dataclasses.models import SwapTransactionList
 
@@ -575,6 +576,32 @@ LIMIT 1
 
         return UTxOSelector.parse(r[0])
 
+    def get_redeemers(self, tx_hash: str) -> list[RedeemerRecord]:
+        """Every redeemer of ``tx_hash`` with its datum bytes.
+
+        Args:
+            tx_hash: The transaction hash (hex).
+
+        Returns:
+            The redeemers in ``(purpose, index)`` order. ``script_hash`` is
+            ``""`` for a redeemer with no script (db-sync's
+            ``redeemer.script_hash`` is nullable), never ``None``.
+        """
+        query = """
+SELECT encode(tx.hash, 'hex') AS tx_hash,
+       r.purpose::text AS purpose,
+       r.index AS index,
+       COALESCE(encode(r.script_hash, 'hex'), '') AS script_hash,
+       encode(rd.bytes, 'hex') AS data_cbor
+FROM redeemer r
+JOIN tx ON tx.id = r.tx_id
+JOIN redeemer_data rd ON rd.id = r.redeemer_data_id
+WHERE tx.hash = %(tx_hash)b
+ORDER BY r.purpose, r.index
+"""
+        rows = self.db_query(query, {"tx_hash": bytes.fromhex(tx_hash)})
+        return [RedeemerRecord.model_validate(row) for row in rows]
+
     def _get_historical_order_utxos(
         self,
         stake_addresses: list[str],

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/src/charli3_dendrite/backend/ogmios_kupo/__init__.py

@@ -22,6 +22,7 @@ from charli3_dendrite.dataclasses.models import BlockInfo
 from charli3_dendrite.dataclasses.models import BlockList
 from charli3_dendrite.dataclasses.models import PoolStateInfo
 from charli3_dendrite.dataclasses.models import PoolStateList
+from charli3_dendrite.dataclasses.models import RedeemerRecord
 from charli3_dendrite.dataclasses.models import ScriptReference
 from charli3_dendrite.dataclasses.models import SwapTransactionList
 
@@ -50,6 +51,8 @@ class OgmiosKupoBackend(AbstractBackend):
             ogmios_url (str): URL for the Ogmios service.
             kupo_url (str): URL for the Kupo service.
             network (Network): The Cardano network to use.
+            path (str): URL path segment appended after the host:port when
+                building the Ogmios websocket connection string.
         """
         _, ws_string = ogmios_url.split("ws://")
         self.ws_url, self.port = ws_string.split(":")
@@ -478,6 +481,15 @@ class OgmiosKupoBackend(AbstractBackend):
                     )
         return None
 
+    def get_redeemers(self, tx_hash: str) -> list[RedeemerRecord]:
+        """Kupo indexes outputs, not redeemers.
+
+        Raises:
+            NotImplementedError: always.
+        """
+        msg = "The Ogmios/Kupo backend has no redeemer index."
+        raise NotImplementedError(msg)
+
     def get_axo_target(
         self,
         assets: Assets,

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/src/charli3_dendrite/dataclasses/models.py

@@ -310,6 +310,22 @@ class ScriptReference(DendriteBaseModel):
             return None
 
 
+class RedeemerRecord(DendriteBaseModel):
+    """One redeemer of a transaction.
+
+    ``purpose`` is the ledger purpose (``spend`` / ``mint`` / ``cert`` /
+    ``reward`` / ``vote`` / ``propose``), ``index`` the redeemer's index within
+    that purpose, ``script_hash`` the hex script it was supplied for and
+    ``data_cbor`` the hex CBOR of the redeemer datum.
+    """
+
+    tx_hash: str
+    purpose: str
+    index: int
+    script_hash: str
+    data_cbor: str
+
+
 class BlockInfo(DendriteBaseModel):
     epoch_slot_no: int
     block_no: int

{charli3_dendrite-1.5.12.dev0 → charli3_dendrite-1.5.13.dev0}/src/charli3_dendrite/dexs/amm/amm_types.py

@@ -136,197 +136,6 @@ class AbstractConstantProductPoolState(AbstractPoolState):
         return amount_in, price_impact
 
 
-class AbstractConstantSumPoolState(AbstractPoolState):
-    """State of a constant-sum AMM pool priced on a fixed integer value vector.
-
-    A constant-sum pool conserves total *value* ``V = Sum(price_i * reserve_i)`` on a
-    fixed integer price vector (positionally aligned to the pool assets), with NO
-    amplification — it is the linear-curve sibling of
-    :class:`AbstractConstantProductPoolState` (``x*y=k``) and
-    :class:`AbstractStableSwapPoolState` (the amplified Curve invariant), and is NOT a
-    stable-swap variant. Within a routable 2-asset ``(i, j)`` leg a swap of ``dx`` of
-    asset ``i`` preserves ``V`` minus the floored LP fee: the pool retains
-    ``floor(dx * p_i * fee_num / fee_den)`` of value and pays the remainder out in
-    asset ``j`` at the fixed price ratio ``p_i : p_j``. Output is bounded by the
-    out-side reserve ``reserve_j`` — a constant-sum leg cannot pay out more of an
-    asset than it holds.
-
-    The returned output is the unique maximum that satisfies the on-chain constant-sum
-    swap-step relation (the value increase ``v_increase`` is pinned to exactly
-    ``floor(input_value * fee_num / fee_den)``): a larger output over-pays (fails the
-    tightness bound) and a smaller output over-charges (fails the achievable bound).
-
-    Concrete constant-sum DEXs supply only the per-leg price weights and fee via the
-    two hooks below (:meth:`_cs_price_pair` and :meth:`_cs_fee`), mirroring how
-    :class:`AbstractStableSwapPoolState` exposes ``amp``/``_get_ann`` and
-    :class:`AbstractConstantLiquidityPoolState` exposes ``_sqrt_price_bounds`` — the
-    standard ``reserve_a`` / ``reserve_b`` / ``unit_a`` / ``unit_b`` interface drives
-    the math.
-    """
-
-    fee_basis: int = 10000
-
-    # -- per-DEX hooks (the analogue of the stable base's amp/_get_ann) --------
-    def _cs_price_pair(self) -> tuple[int, int]:
-        """Integer price weights ``(price_a, price_b)`` aligned to ``(unit_a, unit_b)``.
-
-        The constant-sum value vector restricted to this 2-asset leg. Defaults to an
-        equal-price ``(1, 1)`` leg (the common stable-pair case); override when a leg
-        carries non-unit integer price weights.
-        """
-        return (1, 1)
-
-    def _cs_fee(self) -> tuple[int, int]:
-        """LP swap fee as an exact integer ratio ``(fee_num, fee_den)``.
-
-        Defaults to ``volume_fee / fee_basis``; override to supply the on-chain
-        ``fee_num`` / ``fee_den`` directly (the on-chain check floors
-        ``input_value * fee_num / fee_den``).
-        """
-        fee = self.volume_fee
-        if fee is None:
-            return (0, self.fee_basis)
-        if isinstance(fee, (list, tuple)):
-            return (int(fee[0]), self.fee_basis)
-        return (int(fee), self.fee_basis)
-
-    # -- generic constant-sum value-conservation math -------------------------
-    def get_amount_out(
-        self,
-        asset: Assets,
-        precise: bool = True,
-    ) -> tuple[Assets, float]:
-        """Output amount + price impact for an input ``asset`` (capped at the reserve).
-
-        Value-conservation forward quote: the pool retains the floored fee on the input
-        value and pays out the remaining value at the fixed price ratio, capped at the
-        out-side reserve. This is the unique maximum output that satisfies the on-chain
-        constant-sum step relation.
-
-        Args:
-            asset (Assets): The input asset amount for the swap.
-            precise (bool): Accepted for interface parity; the output is always the
-                integer floor.
-
-        Returns:
-            tuple[Assets, float]: The output asset and the price-impact ratio.
-        """
-        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)
-
-        price_a, price_b = self._cs_price_pair()
-        fee_num, fee_den = self._cs_fee()
-        if asset.unit() == self.unit_a:
-            price_in, price_out, out_real, out_unit = (
-                price_a,
-                price_b,
-                self.reserve_b,
-                self.unit_b,
-            )
-        else:
-            price_in, price_out, out_real, out_unit = (
-                price_b,
-                price_a,
-                self.reserve_a,
-                self.unit_a,
-            )
-
-        amount_in = asset.quantity()
-        input_value = amount_in * price_in
-        # Floor the fee — the pool wins the dust, exactly as the on-chain check pins
-        # v_increase = floor(input_value * fee_num / fee_den).
-        fee_value = input_value * fee_num // fee_den
-        out_value = input_value - fee_value
-        expected_out = min(out_value // price_out, 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 per in) is the fixed ratio price_in/price_out; on an uncapped leg
-        # the only wedge is the fee, so the impact equals the fee fraction (it grows
-        # once the output saturates the reserve cap).
-        effective = (expected_out * price_out) / (amount_in * price_in)
-        return out_assets, 1.0 - effective
-
-    def get_amount_in(
-        self,
-        asset: Assets,
-        precise: bool = True,
-    ) -> tuple[Assets, float]:
-        """Minimum input + price impact to obtain a desired output ``asset``.
-
-        Algebraic inverse of :meth:`get_amount_out`: the least input whose post-fee
-        value covers the requested output value at the fixed price ratio.
-
-        Args:
-            asset (Assets): The desired output asset amount for the swap.
-            precise (bool): Accepted for interface parity; the input is the integer
-                ceiling (the minimal whole-unit input).
-
-        Returns:
-            tuple[Assets, float]: The required input asset and the price-impact ratio.
-
-        Raises:
-            InvalidPoolError: If the desired output exceeds the leg's reserve.
-        """
-        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)
-
-        price_a, price_b = self._cs_price_pair()
-        fee_num, fee_den = self._cs_fee()
-        if asset.unit() == self.unit_b:
-            out_real, price_in, price_out, in_unit = (
-                self.reserve_b,
-                price_a,
-                price_b,
-                self.unit_a,
-            )
-        else:
-            out_real, price_in, price_out, in_unit = (
-                self.reserve_a,
-                price_b,
-                price_a,
-                self.unit_b,
-            )
-        if desired_out >= out_real:
-            error_msg = (
-                f"Desired output {desired_out} exceeds available reserve {out_real}"
-            )
-            raise InvalidPoolError(error_msg)
-
-        out_value = desired_out * price_out
-        net = fee_den - fee_num
-
-        def _produced(amount: int) -> int:
-            value = amount * price_in
-            return (value - value * fee_num // fee_den) // price_out
-
-        # Closed-form ceil is a valid upper bound (it ignores the fee-flooring that
-        # makes small inputs cheaper); flooring can move the true minimum down a few
-        # units, so search down to the minimum, then back up to guarantee coverage.
-        amount_in = max(1, -(-(out_value * fee_den) // (price_in * net)))
-        while amount_in > 1 and _produced(amount_in - 1) >= desired_out:
-            amount_in -= 1
-        while _produced(amount_in) < desired_out:
-            amount_in += 1
-        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
-        effective = (desired_out * price_out) / (amount_in * price_in)
-        return in_assets, 1.0 - effective
-
-
 class AbstractStableSwapPoolState(AbstractPoolState):
     """Represents the state of a stable swap automated market maker (AMM) pool."""
 

charli3_dendrite-1.5.13.dev0/src/charli3_dendrite/dexs/amm/multi_asset.py

@@ -0,0 +1,170 @@
+"""Abstract base for pools whose reserves are an N-asset vector.
+
+Every quote names its units explicitly: for ``N > 2`` there is no "other"
+asset, so nothing on this base defaults or enumerates pairs.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from abc import abstractmethod
+
+from pycardano import Address
+from pycardano import PlutusData
+from pycardano import TransactionOutput
+from pydantic import ConfigDict
+
+from charli3_dendrite.dataclasses.models import Assets
+from charli3_dendrite.dataclasses.models import DendriteBaseModel
+from charli3_dendrite.dataclasses.models import PoolSelector
+from charli3_dendrite.utility import asset_to_value
+
+
+class AbstractMultiAssetPoolState(DendriteBaseModel, ABC):
+    """State of a pool priced over an N-entry reserve vector.
+
+    ``reserves`` is keyed by dendrite unit in canonical order (lovelace first,
+    then policy + name). Subclasses own the curve math and the order builders.
+    """
+
+    model_config = ConfigDict(
+        alias_generator=None,
+        populate_by_name=True,
+        arbitrary_types_allowed=True,
+    )
+
+    reserves: Assets
+
+    @classmethod
+    @abstractmethod
+    def dex(cls) -> str:
+        """The DEX name."""
+
+    @classmethod
+    @abstractmethod
+    def pool_selector(cls) -> PoolSelector:
+        """How pool UTxOs are found."""
+
+    @classmethod
+    @abstractmethod
+    def order_selector(cls) -> list[str]:
+        """The order submission addresses."""
+
+    @property
+    @abstractmethod
+    def pool_id(self) -> str:
+        """A unique identifier for the pool type."""
+
+    @property
+    @abstractmethod
+    def stake_address(self) -> Address:
+        """The address an order UTxO is locked at."""
+
+    @abstractmethod
+    def get_amount_out(
+        self,
+        asset: Assets,
+        out_unit: str,
+        precise: bool = True,
+    ) -> tuple[Assets, float]:
+        """Output of ``out_unit`` for offering ``asset`` (one or more reserves)."""
+
+    @abstractmethod
+    def get_amount_in(
+        self,
+        asset: Assets,
+        in_unit: str,
+        precise: bool = True,
+    ) -> tuple[Assets, float]:
+        """Minimum ``in_unit`` to obtain the single-asset ``asset``."""
+
+    @abstractmethod
+    def price(self, unit_in: str, unit_out: str) -> tuple[int, int]:
+        """The exact ``(price_in, price_out)`` weights between two reserves."""
+
+    @abstractmethod
+    def apply_swap(self, asset_in: Assets, asset_out: Assets) -> None:
+        """Move the reserves as if the swap settled."""
+
+    @abstractmethod
+    def batcher_fee(
+        self,
+        in_assets: Assets | None = None,
+        out_assets: Assets | None = None,
+        extra_assets: Assets | None = None,
+    ) -> Assets:
+        """The lovelace an order locks for its execution fee."""
+
+    @abstractmethod
+    def deposit(
+        self,
+        in_assets: Assets | None = None,
+        out_assets: Assets | None = None,
+    ) -> Assets:
+        """The lovelace rider an order carries and gets back."""
+
+    @abstractmethod
+    def swap_datum(
+        self,
+        address_source: Address,
+        in_assets: Assets,
+        out_assets: Assets,
+        extra_assets: Assets | None = None,
+        address_target: Address | None = None,
+        datum_target: PlutusData | None = None,
+    ) -> PlutusData:
+        """The order datum for a swap of ``in_assets`` into at least ``out_assets``."""
+
+    def units(self) -> list[str]:
+        """The reserve units in canonical order."""
+        return list(self.reserves.root)
+
+    def reserve(self, unit: str) -> int:
+        """The declared reserve of ``unit``.
+
+        Raises:
+            KeyError: ``unit`` is not a reserve of this pool.
+        """
+        return self.reserves.root[unit]
+
+    def swap_utxo(
+        self,
+        address_source: Address,
+        in_assets: Assets,
+        out_assets: Assets,
+        extra_assets: Assets | None = None,
+        address_target: Address | None = None,
+        datum_target: PlutusData | None = None,
+    ) -> tuple[TransactionOutput, PlutusData]:
+        """The order output for a swap: value = input + fee + rider, inline datum.
+
+        Raises:
+            ValueError: more than one asset offered or asked.
+        """
+        if len(in_assets) != 1 or len(out_assets) != 1:
+            msg = "Only one asset can be supplied as input, and one asset as output."
+            raise ValueError(msg)
+        order_datum = self.swap_datum(
+            address_source=address_source,
+            in_assets=in_assets,
+            out_assets=out_assets,
+            extra_assets=extra_assets,
+            address_target=address_target,
+            datum_target=datum_target,
+        )
+        value = Assets(**dict(in_assets.root))
+        value.root["lovelace"] = (
+            value.root.get("lovelace", 0)
+            + self.batcher_fee(
+                in_assets=in_assets,
+                out_assets=out_assets,
+                extra_assets=extra_assets,
+            ).quantity()
+            + self.deposit(in_assets=in_assets, out_assets=out_assets).quantity()
+        )
+        output = TransactionOutput(
+            address=self.stake_address,
+            amount=asset_to_value(value),
+            datum=order_datum,
+        )
+        return output, order_datum