polyester-sdk 0.1.0a0__py3-none-any.whl

polyester/__init__.py

@@ -0,0 +1,32 @@
+from polyester.client import AsyncPolyester, Polyester
+from polyester.codecs.ledger_amounts import LEDGER_SCALE, format_ledger_u128
+from polyester.errors import (
+    PolyesterApiError,
+    PolyesterAuthError,
+    PolyesterError,
+    PolyesterRateLimitError,
+    PolyesterRealtimeError,
+    PolyesterRouteNotFoundError,
+    PolyesterServerError,
+    PolyesterTransportError,
+    PolyesterValidationError,
+)
+
+__version__ = "0.1.0a0"
+
+__all__ = [
+    "AsyncPolyester",
+    "LEDGER_SCALE",
+    "Polyester",
+    "PolyesterApiError",
+    "PolyesterAuthError",
+    "PolyesterError",
+    "PolyesterRateLimitError",
+    "PolyesterRealtimeError",
+    "PolyesterRouteNotFoundError",
+    "PolyesterServerError",
+    "PolyesterTransportError",
+    "PolyesterValidationError",
+    "__version__",
+    "format_ledger_u128",
+]

polyester/_wire.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any
+
+from connectrpc.errors import ConnectError
+from google.protobuf.json_format import MessageToDict
+from google.protobuf.message import Message
+
+from polyester.errors import (
+    PolyesterApiError,
+    PolyesterAuthError,
+    PolyesterRouteNotFoundError,
+    PolyesterServerError,
+    PolyesterTransportError,
+)
+from polyester.gen.orders.v1 import orders_pb2
+
+_ROUTE_NOT_FOUND_MESSAGES = frozenset(
+    {"not found", "404 page not found", "404 not found"}
+)
+
+
+def protobuf_to_public_dict(message: Message) -> dict[str, Any]:
+    return MessageToDict(
+        message,
+        preserving_proto_field_name=False,
+        always_print_fields_with_no_presence=True,
+    )
+
+
+def map_connect_error(exc: ConnectError):
+    if exc.details:
+        for detail in exc.details:
+            full_name = detail.DESCRIPTOR.full_name
+            if full_name.endswith("ErrorDetail") and hasattr(detail, "code"):
+                code_name = orders_pb2.ErrorCode.Name(detail.code)
+                if (
+                    "POLICY" in code_name
+                    or "UNAUTHENTICATED" in code_name
+                    or "PERMISSION" in code_name
+                ):
+                    return PolyesterAuthError(exc.message)
+                if code_name.startswith("ERROR_CODE_"):
+                    return PolyesterApiError(exc.message, code=code_name)
+    code = exc.code.value
+    if code in ("unauthenticated", "permission_denied"):
+        return PolyesterAuthError(exc.message)
+    if code in ("unavailable", "internal"):
+        return PolyesterServerError(exc.message)
+    if code == "deadline_exceeded":
+        return PolyesterTransportError(exc.message)
+    message = (exc.message or "").strip().lower()
+    if code == "unimplemented" and message in _ROUTE_NOT_FOUND_MESSAGES:
+        return PolyesterRouteNotFoundError()
+    return PolyesterApiError(exc.message, code=code)

