htcli 1.1.0__py3-none-any.whl

src/htcli/client/extrinsics/base.py

@@ -0,0 +1,487 @@
+"""
+Base extrinsic client with retry logic and common functionality.
+
+Provides shared functionality for all extrinsic clients including:
+- Retry logic for transient failures
+- Standard extrinsic submission
+- Error handling and extraction
+- Event parsing
+"""
+
+from typing import Any, Optional
+
+from substrateinterface import Keypair, SubstrateInterface
+from substrateinterface.exceptions import SubstrateRequestException
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_fixed
+
+from ...utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class BaseExtrinsicClient:
+    """Base class for all extrinsic clients with retry logic."""
+
+    def __init__(self, substrate: Optional[SubstrateInterface] = None):
+        """Initialize the base extrinsic client."""
+        self.substrate = substrate
+
+    @retry(
+        wait=wait_fixed(7),  # Wait 7 seconds between attempts
+        stop=stop_after_attempt(4),  # Try up to 4 times
+        retry=retry_if_exception_type(
+            (
+                SubstrateRequestException,
+                ConnectionError,
+                TimeoutError,
+                OSError,  # Network errors
+            )
+        ),
+        reraise=True,  # Re-raise the last exception if all retries fail
+    )
+    def _submit_extrinsic_with_retry(
+        self,
+        call: Any,
+        keypair: Keypair,
+        era_period: int = 64,
+        wait_for_inclusion: bool = True,
+        wait_for_finalization: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Submit an extrinsic with retry logic for transient failures.
+
+        Args:
+            call: The composed call to submit
+            keypair: Keypair for signing the transaction
+            era_period: Era period for transaction validity (blocks)
+            wait_for_inclusion: Wait for transaction to be included in a block
+            wait_for_finalization: Wait for transaction to be finalized (takes precedence over wait_for_inclusion)
+
+        Returns:
+            Dict with success status and transaction details
+
+        Raises:
+            Exception: If all retry attempts fail
+        """
+        try:
+            # Get current nonce
+            nonce = self.substrate.get_account_nonce(keypair.ss58_address)
+
+            # Create signed extrinsic (matching mesh-template pattern - no era parameter)
+            extrinsic = self.substrate.create_signed_extrinsic(
+                call=call, keypair=keypair, nonce=nonce
+            )
+
+            # Submit with appropriate wait option
+            # wait_for_finalization takes precedence if both are True
+            if wait_for_finalization:
+                response = self.substrate.submit_extrinsic(
+                    extrinsic, wait_for_finalization=True
+                )
+            elif wait_for_inclusion:
+                response = self.substrate.submit_extrinsic(
+                    extrinsic, wait_for_inclusion=True
+                )
+            else:
+                # Submit without waiting
+                response = self.substrate.submit_extrinsic(extrinsic)
+
+            if response.is_success:
+                # Extract all available fields from response
+                # Try direct access first (like NodeExtrinsics does), then fallback to getattr
+                try:
+                    extrinsic_hash = response.extrinsic_hash
+                    # Convert to hex string if it's bytes
+                    if isinstance(extrinsic_hash, bytes):
+                        extrinsic_hash = "0x" + extrinsic_hash.hex()
+                    elif extrinsic_hash and not isinstance(extrinsic_hash, str):
+                        extrinsic_hash = str(extrinsic_hash)
+                except (AttributeError, Exception):
+                    extrinsic_hash = getattr(response, "extrinsic_hash", None)
+                    if extrinsic_hash and isinstance(extrinsic_hash, bytes):
+                        extrinsic_hash = "0x" + extrinsic_hash.hex()
+
+                try:
+                    block_hash = response.block_hash
+                    # Convert to hex string if it's bytes
+                    if isinstance(block_hash, bytes):
+                        block_hash = "0x" + block_hash.hex()
+                    elif block_hash and not isinstance(block_hash, str):
+                        block_hash = str(block_hash)
+                except (AttributeError, Exception):
+                    block_hash = getattr(response, "block_hash", None)
+                    if block_hash and isinstance(block_hash, bytes):
+                        block_hash = "0x" + block_hash.hex()
+
+                try:
+                    block_number = response.block_number
+                except (AttributeError, Exception):
+                    block_number = getattr(response, "block_number", None)
+
+                # If block_number is not available but we have block_hash, query it
+                if block_number is None and block_hash:
+                    try:
+                        block_number = self.substrate.get_block_number(block_hash=block_hash)
+                    except Exception as e:
+                        logger.debug(f"Could not get block number from block hash: {e}")
+                        block_number = None
+
+                try:
+                    events = response.triggered_events
+                except (AttributeError, Exception):
+                    events = getattr(response, "triggered_events", []) or getattr(response, "events", [])
+
+                # CRITICAL: Check for ExtrinsicFailed events even if is_success is True
+                # Sometimes transactions are included but fail at runtime
+                for event in 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"
+                        ):
+                            # Transaction was included but failed at runtime
+                            error_msg = self._extract_error_message(response)
+                            logger.error(f"Extrinsic failed at runtime: {error_msg}")
+                            return {
+                                "success": False,
+                                "error": error_msg,
+                                "error_details": getattr(response, "error_message", None),
+                                "extrinsic_hash": extrinsic_hash,
+                                "block_hash": block_hash,
+                                "block_number": block_number,
+                            }
+                    except Exception:
+                        continue  # Skip malformed events
+
+                # Validate that we have essential transaction details
+                # If we don't have extrinsic_hash, the transaction didn't actually succeed
+                if not extrinsic_hash:
+                    error_msg = "Transaction submitted but no transaction hash returned. This may indicate a failure."
+                    logger.error(error_msg)
+                    logger.debug(f"Response type: {type(response)}")
+                    logger.debug(f"Response has extrinsic_hash attr: {hasattr(response, 'extrinsic_hash')}")
+                    logger.debug(f"Response has block_hash attr: {hasattr(response, 'block_hash')}")
+                    if hasattr(response, "extrinsic_hash"):
+                        logger.debug(f"extrinsic_hash type: {type(response.extrinsic_hash)}, value: {response.extrinsic_hash}")
+                    if hasattr(response, "block_hash"):
+                        logger.debug(f"block_hash type: {type(response.block_hash)}, value: {response.block_hash}")
+
+                    # Try to extract error from events as fallback
+                    error_from_events = self._extract_error_message(response)
+                    if error_from_events and error_from_events != "Unknown error occurred during extrinsic submission":
+                        error_msg = error_from_events
+
+                    return {
+                        "success": False,
+                        "error": error_msg,
+                        "error_details": getattr(response, "error_message", None),
+                        "extrinsic_hash": None,
+                        "block_hash": block_hash,
+                        "block_number": block_number,
+                    }
+
+                result = {
+                    "success": True,
+                    "extrinsic_hash": extrinsic_hash,
+                    "block_hash": block_hash,
+                    "block_number": block_number,
+                    "events": events,
+                }
+
+                # Also set transaction_hash as alias for compatibility
+                result["transaction_hash"] = extrinsic_hash
+
+                logger.info(
+                    f"Extrinsic submitted successfully: {extrinsic_hash} "
+                    f"at block {block_number}"
+                )
+
+                return result
+            else:
+                error_msg = self._extract_error_message(response)
+                logger.error(f"Extrinsic failed: {error_msg}")
+
+                # Return error details for handler to display nicely
+                return {
+                    "success": False,
+                    "error": error_msg,
+                    "error_details": getattr(response, "error_message", None),
+                    "extrinsic_hash": getattr(response, "extrinsic_hash", None),
+                }
+
+        except Exception as e:
+            logger.error(f"Error submitting extrinsic: {e}")
+            raise  # Let retry decorator handle retries
+
+    def _submit_extrinsic(
+        self,
+        call: Any,
+        keypair: Keypair,
+        wait_for_inclusion: bool = True,
+        wait_for_finalization: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Submit an extrinsic (wrapper for backward compatibility).
+
+        Args:
+            call: The composed call to submit
+            keypair: Keypair for signing the transaction
+            wait_for_inclusion: Wait for transaction to be included in a block
+            wait_for_finalization: Wait for transaction to be finalized (takes precedence over wait_for_inclusion)
+
+        Returns:
+            Dict with success status and transaction details
+        """
+        try:
+            return self._submit_extrinsic_with_retry(
+                call,
+                keypair,
+                wait_for_inclusion=wait_for_inclusion,
+                wait_for_finalization=wait_for_finalization,
+            )
+        except Exception as e:
+            # If retry fails, return error dict instead of raising
+            return {
+                "success": False,
+                "error": str(e),
+                "extrinsic_hash": None,
+            }
+
+    def _extract_error_message(self, response: Any) -> str:
+        """
+        Extract error message from substrate response.
+
+        Args:
+            response: Substrate response object
+
+        Returns:
+            Human-readable error message (preferably just the error name like "NotPendingSubnetOwner")
+        """
+        try:
+            # First, try to get error from error_message attribute
+            if hasattr(response, "error_message") and response.error_message:
+                error = response.error_message
+
+                if isinstance(error, dict):
+                    # Module error format: {"type": "Module", "name": "NotPendingSubnetOwner", "docs": [...]}
+                    if error.get("type") == "Module":
+                        module_error = error.get("name", "UnknownError")
+                        # Return just the error name for easier matching in error handlers
+                        # The error handlers will provide user-friendly messages
+                        return module_error
+
+                    # RPC error format: {'code': ..., 'message': ..., 'data': ...}
+                    if "message" in error:
+                        message = error["message"]
+                        data = error.get("data", "")
+                        if data:
+                            return f"{message}: {data}"
+                        return message
+
+                    # Check if error dict has a "name" key directly
+                    if "name" in error:
+                        return error["name"]
+
+                    # Other error types
+                    return str(error)
+
+                # If error_message is a string, return it
+                if isinstance(error, str):
+                    return error
+
+                return str(error)
+
+            # Fallback: Extract error from ExtrinsicFailed events
+            if hasattr(response, "triggered_events"):
+                for event in response.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"
+                        ):
+                            # Extract the actual error name from event attributes
+                            attributes = event_data.get("attributes", [])
+                            if attributes:
+                                error = attributes[0]
+
+                                # Try multiple ways to extract the error name
+                                if hasattr(error, "name"):
+                                    return error.name
+                                elif isinstance(error, dict):
+                                    # Check for nested error structure
+                                    if "name" in error:
+                                        return error["name"]
+                                    elif "error" in error and isinstance(error["error"], dict):
+                                        return error["error"].get("name", str(error))
+                                    # Check for Module error format in attributes
+                                    if error.get("type") == "Module":
+                                        return error.get("name", str(error))
+                                    return str(error)
+                                elif isinstance(error, (list, tuple)) and len(error) >= 2:
+                                    # Error might be encoded as [module_index, error_index]
+                                    # substrateinterface should decode this, but handle it just in case
+                                    logger.debug(f"Error encoded as indices: {error}")
+                                    return "UnknownError"  # Can't decode without metadata
+                                else:
+                                    # Try to convert to string and check if it looks like an error name
+                                    error_str = str(error)
+                                    # If it's a simple string that looks like an error name, return it
+                                    if error_str and not error_str.startswith("{") and not error_str.startswith("["):
+                                        return error_str
+                                    return error_str
+
+                            # No attributes found
+                            logger.debug("ExtrinsicFailed event has no attributes")
+                            return "ExtrinsicFailed"
+                    except Exception as e:
+                        logger.debug(f"Error extracting from event: {e}")
+                        continue  # Skip malformed events
+
+            # Log what we have for debugging
+            logger.debug(f"Could not extract error from response. Type: {type(response)}")
+            if hasattr(response, "__dict__"):
+                logger.debug(f"Response attributes: {list(response.__dict__.keys())}")
+
+            return "Unknown error occurred during extrinsic submission"
+
+        except Exception as e:
+            logger.warning(f"Could not extract error message: {e}", exc_info=True)
+            return "Error occurred during transaction processing"
+
+    def _extract_event_by_type(
+        self, events: list, module_id: str, event_id: str
+    ) -> Optional[dict[str, Any]]:
+        """
+        Extract specific event data from response events.
+
+        Args:
+            events: List of triggered events
+            module_id: Module ID to match (e.g., "Network")
+            event_id: Event ID to match (e.g., "SubnetRegistered")
+
+        Returns:
+            Event data dict or None if not found
+        """
+        try:
+            for event in events:
+                event_data = event.value
+                if (
+                    event_data.get("module_id") == module_id
+                    and event_data.get("event_id") == event_id
+                ):
+                    return event_data
+        except Exception as e:
+            logger.warning(f"Could not extract event data: {e}")
+
+        return None
+
+    def _extract_attribute_value(
+        self, event_data: dict[str, Any], attribute_index: int, default: Any = None
+    ) -> Any:
+        """
+        Extract attribute value from event data by index.
+
+        Args:
+            event_data: Event data dictionary
+            attribute_index: Index of attribute to extract
+            default: Default value if extraction fails
+
+        Returns:
+            Attribute value or default
+        """
+        try:
+            attributes = event_data.get("attributes", [])
+            if attribute_index < len(attributes):
+                return attributes[attribute_index]
+        except Exception as e:
+            logger.warning(f"Could not extract attribute {attribute_index}: {e}")
+
+        return default
+
+    def _decode_bytes_attribute(self, value: Any) -> str:
+        """
+        Decode bytes attribute to string.
+
+        Args:
+            value: Bytes or string value
+
+        Returns:
+            Decoded string
+        """
+        try:
+            if isinstance(value, bytes):
+                return value.decode("utf-8", errors="ignore")
+            return str(value)
+        except Exception:
+            return str(value)
+
+    def _validate_keypair(self, keypair: Keypair) -> None:
+        """
+        Validate that keypair is properly initialized.
+
+        Args:
+            keypair: Keypair to validate
+
+        Raises:
+            ValueError: If keypair is invalid
+        """
+        if not keypair:
+            raise ValueError("Keypair is required")
+
+        if not hasattr(keypair, "ss58_address") or not keypair.ss58_address:
+            raise ValueError("Keypair must have valid SS58 address")
+
+        if not hasattr(keypair, "private_key") or not keypair.private_key:
+            raise ValueError("Keypair must have valid private key")
+
+    def _validate_substrate(self) -> None:
+        """
+        Validate that substrate interface is properly initialized.
+
+        Raises:
+            ValueError: If substrate is invalid
+        """
+        if not self.substrate:
+            raise ValueError("Substrate interface is required")
+
+        try:
+            # Test connection
+            self.substrate.get_block_number()
+        except Exception as e:
+            raise ValueError(f"Substrate interface not connected: {e}") from e
+
+
+# Common error messages for better user experience
+COMMON_ERROR_MESSAGES = {
+    "NotEnoughBalanceToStake": "Insufficient balance to stake the requested amount",
+    "NotEnoughStakeToWithdraw": "Insufficient stake shares to withdraw the requested amount",
+    "MinStakeNotReached": "Stake amount below minimum required",
+    "MaxStakeReached": "Stake amount exceeds maximum allowed",
+    "InvalidSubnetId": "Subnet does not exist",
+    "InvalidNodeId": "Subnet node does not exist",
+    "SubnetAlreadyExists": "Subnet name already exists",
+    "NodeAlreadyRegistered": "Node already registered for this subnet",
+    "NotSubnetOwner": "Only subnet owner can perform this action",
+    "NodeNotActive": "Subnet node is not active",
+    "SubnetNotActive": "Subnet is not active",
+    "NotKeyOwner": "The selected coldkey does not own the hotkey for this node",
+}
+
+
+def get_user_friendly_error(error_msg: str) -> str:
+    """
+    Convert technical error messages to user-friendly ones.
+
+    Args:
+        error_msg: Technical error message
+
+    Returns:
+        User-friendly error message
+    """
+    for error_type, friendly_msg in COMMON_ERROR_MESSAGES.items():
+        if error_type in error_msg:
+            return friendly_msg
+
+    return error_msg

