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

ddx/common/transactions/disaster_recovery.py

@@ -0,0 +1,96 @@
+"""
+DisasterRecovery module
+"""
+
+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
+from ddx._rust.common.state.keys import StrategyKey
+from ddx._rust.decimal import Decimal
+
+
+@define
+class DisasterRecovery(Event):
+    """
+    Defines a DisasterRecovery
+
+    A DisasterRecovery is when the system is wound down in an extreme recovery scenario.
+
+    Attributes:
+        request_index (int): Sequenced request index of transaction
+    """
+
+    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 DisasterRecovery
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        return cls(
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a DisasterRecovery transaction.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to DisasterRecovery transactions
+        """
+
+        raise NotImplementedError()
+
+        # sorted_positions = sorted(
+        #     smt.all_positions(),
+        #     key=lambda item: item[1].unrealized_pnl(
+        #         kwargs["latest_price_leaves"][item[0].symbol][1].mark_price
+        #     ),
+        #     reverse=True,
+        # )
+        #
+        # for position_key, position in sorted_positions:
+        #     unrealized_pnl = position.unrealized_pnl(
+        #         kwargs["latest_price_leaves"][position_key.symbol][1].mark_price
+        #     )
+        #
+        #     strategy_key: StrategyKey = position_key.as_strategy_key()
+        #     # Get the Strategy leaf given the key from above
+        #     strategy = smt.strategy(strategy_key)
+        #
+        #     # Credit/debit the trader's Strategy leaf by the
+        #     # unrealized PNL to settle
+        #     update_avail_collateral(
+        #         strategy,
+        #         TokenSymbol.USDC,
+        #         strategy.avail_collateral[TokenSymbol.USDC] + unrealized_pnl,
+        #     )
+        #
+        #     smt.store_strategy(
+        #         strategy_key,
+        #         strategy,
+        #     )
+        #
+        #     smt.store_position(
+        #         position_key,
+        #         None,
+        #     )
+        #
+        # for book_order_key, _ in smt.all_book_orders():
+        #     smt.store_book_order_by_key(book_order_key, None)

ddx/common/transactions/event.py

@@ -0,0 +1,48 @@
+"""
+Event module
+"""
+
+from abc import ABC, abstractmethod
+
+from ddx._rust.common.state import DerivadexSMT
+
+
+class Event(ABC):
+    """
+    An Event class from which all Transaction classes inherit
+    """
+
+    @classmethod
+    def decode_value_into_cls(cls, raw_tx_log_event: dict):
+        """
+        Decode a raw transaction log event (dict) into an instance of
+        the class.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        raise NotImplementedError()
+
+    @abstractmethod
+    def process_tx(self, smt: DerivadexSMT, **kwargs):
+        """
+        Process transaction log event by modifying the SMT state
+        and emitting any corresponding events to the Trader when
+        appropriate.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        trader_auditor_queue : asyncio.Queue
+            Queue for sending events from the Auditor to the Trader
+        suppress_trader_queue: bool
+            Suppress trader queue messages
+        **kwargs
+            Additional args specific to various transaction types
+        """
+
+        raise NotImplementedError()

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,292 @@
+"""
+Funding module
+"""
+
+import logging
+from typing import Optional
+
+import numpy as np
+from attrs import define, field
+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
+            strategy.set_avail_collateral(
+                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)