ddx-python 1.0.5__cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

ddx/common/transactions/fee_distribution.py

@@ -0,0 +1,119 @@
+"""
+FeeDistribution
+"""
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common import TokenSymbol
+from ddx._rust.common.state import DerivadexSMT, EpochMetadata, Trader
+from ddx._rust.common.state.keys import EpochMetadataKey, TraderKey
+from ddx._rust.decimal import Decimal
+
+
+@define
+class FeeDistribution(Event):
+    """
+    Defines a FeeDistribution
+
+    A FeeDistribution is an update to a set of custodians' DDX
+    balances.
+
+    Attributes:
+        custodians (list[str]): Operator custodians
+        bonds (list[Decimal]): Operator bonds
+        submitter (str): Checkpoint submitter address
+        epoch_id (int): Epoch id
+        request_index (int): Sequenced request index of transaction
+    """
+
+    custodians: list[str] = field(eq=lambda x: set(map(str.lower, x)))
+    bonds: list[Decimal] = field(eq=set)
+    submitter: str = field(eq=str.lower)
+    epoch_id: int
+    request_index: int = field(default=-1, eq=False)
+
+    @classmethod
+    def decode_value_into_cls(cls, raw_tx_log_event: dict):
+        """
+        Decode a raw transaction log event (dict) into a
+        FeeDistribution instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        fee_distribution_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            fee_distribution_event["custodians"],
+            [Decimal(bond) for bond in fee_distribution_event["bonds"]],
+            fee_distribution_event["submitter"],
+            fee_distribution_event["epochId"],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a FeeDistribution transaction - there shouldn't be any changes to the SMT
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to FeeDistribution transactions
+        """
+
+        # Sum and delete all epoch metadatas up to the last checkpoint/fee distribution
+        epoch_metadatas = sorted(
+            filter(
+                lambda epoch_metadata_key: epoch_metadata_key[0].epoch_id
+                <= self.epoch_id,
+                smt.all_epoch_metadatas(),
+            ),
+            key=lambda epoch_metadata_key: epoch_metadata_key[0].epoch_id,
+        )
+        accumulated_ddx = Decimal("0")
+        for epoch_metadata_key, epoch_metadata in epoch_metadatas:
+            accumulated_ddx += epoch_metadata.ddx_fee_pool
+            smt.store_epoch_metadata(epoch_metadata_key, None)
+
+        if accumulated_ddx != Decimal("0"):
+            total_distributed_fees = Decimal("0")
+            distro_per_custodian = accumulated_ddx / Decimal(str(len(self.custodians)))
+
+            for custodian in self.custodians:
+                trader_key: TraderKey = TraderKey(custodian)
+                trader = smt.trader(trader_key)
+                if trader is None:
+                    # Initialize a new Trader Leaf
+                    trader = Trader.default()
+
+                old_balance = trader.avail_ddx_balance
+                trader.avail_ddx_balance = (
+                    old_balance + distro_per_custodian
+                ).recorded_amount()
+                if trader.avail_ddx_balance != old_balance:
+                    smt.store_trader(trader_key, trader)
+
+                    total_distributed_fees += trader.avail_ddx_balance - old_balance
+
+            dust = accumulated_ddx - total_distributed_fees
+
+            trader_key: TraderKey = TraderKey(self.submitter)
+            trader = smt.trader(trader_key)
+            if trader is None:
+                # Initialize a new Trader Leaf
+                trader = Trader.default()
+
+            old_balance = trader.avail_ddx_balance
+            trader.avail_ddx_balance += dust
+
+            if trader.avail_ddx_balance != old_balance:
+                smt.store_trader(trader_key, trader)

ddx/common/transactions/funding.py

