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

ddx/auditor/websocket_message.py

@@ -0,0 +1,54 @@
+"""
+WebsocketMessage module
+"""
+
+from enum import Enum
+from typing import Dict, Union
+
+from attrs import define
+
+
+class WebsocketMessageType(str, Enum):
+    GET = "Get"
+    SUBSCRIBE = "Subscribe"
+    REQUEST = "Request"
+    INFO = "Info"
+    SEQUENCED = "Sequenced"
+    SAFETY_FAILURE = "SafetyFailure"
+
+
+class WebsocketEventType(str, Enum):
+    PARTIAL = "Partial"
+    UPDATE = "Update"
+    SNAPSHOT = "Snapshot"
+    HEAD = "Head"
+    TAIL = "Tail"
+
+
+@define
+class WebsocketMessage:
+    """
+    Defines a WebsocketMessage.
+    """
+
+    message_type: Union[WebsocketMessageType, str]
+    message_content: str
+
+    @classmethod
+    def decode_value_into_cls(cls, raw_websocket_message: Dict):
+        """
+        Decode a raw websocket message into class
+
+        Parameters
+        ----------
+        raw_websocket_message : Dict
+            Raw websocket message
+        """
+
+        return cls(
+            raw_websocket_message["t"],
+            raw_websocket_message["c"],
+        )
+
+    def repr_json(self):
+        return {"t": self.message_type, "c": self.message_content}

ddx/common/epoch_params.py

@@ -0,0 +1,28 @@
+from attrs import define
+from ddx._rust.common import ProductSymbol
+from ddx._rust.common.requests import SettlementAction
+
+
+@define
+class EpochParams:
+    """
+    Defines the epoch parameters
+    """
+
+    epoch_size: int
+    price_checkpoint_size: int
+    settlement_epoch_length: int
+    pnl_realization_period: int
+    funding_period: int
+    trade_mining_period: int
+    expiry_price_leaves_duration: int
+
+    @property
+    def settlement_action_periods(self):
+        res = {
+            SettlementAction.TradeMining: self.trade_mining_period,
+            SettlementAction.PnlRealization: self.pnl_realization_period,
+            SettlementAction.FundingDistribution: self.funding_period,
+        }
+
+        return res

ddx/common/fill_context.py

@@ -0,0 +1,144 @@
+"""
+Fill module.
+"""
+
+import logging
+from typing import Optional
+
+from attrs import define, field
+from ddx.common.item_utils import update_avail_collateral
+from ddx.common.transactions.inner.outcome import Outcome
+from ddx._rust.common import TokenSymbol
+from ddx._rust.common.enums import OrderSide, PositionSide, TradeSide
+from ddx._rust.common.state import Position, Strategy, Trader
+from ddx._rust.decimal import Decimal
+
+logger = logging.getLogger(__name__)
+
+MAX_DDX_PRICE_CHECKPOINT_AGE_IN_TICKS = 40000
+DDX_FEE_DISCOUNT = 0.5
+
+
+def apply_trade(
+    position: Position, amount: Decimal, price: Decimal, side: OrderSide
+) -> (Position, Decimal):
+    logger.debug(
+        f"Applying trade of {amount} at {price} on {side} to position {position}"
+    )
+    if side == OrderSide.Bid:
+        if position.side == PositionSide.Long:
+            logger.info("Trade side matches position side, increasing position balance")
+            return position.increase(price, amount)
+        if position.side == PositionSide.Short:
+            logger.info(
+                "Trade side does not match position side, decreasing position balance"
+            )
+            if amount > position.balance:
+                return position.cross_over(price, amount)
+            return position.decrease(price, amount)
+        logger.info(
+            "Position side not set, setting to Long and increasing position balance"
+        )
+        position.side = PositionSide.Long
+        return position.increase(price, amount)
+    else:
+        if position.side == PositionSide.Short:
+            logger.info("Trade side matches position side, increasing position balance")
+            return position.increase(price, amount)
+        if position.side == PositionSide.Long:
+            logger.info(
+                "Trade side does not match position side, decreasing position balance"
+            )
+            if amount > position.balance:
+                return position.cross_over(price, amount)
+            return position.decrease(price, amount)
+        logger.info(
+            "Position side not set, setting to Short and increasing position balance"
+        )
+        position.side = PositionSide.Short
+        return position.increase(price, amount)
+
+
+@define
+class FillContext:
+    """
+    Defines a FillContext.
+    """
+
+    outcome: Outcome
+    realized_pnl: Optional[Decimal] = field(init=False)
+
+    def apply_fill(
+        self,
+        position: Optional[Position],
+        side: OrderSide,
+        trade_side: TradeSide,
+        fill_amount: Decimal,
+        fill_price: Decimal,
+    ) -> Position:
+        if position is None:
+            position = Position(
+                PositionSide.Long if side == OrderSide.Bid else PositionSide.Short,
+                Decimal("0"),
+                Decimal("0"),
+            )
+            logger.info(f"New {position.side} position")
+        old_balance = position.balance
+
+        fee = trade_side.trading_fee(fill_amount, fill_price)
+        updated_position, realized_pnl = apply_trade(
+            position, fill_amount, fill_price, side
+        )
+
+        self.realized_pnl = realized_pnl
+        logger.info(f"Realized pnl: {self.realized_pnl}")
+        logger.info(f"Fee: {fee}")
+
+        # Note that, again, we're never reading the fee from the txlog, and instead
+        # we calulate it from the fill amount and price and set it in the outcome.
+        self.outcome.fee = fee
+
+        return updated_position
+
+    def apply_ddx_fee_and_mutate_trader(
+        self,
+        trader: Trader,
+        ddx_price: Decimal,
+    ) -> bool:
+        if self.outcome.fee == Decimal("0"):
+            logger.info("Base fee of 0, no fees to pay")
+            return False
+        fee_in_ddx = (self.outcome.fee / ddx_price) * (Decimal("1") - DDX_FEE_DISCOUNT)
+        if fee_in_ddx.recorded_amount() == Decimal("0"):
+            logger.info(
+                "Fee in DDX is 0 after conversion and discount, no fees to pay in DDX"
+            )
+            return False
+        if trader.avail_ddx_balance < fee_in_ddx:
+            # TODO 3825: this should be caught by the sequencer
+            logger.warn("Not enough DDX to pay fee")
+            return False
+        old_balance = trader.avail_ddx_balance
+        trader.avail_ddx_balance = (old_balance - fee_in_ddx).recorded_amount()
+        self.outcome.fee = (old_balance - trader.avail_ddx_balance).recorded_amount()
+        self.outcome.pay_fee_in_ddx = True
+        return True
+
+    def realize_trade_and_mutate_strategy(self, strategy: Strategy):
+        if strategy.frozen:
+            raise Exception("Cannot realize pnl from a frozen strategy")
+        update_avail_collateral(
+            strategy,
+            TokenSymbol.USDC,
+            strategy.avail_collateral[TokenSymbol.USDC] + self.realized_pnl,
+        )
+        if not self.outcome.pay_fee_in_ddx and self.outcome.fee > Decimal("0"):
+            old_balance = strategy.avail_collateral[TokenSymbol.USDC]
+            update_avail_collateral(
+                strategy,
+                TokenSymbol.USDC,
+                strategy.avail_collateral[TokenSymbol.USDC] - self.outcome.fee,
+            )
+            self.outcome.fee = (
+                old_balance - strategy.avail_collateral[TokenSymbol.USDC]
+            ).recorded_amount()

