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

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
+        """
+
+        insurance_fund_balance = Balance.default()
+        ddx_fee_pool = Decimal("0")
+
+        specs = {}
+        for key, val in kwargs["genesis_params"]["specs"].items():
+            if key.startswith("SINGLENAMEPERP"):
+                kind = SpecsKind.SingleNamePerpetual
+            elif key.startswith("INDEXFUNDPERP"):
+                kind = SpecsKind.IndexFundPerpetual
+            elif key.startswith("BINARYFUTURE"):
+                kind = SpecsKind.BinaryPredictionFuture
+            elif key.startswith("QUARTERLYFUTURE"):
+                kind = SpecsKind.QuarterlyExpiryFuture
+            elif key.startswith("SPOTGATEWAY"):
+                kind = SpecsKind.SpotGateway
+            elif key.startswith("SPOTINDEX"):
+                kind = SpecsKind.SpotIndex
+            elif key.startswith("BINARYGATEWAY"):
+                kind = SpecsKind.BinaryPredictionGateway
+            elif key.startswith("BINARYINDEX"):
+                kind = SpecsKind.BinaryIndex
+            else:
+                raise Exception("Invalid spec in Genesis params")
+            # only split once to avoid splitting on the second dash
+            specs[SpecsKey(kind, key.split("-", 1)[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)

ddx/common/transactions/inner/fill.py

@@ -0,0 +1,232 @@
+"""
+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,
+        reconcile_fees: bool = True,
+    ):
+        """
+        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 reconcile_fees and 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,
+        reconcile_fees: bool = True,
+    ):
+        """
+        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,
+            reconcile_fees,
+        )
+
+    def adjust_for_taker(
+        self,
+        smt: DerivadexSMT,
+        epoch_id: int,
+        trade_mining_active: bool = False,
+        maker_book_order_time_value: Optional[int] = None,
+        reconcile_fees: bool = True,
+    ):
+        """
+        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,
+            reconcile_fees,
+        )

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)