nado-protocol 0.1.0__tar.gz

nado_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.3
+Name: nado-protocol
+Version: 0.1.0
+Summary: Nado Protocol SDK
+Keywords: nado protocol,nado sdk,nado protocol api
+Author: Jeury Mejia
+Author-email: jeury@inkfnd.com
+Maintainer: Frank Jia
+Maintainer-email: frank@inkfnd.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: eth-account (>=0.8.0,<0.9.0)
+Requires-Dist: pydantic (>=1.10.7,<2.0.0)
+Requires-Dist: web3 (>=6.4.0,<7.0.0)
+Project-URL: Documentation, https://nadohq.github.io/nado-python-sdk/
+Project-URL: Homepage, https://nado.xyz
+Description-Content-Type: text/markdown
+
+# Nado Protocol Python SDK
+
+This is the Python SDK for the [Nado Protocol API](TODO).
+
+See [SDK docs](https://nadohq.github.io/nado-python-sdk/index.html) to get started.
+
+## Requirements
+
+- Python 3.9 or above
+
+## Installation
+
+You can install the SDK via pip:
+
+```bash
+pip install nado-protocol
+```
+
+## Basic usage
+
+### Import the necessary utilities:
+
+```python
+from nado_protocol.client import create_nado_client, NadoClientMode
+from nado_protocol.contracts.types import DepositCollateralParams
+from nado_protocol.engine_client.types.execute import (
+    OrderParams,
+    PlaceOrderParams,
+    SubaccountParams
+)
+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
+```
+
+### Create the NadoClient providing your private key:
+
+```python
+print("setting up nado client...")
+private_key = "xxx"
+client = create_nado_client(NadoClientMode.DEVNET, private_key)
+```
+
+### Perform basic operations:
+
+```python
+# Depositing collaterals
+print("approving allowance...")
+approve_allowance_tx_hash = client.spot.approve_allowance(0, to_pow_10(100000, 6))
+print("approve allowance tx hash:", approve_allowance_tx_hash)
+
+print("querying my allowance...")
+token_allowance = client.spot.get_token_allowance(0, client.context.signer.address)
+print("token allowance:", token_allowance)
+
+print("depositing collateral...")
+deposit_tx_hash = client.spot.deposit(
+   DepositCollateralParams(
+      subaccount_name="default", product_id=0, amount=to_pow_10(100000, 6)
+   )
+)
+print("deposit collateral tx hash:", deposit_tx_hash)
+
+# Placing orders
+print("placing order...")
+owner = client.context.engine_client.signer.address
+product_id = 1
+order = OrderParams(
+   sender=SubaccountParams(
+      subaccount_owner=owner,
+      subaccount_name="default",
+   ),
+   priceX18=to_x18(20000),
+   amount=to_pow_10(1, 17),
+   expiration=get_expiration_timestamp(OrderType.POST_ONLY, int(time.time()) + 40),
+   nonce=gen_order_nonce(),
+)
+res = client.market.place_order({"product_id": product_id, "order": order})
+print("order result:", res.json(indent=2))
+```
+
+See [Getting Started](https://nadohq.github.io/nado-python-sdk/getting-started.html) for more.
+
+## Running locally
+
+1. Clone [github repo](https://github.com/nadohq/nado-python-sdk)
+
+2. Install poetry
+
+```
+
+$ curl -sSL https://install.python-poetry.org | python3 -
+
+```
+
+3. Setup a virtual environment and activate it
+
+```
+
+$ python3 -m venv venv
+$ source ./venv/bin/activate
+
+```
+
+4. Install dependencies via `poetry install`
+5. Setup an `.env` file and set the following envvars
+
+```shell
+CLIENT_MODE='devnet'
+SIGNER_PRIVATE_KEY="0x..."
+LINKED_SIGNER_PRIVATE_KEY="0x..." # not required
+```
+
+### Run tests
+
+```
+$ poetry run test
+```
+
+### Run sanity checks
+
+- `poetry run client-sanity`: runs sanity checks for the top-level client.
+- `poetry run engine-sanity`: runs sanity checks for the `engine-client`.
+- `poetry run indexer-sanity`: runs sanity checks for the `indexer-client`.
+- `poetry run contracts-sanity`: runs sanity checks for the contracts module.
+
+### Build Docs
+
+To build the docs locally run:
+
+```
+$ poetry run sphinx-build docs/source docs/build
+```
+

nado_protocol-0.1.0/README.md

@@ -0,0 +1,133 @@
+# Nado Protocol Python SDK
+
+This is the Python SDK for the [Nado Protocol API](TODO).
+
+See [SDK docs](https://nadohq.github.io/nado-python-sdk/index.html) to get started.
+
+## Requirements
+
+- Python 3.9 or above
+
+## Installation
+
+You can install the SDK via pip:
+
+```bash
+pip install nado-protocol
+```
+
+## Basic usage
+
+### Import the necessary utilities:
+
+```python
+from nado_protocol.client import create_nado_client, NadoClientMode
+from nado_protocol.contracts.types import DepositCollateralParams
+from nado_protocol.engine_client.types.execute import (
+    OrderParams,
+    PlaceOrderParams,
+    SubaccountParams
+)
+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
+```
+
+### Create the NadoClient providing your private key:
+
+```python
+print("setting up nado client...")
+private_key = "xxx"
+client = create_nado_client(NadoClientMode.DEVNET, private_key)
+```
+
+### Perform basic operations:
+
+```python
+# Depositing collaterals
+print("approving allowance...")
+approve_allowance_tx_hash = client.spot.approve_allowance(0, to_pow_10(100000, 6))
+print("approve allowance tx hash:", approve_allowance_tx_hash)
+
+print("querying my allowance...")
+token_allowance = client.spot.get_token_allowance(0, client.context.signer.address)
+print("token allowance:", token_allowance)
+
+print("depositing collateral...")
+deposit_tx_hash = client.spot.deposit(
+   DepositCollateralParams(
+      subaccount_name="default", product_id=0, amount=to_pow_10(100000, 6)
+   )
+)
+print("deposit collateral tx hash:", deposit_tx_hash)
+
+# Placing orders
+print("placing order...")
+owner = client.context.engine_client.signer.address
+product_id = 1
+order = OrderParams(
+   sender=SubaccountParams(
+      subaccount_owner=owner,
+      subaccount_name="default",
+   ),
+   priceX18=to_x18(20000),
+   amount=to_pow_10(1, 17),
+   expiration=get_expiration_timestamp(OrderType.POST_ONLY, int(time.time()) + 40),
+   nonce=gen_order_nonce(),
+)
+res = client.market.place_order({"product_id": product_id, "order": order})
+print("order result:", res.json(indent=2))
+```
+
+See [Getting Started](https://nadohq.github.io/nado-python-sdk/getting-started.html) for more.
+
+## Running locally
+
+1. Clone [github repo](https://github.com/nadohq/nado-python-sdk)
+
+2. Install poetry
+
+```
+
+$ curl -sSL https://install.python-poetry.org | python3 -
+
+```
+
+3. Setup a virtual environment and activate it
+
+```
+
+$ python3 -m venv venv
+$ source ./venv/bin/activate
+
+```
+
+4. Install dependencies via `poetry install`
+5. Setup an `.env` file and set the following envvars
+
+```shell
+CLIENT_MODE='devnet'
+SIGNER_PRIVATE_KEY="0x..."
+LINKED_SIGNER_PRIVATE_KEY="0x..." # not required
+```
+
+### Run tests
+
+```
+$ poetry run test
+```
+
+### Run sanity checks
+
+- `poetry run client-sanity`: runs sanity checks for the top-level client.
+- `poetry run engine-sanity`: runs sanity checks for the `engine-client`.
+- `poetry run indexer-sanity`: runs sanity checks for the `indexer-client`.
+- `poetry run contracts-sanity`: runs sanity checks for the contracts module.
+
+### Build Docs
+
+To build the docs locally run:
+
+```
+$ poetry run sphinx-build docs/source docs/build
+```

nado_protocol-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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