ddx/common/item_utils.py

@@ -0,0 +1,38 @@
+# This is unfortunate but must be done because
+# https://pyo3.rs/main/faq#pyo3get-clones-my-field
+
+from ddx._rust.common import TokenSymbol
+from ddx._rust.common.state import InsuranceFundContribution, Strategy
+from ddx._rust.decimal import Decimal
+
+
+def update_avail_collateral(strategy: Strategy, symbol: TokenSymbol, amount: Decimal):
+    strategy.avail_collateral = strategy.update_avail_collateral(
+        symbol,
+        amount,
+    )
+
+
+def update_locked_collateral(strategy: Strategy, symbol: TokenSymbol, amount: Decimal):
+    strategy.locked_collateral = strategy.update_locked_collateral(
+        symbol,
+        amount,
+    )
+
+
+def update_avail_balance(
+    contribution: InsuranceFundContribution, symbol: TokenSymbol, amount: Decimal
+):
+    contribution.avail_balance = contribution.update_avail_balance(
+        symbol,
+        amount,
+    )
+
+
+def update_locked_balance(
+    contribution: InsuranceFundContribution, symbol: TokenSymbol, amount: Decimal
+):
+    contribution.locked_balance = contribution.update_locked_balance(
+        symbol,
+        amount,
+    )

ddx/common/logging.py