@@ -0,0 +1,294 @@
+"""
+Funding module
+"""
+
+import logging
+from typing import Optional
+
+import numpy as np
+from attrs import define, field
+from ddx.common.item_utils import update_avail_collateral
+from ddx.common.transaction_utils import get_prices_for_symbol_and_duration
+from ddx.common.transactions.cancel import Cancel
+from ddx.common.transactions.event import Event
+from ddx.common.transactions.inner.adl_outcome import AdlOutcome
+from ddx.common.transactions.inner.liquidated_position import LiquidatedPosition
+from ddx.common.transactions.inner.liquidation_entry import LiquidationEntry
+from ddx.common.transactions.inner.liquidation_fill import LiquidationFill
+from ddx.common.transactions.inner.outcome import Outcome
+from ddx.common.transactions.liquidation import Liquidation
+from ddx._rust.common import ProductSymbol, TokenSymbol
+from ddx._rust.common.enums import OrderSide, PositionSide
+from ddx._rust.common.state import DerivadexSMT
+from ddx._rust.common.state.keys import StrategyKey
+from ddx._rust.decimal import Decimal
+
+logger = logging.getLogger(__name__)
+
+
+def get_funding_rate(
+    smt: DerivadexSMT,
+    funding_period: int,
+    symbol: ProductSymbol,
+) -> Optional[Decimal]:
+    """
+    Get the projected funding rate for the upcoming funding
+    distribution pay period for a given symbol
+
+    Parameters
+    ----------
+    smt: DerivadexSMT
+        DerivaDEX Sparse Merkle Tree
+    funding_period : int
+        Funding period for retrieving price leaves
+    symbol : str
+        Market symbol
+    """
+
+    if not symbol.is_perpetual():
+        return None
+
+    # Get price leaves for symbol
+    prices = get_prices_for_symbol_and_duration(smt, symbol, funding_period)
+    logger.debug(f"Last {funding_period} price leaves: {prices}")
+
+    # Compute average premium rate across all price checkpoints
+    avg_premium_rate = np.mean(
+        [
+            price_value.mark_price_metadata.ema / price_value.index_price
+            for _, price_value in prices
+        ]
+    )
+
+    # Any values between [-0.0005, 0.0005] => 0
+    unclamped_funding_rate = max(Decimal("0.0005"), avg_premium_rate) + min(
+        Decimal("-0.0005"), avg_premium_rate
+    )
+
+    # Cap the funding rate bounds to [-0.005, 0.005]
+    return min(Decimal("0.005"), max(Decimal("-0.005"), unclamped_funding_rate))
+
+
+@define
+class Funding(Event):
+    """
+    Defines a Funding
+
+    A Funding is when a there is a funding rate distribution.
+
+    Attributes:
+        settlement_epoch_id (int): The epoch id for the funding event.
+        liquidation (Liquidation): Liquidations
+        time_value (int): Time value
+        request_index (int): Sequenced request index of transaction
+    """
+
+    settlement_epoch_id: int
+    liquidation: Liquidation
+    time_value: int
+    request_index: int = field(default=-1, eq=False)
+
+    @classmethod
+    def decode_value_into_cls(cls, raw_tx_log_event: dict):
+        """
+        Decode a raw transaction log event (dict) into a Funding
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        funding_tx_event = raw_tx_log_event["event"]["c"]
+        liquidation_tx_event = funding_tx_event["liquidations"]
+
+        return cls(
+            funding_tx_event["settlementEpochId"],
+            Liquidation(
+                [
+                    LiquidationEntry(
+                        liquidation_entry["traderAddress"],
+                        liquidation_entry["strategyIdHash"],
+                        [
+                            Cancel(
+                                ProductSymbol(canceled_order["symbol"]),
+                                canceled_order["orderHash"],
+                                Decimal(canceled_order["amount"]),
+                                raw_tx_log_event["requestIndex"],
+                            )
+                            for canceled_order in liquidation_entry["canceledOrders"]
+                        ],
+                        [
+                            (
+                                ProductSymbol(liquidated_position_key),
+                                LiquidatedPosition(
+                                    Decimal(liquidated_position_val["amount"]),
+                                    [
+                                        (
+                                            LiquidationFill(
+                                                ProductSymbol(
+                                                    trade_outcome["Fill"]["symbol"]
+                                                ),
+                                                trade_outcome["Fill"]["indexPriceHash"],
+                                                trade_outcome["Fill"]["makerOrderHash"],
+                                                Decimal(
+                                                    trade_outcome["Fill"][
+                                                        "makerOrderRemainingAmount"
+                                                    ]
+                                                ),
+                                                Decimal(
+                                                    trade_outcome["Fill"]["amount"]
+                                                ),
+                                                Decimal(trade_outcome["Fill"]["price"]),
+                                                OrderSide(
+                                                    trade_outcome["Fill"]["takerSide"]
+                                                ),
+                                                Outcome(
+                                                    trade_outcome["Fill"][
+                                                        "makerOutcome"
+                                                    ]["trader"],
+                                                    trade_outcome["Fill"][
+                                                        "makerOutcome"
+                                                    ]["strategyIdHash"],
+                                                ),
+                                                raw_tx_log_event["timeValue"],
+                                                raw_tx_log_event["requestIndex"],
+                                            )
+                                            if "Fill" in trade_outcome
+                                            else Cancel(
+                                                ProductSymbol(
+                                                    trade_outcome["Cancel"]["symbol"]
+                                                ),
+                                                trade_outcome["Cancel"]["orderHash"],
+                                                Decimal(
+                                                    trade_outcome["Cancel"]["amount"]
+                                                ),
+                                                raw_tx_log_event["requestIndex"],
+                                            )
+                                        )
+                                        for trade_outcome in liquidated_position_val[
+                                            "tradeOutcomes"
+                                        ]
+                                    ],
+                                    [
+                                        AdlOutcome(
+                                            adl_outcome["traderAddress"],
+                                            adl_outcome["strategyIdHash"],
+                                            raw_tx_log_event["requestIndex"],
+                                        )
+                                        for adl_outcome in liquidated_position_val[
+                                            "adlOutcomes"
+                                        ]
+                                    ],
+                                    Decimal(
+                                        liquidated_position_val["newInsuranceFundCap"]
+                                    ),
+                                    raw_tx_log_event["requestIndex"],
+                                ),
+                            )
+                            for (
+                                liquidated_position_key,
+                                liquidated_position_val,
+                            ) in liquidation_entry["positions"]
+                        ],
+                        raw_tx_log_event["requestIndex"],
+                    )
+                    for liquidation_entry in liquidation_tx_event
+                ],
+                raw_tx_log_event["requestIndex"],
+            ),
+            raw_tx_log_event["timeValue"],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a Funding transaction. A Funding event consists of
+        consists of information relating to funding rate-related
+        distributions. All open positions will result in traders
+        either paying or receiving a USDC debit/credit to their
+        avaiable collateral as a function of the funding rate (given the
+        Price leaves in the SMT at this time) and their
+        position notional (given the latest mark price).
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to Funding transactions
+        """
+
+        funding_strategies = {}
+
+        # Loop through the funding rate symbols and values as specified
+        # in the transaction
+        for funding_rate_symbol in sorted(kwargs["latest_price_leaves"]):
+            funding_rate = get_funding_rate(
+                smt, kwargs["funding_period"], funding_rate_symbol
+            )
+
+            if funding_rate is not None and funding_rate != Decimal("0"):
+                # If funding rate is non-zero, handle funding payments
+
+                # Obtain latest mark price
+                mark_price = kwargs["latest_price_leaves"][funding_rate_symbol][
+                    1
+                ].mark_price
+
+                # Loop through each open position
+                for (
+                    position_key,
+                    position,
+                ) in smt.all_positions_for_symbol(funding_rate_symbol):
+                    # Compute the funding payment for the trader. When
+                    # the funding rate is positive, long traders will
+                    # pay and short traders will receive payments. When
+                    # the funding rate is negative, long traders will
+                    # receive payments and short traders will pay.
+                    funding_delta = (
+                        (
+                            Decimal("-1.0")
+                            if position.side == PositionSide.Long
+                            else Decimal("1.0")
+                        )
+                        * funding_rate
+                        * position.balance
+                        * mark_price
+                    )
+
+                    # Construct a StrategyKey and corresponding encoded
+                    # key
+                    strategy_key: StrategyKey = position_key.as_strategy_key()
+
+                    funding_strategies[strategy_key] = (
+                        funding_strategies[strategy_key] + funding_delta
+                        if strategy_key in funding_strategies
+                        else funding_delta
+                    )
+
+        for strategy_key, funding_delta in funding_strategies.items():
+            strategy = smt.strategy(strategy_key)
+
+            # Credit/debit the trader's Strategy leaf by the
+            # funding delta from above
+            update_avail_collateral(
+                strategy,
+                TokenSymbol.USDC,
+                strategy.avail_collateral[TokenSymbol.USDC] + funding_delta,
+            )
+
+            # Update the SMT with the H256 repr of the key and
+            # the Strategy leaf
+            smt.store_strategy(
+                strategy_key,
+                strategy,
+            )
+
+        # Process liquidation
+        self.liquidation.process_tx(smt, **kwargs)

