htcli 1.1.0__py3-none-any.whl

src/htcli/models/requests/subnet.py

@@ -0,0 +1,195 @@
+from pydantic import BaseModel, Field, ValidationInfo, field_validator
+
+from src.htcli.models.enums.enum_types import KeyType
+
+
+class SubnetRegisterRequest(BaseModel):
+    """
+    Request model for subnet registration.
+
+    Note: Only fields that are part of RegistrationSubnetData are included here.
+    Other configuration fields (churn_limit, queue_epochs, etc.) are set separately
+    after registration using owner update calls.
+    """
+
+    # Core parameters
+    max_cost: int = Field(
+        ..., description="Maximum cost willing to pay for registration"
+    )
+
+    # Subnet metadata (part of RegistrationSubnetData)
+    name: str = Field(..., description="Unique subnet name", max_length=1024)
+    repo: str = Field(
+        ..., description="Repository URL for subnet code", max_length=1024
+    )
+    description: str = Field(
+        default="", description="Subnet description", max_length=1024
+    )
+    misc: str = Field(
+        default="", description="Miscellaneous information", max_length=1024
+    )
+
+    # Subnet configuration (part of RegistrationSubnetData)
+    min_stake: int = Field(
+        default=100_000_000_000_000_000_000,  # default 100 TENSOR
+        description="Minimum stake balance for subnet nodes (TENSOR)",
+    )
+    max_stake: int = Field(
+        default=1_000_000_000_000_000_000_000,  # default 1000 TENSOR
+        description="Maximum stake balance for subnet nodes (TENSOR)",
+    )
+    delegate_stake_percentage: int = Field(
+        default=100_000_000_000_000_000,  # 10%
+        description="Percentage of emissions allocated to delegate stakers",
+    )
+
+    # Access control (part of RegistrationSubnetData)
+    initial_coldkeys: dict[str, int] = Field(
+        default_factory=dict,
+        description="Initial coldkeys allowed to register (address -> max_registrations). Value must be >= 1.",
+    )
+    initial_validators: dict[int, int] = Field(
+        default_factory=dict,
+        description="Initial validators allowed to register (validator_id -> max_registrations). Value must be >= 1.",
+    )
+    key_types: set[KeyType] = Field(
+        default_factory=lambda: {KeyType.RSA}, description="Supported key types"
+    )
+    bootnodes: set[str] = Field(
+        default_factory=set, description="Bootnode addresses (can be empty)"
+    )
+
+    @field_validator("name")
+    def validate_name(cls, v):
+        if v is None:
+            raise ValueError("Subnet name cannot be None")
+        if not isinstance(v, str) or not v.strip():
+            raise ValueError("Subnet name cannot be empty")
+        return v.strip()
+
+    @field_validator("repo")
+    def validate_repo(cls, v):
+        if v is None:
+            raise ValueError("Repository URL cannot be None")
+        if not isinstance(v, str) or not v.strip():
+            raise ValueError("Repository URL cannot be empty")
+        return v.strip()
+
+    @field_validator("min_stake")
+    def validate_min_stake(cls, v):
+        MIN_TENSOR = 100
+        MIN_WEI = int(MIN_TENSOR * 1e18)  # 100 TENSOR
+
+        if v is None:
+            raise ValueError("min_stake cannot be None")
+        if v < 0:
+            raise ValueError("min_stake cannot be negative")
+        if v < MIN_WEI:
+            raise ValueError(
+                f"min_stake must be at least {MIN_TENSOR} TENSOR (got {v / 1e18:.4f} TENSOR)"
+            )
+        return v
+
+    @field_validator("max_stake")
+    def validate_max_stake(cls, v, info: ValidationInfo):
+        MAX_TENSOR = 1000
+        MAX_WEI = int(MAX_TENSOR * 1e18)  # 1000 TENSOR
+
+        if v is None:
+            raise ValueError("max_stake cannot be None")
+        if v < 0:
+            raise ValueError("max_stake cannot be negative")
+        if v > MAX_WEI:
+            raise ValueError(
+                f"max_stake must be at most {MAX_TENSOR} TENSOR (got {v / 1e18:.4f} TENSOR)"
+            )
+        min_stake = info.data.get("min_stake") if info and info.data else None
+        if min_stake is not None and v < min_stake:
+            raise ValueError(
+                f"max_stake must be greater than or equal to min_stake (min: {min_stake / 1e18:.4f} TENSOR, max: {v / 1e18:.4f} TENSOR)"
+            )
+        return v
+
+    @field_validator("delegate_stake_percentage")
+    def validate_delegate_stake_percentage(cls, v):
+        # Blockchain requirement: MinDelegateStakePercentage (5%) to MaxDelegateStakePercentage (95%)
+        MIN_ALLOWED = 50_000_000_000_000_000  # 5%
+        MAX_ALLOWED = 950_000_000_000_000_000  # 95%
+        if v < MIN_ALLOWED or v > MAX_ALLOWED:
+            raise ValueError(
+                f"delegate_stake_percentage must be between {MIN_ALLOWED / 1e16:.0f}% and {MAX_ALLOWED / 1e16:.0f}%"
+            )
+        return v
+
+    @field_validator("bootnodes")
+    def validate_bootnodes(cls, v):
+        # Bootnodes can be empty, but if provided, must not exceed max
+        if v and len(v) > 32:  # MaxBootnodes::get()
+            raise ValueError("Too many bootnodes (maximum 32)")
+        return v
+
+    @field_validator("initial_coldkeys")
+    def validate_initial_coldkeys(cls, v):
+        # Initial coldkeys can be empty for permissionless subnets
+        # When provided, should have at least 3 for meaningful consensus
+        if v and len(v) > 0 and len(v) < 3:  # MinSubnetNodes::get()
+            raise ValueError(
+                "If providing initial coldkeys, provide at least 3 for meaningful consensus"
+            )
+        # Validate that all max_registrations values are >= 1
+        if v:
+            for address, max_regs in v.items():
+                if max_regs < 1:
+                    raise ValueError(
+                        f"max_registrations for {address} must be >= 1, got {max_regs}"
+                    )
+        return v
+
+    @field_validator("initial_validators")
+    def validate_initial_validators(cls, v):
+        if v:
+            for address, max_regs in v.items():
+                if max_regs < 1:
+                    raise ValueError(
+                        f"max_registrations for {address} must be >= 1, got {max_regs}"
+                    )
+        return v
+
+
+class SubnetActivateRequest(BaseModel):
+    """Request model for subnet activation."""
+
+    subnet_id: int = Field(..., description="Subnet ID to activate")
+
+
+class SubnetRemoveRequest(BaseModel):
+    """Request model for subnet removal."""
+
+    subnet_id: int = Field(..., description="Subnet ID to remove")
+
+
+class SubnetUpdateRequest(BaseModel):
+    """Request model for subnet updates."""
+
+    subnet_id: int = Field(..., description="Subnet ID to update")
+    value: str = Field(..., description="New value")
+
+
+class SubnetConfigUpdateRequest(BaseModel):
+    """Request model for subnet configuration updates."""
+
+    subnet_id: int = Field(..., description="Subnet ID to update")
+    value: int = Field(..., description="New configuration value")
+
+
+class SubnetOwnershipTransferRequest(BaseModel):
+    """Request model for subnet ownership transfer."""
+
+    subnet_id: int = Field(..., description="Subnet ID to transfer")
+    new_owner: str = Field(..., description="New owner account ID")
+
+
+class SubnetOwnershipAcceptRequest(BaseModel):
+    """Request model for accepting subnet ownership."""
+
+    subnet_id: int = Field(..., description="Subnet ID to accept ownership")

