hotstuff-python-sdk 0.0.1b2__py3-none-any.whl → 0.0.1b4__py3-none-any.whl

hotstuff/methods/subscription/channels.py

@@ -0,0 +1,200 @@
+"""Subscription channel method types."""
+from typing import List, Literal, Optional
+from pydantic import BaseModel, Field, field_validator
+
+from hotstuff.utils.address import validate_ethereum_address
+
+
+# Chart types
+SupportedChartResolutions = Literal["1", "5", "15", "60", "240", "1D", "1W"]
+SupportedChartTypes = Literal["mark", "ltp", "index"]
+
+
+# Subscription parameter types
+class TickerSubscriptionParams(BaseModel):
+    """Parameters for ticker subscription."""
+    symbol: str = Field(..., description="Trading pair symbol")
+
+
+class MidsSubscriptionParams(BaseModel):
+    """Parameters for mids subscription."""
+    symbol: str = Field(..., description="Trading pair symbol")
+
+
+class BBOSubscriptionParams(BaseModel):
+    """Parameters for BBO subscription."""
+    symbol: str = Field(..., description="Trading pair symbol")
+
+
+class OrderbookSubscriptionParams(BaseModel):
+    """Parameters for orderbook subscription."""
+    instrument_id: str = Field(..., description="Instrument ID")
+
+
+class TradeSubscriptionParams(BaseModel):
+    """Parameters for trade subscription."""
+    instrument_id: str = Field(..., description="Instrument ID")
+
+
+class ChartSubscriptionParams(BaseModel):
+    """Parameters for chart subscription."""
+    symbol: str = Field(..., description="Trading pair symbol")
+    chart_type: SupportedChartTypes = Field(..., description="Chart type")
+    resolution: SupportedChartResolutions = Field(..., description="Chart resolution")
+
+
+class AccountOrderUpdatesParams(BaseModel):
+    """Parameters for account order updates subscription."""
+    user: str = Field(..., description="User address")
+    
+    @field_validator('user', mode='before')
+    @classmethod
+    def validate_user(cls, v: str) -> str:
+        """Validate and checksum the user address."""
+        return validate_ethereum_address(v)
+    
+    # Alias for backward compatibility
+    @property
+    def address(self) -> str:
+        """Alias for user field (deprecated)."""
+        return self.user
+
+
+class AccountBalanceUpdatesParams(BaseModel):
+    """Parameters for account balance updates subscription."""
+    user: str = Field(..., description="User address")
+    
+    @field_validator('user', mode='before')
+    @classmethod
+    def validate_user(cls, v: str) -> str:
+        """Validate and checksum the user address."""
+        return validate_ethereum_address(v)
+    
+    @property
+    def address(self) -> str:
+        """Alias for user field (deprecated)."""
+        return self.user
+
+
+class PositionsSubscriptionParams(BaseModel):
+    """Parameters for positions subscription."""
+    user: str = Field(..., description="User address")
+    
+    @field_validator('user', mode='before')
+    @classmethod
+    def validate_user(cls, v: str) -> str:
+        """Validate and checksum the user address."""
+        return validate_ethereum_address(v)
+    
+    @property
+    def address(self) -> str:
+        """Alias for user field (deprecated)."""
+        return self.user
+
+
+class FillsSubscriptionParams(BaseModel):
+    """Parameters for fills subscription."""
+    user: str = Field(..., description="User address")
+    
+    @field_validator('user', mode='before')
+    @classmethod
+    def validate_user(cls, v: str) -> str:
+        """Validate and checksum the user address."""
+        return validate_ethereum_address(v)
+    
+    @property
+    def address(self) -> str:
+        """Alias for user field (deprecated)."""
+        return self.user
+
+
+class AccountSummarySubscriptionParams(BaseModel):
+    """Parameters for account summary subscription."""
+    user: str = Field(..., description="User address")
+    
+    @field_validator('user', mode='before')
+    @classmethod
+    def validate_user(cls, v: str) -> str:
+        """Validate and checksum the user address."""
+        return validate_ethereum_address(v)
+
+
+class BlocksSubscriptionParams(BaseModel):
+    """Parameters for blocks subscription."""
+    pass
+
+
+class TransactionsSubscriptionParams(BaseModel):
+    """Parameters for transactions subscription."""
+    pass
+
+
+# Orderbook subscription
+class OrderbookItem(BaseModel):
+    """Orderbook item."""
+    price: float
+    size: float
+    amount: Optional[float] = None
+
+
+class Orderbook(BaseModel):
+    """Orderbook subscription data."""
+    instrument_id: str
+    instrument_name: Optional[str] = None
+    asks: List[OrderbookItem]
+    bids: List[OrderbookItem]
+    timestamp: int
+
+
+# Trade subscription
+class Trade(BaseModel):
+    """Trade subscription data."""
+    id: str
+    instrument: str
+    instrument_name: Optional[str] = None
+    maker: str
+    taker: str
+    price: float
+    size: float
+    timestamp: int
+    side: Literal["buy", "sell"]
+
+
+# Order update subscription
+class OrderUpdate(BaseModel):
+    """Order update subscription data."""
+    id: str
+    account: str
+    instrument: str
+    price: float
+    size: float
+    side: Literal["buy", "sell"]
+    status: str
+    timestamp: int
+
+
+# Account balance update subscription
+class BalanceItem(BaseModel):
+    """Balance item."""
+    asset: str
+    total: float
+    available: float
+    locked: float
+
+
+class AccountBalanceUpdate(BaseModel):
+    """Account balance update subscription data."""
+    account: str
+    balances: List[BalanceItem]
+    timestamp: int
+
+
+# Chart update subscription
+class ChartUpdate(BaseModel):
+    """Chart update subscription data."""
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float
+    time: int

