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

ddx/common/market_specs.py

@@ -0,0 +1,64 @@
+import logging
+
+import sexpdata
+from ddx._rust.common.specs import (
+    ProductSpecs,
+    QuarterlyExpiryFuture,
+    SingleNamePerpetual,
+    SpecsKind,
+)
+from ddx._rust.common.state.keys import SpecsKey
+
+logger = logging.getLogger(__name__)
+
+
+class MarketSpecs:
+    """
+    Defines the MarketSpecs of all symbols
+
+    Attributes:
+        market_specs: SpecsKey <> ProductSpecs
+    """
+
+    def __init__(self, genesis_params: dict):
+        self.market_specs = {}
+        for spec_key, spec in genesis_params["specs"].items():
+            if spec_key.startswith("SINGLENAMEPERP"):
+                spec_kind = SpecsKind.SingleNamePerpetual
+                spec_type = SingleNamePerpetual
+            elif spec_key.startswith("INDEXFUNDPERP"):
+                # TODO: implement this
+                # spec_kind = SpecsKind.IndexFundPerpetual
+                # spec_type = IndexFundPerpetual
+                raise NotImplementedError("IndexFundPerpetual is not implemented")
+            elif spec_key.startswith("QUARTERLYFUTURE"):
+                spec_kind = SpecsKind.QuarterlyExpiryFuture
+                spec_type = QuarterlyExpiryFuture
+            else:
+                continue
+            spec = sexpdata.loads(spec)
+            inner = spec_type(
+                **{
+                    str(k)[1:].replace("-", "_"): v
+                    for k, v in zip(spec[1::2], spec[2::2])
+                }
+            )
+            if isinstance(inner, SingleNamePerpetual):
+                product_specs = ProductSpecs.SingleNamePerpetual(inner)
+            elif isinstance(inner, QuarterlyExpiryFuture):
+                product_specs = ProductSpecs.QuarterlyExpiryFuture(inner)
+            else:
+                raise NotImplementedError("Unknown product specs type")
+            self.market_specs[SpecsKey(spec_kind, spec_key.split("-")[1])] = (
+                product_specs
+            )
+        logger.info(f"Loaded market specs: {self.market_specs}")
+
+    def __getitem__(self, specs_key: SpecsKey) -> ProductSpecs:
+        return self.market_specs[specs_key]
+
+    def keys(self):
+        return self.market_specs.keys()
+
+    def items(self):
+        return self.market_specs.items()

ddx/common/trade_mining_params.py

@@ -0,0 +1,19 @@
+from attrs import define, field
+from ddx._rust.decimal import Decimal
+
+
+@define
+class TradeMiningParams:
+    """
+    Defines the trade mining parameters determined at the start of a scenario
+    """
+
+    trade_mining_length: int
+    trade_mining_reward_per_epoch: Decimal
+    trade_mining_maker_reward_percentage: Decimal
+    trade_mining_taker_reward_percentage: Decimal = field(init=False)
+
+    def __attrs_post_init__(self):
+        self.trade_mining_taker_reward_percentage = (
+            Decimal("1") - self.trade_mining_maker_reward_percentage
+        )

ddx/common/transaction_utils.py