src/htcli/models/requests/validator.py

@@ -0,0 +1,139 @@
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from ...utils.blockchain import validate_ethereum_address
+
+MAX_RATE = 10**18
+
+
+def _validate_account_id(value: Optional[str], field_name: str) -> Optional[str]:
+    if value is None:
+        return value
+    if not validate_ethereum_address(value):
+        raise ValueError(f"{field_name} must be a valid Ethereum address")
+    return value
+
+
+class ValidatorRegisterRequest(BaseModel):
+    """Request model for validator registration."""
+
+    hotkey: str = Field(..., description="Validator hotkey account ID")
+    delegate_reward_rate: int = Field(..., description="Delegate reward rate")
+    delegate_account_id: Optional[str] = Field(
+        None, description="Optional delegate account ID"
+    )
+    delegate_account_rate: Optional[int] = Field(
+        None, description="Optional delegate account rate"
+    )
+    identity: Optional[dict[str, Any]] = Field(
+        None, description="Optional validator identity payload"
+    )
+
+    @field_validator("hotkey")
+    @classmethod
+    def validate_hotkey(cls, value: str) -> str:
+        return _validate_account_id(value, "hotkey")
+
+    @field_validator("delegate_account_id")
+    @classmethod
+    def validate_delegate_account_id(cls, value: Optional[str]) -> Optional[str]:
+        return _validate_account_id(value, "delegate_account_id")
+
+    @field_validator("delegate_reward_rate", "delegate_account_rate")
+    @classmethod
+    def validate_rate(cls, value: Optional[int]) -> Optional[int]:
+        if value is None:
+            return value
+        if value < 0 or value > MAX_RATE:
+            raise ValueError("rate must be between 0 and 100, or a 1e18-format value")
+        return value
+
+    @model_validator(mode="after")
+    def validate_delegate_account_pair(self) -> "ValidatorRegisterRequest":
+        if self.delegate_account_rate is not None and self.delegate_account_id is None:
+            raise ValueError(
+                "delegate_account_id is required when delegate_account_rate is set"
+            )
+        return self
+
+
+class ValidatorDelegateRewardRateUpdateRequest(BaseModel):
+    """Request model for updating validator delegate reward rate."""
+
+    validator_id: int = Field(..., ge=0, description="Validator ID to update")
+    new_delegate_reward_rate: int = Field(..., description="New delegate reward rate")
+
+    @field_validator("new_delegate_reward_rate")
+    @classmethod
+    def validate_rate(cls, value: int) -> int:
+        if value < 0 or value > MAX_RATE:
+            raise ValueError("rate must be between 0 and 100, or a 1e18-format value")
+        return value
+
+
+class ValidatorDelegateAccountUpdateRequest(BaseModel):
+    """Request model for updating validator delegate account."""
+
+    validator_id: int = Field(..., ge=0, description="Validator ID to update")
+    delegate_account_id: Optional[str] = Field(
+        None, description="Optional delegate account ID"
+    )
+    delegate_rate: Optional[int] = Field(
+        None, description="Optional delegate account rate"
+    )
+
+    @field_validator("delegate_account_id")
+    @classmethod
+    def validate_delegate_account_id(cls, value: Optional[str]) -> Optional[str]:
+        return _validate_account_id(value, "delegate_account_id")
+
+    @field_validator("delegate_rate")
+    @classmethod
+    def validate_delegate_rate(cls, value: Optional[int]) -> Optional[int]:
+        if value is None:
+            return value
+        if value < 0 or value > MAX_RATE:
+            raise ValueError("rate must be between 0 and 100, or a 1e18-format value")
+        return value
+
+    @model_validator(mode="after")
+    def validate_delegate_account_pair(self) -> "ValidatorDelegateAccountUpdateRequest":
+        if self.delegate_rate is not None and self.delegate_account_id is None:
+            raise ValueError(
+                "delegate_account_id is required when delegate_rate is set"
+            )
+        return self
+
+
+class ValidatorHotkeyUpdateRequest(BaseModel):
+    """Request model for updating validator hotkey."""
+
+    validator_id: int = Field(..., ge=0, description="Validator ID to update")
+    new_hotkey: str = Field(..., description="New validator hotkey")
+
+    @field_validator("new_hotkey")
+    @classmethod
+    def validate_new_hotkey(cls, value: str) -> str:
+        return _validate_account_id(value, "new_hotkey")
+
+
+class ValidatorColdkeyUpdateRequest(BaseModel):
+    """Request model for updating validator coldkey."""
+
+    validator_id: int = Field(..., ge=0, description="Validator ID to update")
+    new_coldkey: str = Field(..., description="New validator coldkey")
+
+    @field_validator("new_coldkey")
+    @classmethod
+    def validate_new_coldkey(cls, value: str) -> str:
+        return _validate_account_id(value, "new_coldkey")
+
+
+class ValidatorIdentityUpdateRequest(BaseModel):
+    """Request model for updating validator identity."""
+
+    validator_id: int = Field(..., ge=0, description="Validator ID to update")
+    identity: Optional[dict[str, Any]] = Field(
+        None, description="Optional validator identity payload"
+    )

