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

ddx/common/transactions/inner/fill.py

@@ -0,0 +1,227 @@
+"""
+Fill module
+"""
+
+import logging
+from enum import Enum
+from typing import Optional
+
+from attrs import define, field
+from ddx.common.fill_context import (MAX_DDX_PRICE_CHECKPOINT_AGE_IN_TICKS,
+                                 FillContext, apply_trade)
+from ddx.common.transaction_utils import get_most_recent_price
+from ddx.common.transactions.event import Event
+from ddx.common.transactions.inner.outcome import Outcome
+from ddx._rust.common import ProductSymbol, TokenSymbol
+from ddx._rust.common.enums import OrderSide, TradeSide
+from ddx._rust.common.state import (DerivadexSMT, InsuranceFund, Position,
+                                     Price, Stats)
+from ddx._rust.common.state.keys import (EpochMetadataKey, InsuranceFundKey,
+                                          PositionKey, PriceKey, StatsKey,
+                                          StrategyKey, TraderKey)
+from ddx._rust.decimal import Decimal
+
+logger = logging.getLogger(__name__)
+
+
+@define(hash=True)
+class Fill(Event):
+    """
+    Defines a Fill
+    """
+
+    symbol: ProductSymbol
+    amount: Decimal = field(hash=False)
+    price: Decimal = field(hash=False)
+    taker_side: OrderSide = field(hash=False)
+    time_value: int
+    request_index: int = field(eq=False, hash=False)
+
+    def adjust_for_maker_taker(
+        self,
+        smt: DerivadexSMT,
+        epoch_id: int,
+        is_maker: bool,
+        outcome: Outcome,
+        trade_mining_active: bool = False,
+        maker_book_order_time_value: Optional[int] = None,
+    ):
+        """
+        Make some adjustments to the SMT based on whether we are
+        considering the maker or the taker component of the Trade.
+        In this method, we will be adjusting the the Strategy,
+        Position, and Stats leaves.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        epoch_id: int
+            Epoch ID used for recording fees if any
+        is_maker : bool
+            Whether outcome is for the maker or taker
+        outcome: Outcome
+            Outcome to adjust
+        trade_mining_active : bool
+            Whether trade mining is active
+        maker_book_order_time_value: Optional[int]
+            Maker book order time value
+        """
+
+        context = FillContext(outcome)
+
+        position_key: PositionKey = PositionKey(
+            outcome.trader,
+            outcome.strategy_id_hash,
+            self.symbol,
+        )
+
+        position: Optional[Position] = smt.position(position_key)
+
+        position = context.apply_fill(
+            position,
+            (
+                (OrderSide.Ask if self.taker_side == OrderSide.Bid else OrderSide.Bid)
+                if is_maker
+                else self.taker_side
+            ),
+            (TradeSide.Maker if is_maker else TradeSide.Taker),
+            self.amount,
+            self.price,
+        )
+        smt.store_position(
+            position_key,
+            position,
+        )
+
+        trader_key: TraderKey = TraderKey(outcome.trader)
+        trader = smt.trader(trader_key)
+
+        if outcome.fee > Decimal("0") and trader.pay_fees_in_ddx:
+            # Gets the most recent DDX price within MAX_DDX_PRICE_CHECKPOINT_AGE_IN_TICKS
+            _, recent_ddx_price = get_most_recent_price(
+                smt, ProductSymbol("DDXP"), self.time_value
+            )
+            if (
+                recent_ddx_price.time_value
+                >= self.time_value - MAX_DDX_PRICE_CHECKPOINT_AGE_IN_TICKS
+            ):
+                if context.apply_ddx_fee_and_mutate_trader(
+                    trader, recent_ddx_price.index_price
+                ):
+                    smt.store_trader(trader_key, trader)
+            else:
+                raise Exception(
+                    "DDX fee election enabled but no DDX price checkpoint within the max age was found, should have been caught by the operator"
+                )
+
+        strategy_key: StrategyKey = position_key.as_strategy_key()
+        strategy = smt.strategy(strategy_key)
+        context.realize_trade_and_mutate_strategy(strategy)
+        smt.store_strategy(strategy_key, strategy)
+
+        if outcome.fee > Decimal("0"):
+            if outcome.pay_fee_in_ddx:
+                logger.info(f"Fee of {outcome.fee} DDX to be paid")
+                epoch_metadata_key: EpochMetadataKey = EpochMetadataKey(epoch_id)
+                epoch_metadata = smt.epoch_metadata(epoch_metadata_key)
+                epoch_metadata.ddx_fee_pool = (
+                    epoch_metadata.ddx_fee_pool + outcome.fee
+                ).recorded_amount()
+                smt.store_epoch_metadata(epoch_metadata_key, epoch_metadata)
+            else:
+                logger.info(f"Fee of {outcome.fee} USDC to be paid")
+                insurance_fund_key: InsuranceFundKey = InsuranceFundKey()
+                insurance_fund = smt.insurance_fund(insurance_fund_key)
+                insurance_fund[TokenSymbol.USDC] += outcome.fee
+                smt.store_insurance_fund(insurance_fund_key, insurance_fund)
+
+        if (
+            trade_mining_active
+            and maker_book_order_time_value
+            and self.time_value > maker_book_order_time_value + 1
+        ):
+            stats_key: StatsKey = StatsKey(outcome.trader)
+            stats = smt.stats(stats_key)
+            notional_amount = self.amount * self.price
+            if stats is None:
+                # If Stats leaf doesn't exist in the tree, we need
+                # to create/add a new one
+                if is_maker:
+                    # Initialize the trader's maker volume
+                    stats = Stats(notional_amount, Decimal("0"))
+                else:
+                    # Initialize the trader's taker volume
+                    stats = Stats(Decimal("0"), notional_amount)
+            else:
+                # If Stats leaf does exist, we update the existing leaf
+                if is_maker:
+                    # Increment the trader's maker volume
+                    stats.maker_volume += notional_amount
+                else:
+                    # Increment the trader's taker volume
+                    stats.taker_volume += notional_amount
+
+            smt.store_stats(stats_key, stats)
+
+    def adjust_for_maker(
+        self,
+        smt: DerivadexSMT,
+        epoch_id: int,
+        trade_mining_active: bool = False,
+        maker_book_order_time_value: Optional[int] = None,
+    ):
+        """
+        Make some adjustments to the SMT based on the maker side
+        of the Trade.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        epoch_id: int
+            Epoch ID used for recording fees if any
+        trade_mining_active : bool
+            Whether trade mining is active
+        maker_book_order_time_value: Optional[int]
+            Maker book order time value
+        """
+        self.adjust_for_maker_taker(
+            smt,
+            epoch_id,
+            True,
+            self.maker_outcome,
+            trade_mining_active,
+            maker_book_order_time_value,
+        )
+
+    def adjust_for_taker(
+        self,
+        smt: DerivadexSMT,
+        epoch_id: int,
+        trade_mining_active: bool = False,
+        maker_book_order_time_value: Optional[int] = None,
+    ):
+        """
+        Make some adjustments to the SMT based on the taker side
+        of the Trade.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        epoch_id: int
+            Epoch ID used for recording fees if any
+        maker_book_order_time_value: int
+            Maker book order time value
+        trade_mining_active : bool
+            Whether trade mining is active
+        """
+        self.adjust_for_maker_taker(
+            smt,
+            epoch_id,
+            False,
+            self.taker_outcome,
+            trade_mining_active,
+            maker_book_order_time_value,
+        )