src/htcli/client/extrinsics/consensus.py

@@ -0,0 +1,79 @@
+"""
+Consensus-related extrinsics.
+"""
+
+from typing import Any, Dict
+
+from substrateinterface import Keypair
+
+from ...models.requests.consensus import AttestRequest, ProposeAttestationRequest
+from ...utils.logging import get_logger
+from .base import BaseExtrinsicClient
+
+logger = get_logger(__name__)
+
+
+class ConsensusExtrinsics(BaseExtrinsicClient):
+    """Consensus-related extrinsics."""
+
+    def propose_attestation(
+        self, request: ProposeAttestationRequest, keypair: Keypair
+    ) -> Dict[str, Any]:
+        """
+        Propose an attestation.
+
+        Args:
+            request: Proposal request
+            keypair: Keypair for signing
+
+        Returns:
+            Extrinsic receipt
+        """
+        try:
+            logger.info(f"Proposing attestation for subnet {request.subnet_id}")
+
+            call = self.substrate.compose_call(
+                call_module="Network",
+                call_function="propose_attestation",
+                call_params={
+                    "subnet_id": request.subnet_id,
+                    "data": request.data,
+                },
+            )
+
+            return self._submit_extrinsic(call, keypair)
+
+        except Exception as e:
+            logger.error(f"Error proposing attestation: {e}")
+            return {"success": False, "error": str(e)}
+
+    def attest(self, request: AttestRequest, keypair: Keypair) -> Dict[str, Any]:
+        """
+        Attest to a proposal.
+
+        Args:
+            request: Attestation request
+            keypair: Keypair for signing
+
+        Returns:
+            Extrinsic receipt
+        """
+        try:
+            logger.info(
+                f"Attesting to proposal {request.proposal_hash} on subnet {request.subnet_id}"
+            )
+
+            call = self.substrate.compose_call(
+                call_module="Network",
+                call_function="attest",
+                call_params={
+                    "subnet_id": request.subnet_id,
+                    "proposal_hash": request.proposal_hash,
+                },
+            )
+
+            return self._submit_extrinsic(call, keypair)
+
+        except Exception as e:
+            logger.error(f"Error attesting: {e}")
+            return {"success": False, "error": str(e)}