hotstuff/methods/subscription/global.py

@@ -1,200 +1,55 @@
-"""Global subscription method types."""
-from typing import List, Literal, Optional
-from pydantic import BaseModel, Field, field_validator
-from eth_utils import is_address, to_checksum_address
-
-
-def validate_ethereum_address(value: str) -> str:
-    """
-    Validate and normalize an Ethereum address.
-    
-    Args:
-        value: The address string to validate
-        
-    Returns:
-        Checksummed address string
-        
-    Raises:
-        ValueError: If the address is invalid
-    """
-    if not isinstance(value, str):
-        raise ValueError(f"Address must be a string, got {type(value)}")
-    
-    if not is_address(value):
-        raise ValueError(f"Invalid Ethereum address: {value}")
-    
-    return to_checksum_address(value)
-
-
-# Chart types
-SupportedChartResolutions = Literal["1", "5", "15", "60", "240", "1D", "1W"]
-SupportedChartTypes = Literal["mark", "ltp", "index"]
-
-
-# Subscription parameter types
-class TickerSubscriptionParams(BaseModel):
-    """Parameters for ticker subscription."""
-    symbol: str = Field(..., description="Trading pair symbol")
-
-
-class MidsSubscriptionParams(BaseModel):
-    """Parameters for mids subscription."""
-    symbol: str = Field(..., description="Trading pair symbol")
-
-
-class BBOSubscriptionParams(BaseModel):
-    """Parameters for BBO subscription."""
-    symbol: str = Field(..., description="Trading pair symbol")
-
-
-class OrderbookSubscriptionParams(BaseModel):
-    """Parameters for orderbook subscription."""
-    instrument_id: str = Field(..., description="Instrument ID")
-
-
-class TradeSubscriptionParams(BaseModel):
-    """Parameters for trade subscription."""
-    instrument_id: str = Field(..., description="Instrument ID")
-
-
-class ChartSubscriptionParams(BaseModel):
-    """Parameters for chart subscription."""
-    symbol: str = Field(..., description="Trading pair symbol")
-    chart_type: SupportedChartTypes = Field(..., description="Chart type")
-    resolution: SupportedChartResolutions = Field(..., description="Chart resolution")
-
-
-class AccountOrderUpdatesParams(BaseModel):
-    """Parameters for account order updates subscription."""
-    address: str = Field(..., description="User address")
-    
-    @field_validator('address', mode='before')
-    @classmethod
-    def validate_address(cls, v: str) -> str:
-        """Validate and checksum the user address."""
-        return validate_ethereum_address(v)
-
-
-class AccountBalanceUpdatesParams(BaseModel):
-    """Parameters for account balance updates subscription."""
-    address: str = Field(..., description="User address")
-    
-    @field_validator('address', mode='before')
-    @classmethod
-    def validate_address(cls, v: str) -> str:
-        """Validate and checksum the user address."""
-        return validate_ethereum_address(v)
-
-
-class PositionsSubscriptionParams(BaseModel):
-    """Parameters for positions subscription."""
-    address: str = Field(..., description="User address")
-    
-    @field_validator('address', mode='before')
-    @classmethod
-    def validate_address(cls, v: str) -> str:
-        """Validate and checksum the user address."""
-        return validate_ethereum_address(v)
-
-
-class FillsSubscriptionParams(BaseModel):
-    """Parameters for fills subscription."""
-    address: str = Field(..., description="User address")
-    
-    @field_validator('address', mode='before')
-    @classmethod
-    def validate_address(cls, v: str) -> str:
-        """Validate and checksum the user address."""
-        return validate_ethereum_address(v)
-
-
-class AccountSummarySubscriptionParams(BaseModel):
-    """Parameters for account summary subscription."""
-    user: str = Field(..., description="User address")
-    
-    @field_validator('user', mode='before')
-    @classmethod
-    def validate_user_address(cls, v: str) -> str:
-        """Validate and checksum the user address."""
-        return validate_ethereum_address(v)
-
-
-class BlocksSubscriptionParams(BaseModel):
-    """Parameters for blocks subscription."""
-    pass
-
-
-class TransactionsSubscriptionParams(BaseModel):
-    """Parameters for transactions subscription."""
-    pass
-
-
-# Orderbook subscription
-class OrderbookItem(BaseModel):
-    """Orderbook item."""
-    price: float
-    size: float
-    amount: Optional[float] = None  # Alternative field name
-
-
-class Orderbook(BaseModel):
-    """Orderbook subscription data."""
-    instrument_id: str
-    instrument_name: Optional[str] = None  # Alternative field name
-    asks: List[OrderbookItem]
-    bids: List[OrderbookItem]
-    timestamp: int
-
-
-# Trade subscription
-class Trade(BaseModel):
-    """Trade subscription data."""
-    id: str
-    instrument: str
-    instrument_name: Optional[str] = None
-    maker: str
-    taker: str
-    price: float
-    size: float
-    timestamp: int
-    side: Literal["buy", "sell"]
-
-
-# Order update subscription
-class OrderUpdate(BaseModel):
-    """Order update subscription data."""
-    id: str
-    account: str
-    instrument: str
-    price: float
-    size: float
-    side: Literal["buy", "sell"]
-    status: str
-    timestamp: int
-
-
-# Account balance update subscription
-class BalanceItem(BaseModel):
-    """Balance item."""
-    asset: str
-    total: float
-    available: float
-    locked: float
-
-
-class AccountBalanceUpdate(BaseModel):
-    """Account balance update subscription data."""
-    account: str
-    balances: List[BalanceItem]
-    timestamp: int
-
-
-# Chart update subscription
-class ChartUpdate(BaseModel):
-    """Chart update subscription data."""
-    open: float
-    high: float
-    low: float
-    close: float
-    volume: float
-    time: int  # in milliseconds
+"""Global subscription method types.
+
+DEPRECATED: This module is deprecated. Import from hotstuff.methods.subscription.channels instead.
+This module exists for backward compatibility only.
+"""
+# Re-export everything from channels.py for backward compatibility
+from hotstuff.methods.subscription.channels import (
+    SupportedChartResolutions,
+    SupportedChartTypes,
+    TickerSubscriptionParams,
+    MidsSubscriptionParams,
+    BBOSubscriptionParams,
+    OrderbookSubscriptionParams,
+    TradeSubscriptionParams,
+    ChartSubscriptionParams,
+    AccountOrderUpdatesParams,
+    AccountBalanceUpdatesParams,
+    PositionsSubscriptionParams,
+    FillsSubscriptionParams,
+    AccountSummarySubscriptionParams,
+    BlocksSubscriptionParams,
+    TransactionsSubscriptionParams,
+    OrderbookItem,
+    Orderbook,
+    Trade,
+    OrderUpdate,
+    BalanceItem,
+    AccountBalanceUpdate,
+    ChartUpdate,
+)
+
+__all__ = [
+    "SupportedChartResolutions",
+    "SupportedChartTypes",
+    "TickerSubscriptionParams",
+    "MidsSubscriptionParams",
+    "BBOSubscriptionParams",
+    "OrderbookSubscriptionParams",
+    "TradeSubscriptionParams",
+    "ChartSubscriptionParams",
+    "AccountOrderUpdatesParams",
+    "AccountBalanceUpdatesParams",
+    "PositionsSubscriptionParams",
+    "FillsSubscriptionParams",
+    "AccountSummarySubscriptionParams",
+    "BlocksSubscriptionParams",
+    "TransactionsSubscriptionParams",
+    "OrderbookItem",
+    "Orderbook",
+    "Trade",
+    "OrderUpdate",
+    "BalanceItem",
+    "AccountBalanceUpdate",
+    "ChartUpdate",
+]

