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

hotstuff/methods/exchange/account.py

@@ -0,0 +1,120 @@
+"""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)
+
+
+# Add Agent Method
+class AddAgentParams(BaseModel):
+    """Parameters for adding an agent."""
+    agent_name: str = Field(..., alias="agentName", description="Agent name")
+    agent: str = Field(..., description="Agent address")
+    for_account: str = Field(..., alias="forAccount", description="Account to add agent for")
+    signature: Optional[str] = Field(None, description="Agent signature")
+    valid_until: int = Field(..., alias="validUntil", description="Validity expiration timestamp")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+    agent_private_key: Optional[str] = Field(None, alias="agentPrivateKey", description="Agent private key")
+    signer: Optional[str] = Field(None, description="Signer address")
+
+    model_config = ConfigDict(populate_by_name=True)
+    
+    @field_validator('agent', 'signer', 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)
+
+
+# Revoke Agent Method
+class RevokeAgentParams(BaseModel):
+    """Parameters for revoking an agent."""
+    agent: str = Field(..., description="Agent address")
+    for_account: Optional[str] = Field(None, alias="forAccount", description="Account to revoke agent for")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @field_validator('agent', mode='before')
+    @classmethod
+    def validate_agent_address(cls, v: str) -> str:
+        """Validate and checksum the agent address."""
+        return validate_ethereum_address(v)
+
+
+# Update Perp Instrument Leverage Method
+class UpdatePerpInstrumentLeverageParams(BaseModel):
+    """Parameters for updating perp instrument leverage."""
+    instrument_id: int = Field(..., alias="instrumentId", description="Instrument ID")
+    leverage: int = Field(..., description="Leverage value")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Approve Broker Fee Method
+class ApproveBrokerFeeParams(BaseModel):
+    """Parameters for approving broker fee."""
+    broker: str = Field(..., description="Broker address")
+    max_fee_rate: str = Field(..., alias="maxFeeRate", description="Maximum fee rate")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @field_validator('broker', mode='before')
+    @classmethod
+    def validate_broker_address(cls, v: str) -> str:
+        """Validate and checksum the broker address."""
+        return validate_ethereum_address(v)
+
+
+# Create Referral Code Method
+class CreateReferralCodeParams(BaseModel):
+    """Parameters for creating a referral code."""
+    code: str = Field(..., description="Referral code")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Set Referrer Method
+class SetReferrerParams(BaseModel):
+    """Parameters for setting a referrer."""
+    code: str = Field(..., description="Referral code")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Claim Referral Rewards Method
+class ClaimReferralRewardsParams(BaseModel):
+    """Parameters for claiming referral rewards."""
+    collateral_id: int = Field(..., alias="collateralId", description="Collateral ID")
+    spot: bool = Field(..., description="Whether to claim from spot account")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)

hotstuff/methods/exchange/collateral.py

@@ -0,0 +1,94 @@
+"""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)
+
+
+# Account Spot Withdraw Request Method
+class AccountSpotWithdrawRequestParams(BaseModel):
+    """Parameters for account spot withdraw request."""
+    collateral_id: int = Field(..., alias="collateralId", description="Collateral ID")
+    amount: str = Field(..., description="Withdrawal amount")
+    chain_id: int = Field(..., alias="chainId", description="Chain ID")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Account Derivative Withdraw Request Method
+class AccountDerivativeWithdrawRequestParams(BaseModel):
+    """Parameters for account derivative withdraw request."""
+    collateral_id: int = Field(..., alias="collateralId", description="Collateral ID")
+    amount: str = Field(..., description="Withdrawal amount")
+    chain_id: int = Field(..., alias="chainId", description="Chain ID")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Account Spot Balance Transfer Request Method
+class AccountSpotBalanceTransferRequestParams(BaseModel):
+    """Parameters for account spot balance transfer request."""
+    collateral_id: int = Field(..., alias="collateralId", description="Collateral ID")
+    amount: str = Field(..., description="Transfer amount")
+    destination: str = Field(..., description="Destination address")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @field_validator('destination', mode='before')
+    @classmethod
+    def validate_destination_address(cls, v: str) -> str:
+        """Validate and checksum the destination address."""
+        return validate_ethereum_address(v)
+
+
+# Account Derivative Balance Transfer Request Method
+class AccountDerivativeBalanceTransferRequestParams(BaseModel):
+    """Parameters for account derivative balance transfer request."""
+    collateral_id: int = Field(..., alias="collateralId", description="Collateral ID")
+    amount: str = Field(..., description="Transfer amount")
+    destination: str = Field(..., description="Destination address")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @field_validator('destination', mode='before')
+    @classmethod
+    def validate_destination_address(cls, v: str) -> str:
+        """Validate and checksum the destination address."""
+        return validate_ethereum_address(v)
+
+
+# Account Internal Balance Transfer Request Method
+class AccountInternalBalanceTransferRequestParams(BaseModel):
+    """Parameters for account internal balance transfer request."""
+    collateral_id: int = Field(..., alias="collateralId", description="Collateral ID")
+    amount: str = Field(..., description="Transfer amount")
+    to_derivatives_account: bool = Field(..., alias="toDerivativesAccount", description="Transfer to derivatives account flag")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)

hotstuff/methods/exchange/op_codes.py