src/htcli/models/requests/wallet.py

@@ -0,0 +1,118 @@
+"""
+Wallet-related request models.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class WalletCreateRequest(BaseModel):
+    """Request model for wallet creation."""
+
+    name: str = Field(..., description="Wallet name")
+    key_type: str = Field(
+        default="ecdsa", description="Key type (ecdsa/sr25519/ed25519)"
+    )
+    wallet_type: str = Field(
+        default="coldkey", description="Wallet type (coldkey/hotkey)"
+    )
+    owner_address: Optional[str] = Field(None, description="Owner address for hotkeys")
+    password: Optional[str] = Field(None, description="Wallet password")
+
+    @field_validator("key_type")
+    def validate_key_type(cls, v):
+        if v not in ["ecdsa", "sr25519", "ed25519"]:
+            raise ValueError("Key type must be ecdsa, sr25519, or ed25519")
+        return v
+
+    @field_validator("wallet_type")
+    def validate_wallet_type(cls, v):
+        if v not in ["coldkey", "hotkey"]:
+            raise ValueError("Wallet type must be coldkey or hotkey")
+        return v
+
+
+class WalletRestoreRequest(BaseModel):
+    """Request model for wallet restoration."""
+
+    name: str = Field(..., description="Wallet name")
+    private_key: Optional[str] = Field(None, description="Private key (hex)")
+    mnemonic: Optional[str] = Field(None, description="Mnemonic phrase")
+    key_type: str = Field(default="ecdsa", description="Key type")
+    wallet_type: str = Field(default="coldkey", description="Wallet type")
+    owner_address: Optional[str] = Field(None, description="Owner address for hotkeys")
+    password: Optional[str] = Field(None, description="Wallet password")
+
+    @field_validator("private_key")
+    def validate_private_key(cls, v):
+        if v and (len(v) != 64 or not all(c in "0123456789abcdefABCDEF" for c in v)):
+            raise ValueError("Private key must be 64 character hex string")
+        return v
+
+    @field_validator("mnemonic")
+    def validate_mnemonic(cls, v):
+        if v and len(v.split()) not in [12, 15, 18, 21, 24]:
+            raise ValueError("Mnemonic must be 12, 15, 18, 21, or 24 words")
+        return v
+
+
+class WalletUpdateRequest(BaseModel):
+    """Request model for wallet updates."""
+
+    current_name: str = Field(..., description="Current wallet name")
+    new_name: Optional[str] = Field(None, description="New wallet name")
+    new_password: Optional[str] = Field(None, description="New password")
+    remove_password: bool = Field(False, description="Remove password protection")
+    current_password: Optional[str] = Field(
+        None, description="Current password (required when changing/removing password)"
+    )
+    new_owner: Optional[str] = Field(
+        None, description="New owner coldkey name (for hotkeys only)"
+    )
+    owner_name: Optional[str] = Field(
+        None,
+        description="Current owner coldkey name (for hotkeys only, required to identify the hotkey)",
+    )
+
+
+class WalletDeleteRequest(BaseModel):
+    """Request model for wallet deletion."""
+
+    names: list[str] = Field(..., description="Wallet names to delete")
+    force: bool = Field(False, description="Skip confirmation")
+    deletion_plan: Optional[dict] = Field(None, description="Detailed deletion plan")
+    wallet_owners: Optional[dict[str, Optional[str]]] = Field(
+        None,
+        description="Mapping of wallet name to owner_address for disambiguation (hotkeys only)",
+    )
+    wallet_owner_context: Optional[
+        dict[str, dict[str, Optional[str]]]
+    ] = Field(
+        None,
+        description="Mapping of wallet name to extra context (address/coldkey) used during deletion",
+    )
+
+
+class WalletTransferRequest(BaseModel):
+    """Request model for wallet transfers."""
+
+    from_wallet: str = Field(..., description="Source wallet name")
+    to_address: str = Field(..., description="Destination address")
+    amount: float = Field(..., description="Transfer amount")
+    unit: str = Field(default="TENSOR", description="Amount unit")
+
+
+class WalletBalanceRequest(BaseModel):
+    """Request model for wallet balance queries."""
+
+    wallet_name: Optional[str] = Field(None, description="Wallet name")
+    address: Optional[str] = Field(None, description="Wallet address")
+
+
+class PreseededWalletRequest(BaseModel):
+    """Request model for preseeded wallet operations."""
+
+    wallet_name: str = Field(..., description="Wallet name")
+    operation: str = Field(..., description="Operation type")
+    data: Optional[str] = Field(None, description="Operation data")

src/htcli/models/responses/__init__.py

@@ -0,0 +1,147 @@
+"""
+Response models for HTCLI.
+"""
+
+# Base response
+from .base import BaseResponse
+
+# Chain-related responses
+from .chain import BalanceResponse, EpochInfoResponse, NetworkStatsResponse
+
+# Config-related responses
+from .config import (
+    ConfigGetResponse,
+    ConfigInitResponse,
+    ConfigPathResponse,
+    ConfigSetResponse,
+    ConfigShowResponse,
+    ConfigValidateResponse,
+)
+
+# Identity-related responses
+from .identity import (
+    IdentityAcceptResponse,
+    IdentityInfo,
+    IdentityRegisterResponse,
+    IdentityRemoveResponse,
+)
+
+# Overwatch-related responses
+from .overwatch import OverwatchNodeInfo
+
+# Subnet-related responses
+from .subnet import (
+    AllSubnetBootnodes,
+    BootnodesResponse,
+    ColdkeyStakesResponse,
+    ColdkeySubnetNodesResponse,
+    DelegateStakeIncreaseResponse,
+    DelegateStakeInfo,
+    DelegateStakesResponse,
+    NodeDelegateStakeInfo,
+    NodeDelegateStakesResponse,
+    NodeStakeInfo,
+    OverwatchCommitInfo,
+    OverwatchCommitsResponse,
+    OverwatchRevealInfo,
+    OverwatchRevealsResponse,
+    ProofOfStakeResponse,
+    StakeInfo,
+    SubnetData,
+    SubnetInfo,
+    SubnetInfoResponse,
+    SubnetNodeInfo,
+    SubnetNodeInfoResponse,
+    SubnetNodeStakeInfo,
+    SubnetOwnershipTransferResponse,
+    SubnetOwnerUpdateResponse,
+    SubnetPauseResponse,
+    SubnetRegisterResponse,
+    SubnetUnpauseResponse,
+    ValidatorStakesResponse,
+    ValidatorSubnetNodesResponse,
+)
+
+# Wallet-related responses
+from .wallet import (
+    DelegateStakeAddResponse,
+    DelegateStakeRemoveResponse,
+    StakeAddResponse,
+    StakeInfoResponse,
+    StakeRemoveResponse,
+    UnbondingClaimResponse,
+    WalletBalanceResponse,
+    WalletCreateResponse,
+    WalletDeleteResponse,
+    WalletListResponse,
+    WalletStatusResponse,
+    WalletTransferResponse,
+    WalletUpdateResponse,
+)
+
+__all__ = [
+    # Base response
+    "BaseResponse",
+    # Chain responses
+    "BalanceResponse",
+    "EpochInfoResponse",
+    "NetworkStatsResponse",
+    # Overwatch responses
+    "OverwatchNodeInfo",
+    # Identity responses
+    "IdentityInfo",
+    "IdentityRegisterResponse",
+    "IdentityAcceptResponse",
+    "IdentityRemoveResponse",
+    # Wallet responses
+    "WalletCreateResponse",
+    "WalletListResponse",
+    "WalletStatusResponse",
+    "WalletBalanceResponse",
+    "WalletTransferResponse",
+    "WalletUpdateResponse",
+    "WalletDeleteResponse",
+    "DelegateStakeAddResponse",
+    "DelegateStakeRemoveResponse",
+    "StakeAddResponse",
+    "StakeInfoResponse",
+    "StakeRemoveResponse",
+    "UnbondingClaimResponse",
+    # Subnet responses
+    "AllSubnetBootnodes",
+    "BootnodesResponse",
+    "ColdkeyStakesResponse",
+    "ColdkeySubnetNodesResponse",
+    "DelegateStakeIncreaseResponse",
+    "DelegateStakeInfo",
+    "DelegateStakesResponse",
+    "NodeDelegateStakeInfo",
+    "NodeDelegateStakesResponse",
+    "NodeStakeInfo",
+    "OverwatchCommitInfo",
+    "OverwatchCommitsResponse",
+    "OverwatchRevealInfo",
+    "OverwatchRevealsResponse",
+    "ProofOfStakeResponse",
+    "SubnetData",
+    "SubnetInfo",
+    "SubnetInfoResponse",
+    "SubnetNodeInfo",
+    "SubnetNodeInfoResponse",
+    "SubnetNodeStakeInfo",
+    "SubnetOwnershipTransferResponse",
+    "SubnetOwnerUpdateResponse",
+    "SubnetPauseResponse",
+    "SubnetRegisterResponse",
+    "SubnetUnpauseResponse",
+    "ValidatorStakesResponse",
+    "ValidatorSubnetNodesResponse",
+    "StakeInfo",
+    # Config responses
+    "ConfigGetResponse",
+    "ConfigInitResponse",
+    "ConfigPathResponse",
+    "ConfigSetResponse",
+    "ConfigShowResponse",
+    "ConfigValidateResponse",
+]

src/htcli/models/responses/base.py

@@ -0,0 +1,18 @@
+"""
+Base response models.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class BaseResponse(BaseModel):
+    """Base response model."""
+
+    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 for the transaction")
+    error: Optional[str] = Field(None, description="Error message if operation failed")
+    block_number: Optional[int] = Field(None, description="Block number of transaction")
+    epoch: Optional[int] = Field(None, description="Epoch of transaction")

