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

hotstuff/methods/info/account.py

@@ -0,0 +1,371 @@
+"""Account info method types."""
+from typing import List, Literal, Optional, Annotated
+from pydantic import BaseModel, Field, ConfigDict, field_validator, RootModel
+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)
+
+
+# Type alias for validated Ethereum addresses (similar to viem's Address type)
+EthereumAddress = Annotated[
+    str,
+    Field(
+        ...,
+        description="Ethereum address (validated and checksummed)",
+        examples=["0x1234567890123456789012345678901234567890"],
+    ),
+]
+
+
+# Open Orders Method
+class OpenOrdersParams(BaseModel):
+    """Parameters for open orders query."""
+    user: str = Field(..., description="User address")
+    page: Optional[int] = Field(None, description="Page number")
+    limit: Optional[int] = Field(None, description="Number of orders per page")
+    
+    @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 OpenOrder(BaseModel):
+    """Open order information."""
+    order_id: int
+    user: str
+    instrument_id: int
+    instrument: str
+    side: Literal["s", "b"]
+    limit_price: str
+    size: str
+    unfilled: str
+    state: Literal["open", "filled", "cancelled", "triggered"]
+    cloid: str
+    tif: Literal["GTC", "IOC", "FOK"]
+    tpsl: Literal["tp", "sl", ""]
+    trigger_px: str
+    trigger_price: Optional[str] = None
+    post_only: bool
+    reduce_only: bool
+    timestamp: str
+
+
+class OpenOrdersResponse(BaseModel):
+    """Open orders response."""
+    orders: List[OpenOrder] = Field(..., description="List of open orders")
+
+
+# Positions Method
+class PositionsParams(BaseModel):
+    """Parameters for positions query."""
+    user: str = Field(..., description="User address")
+    instrument: Optional[str] = Field(None, description="Filter by instrument")
+    
+    @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 PositionsResponse(BaseModel):
+    """Positions response."""
+    pass
+
+
+# Account Summary Method
+class AccountSummaryParams(BaseModel):
+    """Parameters for account summary query."""
+    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 AccountSummaryResponse(BaseModel):
+    """Account summary response."""
+    total_balance: str
+    total_equity: str
+    total_free: str
+    total_margin: str
+    total_profit_loss: str
+
+
+# Referral Summary Method
+class ReferralSummaryParams(BaseModel):
+    """Parameters for referral summary query."""
+    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 ReferralSummaryResponse(BaseModel):
+    """Referral summary response."""
+    pass 
+
+
+# User Fee Info Method
+class UserFeeInfoParams(BaseModel):
+    """Parameters for user fee info query."""
+    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 UserFeeInfoResponse(BaseModel):
+    """User fee info response."""
+    pass 
+
+
+# Account History Method
+class AccountHistoryParams(BaseModel):
+    """Parameters for account history query."""
+    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 AccountHistoryResponse(BaseModel):
+    """Account history response."""
+    pass 
+
+
+# Order History Method
+class OrderHistoryParams(BaseModel):
+    """Parameters for order history query."""
+    model_config = ConfigDict(populate_by_name=True)
+    
+    user: str = Field(..., description="User address")
+    instrument_id: Optional[str] = Field(None, alias="instrumentId", description="Filter by instrument ID")
+    limit: Optional[int] = Field(None, description="Number of orders to return")
+    
+    @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 OrderHistoryResponse(BaseModel):
+    """Order history response."""
+    pass 
+
+
+# Trade History Method
+class TradeHistoryParams(BaseModel):
+    """Parameters for trade history query."""
+    model_config = ConfigDict(populate_by_name=True)
+    
+    user: str = Field(..., description="User address")
+    instrument_id: Optional[str] = Field(None, alias="instrumentId", description="Filter by instrument ID")
+    limit: Optional[int] = Field(None, description="Number of trades to return")
+    
+    @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 TradeHistoryResponse(BaseModel):
+    """Trade history response."""
+    pass 
+
+
+# Funding History Method
+class FundingHistoryParams(BaseModel):
+    """Parameters for funding history query."""
+    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 FundingHistoryResponse(BaseModel):
+    """Funding history response."""
+    pass 
+
+
+# Transfer History Method
+class TransferHistoryParams(BaseModel):
+    """Parameters for transfer history query."""
+    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 TransferHistoryResponse(BaseModel):
+    """Transfer history response."""
+    pass 
+
+
+# Instrument Leverage Method
+class InstrumentLeverageParams(BaseModel):
+    """Parameters for instrument leverage query."""
+    user: str = Field(..., description="User address")
+    symbol: str = Field(..., description="Instrument symbol")
+    
+    @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 InstrumentLeverageResponse(BaseModel):
+    """Instrument leverage response."""
+    pass 
+
+
+# Referral Info Method
+class ReferralInfoParams(BaseModel):
+    """Parameters for referral info query."""
+    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 ReferralInfoResponse(BaseModel):
+    """Referral info response."""
+    pass 
+
+
+# Sub Accounts List Method
+class SubAccountsListParams(BaseModel):
+    """Parameters for sub accounts list query."""
+    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 SubAccountsListResponse(BaseModel):
+    """Sub accounts list response."""
+    pass 
+
+
+# Agents Method
+class AgentsParams(BaseModel):
+    """Parameters for agents query."""
+    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 Agent(BaseModel):
+    """Agent information."""
+    user: str = Field(..., description="User address")
+    agent_address: Optional[str] = Field(None, description="Agent address")
+    agent_name: Optional[str] = Field(None, description="Agent name")
+    created_at_block_timestamp: Optional[int] = Field(None, description="Creation timestamp")
+    valid_until_timestamp: Optional[int] = Field(None, description="Validity expiration timestamp")
+    
+    model_config = ConfigDict(populate_by_name=True)
+    
+    @field_validator('user', 'agent_address', mode='before')
+    @classmethod
+    def validate_addresses(cls, v: Optional[str]) -> Optional[str]:
+        """Validate and checksum Ethereum addresses."""
+        if v is None or v == "":
+            return v
+        return validate_ethereum_address(v)
+
+
+class AgentsResponse(BaseModel):
+    """Agents response."""
+    pass
+
+
+# User Balance Info Method
+class UserBalanceInfoParams(BaseModel):
+    """Parameters for user balance info query."""
+    user: str = Field(..., description="User address")
+    type: Literal["all", "spot", "derivative"] = Field(..., description="Balance type")
+    
+    @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 UserBalanceInfoResponse(BaseModel):
+    """User balance info response."""
+    pass 
+
+
+# Account Info Method
+class AccountInfoParams(BaseModel):
+    """Parameters for account info query."""
+    model_config = ConfigDict(populate_by_name=True)
+    
+    user: str = Field(..., description="User address")
+    collateral_id: Optional[int] = Field(None, alias="collateralID", description="Collateral ID")
+    include_history: Optional[bool] = Field(None, alias="includeHistory", description="Include history")
+    
+    @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 AccountInfoResponse(BaseModel):
+    """Account info response."""
+    pass 

