nado-protocol 0.1.0__py3-none-any.whl

nado_protocol/client/__init__.py

@@ -0,0 +1,200 @@
+import logging
+from nado_protocol.client.apis.market import MarketAPI
+from nado_protocol.client.apis.perp import PerpAPI
+from nado_protocol.client.apis.spot import SpotAPI
+from nado_protocol.client.apis.subaccount import SubaccountAPI
+from nado_protocol.client.apis.rewards import RewardsAPI
+from nado_protocol.client.context import (
+    NadoClientContext,
+    NadoClientContextOpts,
+    create_nado_client_context,
+)
+from nado_protocol.contracts import NadoContractsContext
+from nado_protocol.contracts.loader import load_deployment
+from nado_protocol.contracts.types import NadoNetwork
+from nado_protocol.utils.backend import NadoBackendURL, Signer
+from nado_protocol.utils.enum import StrEnum
+from nado_protocol.client.context import *
+
+from pydantic import parse_obj_as
+
+
+class NadoClientMode(StrEnum):
+    """
+    NadoClientMode is an enumeration representing the operational modes of the NadoClient.
+
+    Attributes:
+        DEVNET: For local development.
+
+        TESTING: For running tests.
+    """
+
+    # dev
+    DEVNET = "devnet"
+    TESTING = "testing"
+
+
+class NadoClient:
+    """
+    The primary client interface for interacting with Nado Protocol.
+
+    This client consolidates the functionality of various aspects of Nado such as spot, market,
+    subaccount, and perpetual (perp) operations.
+
+    To initialize an instance of this client, use the `create_nado_client` utility.
+
+    Attributes:
+        - context (NadoClientContext): The client context containing configuration for interacting with Nado.
+        - market (MarketAPI): Sub-client for executing and querying market operations.
+        - subaccount (SubaccountAPI): Sub-client for executing and querying subaccount operations.
+        - spot (SpotAPI): Sub-client for executing and querying spot operations.
+        - perp (PerpAPI): Sub-client for executing and querying perpetual operations.
+        - rewards (RewardsAPI): Sub-client for executing and querying rewards operations (e.g: staking, claiming, etc).
+    """
+
+    context: NadoClientContext
+    market: MarketAPI
+    subaccount: SubaccountAPI
+    spot: SpotAPI
+    perp: PerpAPI
+    rewards: RewardsAPI
+
+    def __init__(self, context: NadoClientContext):
+        """
+        Initialize a new instance of the NadoClient.
+
+        This constructor should not be called directly. Instead, use the `create_nado_client` utility to
+        create a new NadoClient. This is because the `create_nado_client` utility includes important
+        additional setup steps that aren't included in this constructor.
+
+        Args:
+            context (NadoClientContext): The client context.
+
+        Note:
+            Use `create_nado_client` for creating instances.
+        """
+        self.context = context
+        self.market = MarketAPI(context)
+        self.subaccount = SubaccountAPI(context)
+        self.spot = SpotAPI(context)
+        self.perp = PerpAPI(context)
+        self.rewards = RewardsAPI(context)
+
+
+def create_nado_client(
+    mode: NadoClientMode,
+    signer: Optional[Signer] = None,
+    context_opts: Optional[NadoClientContextOpts] = None,
+) -> NadoClient:
+    """
+    Create a new NadoClient based on the given mode and signer.
+
+    This function will create a new NadoClientContext based on the provided mode, and then
+    initialize a new NadoClient with that context.
+
+    If `context_opts` are provided, they will be used to create the client context. Otherwise,
+    default context options for the given mode will be used.
+
+    Args:
+        mode (NadoClientMode): The mode in which to operate the client. Can be one of the following:
+            NadoClientMode.DEVNET: For local development.
+
+        signer (Signer, optional): An instance of LocalAccount or a private key string for signing transactions.
+
+        context_opts (NadoClientContextOpts, optional): Options for creating the client context.
+            If not provided, default options for the given mode will be used.
+
+    Returns:
+        NadoClient: The created NadoClient instance.
+    """
+    logging.info(f"Initializing default {mode} context")
+    (
+        engine_endpoint_url,
+        indexer_endpoint_url,
+        trigger_endpoint_url,
+        network_name,
+    ) = client_mode_to_setup(mode)
+    try:
+        network = NadoNetwork(network_name)
+        deployment = load_deployment(network)
+        rpc_node_url = deployment.node_url
+        contracts_context = NadoContractsContext(
+            network=network,
+            endpoint_addr=deployment.endpoint_addr,
+            querier_addr=deployment.querier_addr,
+            perp_engine_addr=deployment.perp_engine_addr,
+            spot_engine_addr=deployment.spot_engine_addr,
+            clearinghouse_addr=deployment.clearinghouse_addr,
+            vrtx_airdrop_addr=deployment.vrtx_airdrop_addr,
+            vrtx_staking_addr=deployment.vrtx_staking_addr,
+            foundation_rewards_airdrop_addr=deployment.foundation_rewards_airdrop_addr,
+        )
+    except Exception as e:
+        logging.warning(
+            f"Failed to load contracts for mode {mode} with error: {e}, using provided defaults."
+        )
+        assert context_opts is not None and context_opts.rpc_node_url is not None
+        assert context_opts is not None and context_opts.contracts_context is not None
+
+        rpc_node_url = context_opts.rpc_node_url
+        contracts_context = context_opts.contracts_context
+
+    if context_opts:
+        parsed_context_opts: NadoClientContextOpts = NadoClientContextOpts.parse_obj(
+            context_opts
+        )
+        engine_endpoint_url = (
+            parsed_context_opts.engine_endpoint_url or engine_endpoint_url
+        )
+        indexer_endpoint_url = (
+            parsed_context_opts.indexer_endpoint_url or indexer_endpoint_url
+        )
+        trigger_endpoint_url = (
+            parsed_context_opts.trigger_endpoint_url or trigger_endpoint_url
+        )
+        rpc_node_url = parsed_context_opts.rpc_node_url or rpc_node_url
+        contracts_context = parsed_context_opts.contracts_context or contracts_context
+
+    context = create_nado_client_context(
+        NadoClientContextOpts(
+            rpc_node_url=rpc_node_url,
+            engine_endpoint_url=parse_obj_as(AnyUrl, engine_endpoint_url),
+            indexer_endpoint_url=parse_obj_as(AnyUrl, indexer_endpoint_url),
+            trigger_endpoint_url=parse_obj_as(AnyUrl, trigger_endpoint_url),
+            contracts_context=contracts_context,
+        ),
+        signer,
+    )
+    return NadoClient(context)
+
+
+def client_mode_to_setup(
+    client_mode: NadoClientMode,
+) -> tuple[str, str, str, str]:
+    try:
+        return {
+            NadoClientMode.DEVNET: (
+                NadoBackendURL.DEVNET_GATEWAY.value,
+                NadoBackendURL.DEVNET_INDEXER.value,
+                NadoBackendURL.DEVNET_TRIGGER.value,
+                NadoNetwork.HARDHAT.value,
+            ),
+            NadoClientMode.TESTING: (
+                NadoBackendURL.DEVNET_GATEWAY.value,
+                NadoBackendURL.DEVNET_INDEXER.value,
+                NadoBackendURL.DEVNET_TRIGGER.value,
+                NadoNetwork.TESTING.value,
+            ),
+        }[client_mode]
+    except KeyError:
+        raise Exception(f"Mode provided `{client_mode}` not supported!")
+
+
+__all__ = [
+    "NadoClient",
+    "NadoClientMode",
+    "create_nado_client",
+    "NadoClientContext",
+    "NadoClientContextOpts",
+    "create_nado_client_context",
+]

