nado-protocol 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

nado_protocol/utils/execute.py

@@ -13,6 +13,7 @@ from nado_protocol.utils.backend import NadoClientOpts
 from nado_protocol.utils.bytes32 import subaccount_to_bytes32, subaccount_to_hex
 from nado_protocol.utils.model import NadoBaseModel
 from nado_protocol.utils.nonce import gen_order_nonce
+from nado_protocol.utils.order import gen_order_verifying_contract
 from nado_protocol.utils.subaccount import Subaccount, SubaccountParams
 
 
@@ -78,13 +79,10 @@ class MarketOrderParams(BaseParams):
     Attributes:
         amount (int): The amount of the asset to be bought or sold in the order. Positive for a `long` position and negative for a `short`.
 
-        expiration (int): The unix timestamp at which the order will expire.
-
         nonce (Optional[int]): A unique number used to prevent replay attacks.
     """
 
     amount: int
-    nonce: Optional[int]
 
 
 class OrderParams(MarketOrderParams):
@@ -99,29 +97,13 @@ class OrderParams(MarketOrderParams):
         amount (int): The amount of the asset to be bought or sold in the order. Positive for a `long` position and negative for a `short`.
 
         nonce (Optional[int]): A unique number used to prevent replay attacks.
+
+        appendix (int): Additional data or instructions related to the order. Use to encode order type and other related data.
     """
 
     priceX18: int
     expiration: int
-
-
-class IsolatedOrderParams(OrderParams):
-    """
-    Class for defining the parameters of an isolated order.
-
-    Attributes:
-        priceX18 (int): The price of the order with a precision of 18 decimal places.
-
-        expiration (int): The unix timestamp at which the order will expire.
-
-        amount (int): The amount of the asset to be bought or sold in the order. Positive for a `long` position and negative for a `short`.
-
-        nonce (Optional[int]): A unique number used to prevent replay attacks.
-
-        margin (int): The margin amount for the isolated order.
-    """
-
-    margin: int
+    appendix: int
 
 
 class NadoBaseExecute:
@@ -142,16 +124,6 @@ class NadoBaseExecute:
     def endpoint_addr(self, addr: str) -> None:
         self._opts.endpoint_addr = addr
 
-    @property
-    def book_addrs(self) -> list[str]:
-        if self._opts.book_addrs is None:
-            raise AttributeError("Book addresses are not set.")
-        return self._opts.book_addrs
-
-    @book_addrs.setter
-    def book_addrs(self, book_addrs: list[str]) -> None:
-        self._opts.book_addrs = book_addrs
-
     @property
     def chain_id(self) -> int:
         if self._opts.chain_id is None:
@@ -191,28 +163,24 @@ class NadoBaseExecute:
             )
         self._opts.linked_signer = linked_signer
 
-    def book_addr(self, product_id: int) -> str:
+    def order_verifying_contract(self, product_id: int) -> str:
         """
-        Retrieves the book address corresponding to the provided product ID.
+        Returns the `place_order` verifying contract address for a given product.
 
-        Needed for signing order placement executes for different products.
+        Note:
+            Previously, `place_order` verifying contracts were accessed via `book_addrs[product_id]`.
+            Virtual books have now been removed, and the verifying contract is derived
+            directly from the product id.
 
-        Args:
-            product_id (int): The ID of the product.
-
-        Returns:
-            str: The book address associated with the given product ID.
+            The address is computed as `address(product_id)`, i.e. the 20-byte
+            big-endian representation of the product id, zero-padded on the left.
 
-        Raises:
-            ValueError: If the provided product_id is greater than or equal to the number of book addresses available.
+            Example:
+                product_id = 18  →  0x0000000000000000000000000000000000000012
         """
-        if product_id >= len(self.book_addrs):
-            raise ValueError(f"Invalid product_id {product_id} provided.")
-        return self.book_addrs[product_id]
+        return gen_order_verifying_contract(product_id)
 
