nado-protocol 0.1.0__py3-none-any.whl

nado_protocol/trigger_client/__init__.py

@@ -0,0 +1,17 @@
+from nado_protocol.trigger_client.types import TriggerClientOpts
+from nado_protocol.trigger_client.execute import TriggerExecuteClient
+from nado_protocol.trigger_client.query import TriggerQueryClient
+
+
+class TriggerClient(TriggerQueryClient, TriggerExecuteClient):  # type: ignore
+    def __init__(self, opts: TriggerClientOpts):
+        TriggerQueryClient.__init__(self, opts)
+        TriggerExecuteClient.__init__(self, opts)
+
+
+__all__ = [
+    "TriggerClient",
+    "TriggerClientOpts",
+    "TriggerExecuteClient",
+    "TriggerQueryClient",
+]

nado_protocol/trigger_client/execute.py

@@ -0,0 +1,118 @@
+import requests
+from functools import singledispatchmethod
+from typing import Union
+from nado_protocol.contracts.types import NadoExecuteType
+from nado_protocol.trigger_client.types.execute import (
+    TriggerExecuteParams,
+    TriggerExecuteRequest,
+    PlaceTriggerOrderParams,
+    CancelTriggerOrdersParams,
+    CancelProductTriggerOrdersParams,
+    to_trigger_execute_request,
+)
+from nado_protocol.engine_client.types.execute import ExecuteResponse
+from nado_protocol.trigger_client.types import TriggerClientOpts
+from nado_protocol.utils.exceptions import (
+    BadStatusCodeException,
+    ExecuteFailedException,
+)
+from nado_protocol.utils.execute import NadoBaseExecute
+from nado_protocol.utils.model import NadoBaseModel, is_instance_of_union
+
+
+class TriggerExecuteClient(NadoBaseExecute):
+    def __init__(self, opts: TriggerClientOpts):
+        super().__init__(opts)
+        self._opts: TriggerClientOpts = TriggerClientOpts.parse_obj(opts)
+        self.url: str = self._opts.url
+        self.session = requests.Session()
+
+    def tx_nonce(self, _: str) -> int:
+        raise NotImplementedError
+
+    @singledispatchmethod
+    def execute(
+        self, params: Union[TriggerExecuteParams, TriggerExecuteRequest]
+    ) -> ExecuteResponse:
+        """
+        Executes the operation defined by the provided parameters.
+
+        Args:
+            params (ExecuteParams): The parameters for the operation to execute. This can represent a variety of operations, such as placing orders, cancelling orders, and more.
+
+        Returns:
+            ExecuteResponse: The response from the executed operation.
+        """
+        req: TriggerExecuteRequest = (
+            params if is_instance_of_union(params, TriggerExecuteRequest) else to_trigger_execute_request(params)  # type: ignore
+        )
+        return self._execute(req)
+
+    @execute.register
+    def _(self, req: dict) -> ExecuteResponse:
+        """
+        Overloaded method to execute the operation defined by the provided request.
+
+        Args:
+            req (dict): The request data for the operation to execute. Can be a dictionary or an instance of ExecuteRequest.
+
+        Returns:
+            ExecuteResponse: The response from the executed operation.
+        """
+        parsed_req: TriggerExecuteRequest = NadoBaseModel.parse_obj(req)  # type: ignore
+        return self._execute(parsed_req)
+
+    def _execute(self, req: TriggerExecuteRequest) -> ExecuteResponse:
+        """
+        Internal method to execute the operation. Sends request to the server.
+
+        Args:
+            req (TriggerExecuteRequest): The request data for the operation to execute.
+
+        Returns:
+            ExecuteResponse: The response from the executed operation.
+
+        Raises:
+            BadStatusCodeException: If the server response status code is not 200.
+            ExecuteFailedException: If there's an error in the execution or the response status is not "success".
+        """
+        res = self.session.post(f"{self.url}/execute", json=req.dict())
+        if res.status_code != 200:
+            raise BadStatusCodeException(res.text)
+        try:
+            execute_res = ExecuteResponse(**res.json(), req=req.dict())
+        except Exception:
+            raise ExecuteFailedException(res.text)
+        if execute_res.status != "success":
+            raise ExecuteFailedException(res.text)
+        return execute_res
+
+    def place_trigger_order(self, params: PlaceTriggerOrderParams) -> ExecuteResponse:
+        params = PlaceTriggerOrderParams.parse_obj(params)
+        params.order = self.prepare_execute_params(params.order, True, True)
+        params.signature = params.signature or self._sign(
+            NadoExecuteType.PLACE_ORDER, params.order.dict(), params.product_id
+        )
+        return self.execute(params)
+
+    def cancel_trigger_orders(
+        self, params: CancelTriggerOrdersParams
+    ) -> ExecuteResponse:
+        params = self.prepare_execute_params(
+            CancelTriggerOrdersParams.parse_obj(params), True
+        )
+        params.signature = params.signature or self._sign(
+            NadoExecuteType.CANCEL_ORDERS, params.dict()
+        )
+        return self.execute(params)
+
+    def cancel_product_trigger_orders(
+        self, params: CancelProductTriggerOrdersParams
+    ) -> ExecuteResponse:
+        params = self.prepare_execute_params(
+            CancelProductTriggerOrdersParams.parse_obj(params), True
+        )
+        params.signature = params.signature or self._sign(
+            NadoExecuteType.CANCEL_PRODUCT_ORDERS, params.dict()
+        )
+        return self.execute(params)