ddx/common/transactions/futures_expiry.py

@@ -0,0 +1,123 @@
+"""
+FuturesExpiry module
+"""
+
+from typing import Optional
+
+import numpy as np
+from attrs import define, field
+from ddx.common.logging import auditor_logger
+from ddx.common.transaction_utils import get_prices_for_symbol_and_duration
+from ddx.common.transactions.cancel import Cancel
+from ddx.common.transactions.event import Event
+from ddx.common.transactions.inner.adl_outcome import AdlOutcome
+from ddx.common.transactions.inner.liquidated_position import LiquidatedPosition
+from ddx.common.transactions.inner.liquidation_entry import LiquidationEntry
+from ddx.common.transactions.inner.outcome import Outcome
+from ddx.common.transactions.liquidation import Liquidation
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.enums import OrderSide
+from ddx._rust.common.specs import Quarter
+from ddx._rust.common.state import DerivadexSMT, Position
+from ddx._rust.common.state.keys import PositionKey, StrategyKey
+from ddx._rust.decimal import Decimal
+
+logger = auditor_logger(__name__)
+
+
+@define(hash=True)
+class FuturesExpiry(Event):
+    """
+    Defines a FuturesExpiry
+
+    A FuturesExpiry is when all futures of a fixed duration expire.
+    This will result in a credit/debit for all strategies.
+
+    Attributes:
+        settlement_epoch_id (int): Settlement epoch id
+        quarter (Quarter): Quarter of the futures expired
+        time_value (int): Time value
+        request_index (int): Sequenced request index of transaction
+    """
+
+    settlement_epoch_id: int
+    quarter: Quarter
+    time_value: int
+    request_index: int = field(default=-1, eq=False, hash=False)
+
+    @classmethod
+    def decode_value_into_cls(cls, raw_tx_log_event: dict):
+        """
+        Decode a raw transaction log event (dict) into a FuturesExpiry
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        futures_expiry_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            futures_expiry_tx_event["settlementEpochId"],
+            Quarter(futures_expiry_tx_event["quarter"]),
+            raw_tx_log_event["timeValue"],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a FuturesExpiry transaction. A FuturesExpiry event
+        consists of information relating to when unrealized pnl is
+        settled/realized for all traders' strategies. This will result
+        in a credit/debit for all strategies. Furthermore, the
+        average entry price for any open positions will be set to the
+        current mark price.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to FuturesExpiry transactions
+        """
+
+        # Close all open orders
+        book_order_leaves: list[tuple[BookOrderKey, BookOrder]] = [
+            (book_order_key, book_order)
+            for book_order_key, book_order in smt.all_book_orders()
+            if (quarter := book_order_key.symbol.futures_quarter()) is not None
+            and quarter == self.quarter
+        ]
+
+        for book_order_key, book_order in book_order_leaves:
+            cancel = Cancel(
+                book_order_key.symbol,
+                book_order_key.order_hash,
+                book_order.amount,
+                self.request_index,
+            )
+            cancel.process_tx(smt)
+
+        # Close all open positions for the expiring quarter
+        relevant_positions: list[tuple[PositionKey, Position]] = [
+            (position_key, position)
+            for position_key, position in sorted(
+                smt.all_positions(),
+                key=lambda item: item[0].symbol,
+            )
+            if (quarter := position_key.symbol.futures_quarter()) is not None
+            and quarter == self.quarter
+        ]
+
+        for position_key, position in relevant_positions:
+            # Set position balances to zero
+            position.balance = Decimal(0)
+
+            # Store the position
+            smt.store_position(position_key, position)