-    def order_nonce(
-        self, recv_time_ms: Optional[int] = None, is_trigger_order: bool = False
-    ) -> int:
+    def order_nonce(self, recv_time_ms: Optional[int] = None) -> int:
         """
         Generate the order nonce. Used for oder placements and cancellations.
 
@@ -222,7 +190,7 @@ class NadoBaseExecute:
         Returns:
             int: The generated order nonce.
         """
-        return gen_order_nonce(recv_time_ms, is_trigger_order=is_trigger_order)
+        return gen_order_nonce(recv_time_ms)
 
     def _inject_owner_if_needed(self, params: Type[BaseParams]) -> Type[BaseParams]:
         """
@@ -245,7 +213,6 @@ class NadoBaseExecute:
         self,
         params: Type[BaseParams],
         use_order_nonce: bool,
-        is_trigger_order: bool = False,
     ) -> Type[BaseParams]:
         """
         Inject the nonce if needed.
@@ -259,15 +226,13 @@ class NadoBaseExecute:
         if params.nonce is not None:
             return params
         params.nonce = (
-            self.order_nonce(is_trigger_order=is_trigger_order)
+            self.order_nonce()
             if use_order_nonce
             else self.tx_nonce(subaccount_to_hex(params.sender))
         )
         return params
 
-    def prepare_execute_params(
-        self, params, use_order_nonce: bool, is_trigger_order: bool = False
-    ):
+    def prepare_execute_params(self, params, use_order_nonce: bool):
         """
         Prepares the parameters for execution by ensuring that both owner and nonce are correctly set.
 
@@ -279,7 +244,7 @@ class NadoBaseExecute:
         """
         params = deepcopy(params)
         params = self._inject_owner_if_needed(params)
