htcli 1.1.0__py3-none-any.whl

src/htcli/client/extrinsics/validator.py

@@ -0,0 +1,203 @@
+"""
+Validator management extrinsics for HTCLI.
+"""
+
+from typing import Any, Optional
+
+from substrateinterface import Keypair, SubstrateInterface
+
+from ...models.requests.validator import (
+    ValidatorColdkeyUpdateRequest,
+    ValidatorDelegateAccountUpdateRequest,
+    ValidatorDelegateRewardRateUpdateRequest,
+    ValidatorHotkeyUpdateRequest,
+    ValidatorIdentityUpdateRequest,
+    ValidatorRegisterRequest,
+)
+from ...utils.logging import get_logger
+from .base import BaseExtrinsicClient
+from .node import SimpleExtrinsicResponse
+
+logger = get_logger(__name__)
+
+
+class ValidatorExtrinsics(BaseExtrinsicClient):
+    """Client for validator-related extrinsics."""
+
+    def __init__(self, substrate: Optional[SubstrateInterface] = None):
+        super().__init__(substrate)
+
+    def register_validator(
+        self, request: ValidatorRegisterRequest, keypair: Keypair
+    ) -> SimpleExtrinsicResponse:
+        """Register a validator using live runtime metadata parameters."""
+        try:
+            logger.info("Registering validator")
+
+            delegate_account = None
+            if request.delegate_account_id:
+                delegate_account = {
+                    "account_id": request.delegate_account_id,
+                    "rate": (
+                        0
+                        if request.delegate_account_rate is None
+                        else request.delegate_account_rate
+                    ),
+                }
+
+            call_params: dict[str, Any] = {
+                "hotkey": request.hotkey,
+                "delegate_reward_rate": request.delegate_reward_rate,
+                "delegate_account": delegate_account,
+                "identity": request.identity,
+            }
+
+            call = self.substrate.compose_call(
+                call_module="Network",
+                call_function="register_validator",
+                call_params=call_params,
+            )
+            result = self._submit_extrinsic(call, keypair)
+
+            if result["success"]:
+                self._attach_validator_event_fields(result, request.hotkey)
+                result["message"] = "Validator registered successfully"
+
+            return SimpleExtrinsicResponse(result)
+        except Exception as e:
+            logger.error(f"Error registering validator: {e}")
+            return SimpleExtrinsicResponse({"success": False, "error": str(e)})
+
+    def update_validator_delegate_reward_rate(
+        self,
+        request: ValidatorDelegateRewardRateUpdateRequest,
+        keypair: Keypair,
+    ) -> SimpleExtrinsicResponse:
+        """Update a validator delegate reward rate."""
+        return self._submit_validator_update(
+            call_function="update_validator_delegate_reward_rate",
+            call_params={
+                "validator_id": request.validator_id,
+                "new_delegate_reward_rate": request.new_delegate_reward_rate,
+            },
+            keypair=keypair,
+            success_message=(
+                f"Validator {request.validator_id} delegate reward rate updated"
+            ),
+        )
+
+    def update_validator_delegate_account(
+        self,
+        request: ValidatorDelegateAccountUpdateRequest,
+        keypair: Keypair,
+    ) -> SimpleExtrinsicResponse:
+        """Update or clear a validator delegate account."""
+        return self._submit_validator_update(
+            call_function="update_validator_delegate_account",
+            call_params={
+                "validator_id": request.validator_id,
+                "delegate_account_id": request.delegate_account_id,
+                "delegate_rate": request.delegate_rate,
+            },
+            keypair=keypair,
+            success_message=f"Validator {request.validator_id} delegate account updated",
+        )
+
+    def update_validator_hotkey(
+        self,
+        request: ValidatorHotkeyUpdateRequest,
+        keypair: Keypair,
+    ) -> SimpleExtrinsicResponse:
+        """Update a validator hotkey."""
+        return self._submit_validator_update(
+            call_function="update_validator_hotkey",
+            call_params={
+                "validator_id": request.validator_id,
+                "new_hotkey": request.new_hotkey,
+            },
+            keypair=keypair,
+            success_message=f"Validator {request.validator_id} hotkey updated",
+        )
+
+    def update_validator_coldkey(
+        self,
+        request: ValidatorColdkeyUpdateRequest,
+        keypair: Keypair,
+    ) -> SimpleExtrinsicResponse:
+        """Update a validator coldkey."""
+        return self._submit_validator_update(
+            call_function="update_validator_coldkey",
+            call_params={
+                "validator_id": request.validator_id,
+                "new_coldkey": request.new_coldkey,
+            },
+            keypair=keypair,
+            success_message=f"Validator {request.validator_id} coldkey updated",
+        )
+
+    def update_validator_identity(
+        self,
+        request: ValidatorIdentityUpdateRequest,
+        keypair: Keypair,
+    ) -> SimpleExtrinsicResponse:
+        """Update or clear a validator identity."""
+        return self._submit_validator_update(
+            call_function="update_validator_identity",
+            call_params={
+                "validator_id": request.validator_id,
+                "identity": request.identity,
+            },
+            keypair=keypair,
+            success_message=f"Validator {request.validator_id} identity updated",
+        )
+
+    def _submit_validator_update(
+        self,
+        call_function: str,
+        call_params: dict[str, Any],
+        keypair: Keypair,
+        success_message: str,
+    ) -> SimpleExtrinsicResponse:
+        try:
+            call = self.substrate.compose_call(
+                call_module="Network",
+                call_function=call_function,
+                call_params=call_params,
+            )
+            result = self._submit_extrinsic(call, keypair)
+            if result["success"]:
+                result["message"] = success_message
+                result["validator_id"] = call_params.get("validator_id")
+            return SimpleExtrinsicResponse(result)
+        except Exception as e:
+            logger.error(f"Error submitting validator update {call_function}: {e}")
+            return SimpleExtrinsicResponse({"success": False, "error": str(e)})
+
+    def _attach_validator_event_fields(
+        self, result: dict[str, Any], fallback_hotkey: str
+    ) -> None:
+        for event in result.get("events", []):
+            if not hasattr(event, "value"):
+                continue
+            event_data = event.value
+            if event_data.get("module_id") != "Network":
+                continue
+            if event_data.get("event_id") not in {
+                "ValidatorRegistered",
+                "ValidatorCreated",
+            }:
+                continue
+
+            attributes = event_data.get("attributes", {})
+            if isinstance(attributes, dict):
+                result["validator_id"] = attributes.get("validator_id")
+                result["hotkey"] = attributes.get("hotkey", fallback_hotkey)
+            elif isinstance(attributes, (list, tuple)):
+                if attributes:
+                    result["validator_id"] = attributes[0]
+                if len(attributes) > 1:
+                    result["hotkey"] = attributes[1]
+            break
+
+        if "hotkey" not in result or not result["hotkey"]:
+            result["hotkey"] = fallback_hotkey