@@ -0,0 +1,28 @@
+"""Exchange operation codes."""
+EXCHANGE_OP_CODES = {
+    # Account Actions
+    "addAgent": 1201,
+    "revokeAgent": 1211,
+    "updatePerpInstrumentLeverage": 1203,
+    "approveBrokerFee": 1207,
+    "createReferralCode": 1208,
+    "setReferrer": 1209,
+    "claimReferralRewards": 1210,
+
+    # Trading Actions
+    "placeOrder": 1301,
+    "cancelByOid": 1302,
+    "cancelAll": 1311,
+    "cancelByCloid": 1312,
+
+    # Collateral Actions
+    "accountSpotWithdrawRequest": 1002,
+    "accountDerivativeWithdrawRequest": 1003,
+    "accountSpotBalanceTransferRequest": 1051,
+    "accountDerivativeBalanceTransferRequest": 1052,
+    "accountInternalBalanceTransferRequest": 1053,
+
+    # Vault Actions
+    "depositToVault": 1401,
+    "redeemFromVault": 1402,
+}

hotstuff/methods/exchange/trading.py

@@ -0,0 +1,117 @@
+"""Trading exchange method types."""
+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
+
+
+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)
+
+
+# Place Order Method
+class UnitOrder(BaseModel):
+    """Single order unit."""
+    instrument_id: int = Field(..., gt=0, alias="instrumentId", description="Instrument ID")
+    side: Literal["b", "s"] = Field(..., description="Order side: 'b' for buy, 's' for sell")
+    position_side: Literal["LONG", "SHORT", "BOTH"] = Field(..., alias="positionSide", description="Position side")
+    price: str = Field(..., description="Order price")
+    size: str = Field(..., description="Order size")
+    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")
+    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")
+    grouping: Optional[Literal["position", "normal", ""]] = Field(None, description="Order grouping")
+
+    model_config = ConfigDict(populate_by_name=True)
+    
+    @field_serializer('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."""
+        return "" if value is None else value
+
+
+class BrokerConfig(BaseModel):
+    """Broker configuration."""
+    broker: str = Field(..., description="Broker address")
+    fee: str = Field(..., description="Broker fee")
+    
+    @field_validator('broker', mode='before')
+    @classmethod
+    def validate_broker_address(cls, v: str) -> str:
+        """Validate and checksum the broker address."""
+        if v == "":
+            return v  # Allow empty string for no broker
+        return validate_ethereum_address(v)
+
+
+class PlaceOrderParams(BaseModel):
+    """Parameters for placing an order."""
+    orders: List[UnitOrder] = Field(..., description="List of orders to place")
+    expires_after: int = Field(..., alias="expiresAfter", description="Expiration timestamp")
+    broker_config: Optional[BrokerConfig] = Field(None, alias="brokerConfig", description="Broker configuration")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Cancel By Oid Method
+class UnitCancelByOrderId(BaseModel):
+    """Cancel by order ID unit."""
+    oid: int = Field(..., description="Order ID")
+    instrument_id: int = Field(..., gt=0, description="Instrument ID")
+
+
+class CancelByOidParams(BaseModel):
+    """Parameters for cancelling by order ID."""
+    cancels: List[UnitCancelByOrderId] = Field(..., description="List of orders to cancel")
+    expires_after: int = Field(..., alias="expiresAfter", description="Expiration timestamp")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Cancel By Cloid Method
+class UnitCancelByClOrderId(BaseModel):
+    """Cancel by client order ID unit."""
+    cloid: str = Field(..., description="Client order ID")
+    instrument_id: int = Field(..., gt=0, description="Instrument ID")
+
+
+class CancelByCloidParams(BaseModel):
+    """Parameters for cancelling by client order ID."""
+    cancels: List[UnitCancelByClOrderId] = Field(..., description="List of orders to cancel")
+    expires_after: int = Field(..., alias="expiresAfter", description="Expiration timestamp")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+# Cancel All Method
+class CancelAllParams(BaseModel):
+    """Parameters for cancelling all orders."""
+    expires_after: int = Field(..., alias="expiresAfter", description="Expiration timestamp")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)

hotstuff/methods/exchange/vault.py

@@ -0,0 +1,59 @@
+"""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)
+
+
+# Deposit To Vault Method
+class DepositToVaultParams(BaseModel):
+    """Parameters for depositing to a vault."""
+    vault_address: str = Field(..., alias="vaultAddress", description="Vault address")
+    amount: str = Field(..., description="Deposit amount")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @field_validator('vault_address', mode='before')
+    @classmethod
+    def validate_vault_address(cls, v: str) -> str:
+        """Validate and checksum the vault address."""
+        return validate_ethereum_address(v)
+
+
+# Redeem From Vault Method
+class RedeemFromVaultParams(BaseModel):
+    """Parameters for redeeming from a vault."""
+    vault_address: str = Field(..., alias="vaultAddress", description="Vault address")
+    shares: str = Field(..., description="Number of shares to redeem")
+    nonce: Optional[int] = Field(None, description="Transaction nonce")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @field_validator('vault_address', mode='before')
+    @classmethod
+    def validate_vault_address(cls, v: str) -> str:
+        """Validate and checksum the vault address."""
+        return validate_ethereum_address(v)

hotstuff/methods/info/__init__.py

@@ -0,0 +1,14 @@
+"""Info method types organized by category."""
+import importlib
+
+GlobalInfoMethods = importlib.import_module("hotstuff.methods.info.global")
+AccountInfoMethods = importlib.import_module("hotstuff.methods.info.account")
+VaultInfoMethods = importlib.import_module("hotstuff.methods.info.vault")
+ExplorerInfoMethods = importlib.import_module("hotstuff.methods.info.explorer")
+
+__all__ = [
+    "GlobalInfoMethods",
+    "AccountInfoMethods",
+    "VaultInfoMethods",
+    "ExplorerInfoMethods",
+]