@@ -0,0 +1,85 @@
+import logging
+from typing import Optional
+
+from ddx.common.logging import auditor_logger
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.state import DerivadexSMT, Price
+from ddx._rust.common.state.keys import PriceKey
+from ddx._rust.decimal import Decimal
+from sortedcontainers import SortedKeyList
+
+logger = logging.getLogger(__name__)
+
+
+def get_prices_for_symbol_and_duration(
+    smt: DerivadexSMT,
+    symbol: ProductSymbol,
+    duration: int,
+) -> SortedKeyList:
+    """
+    Get Price leaves from SMT for a given market and a certain duration. This is used
+    internally when computing the funding rate since we need to
+    obtain all the Price leaves in the state to derive the
+    time-weighted average of the premium rate.
+
+    Parameters
+    ----------
+    smt: DerivadexSMT
+        DerivaDEX Sparse Merkle Tree
+    symbol : ProductSymbol
+        Market symbol
+    duration : int
+        Duration of lookback in ticks
+    """
+    logger.debug(f"Getting price leaves for {symbol} for the last {duration} ticks")
+
+    price_leaves = smt.all_prices_for_symbol(symbol)
+    logger.debug(f"All price leaves for {symbol}: {price_leaves}")
+    if not price_leaves:
+        return SortedKeyList()
+
+    sorted_price_leaves = SortedKeyList(key=lambda price: price[1].time_value)
+    for key, value in price_leaves:
+        sorted_price_leaves.add((key, value))
+
+    last_time_value = sorted_price_leaves[-1][1].time_value
+
+    bisect_time_value = max(last_time_value - duration, 0)
+    logger.debug(
+        f"Retrieving price leaves from within ticks [{bisect_time_value}, {last_time_value}]"
+    )
+    bisect_index = sorted_price_leaves.bisect_key_left(bisect_time_value)
+    logger.debug(f"Bisection index: {bisect_index}")
+
+    return sorted_price_leaves[bisect_index:]
+
+
+def get_most_recent_price(
+    smt: DerivadexSMT, symbol: ProductSymbol, time_value: int
+) -> Optional[tuple[PriceKey, Price]]:
+    """
+    Get the most recent Price leaf for a given market and time value.
+
+    Parameters
+    ----------
+    smt: DerivadexSMT
+        DerivaDEX Sparse Merkle Tree
+    symbol : ProductSymbol
+        Market symbol
+    time_value : int
+        Time value of reference
+    """
+
+    logger.debug(
+        f"Getting the most recent price for {symbol} at time value {time_value}"
+    )
+
+    price_leaves = smt.all_prices_for_symbol(symbol)
+    logger.debug(f"All price leaves for {symbol}: {price_leaves}")
+
+    # Find the most recent price leaf at or before time_value
+    return max(
+        filter(lambda price: price[1].time_value <= time_value, price_leaves),
+        key=lambda price: price[1].ordinal,
+        default=None,
+    )

ddx/common/transactions/advance_epoch.py

@@ -0,0 +1,91 @@
+"""
+AdvanceEpoch module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common import ProductSymbol, TokenSymbol
+from ddx._rust.common.state import DerivadexSMT, EpochMetadata
+from ddx._rust.common.state.keys import EpochMetadataKey
+from ddx._rust.decimal import Decimal
+
+
+@define
+class AdvanceEpoch(Event):
+    """
+    Defines an AdvanceEpoch
+
+    An AdvanceEpoch is a non-transitioning transaction that indicates
+    the start of a new epoch.
+
+    Attributes:
+        next_book_ordinals (dict[ProductSymbol, int]): dictionary ({symbol: next_book_ordinal}) indicating the next book ordinal by symbol
+        new_epoch_id (int): New epoch ID after epoch marker
+        request_index (int): Sequenced request index of transaction
+    """
+
+    next_book_ordinals: dict[ProductSymbol, int]
+    new_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 an AdvanceEpoch
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        advance_epoch_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            {
+                ProductSymbol(symbol): ordinal
+                for symbol, ordinal in advance_epoch_tx_event[
+                    "nextBookOrdinals"
+                ].items()
+            },
+            advance_epoch_tx_event["newEpochId"],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process an EpochMarker transaction of type AdvanceEpoch. This
+        indicates the a new epoch in the transaction log, although
+        it is not state-transitioning in the way typical transactions
+        are.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to AdvanceEpoch transactions
+        """
+
+        # Update current epoch next book ordinals for closing
+        old_epoch_metadata_key = EpochMetadataKey(self.new_epoch_id - 1)
+        old_epoch_metadata = smt.epoch_metadata(old_epoch_metadata_key)
+        old_epoch_metadata.next_book_ordinals = self.next_book_ordinals
+        smt.store_epoch_metadata(old_epoch_metadata_key, old_epoch_metadata)
+
+        # Create a new epoch metadata
+        smt.store_epoch_metadata(
+            EpochMetadataKey(self.new_epoch_id), EpochMetadata.default()
+        )
+
+        # Set the expected epoch ID to be the new epoch ID 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"], self.new_epoch_id)
+        kwargs["expected_tx_ordinal"](kwargs["auditor_instance"], -1)

