nado-protocol 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

nado_protocol/trigger_client/types/query.py

@@ -1,4 +1,5 @@
-from typing import Optional
+from typing import Optional, List, Union
+from enum import Enum
 
 from pydantic import validator
 
@@ -9,6 +10,22 @@ from nado_protocol.utils.execute import BaseParams, SignatureParams
 from nado_protocol.utils.model import NadoBaseModel
 
 
+class TriggerType(str, Enum):
+    PRICE_TRIGGER = "price_trigger"
+    TIME_TRIGGER = "time_trigger"
+
+
+class TriggerOrderStatusType(str, Enum):
+    CANCELLED = "cancelled"
+    TRIGGERED = "triggered"
+    INTERNAL_ERROR = "internal_error"
+    TRIGGERING = "triggering"
+    WAITING_PRICE = "waiting_price"
+    WAITING_DEPENDENCY = "waiting_dependency"
+    TWAP_EXECUTING = "twap_executing"
+    TWAP_COMPLETED = "twap_completed"
+
+
 class ListTriggerOrdersTx(BaseParams):
     recvTime: int
 
@@ -20,18 +37,114 @@ class ListTriggerOrdersParams(NadoBaseModel):
 
     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]
+    product_ids: Optional[List[int]] = None
+    trigger_types: Optional[List[TriggerType]] = None
+    status_types: Optional[List[TriggerOrderStatusType]] = None
+    max_update_time: Optional[int] = None
+    max_digest: Optional[str] = None
+    digests: Optional[List[str]] = None
+    reduce_only: Optional[bool] = None
+    limit: Optional[int] = None
+    signature: Optional[str] = None
+
+
+class ListTwapExecutionsParams(NadoBaseModel):
+    """
+    Parameters for listing TWAP executions for a specific order
+    """
+
+    type = "list_twap_executions"
+    digest: str
+
+
+class ExecutedStatusData(NadoBaseModel):
+    """Data for executed TWAP execution"""
+
+    executed_time: int
+    execute_response: dict  # ExecuteResponse from engine
+
+
+class ExecutedStatus(NadoBaseModel):
+    """Status when TWAP execution has been executed"""
+
+    executed: ExecutedStatusData
+
+
+class FailedStatus(NadoBaseModel):
+    """Status when TWAP execution failed"""
+
+    failed: str
+
+
+class CancelledStatus(NadoBaseModel):
+    """Status when TWAP execution was cancelled"""
+
+    cancelled: str
+
+
+class TwapExecutionDetail(NadoBaseModel):
+    """Detail of a single TWAP execution"""
+
+    execution_id: int
+    scheduled_time: int
+    status: Union[
+        ExecutedStatus, FailedStatus, CancelledStatus, str
+    ]  # str for "pending"
+    updated_at: int
+
+
+class TwapExecutionsData(NadoBaseModel):
+    """Data model for TWAP executions"""
+
+    executions: List[TwapExecutionDetail]
+
+
+class TriggeredStatus(NadoBaseModel):
+    """Status when order has been triggered"""
+
+    triggered: dict  # Contains trigger execution details
+
+
+class TriggerCancelledStatus(NadoBaseModel):
+    """Status when order has been cancelled"""
+
+    cancelled: str  # Cancellation reason (e.g., "user_requested")
+
+
+class TriggerInternalErrorStatus(NadoBaseModel):
+    """Status when there was an internal error"""
+
+    internal_error: str  # Error description
+
+
+class TwapExecutingStatusObject(NadoBaseModel):
+    """Status when TWAP order is executing"""
+
+    twap_executing: dict  # Contains execution details
+
+
+class TwapCompletedStatusObject(NadoBaseModel):
+    """Status when TWAP order is completed"""
+
+    twap_completed: dict  # Contains completion details
+
+
+# Union type for trigger order status
+# Order matters: more specific types (with required fields) should come first
+TriggerOrderStatus = Union[
+    TriggeredStatus,
+    TriggerCancelledStatus,
+    TriggerInternalErrorStatus,
+    TwapExecutingStatusObject,
+    TwapCompletedStatusObject,
+    str,  # For simple status strings like "waiting_price", "waiting_dependency", etc.
+]
 
 
 class TriggerOrder(NadoBaseModel):
     order: TriggerOrderData
-    status: str
+    status: TriggerOrderStatus
+    placed_at: int
     updated_at: int
 
 
