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

ddx/common/transactions/strategy_update.py

@@ -0,0 +1,156 @@
+"""
+Strategy Update module
+"""
+
+from typing import Optional
+
+from attrs import define, field
+from ddx.common.item_utils import update_avail_collateral, update_locked_collateral
+from ddx.common.transactions.event import Event
+from ddx.common.utils import calculate_max_collateral
+from ddx._rust.common import TokenSymbol
+from ddx._rust.common.state import DerivadexSMT, Strategy, Trader
+from ddx._rust.common.state.keys import StrategyKey, TraderKey
+from ddx._rust.common.transactions import StrategyUpdateKind
+from ddx._rust.decimal import Decimal
+
+
+@define
+class StrategyUpdate(Event):
+    """
+    Defines a Strategy Update
+
+    A StrategyUpdate is an update to a trader's strategy (such as
+    depositing or withdrawing collateral).
+
+    Attributes:
+        trader_address (str): Trader's Ethereum address this strategy belongs to
+        collateral_address (str): Collateral's Ethereum address a deposit/withdrawal has been made with
+        strategy_id_hash (str): Strategy ID hash for the given trader this event belongs to
+        strategy_id (Optional[str]): Strategy ID for the given trader this event belongs to. Only deposits will fill this field
+        amount (Decimal): The amount of collateral deposited or withdrawn
+        update_kind (StrategyUpdateKind): Update kind (Deposit=0, Withdraw=1)
+        tx_hash (str): The Ethereum transaction's hash
+        request_index (int): Sequenced request index of transaction
+    """
+
+    trader_address: str = field(eq=str.lower)
+    collateral_address: str = field(eq=str.lower)
+    strategy_id_hash: str = field(eq=str.lower)
+    strategy_id: Optional[str]
+    amount: Decimal
+    update_kind: StrategyUpdateKind
+    tx_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 StrategyUpdate
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        strategy_update_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            strategy_update_tx_event["trader"],
+            strategy_update_tx_event["collateralAddress"],
+            strategy_update_tx_event["strategyIdHash"],
+            strategy_update_tx_event.get("strategyId"),
+            Decimal(strategy_update_tx_event["amount"]),
+            StrategyUpdateKind(strategy_update_tx_event["updateKind"]),
+            strategy_update_tx_event["txHash"],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a StrategyUpdate transaction. A StrategyUpdate consists
+        of information relating to updates for a trader's strategy, such
+        as when their free or frozen collateral has changed due to a
+        deposit or withdrawal. This will update the Strategy leaf in the
+        SMT.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to StrategyUpdate transactions
+        """
+
+        strategy_key: StrategyKey = StrategyKey(
+            self.trader_address, self.strategy_id_hash
+        )
+        strategy = smt.strategy(strategy_key)
+
+        symbol = TokenSymbol.from_address(self.collateral_address)
+        if self.update_kind == StrategyUpdateKind.Deposit:
+            # If StrategyUpdate is of deposit type
+
+            trader_key: TraderKey = TraderKey(self.trader_address)
+            trader = smt.trader(trader_key)
+
+            if strategy is None:
+                # If we haven't yet seen the Strategy leaf, create a new
+                # one
+                strategy = Strategy.default()
+
+                if trader is None:
+                    # Initialize a new Trader Leaf
+                    trader = Trader.default()
+
+                    smt.store_trader(trader_key, trader)
+
+            # Compute max allowable deposit given the collateral guard
+            # for the trader's DDX balance
+            max_allowable_deposit = max(
+                (
+                    calculate_max_collateral(
+                        kwargs["collateral_tranches"], trader.avail_ddx_balance
+                    )
+                    - strategy.avail_collateral.total_value()
+                ),
+                Decimal("0"),
+            )
+
+            # Compute how much of the attempted deposit will be added
+            # to the Strategy's free collateral
+            net = min(max_allowable_deposit, self.amount)
+
+            # Increment the Strategy's free collateral
+            update_avail_collateral(
+                strategy, symbol, strategy.avail_collateral[symbol] + net
+            )
+
+            # Compute how much of the attempted deposit will be added
+            # to the Strategy's frozen collateral
+            kickback = self.amount - net
+            if kickback != Decimal("0"):
+                # Increment the Strategy's frozen collateral
+                update_locked_collateral(
+                    strategy, symbol, strategy.locked_collateral[symbol] + kickback
+                )
+        elif self.update_kind == StrategyUpdateKind.Withdraw:
+            # If StrategyUpdate is of withdrawal (claimed) type
+            if strategy is None or strategy.locked_collateral[symbol] < self.amount:
+                raise Exception(
+                    "Strategy leaf either non-existent or insufficiently capitalized to facilitate withdrawal"
+                )
+
+            # Adjust the existing strategy leaf by decrementing the
+            # free collateral by the amount in the withdrawal event
+            update_locked_collateral(
+                strategy, symbol, strategy.locked_collateral[symbol] - self.amount
+            )
+
+        smt.store_strategy(strategy_key, strategy)

ddx/common/transactions/tradable_product_update.py

@@ -0,0 +1,98 @@
+"""
+Tradable Product Update module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common.specs import SpecsKind
+from ddx._rust.common.state import (DerivadexSMT, TradableProduct,
+                                     TradableProductParameters)
+from ddx._rust.common.state.keys import SpecsKey, TradableProductKey
+
+
+@define
+class TradableProductUpdate(Event):
+    """
+    Defines a Tradable Product Update
+
+    A TradableProductUpdate is an update to a trader's strategy (such as depositing or withdrawing collateral).
+
+    Attributes:
+        additions (list[TradableProductKey]): List of tradable product keys that are marked tradable
+        removals (list[TradableProductKey]): List of tradable product keys that are marked untradable
+        request_index (int): Sequenced request index of transaction
+    """
+
+    additions: list[TradableProductKey]
+    removals: list[TradableProductKey]
+    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 StrategyUpdate
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        tradable_product_update_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            [
+                TradableProductKey(
+                    SpecsKey(
+                        SpecsKind(tradable_product_key["specs"]["kind"]),
+                        tradable_product_key["specs"]["name"],
+                    ),
+                    TradableProductParameters.from_dict(
+                        tradable_product_key["parameters"]
+                    ),
+                )
+                for tradable_product_key in tradable_product_update_tx_event[
+                    "additions"
+                ]
+            ],
+            [
+                TradableProductKey(
+                    SpecsKey(
+                        SpecsKind(tradable_product_key["specs"]["kind"]),
+                        tradable_product_key["specs"]["name"],
+                    ),
+                    TradableProductParameters.from_dict(
+                        tradable_product_key["parameters"]
+                    ),
+                )
+                for tradable_product_key in tradable_product_update_tx_event["removals"]
+            ],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a TradableProductUpdate transaction. A TradableProductUpdate consists
+        of information relating to updates of the list of tradable products.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to TradableProductUpdate transactions
+        """
+
+        for tradable_product_key in self.additions:
+            smt.store_tradable_product(
+                tradable_product_key,
+                TradableProduct(),
+            )
+
+        for tradable_product_key in self.removals:
+            smt.store_tradable_product(tradable_product_key, None)

ddx/common/transactions/trade_mining.py

@@ -0,0 +1,147 @@
+"""
+TradeMining module
+"""
+
+import logging
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common.state import DerivadexSMT, Stats
+from ddx._rust.common.state.keys import TraderKey
+from ddx._rust.decimal import Decimal
+
+logger = logging.getLogger(__name__)
+
+
+@define
+class TradeMining(Event):
+    """
+    Defines a TradeMining
+
+    A TradeMining is when a there is a trade mining distribution.
+
+    Attributes:
+        settlement_epoch_id (int): Settlement epoch id
+        ddx_distributed (Decimal): The total DDX distributed in this interval.
+        total_volume (Stats): The total maker and taker volume for this interval.
+        request_index (int): Sequenced request index of transaction
+    """
+
+    settlement_epoch_id: int
+    ddx_distributed: Decimal
+    total_volume: Stats
+    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
+        """
+
+        trade_mining_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            trade_mining_tx_event["settlementEpochId"],
+            Decimal(trade_mining_tx_event["ddxDistributed"]),
+            Stats(
+                Decimal(trade_mining_tx_event["totalVolume"]["makerVolume"]),
+                Decimal(trade_mining_tx_event["totalVolume"]["takerVolume"]),
+            ),
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a TradeMining transaction. A TradeMining event consists
+        of consists of information relating to the trade mining
+        distribution, when DDX will be allocated to traders due to
+        their maker and taker volume contributions as a proportion to
+        the overall exchange volume.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to TradeMining transactions
+        """
+
+        if not kwargs["trade_mining_active"]:
+            return
+
+        # The overall trade mining allocation is 75% of the
+        # liquidity mining supply (50mm DDX) issued over a 10-year
+        # schedule, 3 times a day
+        ddx_reward_per_epoch = kwargs["trade_mining_reward_per_epoch"]
+        trade_mining_maker_reward_percentage = kwargs[
+            "trade_mining_maker_reward_percentage"
+        ]
+        trade_mining_taker_reward_percentage = kwargs[
+            "trade_mining_taker_reward_percentage"
+        ]
+        if self.ddx_distributed != Decimal("0"):
+            # If trade mining did distribute DDX during the trade
+            # mining period, we should handle DDX distributions,
+            # otherwise we can gracefully skip
+
+            # Loop through all the stats leaves
+            for stats_key, stats in smt.all_stats():
+                # Compute the DDX gained as a result of maker volume
+                # for the trader (20% of the DDX rewards go to makers)
+                ddx_accrued_as_maker = (
+                    stats.maker_volume
+                    / self.total_volume.maker_volume
+                    * ddx_reward_per_epoch
+                    * trade_mining_maker_reward_percentage
+                    if self.total_volume.maker_volume != Decimal("0")
+                    else Decimal("0")
+                )
+
+                # Compute the DDX gained as a result of taker volume
+                # for the trader (80% of the DDX rewards go to takers)
+                ddx_accrued_as_taker = (
+                    stats.taker_volume
+                    / self.total_volume.taker_volume
+                    * ddx_reward_per_epoch
+                    * trade_mining_taker_reward_percentage
+                    if self.total_volume.taker_volume != Decimal("0")
+                    else Decimal("0")
+                )
+
+                if ddx_accrued_as_maker != Decimal(
+                    "0"
+                ) or ddx_accrued_as_taker != Decimal("0"):
+                    # If DDX accrued for trader is non-zero, handle
+                    # distribution
+
+                    # Derive TraderKey given the key
+                    trader_key: TraderKey = stats_key.as_trader_key()
+
+                    # Get Trader leaf given the key from above
+                    trader = smt.trader(trader_key)
+
+                    # Increment the Trader leaf's available balance by the
+                    # DDX accrued (both maker and taker)
+                    trader.avail_ddx_balance = (
+                        trader.avail_ddx_balance
+                        + ddx_accrued_as_maker
+                        + ddx_accrued_as_taker
+                    ).recorded_amount()
+
+                    # Update the SMT with the H256 repr of the key and
+                    # the Trader leaf
+                    smt.store_trader(trader_key, trader)
+
+                    # Update the SMT with the H256 repr of the key and
+                    # the Stats leaf
+                    smt.store_stats(stats_key, None)

ddx/common/transactions/trader_update.py

@@ -0,0 +1,105 @@
+"""
+Trader Update module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common.state import DerivadexSMT, Trader
+from ddx._rust.common.state.keys import TraderKey
+from ddx._rust.common.transactions import TraderUpdateKind
+from ddx._rust.decimal import Decimal
+
+
+@define
+class TraderUpdate(Event):
+    """
+    Defines a TraderUpdate
+
+    A TraderUpdate is an update to a trader's DDX account (such as depositing
+    or withdrawing DDX).
+
+    Attributes:
+        trader_address (str): Trader's Ethereum address this strategy belongs to
+        amount (Decimal): The amount of collateral deposited or withdrawn
+        update_kind (TraderUpdateKind): Update kind (Deposit, Withdraw, Profile)
+        pay_fees_in_ddx (bool): Whether trader has opted to pay fees in DDX by default
+        tx_hash (str): The Ethereum transaction's hash
+        request_index (int): Sequenced request index of transaction
+    """
+
+    trader_address: str = field(eq=str.lower)
+    amount: Decimal
+    update_kind: TraderUpdateKind
+    pay_fees_in_ddx: bool
+    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 StrategyUpdate
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        trader_update_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            trader_update_tx_event["trader"],
+            Decimal(trader_update_tx_event["amount"]),
+            TraderUpdateKind(trader_update_tx_event["updateKind"]),
+            trader_update_tx_event["payFeesInDdx"],
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a TraderUpdate transaction. A TraderUpdate consists
+        of information relating to updates to a trader. This will
+        update the Trader leaf in the SMT.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to TraderUpdate transactions
+        """
+
+        trader_key: TraderKey = TraderKey(self.trader_address)
+        trader = smt.trader(trader_key)
+
+        if self.update_kind == TraderUpdateKind.DepositDDX:
+            # If TraderUpdate is of deposit type
+            if trader is None:
+                # Initialize a new Trader Leaf
+                trader = Trader.default()
+
+            trader.avail_ddx_balance += self.amount
+        elif self.update_kind == TraderUpdateKind.WithdrawDDX:
+            # If TraderUpdate is of withdrawal (claimed) type
+            if trader is None or trader.locked_ddx_balance < self.amount:
+                raise Exception(
+                    "Trader leaf either non-existent or insufficiently capitalized to facilitate withdrawal"
+                )
+
+            # Adjust the existing Trader leaf by decrementing the
+            # free collateral by the amount in the withdrawal event
+            trader.locked_ddx_balance -= self.amount
+        elif self.update_kind == TraderUpdateKind.Profile:
+            # If TraderUpdate is of profile type
+            if trader is None:
+                raise Exception("Trader leaf non-existent")
+
+            # Adjust the existing Trader leaf by setting the
+            # flag to pay fees in DDX
+            trader.pay_fees_in_ddx = self.pay_fees_in_ddx
+
+        smt.store_trader(trader_key, trader)

ddx/common/transactions/withdraw.py

@@ -0,0 +1,91 @@
+"""
+Withdraw module
+"""
+
+from attrs import define, field
+from ddx.common.item_utils import update_avail_collateral, update_locked_collateral
+from ddx.common.transactions.event import Event
+from ddx._rust.common import TokenSymbol
+from ddx._rust.common.state import DerivadexSMT, Strategy, Trader
+from ddx._rust.common.state.keys import StrategyKey
+from ddx._rust.decimal import Decimal
+
+
+@define
+class Withdraw(Event):
+    """
+    Defines a Withdraw Update
+
+    A Withdraw Update is when a withdrawal of collateral is **signaled**.
+
+    Attributes:
+        recipient_address (str): Trader address DDX is being withdrawn to
+        strategy_id_hash (str): Cross-margined strategy ID hash for which this withdrawal applies
+        collateral_address (str): Collateral ERC-20 token address being withdrawn
+        amount (Decimal): The amount of DDX being withdrawn
+        request_index (int): Sequenced request index of transaction
+    """
+
+    recipient_address: str = field(eq=str.lower)
+    strategy_id_hash: str = field(eq=str.lower)
+    collateral_address: str = field(eq=str.lower)
+    amount: Decimal
+    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 Withdraw
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        withdraw_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            withdraw_tx_event["recipientAddress"],
+            withdraw_tx_event["strategy"],
+            withdraw_tx_event["currency"],
+            Decimal(withdraw_tx_event["amount"]),
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a Withdraw transaction. A Withdraw event consists
+        of consists of information relating to withdrawal of collateral.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to Withdraw transactions
+        """
+
+        strategy_key: StrategyKey = StrategyKey(
+            self.recipient_address, self.strategy_id_hash
+        )
+        strategy: Strategy = smt.strategy(strategy_key)
+
+        # Decrement the free balance by the withdrawn amount
+        symbol = TokenSymbol.from_address(self.collateral_address)
+        update_avail_collateral(
+            strategy,
+            symbol,
+            strategy.avail_collateral[symbol] - self.amount,
+        )
+        # Increment the frozen balance by the withdrawn amount
+        update_locked_collateral(
+            strategy, symbol, strategy.locked_collateral[symbol] + self.amount
+        )
+
+        smt.store_strategy(strategy_key, strategy)