-        params = self._inject_nonce_if_needed(params, use_order_nonce, is_trigger_order)
+        params = self._inject_nonce_if_needed(params, use_order_nonce)
         return params
 
     def _sign(
@@ -306,16 +271,11 @@ class NadoBaseExecute:
                 - For 'PLACE_ORDER', it's derived from the book address associated with the product_id.
                 - For other operations, it's the endpoint address.
         """
-        is_place_order = (
-            execute == NadoExecuteType.PLACE_ORDER
-            or execute == NadoExecuteType.PLACE_ISOLATED_ORDER
-        )
+        is_place_order = execute == NadoExecuteType.PLACE_ORDER
         if is_place_order and product_id is None:
-            raise ValueError(
-                "Missing `product_id` to sign place_order or place_isolated_order execute"
-            )
+            raise ValueError("Missing `product_id` to sign place_order execute")
         verifying_contract = (
-            self.book_addr(product_id)
+            self.order_verifying_contract(product_id)
             if is_place_order and product_id
             else self.endpoint_addr
         )
@@ -376,10 +336,9 @@ class NadoBaseExecute:
         Returns:
             str: The generated EIP-712 signature.
         """
+        typed_data = build_eip712_typed_data(execute, msg, verifying_contract, chain_id)
         return sign_eip712_typed_data(
-            typed_data=build_eip712_typed_data(
-                execute, msg, verifying_contract, chain_id
-            ),
+            typed_data=typed_data,
             signer=signer,
         )
 
@@ -398,6 +357,6 @@ class NadoBaseExecute:
         return self.build_digest(
             NadoExecuteType.PLACE_ORDER,
             order.dict(),
-            self.book_addr(product_id),
+            self.order_verifying_contract(product_id),
             self.chain_id,
         )

nado_protocol/utils/expiration.py

@@ -1,4 +1,5 @@
 from enum import IntEnum
+import time
 
 
 class OrderType(IntEnum):
@@ -8,38 +9,16 @@ class OrderType(IntEnum):
     POST_ONLY = 3
 
 
-def get_expiration_timestamp(
-    order_type: OrderType, expiration: int, reduce_only: bool = False
-) -> int:
+def get_expiration_timestamp(seconds_from_now: int) -> int:
     """
-    Encodes the order type into the expiration timestamp for special order types such as immediate-or-cancel.
+    Returns a timestamp that is seconds_from_now in the future.
 
-    Args:
-        order_type (OrderType): The type of order.
-
-        expiration (int): The expiration timestamp in UNIX seconds.
-
-        reduce_only (bool): When True, the order can only reduce the size of an existing position. Works only with IOC & FOK.
-
-    Returns:
-        int: The properly formatted timestamp needed for the specified order type.
-    """
-    expiration = int(expiration) | (order_type << 62)
-    if reduce_only:
-        expiration |= 1 << 61
-    return expiration
-
-
-def decode_expiration(expiration: int) -> tuple[OrderType, int]:
-    """
-    Decodes the expiration timestamp to retrieve the order type and original expiration timestamp.
+    Order types and reduce-only flags should now be set using build_appendix().
 
     Args:
-        expiration (int): The encoded expiration timestamp.
+        seconds_from_now (int): Number of seconds from now for expiration.
 
     Returns:
-        Tuple[OrderType, int]: The decoded order type and the original expiration timestamp.
+        int: The expiration timestamp.
     """
-    order_type: OrderType = OrderType(expiration >> 62)
-    exp_timestamp = expiration & ((1 << 62) - 1)
-    return order_type, exp_timestamp
+    return int(time.time()) + seconds_from_now

nado_protocol/utils/nonce.py

@@ -6,7 +6,6 @@ import random
 def gen_order_nonce(
     recv_time_ms: Optional[int] = None,
     random_int: Optional[int] = None,
-    is_trigger_order: bool = False,
 ) -> int:
     """
     Generates an order nonce based on a received timestamp and a random integer.
@@ -27,7 +26,4 @@ def gen_order_nonce(
         random_int = random.randint(0, 999)
 
     nonce = (recv_time_ms << 20) + random_int
-
-    if is_trigger_order:
-        nonce = nonce | (1 << 63)
     return nonce

nado_protocol/utils/order.py

@@ -0,0 +1,356 @@
+from typing import Optional
+from enum import IntEnum
+from nado_protocol.utils.expiration import OrderType
+
+
+# Order appendix version
+APPENDIX_VERSION = 0
+
+
+class AppendixBitFields:
+    # | value   | reserved | trigger | reduce only | order type| isolated | version |
+    # | 96 bits | 18 bits  | 2 bits  | 1 bit       | 2 bits    | 1 bit    | 8 bits  |
+    # | 127..32 | 31..14   | 13..12  | 11          | 10..9     | 8        | 7..0    |
+
+    # Bit positions (from LSB to MSB)
+    VERSION_BITS = 8  # bits 7..0
+    ISOLATED_BITS = 1  # bit 8
+    ORDER_TYPE_BITS = 2  # bits 10..9
+    REDUCE_ONLY_BITS = 1  # bit 11
+    TRIGGER_TYPE_BITS = 2  # bits 13..12
+    RESERVED_BITS = 18  # bits 31..14
+    VALUE_BITS = 96  # bits 127..32 (for isolated margin or TWAP data)
+
+    # Bit masks
+    VERSION_MASK = (1 << VERSION_BITS) - 1
+    ISOLATED_MASK = (1 << ISOLATED_BITS) - 1
+    ORDER_TYPE_MASK = (1 << ORDER_TYPE_BITS) - 1
+    REDUCE_ONLY_MASK = (1 << REDUCE_ONLY_BITS) - 1
+    TRIGGER_TYPE_MASK = (1 << TRIGGER_TYPE_BITS) - 1
+    RESERVED_MASK = (1 << RESERVED_BITS) - 1
+    VALUE_MASK = (1 << VALUE_BITS) - 1
+
+    # Bit shift positions
+    VERSION_SHIFT = 0
+    ISOLATED_SHIFT = 8
+    ORDER_TYPE_SHIFT = 9
+    REDUCE_ONLY_SHIFT = 11
+    TRIGGER_TYPE_SHIFT = 12
+    RESERVED_SHIFT = 14
+    VALUE_SHIFT = 32
+
+
+class OrderAppendixTriggerType(IntEnum):
+    """
+    Enumeration for trigger order types encoded in the appendix.
+    """
+
+    PRICE = 1
+    TWAP = 2
+    TWAP_CUSTOM_AMOUNTS = 3
+
+
+class TWAPBitFields:
+    """Bit field definitions for TWAP value packing within the 96-bit value field."""
+
+    # Bit layout (MSB → LSB): | times (32 bits) | slippage_x6 (32 bits) | reserved (32 bits) |
+    TIMES_BITS = 32
+    SLIPPAGE_BITS = 32
+    RESERVED_BITS = 32
+
+    # Bit masks
+    TIMES_MASK = (1 << TIMES_BITS) - 1
+    SLIPPAGE_MASK = (1 << SLIPPAGE_BITS) - 1
+    RESERVED_MASK = (1 << RESERVED_BITS) - 1
+
+    # Bit shift positions (within the 96-bit value field)
+    RESERVED_SHIFT = 0
+    SLIPPAGE_SHIFT = 32
+    TIMES_SHIFT = 64
+
+    # Slippage scaling factor (6 decimal places)
+    SLIPPAGE_SCALE = 1_000_000
+
+
+def pack_twap_appendix_value(times: int, slippage_frac: float) -> int:
+    """
+    Packs TWAP order fields into a 96-bit integer for the appendix.
+
+    Bit layout (MSB → LSB):
+    |   times   | slippage_x6 | reserved |
+    |-----------|-------------|----------|
+    | 95..64    | 63..32      | 31..0    |
+    | 32 bits   | 32 bits     | 32 bits  |
+    """
+    slippage_x6 = int(slippage_frac * TWAPBitFields.SLIPPAGE_SCALE)
+    reserved = 0  # reserved 32-bit field (currently unused)
+
+    return (
+        ((times & TWAPBitFields.TIMES_MASK) << TWAPBitFields.TIMES_SHIFT)
+        | ((slippage_x6 & TWAPBitFields.SLIPPAGE_MASK) << TWAPBitFields.SLIPPAGE_SHIFT)
+        | ((reserved & TWAPBitFields.RESERVED_MASK) << TWAPBitFields.RESERVED_SHIFT)
+    )
+
+
+def unpack_twap_appendix_value(value: int) -> tuple[int, float]:
+    """
+    Unpacks a 96-bit integer into TWAP order fields.
+
+    Args:
+        value (int): The 96-bit value to unpack.
+
+    Returns:
+        tuple[int, float]: Number of TWAP executions and slippage fraction.
+    """
+    times = (value >> TWAPBitFields.TIMES_SHIFT) & TWAPBitFields.TIMES_MASK
+    slippage_x6 = (value >> TWAPBitFields.SLIPPAGE_SHIFT) & TWAPBitFields.SLIPPAGE_MASK
+    slippage_frac = slippage_x6 / TWAPBitFields.SLIPPAGE_SCALE
+
+    return int(times), slippage_frac
+
+
+def build_appendix(
+    order_type: OrderType,
+    isolated: bool = False,
+    reduce_only: bool = False,
+    trigger_type: Optional[OrderAppendixTriggerType] = None,
+    isolated_margin: Optional[int] = None,
+    twap_times: Optional[int] = None,
+    twap_slippage_frac: Optional[float] = None,
+    _version: Optional[int] = APPENDIX_VERSION,
+) -> int:
+    """
+    Builds an appendix value with the specified parameters.
+
+    Args:
+        order_type (OrderType): The order execution type. Required.
+        isolated (bool): Whether this order is for an isolated position. Defaults to False.
+        reduce_only (bool): Whether this is a reduce-only order. Defaults to False.
+        trigger_type (Optional[OrderAppendixTriggerType]): Trigger type. Defaults to None (no trigger).
+        isolated_margin (Optional[int]): Margin amount for isolated position if isolated is True.
+        twap_times (Optional[int]): Number of TWAP executions (required for TWAP trigger type).
+        twap_slippage_frac (Optional[float]): TWAP slippage fraction (required for TWAP trigger type).
+
+    Returns:
+        int: The built appendix value with version set to APPENDIX_VERSION.
+
+    Raises:
+        ValueError: If parameters are invalid or incompatible.
+    """
+    if isolated_margin is not None and not isolated:
+        raise ValueError("isolated_margin can only be set when isolated=True")
+
+    if (
+        isolated
+        and trigger_type is not None
+        and trigger_type
+        in [OrderAppendixTriggerType.TWAP, OrderAppendixTriggerType.TWAP_CUSTOM_AMOUNTS]
+    ):
+        raise ValueError("An order cannot be both isolated and a TWAP order")
+
+    if trigger_type is not None and trigger_type in [
+        OrderAppendixTriggerType.TWAP,
+        OrderAppendixTriggerType.TWAP_CUSTOM_AMOUNTS,
+    ]:
+        if twap_times is None or twap_slippage_frac is None:
+            raise ValueError(
+                "twap_times and twap_slippage_frac are required for TWAP orders"
+            )
+
+    appendix = 0
+
+    version = _version if _version is not None else APPENDIX_VERSION
+
+    # Version (bits 7..0)
+    appendix |= (
+        version & AppendixBitFields.VERSION_MASK
+    ) << AppendixBitFields.VERSION_SHIFT
+
+    # Isolated bit (bit 8)
+    if isolated:
+        appendix |= 1 << AppendixBitFields.ISOLATED_SHIFT
+
+    # Order type (bits 10..9) - 2 bits only
+    appendix |= (
+        int(order_type) & AppendixBitFields.ORDER_TYPE_MASK
+    ) << AppendixBitFields.ORDER_TYPE_SHIFT
+
+    # Reduce only bit (bit 11)
+    if reduce_only:
+        appendix |= 1 << AppendixBitFields.REDUCE_ONLY_SHIFT
+
+    # Trigger type (bits 13..12) - default to 0 if None
+    trigger_value = 0 if trigger_type is None else int(trigger_type)
+    appendix |= (
+        trigger_value & AppendixBitFields.TRIGGER_TYPE_MASK
+    ) << AppendixBitFields.TRIGGER_TYPE_SHIFT
+
+    # Handle upper bits (127..32) based on order type
+    if isolated and isolated_margin is not None:
+        # Isolated margin (bits 127..32)
+        appendix |= (
+            isolated_margin & AppendixBitFields.VALUE_MASK
+        ) << AppendixBitFields.VALUE_SHIFT
+    elif trigger_type is not None and trigger_type in [
+        OrderAppendixTriggerType.TWAP,
+        OrderAppendixTriggerType.TWAP_CUSTOM_AMOUNTS,
+    ]:
+        # TWAP value (bits 127..32) - 96 bits
+        # These are guaranteed to be non-None due to validation above
+        assert twap_times is not None
+        assert twap_slippage_frac is not None
+        twap_value = pack_twap_appendix_value(twap_times, twap_slippage_frac)
+        appendix |= (
+            twap_value & AppendixBitFields.VALUE_MASK
+        ) << AppendixBitFields.VALUE_SHIFT
+
+    return appendix
+
+
+def gen_order_verifying_contract(product_id: int) -> str:
+    """
+    Generates the order verifying contract address based on the product ID.
+
+    Args:
+        product_id (int): The product ID for which to generate the verifying contract address.
+
+    Returns:
+        str: The generated order verifying contract address in hexadecimal format.
+    """
+    be_bytes = product_id.to_bytes(20, byteorder="big", signed=False)
+    return "0x" + be_bytes.hex()
+
+
+def order_reduce_only(appendix: int) -> bool:
+    """
+    Checks if the order is reduce-only based on the appendix value.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        bool: True if the order is reduce-only, False otherwise.
+    """
+    return (
+        appendix >> AppendixBitFields.REDUCE_ONLY_SHIFT
+        & AppendixBitFields.REDUCE_ONLY_MASK
+    ) == 1
+
+
+def order_is_trigger_order(appendix: int) -> bool:
+    """
+    Checks if the order is a trigger order based on the appendix value.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        bool: True if the order is a trigger order, False otherwise.
+    """
+    return (
+        appendix >> AppendixBitFields.TRIGGER_TYPE_SHIFT
+        & AppendixBitFields.TRIGGER_TYPE_MASK
+    ) > 0
+
+
+def order_is_isolated(appendix: int) -> bool:
+    """
+    Checks if the order is for an isolated position based on the appendix value.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        bool: True if the order is for an isolated position, False otherwise.
+    """
+    return (
+        appendix >> AppendixBitFields.ISOLATED_SHIFT & AppendixBitFields.ISOLATED_MASK
+    ) == 1
+
+
+def order_isolated_margin(appendix: int) -> Optional[int]:
+    """
+    Extracts the isolated margin amount from the appendix value.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        Optional[int]: The isolated margin amount if the order is isolated, None otherwise.
+    """
+    if order_is_isolated(appendix):
+        return (
+            appendix >> AppendixBitFields.VALUE_SHIFT
+        ) & AppendixBitFields.VALUE_MASK
+    return None
+
+
+def order_version(appendix: int) -> int:
+    """
+    Extracts the version from the appendix value.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        int: The version number (bits 7..0).
+    """
+    return (
+        appendix >> AppendixBitFields.VERSION_SHIFT
+    ) & AppendixBitFields.VERSION_MASK
+
+
+def order_trigger_type(appendix: int) -> Optional[OrderAppendixTriggerType]:
+    """
+    Extracts the trigger type from the appendix value.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        Optional[OrderAppendixTriggerType]: The trigger type, or None if no trigger is set.
+    """
+    trigger_bits = (
+        appendix >> AppendixBitFields.TRIGGER_TYPE_SHIFT
+    ) & AppendixBitFields.TRIGGER_TYPE_MASK
+    if trigger_bits == 0:
+        return None
+    return OrderAppendixTriggerType(trigger_bits)
+
+
+def order_twap_data(appendix: int) -> Optional[tuple[int, float]]:
+    """
+    Extracts TWAP data from the appendix value if it's a TWAP order.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        Optional[tuple[int, float]]: Tuple of (times, slippage_frac) if TWAP, None otherwise.
+    """
+    trigger_type = order_trigger_type(appendix)
+    if trigger_type is not None and trigger_type in [
+        OrderAppendixTriggerType.TWAP,
+        OrderAppendixTriggerType.TWAP_CUSTOM_AMOUNTS,
+    ]:
+        twap_value = (
+            appendix >> AppendixBitFields.VALUE_SHIFT
+        ) & AppendixBitFields.VALUE_MASK
+        return unpack_twap_appendix_value(twap_value)
+    return None
+
+
+def order_execution_type(appendix: int) -> OrderType:
+    """
+    Extracts the order execution type from the appendix value.
+
+    Args:
+        appendix (int): The order appendix value.
+
+    Returns:
+        OrderType: The order execution type.
+    """
+    order_type_bits = (
+        appendix >> AppendixBitFields.ORDER_TYPE_SHIFT
+    ) & AppendixBitFields.ORDER_TYPE_MASK
+    return OrderType(order_type_bits)

{nado_protocol-0.1.0.dist-info → nado_protocol-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nado-protocol
-Version: 0.1.0
+Version: 0.1.2
 Summary: Nado Protocol SDK
 Keywords: nado protocol,nado sdk,nado protocol api
 Author: Jeury Mejia
@@ -54,6 +54,7 @@ from nado_protocol.engine_client.types.execute import (
 from nado_protocol.utils.expiration import OrderType, get_expiration_timestamp
 from nado_protocol.utils.math import to_pow_10, to_x18
 from nado_protocol.utils.nonce import gen_order_nonce
+from nado_protocol.utils.order import build_appendix
 ```
 
 ### Create the NadoClient providing your private key:
@@ -95,8 +96,9 @@ order = OrderParams(
    ),
    priceX18=to_x18(20000),
    amount=to_pow_10(1, 17),
-   expiration=get_expiration_timestamp(OrderType.POST_ONLY, int(time.time()) + 40),
+   expiration=get_expiration_timestamp(40),
    nonce=gen_order_nonce(),
+   appendix=build_appendix(order_type=OrderType.POST_ONLY)
 )
 res = client.market.place_order({"product_id": product_id, "order": order})
 print("order result:", res.json(indent=2))