nado_protocol/client/apis/__init__.py

@@ -0,0 +1,26 @@
+from nado_protocol.client.apis.base import *
+from nado_protocol.client.apis.market import *
+from nado_protocol.client.apis.perp import *
+from nado_protocol.client.apis.spot import *
+from nado_protocol.client.apis.spot.base import *
+from nado_protocol.client.apis.subaccount import *
+from nado_protocol.client.apis.rewards import *
+
+__all__ = [
+    "NadoBaseAPI",
+    "MarketAPI",
+    "MarketExecuteAPI",
+    "MarketQueryAPI",
+    "SpotAPI",
+    "BaseSpotAPI",
+    "SpotExecuteAPI",
+    "SpotQueryAPI",
+    "SubaccountAPI",
+    "SubaccountExecuteAPI",
+    "SubaccountQueryAPI",
+    "PerpAPI",
+    "PerpQueryAPI",
+    "RewardsAPI",
+    "RewardsExecuteAPI",
+    "RewardsQueryAPI",
+]

nado_protocol/client/apis/base.py

@@ -0,0 +1,42 @@
+from typing import Optional
+from nado_protocol.client.context import NadoClientContext
+from nado_protocol.utils.exceptions import MissingSignerException
+from eth_account.signers.local import LocalAccount
+
+
+class NadoBaseAPI:
+    """
+    The base class for all Nado API classes, providing the foundation for API-specific classes in the Nado client.
+
+    NadoBaseAPI serves as a foundation for the hierarchical structure of the Nado API classes. This structure allows for better
+    organization and separation of concerns, with each API-specific subclass handling a different aspect of the Nado client's functionality.
+
+    Attributes:
+        context (NadoClientContext): The context in which the API operates, providing access to the client's state and services.
+
+    Note:
+        This class is not meant to be used directly. It provides base functionality for other API classes in the Nado client.
+    """
+
+    context: NadoClientContext
+
+    def __init__(self, context: NadoClientContext):
+        """
+        Initialize an instance of NadoBaseAPI.
+
+        NadoBaseAPI requires a context during instantiation, which should be an instance of NadoClientContext. This context
+        provides access to the state and services of the Nado client and allows the API to interact with these.
+
+        Args:
+            context (NadoClientContext): The context in which this API operates. Provides access to the state and services
+            of the Nado client.
+        """
+        self.context = context
+
+    def _get_signer(self, signer: Optional[LocalAccount]) -> LocalAccount:
+        signer = signer if signer else self.context.signer
+        if not signer:
+            raise MissingSignerException(
+                "A signer must be provided or set via the context."
+            )
+        return signer