@@ -0,0 +1,184 @@
+import inspect
+import logging
+
+from colorama import Back, Fore, Style
+from verboselogs import VerboseLogger
+
+logging.setLoggerClass(VerboseLogger)
+
+CHECKMARK = f"{Style.BRIGHT}{Back.GREEN}\u2713{Style.NORMAL}{Back.RESET}"
+
+
+def freeze_logging(func):
+    """Decorator to set the logging pathname, filename, and lineno based on the caller of the decorated function."""
+
+    class CustomLogRecord(logging.LogRecord):
+        def __init__(self, *args, **kwargs):
+            super().__init__(*args, **kwargs)
+            # Capture the stack frame of the caller outside the current module and not from __init__.py
+            for f in inspect.stack():
+                if (
+                    f[1] != inspect.getfile(inspect.currentframe())
+                    and "__init__.py" not in f[1]
+                    and "utils.py" not in f[1]
+                ):
+                    self.pathname = f[1]
+                    self.filename = f[1].split("/")[-1]
+                    self.lineno = f[2]
+                    break
+            else:
+                self.pathname = "unknown_path"
+                self.lineno = 0
+
+    def wrapper(*args, **kwargs):
+        # Temporarily replace the LogRecord class for the logger
+        original_factory = logging.getLogRecordFactory()
+        logging.setLogRecordFactory(CustomLogRecord)
+
+        try:
+            return func(*args, **kwargs)
+        finally:
+            # Restore the original LogRecord class
+            logging.setLogRecordFactory(original_factory)
+
+    return wrapper
+
+
+def auditor_logger(name: str):
+    logger = logging.getLogger(name)
+    logger = AuditorAdapter(logger)
+    return logger
+
+
+def local_logger(name: str):
+    logger = logging.getLogger(name)
+    logger = LocalAdapter(logger)
+    return logger
+
+
+def assert_logger(name: str):
+    logger = logging.getLogger(name)
+    logger = AssertAdapter(logger)
+    return logger
+
+
+def data_logger(name: str):
+    logger = logging.getLogger(name)
+    logger = DataAdapter(logger)
+    return logger
+
+
+class DataAdapter(logging.LoggerAdapter):
+    """
+    Wrap all messages with "data: " and make the message green.
+    """
+
+    def process(self, msg, kwargs):
+        return f"{Fore.GREEN}data: {msg}{Style.RESET_ALL}", kwargs
+
+    @freeze_logging
+    def verbose(self, msg, *args, **kwargs):
+        self.log(logging.VERBOSE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def notice(self, msg, *args, **kwargs):
+        self.log(logging.NOTICE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def success(self, msg, *args, **kwargs):
+        self.log(logging.SUCCESS, msg, *args, **kwargs)
+
+    @freeze_logging
+    def spam(self, msg, *args, **kwargs):
+        self.log(logging.SPAM, msg, *args, **kwargs)
+
+    @freeze_logging
+    def failure(self, msg, *args, **kwargs):
+        self.log(logging.FAILURE, msg, *args, **kwargs)
+
+
+class AssertAdapter(logging.LoggerAdapter):
+    """
+    Wrap all messages with "assert: " and make the message yellow.
+    """
+
+    def process(self, msg, kwargs):
+        return f"{Fore.YELLOW}assert: {msg}{Style.RESET_ALL}", kwargs
+
+    @freeze_logging
+    def verbose(self, msg, *args, **kwargs):
+        self.log(logging.VERBOSE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def notice(self, msg, *args, **kwargs):
+        self.log(logging.NOTICE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def success(self, msg, *args, **kwargs):
+        self.log(logging.SUCCESS, msg, *args, **kwargs)
+
+    @freeze_logging
+    def spam(self, msg, *args, **kwargs):
+        self.log(logging.SPAM, msg, *args, **kwargs)
+
+    @freeze_logging
+    def failure(self, msg, *args, **kwargs):
+        self.log(logging.FAILURE, msg, *args, **kwargs)
+
+
+class AuditorAdapter(logging.LoggerAdapter):
+    """
+    Wrap all messages with "auditor: " and make the message magenta.
+    """
+
+    def process(self, msg, kwargs):
+        return f"{Fore.MAGENTA}auditor: {msg}{Style.RESET_ALL}", kwargs
+
+    @freeze_logging
+    def verbose(self, msg, *args, **kwargs):
+        self.log(logging.VERBOSE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def notice(self, msg, *args, **kwargs):
+        self.log(logging.NOTICE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def success(self, msg, *args, **kwargs):
+        self.log(logging.SUCCESS, msg, *args, **kwargs)
+
+    @freeze_logging
+    def spam(self, msg, *args, **kwargs):
+        self.log(logging.SPAM, msg, *args, **kwargs)
+
+    @freeze_logging
+    def failure(self, msg, *args, **kwargs):
+        self.log(logging.FAILURE, msg, *args, **kwargs)
+
+
+class LocalAdapter(logging.LoggerAdapter):
+    """
+    Wrap all messages with "local: " and make the message blue.
+    """
+
+    def process(self, msg, kwargs):
+        return f"{Fore.BLUE}local: {msg}{Style.RESET_ALL}", kwargs
+
+    @freeze_logging
+    def verbose(self, msg, *args, **kwargs):
+        self.log(logging.VERBOSE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def notice(self, msg, *args, **kwargs):
+        self.log(logging.NOTICE, msg, *args, **kwargs)
+
+    @freeze_logging
+    def success(self, msg, *args, **kwargs):
+        self.log(logging.SUCCESS, msg, *args, **kwargs)
+
+    @freeze_logging
+    def spam(self, msg, *args, **kwargs):
+        self.log(logging.SPAM, msg, *args, **kwargs)
+
+    @freeze_logging
+    def failure(self, msg, *args, **kwargs):
+        self.log(logging.FAILURE, msg, *args, **kwargs)

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["Genesis"]["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("QUARTERLYEXPIRYFUTURE"):
+                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,
+    )