hotstuff/transports/http.py

@@ -2,9 +2,17 @@
 import json
 from typing import Optional, Any, Dict, Callable, Awaitable
 import aiohttp
+import asyncio
 
 from hotstuff.types import HttpTransportOptions
 from hotstuff.utils import ENDPOINTS_URLS
+from hotstuff.exceptions import (
+    HotstuffAPIError,
+    HotstuffConnectionError,
+    HotstuffTimeoutError,
+    HotstuffRateLimitError,
+    HotstuffAuthenticationError,
+)
 
 
 class HttpTransport:
@@ -74,7 +82,10 @@ class HttpTransport:
             The response data
             
         Raises:
-            Exception: If the request fails
+            HotstuffAPIError: If the API returns an error
+            HotstuffConnectionError: If connection fails
+            HotstuffTimeoutError: If request times out
+            HotstuffRateLimitError: If rate limit is exceeded
         """
         try:
             # Determine the base URL
@@ -102,30 +113,49 @@ class HttpTransport:
             
             # Make request
             async with session.request(method, url, **kwargs) as response:
+                # Handle rate limiting
+                if response.status == 429:
+                    retry_after = response.headers.get("Retry-After")
+                    raise HotstuffRateLimitError(
+                        "Rate limit exceeded",
+                        retry_after=int(retry_after) if retry_after else None
+                    )
+                
+                # Handle authentication errors
+                if response.status in (401, 403):
+                    text = await response.text()
+                    raise HotstuffAuthenticationError(text or "Authentication failed", status_code=response.status)
+                
                 # Check if response is OK
                 if not response.ok:
                     text = await response.text()
-                    raise Exception(text or f"HTTP {response.status}")
+                    raise HotstuffAPIError(text or f"HTTP {response.status}", status_code=response.status)
                 
                 # Check content type
                 content_type = response.headers.get("Content-Type", "")
                 if "application/json" not in content_type:
                     text = await response.text()
-                    raise Exception(text)
+                    raise HotstuffAPIError(f"Unexpected content type: {text}")
                 
                 # Parse response
                 body = await response.json()
                 
                 # Check for error in response
                 if isinstance(body, dict) and body.get("type") == "error":
-                    raise Exception(body.get("message", "Unknown error"))
+                    raise HotstuffAPIError(body.get("message", "Unknown error"))
                 
                 return body
         
+        except asyncio.TimeoutError:
+            raise HotstuffTimeoutError(f"Request to {endpoint} timed out")
+        except aiohttp.ClientConnectorError as e:
+            raise HotstuffConnectionError(f"Failed to connect to {url}: {str(e)}")
         except aiohttp.ClientError as e:
-            raise Exception(f"HTTP request failed: {str(e)}")
+            raise HotstuffConnectionError(f"HTTP request failed: {str(e)}")
+        except (HotstuffAPIError, HotstuffConnectionError, HotstuffTimeoutError, HotstuffRateLimitError):
+            raise
         except Exception as e:
-            raise e
+            raise HotstuffAPIError(str(e))
     
     async def close(self):
         """Close the HTTP session."""

hotstuff/utils/__init__.py

@@ -1,13 +1,16 @@
 """Utilities package."""
 from hotstuff.utils.endpoints import ENDPOINTS_URLS
 from hotstuff.utils.nonce import NonceManager
-from hotstuff.utils.signing import sign_action
+from hotstuff.utils.signing import sign_action, canonicalize_for_signing
+from hotstuff.utils.address import validate_ethereum_address
 from hotstuff.methods.exchange.op_codes import EXCHANGE_OP_CODES
 
 __all__ = [
     "ENDPOINTS_URLS",
     "NonceManager",
     "sign_action",
+    "canonicalize_for_signing",
+    "validate_ethereum_address",
     "EXCHANGE_OP_CODES",
 ]
 

hotstuff/utils/signing.py

@@ -1,12 +1,33 @@
 """Signing utilities for EIP-712 typed data."""
 import msgpack
 from eth_account import Account
-from eth_account.messages import encode_structured_data
 from eth_utils import keccak
 from hotstuff.methods.exchange.op_codes import EXCHANGE_OP_CODES
 
+# Check which API to use for encoding typed data
+try:
+    from eth_account.messages import encode_typed_data
+    _USE_NEW_API = True
+except ImportError:
+    from eth_account.messages import encode_structured_data
+    _USE_NEW_API = False
 
-async def sign_action(
+
+def canonicalize_for_signing(obj):
+    """
+    Return a copy of obj with all dict keys sorted alphabetically, recursively.
+    Use this before signing and in the request body so msgpack bytes are
+    deterministic and match backend verification (fixes "invalid order signer"
+    for cancelByOid / cancelByCloid when key order differs from backend).
+    """
+    if isinstance(obj, dict):
+        return {k: canonicalize_for_signing(v) for k, v in sorted(obj.items())}
+    if isinstance(obj, list):
+        return [canonicalize_for_signing(item) for item in obj]
+    return obj
+
+
+def sign_action(
     wallet: Account,
     action: dict,
     tx_type: int,
@@ -15,6 +36,9 @@ async def sign_action(
     """
     Sign an action using EIP-712.
     
