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

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,131 @@
+"""
+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
+from typing import Optional
+
+
+def _is_zero_address(addr: Optional[str]) -> bool:
+    if addr is None:
+        return True
+    try:
+        return int(str(addr).replace("0x", ""), 16) == 0
+    except Exception:
+        return False
+
+
+@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
+        referral_address (Optional[str]): Optional referral address to set exactly once
+        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
+    referral_address: Optional[str] = None
+    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"]
+
+        amount_raw = trader_update_tx_event.get("amount")
+        amount = Decimal(amount_raw) if amount_raw is not None else Decimal("0")
+
+        return cls(
+            trader_update_tx_event["trader"],
+            amount,
+            TraderUpdateKind(trader_update_tx_event["updateKind"]),
+            trader_update_tx_event.get("payFeesInDdx", False),
+            trader_update_tx_event.get("referralAddress"),
+            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
+            if self.referral_address and not _is_zero_address(self.referral_address):
+                # Set-once semantics: only set when currently unset/zero.
+                if _is_zero_address(trader.referral_address):
+                    # Ensure the referral uses the 21-byte TraderAddress format (chain byte + EOA).
+                    referral = self.referral_address
+                    if referral.startswith("0x") and len(referral) == 42:
+                        referral = f"0x00{referral[2:]}"
+                    trader.referral_address = referral
+                elif trader.referral_address != self.referral_address:
+                    raise Exception("Referral address already set for trader")
+
+        smt.store_trader(trader_key, trader)

ddx/common/transactions/withdraw.py

@@ -0,0 +1,90 @@
+"""
+Withdraw module
+"""
+
+from attrs import define, field
+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)
+        strategy.set_avail_collateral(
+            symbol,
+            strategy.avail_collateral[symbol] - self.amount,
+        )
+        # Increment the frozen balance by the withdrawn amount
+        strategy.set_locked_collateral(
+            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)

ddx/common/utils.py

@@ -0,0 +1,176 @@
+"""
+Utils module
+"""
+
+from decimal import Decimal as PyDecimal
+import simplejson as json
+
+from ddx._rust.common.enums import OrderSide
+from ddx._rust.decimal import Decimal
+
+
+def round_to_unit(val: Decimal) -> Decimal:
+    """
+    Round a decimal value down to 6 units of precision.
+
+    Parameters
+    ----------
+    val : Decimal
+        Value to be rounded
+    """
+
+    return val.quantize(6)
+
+
+def to_base_unit_amount(val: Decimal, decimals: int) -> int:
+    """
+    Convert a value to grains format (e.g. DDX grains would be
+    multiplying by 10 ** 18).
+
+    Parameters
+    ----------
+    val : Decimal
+        Value to be scaled up
+    decimals : int
+        Number of decimal places to scale up to
+    """
+
+    return int(round_to_unit(val) * 10**decimals)
+
+
+def to_unit_amount(val: int, decimals: int) -> Decimal:
+    """
+    Convert a value from grains format (e.g. from DDX grains would be
+    dividing by 10 ** 18).
+
+    Parameters
+    ----------
+    val : Decimal
+        Value to be scaled down
+    decimals : int
+        Number of decimal places to scale down by
+    """
+
+    return Decimal(str(val)) / 10**decimals
+
+
+def to_base_unit_amount_list(vals: list[Decimal], decimals: int) -> list[int]:
+    """
+    Convert values to grains format (e.g. DDX grains would be
+    multiplying by 10 ** 18).
+
+    Parameters
+    ----------
+    vals : list[Decimal]
+        Values to be scaled up
+    decimals : int
+        Number of decimal places to scale up to
+    """
+
+    return [to_base_unit_amount(val, decimals) for val in vals]
+
+
+def to_unit_amount_list(vals: list[int], decimals: int):
+    """
+    Convert values from grains format (e.g. from DDX grains would be
+    dividing by 10 ** 18).
+
+    Parameters
+    ----------
+    vals : list[int]
+        Values to be scaled down
+    decimals : int
+        Number of decimal places to scale down by
+    """
+
+    return [to_unit_amount(val, decimals) for val in vals]
+
+
+def to_adjusted_encoding_for_negative_val(val: int):
+    """
+    Adjust encoding for a potentially negative value
+
+    Parameters
+    ----------
+    vals : int
+        Values to be adjusted
+    """
+
+    return 16**32 + abs(val) if val < 0 else val
+
+
+def to_adjusted_encoding_for_negative_val_list(vals: list[int]):
+    """
+    Adjust encoding for list of potentially negative values
+
+    Parameters
+    ----------
+    vals : list[int]
+        list of values to be adjusted
+    """
+
+    return [to_adjusted_encoding_for_negative_val(val) for val in vals]
+
+
+def from_adjusted_encoding_for_negative_val(val: int):
+    """
+    Adjust encoding for a potentially negative value
+
+    Parameters
+    ----------
+    vals : int
+        Values to be adjusted
+    """
+
+    return val if val < 16**32 else -(val - 16**32)
+
+
+def get_parsed_tx_log_entry(tx_log_entry: dict):
+    """
+    Parse an individual transaction log entry into a format
+    suitable for the Auditor. This format was selected so
+    that the Auditor can be reused as-is by the integration
+    tests with no changes needed.
+
+    Parameters
+    ----------
+    tx_log_entry : dict
+        Transaction log message
+    """
+    return {
+        "event": tx_log_entry["event"],
+        "requestIndex": int(tx_log_entry["requestIndex"]),
+        "epochId": int(tx_log_entry["epochId"]),
+        "txOrdinal": int(tx_log_entry["ordinal"]),
+        "batchId": int(tx_log_entry["batchId"]),
+        "timeValue": int(tx_log_entry["time"]["value"]),
+        "timestamp": int(tx_log_entry["time"]["timestamp"]),
+        "stateRootHash": tx_log_entry["stateRootHash"],
+    }
+
+
+def calculate_max_collateral(
+    collateral_tranches: list[tuple[Decimal, Decimal]], ddx_balance: Decimal
+) -> Decimal:
+    limit = Decimal("0")
+    for ddx_threshold, max_collateral in collateral_tranches:
+        limit = max_collateral
+        if ddx_balance < ddx_threshold:
+            break
+    return limit
+
+
+class ComplexOutputEncoder(json.JSONEncoder):
+    """
+    Custom JSON-encoder for serializing objects
+    """
+
+    def __init__(self, **kwargs):
+        super(ComplexOutputEncoder, self).__init__(**kwargs)
+
+    def default(self, o):
+        if hasattr(o, "repr_json"):
+            return o.repr_json()
+        elif type(o) == Decimal:
+            return PyDecimal(str(o))
+        return json.JSONEncoder.default(self, o)

ddx/config.py

@@ -0,0 +1,17 @@
+import os
+
+# from ddx._rust import common
+from ddx._rust.common import reinit_operator_context
+
+# FIXME: might need to change these environment variables to `DDX_CONTRACT_DEPLOYMENT` for better convention
+
+
+def load_mainnet():
+    os.environ["CONTRACT_DEPLOYMENT"] = "derivadex"
+    # common.reinit_operator_context()
+    reinit_operator_context()
+
+
+def load_testnet():
+    os.environ["CONTRACT_DEPLOYMENT"] = "testnet"
+    reinit_operator_context()