nado_protocol/trigger_client/query.py

@@ -0,0 +1,61 @@
+import requests
+from nado_protocol.contracts.types import NadoTxType
+from nado_protocol.trigger_client.types import TriggerClientOpts
+from nado_protocol.trigger_client.types.query import (
+    ListTriggerOrdersParams,
+    ListTriggerOrdersRequest,
+    TriggerQueryResponse,
+)
+from nado_protocol.utils.exceptions import (
+    BadStatusCodeException,
+    QueryFailedException,
+)
+from nado_protocol.utils.execute import NadoBaseExecute
+
+
+class TriggerQueryClient(NadoBaseExecute):
+    """
+    Client class for querying the trigger service.
+    """
+
+    def __init__(self, opts: TriggerClientOpts):
+        self._opts: TriggerClientOpts = TriggerClientOpts.parse_obj(opts)
+        self.url: str = self._opts.url
+        self.session = requests.Session()  # type: ignore
+
+    def tx_nonce(self, _: str) -> int:
+        raise NotImplementedError
+
+    def query(self, req: dict) -> TriggerQueryResponse:
+        """
+        Send a query to the trigger service.
+
+        Args:
+            req (QueryRequest): The query request parameters.
+
+        Returns:
+            QueryResponse: The response from the engine.
+
+        Raises:
+            BadStatusCodeException: If the response status code is not 200.
+            QueryFailedException: If the query status is not "success".
+        """
+        res = self.session.post(f"{self.url}/query", json=req)
+        if res.status_code != 200:
+            raise BadStatusCodeException(res.text)
+        try:
+            query_res = TriggerQueryResponse(**res.json())
+        except Exception:
+            raise QueryFailedException(res.text)
+        if query_res.status != "success":
+            raise QueryFailedException(res.text)
+        return query_res
+
+    def list_trigger_orders(
+        self, params: ListTriggerOrdersParams
+    ) -> TriggerQueryResponse:
+        params = ListTriggerOrdersParams.parse_obj(params)
+        params.signature = params.signature or self._sign(
+            NadoTxType.LIST_TRIGGER_ORDERS, params.tx.dict()
+        )
+        return self.query(ListTriggerOrdersRequest.parse_obj(params).dict())

nado_protocol/trigger_client/types/__init__.py

@@ -0,0 +1,7 @@
+from nado_protocol.utils.backend import NadoClientOpts
+
+
+class TriggerClientOpts(NadoClientOpts):
+    """
+    Model defining the configuration options for the Trigger Client.
+    """

nado_protocol/trigger_client/types/execute.py