src/htcli/models/responses/chain.py

@@ -0,0 +1,39 @@
+"""
+Chain-related response models.
+"""
+
+from typing import Optional
+
+from pydantic import Field
+
+from .base import BaseResponse
+
+
+class NetworkStatsResponse(BaseResponse):
+    """Response for network statistics."""
+
+    total_subnets: Optional[int] = Field(None, description="Total number of subnets")
+    total_nodes: Optional[int] = Field(None, description="Total number of nodes")
+    total_stake: Optional[int] = Field(None, description="Total network stake")
+    current_epoch: Optional[int] = Field(None, description="Current epoch")
+    network_load: Optional[float] = Field(None, description="Network load percentage")
+
+
+class EpochInfoResponse(BaseResponse):
+    """Response for epoch information."""
+
+    current_epoch: Optional[int] = Field(None, description="Current epoch number")
+    epoch_start: Optional[int] = Field(None, description="Epoch start block")
+    epoch_end: Optional[int] = Field(None, description="Epoch end block")
+    blocks_per_epoch: Optional[int] = Field(None, description="Blocks per epoch")
+    epoch_duration: Optional[int] = Field(None, description="Epoch duration in seconds")
+
+
+class BalanceResponse(BaseResponse):
+    """Response for balance information."""
+
+    address: Optional[str] = Field(None, description="Account address")
+    balance: Optional[int] = Field(None, description="Account balance")
+    locked_balance: Optional[int] = Field(None, description="Locked balance")
+    available_balance: Optional[int] = Field(None, description="Available balance")
+    reserved_balance: Optional[int] = Field(None, description="Reserved balance")