hotstuff/methods/info/explorer.py

@@ -0,0 +1,57 @@
+"""Explorer info method types."""
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+# Blocks Method
+class BlocksParams(BaseModel):
+    """Parameters for blocks query."""
+    offset: int = Field(..., description="Offset for pagination")
+    limit: int = Field(..., description="Number of blocks to return")
+
+
+class BlocksResponse(BaseModel):
+    """Blocks response."""
+    pass 
+
+
+# Block Details Method
+class BlockDetailsParams(BaseModel):
+    """Parameters for block details query."""
+    block_hash: Optional[str] = Field(None, description="Block hash")
+    block_height: Optional[int] = Field(None, description="Block height")
+
+
+class BlockDetailsResponse(BaseModel):
+    """Block details response."""
+    pass 
+
+
+# Transactions Method
+class TransactionFilter(BaseModel):
+    """Transaction filter."""
+    account: Optional[str] = Field(None, description="Filter by account")
+    tx_type: Optional[int] = Field(None, description="Filter by transaction type")
+
+
+class TransactionsParams(BaseModel):
+    """Parameters for transactions query."""
+    offset: Optional[int] = Field(None, description="Offset for pagination")
+    limit: Optional[int] = Field(None, description="Number of transactions to return")
+    filter: Optional[TransactionFilter] = Field(None, description="Transaction filter")
+
+
+class TransactionsResponse(BaseModel):
+    """Transactions response."""
+    pass 
+
+
+# Transaction Details Method
+class TransactionDetailsParams(BaseModel):
+    """Parameters for transaction details query."""
+    tx_hash: str = Field(..., description="Transaction hash")
+
+
+class TransactionDetailsResponse(BaseModel):
+    """Transaction details response."""
+    pass 

