nado-protocol 0.1.0__py3-none-any.whl

nado_protocol/utils/bytes32.py

@@ -0,0 +1,159 @@
+import binascii
+from typing import Optional, Union
+from nado_protocol.utils.subaccount import Subaccount, SubaccountParams
+
+
+def hex_to_bytes32(input: Union[str, bytes]) -> bytes:
+    """Converts a hexadecimal string or bytes to a bytes object of length 32.
+
+    Args:
+        input (str | bytes): The hexadecimal string or bytes to be converted.
+
+    Returns:
+        bytes: The converted bytes object of length 32.
+    """
+    return hex_to_bytes(input, 32)
+
+
+def hex_to_bytes12(input: Union[str, bytes]) -> bytes:
+    """Converts a hexadecimal string or bytes to a bytes object of length 12.
+
+    Args:
+        input (str | bytes): The hexadecimal string or bytes to be converted.
+
+    Returns:
+        bytes: The converted bytes object of length 12.
+    """
+    return hex_to_bytes(input, 12)
+
+
+def hex_to_bytes(input: Union[str, bytes], size: int) -> bytes:
+    """Converts a hexadecimal string or bytes to a bytes object of specified size.
+
+    Args:
+        input (str | bytes): The hexadecimal string or bytes to be converted.
+
+        size (int): The specified size for the output bytes object.
+
+    Returns:
+        bytes: The converted bytes object of the specified size.
+    """
+    if isinstance(input, bytes):
+        return input
+    if input.encode() == zero_subaccount():
+        return zero_subaccount()
+    if input.startswith("0x"):
+        input = input[2:]
+    data_bytes = bytes.fromhex(input)
+    padded_data = data_bytes + b"\x00" * (size - len(data_bytes))
+    return padded_data
+
+
+def str_to_hex(input: str) -> str:
+    """Converts a string to its hexadecimal representation.
+
+    Args:
+        input (str): The string to be converted.
+
+    Returns:
+        str: The hexadecimal representation of the input string.
+    """
+    return binascii.hexlify(input.encode()).decode()
+
+
+def subaccount_to_bytes32(
+    subaccount: Subaccount, name: Optional[Union[str, bytes]] = None
+) -> bytes:
+    """Converts a subaccount representation to a bytes object of length 32.
+
+    Args:
+        subaccount (Subaccount): The subaccount, which can be a string, bytes, or SubaccountParams instance.
+
+        name (str|bytes, optional): The subaccount name, when provided `subaccount` is expected to be the owner address.
+
+    Returns:
+        (bytes|SubaccountParams): The bytes object of length 32 representing the subaccount.
+
+    Raises:
+        ValueError: If the `subaccount` is a `SubaccountParams` instance and is missing either `subaccount_owner` or `subaccount_name`
+
+    Note:
+        If `name` is provided, `subaccount` must be the owner address, otherwise `subaccount`
+        can be the bytes32 or hex representation of the subaccount or a SubaccountParams object.
+    """
+    if isinstance(subaccount, str):
+        if name is None:
+            return hex_to_bytes32(subaccount)
+        else:
+            name = name.hex() if isinstance(name, bytes) else name
+            return hex_to_bytes32(subaccount + str_to_hex(name))
+    elif isinstance(subaccount, SubaccountParams):
+        subaccount_owner = subaccount.dict().get("subaccount_owner")
+        subaccount_name = subaccount.dict().get("subaccount_name")
+        if subaccount_owner is None or subaccount_name is None:
+            raise ValueError("Missing `subaccount_owner` or `subaccount_name`")
+        else:
+            return hex_to_bytes32(subaccount_owner + str_to_hex(subaccount_name))
+    else:
+        return subaccount
+
+
+def subaccount_to_hex(
+    subaccount: Subaccount, name: Optional[Union[str, bytes]] = None
+) -> str:
+    """Converts a subaccount representation to its hexadecimal representation.
+
+    Args:
+        subaccount (Subaccount): The subaccount, which can be a string, bytes, or SubaccountParams instance.
+
+        name (str|bytes, optional): Additional string, if any, to be appended to the subaccount string before conversion. Defaults to None.
+
+    Returns:
+        (str|SubaccountParams): The hexadecimal representation of the subaccount.
+    """
+    return bytes32_to_hex(subaccount_to_bytes32(subaccount, name))
+
+
+def subaccount_name_to_bytes12(subaccount_name: str) -> bytes:
+    """Converts a subaccount name to a bytes object of length 12.
+
+    Args:
+        subaccount_name (str): The subaccount name to be converted.
+
+    Returns:
+        bytes: A bytes object of length 12 representing the subaccount name.
+    """
+    return hex_to_bytes12(str_to_hex(subaccount_name))
+
+
+def bytes32_to_hex(bytes32: bytes) -> str:
+    """Converts a bytes object of length 32 to its hexadecimal representation.
+
+    Args:
+        bytes32 (bytes): The bytes object of length 32 to be converted.
+
+    Returns:
+        str: The hexadecimal representation of the input bytes object. If the input is not a bytes object, the function returns the input itself.
+    """
+    if isinstance(bytes32, bytes):
+        return f"0x{bytes32.hex()}"
+    else:
+        return bytes32
+
+
+def zero_subaccount() -> bytes:
+    """Generates a bytes object of length 32 filled with zero bytes.
+
+    Returns:
+        bytes: A bytes object of length 32 filled with zero bytes.
+    """
+    return b"\x00" * 32
+
+
+def zero_address() -> bytes:
+    """Generates a bytes object of length 20 filled with zero bytes.
+
+    Returns:
+        bytes: A bytes object of length 20 filled with zero bytes.
+    """
+    return b"\x00" * 20