ddx/common/transactions/advance_settlement_epoch.py

@@ -0,0 +1,63 @@
+"""
+AdvanceSettlementEpoch module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common.state import DerivadexSMT
+
+
+@define
+class AdvanceSettlementEpoch(Event):
+    """
+    Defines a AdvanceSettlementEpoch
+
+    A AdvanceSettlementEpoch is a non-transitioning transaction that indicates
+    the start of a new settlement epoch.
+
+    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 AdvanceSettlementEpoch
+        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 AdvanceSettlementEpoch transaction.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to AdvanceSettlementEpoch transactions
+        """
+
+        latest_price_keys = {
+            price_key for price_key, _ in kwargs["latest_price_leaves"].values()
+        }
+        for price_key, _ in smt.all_prices():
+            if price_key in latest_price_keys:
+                continue
+
+            smt.store_price(price_key, None)

ddx/common/transactions/all_price_checkpoints.py

@@ -0,0 +1,84 @@
+"""
+AllPriceCheckpoints module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx.common.transactions.price_checkpoint import PriceCheckpoint
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.accounting import MarkPriceMetadata
+from ddx._rust.common.state import DerivadexSMT
+from ddx._rust.decimal import Decimal
+
+
+@define
+class AllPriceCheckpoints(Event):
+    """
+    Defines a AllPriceCheckpoints
+
+    An AllPriceCheckpoints is when a market registers an update to the
+    composite index price a perpetual is tracking along with the ema
+    component for 1+ symbols.
+
+    Attributes:
+        price_checkpoints (list[PriceCheckpoint]): The price checkpoints that make up this transaction
+        request_index (int): Sequenced request index of transaction
+    """
+
+    price_checkpoints: list[PriceCheckpoint] = field(eq=set)
+    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 an
+        AllPriceCheckpoints instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        all_price_checkpoint_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            [
+                PriceCheckpoint(
+                    ProductSymbol(all_price_checkpoints_key),
+                    MarkPriceMetadata.from_dict(
+                        all_price_checkpoints_val["markPriceMetadata"]
+                    ),
+                    all_price_checkpoints_val["indexPriceHash"],
+                    Decimal(all_price_checkpoints_val["indexPrice"]),
+                    all_price_checkpoints_val["ordinal"],
+                    all_price_checkpoints_val["timeValue"],
+                    raw_tx_log_event["requestIndex"],
+                )
+                for all_price_checkpoints_key, all_price_checkpoints_val in all_price_checkpoint_tx_event.items()
+            ],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process an AllPriceCheckpoints transaction. An
+        AllPriceCheckpoints consists of information relating to a new
+        price checkpoint for 1+ symbols.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to AllPriceCheckpoints transactions
+        """
+
+        # Loop through each price checkpoint event and process them
+        # individually
+        for price_checkpoint in self.price_checkpoints:
+            price_checkpoint.process_tx(smt, **kwargs)

ddx/common/transactions/cancel.py

@@ -0,0 +1,76 @@
+"""
+Cancel module
+"""
+
+import logging
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common import ProductSymbol
+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 Cancel(Event):
+    """
+    Defines a Cancel
+
+    A Cancel is when an existing order is canceled and removed from the
+    order book.
+
+    Attributes:
+        symbol (ProductSymbol): The symbol for the market this order is for.
+        order_hash (str): Hexstr representation of the EIP-712 hash of the order
+        amount (Decimal): Amount/size of order
+        request_index (int): Sequenced request index of transaction
+    """
+
+    symbol: ProductSymbol
+    order_hash: str = field(eq=str.lower)
+    amount: Decimal
+    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 Cancel
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        cancel_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            ProductSymbol(cancel_tx_event["symbol"]),
+            cancel_tx_event["orderHash"],
+            Decimal(cancel_tx_event["amount"]),
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a Cancel transaction. We will need to delete a
+        BookOrder leaf with this information.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to Cancel transactions
+        """
+
+        logger.debug(f"Canceling {self.symbol} order {self.order_hash}")
+        smt.store_book_order(BookOrderKey(self.symbol, self.order_hash), None)