@@ -0,0 +1,89 @@
+from typing import Union
+from pydantic import validator
+from nado_protocol.contracts.types import NadoExecuteType
+from nado_protocol.utils.bytes32 import bytes32_to_hex
+from nado_protocol.utils.model import NadoBaseModel
+from nado_protocol.engine_client.types.execute import (
+    PlaceOrderParams,
+    CancelOrdersParams,
+    CancelProductOrdersParams,
+    CancelOrdersRequest,
+    CancelProductOrdersRequest,
+)
+from nado_protocol.trigger_client.types.models import TriggerCriteria
+
+
+class PlaceTriggerOrderParams(PlaceOrderParams):
+    trigger: TriggerCriteria
+
+
+CancelTriggerOrdersParams = CancelOrdersParams
+CancelProductTriggerOrdersParams = CancelProductOrdersParams
+
+TriggerExecuteParams = Union[
+    PlaceTriggerOrderParams, CancelTriggerOrdersParams, CancelProductTriggerOrdersParams
+]
+
+
+class PlaceTriggerOrderRequest(NadoBaseModel):
+    """
+    Parameters for a request to place an order.
+
+    Attributes:
+        place_order (PlaceOrderParams): The parameters for the order to be placed.
+
+    Methods:
+        serialize: Validates and serializes the order parameters.
+    """
+
+    place_order: PlaceTriggerOrderParams
+
+    @validator("place_order")
+    def serialize(cls, v: PlaceTriggerOrderParams) -> PlaceTriggerOrderParams:
+        if v.order.nonce is None:
+            raise ValueError("Missing order `nonce`")
+        if v.signature is None:
+            raise ValueError("Missing `signature")
+        if isinstance(v.order.sender, bytes):
+            v.order.serialize_dict(["sender"], bytes32_to_hex)
+        v.order.serialize_dict(["nonce", "priceX18", "amount", "expiration"], str)
+        return v
+
+
+CancelTriggerOrdersRequest = CancelOrdersRequest
+CancelProductTriggerOrdersRequest = CancelProductOrdersRequest
+
+TriggerExecuteRequest = Union[
+    PlaceTriggerOrderRequest,
+    CancelTriggerOrdersRequest,
+    CancelProductTriggerOrdersRequest,
+]
+
+
+def to_trigger_execute_request(params: TriggerExecuteParams) -> TriggerExecuteRequest:
+    """
+    Maps `TriggerExecuteParams` to its corresponding `TriggerExecuteRequest` object based on the parameter type.
+
+    Args:
+        params (TriggerExecuteParams): The parameters to be executed.
+
+    Returns:
+        TriggerExecuteRequest: The corresponding `TriggerExecuteRequest` object.
+    """
+    execute_request_mapping = {
+        PlaceTriggerOrderParams: (
+            PlaceTriggerOrderRequest,
+            NadoExecuteType.PLACE_ORDER.value,
+        ),
+        CancelTriggerOrdersParams: (
+            CancelTriggerOrdersRequest,
+            NadoExecuteType.CANCEL_ORDERS.value,
+        ),
+        CancelProductTriggerOrdersParams: (
+            CancelProductTriggerOrdersRequest,
+            NadoExecuteType.CANCEL_PRODUCT_ORDERS.value,
+        ),
+    }
+
+    RequestClass, field_name = execute_request_mapping[type(params)]
+    return RequestClass(**{field_name: params})  # type: ignore

nado_protocol/trigger_client/types/models.py