src/htcli/client/extrinsics/wallet.py

@@ -0,0 +1,323 @@
+"""
+Wallet extrinsics operations for blockchain state changes.
+Handles staking, unstaking, transfers, and other wallet-related transactions.
+"""
+
+from substrateinterface import SubstrateInterface
+
+from ...utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class WalletExtrinsics:
+    """Extrinsics client for wallet state-changing operations."""
+
+    def __init__(self, substrate: SubstrateInterface):
+        self.substrate = substrate
+
+    def transfer_funds(
+        self, from_address: str, to_address: str, amount: str, keypair=None
+    ):
+        """Transfer funds using Balances.transfer with real transaction submission."""
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            # Convert amount to the smallest unit (18 decimals for TENSOR)
+            amount_in_smallest_unit = int(float(amount) * 1e18)
+
+            # Convert address to proper format for substrate
+            if to_address.startswith("0x"):
+                # EVM address format
+                dest_bytes = bytes.fromhex(to_address[2:])
+            else:
+                # SS58 address format
+                from substrateinterface.utils.ss58 import ss58_decode
+
+                try:
+                    decoded_hex = ss58_decode(to_address)
+                    dest_bytes = bytes.fromhex(decoded_hex)
+                except Exception as e:
+                    logger.error(
+                        f"Failed to decode SS58 address {to_address}: {str(e)}"
+                    )
+                    raise Exception(f"Invalid SS58 address format: {str(e)}") from e
+
+            if len(dest_bytes) not in [20, 32]:
+                raise Exception("Address must be 20 or 32 bytes.")
+
+            # If keypair provided, check balance before submitting transaction
+            if keypair:
+                # Check sender's balance before attempting transfer
+                try:
+                    account_info = self.substrate.query("System", "Account", [from_address])
+                    available_balance = (
+                        account_info.value["data"]["free"]
+                        if account_info and account_info.value
+                        else 0
+                    )
+                    
+                    # Check if balance is sufficient (including potential fees)
+                    # Reserve some buffer for transaction fees (estimate ~0.01 TENSOR)
+                    fee_buffer = int(0.01 * 1e18)  # 0.01 TENSOR in smallest units
+                    required_balance = amount_in_smallest_unit + fee_buffer
+                    
+                    if available_balance < amount_in_smallest_unit:
+                        error_msg = (
+                            f"Insufficient balance. Available: {available_balance / 1e18:.4f} TENSOR, "
+                            f"Required: {float(amount):.4f} TENSOR"
+                        )
+                        logger.error(error_msg)
+                        raise Exception(error_msg)
+                    
+                    if available_balance < required_balance:
+                        logger.warning(
+                            f"Balance may be insufficient after fees. Available: {available_balance / 1e18:.4f} TENSOR, "
+                            f"Transfer amount: {float(amount):.4f} TENSOR"
+                        )
+                except Exception as e:
+                    # If balance check fails, log but don't block transfer
+                    # (in case of network issues, let blockchain validate)
+                    logger.warning(f"Could not verify balance before transfer: {str(e)}")
+                    # Re-raise if it's our insufficient balance error
+                    if "Insufficient balance" in str(e):
+                        raise
+
+            # Compose the call using Balances pallet
+            call_data = self.substrate.compose_call(
+                call_module="Balances",
+                call_function="transfer_keep_alive",
+                call_params={
+                    "dest": dest_bytes,
+                    "value": amount_in_smallest_unit,
+                },
+            )
+
+            # If keypair provided, submit real transaction
+            if keypair:
+                # Create and submit transaction
+                extrinsic = self.substrate.create_signed_extrinsic(
+                    call=call_data, keypair=keypair
+                )
+
+                # Submit and wait for confirmation with timeout
+                try:
+                    receipt = self.substrate.submit_extrinsic(
+                        extrinsic=extrinsic, wait_for_inclusion=True
+                    )
+                except Exception as e:
+                    error_str = str(e)
+                    # Improve error message for fee-related errors
+                    if "1010" in error_str or "Inability to pay" in error_str or "balance too low" in error_str.lower():
+                        error_msg = (
+                            f"Transaction failed: Insufficient balance to pay transaction fees.\n"
+                            f"   • The account needs sufficient balance to cover both the transfer amount and transaction fees.\n"
+                            f"   • Please ensure the account has enough TENSOR to cover fees (typically ~0.01-0.1 TENSOR).\n"
+                            f"   • Original error: {error_str}"
+                        )
+                        logger.error(error_msg)
+                        raise Exception(error_msg) from e
+                    logger.error(f"Failed to submit extrinsic: {error_str}")
+                    raise Exception(f"Transaction submission failed: {error_str}") from e
+
+                # CRITICAL: Check if transaction actually succeeded
+                # Even if no exception was raised, the transaction might have failed
+                if not hasattr(receipt, "is_success") or not receipt.is_success:
+                    # Extract error message from receipt
+                    error_msg = "Transaction failed"
+                    if hasattr(receipt, "error_message") and receipt.error_message:
+                        error_msg = str(receipt.error_message)
+                    elif hasattr(receipt, "triggered_events"):
+                        # Check for ExtrinsicFailed events
+                        for event in receipt.triggered_events:
+                            try:
+                                event_data = event.value if hasattr(event, "value") else event
+                                if (
+                                    event_data.get("module_id") == "System"
+                                    and event_data.get("event_id") == "ExtrinsicFailed"
+                                ):
+                                    error_msg = "Transaction failed: ExtrinsicFailed event detected"
+                                    break
+                            except Exception:
+                                continue
+                    
+                    logger.error(f"Transfer transaction failed: {error_msg}")
+                    raise Exception(f"Insufficient balance or transaction failed: {error_msg}")
+
+                # Check for ExtrinsicFailed events even if is_success is True
+                # Sometimes transactions are included but fail at runtime
+                extrinsic_failed = False
+                if hasattr(receipt, "triggered_events"):
+                    for event in receipt.triggered_events:
+                        try:
+                            event_data = event.value if hasattr(event, "value") else event
+                            if (
+                                event_data.get("module_id") == "System"
+                                and event_data.get("event_id") == "ExtrinsicFailed"
+                            ):
+                                extrinsic_failed = True
+                                break
+                        except Exception:
+                            # Skip malformed events
+                            continue
+                
+                if extrinsic_failed:
+                    error_msg = "Transaction failed: ExtrinsicFailed event detected"
+                    logger.error(f"Transfer transaction failed: {error_msg}")
+                    raise Exception(f"Insufficient balance or transaction failed: {error_msg}")
+
+                # Return real transaction details
+                return {
+                    "success": True,
+                    "message": "Transfer completed successfully",
+                    "transaction_hash": receipt.extrinsic_hash,
+                    "block_hash": receipt.block_hash,
+                    "block_number": receipt.block_number,
+                    "data": {
+                        "from_address": from_address,
+                        "to_address": to_address,
+                        "amount": amount,
+                        "amount_in_smallest_unit": amount_in_smallest_unit,
+                        "receipt": receipt,
+                        "fee": receipt.get("total_fee_amount"),
+                    },
+                }
+            else:
+                # Return composed call data for manual submission
+                return {
+                    "success": True,
+                    "message": "Transfer call composed successfully",
+                    "transaction_hash": None,
+                    "block_number": None,
+                    "data": {
+                        "from_address": from_address,
+                        "to_address": to_address,
+                        "amount": amount,
+                        "amount_in_smallest_unit": amount_in_smallest_unit,
+                        "call_data": call_data,
+                    },
+                }
+        except Exception as e:
+            # Use the centralized error handling system
+            from src.htcli.errors import handle_blockchain_error
+
+            blockchain_error = handle_blockchain_error(str(e))
+            raise blockchain_error from e
+
+    def update_coldkey(
+        self, hotkey: str, new_coldkey: str, keypair=None
+    ) -> dict:
+        """
+        Update the coldkey owner of a hotkey on-chain.
+        
+        This changes the blockchain state, moving ownership from the current coldkey
+        (signer) to the new coldkey. This is the authoritative way to change hotkey ownership.
+        
+        Args:
+            hotkey: The hotkey address whose owner is being changed
+            new_coldkey: The new coldkey address that will own the hotkey
+            keypair: Keypair of the current coldkey owner (must sign the transaction)
+            
+        Returns:
+            Dictionary with transaction result including hash, block number, etc.
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+            
+            if not keypair:
+                raise Exception("Keypair required to sign update_coldkey transaction")
+            
+            # Validate addresses
+            from ...utils.blockchain import validate_address
+            validate_address(hotkey)
+            validate_address(new_coldkey)
+            
+            # Ensure hotkey != new_coldkey
+            if hotkey.lower() == new_coldkey.lower():
+                raise Exception("Hotkey cannot be the same as the new coldkey")
+            
+            # Compose the call using Network pallet
+            call_data = self.substrate.compose_call(
+                call_module="Network",
+                call_function="update_coldkey",
+                call_params={
+                    "hotkey": hotkey,
+                    "new_coldkey": new_coldkey,
+                },
+            )
+            
+            # Create and submit transaction
+            extrinsic = self.substrate.create_signed_extrinsic(
+                call=call_data, keypair=keypair
+            )
+            
+            # Submit and wait for finalization
+            try:
+                receipt = self.substrate.submit_extrinsic(
+                    extrinsic=extrinsic,
+                    wait_for_inclusion=True,
+                    wait_for_finalization=True,
+                )
+            except Exception as e:
+                logger.error(f"Failed to submit update_coldkey extrinsic: {str(e)}")
+                raise Exception(f"Transaction submission failed: {str(e)}") from e
+            
+            # Check if transaction actually succeeded
+            if not hasattr(receipt, "is_success") or not receipt.is_success:
+                error_msg = "Transaction failed"
+                if hasattr(receipt, "error_message") and receipt.error_message:
+                    error_msg = str(receipt.error_message)
+                elif hasattr(receipt, "triggered_events"):
+                    for event in receipt.triggered_events:
+                        try:
+                            event_data = event.value if hasattr(event, "value") else event
+                            if (
+                                event_data.get("module_id") == "System"
+                                and event_data.get("event_id") == "ExtrinsicFailed"
+                            ):
+                                error_msg = "Transaction failed: ExtrinsicFailed event detected"
+                                break
+                        except Exception:
+                            continue
+                
+                logger.error(f"Update coldkey transaction failed: {error_msg}")
+                raise Exception(f"Update coldkey failed: {error_msg}")
+            
+            # Check for ExtrinsicFailed events
+            extrinsic_failed = False
+            if hasattr(receipt, "triggered_events"):
+                for event in receipt.triggered_events:
+                    try:
+                        event_data = event.value if hasattr(event, "value") else event
+                        if (
+                            event_data.get("module_id") == "System"
+                            and event_data.get("event_id") == "ExtrinsicFailed"
+                        ):
+                            extrinsic_failed = True
+                            break
+                    except Exception:
+                        continue
+            
+            if extrinsic_failed:
+                error_msg = "Transaction failed: ExtrinsicFailed event detected"
+                logger.error(f"Update coldkey transaction failed: {error_msg}")
+                raise Exception(f"Update coldkey failed: {error_msg}")
+            
+            # Return transaction details
+            return {
+                "success": True,
+                "message": "Coldkey updated successfully on-chain",
+                "transaction_hash": receipt.extrinsic_hash,
+                "block_hash": receipt.block_hash,
+                "block_number": receipt.block_number,
+                "data": {
+                    "hotkey": hotkey,
+                    "old_coldkey": keypair.ss58_address,
+                    "new_coldkey": new_coldkey,
+                },
+            }
+        except Exception as e:
+            logger.error(f"Error updating coldkey: {e}")
+            raise

src/htcli/client/offchain/__init__.py

@@ -0,0 +1,10 @@
+"""
+Off-chain module for local operations that don't interact with the blockchain.
+Contains utilities for wallet management, configuration, and local state management.
+"""
+
+from .backup import BackupManager
+from .config import ConfigManager
+from .wallet import WalletManager
+
+__all__ = ["WalletManager", "ConfigManager", "BackupManager"]