ddx/common/transactions/inner/liquidated_position.py

@@ -0,0 +1,41 @@
+"""
+LiquidatedPosition module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.cancel import Cancel
+from ddx.common.transactions.inner.adl_outcome import AdlOutcome
+from ddx.common.transactions.inner.liquidation_fill import LiquidationFill
+from ddx._rust.decimal import Decimal
+
+
+@define
+class LiquidatedPosition:
+    """
+    Defines a LiquidatedPosition
+
+    A LiquidatedPosition has data pertaining to a liquidated position.
+
+    Attributes:
+        amount (Decimal): Liquidated balance amount
+        trade_outcomes (list[LiquidationFill | Cancel]): A list of trade outcome objects
+        adl_outcomes (list[AdlOutcome]): Positions that were ADL'd as a result of the liquidation
+        new_insurance_fund_cap (Decimal): Insurance fund capitalization after the liquidation
+        request_index (int): Sequenced request index of transaction
+    """
+
+    amount: Decimal
+    trade_outcomes: list[LiquidationFill | Cancel] = field(eq=set)
+    adl_outcomes: list[AdlOutcome] = field(eq=set)
+    new_insurance_fund_cap: Decimal
+    request_index: int = field(default=-1, eq=False)
+
+    def __hash__(self):
+        return hash(
+            (
+                self.amount,
+                frozenset(self.trade_outcomes),
+                frozenset(self.adl_outcomes),
+                self.new_insurance_fund_cap,
+            )
+        )

ddx/common/transactions/inner/liquidation_entry.py

@@ -0,0 +1,41 @@
+"""
+LiquidationEntry module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.cancel import Cancel
+from ddx.common.transactions.inner.liquidated_position import LiquidatedPosition
+from ddx._rust.common import ProductSymbol
+
+
+@define
+class LiquidationEntry:
+    """
+    Defines a LiquidationEntry
+
+    A LiquidationEntry contains data pertaining to individual trader and
+    strategy liquidations.
+
+    Attributes:
+        trader_address (str): Liquidated trader's Ethereum address
+        strategy_id_hash (str): Liquidated strategy ID hash
+        canceled_orders (list[Cancel]): Canceled orders for liquidated trader
+        positions (list[tuple[str, LiquidatedPosition]]): Contains information pertaining to individual liquidated positions by symbol
+        request_index (int): Sequenced request index of transaction
+    """
+
+    trader_address: str = field(eq=str.lower)
+    strategy_id_hash: str = field(eq=str.lower)
+    canceled_orders: list[Cancel] = field(eq=set)
+    positions: list[tuple[ProductSymbol, LiquidatedPosition]] = field(eq=set)
+    request_index: int = field(default=-1, eq=False)
+
+    def __hash__(self):
+        return hash(
+            (
+                self.trader_address,
+                self.strategy_id_hash,
+                frozenset(self.canceled_orders),
+                frozenset(self.positions),
+            )
+        )

