htcli 1.1.0__py3-none-any.whl

src/htcli/models/responses/staking.py

@@ -0,0 +1,502 @@
+"""
+Staking response models for HTCLI.
+
+These models define the response structure for all staking operations
+on the Hypertensor blockchain.
+"""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+from scalecodec import ScaleBytes
+
+# ============================================================================
+# BASE RESPONSE MODELS
+# ============================================================================
+
+
+class BaseStakingResponse(BaseModel):
+    """Base response model for staking operations."""
+
+    success: bool = Field(..., description="Whether the operation was successful")
+    transaction_hash: Optional[str] = Field(None, description="Transaction hash")
+    block_hash: Optional[str] = Field(
+        None, description="Block hash where transaction was included"
+    )
+    block_number: Optional[int] = Field(
+        None, description="Block number where transaction was included"
+    )
+    message: Optional[str] = Field(None, description="Human-readable message")
+    error: Optional[str] = Field(None, description="Error message if operation failed")
+
+
+class UnbondingEntry(BaseModel):
+    """Represents an unbonding entry."""
+
+    amount: int = Field(..., description="Amount in wei")
+    unlock_block: int = Field(..., description="Block number when unbonding completes")
+
+    @classmethod
+    def from_scale_bytes(cls, scale_bytes: bytes) -> "UnbondingEntry":
+        """Create UnbondingEntry from SCALE encoded bytes."""
+        # Unbonding entry is (u128, u32) tuple
+
+        sb = ScaleBytes(scale_bytes)
+        amount = sb.get_next_u128()
+        unlock_block = sb.get_next_u32()
+
+        return cls(amount=amount, unlock_block=unlock_block)
+
+
+# ============================================================================
+# DIRECT STAKING RESPONSES
+# ============================================================================
+
+
+class StakeAddResponse(BaseStakingResponse):
+    """Response for adding stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    subnet_node_id: Optional[int] = Field(None, description="Subnet node ID")
+    hotkey: Optional[str] = Field(None, description="Hotkey address")
+    stake_added: Optional[int] = Field(None, description="Amount staked in wei")
+    total_stake: Optional[int] = Field(None, description="Total stake after operation")
+
+
+class StakeRemoveResponse(BaseStakingResponse):
+    """Response for removing stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    stake_removed: Optional[int] = Field(None, description="Amount removed in wei")
+    total_stake: Optional[int] = Field(
+        None, description="Remaining stake after operation"
+    )
+    unbonding_entries: Optional[list[UnbondingEntry]] = Field(
+        None, description="New unbonding entries created"
+    )
+
+
+class ClaimUnbondingsResponse(BaseStakingResponse):
+    """Response for claiming unbonded stake."""
+
+    total_claimed: Optional[int] = Field(
+        None, description="Total amount claimed in wei"
+    )
+    entries_claimed: Optional[int] = Field(
+        None, description="Number of unbonding entries claimed"
+    )
+    entries_remaining: Optional[int] = Field(
+        None, description="Number of unbonding entries remaining"
+    )
+
+
+# ============================================================================
+# DELEGATE STAKING RESPONSES
+# ============================================================================
+
+
+class DelegateStakeAddResponse(BaseStakingResponse):
+    """Response for adding delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    stake_added: Optional[int] = Field(None, description="Amount delegated in wei")
+    shares_received: Optional[int] = Field(None, description="Shares received")
+    share_price: Optional[float] = Field(
+        None, description="Share price in TENSOR per share"
+    )
+    total_shares: Optional[int] = Field(
+        None, description="Total shares after operation"
+    )
+
+
+class DelegateStakeRemoveResponse(BaseStakingResponse):
+    """Response for removing delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    shares_removed: Optional[int] = Field(None, description="Shares removed")
+    balance_received: Optional[int] = Field(None, description="Balance received in wei")
+    share_price: Optional[float] = Field(None, description="Share price at removal")
+    remaining_shares: Optional[int] = Field(None, description="Remaining shares")
+
+
+class DelegateStakeTransferResponse(BaseStakingResponse):
+    """Response for transferring delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    from_account: Optional[str] = Field(None, description="Source account")
+    to_account: Optional[str] = Field(None, description="Destination account")
+    shares_transferred: Optional[int] = Field(None, description="Shares transferred")
+
+
+class DelegateStakeSwapResponse(BaseStakingResponse):
+    """Response for swapping delegate stake."""
+
+    from_subnet_id: Optional[int] = Field(None, description="Source subnet ID")
+    to_subnet_id: Optional[int] = Field(None, description="Destination subnet ID")
+    shares_swapped: Optional[int] = Field(None, description="Shares swapped")
+    from_share_price: Optional[float] = Field(
+        None, description="Source subnet share price"
+    )
+    to_share_price: Optional[float] = Field(
+        None, description="Destination subnet share price"
+    )
+
+
+class DelegateStakeDonateResponse(BaseStakingResponse):
+    """Response for donating delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    shares_donated: Optional[int] = Field(None, description="Shares donated")
+    balance_donated: Optional[int] = Field(None, description="Balance donated in wei")
+
+
+# ============================================================================
+# VALIDATOR DELEGATE STAKING RESPONSES
+# ============================================================================
+
+
+class ValidatorDelegateStakeAddResponse(BaseStakingResponse):
+    """Response for adding validator delegate stake."""
+
+    validator_id: Optional[int] = Field(None, description="Validator ID")
+    stake_added: Optional[int] = Field(None, description="Amount delegated in wei")
+    shares_received: Optional[int] = Field(None, description="Shares received")
+
+
+class ValidatorDelegateStakeRemoveResponse(BaseStakingResponse):
+    """Response for removing validator delegate stake."""
+
+    validator_id: Optional[int] = Field(None, description="Validator ID")
+    shares_removed: Optional[int] = Field(None, description="Shares removed")
+    balance_received: Optional[int] = Field(None, description="Balance received in wei")
+
+
+class ValidatorDelegateStakeTransferResponse(BaseStakingResponse):
+    """Response for transferring validator delegate stake."""
+
+    validator_id: Optional[int] = Field(None, description="Validator ID")
+    to_account: Optional[str] = Field(None, description="Destination account")
+    shares_transferred: Optional[int] = Field(None, description="Shares transferred")
+
+
+class ValidatorDelegateStakeSwapResponse(BaseStakingResponse):
+    """Response for swapping validator delegate stake."""
+
+    from_validator_id: Optional[int] = Field(None, description="Source validator ID")
+    to_validator_id: Optional[int] = Field(None, description="Destination validator ID")
+    shares_swapped: Optional[int] = Field(None, description="Shares swapped")
+
+
+class ValidatorDelegateStakeDonateResponse(BaseStakingResponse):
+    """Response for donating validator delegate stake."""
+
+    validator_id: Optional[int] = Field(None, description="Validator ID")
+    balance_donated: Optional[int] = Field(None, description="Balance donated in wei")
+
+
+# ============================================================================
+# NODE DELEGATE STAKING RESPONSES
+# ============================================================================
+
+
+class NodeDelegateStakeAddResponse(BaseStakingResponse):
+    """Response for adding node delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    subnet_node_id: Optional[int] = Field(None, description="Subnet node ID")
+    hotkey: Optional[str] = Field(None, description="Hotkey address")
+    stake_added: Optional[int] = Field(None, description="Amount delegated in wei")
+    shares_received: Optional[int] = Field(None, description="Shares received")
+
+
+class NodeDelegateStakeRemoveResponse(BaseStakingResponse):
+    """Response for removing node delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    subnet_node_id: Optional[int] = Field(None, description="Subnet node ID")
+    hotkey: Optional[str] = Field(None, description="Hotkey address")
+    shares_removed: Optional[int] = Field(None, description="Shares removed")
+    balance_received: Optional[int] = Field(None, description="Balance received in wei")
+
+
+class NodeDelegateStakeTransferResponse(BaseStakingResponse):
+    """Response for transferring node delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    subnet_node_id: Optional[int] = Field(None, description="Subnet node ID")
+    hotkey: Optional[str] = Field(None, description="Hotkey address")
+    from_account: Optional[str] = Field(None, description="Source account")
+    to_account: Optional[str] = Field(None, description="Destination account")
+    shares_transferred: Optional[int] = Field(None, description="Shares transferred")
+
+
+class NodeDelegateStakeSwapResponse(BaseStakingResponse):
+    """Response for swapping node delegate stake."""
+
+    from_subnet_id: Optional[int] = Field(None, description="Source subnet ID")
+    from_subnet_node_id: Optional[int] = Field(
+        None, description="Source subnet node ID"
+    )
+    from_hotkey: Optional[str] = Field(None, description="Source hotkey")
+    to_subnet_id: Optional[int] = Field(None, description="Destination subnet ID")
+    to_subnet_node_id: Optional[int] = Field(
+        None, description="Destination subnet node ID"
+    )
+    to_hotkey: Optional[str] = Field(None, description="Destination hotkey")
+    shares_swapped: Optional[int] = Field(None, description="Shares swapped")
+
+
+class NodeDelegateStakeDonateResponse(BaseStakingResponse):
+    """Response for donating node delegate stake."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    subnet_node_id: Optional[int] = Field(None, description="Subnet node ID")
+    hotkey: Optional[str] = Field(None, description="Hotkey address")
+    shares_donated: Optional[int] = Field(None, description="Shares donated")
+    balance_donated: Optional[int] = Field(None, description="Balance donated in wei")
+
+
+# ============================================================================
+# CROSS-STAKE SWAP RESPONSES
+# ============================================================================
+
+
+class StakeSwapFromNodeToSubnetResponse(BaseStakingResponse):
+    """Response for swapping stake from node delegate to subnet delegate."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    subnet_node_id: Optional[int] = Field(None, description="Subnet node ID")
+    hotkey: Optional[str] = Field(None, description="Hotkey address")
+    stake_swapped: Optional[int] = Field(None, description="Amount swapped in wei")
+    node_shares_removed: Optional[int] = Field(
+        None, description="Node delegate shares removed"
+    )
+    subnet_shares_received: Optional[int] = Field(
+        None, description="Subnet delegate shares received"
+    )
+
+
+class StakeSwapFromSubnetToNodeResponse(BaseStakingResponse):
+    """Response for swapping stake from subnet delegate to node delegate."""
+
+    subnet_id: Optional[int] = Field(None, description="Subnet ID")
+    subnet_node_id: Optional[int] = Field(None, description="Subnet node ID")
+    hotkey: Optional[str] = Field(None, description="Hotkey address")
+    stake_swapped: Optional[int] = Field(None, description="Amount swapped in wei")
+    subnet_shares_removed: Optional[int] = Field(
+        None, description="Subnet delegate shares removed"
+    )
+    node_shares_received: Optional[int] = Field(
+        None, description="Node delegate shares received"
+    )
+
+
+class StakeSwapFromValidatorToSubnetResponse(BaseStakingResponse):
+    """Response for swapping stake from validator delegate to subnet delegate."""
+
+    validator_id: Optional[int] = Field(None, description="Source validator ID")
+    subnet_id: Optional[int] = Field(None, description="Destination subnet ID")
+    stake_swapped: Optional[int] = Field(None, description="Shares swapped")
+    validator_shares_removed: Optional[int] = Field(
+        None, description="Validator delegate shares removed"
+    )
+    subnet_shares_received: Optional[int] = Field(
+        None, description="Subnet delegate shares received"
+    )
+
+
+class StakeSwapFromSubnetToValidatorResponse(BaseStakingResponse):
+    """Response for swapping stake from subnet delegate to validator delegate."""
+
+    subnet_id: Optional[int] = Field(None, description="Source subnet ID")
+    validator_id: Optional[int] = Field(None, description="Destination validator ID")
+    stake_swapped: Optional[int] = Field(None, description="Shares swapped")
+    subnet_shares_removed: Optional[int] = Field(
+        None, description="Subnet delegate shares removed"
+    )
+    validator_shares_received: Optional[int] = Field(
+        None, description="Validator delegate shares received"
+    )
+
+
+class StakeSwapQueueUpdateResponse(BaseStakingResponse):
+    """Response for updating stake swap queue."""
+
+    queue_updated: Optional[bool] = Field(None, description="Whether queue was updated")
+    queue_position: Optional[int] = Field(
+        None, description="Position in queue if applicable"
+    )
+
+
+# ============================================================================
+# OVERWATCH STAKING RESPONSES
+# ============================================================================
+
+
+class OverwatchStakeAddResponse(BaseStakingResponse):
+    """Response for adding overwatch stake."""
+
+    stake_added: Optional[int] = Field(None, description="Amount staked in wei")
+    total_overwatch_stake: Optional[int] = Field(
+        None, description="Total overwatch stake"
+    )
+
+
+class OverwatchStakeRemoveResponse(BaseStakingResponse):
+    """Response for removing overwatch stake."""
+
+    stake_removed: Optional[int] = Field(None, description="Amount removed in wei")
+    remaining_overwatch_stake: Optional[int] = Field(
+        None, description="Remaining overwatch stake"
+    )
+
+
+# ============================================================================
+# QUERY RESPONSE MODELS
+# ============================================================================
+
+
+class StakeInfo(BaseModel):
+    """Comprehensive stake information for an account."""
+
+    account_id: str = Field(..., description="Account address")
+    subnet_id: int = Field(..., description="Subnet ID")
+
+    # Direct stake
+    direct_stake_balance: int = Field(0, description="Direct stake balance in wei")
+
+    # Delegate stake (subnet level)
+    delegate_stake_shares: int = Field(0, description="Delegate stake shares")
+    delegate_stake_balance: int = Field(0, description="Delegate stake balance in wei")
+
+    # Node delegate stakes
+    node_delegate_stakes: list[dict[str, Any]] = Field(
+        default_factory=list, description="Node delegate stakes"
+    )
+
+    # Unbonding information
+    unbonding_ledger: list[UnbondingEntry] = Field(
+        default_factory=list, description="Unbonding entries"
+    )
+
+    @classmethod
+    def from_scale_bytes(cls, scale_bytes: bytes) -> "StakeInfo":
+        """Create StakeInfo from SCALE encoded bytes."""
+
+        sb = ScaleBytes(scale_bytes)
+
+        # Parse the stake info structure
+        # This depends on the exact blockchain storage format
+        # For now, return a basic structure
+        return cls(
+            account_id="",  # Parse from context
+            subnet_id=0,  # Parse from context
+            direct_stake_balance=(
+                sb.get_next_u128() if sb.remaining_length() >= 16 else 0
+            ),
+            delegate_stake_shares=(
+                sb.get_next_u128() if sb.remaining_length() >= 16 else 0
+            ),
+            delegate_stake_balance=0,  # Calculate from shares
+            node_delegate_stakes=[],
+            unbonding_ledger=[],
+        )
+
+
+class DelegateStakeInfo(BaseModel):
+    """Delegate stake information for a subnet."""
+
+    subnet_id: int = Field(..., description="Subnet ID")
+    shares: int = Field(..., description="Number of shares")
+    balance: int = Field(..., description="Balance value in wei")
+    share_price: float = Field(..., description="Share price in TENSOR per share")
+
+    @classmethod
+    def from_scale_bytes(
+        cls, scale_bytes: bytes, subnet_id: int = 0
+    ) -> "DelegateStakeInfo":
+        """Create DelegateStakeInfo from SCALE encoded bytes."""
+
+        sb = ScaleBytes(scale_bytes)
+        shares = sb.get_next_u128()
+        balance = sb.get_next_u128()
+
+        share_price = balance / shares / 1e18 if shares > 0 else 1.0
+
+        return cls(
+            subnet_id=subnet_id, shares=shares, balance=balance, share_price=share_price
+        )
+
+
+class NodeDelegateStakeInfo(BaseModel):
+    """Node delegate stake information."""
+
+    subnet_id: int = Field(..., description="Subnet ID")
+    subnet_node_id: int = Field(..., description="Subnet node ID")
+    hotkey: str = Field(..., description="Hotkey address")
+    shares: int = Field(..., description="Number of shares")
+    balance: int = Field(..., description="Balance value in wei")
+
+    @classmethod
+    def from_scale_bytes(
+        cls,
+        scale_bytes: bytes,
+        subnet_id: int = 0,
+        subnet_node_id: int = 0,
+        hotkey: str = "",
+    ) -> "NodeDelegateStakeInfo":
+        """Create NodeDelegateStakeInfo from SCALE encoded bytes."""
+
+        sb = ScaleBytes(scale_bytes)
+        shares = sb.get_next_u128()
+        balance = sb.get_next_u128()
+
+        return cls(
+            subnet_id=subnet_id,
+            subnet_node_id=subnet_node_id,
+            hotkey=hotkey,
+            shares=shares,
+            balance=balance,
+        )
+
+
+class UnbondingLedger(BaseModel):
+    """Complete unbonding ledger for an account."""
+
+    account_id: str = Field(..., description="Account address")
+    total_unbonding: int = Field(0, description="Total unbonding amount in wei")
+    entries: list[UnbondingEntry] = Field(
+        default_factory=list, description="Unbonding entries"
+    )
+    claimable_amount: int = Field(0, description="Amount ready to claim in wei")
+    pending_amount: int = Field(0, description="Amount still unbonding in wei")
+
+    @classmethod
+    def from_scale_bytes(
+        cls, scale_bytes: bytes, account_id: str = "", current_block: int = 0
+    ) -> "UnbondingLedger":
+        """Create UnbondingLedger from SCALE encoded bytes."""
+
+        sb = ScaleBytes(scale_bytes)
+        entries = []
+
+        # Parse vector of (u128, u32) tuples
+        vector_length = sb.get_next_u32()
+        for _ in range(vector_length):
+            amount = sb.get_next_u128()
+            unlock_block = sb.get_next_u32()
+            entries.append(UnbondingEntry(amount=amount, unlock_block=unlock_block))
+
+        total_unbonding = sum(entry.amount for entry in entries)
+        claimable_amount = sum(
+            entry.amount for entry in entries if current_block >= entry.unlock_block
+        )
+        pending_amount = total_unbonding - claimable_amount
+
+        return cls(
+            account_id=account_id,
+            total_unbonding=total_unbonding,
+            entries=entries,
+            claimable_amount=claimable_amount,
+            pending_amount=pending_amount,
+        )