htcli 1.1.0__py3-none-any.whl

src/htcli/client/rpc/__init__.py

@@ -0,0 +1,20 @@
+"""
+RPC module for read-only blockchain queries.
+Contains clients for querying blockchain state without making changes.
+"""
+
+from .chain import ChainRpcClient
+from .node import SubnetNodeRpcClient
+from .overwatch import OverwatchRpcClient
+from .staking import StakingRpcClient
+from .subnet import SubnetRpcClient
+from .wallet import WalletRpcClient
+
+__all__ = [
+    "ChainRpcClient",
+    "StakingRpcClient",
+    "SubnetRpcClient",
+    "WalletRpcClient",
+    "SubnetNodeRpcClient",
+    "OverwatchRpcClient",
+]

src/htcli/client/rpc/chain.py

@@ -0,0 +1,568 @@
+"""
+RPC client for general chain queries.
+Handles network peers, block info, chain head, and runtime version queries.
+"""
+
+import math
+import time
+from typing import Any, Optional
+
+from substrateinterface import SubstrateInterface
+
+from ...utils.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ChainRpcClient:
+    """RPC client for general chain read-only operations."""
+
+    def __init__(self, substrate: Optional[SubstrateInterface] = None):
+        """Initialize the chain RPC client."""
+        self.substrate = substrate
+
+    def get_block_number(self, block_hash: Optional[str] = None) -> Optional[int]:
+        """
+        Get the block number for the supplied hash (defaults to latest).
+
+        Args:
+            block_hash: Optional block hash to resolve. When omitted, the latest block
+                hash is fetched first (matching mesh-template chain_functions).
+
+        Returns:
+            Current block number or None if error
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            # If we already have a block hash, resolve it directly
+            if block_hash:
+                return self.substrate.get_block_number(block_hash=block_hash)
+
+            # Otherwise, fetch the latest block hash and resolve that
+            latest_hash = self.substrate.get_block_hash()
+            if latest_hash:
+                return self.substrate.get_block_number(block_hash=latest_hash)
+
+            # Fallback to querying the latest header (should rarely be needed)
+            header = self.substrate.rpc_request("chain_getHeader", [None])
+            if header and "result" in header and header["result"].get("number"):
+                return int(header["result"]["number"], 16)
+
+            return None
+        except Exception as e:
+            logger.error(f"Failed to get block number: {str(e)}")
+            return None
+
+    def get_current_epoch(self) -> Optional[int]:
+        """
+        Get current epoch number.
+
+        Returns:
+            Current epoch or None if error
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            # Get current block
+            block_num = self.get_block_number()
+            if block_num is None:
+                return None
+
+            # Get epoch length from runtime constant
+            epoch_length = self.substrate.get_constant("Network", "EpochLength")
+            if epoch_length:
+                return block_num // epoch_length.value
+            return None
+        except Exception as e:
+            logger.error(f"Failed to get current epoch: {str(e)}")
+            return None
+
+    def get_account_balance(self, address: str) -> Optional[int]:
+        """
+        Get account balance in wei.
+
+        Args:
+            address: Account address
+
+        Returns:
+            Balance in wei or None if error
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            # Query account info
+            result = self.substrate.query("System", "Account", [address])
+            if result and hasattr(result, "value") and result.value:
+                account_info = result.value
+                # Get free balance
+                if isinstance(account_info, dict) and "data" in account_info:
+                    return account_info["data"].get("free", 0)
+            return 0
+        except Exception as e:
+            logger.error(f"Failed to get account balance: {str(e)}")
+            return None
+
+    def get_peers(self) -> dict[str, Any]:
+        """
+        Get network peers using RPC call.
+
+        Returns:
+            dictionary with peers information
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            peers = self.substrate.rpc_request("system_peers", [])
+
+            return {
+                "success": True,
+                "message": "Peers retrieved successfully",
+                "data": peers.get("result", []) if peers else [],
+            }
+        except Exception as e:
+            logger.error(f"Failed to get peers: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get peers: {str(e)}",
+                "data": [],
+            }
+
+    def get_block_info(self, block_number: Optional[int] = None) -> dict[str, Any]:
+        """
+        Get block information using RPC calls.
+
+        Args:
+            block_number: Optional block number to query (defaults to latest)
+
+        Returns:
+            dictionary with block information
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            # Get block hash
+            if block_number is not None:
+                block_hash = self.substrate.get_block_hash(block_number)
+            else:
+                block_hash = self.substrate.get_chain_head()
+
+            # Get block header and data
+            block_header = self.substrate.get_block_header(block_hash)
+            block = self.substrate.get_block(block_hash)
+
+            return {
+                "success": True,
+                "message": "Block info retrieved successfully",
+                "data": {
+                    "hash": str(block_hash),
+                    "number": block_header.get("number", 0) if block_header else 0,
+                    "parent_hash": (
+                        str(block_header.get("parentHash", "")) if block_header else ""
+                    ),
+                    "state_root": (
+                        str(block_header.get("stateRoot", "")) if block_header else ""
+                    ),
+                    "extrinsics_root": (
+                        str(block_header.get("extrinsicsRoot", ""))
+                        if block_header
+                        else ""
+                    ),
+                    "digest": block_header.get("digest", {}) if block_header else {},
+                    "extrinsics_count": (
+                        len(block.get("extrinsics", [])) if block else 0
+                    ),
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to get block info: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get block info: {str(e)}",
+                "data": {},
+            }
+
+    def get_chain_head(self) -> dict[str, Any]:
+        """
+        Get the current chain head.
+
+        Returns:
+            dictionary with chain head information
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            head = self.substrate.get_chain_head()
+            return {
+                "success": True,
+                "message": "Chain head retrieved successfully",
+                "data": {"head": str(head)},
+            }
+        except Exception as e:
+            logger.error(f"Failed to get chain head: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get chain head: {str(e)}",
+                "data": {"head": None},
+            }
+
+    def get_runtime_version(self) -> dict[str, Any]:
+        """
+        Get the runtime version.
+
+        Returns:
+            dictionary with runtime version information
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            runtime_version = self.substrate.get_runtime_version()
+            return {
+                "success": True,
+                "message": "Runtime version retrieved successfully",
+                "data": runtime_version,
+            }
+        except Exception as e:
+            logger.error(f"Failed to get runtime version: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get runtime version: {str(e)}",
+                "data": {},
+            }
+
+    def get_network_properties(self) -> dict[str, Any]:
+        """
+        Get network properties using RPC call.
+
+        Returns:
+            dictionary with network properties
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            properties = self.substrate.rpc_request("system_properties", [])
+
+            return {
+                "success": True,
+                "message": "Network properties retrieved successfully",
+                "data": properties.get("result", {}) if properties else {},
+            }
+        except Exception as e:
+            logger.error(f"Failed to get network properties: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get network properties: {str(e)}",
+                "data": {},
+            }
+
+    def get_chain_spec(self) -> dict[str, Any]:
+        """
+        Get chain specification using RPC call.
+
+        Returns:
+            dictionary with chain specification
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            chain_spec = self.substrate.rpc_request("system_chain", [])
+
+            return {
+                "success": True,
+                "message": "Chain spec retrieved successfully",
+                "data": {
+                    "chain": chain_spec.get("result", "") if chain_spec else "",
+                },
+            }
+        except Exception as e:
+            logger.error(f"Failed to get chain spec: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get chain spec: {str(e)}",
+                "data": {"chain": ""},
+            }
+
+    def get_health(self) -> dict[str, Any]:
+        """
+        Get network health status using RPC call.
+
+        Returns:
+            dictionary with health information
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            health = self.substrate.rpc_request("system_health", [])
+
+            return {
+                "success": True,
+                "message": "Health status retrieved successfully",
+                "data": health.get("result", {}) if health else {},
+            }
+        except Exception as e:
+            logger.error(f"Failed to get health status: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get health status: {str(e)}",
+                "data": {},
+            }
+
+    def ping(self) -> dict[str, Any]:
+        """
+        Ping the connected node with a lightweight health RPC.
+
+        Returns:
+            dictionary with latency and health details
+        """
+        start_time = time.perf_counter()
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            health_response = self.substrate.rpc_request("system_health", [])
+            latency_ms = (time.perf_counter() - start_time) * 1000
+            health = health_response.get("result", {}) if health_response else {}
+
+            return {
+                "success": True,
+                "message": "Node responded successfully",
+                "data": {
+                    "latency_ms": latency_ms,
+                    "peers": health.get("peers"),
+                    "is_syncing": health.get("isSyncing"),
+                    "should_have_peers": health.get("shouldHavePeers"),
+                },
+            }
+        except Exception as e:
+            latency_ms = (time.perf_counter() - start_time) * 1000
+            logger.error(f"Failed to ping node: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to ping node: {str(e)}",
+                "data": {"latency_ms": latency_ms},
+            }
+
+    def get_sync_state(self) -> dict[str, Any]:
+        """
+        Get synchronization state using RPC call.
+
+        Returns:
+            dictionary with sync state information
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            sync_state = self.substrate.rpc_request("system_syncState", [])
+
+            return {
+                "success": True,
+                "message": "Sync state retrieved successfully",
+                "data": sync_state.get("result", {}) if sync_state else {},
+            }
+        except Exception as e:
+            logger.error(f"Failed to get sync state: {str(e)}")
+            return {
+                "success": False,
+                "message": f"Failed to get sync state: {str(e)}",
+                "data": {},
+            }
+
+    def _percent_mul(self, x: int, y: int) -> int:
+        """
+        Multiply x by percentage y (using 1e18 precision).
+
+        Equivalent to Rust: x * y / PERCENTAGE_FACTOR
+        """
+        PERCENTAGE_FACTOR = 1_000_000_000_000_000_000  # 1e18
+
+        if x == 0 or y == 0:
+            return 0
+
+        # Use integer arithmetic to avoid precision loss
+        result = (x * y) // PERCENTAGE_FACTOR
+        return min(result, 2**127 - 1)  # Clamp to safe u128 range
+
+    def _percent_div(self, x: int, y: int) -> int:
+        """
+        Divide x by y, returning result as percentage (using 1e18 precision).
+
+        Equivalent to Rust: x * PERCENTAGE_FACTOR / y
+        """
+        PERCENTAGE_FACTOR = 1_000_000_000_000_000_000  # 1e18
+
+        if x == 0 or y == 0:
+            return 0
+
+        # Use integer arithmetic to avoid precision loss
+        result = (x * PERCENTAGE_FACTOR) // y
+        return min(result, 2**127 - 1)  # Clamp to safe u128 range
+
+    def _get_percent_as_f64(self, v: int) -> float:
+        """
+        Convert percentage value (1e18 = 100%) to f64.
+
+        Equivalent to Rust: v as f64 / PERCENTAGE_FACTOR
+        """
+        PERCENTAGE_FACTOR = 1_000_000_000_000_000_000  # 1e18
+        return v / PERCENTAGE_FACTOR
+
+    def get_subnet_registration_cost(self) -> Optional[int]:
+        """
+        Get the current subnet registration cost in wei.
+
+        The cost dynamically decreases over time using exponential decay
+        from the last registration until it reaches the minimum cost.
+
+        This queries storage values and calculates the current cost based on:
+        - Last registration cost
+        - Minimum cost
+        - Decay period and rate
+        - Blocks since last registration
+        - Alpha parameter for exponential decay
+
+        Returns:
+            Current registration cost in wei (1e18 = 1 TENSOR) or None if error
+
+        Example:
+            >>> chain_rpc = ChainRpcClient(substrate)
+            >>> cost = chain_rpc.get_subnet_registration_cost()
+            >>> if cost:
+            >>>     print(f"Current cost: {cost / 1e18:.2f} TENSOR")
+        """
+        try:
+            if not self.substrate:
+                raise Exception("Not connected to blockchain")
+
+            # Query storage values with detailed error tracking
+            logger.debug("Querying LastRegistrationCost...")
+            last_cost_result = self.substrate.query(
+                "Network", "LastRegistrationCost", []
+            )
+            logger.debug(f"LastRegistrationCost result: {last_cost_result}")
+
+            logger.debug("Querying MinRegistrationCost...")
+            min_cost_result = self.substrate.query("Network", "MinRegistrationCost", [])
+            logger.debug(f"MinRegistrationCost result: {min_cost_result}")
+
+            logger.debug("Querying LastSubnetRegistrationBlock...")
+            last_block_result = self.substrate.query(
+                "Network", "LastSubnetRegistrationBlock", []
+            )
+            logger.debug(f"LastSubnetRegistrationBlock result: {last_block_result}")
+
+            logger.debug("Querying RegistrationCostDecayBlocks...")
+            decay_blocks_result = self.substrate.query(
+                "Network", "RegistrationCostDecayBlocks", []
+            )
+            logger.debug(f"RegistrationCostDecayBlocks result: {decay_blocks_result}")
+
+            logger.debug("Querying RegistrationCostAlpha...")
+            alpha_result = self.substrate.query("Network", "RegistrationCostAlpha", [])
+            logger.debug(f"RegistrationCostAlpha result: {alpha_result}")
+
+            # Check which values are missing
+            missing = []
+            if not last_cost_result:
+                missing.append("LastRegistrationCost")
+            if not min_cost_result:
+                missing.append("MinRegistrationCost")
+            if not last_block_result:
+                missing.append("LastSubnetRegistrationBlock")
+            if not decay_blocks_result:
+                missing.append("RegistrationCostDecayBlocks")
+            if not alpha_result:
+                missing.append("RegistrationCostAlpha")
+
+            if missing:
+                logger.error(f"Missing storage values: {', '.join(missing)}")
+                logger.error("These storage items may not exist in the Network pallet")
+                return None
+
+            last_cost = (
+                last_cost_result.value
+                if hasattr(last_cost_result, "value")
+                else last_cost_result
+            )
+            min_cost = (
+                min_cost_result.value
+                if hasattr(min_cost_result, "value")
+                else min_cost_result
+            )
+            last_block = (
+                last_block_result.value
+                if hasattr(last_block_result, "value")
+                else last_block_result
+            )
+            decay_blocks = (
+                decay_blocks_result.value
+                if hasattr(decay_blocks_result, "value")
+                else decay_blocks_result
+            )
+            alpha = (
+                alpha_result.value if hasattr(alpha_result, "value") else alpha_result
+            )
+
+            # Get current block
+            current_block = self.get_block_number()
+            if current_block is None:
+                return None
+
+            # Calculate decayed cost using exponential decay (matching blockchain)
+            delta_blocks = current_block - last_block
+
+            # If already at min or no decay period
+            if decay_blocks == 0 or last_cost <= min_cost:
+                cost = max(last_cost, min_cost)
+            elif delta_blocks >= decay_blocks:
+                # Fully decayed: exactly min price
+                cost = min_cost
+            else:
+                # Exponential decay calculation (matching blockchain implementation)
+                diff = last_cost - min_cost
+
+                # Calculate remaining fraction as percentage: (decay_blocks - delta_blocks) / decay_blocks
+                remaining_blocks = decay_blocks - delta_blocks
+                remaining_frac = self._percent_div(remaining_blocks, decay_blocks)
+
+                # Apply concave exponential: remaining_frac ^ alpha
+                # Convert to f64 for pow calculation
+                remaining_frac_f64 = self._get_percent_as_f64(remaining_frac)
+                alpha_f64 = self._get_percent_as_f64(alpha)
+
+                # Calculate concave factor using pow
+                concave_factor = math.pow(remaining_frac_f64, alpha_f64)
+
+                # Calculate addend: diff * concave_factor
+                # Prevent overflow by clamping diff
+                safe_diff_f64 = min(diff, (2**127 - 1) / max(concave_factor, 1e-10))
+                addend = int(safe_diff_f64 * concave_factor)
+                addend = max(0, min(addend, 2**127 - 1))  # Clamp to safe range
+
+                # Final cost: min_price + addend
+                cost = min_cost + addend
+                cost = max(cost, min_cost)  # Ensure cost >= min_cost
+                cost = min(cost, 2**127 - 1)  # Clamp to safe u128 range
+
+            logger.info(
+                f"Subnet registration cost at block {current_block}: {cost / 1e18:.2f} TENSOR"
+            )
+            logger.debug(
+                f"  Last cost: {last_cost / 1e18:.2f}, Min: {min_cost / 1e18:.2f}, "
+                f"Blocks since last: {delta_blocks}/{decay_blocks}, Alpha: {alpha / 1e18:.6f}"
+            )
+
+            return cost
+        except Exception as e:
+            logger.error(f"Failed to get subnet registration cost: {str(e)}")
+            return None