@@ -40,7 +153,7 @@ class TriggerOrdersData(NadoBaseModel):
     Data model for trigger orders
     """
 
-    orders: list[TriggerOrder]
+    orders: List[TriggerOrder]
 
 
 class ListTriggerOrdersRequest(ListTriggerOrdersParams):
@@ -54,6 +167,15 @@ class ListTriggerOrdersRequest(ListTriggerOrdersParams):
         return v
 
 
+class ListTwapExecutionsRequest(ListTwapExecutionsParams):
+    pass
+
+
+TriggerQueryParams = Union[ListTriggerOrdersParams, ListTwapExecutionsParams]
+TriggerQueryRequest = Union[ListTriggerOrdersRequest, ListTwapExecutionsRequest]
+TriggerQueryData = Union[TriggerOrdersData, TwapExecutionsData]
+
+
 class TriggerQueryResponse(NadoBaseModel):
     """
     Represents a response to a query request.
@@ -61,7 +183,7 @@ class TriggerQueryResponse(NadoBaseModel):
     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.
+        data (Optional[TriggerQueryData]): 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.
 
@@ -71,7 +193,7 @@ class TriggerQueryResponse(NadoBaseModel):
     """
 
     status: ResponseStatus
-    data: Optional[TriggerOrdersData]
-    error: Optional[str]
-    error_code: Optional[int]
-    request_type: Optional[str]
+    data: Optional[TriggerQueryData] = None
+    error: Optional[str] = None
+    error_code: Optional[int] = None
+    request_type: Optional[str] = None

nado_protocol/utils/twap.py

@@ -0,0 +1,189 @@
+from typing import List, Optional
+from nado_protocol.utils.order import (
+    build_appendix,
+    OrderAppendixTriggerType,
+)
+from nado_protocol.utils.expiration import OrderType
+from nado_protocol.utils.execute import OrderParams
+
+
+def create_twap_order(
+    product_id: int,
+    sender: str,
+    price_x18: str,
+    total_amount_x18: str,
+    expiration: int,
+    nonce: int,
+    times: int,
+    slippage_frac: float,
+    interval_seconds: int,
+    custom_amounts_x18: Optional[List[str]] = None,
+    reduce_only: bool = False,
+    spot_leverage: Optional[bool] = None,
+    id: Optional[int] = None,
+):
+    """
+    Create a TWAP (Time-Weighted Average Price) order.
+
+    Args:
+        product_id (int): The product ID for the order.
+        sender (str): The sender address (32 bytes hex).
+        price_x18 (str): The limit price multiplied by 1e18.
+        total_amount_x18 (str): The total amount to trade multiplied by 1e18 (signed, negative for sell).
+        expiration (int): Order expiration timestamp.
+        nonce (int): Order nonce.
+        times (int): Number of TWAP executions (1-500).
+        slippage_frac (float): Slippage tolerance as a fraction (e.g., 0.01 for 1%).
+        interval_seconds (int): Time interval between executions in seconds.
+        custom_amounts_x18 (Optional[List[str]]): Custom amounts for each execution multiplied by 1e18.
+                                                If provided, uses TWAP_CUSTOM_AMOUNTS trigger type.
+        reduce_only (bool): Whether this is a reduce-only order.
+        spot_leverage (Optional[bool]): Whether to use spot leverage.
+        id (Optional[int]): Optional order ID.
+
+    Returns:
+        PlaceTriggerOrderParams: Parameters for placing the TWAP order.
+
+    Raises:
+        ValueError: If parameters are invalid.
+    """
+    # Import here to avoid circular imports
+    from nado_protocol.trigger_client.types.models import TimeTrigger
+    from nado_protocol.trigger_client.types.execute import PlaceTriggerOrderParams
+
+    if times < 1 or times > 500:
+        raise ValueError(f"TWAP times must be between 1 and 500, got {times}")
+
+    if slippage_frac < 0 or slippage_frac > 1:
+        raise ValueError(
+            f"Slippage fraction must be between 0 and 1, got {slippage_frac}"
+        )
+
+    if interval_seconds <= 0:
+        raise ValueError(f"Interval must be positive, got {interval_seconds}")
+
+    # Determine trigger type
+    trigger_type = (
+        OrderAppendixTriggerType.TWAP_CUSTOM_AMOUNTS
+        if custom_amounts_x18 is not None
+        else OrderAppendixTriggerType.TWAP
+    )
+
+    # Build appendix - TWAP orders must use IOC execution type
+    appendix = build_appendix(
+        order_type=OrderType.IOC,
+        reduce_only=reduce_only,
+        trigger_type=trigger_type,
+        twap_times=times,
+        twap_slippage_frac=slippage_frac,
+    )
+
+    # Create the base order
+    order_params = OrderParams(
+        sender=sender,
+        priceX18=int(price_x18),
+        amount=int(total_amount_x18),
+        expiration=expiration,
+        nonce=nonce,
+        appendix=appendix,
+    )
+
+    # Create trigger criteria
+    from nado_protocol.trigger_client.types.models import TimeTriggerData
+
+    trigger = TimeTrigger(
+        time_trigger=TimeTriggerData(
+            interval=interval_seconds,
+            amounts=custom_amounts_x18,
+        )
+    )
+
+    return PlaceTriggerOrderParams(
+        product_id=product_id,
+        order=order_params,
+        trigger=trigger,
+        signature=None,  # Will be filled by client
+        digest=None,  # Will be filled by client
+        spot_leverage=spot_leverage,
+        id=id,
+    )
+
+
+def validate_twap_order(
+    total_amount_x18: str,
+    times: int,
+    custom_amounts_x18: Optional[List[str]] = None,
+) -> None:
+    """
+    Validate TWAP order parameters.
+
+    Args:
+        total_amount_x18 (str): The total amount to trade multiplied by 1e18.
+        times (int): Number of TWAP executions.
+        custom_amounts_x18 (Optional[List[str]]): Custom amounts for each execution multiplied by 1e18.
+
+    Raises:
+        ValueError: If validation fails.
+    """
+    total_amount_int = int(total_amount_x18)
+
+    if custom_amounts_x18 is None:
+        # For equal distribution, total amount must be divisible by times
+        if total_amount_int % times != 0:
+            raise ValueError(
+                f"Total amount {total_amount_x18} must be divisible by times {times} "
+                f"for equal distribution TWAP orders"
+            )
+    else:
+        # For custom amounts, verify the list length and sum
+        if len(custom_amounts_x18) != times:
+            raise ValueError(
+                f"Custom amounts list length ({len(custom_amounts_x18)}) must equal "
+                f"times ({times})"
+            )
+
+        custom_sum = sum(int(amount) for amount in custom_amounts_x18)
+        if custom_sum != total_amount_int:
+            raise ValueError(
+                f"Sum of custom amounts ({custom_sum}) must equal "
+                f"total amount ({total_amount_int})"
+            )
+
+
+def estimate_twap_completion_time(times: int, interval_seconds: int) -> int:
+    """
+    Estimate the total time for TWAP order completion.
+
+    Args:
+        times (int): Number of TWAP executions.
+        interval_seconds (int): Time interval between executions.
+
+    Returns:
+        int: Estimated completion time in seconds.
+    """
+    return (times - 1) * interval_seconds
+
+
+def calculate_equal_amounts(total_amount_x18: str, times: int) -> List[str]:
+    """
+    Calculate equal amounts for TWAP executions.
+
+    Args:
+        total_amount_x18 (str): The total amount to distribute multiplied by 1e18.
+        times (int): Number of executions.
+
+    Returns:
+        List[str]: List of equal amounts for each execution multiplied by 1e18.
+
+    Raises:
+        ValueError: If total amount is not divisible by times.
+    """
+    total_amount_int = int(total_amount_x18)
+
+    if total_amount_int % times != 0:
+        raise ValueError(
+            f"Total amount {total_amount_x18} is not divisible by times {times}"
+        )
+
+    amount_per_execution = total_amount_int // times
+    return [str(amount_per_execution)] * times

nado_protocol-0.1.6.dist-info/METADATA

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: nado-protocol
+Version: 0.1.6
+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
+Classifier: Programming Language :: Python :: 3.14
+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
+from nado_protocol.utils.order import build_appendix
+```
+
+### 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(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))
+```
+
+## TWAP and Trigger Orders
+
+The SDK provides comprehensive support for Time-Weighted Average Price (TWAP) orders and price trigger orders through the Trigger Client.
+
+### TWAP Orders
+
+TWAP orders allow you to execute large trades over time with controlled slippage:
+
+```python
+from nado_protocol.trigger_client import TriggerClient
+from nado_protocol.trigger_client.types import TriggerClientOpts
+from nado_protocol.utils.math import to_x18
+from nado_protocol.utils.expiration import get_expiration_timestamp
+
+# Create trigger client
+trigger_client = TriggerClient(
+    opts=TriggerClientOpts(url=TRIGGER_BACKEND_URL, signer=private_key)
+)
+
+# Place a TWAP order to buy 5 BTC over 2 hours
+twap_result = trigger_client.place_twap_order(
+    product_id=1,
+    sender=client.signer.address,
+    price_x18=str(to_x18(50_000)),        # Max $50k per execution
+    total_amount_x18=str(to_x18(5)),      # Buy 5 BTC total
+    expiration=get_expiration_timestamp(60 * 24),  # 24 hours
+    nonce=client.order_nonce(),
+    times=10,                             # Split into 10 executions
+    slippage_frac=0.005,                  # 0.5% slippage tolerance
+    interval_seconds=720,                 # 12 minutes between executions
+)
+```
+
+### TWAP with Custom Amounts
+
+For more sophisticated strategies, you can specify custom amounts for each execution:
+
+```python
+# Decreasing size strategy: 2 BTC, 1.5 BTC, 1 BTC, 0.5 BTC
+custom_amounts = [
+    str(to_x18(2)),      # 2 BTC
+    str(to_x18(1.5)),    # 1.5 BTC  
+    str(to_x18(1)),      # 1 BTC
+    str(to_x18(0.5)),    # 0.5 BTC
+]
+
+custom_twap_result = trigger_client.place_twap_order(
+    product_id=1,
+    sender=client.signer.address,
+    price_x18=str(to_x18(51_000)),
+    total_amount_x18=str(to_x18(5)),      # 5 BTC total
+    expiration=get_expiration_timestamp(60 * 12),
+    nonce=client.order_nonce(),
+    times=4,                              # 4 executions
+    slippage_frac=0.01,                   # 1% slippage
+    interval_seconds=1800,                # 30 minutes
+    custom_amounts_x18=custom_amounts,
+)
+```
+
+### Price Trigger Orders
+
+Create conditional orders that execute when price conditions are met:
+
+```python
+# Stop-loss order (sell when price drops below $45k)
+stop_loss = trigger_client.place_price_trigger_order(
+    product_id=1,
+    sender=client.signer.address,
+    price_x18=str(to_x18(44_000)),        # Sell at $44k
+    amount_x18=str(-to_x18(1)),           # Sell 1 BTC (negative for sell)
+    expiration=get_expiration_timestamp(60 * 24 * 7),  # 1 week
+    nonce=client.order_nonce(),
+    trigger_price_x18=str(to_x18(45_000)), # Trigger below $45k
+    trigger_type="last_price_below",
+    reduce_only=True,                     # Only reduce position
+)
+
+# Take-profit order (sell when price rises above $55k)
+take_profit = trigger_client.place_price_trigger_order(
+    product_id=1,
+    sender=client.signer.address,
+    price_x18=str(to_x18(56_000)),        # Sell at $56k
+    amount_x18=str(-to_x18(1)),           # Sell 1 BTC
+    expiration=get_expiration_timestamp(60 * 24 * 7),
+    nonce=client.order_nonce(),
+    trigger_price_x18=str(to_x18(55_000)), # Trigger above $55k
+    trigger_type="last_price_above",
+    reduce_only=True,
+)
+```
+
+### Supported Trigger Types
+
+The SDK supports six types of price triggers:
+
+- `"last_price_above"`: Trigger when last traded price goes above threshold
+- `"last_price_below"`: Trigger when last traded price goes below threshold  
+- `"oracle_price_above"`: Trigger when oracle price goes above threshold
+- `"oracle_price_below"`: Trigger when oracle price goes below threshold
+- `"mid_price_above"`: Trigger when mid price goes above threshold
+- `"mid_price_below"`: Trigger when mid price goes below threshold
+
+### Complete Trading Strategy Example
+
+Here's how to set up a complete trading strategy with stop-loss, take-profit, and DCA:
+
+```python
+# 1. Stop-loss protection
+stop_loss = trigger_client.place_price_trigger_order(
+    product_id=1,
+    sender=client.signer.address,
+    price_x18=str(to_x18(44_000)),
+    amount_x18=str(-to_x18(2)),           # Close 2 BTC position
+    expiration=get_expiration_timestamp(60 * 24 * 30),
+    nonce=client.order_nonce(),
+    trigger_price_x18=str(to_x18(45_000)),
+    trigger_type="last_price_below",
+    reduce_only=True,
+)
+
+# 2. Take-profit target
+take_profit = trigger_client.place_price_trigger_order(
+    product_id=1,
+    sender=client.signer.address,
+    price_x18=str(to_x18(58_000)),
+    amount_x18=str(-to_x18(2)),           # Close 2 BTC position
+    expiration=get_expiration_timestamp(60 * 24 * 30),
+    nonce=client.order_nonce(),
+    trigger_price_x18=str(to_x18(57_000)),
+    trigger_type="last_price_above", 
+    reduce_only=True,
+)
+
+# 3. DCA accumulation strategy
+dca_strategy = trigger_client.place_twap_order(
+    product_id=1,
+    sender=client.signer.address,
+    price_x18=str(to_x18(52_000)),        # Max $52k per buy
+    total_amount_x18=str(to_x18(10)),     # Buy 10 BTC over time
+    expiration=get_expiration_timestamp(60 * 24 * 7),
+    nonce=client.order_nonce(),
+    times=20,                             # 20 executions
+    slippage_frac=0.005,                  # 0.5% slippage
+    interval_seconds=1800,                # 30 minutes
+)
+```
+
+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 trigger-sanity`: runs sanity checks for the `trigger-client` including TWAP and price trigger examples.
+- `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
+```
+