ddx/common/transactions/cancel_all.py

@@ -0,0 +1,88 @@
+"""
+CancelAll module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.cancel import Cancel
+from ddx.common.transactions.event import Event
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.state import BookOrder, DerivadexSMT
+from ddx._rust.common.state.keys import BookOrderKey
+from ddx._rust.h256 import H256
+
+
+@define
+class CancelAll(Event):
+    """
+    Defines a CancelAll
+
+    A CancelAll is when all existing orders are canceled and removed from the
+    order book for a given trader, strategy, and symbol.
+
+    Attributes:
+        symbol (ProductSymbol): The symbol for the market to cancel all orders for.
+        trader_address (str): The trader address component of the strategy key pertaining to the CancelAll tx.
+        strategy_id_hash (str): The strategy id hash component of the strategy key pertaining to the CancelAll tx.
+        request_index (int): Sequenced request index of transaction
+    """
+
+    symbol: ProductSymbol
+    trader_address: str = field(eq=str.lower)
+    strategy_id_hash: 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 CancelAll
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        cancel_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            ProductSymbol(cancel_tx_event["symbol"]),
+            cancel_tx_event["strategyKey"]["traderAddress"],
+            cancel_tx_event["strategyKey"]["strategyIdHash"],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a CancelAll transaction. We will need to delete a
+        BookOrder leaf with this information.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to CancelAll transactions
+        """
+
+        book_order_leaves: list[tuple[BookOrderKey, BookOrder]] = [
+            (book_order_key, book_order)
+            for book_order_key, book_order in smt.all_book_orders_for_symbol(
+                self.symbol
+            )
+            if book_order.trader_address == self.trader_address
+            and book_order.strategy_id_hash == self.strategy_id_hash
+        ]
+
+        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)

ddx/common/transactions/complete_fill.py

@@ -0,0 +1,103 @@
+"""
+CompleteFill module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.cancel import Cancel
+from ddx.common.transactions.event import Event
+from ddx.common.transactions.inner.outcome import Outcome
+from ddx.common.transactions.inner.trade_fill import TradeFill
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.enums import OrderSide
+from ddx._rust.common.state import DerivadexSMT
+from ddx._rust.decimal import Decimal
+
+
+@define
+class CompleteFill(Event):
+    """
+    Defines an CompleteFill
+
+    A CompleteFill is a scenario where the taker order has been completely filled
+    across 1 or more maker orders along with any canceled maker orders.
+
+    Attributes:
+        trade_outcomes (list[TradeFill | Cancel]): A list of trade outcome objects
+        request_index (int): Sequenced request index of transaction
+    """
+
+    trade_outcomes: list[TradeFill | Cancel] = field(eq=set)
+    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 CompleteFill
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        event = raw_tx_log_event["event"]["c"]
+        trade_outcomes_tx_event = event["tradeOutcomes"]
+
+        return cls(
+            [
+                (
+                    TradeFill(
+                        ProductSymbol(trade_outcome["Fill"]["symbol"]),
+                        trade_outcome["Fill"]["takerOrderHash"],
+                        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"],
+                        ),
+                        Outcome(
+                            trade_outcome["Fill"]["takerOutcome"]["trader"],
+                            trade_outcome["Fill"]["takerOutcome"]["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 trade_outcomes_tx_event
+            ],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a CompleteFill transaction. A CompleteFill consists of
+        Fill objects, which will adjust the maker BookOrder leaf in the
+        SMT, while also adjusting the Strategy, Position, and Trader
+        leaves corresponding to both the maker and the taker.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to CompleteFill transactions
+        """
+
+        # Loop through each trade outcome event and process them individually
+        for trade_outcome in self.trade_outcomes:
+            trade_outcome.process_tx(smt, **kwargs)