polyester/auth.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import time
+from dataclasses import dataclass
+from urllib.parse import parse_qsl, quote, urlsplit
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from polyester.errors import PolyesterAuthError
+
+API_KEY_ID_ENV = "POLYESTER_API_KEY_ID"
+API_PRIVATE_KEY_ENV = "POLYESTER_API_PRIVATE_KEY"
+ACCOUNT_ID_ENV = "POLYESTER_ACCOUNT_ID"
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKeyCredentials:
+    key_id: str
+    private_key: bytes
+
+
+def load_api_key_credentials(
+    *,
+    api_key_id: str | None = None,
+    api_private_key: str | bytes | None = None,
+    from_env: bool = True,
+) -> ApiKeyCredentials | None:
+    key_id = api_key_id
+    private = api_private_key
+    if from_env:
+        key_id = key_id or os.getenv(API_KEY_ID_ENV)
+        private = private if private is not None else os.getenv(API_PRIVATE_KEY_ENV)
+    if not key_id and not private:
+        return None
+    if not key_id or private is None:
+        if from_env:
+            message = "Both POLYESTER_API_KEY_ID and POLYESTER_API_PRIVATE_KEY are required"
+        else:
+            message = "Both api_key_id and api_private_key are required"
+        raise PolyesterAuthError(
+            message
+        )
+    return ApiKeyCredentials(key_id=key_id, private_key=normalize_private_key(private))
+
+
+def normalize_private_key(value: str | bytes) -> bytes:
+    if isinstance(value, bytes):
+        private = value
+    else:
+        try:
+            private = bytes.fromhex(value.strip())
+        except ValueError as exc:
+            raise PolyesterAuthError(
+                "API private key must be a valid hex string or raw bytes"
+            ) from exc
+    if len(private) != 32:
+        raise PolyesterAuthError("Ed25519 API private key must be exactly 32 bytes")
+    return private
+
+
+def generate_ed25519_keypair() -> tuple[bytes, bytes]:
+    """Generate a new Ed25519 keypair (public, secret), each 32 bytes."""
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    return public_key.public_bytes_raw(), private_key.private_bytes_raw()
+
+
+def sha256_hex(body: bytes) -> str:
+    return hashlib.sha256(body).hexdigest()
+
+
+def canonical_query(url: str) -> str:
+    pairs = []
+    for key, value in parse_qsl(urlsplit(url).query, keep_blank_values=True):
+        pairs.append(f"{quote(key, safe='')}={quote(value, safe='')}")
+    pairs.sort()
+    return "&".join(pairs)
+
+
+def canonical_signing_string(
+    *,
+    timestamp_ms: str,
+    method: str,
+    url: str,
+    body: bytes,
+) -> str:
+    pathname = urlsplit(url).path or "/"
+    return "\n".join(
+        [timestamp_ms, method.upper(), pathname, canonical_query(url), sha256_hex(body)]
+    )
+
+
+def sign_request(
+    credentials: ApiKeyCredentials,
+    *,
+    method: str,
+    url: str,
+    body: bytes = b"",
+    timestamp_ms: str | None = None,
+) -> dict[str, str]:
+    timestamp = timestamp_ms or str(int(time.time() * 1000))
+    canonical = canonical_signing_string(
+        timestamp_ms=timestamp,
+        method=method,
+        url=url,
+        body=body,
+    )
+    key = Ed25519PrivateKey.from_private_bytes(credentials.private_key)
+    signature = key.sign(canonical.encode("utf-8")).hex()
+    return {
+        "X-API-KEY-ID": credentials.key_id,
+        "X-API-TIMESTAMP": timestamp,
+        "X-API-SIGNATURE": signature,
+    }

polyester/auth_interceptor.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+from connectrpc.codec import Codec
+from connectrpc.interceptor import UnaryInterceptor
+from connectrpc.request import RequestContext
+from google.protobuf.message import Message
+
+from polyester.auth import ApiKeyCredentials, sign_request
+
+
+class ApiKeyAuthUnaryInterceptor(UnaryInterceptor):
+    """Attach Polyester API-key headers to generated Connect unary calls."""
+
+    def __init__(
+        self,
+        credentials: ApiKeyCredentials,
+        *,
+        base_url: str,
+        codec: Codec,
+    ) -> None:
+        self._credentials = credentials
+        self._base_url = base_url.rstrip("/")
+        self._codec = codec
+
+    async def intercept_unary(
+        self,
+        call_next: Callable[[Message, RequestContext], Awaitable[Message]],
+        request: Message,
+        ctx: RequestContext,
+    ) -> Message:
+        info = ctx.method()
+        url = f"{self._base_url}/{info.service_name}/{info.name}"
+        body = self._codec.encode(request)
+        headers = sign_request(
+            self._credentials,
+            method=ctx.http_method(),
+            url=url,
+            body=body,
+        )
+        ctx.request_headers().update(headers)
+        return await call_next(request, ctx)