@@ -0,0 +1,44 @@
+from typing import Optional, Union
+from nado_protocol.utils.model import NadoBaseModel
+
+
+class PriceAboveTrigger(NadoBaseModel):
+    price_above: str
+
+
+class PriceBelowTrigger(NadoBaseModel):
+    price_below: str
+
+
+class LastPriceAboveTrigger(NadoBaseModel):
+    last_price_above: str
+
+
+class LastPriceBelowTrigger(NadoBaseModel):
+    last_price_below: str
+
+
+TriggerCriteria = Union[
+    PriceAboveTrigger, PriceBelowTrigger, LastPriceAboveTrigger, LastPriceBelowTrigger
+]
+
+
+class OrderData(NadoBaseModel):
+    sender: str
+    priceX18: str
+    amount: str
+    expiration: str
+    nonce: str
+
+
+class TriggerOrderData(NadoBaseModel):
+    """
+    Data model for details of a trigger order.
+    """
+
+    product_id: int
+    order: OrderData
+    signature: str
+    spot_leverage: Optional[bool]
+    digest: Optional[str]
+    trigger: TriggerCriteria

nado_protocol/trigger_client/types/query.py

@@ -0,0 +1,77 @@
+from typing import Optional
+
+from pydantic import validator
+
+from nado_protocol.engine_client.types.models import ResponseStatus
+from nado_protocol.trigger_client.types.models import TriggerOrderData
+from nado_protocol.utils.bytes32 import bytes32_to_hex
+from nado_protocol.utils.execute import BaseParams, SignatureParams
+from nado_protocol.utils.model import NadoBaseModel
+
+
+class ListTriggerOrdersTx(BaseParams):
+    recvTime: int
+
+
+class ListTriggerOrdersParams(NadoBaseModel):
+    """
+    Parameters for listing trigger orders
+    """
+
+    type = "list_trigger_orders"
+    tx: ListTriggerOrdersTx
+    product_id: Optional[int]
+    pending: bool
+    max_update_time: Optional[str]
+    max_digest: Optional[str]
+    digests: Optional[list[str]]
+    limit: Optional[int]
+    signature: Optional[str]
+
+
+class TriggerOrder(NadoBaseModel):
+    order: TriggerOrderData
+    status: str
+    updated_at: int
+
+
+class TriggerOrdersData(NadoBaseModel):
+    """
+    Data model for trigger orders
+    """
+
+    orders: list[TriggerOrder]
+
+
+class ListTriggerOrdersRequest(ListTriggerOrdersParams):
+    tx: ListTriggerOrdersTx
+
+    @validator("tx")
+    def serialize(cls, v: ListTriggerOrdersTx) -> ListTriggerOrdersTx:
+        if isinstance(v.sender, bytes):
+            v.serialize_dict(["sender"], bytes32_to_hex)
+        v.serialize_dict(["recvTime"], str)
+        return v
+
+
+class TriggerQueryResponse(NadoBaseModel):
+    """
+    Represents a response to a query request.
+
+    Attributes:
+        status (ResponseStatus): The status of the query response.
+
+        data (Optional[QueryResponseData]): The data returned from the query, or an error message if the query failed.
+
+        error (Optional[str]): The error message, if any error occurred during the query.
+
+        error_code (Optional[int]): The error code, if any error occurred during the query.
+
+        request_type (Optional[str]): Type of the request.
+    """
+
+    status: ResponseStatus
+    data: Optional[TriggerOrdersData]
+    error: Optional[str]
+    error_code: Optional[int]
+    request_type: Optional[str]

nado_protocol/utils/__init__.py

@@ -0,0 +1,37 @@
+from nado_protocol.utils.backend import *
+from nado_protocol.utils.bytes32 import *
+from nado_protocol.utils.subaccount import *
+from nado_protocol.utils.expiration import *
+from nado_protocol.utils.math import *
+from nado_protocol.utils.nonce import *
+from nado_protocol.utils.exceptions import *
+
+__all__ = [
+    "NadoBackendURL",
+    "NadoClientOpts",
+    "SubaccountParams",
+    "Subaccount",
+    "subaccount_to_bytes32",
+    "subaccount_to_hex",
+    "subaccount_name_to_bytes12",
+    "hex_to_bytes32",
+    "hex_to_bytes12",
+    "hex_to_bytes",
+    "str_to_hex",
+    "bytes32_to_hex",
+    "zero_subaccount",
+    "zero_address",
+    "OrderType",
+    "get_expiration_timestamp",
+    "gen_order_nonce",
+    "decode_expiration",
+    "to_pow_10",
+    "to_x18",
+    "from_pow_10",
+    "from_x18",
+    "ExecuteFailedException",
+    "QueryFailedException",
+    "BadStatusCodeException",
+    "MissingSignerException",
+    "InvalidProductId",
+]

