tpluspy 0.1.0a0__py3-none-any.whl

tplus/client/__init__.py

@@ -0,0 +1,4 @@
+from .clearingengine import ClearingEngineClient
+from .orderbook import OrderBookClient
+
+__all__ = ("ClearingEngineClient", "OrderBookClient")

tplus/client/base.py

@@ -0,0 +1,291 @@
+import json
+import logging
+import ssl
+from collections.abc import AsyncIterator, Callable
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+import websockets
+
+from tplus.logger import get_logger
+from tplus.utils.user import User
+
+
+class BaseClient:
+    """
+    Base client to use across T+ services.
+    """
+
+    DEFAULT_TIMEOUT = 10.0
+    AUTH = True
+
+    def __init__(
+        self,
+        user: User,
+        base_url: str,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+        websocket_kwargs: dict[str, Any] | None = None,
+        log_level: int = logging.INFO,
+    ):
+        self.user = user
+        self.base_url = base_url.rstrip("/")
+        self._parsed_base_url = urlparse(self.base_url)
+        self._client = client or httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Content-Type": "application/json", "Accept": "application/json"},
+            verify=False,  # TODO remove that for production
+        )
+        self._ws_kwargs: dict[str, Any] = websocket_kwargs or {}
+
+        import asyncio
+
+        self._auth_lock: asyncio.Lock = asyncio.Lock()
+        self._auth_token: str | None = None
+        self._auth_expiry_ns: int = 0
+        self.logger = get_logger(log_level=log_level)
+
+    @classmethod
+    def from_client(cls, client: "BaseClient") -> "BaseClient":
+        """
+        Easy way to clone clients without initializing multiple AsyncClients.
+        """
+        return cls(client.user, client.base_url, client=client._client)
+
+    async def _get(self, endpoint: str, json_data: dict[str, Any] | None = None) -> dict[str, Any]:
+        return await self._request("GET", endpoint, json_data=json_data)
+
+    async def _post(self, endpoint: str, json_data: dict[str, Any] | None = None) -> dict[str, Any]:
+        return await self._request("POST", endpoint, json_data=json_data)
+
+    async def _request(
+        self, method: str, endpoint: str, json_data: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        relative_url = endpoint if endpoint.startswith("/") else f"/{endpoint}"
+
+        if self.AUTH and (
+            not relative_url.startswith("/nonce") and not relative_url.startswith("/auth")
+        ):
+            await self._ensure_auth()
+
+        try:
+            if json_data:
+                self.logger.debug(f"Request to {method} {relative_url} with payload: {json_data}")
+            request_headers = self._get_auth_headers()
+            if request_headers:
+                merged_headers = {**self._client.headers, **request_headers}
+            else:
+                merged_headers = None
+
+            response = await self._client.request(
+                method=method,
+                url=relative_url,
+                json=json_data,
+                headers=merged_headers,
+            )
+
+            # If we receive an HTTP 401/403, the auth token may have expired. Refresh the
+            # credentials **once** and retry the request automatically. This keeps the
+            # higher-level client APIs unaware of token lifetimes and greatly simplifies
+            # consumer code.
+            if response.status_code in {401, 403} and not relative_url.startswith("/auth"):
+                self.logger.info(
+                    "Received %s for %s – refreshing auth token and retrying once.",
+                    response.status_code,
+                    relative_url,
+                )
+
+                # Force re-authentication and rebuild the auth headers (inside the same
+                # lock to avoid a thundering herd when many coroutines hit expiry at the
+                # same time).
+                await self._authenticate()
+                retry_headers = {**self._client.headers, **self._get_auth_headers()}
+
+                response = await self._client.request(
+                    method=method,
+                    url=relative_url,
+                    json=json_data,
+                    headers=retry_headers,
+                )
+
+            if response.status_code == 204:
+                return {}
+            if not response.content:
+                return {}
+
+            try:
+                json_response = response.json()
+                if json_response is None:
+                    self.logger.warning(
+                        f"API endpoint {response.request.url!r} returned JSON null. Treating as empty dictionary."
+                    )
+                    return {}
+
+                return json_response
+
+            except Exception:
+                raise Exception(
+                    f"Invalid response from server - status_code={response.status_code}."
+                )
+
+        except httpx.TimeoutException as e:
+            self.logger.error(f"Request timed out to {e.request.url!r}: {e}")
+            raise
+        except httpx.RequestError as e:
+            self.logger.error(
+                f"An error occurred while requesting {e.request.url!r}: {type(e).__name__} - {e}"
+            )
+            raise
+        except httpx.HTTPStatusError as e:
+            self.logger.error(
+                f"HTTP error {e.response.status_code} while requesting {e.request.url!r}: {e.response.text}"
+            )
+            raise
+        except json.JSONDecodeError as e:
+            self.logger.error(
+                f"Failed to decode JSON response from {response.request.url!r}. Status: {response.status_code}. Content: {response.text[:100]}..."
+            )
+            raise ValueError(f"Invalid JSON received from API: {e}") from e
+
+    async def _ensure_auth(self) -> None:
+        import time
+
+        safety_margin_ns = 60 * 1_000_000_000
+        if self._auth_token and (time.time_ns() + safety_margin_ns) < self._auth_expiry_ns:
+            return
+
+        async with self._auth_lock:
+            if self._auth_token and (time.time_ns() + safety_margin_ns) < self._auth_expiry_ns:
+                return
+
+            await self._authenticate()
+
+    def _get_auth_headers(self) -> dict[str, str]:
+        if not self._auth_token:
+            return {}
+        return {
+            "Authorization": f"Bearer {self._auth_token}",
+            "User-Id": self.user.public_key,
+        }
+
+    async def _authenticate(self) -> None:
+        nonce_endpoint = f"/nonce/{self.user.public_key}"
+        nonce_resp = await self._client.get(nonce_endpoint)
+        nonce_resp.raise_for_status()
+        nonce_data = nonce_resp.json() if hasattr(nonce_resp, "json") else nonce_resp
+        nonce_value = nonce_data["value"] if isinstance(nonce_data, dict) else nonce_data
+
+        signature_bytes = self.user.sign(nonce_value)
+        signature_array = list(signature_bytes)
+
+        self.logger.debug(f"AUTH DEBUG: nonce={nonce_value} (len={len(nonce_value)})")
+        self.logger.debug(
+            f"AUTH DEBUG: signature={signature_array[:8]}... (len={len(signature_array)})"
+        )
+
+        auth_payload = {
+            "user_id": self.user.public_key,
+            "nonce": nonce_value,
+            "signature": signature_array,
+        }
+
+        token_resp = await self._client.post("/auth", json=auth_payload)
+        token_resp.raise_for_status()
+        token_json = token_resp.json() if hasattr(token_resp, "json") else token_resp
+
+        self.logger.info(f"Full authentication response from server: {token_json}")
+
+        self.logger.debug(
+            f"AUTH DEBUG: token={token_json.get('token')} expires={token_json.get('expiry_ns')}"
+        )
+
+        self._auth_token = token_json["token"]
+        self._auth_expiry_ns = int(token_json["expiry_ns"])
+
+    async def _ws_auth_headers(self) -> dict[str, str]:
+        if self.AUTH:
+            await self._ensure_auth()
+
+        return self._get_auth_headers()
+
+    def _get_websocket_url(self, path: str) -> str:
+        from urllib.parse import urlunparse
+
+        scheme = "wss" if self._parsed_base_url.scheme == "https" else "ws"
+        netloc = self._parsed_base_url.netloc
+        ws_path = path if path.startswith("/") else f"/{path}"
+        return urlunparse((scheme, netloc, ws_path, "", "", ""))
+
+    CONTROL_MESSAGE_TYPES: set[str] = {
+        "subscriptions",
+        "ping",
+        "pong",
+    }
+
+    async def _stream_ws(
+        self,
+        path: str,
+        parser: Callable[[Any], Any],
+        *,
+        control_handler: Callable[[dict[str, Any]], None] | None = None,
+    ) -> AsyncIterator[Any]:
+        ws_url = self._get_websocket_url(path)
+        self.logger.debug("Connecting to %s stream: %s", path, ws_url)
+        auth_headers = await self._ws_auth_headers()
+        ws_kwargs = dict(self._ws_kwargs)
+        if "extra_headers" in ws_kwargs and ws_kwargs["extra_headers"]:
+            caller_headers = ws_kwargs.pop("extra_headers")
+            if isinstance(caller_headers, dict):
+                caller_headers.update(auth_headers)
+                ws_kwargs["extra_headers"] = caller_headers
+            else:
+                ws_kwargs["extra_headers"] = list(auth_headers.items()) + list(caller_headers)
+        else:
+            ws_kwargs["extra_headers"] = auth_headers
+
+        # TODO Remove this when we have a real SSL certificate (or make it configurable)
+        ssl_context = ssl.create_default_context()
+        ssl_context.check_hostname = False
+        ssl_context.verify_mode = ssl.CERT_NONE
+
+        async with websockets.connect(ws_url, **ws_kwargs, ssl=ssl_context) as websocket:
+            async for message in websocket:
+                try:
+                    data = json.loads(message)
+                    if isinstance(data, dict) and data.get("type") in self.CONTROL_MESSAGE_TYPES:
+                        if control_handler is not None:
+                            control_handler(data)
+                        continue
+                    yield parser(data)
+                except json.JSONDecodeError:
+                    self.logger.warning(
+                        "Received non-JSON message on %s stream: %s…", path, message[:100]
+                    )
+                except Exception as e:
+                    self.logger.error(
+                        "Error processing message from %s stream: %s. Message: %s…",
+                        path,
+                        e,
+                        message[:100],
+                    )
+
+    async def close(self) -> None:
+        """
+        Closes the underlying httpx async client.
+        """
+        self.logger.debug("Closing async HTTP client.")
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        """
+        Async context manager entry.
+        """
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """
+        Async context manager exit.
+        """
+        await self.close()

tplus/client/clearingengine/__init__.py

@@ -0,0 +1,66 @@
+from functools import cached_property
+
+from tplus.client.clearingengine.admin import AdminClient
+from tplus.client.clearingengine.assetregistry import AssetRegistryClient
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+from tplus.client.clearingengine.decimal import DecimalClient
+from tplus.client.clearingengine.deposit import DepositClient
+from tplus.client.clearingengine.settlement import SettlementClient
+from tplus.client.clearingengine.vault import VaultClient
+from tplus.client.clearingengine.withdrawal import WithdrawalClient
+
+
+class ClearingEngineClient(BaseClearingEngineClient):
+    """
+    APIs targeting the clearing engine ("CE") directly. Most of the APIs are
+    permission-less; however some require signing, such as settlements and withdrawal flows.
+    """
+
+    @cached_property
+    def settlements(self) -> SettlementClient:
+        """
+        APIs related to settlements.
+        """
+        return SettlementClient.from_client(self)
+
+    @cached_property
+    def assets(self) -> AssetRegistryClient:
+        """
+        APIs related to registered assets.
+        """
+        return AssetRegistryClient.from_client(self)
+
+    @cached_property
+    def decimals(self) -> DecimalClient:
+        """
+        APIs related to decimals.
+        """
+        return DecimalClient.from_client(self)
+
+    @cached_property
+    def deposits(self) -> DepositClient:
+        """
+        APIs related to deposits.
+        """
+        return DepositClient.from_client(self)
+
+    @cached_property
+    def withdrawals(self) -> WithdrawalClient:
+        """
+        APIs related to withdrawals.
+        """
+        return WithdrawalClient.from_client(self)
+
+    @cached_property
+    def vaults(self) -> VaultClient:
+        """
+        APIs related to vaults.
+        """
+        return VaultClient.from_client(self)
+
+    @cached_property
+    def admin(self) -> AdminClient:
+        """
+        APIs related to the admin clearing-engine.
+        """
+        return AdminClient.from_client(self)

tplus/client/clearingengine/admin.py

@@ -0,0 +1,30 @@
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+from tplus.model.asset_identifier import AssetIdentifier
+from tplus.model.types import UserPublicKey
+
+
+class AdminClient(BaseClearingEngineClient):
+    async def get_verifying_key(self):
+        """
+        Get a clearing-engine's verifying key.
+
+        Returns:
+            str | None
+        """
+        return await self._get("admin/verifying-key")
+
+    async def modify_user_inventory(
+        self, user: "UserPublicKey", asset: "AssetIdentifier", balance: dict
+    ):
+        """
+        Admin-only API for testing.
+        """
+        if not isinstance(user, UserPublicKey):
+            user = UserPublicKey.__validate_user__(user)
+        if not isinstance(asset, AssetIdentifier):
+            asset = AssetIdentifier.model_validate(asset)
+
+        asset = asset.model_dump()
+        await self._post(
+            "admin/inventory/modify", json_data={"user": user, "asset": asset, "balance": balance}
+        )

tplus/client/clearingengine/assetregistry.py

@@ -0,0 +1,37 @@
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+
+
+class AssetRegistryClient(BaseClearingEngineClient):
+    """
+    Clearing engine APIs related to assets.
+    """
+
+    async def get(self) -> dict:
+        """
+        Get all registered assets in the CE.
+
+        Returns:
+            dict: A mapping of stringified asset index (base 10) to chain ID to asset information.
+        """
+        return await self._get("assets")
+
+    async def get_risk_parameters(self):
+        """
+        Get all registered risk parameters in the CE.
+
+        Returns:
+            dict: A mapping of asset identifiers to their respective risk parameters.
+        """
+        return await self._get("params")
+
+    async def update(self):
+        """
+        Request that the clearing engine updates its registered assets for the given registry chain.
+        """
+        await self._post("assets/update")
+
+    async def update_risk_parameters(self):
+        """
+        Request that the clearing engine updates its registered risk parameters.
+        """
+        await self._post("params/update")

tplus/client/clearingengine/base.py

@@ -0,0 +1,5 @@
+from tplus.client.base import BaseClient
+
+
+class BaseClearingEngineClient(BaseClient):
+    AUTH = False

tplus/client/clearingengine/decimal.py

@@ -0,0 +1,47 @@
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+from tplus.model.asset_identifier import AssetIdentifier
+
+
+def _prep_request(
+    asset_ids: list[str | AssetIdentifier] | str | AssetIdentifier, chains: list[int] | int
+) -> dict:
+    if not isinstance(asset_ids, list):
+        asset_ids = [asset_ids]
+    if not isinstance(chains, list):
+        chains = [chains]
+
+    assets = []
+    for asset in asset_ids:
+        if not isinstance(asset, AssetIdentifier):
+            asset = AssetIdentifier.model_validate(asset)
+
+        assets.append(asset.model_dump())
+
+    return {"assets": assets, "chains": chains}
+
+
+class DecimalClient(BaseClearingEngineClient):
+    """
+    APIs related to decimals.
+    """
+
+    async def get(self, asset_id: list[str | AssetIdentifier], chains: list[int]) -> dict:
+        """
+        Get CE cached decimals for the given assets and chains.
+
+        Args:
+            asset_id (list[str | AssetIdentifier]): Asset identifiers.
+            chains (list[int]): Chains identifiers.
+
+        Returns:
+            A mapping of asset Ids => chains => decimals.
+        """
+        request = _prep_request(asset_id, chains)
+        return await self._get("decimals", json_data=request)
+
+    async def update(self, asset_id: list[str | AssetIdentifier], chains: list[int]):
+        """
+        Request that the CE update cache decimals for the given assets and chains.
+        """
+        request = _prep_request(asset_id, chains)
+        await self._post("decimals/update", json_data=request)

tplus/client/clearingengine/deposit.py

@@ -0,0 +1,19 @@
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+
+
+class DepositClient(BaseClearingEngineClient):
+    """
+    APIs related to deposits.
+    """
+
+    async def update(self, user: str, chain_id: int):
+        """
+        Request that the CE check the deposit vault for new deposits for
+        the given user.
+
+        Args:
+            user (str): The user pubkey key ID.
+            chain_id (int): The chain ID to check.
+        """
+        request = {"user": user, "chain_id": chain_id}
+        await self._post("deposits/update", json_data=request)

tplus/client/clearingengine/settlement.py

@@ -0,0 +1,84 @@
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+from tplus.model.asset_identifier import ChainAddress
+from tplus.model.settlement import BatchSettlementRequest, TxSettlementRequest
+
+
+class SettlementClient(BaseClearingEngineClient):
+    """
+    Clearing engine APIs related to settlements.
+    """
+
+    async def init_settlement(self, request: dict | TxSettlementRequest):
+        """
+        Initialize a transaction (atomic) based settlement. This begins the process
+        of settling. Use ``get_signatures()`` to retrieve successful signatures.
+
+        Args:
+            request (dict | TxSettlementRequest): transaction request.
+        """
+        if isinstance(request, dict):
+            # Validate.
+            request = TxSettlementRequest.model_validate(request)
+
+        data = request.model_dump(mode="json")
+        await self._post("settlement/init", json_data=data)
+
+    async def get_signatures(self, user: str) -> dict:
+        """
+        Get CE approved signatures for the given user for settlement. This happens
+        after settlement initialization.
+
+        Args:
+            user (str): The settler.
+
+        Returns:
+            A list of signatures (rust int arrays).
+        """
+        return await self._get(f"settlement/signatures/{user}")
+
+    async def init_batch_settlement(self, request: dict | BatchSettlementRequest):
+        """
+        Initialize a bundle-based settlement.
+
+        Args:
+            request (dict | BatchSettlementRequest): The transaction request.
+        """
+        if isinstance(request, dict):
+            # Validate.
+            request = BatchSettlementRequest.model_validate(request)
+
+        json_data = request.model_dump(mode="json")
+        await self._post("settlement/batch", json_data=json_data)
+
+    async def update(self, user: str, chain_id: int):
+        """
+        Request that the CE check the deposit vault for new settlements for
+        the given user.
+
+        Args:
+            user (str): The user pubkey key ID.
+            chain_id (int): The chain ID to check.
+        """
+        request = {"user": user, "chain_id": chain_id}
+        await self._post("settlement/update", json_data=request)
+
+    async def update_approved_settlers(self, chain_id: int, vault_address: str):
+        """
+        Request that the CE check the deposit vault for new approved settlers.
+
+        Args:
+            chain_id (int): The chain ID to check.
+            vault_address (str): The vault address to check.
+        """
+        request = ChainAddress(f"{vault_address}@{chain_id}")
+        json_data = request.model_dump(mode="json")
+        await self._post("settlers/update", json_data=json_data)
+
+    async def get_approved_settlers(self, chain_id: int) -> list[str]:
+        """
+        Request that the CE check the deposit vault for new approved settlers.
+
+        Args:
+            chain_id (int): The chain ID to check.
+        """
+        return await self._get(f"settlers/{chain_id}")

tplus/client/clearingengine/vault.py

@@ -0,0 +1,34 @@
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+from tplus.model.asset_identifier import AssetIdentifier, ChainAddress
+from tplus.model.types import ChainID
+
+
+class VaultClient(BaseClearingEngineClient):
+    """
+    APIs related to vaults.
+    """
+
+    async def update(self):
+        """
+        Request that the CE check the registry contract for new registered vaults.
+        """
+        await self._post("vaults/update")
+
+    async def update_balance(self, asset_id: AssetIdentifier | str, chain_id: ChainID):
+        """
+        Request that the CE check the deposit vault for new deposits for
+        the given user.
+
+        Args:
+            asset_id (AssetIdentifier | str): The asset identifier.
+            chain_id (:class:`~tplus.models.types.ChainID`): The chain ID to check.
+        """
+        request = {"asset_id": asset_id, "chain_id": chain_id}
+        await self._post("vault/balance/update", json_data=request)
+
+    async def get(self) -> list[ChainAddress]:
+        """
+        Get all registered vaults.
+        """
+        result = await self._get("vaults") or []
+        return [ChainAddress.model_validate(a) for a in result]

tplus/client/clearingengine/withdrawal.py

@@ -0,0 +1,57 @@
+from tplus.client.clearingengine.base import BaseClearingEngineClient
+from tplus.model.withdrawal import WithdrawalRequest
+
+
+class WithdrawalClient(BaseClearingEngineClient):
+    """
+    APIs related to withdrawal.
+    """
+
+    async def init_withdrawal(self, withdrawal: dict | WithdrawalRequest):
+        """
+        Begin the steps of initializing a withdrawal. Once successful, can
+        use ``.get_signatures()`` to fetch the resulting signatures for
+        completing the withdrawal.
+
+        Args:
+            withdrawal (dict | WithdrawalRequest): The withdrawal data
+        """
+        if isinstance(withdrawal, dict):
+            # Validate.
+            withdrawal = WithdrawalRequest.model_validate(withdrawal)
+
+        json_data = withdrawal.model_dump(mode="json")
+        await self._post("withdrawal/init", json_data=json_data)
+
+    async def get_signatures(self, user: str) -> dict:
+        """
+        Get CE approved signatures for the given user for withdrawal. This happens
+        after withdrawal initialization.
+
+        Args:
+            user (str): The user withdrawing.
+
+        Returns:
+            A list of signatures (rust int arrays).
+        """
+        return await self._get(f"withdrawal/signatures/{user}")
+
+    async def update(self, user: str, chain_id: int):
+        """
+        Request the CE check for new completed deposits for the given user on
+        the given chain.
+
+        Args:
+            user (str): The user withdrawing.
+            chain_id (int): The chain to request withdrawals for.
+        """
+        await self._post("withdrawal/update", json_data={"user": user, "chain_id": chain_id})
+
+    async def get_queued(self, user: str) -> list[WithdrawalRequest]:
+        """
+        Get a user's queued withdrawals.
+
+        Args:
+            user (str): The user withdrawing.
+        """
+        return await self._get(f"withdrawal/queue/{user}")