polyester/catalogs/__init__.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from polyester.catalogs.zipper import build_zipper_catalog_data
+from polyester.catalogs.zipper_supply import patch_zipper_catalog_supply
+from polyester.models.zipper import (
+    DepositWithdrawConfig,
+    ZippedAssetSupplyUpdate,
+    ZipperCatalogData,
+)
+
+
+@dataclass(slots=True)
+class CatalogManager:
+    spot_config: dict[str, Any] = field(default_factory=dict)
+    zipper: ZipperCatalogData | None = None
+    deposit_withdraw_config: DepositWithdrawConfig | None = None
+    _legacy_zipper_raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def zipper_config(self) -> dict[str, Any]:
+        """Backward-compatible raw dict view of the typed zipper catalog."""
+        if self.deposit_withdraw_config is None:
+            return {}
+        config = self.deposit_withdraw_config
+        return {
+            "chains": [msgspec_to_dict(chain) for chain in config.chains],
+            "assets": [
+                {
+                    **msgspec_to_dict(asset),
+                    "variants": [msgspec_to_dict(variant) for variant in asset.variants],
+                }
+                for asset in config.assets
+            ],
+            "contracts": [msgspec_to_dict(item) for item in config.contracts],
+            "polyesterChainId": config.polyester_chain_id,
+            "tsSec": config.ts_ms // 1000 if config.ts_ms else 0,
+        }
+
+    def hydrate_spot_config(self, config: dict[str, Any]) -> None:
+        self.spot_config = config
+
+    def hydrate_zipper_config(
+        self,
+        config: DepositWithdrawConfig | dict[str, Any],
+    ) -> None:
+        if isinstance(config, DepositWithdrawConfig):
+            self.deposit_withdraw_config = config
+            self.zipper = build_zipper_catalog_data(config)
+            return
+        self.deposit_withdraw_config = None
+        self.zipper = None
+        self._legacy_zipper_raw = config
+
+    def hydrate_deposit_withdraw_config(self, config: DepositWithdrawConfig) -> None:
+        self.hydrate_zipper_config(config)
+
+    def symbol_id_for_symbol(self, symbol: str) -> int | None:
+        for pair in self._pairs():
+            if pair.get("symbol") == symbol:
+                value = pair.get("symbol_id") or pair.get("symbolId")
+                return int(value) if value is not None else None
+        return None
+
+    def base_quantity_scale_for_symbol(self, symbol: str) -> int:
+        for pair in self._pairs():
+            if pair.get("symbol") == symbol:
+                value = (
+                    pair.get("base_quantity_scale")
+                    or pair.get("baseQuantityScale")
+                    or pair.get("qtyScale")
+                )
+                return int(value) if value is not None else 8
+        return 8
+
+    def orderbook_price_buckets_for_symbol(self, symbol: str) -> list[str]:
+        pair = self._pair_for_symbol(symbol)
+        if pair is None:
+            return []
+        marketdata = pair.get("marketdata") or pair.get("marketData") or {}
+        buckets = marketdata.get("orderbook_price_buckets") or marketdata.get(
+            "orderbookPriceBuckets"
+        )
+        if not isinstance(buckets, list):
+            return []
+        result: list[str] = []
+        for value in buckets:
+            if isinstance(value, (int, float)):
+                text = format(value, "f").rstrip("0").rstrip(".") or "0"
+                result.append(text)
+            elif value is not None:
+                result.append(str(value))
+        return result
+
+    def ledger_id_for_asset(self, asset_symbol: str) -> int | None:
+        catalog = self.zipper
+        if catalog is not None:
+            for asset in catalog.assets:
+                if asset.asset == asset_symbol:
+                    return asset.ledger_id or None
+        raw = self._legacy_zipper_raw or self.zipper_config
+        for row in raw.get("assets") or []:
+            symbol = row.get("asset") or row.get("code")
+            if symbol == asset_symbol:
+                value = row.get("ledgerId") or row.get("ledger_id")
+                return int(value) if value is not None else None
+        return None
+
+    def quantity_scale_for_asset(self, asset_symbol: str) -> int | None:
+        catalog = self.zipper
+        if catalog is not None:
+            for asset in catalog.assets:
+                if asset.asset == asset_symbol:
+                    return asset.quantity_scale
+        raw = self._legacy_zipper_raw or self.zipper_config
+        for row in raw.get("assets") or []:
+            symbol = row.get("asset") or row.get("code")
+            if symbol == asset_symbol:
+                value = row.get("quantityScale") or row.get("quantity_scale")
+                return int(value) if value is not None else None
+        return None
+
+    def quantity_scale_for_zipped_asset_id(self, zipped_asset_id: int) -> int:
+        catalog = self.zipper
+        if catalog is not None:
+            for asset in catalog.assets:
+                for chain in asset.chains:
+                    if chain.zipped_asset_id == zipped_asset_id:
+                        return asset.quantity_scale
+        return 18
+
+    def patch_zipper_supply(self, updates: list[ZippedAssetSupplyUpdate]) -> bool:
+        if self.zipper is None or not updates:
+            return False
+        patched = patch_zipper_catalog_supply(self.zipper, updates)
+        if patched is self.zipper:
+            return False
+        self.zipper = patched
+        return True
+
+    def _pair_for_symbol(self, symbol: str) -> dict[str, Any] | None:
+        for pair in self._pairs():
+            if pair.get("symbol") == symbol:
+                return pair
+        return None
+
+    def _pairs(self) -> list[dict[str, Any]]:
+        pairs = self.spot_config.get("pairs") or self.spot_config.get("symbols") or []
+        return [pair for pair in pairs if isinstance(pair, dict)]
+
+
+def msgspec_to_dict(value: object) -> dict[str, Any]:
+    import msgspec
+
+    return msgspec.to_builtins(value)