ddx/common/transactions/inner/liquidation_fill.py

@@ -0,0 +1,118 @@
+"""
+LiquidationFill module
+"""
+
+import logging
+
+from attrs import define, field
+from ddx.common.transactions.inner.fill import Fill
+from ddx.common.transactions.inner.outcome import Outcome
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.enums import OrderSide
+from ddx._rust.common.state import DerivadexSMT
+from ddx._rust.common.state.keys import BookOrderKey
+from ddx._rust.decimal import Decimal
+
+logger = logging.getLogger(__name__)
+
+
+@define(hash=True)
+class LiquidationFill(Fill):
+    """
+    Defines a LiquidationFill
+    """
+
+    maker_order_hash: str = field(eq=str.lower)
+    maker_outcome: Outcome = field(hash=False)
+    maker_order_remaining_amount: Decimal = field(hash=False)
+    index_price_hash: str = field(eq=str.lower)
+    request_index: int = field(default=-1, eq=False, hash=False)
+
+    def __init__(
+        self,
+        symbol: ProductSymbol,
+        index_price_hash: str,
+        maker_order_hash: str,
+        maker_order_remaining_amount: Decimal,
+        amount: Decimal,
+        price: Decimal,
+        taker_side: OrderSide,
+        maker_outcome: Outcome,
+        time_value: int,
+        request_index: int = -1,
+    ):
+        """
+        Initialize a LiquidationFill instance
+        Parameters
+        ----------
+        symbol : ProductSymbol
+            Product symbol
+        index_price_hash : str
+            Index price hash
+        maker_order_hash : str
+            Maker order hash
+        maker_order_remaining_amount : Decimal
+            Maker order remaining amount
+        amount : Decimal
+            Amount
+        price : Decimal
+            Price
+        taker_side : OrderSide
+            Taker side
+        maker_outcome : Outcome
+            Maker outcome
+        time_value : int
+            Time value
+        request_index : int
+            Request index
+        """
+        super().__init__(
+            symbol,
+            amount,
+            price,
+            taker_side,
+            time_value,
+            request_index,
+        )
+        self.maker_order_hash = maker_order_hash
+        self.maker_outcome = maker_outcome
+        self.maker_order_remaining_amount = maker_order_remaining_amount
+        self.index_price_hash = index_price_hash
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a LiquidationFill transaction. These are Fill
+        transactions that have risen from either a Liquidation.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to Liquidation transactions
+        """
+
+        maker_book_order_key: BookOrderKey = BookOrderKey(
+            self.symbol, self.maker_order_hash
+        )
+
+        maker_book_order = smt.book_order(maker_book_order_key)
+        maker_book_order_time_value = maker_book_order.time_value
+
+        maker_book_order.amount = self.maker_order_remaining_amount
+        smt.store_book_order(maker_book_order_key, maker_book_order)
+
+        # Adjust the maker-related position. Take note that
+        # in a liquidation, there is no taker component, so
+        # unlike its counterpart (TradeFill), a
+        # LiquidationFill only considers the maker
+        self.adjust_for_maker(
+            smt,
+            kwargs["epoch_id"],
+            kwargs["trade_mining_active"],
+            maker_book_order_time_value,
+        )

ddx/common/transactions/inner/outcome.py

@@ -0,0 +1,32 @@
+"""
+Outcome module
+"""
+
+from typing import Optional
+
+from attrs import define, field
+from ddx._rust.decimal import Decimal
+
+
+@define(hash=True)
+class Outcome:
+    """
+    Defines a Outcome
+
+    An Outcome is a part of a Fill transaction. It holds information
+    including the fees paid, the strategy ID and trader address, and
+    whether fees are being paid in DDX or not (i.e. USDC).
+
+    Attributes:
+        trader (str): Trader's Ethereum address
+        strategy_id_hash (str): Strategy ID hash
+        fee (Decimal): Fees paid for filled trade
+        pay_fee_in_ddx (bool): Whether the trader has elected to pay the fee in DDX
+    """
+
+    trader: str = field(eq=str.lower, default="")
+    strategy_id_hash: str = field(eq=str.lower, default="")
+    # The below fields do not exist in the txlog (and thus are not checked in transaction
+    # equality), and are only used when executing/processing transactions.
+    fee: Optional[Decimal] = field(eq=False, default=None)
+    pay_fee_in_ddx: Optional[bool] = field(eq=False, default=None)

ddx/common/transactions/inner/trade_fill.py

@@ -0,0 +1,125 @@
+"""
+TradeFill module
+"""
+
+import asyncio
+
+from attrs import define, field
+from ddx.common.transactions.inner.fill import Fill
+from ddx.common.transactions.inner.outcome import Outcome
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.enums import OrderSide
+from ddx._rust.common.state import DerivadexSMT, Price
+from ddx._rust.common.state.keys import BookOrderKey, PriceKey
+from ddx._rust.decimal import Decimal
+
+
+@define(hash=True)
+class TradeFill(Fill):
+    """
+    Defines a TradeFill
+    """
+
+    maker_order_hash: str = field(eq=str.lower)
+    maker_outcome: Outcome = field(hash=False)
+    maker_order_remaining_amount: Decimal = field(hash=False)
+    taker_order_hash: str = field(eq=str.lower)
+    taker_outcome: Outcome = field(hash=False)
+    request_index: int = field(default=-1, eq=False, hash=False)
+
+    def __init__(
+        self,
+        symbol: ProductSymbol,
+        taker_order_hash: str,
+        maker_order_hash: str,
+        maker_order_remaining_amount: Decimal,
+        amount: Decimal,
+        price: Decimal,
+        taker_side: OrderSide,
+        maker_outcome: Outcome,
+        taker_outcome: Outcome,
+        time_value: int,
+        request_index: int = -1,
+    ):
+        """
+        Initialize a TradeFill instance
+        Parameters
+        ----------
+        symbol : ProductSymbol
+            Product symbol
+        taker_order_hash : str
+            Taker order hash
+        maker_order_hash : str
+            Maker order hash
+        maker_order_remaining_amount : Decimal
+            Maker order remaining amount
+        amount : Decimal
+            Amount
+        price : Decimal
+            Price
+        taker_side : OrderSide
+            Taker side
+        maker_outcome : Outcome
+            Maker outcome
+        taker_outcome : Outcome
+            Taker outcome
+        time_value : int
+            Time value
+        request_index : int
+            Request index
+        """
+        super().__init__(
+            symbol,
+            amount,
+            price,
+            taker_side,
+            time_value,
+            request_index,
+        )
+        self.maker_order_hash = maker_order_hash
+        self.maker_outcome = maker_outcome
+        self.maker_order_remaining_amount = maker_order_remaining_amount
+        self.taker_order_hash = taker_order_hash
+        self.taker_outcome = taker_outcome
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a TradeFill transaction. These are Fill transactions
+        that have risen from either a CompleteFill or a PartialFill
+        transaction.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to CompleteFill/PartialFill transactions
+        """
+
+        maker_book_order_key: BookOrderKey = BookOrderKey(
+            self.symbol, self.maker_order_hash
+        )
+        maker_book_order = smt.book_order(maker_book_order_key)
+        maker_book_order_time_value = maker_book_order.time_value
+
+        maker_book_order.amount = self.maker_order_remaining_amount
+        smt.store_book_order(maker_book_order_key, maker_book_order)
+
+        # Make the appropriate adjustments for both the maker and taker
+        # components of the Trade
+        self.adjust_for_maker(
+            smt,
+            kwargs["epoch_id"],
+            kwargs["trade_mining_active"],
+            maker_book_order_time_value,
+        )
+        self.adjust_for_taker(
+            smt,
+            kwargs["epoch_id"],
+            kwargs["trade_mining_active"],
+            maker_book_order_time_value,
+        )