ddx/common/transactions/withdraw_ddx.py

@@ -0,0 +1,74 @@
+"""
+WithdrawDDX module
+"""
+
+from attrs import define, field
+from ddx.common.transactions.event import Event
+from ddx._rust.common.state import DerivadexSMT
+from ddx._rust.common.state.keys import TraderKey
+from ddx._rust.decimal import Decimal
+
+
+@define
+class WithdrawDDX(Event):
+    """
+    Defines a WithdrawDDX Update
+
+    A WithdrawDDX is when a withdrawal of DDX is signaled.
+
+    Attributes:
+        recipient_address (str): Ethereum address DDX is being withdrawn to
+        amount (Decimal): The amount of DDX being withdrawn
+        request_index (int): Sequenced request index of transaction
+    """
+
+    recipient_address: str = field(eq=str.lower)
+    amount: Decimal
+    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 WithdrawDDX
+        instance.
+
+        Parameters
+        ----------
+        raw_tx_log_event : dict
+            Raw transaction log event being processed
+        """
+
+        withdraw_ddx_tx_event = raw_tx_log_event["event"]["c"]
+
+        return cls(
+            withdraw_ddx_tx_event["recipientAddress"],
+            Decimal(withdraw_ddx_tx_event["amount"]),
+            raw_tx_log_event["requestIndex"],
+        )
+
+    def process_tx(
+        self,
+        smt: DerivadexSMT,
+        **kwargs,
+    ):
+        """
+        Process a WithdrawDDX transaction. A WithdrawDDX event consists
+        of consists of information relating to withdrawal of DDX.
+
+        Parameters
+        ----------
+        smt: DerivadexSMT
+            DerivaDEX Sparse Merkle Tree
+        **kwargs
+            Additional args specific to WithdrawDDX transactions
+        """
+
+        trader_key: TraderKey = TraderKey(self.recipient_address)
+        trader = smt.trader(trader_key)
+
+        # Decrement the free balance by the withdrawn amount
+        trader.avail_ddx_balance -= self.amount
+        # Increment the frozen balance by the withdrawn amount
+        trader.locked_ddx_balance += self.amount
+
+        smt.store_trader(trader_key, trader)