+    This is a synchronous function that generates an EIP-712 signature
+    for the given action data.
+    
     Args:
         wallet: The account to sign with
         action: The action data
@@ -22,10 +46,12 @@ async def sign_action(
         is_testnet: Whether this is for testnet
         
     Returns:
-        str: The signature
+        str: The signature (hex string)
     """
+    # Canonicalize key order so msgpack bytes match backend (deterministic signing)
+    canonical_action = canonicalize_for_signing(action)
     # Encode action to msgpack
-    action_bytes = msgpack.packb(action)
+    action_bytes = msgpack.packb(canonical_action)
     
     # Hash the payload
     payload_hash = keccak(action_bytes)
@@ -38,14 +64,8 @@ async def sign_action(
         "verifyingContract": "0x1234567890123456789012345678901234567890",
     }
     
-    # EIP-712 types
-    types = {
-        "EIP712Domain": [
-            {"name": "name", "type": "string"},
-            {"name": "version", "type": "string"},
-            {"name": "chainId", "type": "uint256"},
-            {"name": "verifyingContract", "type": "address"},
-        ],
+    # EIP-712 message types (without EIP712Domain for new API)
+    message_types = {
         "Action": [
             {"name": "source", "type": "string"},
             {"name": "hash", "type": "bytes32"},
@@ -53,23 +73,40 @@ async def sign_action(
         ],
     }
     
-    # Message
+    # Message data
     message = {
         "source": "Testnet" if is_testnet else "Mainnet",
         "hash": payload_hash,
         "txType": tx_type,
     }
     
-    # Create structured data
-    structured_data = {
-        "types": types,
-        "primaryType": "Action",
-        "domain": domain,
-        "message": message,
-    }
+    if _USE_NEW_API:
+        # New API (eth-account >= 0.9): use 3-argument form
+        encoded_data = encode_typed_data(
+            domain_data=domain,
+            message_types=message_types,
+            message_data=message,
+        )
+    else:
+        # Legacy API (eth-account < 0.9): use full_message form
+        # Include EIP712Domain in types for legacy API
+        types_with_domain = {
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"},
+            ],
+            **message_types,
+        }
+        structured_data = {
+            "types": types_with_domain,
+            "primaryType": "Action",
+            "domain": domain,
+            "message": message,
+        }
+        encoded_data = encode_structured_data(structured_data)
     
-    # Encode and sign
-    encoded_data = encode_structured_data(structured_data)
     signed_message = wallet.sign_message(encoded_data)
     
     return signed_message.signature.hex()