polyester/catalogs/zipper.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from polyester.models.zipper import (
+    DepositWithdrawConfig,
+    ZipperAssetConfig,
+    ZipperCatalogData,
+    ZipperChainConfig,
+    ZipperEnrichedAssetChain,
+    ZipperEnrichedAssetConfig,
+)
+
+
+def build_zipper_catalog_data(config: DepositWithdrawConfig) -> ZipperCatalogData:
+    chains_by_id = {chain.chain_id: chain for chain in config.chains}
+    enriched_assets: list[ZipperEnrichedAssetConfig] = []
+    for asset in config.assets:
+        enriched_assets.append(
+            ZipperEnrichedAssetConfig(
+                asset=asset.asset,
+                ledger_id=asset.ledger_id,
+                name=asset.name,
+                icon=asset.icon,
+                quantity_scale=asset.quantity_scale,
+                quantity_display_decimals=asset.quantity_display_decimals,
+                u_asset_id=asset.u_asset_id,
+                chains=_enrich_asset_chains(asset, chains_by_id),
+            )
+        )
+    return ZipperCatalogData(
+        chains=list(config.chains),
+        assets=enriched_assets,
+        contracts=list(config.contracts),
+        ts_ms=config.ts_ms,
+    )
+
+
+def _enrich_asset_chains(
+    asset: ZipperAssetConfig,
+    chains_by_id: dict[int, ZipperChainConfig],
+) -> list[ZipperEnrichedAssetChain]:
+    enriched: list[ZipperEnrichedAssetChain] = []
+    for variant in asset.variants:
+        chain = chains_by_id.get(variant.chain_id)
+        if chain is None:
+            continue
+        enriched.append(
+            ZipperEnrichedAssetChain(
+                chain_id=chain.chain_id,
+                code=chain.code,
+                name=chain.name,
+                native_chain_id=chain.native_chain_id,
+                native_currency_symbol=chain.native_currency_symbol,
+                explorer_url=chain.explorer_url,
+                icon=chain.icon,
+                required_confirmations=chain.required_confirmations,
+                confirmation_time_seconds=chain.confirmation_time_seconds,
+                is_case_sensitive=chain.is_case_sensitive,
+                min_address_length=chain.min_address_length,
+                max_address_length=chain.max_address_length,
+                zipped_asset_id=variant.zipped_asset_id,
+                is_native_asset=variant.is_native_asset,
+                network_fee=variant.network_fee,
+                network_fee_ts_sec=variant.network_fee_ts_sec,
+                deposit_min_amount=variant.deposit_min_amount,
+                withdraw_min_amount=variant.withdraw_min_amount,
+                supply=variant.supply,
+                source_token=variant.source_token,
+                z_token=variant.z_token,
+            )
+        )
+    return enriched