nado_protocol/utils/enum.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class StrEnum(str, Enum):
+    def __str__(self):
+        return self.value

nado_protocol/utils/exceptions.py

@@ -0,0 +1,58 @@
+class ExecuteFailedException(Exception):
+    """Raised when the execute status is not 'success'"""
+
+    def __init__(self, message="Execute failed"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class QueryFailedException(Exception):
+    """Raised when the query status is not 'success'"""
+
+    def __init__(self, message="Query failed"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class BadStatusCodeException(Exception):
+    """Raised when the response status code is not 200"""
+
+    def __init__(self, message="Bad status code"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class MissingSignerException(Exception):
+    """Raised when the Signer is required to perform an operation but it's not provided."""
+
+    def __init__(self, message="Signer not provided"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class InvalidProductId(Exception):
+    """Raised when product id is invalid."""
+
+    def __init__(self, message="Invalid product id provided"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class InvalidVrtxClaimParams(Exception):
+    """Raised when providing invalid VRTX claim parameters."""
+
+    def __init__(
+        self,
+        message="Invalid VRTX params. Either `amount` or `claim_all` must be provided",
+    ):
+        self.message = message
+        super().__init__(self.message)
+
+
+class MissingTriggerClient(Exception):
+    def __init__(
+        self,
+        message="Trigger client not initialized.",
+    ):
+        self.message = message
+        super().__init__(self.message)

nado_protocol/utils/execute.py

@@ -0,0 +1,403 @@
+from abc import abstractmethod
+from copy import deepcopy
+from typing import Optional, Type, Union
+from eth_account.signers.local import LocalAccount
+from pydantic import validator
+from nado_protocol.contracts.eip712.sign import (
+    build_eip712_typed_data,
+    get_eip712_typed_data_digest,
+    sign_eip712_typed_data,
+)
+from nado_protocol.contracts.types import NadoExecuteType
+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.subaccount import Subaccount, SubaccountParams
+
+
+class BaseParams(NadoBaseModel):
+    """
+    Base class for defining request parameters to be sent to the Nado API.
+
+    Attributes:
+        sender (Subaccount): The sender's subaccount identifier.
+        nonce (Optional[int]): An optional nonce for the request.
+
+    Note:
+        - The sender attribute is validated and serialized to bytes32 format before sending the request.
+    """
+
+    sender: Subaccount
+    nonce: Optional[int]
+
+    class Config:
+        validate_assignment = True
+
+    @validator("sender")
+    def serialize_sender(cls, v: Subaccount) -> Union[bytes, Subaccount]:
+        """
+        Validates and serializes the sender to bytes32 format.
+
+        Args:
+            v (Subaccount): The sender's subaccount identifier.
+
+        Returns:
+            (bytes|Subaccount): The serialized sender in bytes32 format or the original Subaccount if it cannot be converted to bytes32.
+        """
+        try:
+            return subaccount_to_bytes32(v)
+        except ValueError:
+            return v
+
+
+class SignatureParams(NadoBaseModel):
+    """
+    Class for defining signature parameters in a request sent to the Nado API.
+
+    Attributes:
+        signature (Optional[str]): An optional string representing the signature for the request.
+    """
+
+    signature: Optional[str]
+
+
+class BaseParamsSigned(BaseParams, SignatureParams):
+    """
+    Class that combines the base parameters and signature parameters for a signed request
+    to the Nado API. Inherits attributes from BaseParams and SignatureParams.
+    """
+
+    pass
+
+
+class MarketOrderParams(BaseParams):
+    """
+    Class for defining the parameters of a market order.
+
+    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):
+    """
+    Class for defining the parameters of an 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.
+    """
+
+    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
+
+
+class NadoBaseExecute:
+    def __init__(self, opts: NadoClientOpts):
+        self._opts = opts
+
+    @abstractmethod
+    def tx_nonce(self, _: str) -> int:
+        pass
+
+    @property
+    def endpoint_addr(self) -> str:
+        if self._opts.endpoint_addr is None:
+            raise AttributeError("Endpoint address not set.")
+        return self._opts.endpoint_addr
+
+    @endpoint_addr.setter
+    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:
+            raise AttributeError("Chain ID is not set.")
+        return self._opts.chain_id
+
+    @chain_id.setter
+    def chain_id(self, chain_id: Union[int, str]) -> None:
+        self._opts.chain_id = int(chain_id)
+
+    @property
+    def signer(self) -> LocalAccount:
+        if self._opts.signer is None:
+            raise AttributeError("Signer is not set.")
+        assert isinstance(self._opts.signer, LocalAccount)
+        return self._opts.signer
+
+    @signer.setter
+    def signer(self, signer: LocalAccount) -> None:
+        self._opts.signer = signer
+
+    @property
+    def linked_signer(self) -> LocalAccount:
+        if self._opts.linked_signer is not None:
+            assert isinstance(self._opts.linked_signer, LocalAccount)
+            return self._opts.linked_signer
+        if self._opts.signer is not None:
+            assert isinstance(self._opts.signer, LocalAccount)
+            return self.signer
+        raise AttributeError("Signer is not set.")
+
+    @linked_signer.setter
+    def linked_signer(self, linked_signer: LocalAccount) -> None:
+        if self._opts.signer is None:
+            raise AttributeError(
+                "Must set a `signer` first before setting `linked_signer`."
+            )
+        self._opts.linked_signer = linked_signer
+
+    def book_addr(self, product_id: int) -> str:
+        """
+        Retrieves the book address corresponding to the provided product ID.
+
+        Needed for signing order placement executes for different products.
+
+        Args:
+            product_id (int): The ID of the product.
+
+        Returns:
+            str: The book address associated with the given product ID.
+
+        Raises:
+            ValueError: If the provided product_id is greater than or equal to the number of book addresses available.
+        """
+        if product_id >= len(self.book_addrs):
+            raise ValueError(f"Invalid product_id {product_id} provided.")
+        return self.book_addrs[product_id]
+
+    def order_nonce(
+        self, recv_time_ms: Optional[int] = None, is_trigger_order: bool = False
+    ) -> int:
+        """
+        Generate the order nonce. Used for oder placements and cancellations.
+
+        Args:
+            recv_time_ms (int, optional): Received time in milliseconds.
+
+        Returns:
+            int: The generated order nonce.
+        """
+        return gen_order_nonce(recv_time_ms, is_trigger_order=is_trigger_order)
+
+    def _inject_owner_if_needed(self, params: Type[BaseParams]) -> Type[BaseParams]:
+        """
+        Inject the owner if needed.
+
+        Args:
+            params (Type[BaseParams]): The parameters.
+
+        Returns:
+            Type[BaseParams]: The parameters with the owner injected if needed.
+        """
+        if isinstance(params.sender, SubaccountParams):
+            params.sender.subaccount_owner = (
+                params.sender.subaccount_owner or self.signer.address
+            )
+            params.sender = params.serialize_sender(params.sender)
+        return params
+
+    def _inject_nonce_if_needed(
+        self,
+        params: Type[BaseParams],
+        use_order_nonce: bool,
+        is_trigger_order: bool = False,
+    ) -> Type[BaseParams]:
+        """
+        Inject the nonce if needed.
+
+        Args:
+            params (Type[BaseParams]): The parameters.
+
+        Returns:
+            Type[BaseParams]: The parameters with the nonce injected if needed.
+        """
+        if params.nonce is not None:
+            return params
+        params.nonce = (
+            self.order_nonce(is_trigger_order=is_trigger_order)
+            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
+    ):
+        """
+        Prepares the parameters for execution by ensuring that both owner and nonce are correctly set.
+
+        Args:
+            params (Type[BaseParams]): The original parameters.
+
+        Returns:
+            Type[BaseParams]: A copy of the original parameters with owner and nonce injected if needed.
+        """
+        params = deepcopy(params)
+        params = self._inject_owner_if_needed(params)
+        params = self._inject_nonce_if_needed(params, use_order_nonce, is_trigger_order)
+        return params
+
+    def _sign(
+        self, execute: NadoExecuteType, msg: dict, product_id: Optional[int] = None
+    ) -> str:
+        """
+        Internal method to create an EIP-712 signature for the given operation type and message.
+
+        Args:
+            execute (NadoExecuteType): The Nado execute type to sign.
+
+            msg (dict): The message to be signed.
+
+            product_id (int, optional): Required for 'PLACE_ORDER' operation, specifying the product ID.
+
+        Returns:
+            str: The generated EIP-712 signature.
+
+        Raises:
+            ValueError: If the operation type is 'PLACE_ORDER' and no product_id is provided.
+
+        Notes:
+            The contract used for verification varies based on the operation type:
+                - 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
+        )
+        if is_place_order and product_id is None:
+            raise ValueError(
+                "Missing `product_id` to sign place_order or place_isolated_order execute"
+            )
+        verifying_contract = (
+            self.book_addr(product_id)
+            if is_place_order and product_id
+            else self.endpoint_addr
+        )
+        return self.sign(
+            execute, msg, verifying_contract, self.chain_id, self.linked_signer
+        )
+
+    def build_digest(
+        self,
+        execute: NadoExecuteType,
+        msg: dict,
+        verifying_contract: str,
+        chain_id: int,
+    ) -> str:
+        """
+        Build an EIP-712 compliant digest from given parameters.
+
+        Must provide the same input to build an EIP-712 typed data as the one provided for signing via `.sign(...)`
+
+        Args:
+            execute (NadoExecuteType): The Nado execute type to build digest for.
+
+            msg (dict): The EIP712 message.
+
+            verifying_contract (str): The contract used for verification.
+
+            chain_id (int): The network chain ID.
+
+        Returns:
+            str: The digest computed from the provided parameters.
+        """
+        return get_eip712_typed_data_digest(
+            build_eip712_typed_data(execute, msg, verifying_contract, chain_id)
+        )
+
+    def sign(
+        self,
+        execute: NadoExecuteType,
+        msg: dict,
+        verifying_contract: str,
+        chain_id: int,
+        signer: LocalAccount,
+    ) -> str:
+        """
+        Signs the EIP-712 typed data using the provided signer account.
+
+        Args:
+            execute (NadoExecuteType): The type of operation.
+
+            msg (dict): The message to be signed.
+
+            verifying_contract (str): The contract used for verification.
+
+            chain_id (int): The network chain ID.
+
+            signer (LocalAccount): The account used to sign the data.
+
+        Returns:
+            str: The generated EIP-712 signature.
+        """
+        return sign_eip712_typed_data(
+            typed_data=build_eip712_typed_data(
+                execute, msg, verifying_contract, chain_id
+            ),
+            signer=signer,
+        )
+
+    def get_order_digest(self, order: OrderParams, product_id: int) -> str:
+        """
+        Generates the order digest for a given order and product ID.
+
+        Args:
+            order (OrderParams): The order parameters.
+
+            product_id (int): The ID of the product.
+
+        Returns:
+            str: The generated order digest.
+        """
+        return self.build_digest(
+            NadoExecuteType.PLACE_ORDER,
+            order.dict(),
+            self.book_addr(product_id),
+            self.chain_id,
+        )

nado_protocol/utils/expiration.py

@@ -0,0 +1,45 @@
+from enum import IntEnum
+
+
+class OrderType(IntEnum):
+    DEFAULT = 0
+    IOC = 1
+    FOK = 2
+    POST_ONLY = 3
+
+
+def get_expiration_timestamp(
+    order_type: OrderType, expiration: int, reduce_only: bool = False
+) -> int:
+    """
+    Encodes the order type into the expiration timestamp for special order types such as immediate-or-cancel.
+
+    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.
+
+    Args:
+        expiration (int): The encoded expiration timestamp.
+
+    Returns:
+        Tuple[OrderType, int]: The decoded order type and the original expiration timestamp.
+    """
+    order_type: OrderType = OrderType(expiration >> 62)
+    exp_timestamp = expiration & ((1 << 62) - 1)
+    return order_type, exp_timestamp