hotstuff/methods/info/global.py

@@ -0,0 +1,249 @@
+"""Global info method types."""
+from typing import List, Literal, Optional, Union
+from pydantic import BaseModel, Field, ConfigDict, field_validator
+
+
+# Oracle Method
+class OracleParams(BaseModel):
+    """Parameters for oracle price query."""
+    symbol: str = Field(..., description="Symbol to get oracle price for")
+
+
+class OracleResponse(BaseModel):
+    """Oracle price response."""
+    symbol: str
+    index_price: str
+    ext_mark_price: str
+    updated_at: int
+
+
+# Supported Collateral Method
+class SupportedCollateralParams(BaseModel):
+    """Parameters for supported collateral query."""
+    pass
+
+
+class BridgeByChain(BaseModel):
+    """Bridge chain configuration."""
+    bridge_chain_type: int
+    bridge_chain_id: int
+    token_address: str
+    bridge_contract_address: str
+    enabled: bool
+
+
+class WeightTier(BaseModel):
+    """Weight tier configuration."""
+    amount: int
+    weight: int
+
+
+class CollRisk(BaseModel):
+    """Collateral risk configuration."""
+    weight_tiers: List[WeightTier]
+    max_margin_cap: int
+    stale_price_guard_weight: int
+
+
+class SupportedCollateral(BaseModel):
+    """Supported collateral information."""
+    id: int
+    symbol: str
+    name: str
+    decimals: int
+    default_coll_weight: int
+    price_index: str
+    type: int
+    bridge_by_chain: List[BridgeByChain]
+    coll_risk: List[CollRisk]
+    withdrawal_fee: int
+    added_at_block: int
+
+
+# Instruments Method
+class InstrumentsParams(BaseModel):
+    """Parameters for instruments query."""
+    type: Literal["perps", "spot", "all"] = Field(..., description="Instrument type filter")
+
+
+class MarginTier(BaseModel):
+    """Margin tier configuration."""
+    notional_usd_threshold: str
+    max_leverage: int
+    mmr: float  # Can be fractional
+    mmd: int
+
+
+class PerpInstrument(BaseModel):
+    """Perpetual instrument information."""
+    id: int
+    name: str
+    price_index: str
+    lot_size: float  # Can be fractional (e.g., 1e-05)
+    tick_size: float  # Can be fractional (e.g., 0.1, 1e-06)
+    settlement_currency: int
+    only_isolated: bool
+    max_leverage: int
+    delisted: bool
+    min_notional_usd: int
+    margin_tiers: List[MarginTier]
+    listed_at_block_timestamp: int
+
+
+class SpotInstrument(BaseModel):
+    """Spot instrument information."""
+    id: int
+    name: str
+    price_index: str
+    lot_size: int
+    tick_size: float  # Can be fractional (e.g., 0.0001)
+    base_asset: int
+    quote_asset: int
+    stable_pair: bool
+    min_size_in_quote_asset: int
+    listed_at_block_timestamp: int
+
+
+class InstrumentsResponse(BaseModel):
+    """Instruments response."""
+    perps: List[PerpInstrument]
+    spot: List[SpotInstrument]
+
+
+# Ticker Method
+class TickerParams(BaseModel):
+    """Parameters for ticker query."""
+    symbol: str = Field(..., description="Trading pair symbol")
+
+
+class Ticker(BaseModel):
+    """Ticker information."""
+    type: Literal["perp", "spot"]
+    symbol: str
+    mark_price: str
+    mid_price: str
+    index_price: str
+    best_bid_price: str
+    best_ask_price: str
+    best_bid_size: str
+    best_ask_size: str
+    funding_rate: str
+    open_interest: str
+    volume_24h: str
+    change_24h: str
+    max_trading_price: str
+    min_trading_price: str
+    last_updated: int
+    last_price: str
+
+
+# Orderbook Method
+class OrderbookParams(BaseModel):
+    """Parameters for orderbook query."""
+    symbol: str = Field(..., description="Trading pair symbol")
+    depth: Optional[int] = Field(None, description="Orderbook depth")
+
+
+class OrderbookLevel(BaseModel):
+    """Orderbook level (bid/ask)."""
+    price: str  # API may return int/float, but we store as string for precision
+    size: str   # API may return int/float, but we store as string for precision
+    
+    @field_validator('price', mode='before')
+    @classmethod
+    def convert_price_to_string(cls, v: Union[str, int, float]) -> str:
+        """Convert numeric price to string."""
+        if not isinstance(v, str):
+            return str(v)
+        return v
+    
+    @field_validator('size', mode='before')
+    @classmethod
+    def convert_size_to_string(cls, v: Union[str, int, float]) -> str:
+        """Convert numeric size to string."""
+        if not isinstance(v, str):
+            return str(v)
+        return v
+
+
+class OrderbookResponse(BaseModel):
+    """Orderbook response."""
+    bids: List[OrderbookLevel]
+    asks: List[OrderbookLevel]
+    instrument_name: str
+    timestamp: int
+    sequence_number: int
+
+
+# Trades Method
+class TradesParams(BaseModel):
+    """Parameters for trades query."""
+    symbol: str = Field(..., description="Trading pair symbol")
+    limit: Optional[int] = Field(None, description="Number of trades to return")
+
+
+class Trade(BaseModel):
+    """Trade information."""
+    instrument_id: int
+    instrument: str
+    trade_id: int
+    tx_hash: str
+    side: Literal["b", "s"]
+    price: str
+    size: str
+    maker: str
+    taker: str
+    timestamp: str
+
+
+# Mids Method
+class MidsParams(BaseModel):
+    """Parameters for mids query."""
+    pass
+
+
+class Mid(BaseModel):
+    """Mid price information."""
+    symbol: str
+    mid_price: str
+
+
+# BBO Method
+class BBOParams(BaseModel):
+    """Parameters for best bid/offer query."""
+    symbol: str = Field(..., description="Trading pair symbol")
+
+
+class BBO(BaseModel):
+    """Best bid/offer information."""
+    symbol: str
+    best_bid_price: str
+    best_ask_price: str
+    best_bid_size: str
+    best_ask_size: str
+
+
+# Chart Method
+SupportedChartResolutions = Literal["1", "5", "15", "60", "240", "1D", "1W"]
+SupportedChartTypes = Literal["mark", "ltp", "index"]
+
+
+class ChartParams(BaseModel):
+    """Parameters for chart data query."""
+    model_config = ConfigDict(populate_by_name=True)
+    
+    symbol: str = Field(..., description="Trading pair symbol")
+    resolution: SupportedChartResolutions = Field(..., description="Chart resolution")
+    from_: int = Field(..., alias="from", description="Start timestamp")
+    to: int = Field(..., description="End timestamp")
+    chart_type: SupportedChartTypes = Field(..., description="Chart type")
+
+
+class ChartPoint(BaseModel):
+    """Chart data point."""
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float
+    time: int