charli3_dendrite 1.5.14.dev0__tar.gz → 1.5.14.dev2__tar.gz

{charli3_dendrite-1.5.14.dev0 → charli3_dendrite-1.5.14.dev2}/PKG-INFO

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

{charli3_dendrite-1.5.14.dev0 → charli3_dendrite-1.5.14.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "charli3_dendrite"
-version = "1.5.14-dev0"
+version = "1.5.14-dev2"
 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.14-dev0"
+current_version = "1.5.14-dev2"
 parse = """(?x)
     (?P<major>\\d+)\\.
     (?P<minor>\\d+)\\.

{charli3_dendrite-1.5.14.dev0 → charli3_dendrite-1.5.14.dev2}/src/charli3_dendrite/dexs/amm/wingriders.py

@@ -696,6 +696,12 @@ class WingRidersSSPState(AbstractStableSwapPoolState, WingRidersCPPState):
         return ["980e8c567670d34d4ec13a0c3b6de6199f260ae5dc9dc9e867bc5c934c"]
 
 
+# WingRiders V2 agent fee tiers: the most ADA an order can move and still pay the
+# small (0.85 ADA) or medium (1.5 ADA) fee.
+_V2_SMALL_ORDER_MAX_LOVELACE = 250_000_000
+_V2_MEDIUM_ORDER_MAX_LOVELACE = 500_000_000
+
+
 class WingRidersV2CPPState(AbstractConstantProductPoolState):
     """WingRiders CPP state."""
 
@@ -839,10 +845,22 @@ class WingRidersV2CPPState(AbstractConstantProductPoolState):
         out_assets: Assets | None = None,
         extra_assets: Assets | None = None,
     ):
-        """The V2 batcher charges a flat 2 ADA regardless of swap size (an order
-        fill deducts exactly ``2_000_000`` from the order value; the V1-era ADA
-        size tiers do not apply to V2).
+        """The agent fee the batcher keeps, tiered by the order's ADA amount.
+
+        An order always attaches 4 ADA on top of the swap: this fee plus the
+        refundable :meth:`deposit`. The batcher keeps 0.85 ADA when the order moves
+        at most 250 ADA, 1.5 ADA up to 500 ADA, and 2 ADA above that or when no ADA
+        is swapped, and returns the rest of the 4 ADA with the swap output.
         """
+        if in_assets is None or out_assets is None:
+            return Assets(lovelace=2000000)
+        merged_assets = in_assets + out_assets
+        if "lovelace" in merged_assets:
+            lovelace = merged_assets["lovelace"]
+            if lovelace <= _V2_SMALL_ORDER_MAX_LOVELACE:
+                return Assets(lovelace=850000)
+            if lovelace <= _V2_MEDIUM_ORDER_MAX_LOVELACE:
+                return Assets(lovelace=1500000)
         return Assets(lovelace=2000000)
 
 

{charli3_dendrite-1.5.14.dev0 → charli3_dendrite-1.5.14.dev2}/src/charli3_dendrite/lending/fluidtokens/math.py

@@ -40,21 +40,50 @@ def perpetual_outstanding_debt(
     repaid_installments: int = 0,
     installment_period: int = 0,
     initial_grace_period: int = 0,
+) -> int:
+    """Perpetual remaining debt for analytics: the principal before ``lend_date``.
+
+    Equal to :func:`perpetual_debt` once ``now_ms`` is past ``lend_date_ms``. A loan's
+    ``lend_date`` is its borrow transaction's validity upper bound, so for up to an
+    hour after the borrow ``now_ms`` can precede it; analytics report the principal
+    there, where the contract's own formula dips below it.
+    """
+    elapsed_ms = now_ms - lend_date_ms
+    if elapsed_ms <= 0:
+        return principal
+    return perpetual_debt(
+        principal=principal,
+        interest_rate=interest_rate,
+        apy_coef=apy_coef,
+        elapsed_ms=elapsed_ms,
+        repaid_installments=repaid_installments,
+        installment_period=installment_period,
+        initial_grace_period=initial_grace_period,
+    )
+
+
+def perpetual_debt(
+    *,
+    principal: int,
+    interest_rate: int,
+    apy_coef: int,
+    elapsed_ms: int,
+    repaid_installments: int = 0,
+    installment_period: int = 0,
+    initial_grace_period: int = 0,
 ) -> int:
     """Perpetual remaining debt == ``finance.ak`` get_remaining_debt (PerpetualLoan).
 
     ``remainingInterest = principal * (c * dh + m * H^2) / 8760`` where
     ``c = interest_rate/10000``, ``m = apy_coef/1_000_000``, ``H`` is the exact
-    fractional hours since ``lend_date`` and
+    fractional hours elapsed since ``lend_date`` and
     ``dh = H - accumulatedHoursOfRepaidInstallments``; the debt is
-    ``ceil(principal + remainingInterest)``. The on-chain validator measures time to the
-    transaction's validity upper bound; analytics use ``now_ms`` as that proxy.
+    ``ceil(principal + remainingInterest)``. The validators measure ``elapsed_ms`` to
+    the transaction's validity upper bound and apply the formula at any sign, so a
+    transaction amount must use this, not :func:`perpetual_outstanding_debt`.
     """
-    t = now_ms - lend_date_ms
-    if t <= 0:
-        return principal
-    hours = Fraction(t, _MS_PER_HOUR)
-    hours_squared = Fraction(t * t, _MS_PER_HOUR * _MS_PER_HOUR)
+    hours = Fraction(elapsed_ms, _MS_PER_HOUR)
+    hours_squared = Fraction(elapsed_ms * elapsed_ms, _MS_PER_HOUR * _MS_PER_HOUR)
     m = Fraction(apy_coef, 1_000_000)
     c = Fraction(interest_rate, _BASIS)
     accumulated = _accumulated_installment_hours(
@@ -69,6 +98,33 @@ def perpetual_outstanding_debt(
     return ceil(Fraction(principal) + remaining_interest)
 
 
+def is_repayment_late(
+    *,
+    is_perpetual: bool,
+    now_ms: int,
+    lend_date_ms: int,
+    initial_grace_period: int,
+    repaid_installments: int,
+    installment_period: int,
+    repayment_time_window: int,
+) -> bool:
+    """``finance.ak`` is_repayment_late: past the next installment's repayment window.
+
+    A perpetual loan without installments is never late. Otherwise the next installment
+    is due ``initial_grace_period + (repaid_installments + 1) * installment_period``
+    hours after ``lend_date``, with ``repayment_time_window`` hours of slack; ``now_ms``
+    past that deadline (strictly) is late.
+    """
+    if is_perpetual and installment_period == 0:
+        return False
+    hours = (
+        initial_grace_period
+        + (repaid_installments + 1) * installment_period
+        + repayment_time_window
+    )
+    return now_ms > lend_date_ms + hours * _MS_PER_HOUR
+
+
 def amortization_installment(
     *,
     principal: int,
@@ -164,3 +220,54 @@ def health_factor(
     if debt <= 0 or l_tv_divider <= 0:
         return Decimal("Infinity")
     return (collateral_value * Decimal(l_tv)) / (debt * Decimal(l_tv_divider))
+
+
+def amortized_remaining_principal(
+    *,
+    principal: int,
+    interest_rate: int,
+    total_installments: int,
+    repaid_installments: int,
+) -> int:
+    """Principal left after ``repaid_installments`` amortized installments.
+
+    ``loan_recast_action.ak``: with ``R = 1 + (interest_rate/10000)/n`` and the annuity
+    ``A`` of :func:`amortization_installment`, the remaining principal is
+    ``ceil(P * R^k - A * (R^k - 1) / (R - 1))``. A zero rate or no installments has no
+    on-chain value (the contract divides by zero) and raises ``ValueError``.
+    """
+    if total_installments <= 0 or interest_rate == 0:
+        raise ValueError("an amortized loan needs installments and a non-zero rate")
+    installment = amortization_installment(
+        principal=principal,
+        interest_rate=interest_rate,
+        total_installments=total_installments,
+    )
+    growth = 1 + Fraction(interest_rate, _BASIS) / total_installments
+    growth_k = growth**repaid_installments
+    return ceil(
+        principal * growth_k - installment * (growth_k - 1) / (growth - 1),
+    )
+
+
+def liquidation_min_collateral(
+    *,
+    debt: int,
+    principal_price: Fraction,
+    collateral_price: Fraction,
+    l_tv: int,
+    l_tv_divider: int,
+) -> int:
+    """Smallest collateral amount the contract does not consider liquidatable.
+
+    ``finance.ak`` can_liquidate liquidates when the collateral is worth nothing or
+    ``l_tv / l_tv_divider < debt_value / collateral_value`` (strictly), prices being
+    lovelace per smallest unit. The minimum safe collateral is therefore
+    ``ceil(debt_value * l_tv_divider / (l_tv * collateral_price))``, and at least 1.
+    """
+    if l_tv <= 0 or l_tv_divider <= 0 or collateral_price <= 0:
+        raise ValueError("liquidation LTV and collateral price must be positive")
+    minimum = ceil(
+        Fraction(debt) * principal_price * l_tv_divider / (l_tv * collateral_price),
+    )
+    return max(minimum, 1)

charli3_dendrite-1.5.14.dev2/src/charli3_dendrite/lending/fluidtokens/transactions/borrow_terms.py

@@ -0,0 +1,195 @@
+"""Pool-borrow terms shared by the FluidTokens transaction builders.
+
+Everything here reads only the pool datum fields V3 and V4 have in common, the signed
+oracle witness, and the chain's min-UTxO rule: the lender-bond address and datum
+commitment, the chosen collateral unit and its floor, the borrow validity window, and
+the min-ADA of a synthesized output.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from fractions import Fraction
+from math import ceil
+from typing import TYPE_CHECKING
+from typing import Any
+
+from pycardano import Address
+from pycardano import TransactionOutput
+from pycardano import min_lovelace
+
+from charli3_dendrite.dataclasses.models import Assets
+from charli3_dendrite.lending.fluidtokens.datums import CollateralAsset
+from charli3_dendrite.lending.fluidtokens.datums import PoolDatum
+from charli3_dendrite.lending.fluidtokens.transactions._common import (
+    address_from_plutus,
+)
+from charli3_dendrite.lending.transactions.infra import OUTPUT_MIN_ADA
+from charli3_dendrite.lending.transactions.infra import EvalContext
+from charli3_dendrite.lending.units import constr
+from charli3_dendrite.utility import asset_to_value
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from charli3_dendrite.lending.fluidtokens.oracles.witness import OracleReward
+
+# The FluidTokens borrow validator caps the transaction's validity window at one hour
+# (3600 slots), a distinct, wider bound than the 360-slot
+# ``_common.LOAN_ACTION_VALIDITY_SLOTS`` the V3 loan-action validators use. The window
+# additionally must fall inside the signed oracle witness's ms window.
+BORROW_VALIDITY_SLOTS = 3600
+
+# Plutus ``Bool`` True is constructor alternative 1.
+_BOOL_TRUE = 1
+
+
+def lender_bond_address(pool_datum: PoolDatum) -> Address:
+    """Decode the pool's committed ``lender_bond_address`` to a pycardano `Address`."""
+    raw = pool_datum.lender_bond_address
+    data = raw.data if hasattr(raw, "data") else raw
+    return address_from_plutus(data)
+
+
+def lender_bond_datum_matches(pool_datum: PoolDatum, datum_hex: str) -> bool:
+    """True if ``datum_hex`` hashes to the pool's committed lender-bond datum hash."""
+    digest = hashlib.blake2b(bytes.fromhex(datum_hex), digest_size=32).digest()
+    return digest == bytes(pool_datum.lender_bond_inline_datum_hash)
+
+
+def collateral_unit(pool_datum: PoolDatum, chosen_collateral_index: int) -> str:
+    """The unit (``policy_hex`` ++ ``name_hex``) of the chosen collateral option."""
+    chosen = list(pool_datum.collateral_options)[chosen_collateral_index]
+    if not isinstance(chosen, CollateralAsset):
+        chosen = CollateralAsset.from_primitive(chosen)
+    alt, fields = constr(chosen.maybe_asset_name)
+    name = bytes(fields[0]) if alt == 0 and fields else b""
+    return chosen.policy_id.hex() + name.hex()
+
+
+def min_collateral_amount(
+    pool_datum: PoolDatum,
+    *,
+    chosen_collateral_index: int,
+    principal_amount: int,
+    price_num: int,
+    price_den: int,
+    principal_price_num: int | None = None,
+    principal_price_den: int | None = None,
+) -> int:
+    """Minimum collateral units required to back ``principal_amount``.
+
+    Mirrors the pool validator's collateral floor. For a dynamically-priced pool the
+    principal is first expressed in lovelace at its price
+    ``principal_price_num / principal_price_den`` (1:1 for an ADA principal, which
+    ignores the principal price), scaled by the option's
+    ``min_collateral_divider / min_collateral`` ratio, and converted to collateral units
+    at the collateral price ``price_num / price_den``:
+    ``ceil(principal * principal_price * divider / min_collateral / price)``. For a
+    statically-priced pool the floor is
+    ``ceil(principal_amount * min_collateral / min_collateral_div)``. Prices are
+    lovelace per smallest unit. A non-ADA principal needs its price and raises
+    ``NotImplementedError`` without it.
+    """
+    principal_asset = pool_datum.common_data.principal_asset
+    principal_price = Fraction(1)
+    if principal_asset.policy_id or principal_asset.asset_name:
+        if principal_price_num is None or principal_price_den is None:
+            raise NotImplementedError(
+                "min-collateral for a non-ADA principal pool needs the principal "
+                "oracle price",
+            )
+        principal_price = Fraction(principal_price_num, principal_price_den)
+    min_collateral = int(list(pool_datum.min_collateral)[chosen_collateral_index])
+    divider = int(list(pool_datum.min_collateral_divider)[chosen_collateral_index])
+    dynamic_alt, _ = constr(pool_datum.dynamic_collateral_price)
+    if dynamic_alt == _BOOL_TRUE:
+        collateral_in_lovelace = (
+            Fraction(principal_amount * divider, min_collateral) * principal_price
+        )
+        return ceil(collateral_in_lovelace * Fraction(price_den, price_num))
+    return ceil(Fraction(principal_amount * min_collateral, divider))
+
+
+def borrow_window(
+    oracle: OracleReward,
+    *,
+    valid_from: int | None,
+    valid_to: int | None,
+    tip: int,
+) -> tuple[int, int]:
+    """The borrow's ``(valid_from, valid_to)`` slot window, covered by the witness.
+
+    :func:`signed_window` for one witness under the one-hour borrow cap.
+    """
+    return signed_window(
+        [oracle],
+        valid_from=valid_from,
+        valid_to=valid_to,
+        tip=tip,
+        cap=BORROW_VALIDITY_SLOTS,
+    )
+
+
+def signed_window(
+    oracles: Sequence[OracleReward],
+    *,
+    valid_from: int | None,
+    valid_to: int | None,
+    tip: int,
+    cap: int,
+) -> tuple[int, int]:
+    """A ``(valid_from, valid_to)`` slot window every signed price covers.
+
+    A fully pinned window (byte-exact replay) is accepted only if it spans at most
+    ``cap`` slots AND every witness covers it. Otherwise the window starts at the
+    backend ``tip`` (or the latest witness start) and ends ``cap`` slots later or at
+    the earliest witness end; a window no witness set can cover raises (a witness is
+    stale relative to the tip). Without witnesses the window is ``cap`` slots from
+    the tip.
+    """
+    if valid_from is not None and valid_to is not None:
+        if valid_to - valid_from > cap:
+            raise ValueError(f"validity window exceeds {cap} slots")
+        if not all(o.contains_slot_window(valid_from, valid_to) for o in oracles):
+            raise ValueError(
+                "pinned validity window is not covered by the oracle witness",
+            )
+        return valid_from, valid_to
+    covered = [o.tx_validity_slots() for o in oracles]
+    lower = (
+        valid_from if valid_from is not None else max([tip, *(f for f, _ in covered)])
+    )
+    upper = (
+        valid_to
+        if valid_to is not None
+        else min([lower + cap, *(t for _, t in covered)])
+    )
+    if upper - lower > cap:
+        upper = lower + cap
+    if upper <= lower or not all(o.contains_slot_window(lower, upper) for o in oracles):
+        raise ValueError(
+            "could not fit a validity window inside the oracle witness; the witness "
+            "may be stale relative to the backend tip",
+        )
+    return lower, upper
+
+
+def min_output_lovelace(
+    *,
+    address: str,
+    assets: dict[str, int],
+    datum: Any,  # noqa: ANN401 - PlutusData, RawCBOR or None
+    slot: int,
+) -> int:
+    """The protocol min-ADA of an output with ``assets`` and ``datum`` at ``address``.
+
+    ``assets`` maps unit to quantity and excludes lovelace; the output is sized with a
+    placeholder coin, which ``min_lovelace`` does not depend on beyond its encoding.
+    """
+    output = TransactionOutput(
+        Address.decode(address),
+        asset_to_value(Assets(**{"lovelace": OUTPUT_MIN_ADA, **assets})),
+        datum=datum,
+    )
+    return min_lovelace(EvalContext(last_block_slot=slot), output=output)