polyester/catalogs/zipper_supply.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import time
+
+from polyester.models.zipper import (
+    ZippedAssetSupplyUpdate,
+    ZipperCatalogData,
+    ZipperEnrichedAssetChain,
+    ZipperEnrichedAssetConfig,
+)
+
+
+def patch_zipper_catalog_supply(
+    catalog: ZipperCatalogData,
+    updates: list[ZippedAssetSupplyUpdate],
+) -> ZipperCatalogData:
+    if not updates:
+        return catalog
+
+    supply_by_id = {item.zipped_asset_id: item.supply for item in updates}
+    changed = False
+    next_assets: list[ZipperEnrichedAssetConfig] = []
+
+    for asset in catalog.assets:
+        asset_changed = False
+        next_chains: list[ZipperEnrichedAssetChain] = []
+        for chain in asset.chains:
+            supply = supply_by_id.get(chain.zipped_asset_id)
+            if supply is None or supply == chain.supply:
+                next_chains.append(chain)
+                continue
+            asset_changed = True
+            changed = True
+            next_chains.append(
+                ZipperEnrichedAssetChain(
+                    chain_id=chain.chain_id,
+                    code=chain.code,
+                    name=chain.name,
+                    native_chain_id=chain.native_chain_id,
+                    native_currency_symbol=chain.native_currency_symbol,
+                    explorer_url=chain.explorer_url,
+                    icon=chain.icon,
+                    required_confirmations=chain.required_confirmations,
+                    confirmation_time_seconds=chain.confirmation_time_seconds,
+                    is_case_sensitive=chain.is_case_sensitive,
+                    min_address_length=chain.min_address_length,
+                    max_address_length=chain.max_address_length,
+                    zipped_asset_id=chain.zipped_asset_id,
+                    is_native_asset=chain.is_native_asset,
+                    network_fee=chain.network_fee,
+                    network_fee_ts_sec=chain.network_fee_ts_sec,
+                    deposit_min_amount=chain.deposit_min_amount,
+                    withdraw_min_amount=chain.withdraw_min_amount,
+                    supply=supply,
+                    source_token=chain.source_token,
+                    z_token=chain.z_token,
+                )
+            )
+        if asset_changed:
+            next_assets.append(
+                ZipperEnrichedAssetConfig(
+                    asset=asset.asset,
+                    ledger_id=asset.ledger_id,
+                    name=asset.name,
+                    icon=asset.icon,
+                    quantity_scale=asset.quantity_scale,
+                    quantity_display_decimals=asset.quantity_display_decimals,
+                    u_asset_id=asset.u_asset_id,
+                    chains=next_chains,
+                )
+            )
+        else:
+            next_assets.append(asset)
+
+    if not changed:
+        return catalog
+
+    ts_ms = int(time.time() * 1000)
+    return ZipperCatalogData(
+        chains=list(catalog.chains),
+        assets=next_assets,
+        contracts=list(catalog.contracts),
+        ts_ms=ts_ms,
+    )