nado_protocol/utils/backend.py

@@ -0,0 +1,111 @@
+from nado_protocol.utils.enum import StrEnum
+from eth_account import Account
+from eth_account.signers.local import LocalAccount
+from typing import Optional, Union
+from pydantic import BaseModel, AnyUrl, validator, root_validator
+
+
+class NadoBackendURL(StrEnum):
+    """Enum representing different Nado backend URLs."""
+
+    # dev
+    DEVNET_GATEWAY = "http://localhost:80"
+    DEVNET_INDEXER = "http://localhost:8000"
+    DEVNET_TRIGGER = "http://localhost:8080"
+
+
+PrivateKey = str
+Signer = Union[LocalAccount, PrivateKey]
+
+
+class NadoClientOpts(BaseModel):
+    """
+    Model defining the configuration options for execute Nado Clients (e.g: Engine, Trigger). It includes various parameters such as the URL,
+    the signer, the linked signer, the chain ID, and others.
+
+    Attributes:
+        url (AnyUrl): The URL of the server.
+        signer (Optional[Signer]): The signer for the client, if any. It can either be a `LocalAccount` or a private key.
+        linked_signer (Optional[Signer]): An optional signer linked the main subaccount to perform executes on it's behalf.
+        chain_id (Optional[int]): An optional network chain ID.
+        endpoint_addr (Optional[str]): Nado's endpoint address used for verifying executes.
+        book_addrs (Optional[list[str]]): Nado's book addresses used for verifying order placement.
+
+    Notes:
+        - The class also includes several methods for validating and sanitizing the input values.
+        - "linked_signer" cannot be set if "signer" is not set.
+    """
+
+    url: AnyUrl
+    signer: Optional[Union[LocalAccount, PrivateKey]] = None
+    linked_signer: Optional[Signer] = None
+    chain_id: Optional[int] = None
+    endpoint_addr: Optional[str] = None
+    book_addrs: Optional[list[str]] = None
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    @root_validator
+    def check_linked_signer(cls, values: dict):
+        """
+        Validates that if a linked_signer is set, a signer must also be set.
+
+        Args:
+            values (dict): The input values to be validated.
+
+        Raises:
+            ValueError: If linked_signer is set but signer is not.
+
+        Returns:
+            dict: The validated values.
+        """
+        signer, linked_signer = values.get("signer"), values.get("linked_signer")
+        if linked_signer and not signer:
+            raise ValueError("linked_signer cannot be set if signer is not set")
+        return values
+
+    @validator("url")
+    def clean_url(cls, v: AnyUrl) -> str:
+        """
+        Cleans the URL input by removing trailing slashes.
+
+        Args:
+            v (AnyUrl): The input URL.
+
+        Returns:
+            str: The cleaned URL.
+        """
+        return v.rstrip("/")
+
+    @validator("signer")
+    def signer_to_local_account(cls, v: Optional[Signer]) -> Optional[LocalAccount]:
+        """
+        Validates and converts the signer to a LocalAccount instance.
+
+        Args:
+            v (Optional[Signer]): The signer instance or None.
+
+        Returns:
+            Optional[LocalAccount]: The LocalAccount instance or None.
+        """
+        if v is None or isinstance(v, LocalAccount):
+            return v
+        return Account.from_key(v)
+
+    @validator("linked_signer")
+    def linked_signer_to_local_account(
+        cls, v: Optional[Signer]
+    ) -> Optional[LocalAccount]:
+        """
+        Validates and converts the linked_signer to a LocalAccount instance.
+
+        Args:
+            v (Optional[Signer]): The linked_signer instance or None.
+
+        Returns:
+            Optional[LocalAccount]: The LocalAccount instance or None.
+        """
+        if v is None or isinstance(v, LocalAccount):
+            return v
+        return Account.from_key(v)