ddx/common/transactions/genesis.py

@@ -0,0 +1,108 @@
+"""
+Genesis module
+"""
+
+from typing import Optional
+
+from attrs import define, field
+from ddx.common.logging import auditor_logger
+from ddx.common.transactions.event import Event
+from ddx._rust.common.specs import SpecsKind
+from ddx._rust.common.state import Balance, DerivadexSMT
+from ddx._rust.common.state.keys import InsuranceFundKey, SpecsKey
+from ddx._rust.decimal import Decimal
+
+logger = auditor_logger(__name__)
+
+
+@define
+class Genesis(Event):
+    """
+    Defines a Genesis
+
+    A Genesis is a non-transitioning transaction that indicates
+    the start of the first epoch.
+
+    Attributes:
+        state_root_hash (str): State root hash at time of marker
+        request_index (int): Sequenced request index of transaction
+    """
+
+    state_root_hash: Optional[str] = field(eq=str.lower)
+    request_index: int = field(default=-1, eq=False)
+
+    @classmethod
+    def decode_value_into_cls(cls, raw_tx_log_event: dict):
+        """
+        Decode a raw transaction log event (dict) into a Genesis
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        genesis_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            genesis_tx_event.get("stateRootHash"),
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        **kwargs,
+    ):
+        """
+        Process an EpochMarker transaction of type Genesis. This
+        indicates the very first event in the transaction log, although
+        it is not state-transitioning in the way typical transactions
+        are.
+
+        Parameters
+        ----------
+        **kwargs
+            Additional args specific to Genesis transactions
+        """
+
+        if (
+            collaterals := kwargs["genesis_params"]["Genesis"].get("insuranceFundCap")
+        ) is not None:
+            insurance_fund_balance = Balance.new_from_many(collaterals)
+        else:
+            insurance_fund_balance = Balance.default()
+
+        ddx_fee_pool = kwargs["genesis_params"]["Genesis"].get("ddxFeePool")
+        if ddx_fee_pool is None:
+            ddx_fee_pool = Decimal("0")
+
+        specs = {}
+        for key, val in kwargs["genesis_params"]["Genesis"]["specs"].items():
+            if key.startswith("SINGLENAMEPERP"):
+                kind = SpecsKind.SingleNamePerpetual
+            elif key.startswith("INDEXFUNDPERP"):
+                kind = SpecsKind.IndexFundPerpetual
+            elif key.startswith("QUARTERLYEXPIRYFUTURE"):
+                kind = SpecsKind.QuarterlyExpiryFuture
+            elif key.startswith("GATEWAY"):
+                kind = SpecsKind.MarketGateway
+            else:
+                raise Exception("Invalid spec in Genesis params")
+
+            specs[SpecsKey(kind, key.split("-")[1])] = val
+
+        logger.info(
+            f"Initializing SMT from genesis:\n\tInsurance fund: {insurance_fund_balance}\n\tDDX fee pool: {ddx_fee_pool}\n\tSpecs: {specs}\n\tCurrent datetime: {kwargs['current_time']}"
+        )
+        smt = DerivadexSMT.from_genesis(
+            insurance_fund_balance, ddx_fee_pool, specs, kwargs["current_time"]
+        )
+        kwargs["smt"](kwargs["auditor_instance"], smt)
+
+        # Set the expected epoch ID to be 1 and the expected tx ordinal
+        # to be -1, because we immediately increment this by 1, thus
+        # setting it to 0, which will be the first tx ordinal of the
+        # next epoch
+        kwargs["expected_epoch_id"](kwargs["auditor_instance"], 1)
+        kwargs["expected_tx_ordinal"](kwargs["auditor_instance"], -1)

ddx/common/transactions/inner/adl_outcome.py

@@ -0,0 +1,25 @@
+"""
+AdlOutcome module
+"""
+
+from attrs import define, field
+from ddx._rust.decimal import Decimal
+
+
+@define(hash=True)
+class AdlOutcome:
+    """
+    Defines an AdlOutcome
+
+    An AdlOutcome is a scenario where a strategy has been auto-deleveraged
+    due to a liquidation.
+
+    Attributes:
+        trader_address (str): Auto-deleveraged trader's ethereum address
+        strategy_id_hash (str): Auto-deleveraged strategy ID hash
+        request_index (int): Sequenced request index of transaction
+    """
+
+    trader_address: str = field(eq=str.lower)
+    strategy_id_hash: str = field(eq=str.lower)
+    request_index: int = field(default=-1, eq=False, hash=False)