hotstuff-python-sdk 0.0.1b1__py3-none-any.whl → 0.0.1b3__py3-none-any.whl

hotstuff/__init__.py

@@ -1,19 +1,41 @@
 """Hotstuff Python SDK.
 
-A Python SDK for interacting with Hotstuff Labs decentralized exchange.
+A Python SDK for interacting with Hotstuff L1.
 """
 
-__version__ = "0.0.1-beta.1"
+__version__ = "0.0.1-beta.3"
 
+# Transports
 from hotstuff.transports import HttpTransport, WebSocketTransport
+
+# Clients
 from hotstuff.apis import InfoClient, ExchangeClient, SubscriptionClient
+
+# Transport Types
 from hotstuff.types import (
     HttpTransportOptions,
     WebSocketTransportOptions,
 )
+
+# Utils
 from hotstuff.utils import NonceManager, sign_action, EXCHANGE_OP_CODES
 
-# Export method types for convenience
+# Exceptions
+from hotstuff.exceptions import (
+    HotstuffError,
+    HotstuffAPIError,
+    HotstuffConnectionError,
+    HotstuffTimeoutError,
+    HotstuffAuthenticationError,
+    HotstuffValidationError,
+    HotstuffInsufficientFundsError,
+    HotstuffOrderError,
+    HotstuffRateLimitError,
+    HotstuffWebSocketError,
+    HotstuffSubscriptionError,
+)
+
+# Exchange Method Types (for convenience)
 from hotstuff.methods.exchange.trading import (
     UnitOrder,
     BrokerConfig,
@@ -24,6 +46,27 @@ from hotstuff.methods.exchange.trading import (
 )
 from hotstuff.methods.exchange.account import AddAgentParams
 
+# Market data types (clean imports without 'global' keyword)
+from hotstuff.methods.info.market import (
+    TickerParams,
+    Ticker,
+    OrderbookParams,
+    OrderbookResponse,
+    InstrumentsParams,
+    InstrumentsResponse,
+    TradesParams,
+    Trade,
+    OracleParams,
+    OracleResponse,
+)
+
+# Subscription types (clean imports)
+from hotstuff.methods.subscription.channels import (
+    TickerSubscriptionParams,
+    TradeSubscriptionParams,
+    OrderbookSubscriptionParams,
+)
+
 __all__ = [
     # Version
     "__version__",
@@ -37,7 +80,19 @@ __all__ = [
     # Transport Types
     "HttpTransportOptions",
     "WebSocketTransportOptions",
-    # Exchange Method Types (for backward compatibility)
+    # Exceptions
+    "HotstuffError",
+    "HotstuffAPIError",
+    "HotstuffConnectionError",
+    "HotstuffTimeoutError",
+    "HotstuffAuthenticationError",
+    "HotstuffValidationError",
+    "HotstuffInsufficientFundsError",
+    "HotstuffOrderError",
+    "HotstuffRateLimitError",
+    "HotstuffWebSocketError",
+    "HotstuffSubscriptionError",
+    # Exchange Method Types
     "UnitOrder",
     "BrokerConfig",
     "PlaceOrderParams",
@@ -45,6 +100,21 @@ __all__ = [
     "CancelByCloidParams",
     "CancelAllParams",
     "AddAgentParams",
+    # Market Data Types
+    "TickerParams",
+    "Ticker",
+    "OrderbookParams",
+    "OrderbookResponse",
+    "InstrumentsParams",
+    "InstrumentsResponse",
+    "TradesParams",
+    "Trade",
+    "OracleParams",
+    "OracleResponse",
+    # Subscription Types
+    "TickerSubscriptionParams",
+    "TradeSubscriptionParams",
+    "OrderbookSubscriptionParams",
     # Utils
     "NonceManager",
     "sign_action",

hotstuff/apis/exchange.py

@@ -38,7 +38,6 @@ class ExchangeClient:
     async def add_agent(
         self,
         params: AM.AddAgentParams,
-        execute: bool = True,
         signal: Optional[Any] = None
     ) -> Dict[str, Any]:
         """
@@ -46,7 +45,6 @@ class ExchangeClient:
         
         Args:
             params: Agent parameters
-            execute: Whether to execute the action
             signal: Optional abort signal
             
         Returns:
@@ -58,7 +56,7 @@ class ExchangeClient:
         agent_account = Account.from_key(params.agent_private_key)
         
         # Sign with agent account
-        agent_signature = await sign_action(
+        agent_signature = sign_action(
             wallet=agent_account,
             action={
                 "signer": params.signer,
@@ -80,8 +78,7 @@ class ExchangeClient:
         
         return await self._execute_action(
             {"action": "addAgent", "params": params_dict},
-            signal,
-            execute
+            signal
         )
 
     async def revoke_agent(
@@ -484,11 +481,11 @@ class ExchangeClient:
             params["nonce"] = await self.nonce()
         
         # Sign the action
-        signature = await sign_action(
+        signature = sign_action(
             wallet=self.wallet,
             action=params,
             tx_type=EXCHANGE_OP_CODES[action],
-            is_testnet=True,
+            is_testnet=self.transport.is_testnet,
         )
         
         if execute:

hotstuff/apis/info.py

@@ -1,11 +1,10 @@
 """Info API client."""
 from typing import Optional, Any, List
-import importlib
 
-GM = importlib.import_module("hotstuff.methods.info.global")
-AM = importlib.import_module("hotstuff.methods.info.account")
-VM = importlib.import_module("hotstuff.methods.info.vault")
-EM = importlib.import_module("hotstuff.methods.info.explorer")
+from hotstuff.methods.info import market as GM
+from hotstuff.methods.info import account as AM
+from hotstuff.methods.info import vault as VM
+from hotstuff.methods.info import explorer as EM
 
 
 class InfoClient:
@@ -110,11 +109,12 @@ class InfoClient:
     
     async def positions(
         self, params: AM.PositionsParams, signal: Optional[Any] = None
-    ) -> AM.PositionsResponse:
+    ) -> Any:
         """Get current positions."""
         request = {"method": "positions", "params": params.model_dump()}
         response = await self.transport.request("info", request, signal)
-        return AM.PositionsResponse.model_validate(response)
+        # Returns a list of positions
+        return response
     
     async def account_summary(
         self, params: AM.AccountSummaryParams, signal: Optional[Any] = None

hotstuff/apis/subscription.py

@@ -1,8 +1,7 @@
 """Subscription API client for real-time data."""
 from typing import Callable, Dict, Any
-import importlib
 
-SM = importlib.import_module("hotstuff.methods.subscription.global")
+from hotstuff.methods.subscription import channels as SM
 
 
 class SubscriptionClient:
@@ -153,16 +152,13 @@ class SubscriptionClient:
         Subscribe to order updates.
         
         Args:
-            params: Subscription parameters (address)
+            params: Subscription parameters (user address)
             listener: Callback function for updates
             
         Returns:
             Subscription object with unsubscribe method
         """
-        # Convert to format expected by API (both address and user)
-        params_dict = params.model_dump()
-        params_dict["user"] = params_dict["address"]
-        return await self.transport.subscribe("accountOrderUpdates", params_dict, listener)
+        return await self.transport.subscribe("accountOrderUpdates", params.model_dump(), listener)
     
     async def account_balance_updates(
         self,
@@ -173,16 +169,13 @@ class SubscriptionClient:
         Subscribe to balance updates.
         
         Args:
-            params: Subscription parameters (address)
+            params: Subscription parameters (user address)
             listener: Callback function for updates
             
         Returns:
             Subscription object with unsubscribe method
         """
-        # Convert to format expected by API (both address and user)
-        params_dict = params.model_dump()
-        params_dict["user"] = params_dict["address"]
-        return await self.transport.subscribe("accountBalanceUpdates", params_dict, listener)
+        return await self.transport.subscribe("accountBalanceUpdates", params.model_dump(), listener)
     
     async def positions(
         self,
@@ -193,16 +186,13 @@ class SubscriptionClient:
         Subscribe to position updates.
         
         Args:
-            params: Subscription parameters (address)
+            params: Subscription parameters (user address)
             listener: Callback function for updates
             
         Returns:
             Subscription object with unsubscribe method
         """
-        # Convert to format expected by API (both address and user)
-        params_dict = params.model_dump()
-        params_dict["user"] = params_dict["address"]
-        return await self.transport.subscribe("positions", params_dict, listener)
+        return await self.transport.subscribe("positions", params.model_dump(), listener)
     
     async def fills(
         self,
@@ -213,16 +203,13 @@ class SubscriptionClient:
         Subscribe to fills.
         
         Args:
-            params: Subscription parameters (address)
+            params: Subscription parameters (user address)
             listener: Callback function for updates
             
         Returns:
             Subscription object with unsubscribe method
         """
-        # Convert to format expected by API (both address and user)
-        params_dict = params.model_dump()
-        params_dict["user"] = params_dict["address"]
-        return await self.transport.subscribe("fills", params_dict, listener)
+        return await self.transport.subscribe("fills", params.model_dump(), listener)
     
     async def account_summary(
         self,

hotstuff/exceptions.py

@@ -0,0 +1,72 @@
+"""Custom exceptions for the Hotstuff SDK."""
+
+
+class HotstuffError(Exception):
+    """Base exception for all Hotstuff SDK errors."""
+    pass
+
+
+class HotstuffAPIError(HotstuffError):
+    """Error returned from the Hotstuff API."""
+    
+    def __init__(self, message: str, status_code: int = None, error_code: str = None):
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        super().__init__(self.message)
+    
+    def __str__(self):
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"(HTTP {self.status_code})")
+        if self.error_code:
+            parts.append(f"[{self.error_code}]")
+        return " ".join(parts)
+
+
+class HotstuffConnectionError(HotstuffError):
+    """Error connecting to the Hotstuff API."""
+    pass
+
+
+class HotstuffTimeoutError(HotstuffError):
+    """Request to the Hotstuff API timed out."""
+    pass
+
+
+class HotstuffAuthenticationError(HotstuffAPIError):
+    """Authentication error (invalid signature, expired, etc.)."""
+    pass
+
+
+class HotstuffValidationError(HotstuffError):
+    """Error validating request parameters."""
+    pass
+
+
+class HotstuffInsufficientFundsError(HotstuffAPIError):
+    """Insufficient funds for the requested operation."""
+    pass
+
+
+class HotstuffOrderError(HotstuffAPIError):
+    """Error related to order placement or management."""
+    pass
+
+
+class HotstuffRateLimitError(HotstuffAPIError):
+    """Rate limit exceeded."""
+    
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: int = None):
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after
+
+
+class HotstuffWebSocketError(HotstuffError):
+    """WebSocket-related error."""
+    pass
+
+
+class HotstuffSubscriptionError(HotstuffWebSocketError):
+    """Error subscribing to a channel."""
+    pass

hotstuff/methods/exchange/account.py

@@ -1,30 +1,8 @@
 """Account exchange method types."""
 from typing import Optional
 from pydantic import BaseModel, Field, ConfigDict, 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 checksummed address (EIP-55)
-    return to_checksum_address(value)
+from hotstuff.utils.address import validate_ethereum_address
 
 
 # Add Agent Method

hotstuff/methods/exchange/collateral.py

@@ -1,30 +1,8 @@
 """Collateral exchange method types."""
 from typing import Optional
 from pydantic import BaseModel, Field, ConfigDict, 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 checksummed address (EIP-55)
-    return to_checksum_address(value)
+
+from hotstuff.utils.address import validate_ethereum_address
 
 
 # Account Spot Withdraw Request Method

hotstuff/methods/exchange/trading.py

@@ -1,30 +1,40 @@
 """Trading exchange method types."""
+import re
 from typing import List, Literal, Optional, Any
 from pydantic import BaseModel, Field, ConfigDict, field_validator, field_serializer
-from eth_utils import is_address, to_checksum_address
 
+from hotstuff.utils.address import validate_ethereum_address
 
-def validate_ethereum_address(value: str) -> str:
+
+# Regex pattern for valid cloid: 0x followed by exactly 32 hex digits (128-bit)
+CLOID_PATTERN = re.compile(r'^0x[0-9a-fA-F]{32}$')
+
+
+def validate_cloid(value: Optional[str]) -> Optional[str]:
     """
-    Validate and normalize an Ethereum address.
+    Validate client order ID format.
     
     Args:
-        value: The address string to validate
+        value: The cloid string to validate
         
     Returns:
-        Checksummed address string
+        The validated cloid string (lowercase hex)
         
     Raises:
-        ValueError: If the address is invalid
+        ValueError: If the cloid format is invalid
     """
-    if not isinstance(value, str):
-        raise ValueError(f"Address must be a string, got {type(value)}")
+    if value is None or value == "":
+        return None
     
-    if not is_address(value):
-        raise ValueError(f"Invalid Ethereum address: {value}")
+    if not CLOID_PATTERN.match(value):
+        raise ValueError(
+            f"Invalid cloid format: '{value}'. "
+            "ClOrdID must be 0x followed by 32 hex digits (128-bit). "
+            "Example: 0x1234567890abcdef1234567890abcdef"
+        )
     
-    # Return checksummed address (EIP-55)
-    return to_checksum_address(value)
+    # Return lowercase for consistency
+    return value.lower()
 
 
 # Place Order Method
@@ -38,7 +48,10 @@ class UnitOrder(BaseModel):
     tif: Literal["GTC", "IOC", "FOK"] = Field(..., description="Time in force")
     ro: bool = Field(..., description="Reduce-only flag")
     po: bool = Field(..., description="Post-only flag")
-    cloid: str = Field(..., description="Client order ID")
+    cloid: Optional[str] = Field(
+        None, 
+        description="Client order ID (optional). Format: 0x + 32 hex digits (128-bit). Example: 0x1234567890abcdef1234567890abcdef"
+    )
     trigger_px: Optional[str] = Field(None, alias="triggerPx", description="Trigger price")
     is_market: Optional[bool] = Field(None, alias="isMarket", description="Market order flag")
     tpsl: Optional[Literal["tp", "sl", ""]] = Field(None, description="Take profit/stop loss")
@@ -46,9 +59,15 @@ class UnitOrder(BaseModel):
 
     model_config = ConfigDict(populate_by_name=True)
     
-    @field_serializer('trigger_px', 'tpsl', 'grouping')
+    @field_validator('cloid', mode='before')
+    @classmethod
+    def validate_cloid_format(cls, v: Optional[str]) -> Optional[str]:
+        """Validate cloid format: 0x + 32 hex digits."""
+        return validate_cloid(v)
+    
+    @field_serializer('cloid', 'trigger_px', 'tpsl', 'grouping')
     def serialize_optional_strings(self, value: Optional[str], _info) -> str:
-        """Convert None to empty string for optional string fields to match original SDK."""
+        """Convert None to empty string for optional string fields to match API expectations."""
         return "" if value is None else value
 
 
@@ -95,8 +114,20 @@ class CancelByOidParams(BaseModel):
 # Cancel By Cloid Method
 class UnitCancelByClOrderId(BaseModel):
     """Cancel by client order ID unit."""
-    cloid: str = Field(..., description="Client order ID")
+    cloid: str = Field(
+        ..., 
+        description="Client order ID. Format: 0x + 32 hex digits (128-bit). Example: 0x1234567890abcdef1234567890abcdef"
+    )
     instrument_id: int = Field(..., gt=0, description="Instrument ID")
+    
+    @field_validator('cloid', mode='before')
+    @classmethod
+    def validate_cloid_format(cls, v: str) -> str:
+        """Validate cloid format: 0x + 32 hex digits."""
+        result = validate_cloid(v)
+        if result is None:
+            raise ValueError("cloid is required for cancel by cloid")
+        return result
 
 
 class CancelByCloidParams(BaseModel):

hotstuff/methods/exchange/vault.py

@@ -1,30 +1,8 @@
 """Vault exchange method types."""
 from typing import Optional
 from pydantic import BaseModel, Field, ConfigDict, 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 checksummed address (EIP-55)
-    return to_checksum_address(value)
+
+from hotstuff.utils.address import validate_ethereum_address
 
 
 # Deposit To Vault Method