htcli 1.1.0__py3-none-any.whl

src/htcli/utils/blockchain/staking.py

@@ -0,0 +1,448 @@
+"""
+Staking utilities for Hypertensor blockchain.
+
+Provides helper functions for staking calculations, conversions,
+and share calculations.
+"""
+
+from typing import Optional, Tuple
+
+# ============================================================================
+# UNIT CONVERSIONS
+# ============================================================================
+
+
+def wei_to_tensor(wei_amount: int) -> float:
+    """
+    Convert wei amount to TENSOR.
+
+    Args:
+        wei_amount: Amount in wei
+
+    Returns:
+        Amount in TENSOR
+    """
+    return wei_amount / 1e18
+
+
+def tensor_to_wei(tensor_amount: float) -> int:
+    """
+    Convert TENSOR amount to wei.
+
+    Args:
+        tensor_amount: Amount in TENSOR
+
+    Returns:
+        Amount in wei
+    """
+    return int(tensor_amount * 1e18)
+
+
+def format_tensor_amount(wei_amount: int, decimals: int = 4) -> str:
+    """
+    Format wei amount as human-readable TENSOR string.
+
+    Args:
+        wei_amount: Amount in wei
+        decimals: Number of decimal places to show
+
+    Returns:
+        Formatted string (e.g., "100.5000 TENSOR")
+    """
+    tensor_amount = wei_to_tensor(wei_amount)
+    return f"{tensor_amount:.{decimals}f} TENSOR"
+
+
+def parse_tensor_amount(tensor_str: str) -> int:
+    """
+    Parse human-readable TENSOR string to wei.
+
+    Args:
+        tensor_str: String like "100.5 TENSOR" or "100.5"
+
+    Returns:
+        Amount in wei
+
+    Raises:
+        ValueError: If string format is invalid
+    """
+    # Remove "TENSOR" suffix if present
+    amount_str = tensor_str.replace("TENSOR", "").strip()
+
+    try:
+        tensor_amount = float(amount_str)
+        return tensor_to_wei(tensor_amount)
+    except ValueError:
+        raise ValueError(f"Invalid tensor amount format: {tensor_str}")
+
+
+# ============================================================================
+# SHARE CALCULATIONS
+# ============================================================================
+
+
+def calculate_shares_from_balance(
+    balance: int, total_shares: int, total_balance: int
+) -> int:
+    """
+    Calculate shares from balance using current share price.
+
+    Args:
+        balance: Balance to convert to shares
+        total_shares: Current total shares outstanding
+        total_balance: Current total balance backing shares
+
+    Returns:
+        Number of shares
+    """
+    if total_shares == 0:
+        # If no shares exist, 1 share = 1 wei (initial price)
+        return balance
+
+    if total_balance == 0:
+        raise ValueError("Cannot calculate shares with zero total balance")
+
+    # Share price = total_balance / total_shares
+    # Shares = balance / share_price = balance * total_shares / total_balance
+    return (balance * total_shares) // total_balance
+
+
+def calculate_balance_from_shares(
+    shares: int, total_shares: int, total_balance: int
+) -> int:
+    """
+    Calculate balance from shares using current share price.
+
+    Args:
+        shares: Number of shares
+        total_shares: Current total shares outstanding
+        total_balance: Current total balance backing shares
+
+    Returns:
+        Balance in wei
+    """
+    if total_shares == 0:
+        return 0
+
+    # Share price = total_balance / total_shares
+    # Balance = shares * share_price = shares * total_balance / total_shares
+    return (shares * total_balance) // total_shares
+
+
+def calculate_share_price(total_shares: int, total_balance: int) -> float:
+    """
+    Calculate current share price.
+
+    Args:
+        total_shares: Current total shares outstanding
+        total_balance: Current total balance backing shares
+
+    Returns:
+        Share price in TENSOR per share
+    """
+    if total_shares == 0:
+        return 1.0  # Initial price
+
+    return wei_to_tensor(total_balance) / total_shares
+
+
+def calculate_share_price_change(
+    old_total_shares: int,
+    old_total_balance: int,
+    new_total_shares: int,
+    new_total_balance: int,
+) -> Tuple[float, float]:
+    """
+    Calculate share price change between two states.
+
+    Args:
+        old_total_shares: Previous total shares
+        old_total_balance: Previous total balance
+        new_total_shares: New total shares
+        new_total_balance: New total balance
+
+    Returns:
+        Tuple of (old_price, new_price) in TENSOR per share
+    """
+    old_price = calculate_share_price(old_total_shares, old_total_balance)
+    new_price = calculate_share_price(new_total_shares, new_total_balance)
+
+    return old_price, new_price
+
+
+# ============================================================================
+# UNBONDING CALCULATIONS
+# ============================================================================
+
+
+def estimate_unbonding_time(blocks_per_epoch: int = 2100) -> int:
+    """
+    Estimate unbonding time in blocks.
+
+    Args:
+        blocks_per_epoch: Number of blocks per epoch
+
+    Returns:
+        Estimated unbonding time in blocks
+    """
+    # Typical unbonding period is 7 epochs
+    unbonding_epochs = 7
+    return unbonding_epochs * blocks_per_epoch
+
+
+def estimate_unbonding_time_days(
+    blocks_per_epoch: int = 2100, block_time_seconds: int = 6
+) -> float:
+    """
+    Estimate unbonding time in days.
+
+    Args:
+        blocks_per_epoch: Number of blocks per epoch
+        block_time_seconds: Average block time in seconds
+
+    Returns:
+        Estimated unbonding time in days
+    """
+    unbonding_blocks = estimate_unbonding_time(blocks_per_epoch)
+    unbonding_seconds = unbonding_blocks * block_time_seconds
+    return unbonding_seconds / (24 * 60 * 60)  # Convert to days
+
+
+def calculate_unbonding_ledger_total(unbonding_ledger: list) -> int:
+    """
+    Calculate total amount in unbonding ledger.
+
+    Args:
+        unbonding_ledger: List of (amount, unlock_block) tuples
+
+    Returns:
+        Total unbonding amount in wei
+    """
+    return sum(entry[0] for entry in unbonding_ledger)
+
+
+def find_claimable_unbondings(
+    unbonding_ledger: list, current_block: int
+) -> Tuple[list, list]:
+    """
+    Find claimable and pending unbondings.
+
+    Args:
+        unbonding_ledger: List of (amount, unlock_block) tuples
+        current_block: Current blockchain block number
+
+    Returns:
+        Tuple of (claimable_entries, pending_entries)
+    """
+    claimable = []
+    pending = []
+
+    for entry in unbonding_ledger:
+        amount, unlock_block = entry
+        if current_block >= unlock_block:
+            claimable.append(entry)
+        else:
+            pending.append(entry)
+
+    return claimable, pending
+
+
+# ============================================================================
+# STAKE VALIDATION
+# ============================================================================
+
+
+def validate_stake_amount(
+    amount: int, min_stake: int, max_stake: int, current_stake: int = 0
+) -> Tuple[bool, Optional[str]]:
+    """
+    Validate stake amount against limits.
+
+    Args:
+        amount: Amount to stake
+        min_stake: Minimum stake requirement
+        max_stake: Maximum stake limit
+        current_stake: Current stake amount
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if amount <= 0:
+        return False, "Stake amount must be positive"
+
+    new_total = current_stake + amount
+
+    if new_total < min_stake:
+        return (
+            False,
+            f"Total stake {format_tensor_amount(new_total)} below minimum {format_tensor_amount(min_stake)}",
+        )
+
+    if new_total > max_stake:
+        return (
+            False,
+            f"Total stake {format_tensor_amount(new_total)} exceeds maximum {format_tensor_amount(max_stake)}",
+        )
+
+    return True, None
+
+
+def validate_unstake_amount(
+    amount: int, current_stake: int, min_stake: int = 0
+) -> Tuple[bool, Optional[str]]:
+    """
+    Validate unstake amount against current stake.
+
+    Args:
+        amount: Amount to unstake
+        current_stake: Current stake amount
+        min_stake: Minimum stake to maintain
+
+    Returns:
+        Tuple of (is_valid, error_message)
+    """
+    if amount <= 0:
+        return False, "Unstake amount must be positive"
+
+    if amount > current_stake:
+        return (
+            False,
+            f"Cannot unstake {format_tensor_amount(amount)} from {format_tensor_amount(current_stake)}",
+        )
+
+    remaining_stake = current_stake - amount
+
+    if remaining_stake < min_stake:
+        return (
+            False,
+            f"Remaining stake {format_tensor_amount(remaining_stake)} below minimum {format_tensor_amount(min_stake)}",
+        )
+
+    return True, None
+
+
+# ============================================================================
+# REWARD CALCULATIONS
+# ============================================================================
+
+
+def calculate_delegate_reward_rate(
+    node_stake: int,
+    total_subnet_stake: int,
+    base_reward_rate: float = 0.15,  # 15% base rate
+) -> float:
+    """
+    Calculate delegate reward rate for a node.
+
+    Args:
+        node_stake: Node's stake amount
+        total_subnet_stake: Total stake in subnet
+        base_reward_rate: Base reward rate (default 15%)
+
+    Returns:
+        Calculated reward rate as decimal (0.15 = 15%)
+    """
+    if total_subnet_stake == 0:
+        return base_reward_rate
+
+    # Calculate stake ratio
+    stake_ratio = node_stake / total_subnet_stake
+
+    # Adjust reward rate based on stake ratio
+    # Higher stake ratio = higher reward rate
+    adjusted_rate = base_reward_rate * (1 + stake_ratio)
+
+    # Cap at maximum rate (e.g., 25%)
+    max_rate = 0.25
+    return min(adjusted_rate, max_rate)
+
+
+def estimate_rewards(stake_amount: int, reward_rate: float, epochs: int = 1) -> int:
+    """
+    Estimate rewards for a given stake amount and rate.
+
+    Args:
+        stake_amount: Stake amount in wei
+        reward_rate: Reward rate as decimal (0.15 = 15%)
+        epochs: Number of epochs to calculate for
+
+    Returns:
+        Estimated rewards in wei
+    """
+    # Annual reward rate to epoch reward rate
+    # Assuming 365 days / 7 days per epoch = ~52 epochs per year
+    epochs_per_year = 52
+    epoch_reward_rate = reward_rate / epochs_per_year
+
+    # Calculate compound interest
+    rewards = stake_amount * epoch_reward_rate * epochs
+
+    return int(rewards)
+
+
+# ============================================================================
+# UTILITY FUNCTIONS
+# ============================================================================
+
+
+def format_stake_summary(
+    direct_stake: int,
+    delegate_stake_shares: int,
+    delegate_stake_balance: int,
+    node_delegate_stakes: list,
+) -> str:
+    """
+    Format a comprehensive stake summary.
+
+    Args:
+        direct_stake: Direct stake amount
+        delegate_stake_shares: Delegate stake shares
+        delegate_stake_balance: Delegate stake balance
+        node_delegate_stakes: List of node delegate stakes
+
+    Returns:
+        Formatted summary string
+    """
+    lines = []
+
+    if direct_stake > 0:
+        lines.append(f"Direct Stake: {format_tensor_amount(direct_stake)}")
+
+    if delegate_stake_shares > 0:
+        lines.append(
+            f"Delegate Stake: {format_tensor_amount(delegate_stake_balance)} ({delegate_stake_shares} shares)"
+        )
+
+    if node_delegate_stakes:
+        lines.append("Node Delegate Stakes:")
+        for stake in node_delegate_stakes:
+            lines.append(
+                f"  - Node {stake['node_id']}: {format_tensor_amount(stake['balance'])}"
+            )
+
+    if not lines:
+        lines.append("No stakes found")
+
+    return "\n".join(lines)
+
+
+def calculate_total_stake_value(
+    direct_stake: int, delegate_stake_balance: int, node_delegate_stakes: list
+) -> int:
+    """
+    Calculate total stake value across all types.
+
+    Args:
+        direct_stake: Direct stake amount
+        delegate_stake_balance: Delegate stake balance
+        node_delegate_stakes: List of node delegate stakes
+
+    Returns:
+        Total stake value in wei
+    """
+    total = direct_stake + delegate_stake_balance
+
+    for stake in node_delegate_stakes:
+        total += stake.get("balance", 0)
+
+    return total