nado_protocol/client/apis/market/__init__.py

@@ -0,0 +1,23 @@
+from nado_protocol.client.apis.market.execute import MarketExecuteAPI
+from nado_protocol.client.apis.market.query import MarketQueryAPI
+
+
+class MarketAPI(MarketExecuteAPI, MarketQueryAPI):
+    """
+    A unified interface for market operations in the Nado Protocol.
+
+    This class combines functionalities from both MarketExecuteAPI and MarketQueryAPI
+    into a single interface, providing a simpler and more consistent way to perform market operations.
+    It allows for both query (data retrieval) and execution (transaction) operations for market.
+
+    Inheritance:
+        MarketExecuteAPI: This provides functionalities to execute various operations related to market.
+        These include actions like placing an order, canceling an order, minting and burning LP tokens.
+
+        MarketQueryAPI: This provides functionalities to retrieve various kinds of information related to market.
+        These include operations like retrieving order books, historical orders, market matches, and others.
+
+    Attributes and Methods: Inherited from MarketExecuteAPI and MarketQueryAPI.
+    """
+
+    pass

nado_protocol/client/apis/market/execute.py

@@ -0,0 +1,192 @@
+from nado_protocol.engine_client.types.execute import (
+    BurnLpParams,
+    CancelAndPlaceParams,
+    CancelOrdersParams,
+    CancelProductOrdersParams,
+    ExecuteResponse,
+    MintLpParams,
+    PlaceMarketOrderParams,
+    PlaceOrderParams,
+    PlaceIsolatedOrderParams,
+)
+from nado_protocol.client.apis.base import NadoBaseAPI
+from nado_protocol.trigger_client.types.execute import (
+    PlaceTriggerOrderParams,
+    CancelTriggerOrdersParams,
+    CancelProductTriggerOrdersParams,
+)
+from nado_protocol.utils.exceptions import MissingTriggerClient
+from nado_protocol.utils.subaccount import Subaccount
+
+
+class MarketExecuteAPI(NadoBaseAPI):
+    """
+    Provides functionality to interact with the Nado's market execution APIs.
+    This class contains methods that allow clients to execute operations such as minting LP tokens, burning LP tokens,
+    placing and cancelling orders on the Nado market.
+
+    Attributes:
+        context (NadoClientContext): The context that provides connectivity configuration for NadoClient.
+
+    Note:
+        This class should not be instantiated directly, it is designed to be used through a NadoClient instance.
+    """
+
+    def mint_lp(self, params: MintLpParams) -> ExecuteResponse:
+        """
+        Mint LP tokens through the engine.
+
+        Args:
+            params (MintLpParams): Parameters required to mint LP tokens.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.mint_lp(params)
+
+    def burn_lp(self, params: BurnLpParams) -> ExecuteResponse:
+        """
+        Burn LP tokens through the engine.
+
+        Args:
+            params (BurnLpParams): Parameters required to burn LP tokens.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.burn_lp(params)
+
+    def place_order(self, params: PlaceOrderParams) -> ExecuteResponse:
+        """
+        Places an order through the engine.
+
+        Args:
+            params (PlaceOrderParams): Parameters required to place an order.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.place_order(params)
+
+    def place_isolated_order(self, params: PlaceIsolatedOrderParams) -> ExecuteResponse:
+        """
+        Places an isolated order through the engine.
+
+        Args:
+            params (PlaceIsolatedOrderParams): Parameters required to place an isolated order.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.place_isolated_order(params)
+
+    def place_market_order(self, params: PlaceMarketOrderParams) -> ExecuteResponse:
+        """
+        Places a market order through the engine.
+
+        Args:
+            params (PlaceMarketOrderParams): Parameters required to place a market order.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.place_market_order(params)
+
+    def cancel_orders(self, params: CancelOrdersParams) -> ExecuteResponse:
+        """
+        Cancels orders through the engine.
+
+        Args:
+            params (CancelOrdersParams): Parameters required to cancel orders.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution containing information about the canceled product orders.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.cancel_orders(params)
+
+    def cancel_product_orders(
+        self, params: CancelProductOrdersParams
+    ) -> ExecuteResponse:
+        """
+        Cancels all orders for provided products through the engine.
+
+        Args:
+            params (CancelProductOrdersParams): Parameters required to cancel product orders.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution containing information about the canceled product orders.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.cancel_product_orders(params)
+
+    def cancel_and_place(self, params: CancelAndPlaceParams) -> ExecuteResponse:
+        """
+        Cancels orders and places a new one through the engine on the same request.
+
+        Args:
+            params (CancelAndPlaceParams): Parameters required to cancel orders and place a new one.
+
+        Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.cancel_and_place(params)
+
+    def close_position(
+        self, subaccount: Subaccount, product_id: int
+    ) -> ExecuteResponse:
+        """
+        Places an order through the engine to close a position for the provided `product_id`.
+
+        Attributes:
+            subaccount (Subaccount): The subaccount to close position for.
+            product_id (int): The ID of the product to close position for.
+
+         Returns:
+            ExecuteResponse: The response from the engine execution.
+
+        Raises:
+            Exception: If there is an error during the execution or the response status is not "success".
+        """
+        return self.context.engine_client.close_position(subaccount, product_id)
+
+    def place_trigger_order(self, params: PlaceTriggerOrderParams) -> ExecuteResponse:
+        if self.context.trigger_client is None:
+            raise MissingTriggerClient()
+        return self.context.trigger_client.place_trigger_order(params)
+
+    def cancel_trigger_orders(
+        self, params: CancelTriggerOrdersParams
+    ) -> ExecuteResponse:
+        if self.context.trigger_client is None:
+            raise MissingTriggerClient()
+        return self.context.trigger_client.cancel_trigger_orders(params)
+
+    def cancel_trigger_product_orders(
+        self, params: CancelProductTriggerOrdersParams
+    ) -> ExecuteResponse:
+        if self.context.trigger_client is None:
+            raise MissingTriggerClient()
+        return self.context.trigger_client.cancel_product_trigger_orders(params)