communex.types

  1"""
  2Common types for the communex module.
  3"""
  4
  5from typing import NewType, TypedDict
  6from enum import Enum
  7
  8Ss58Address = NewType("Ss58Address", str)
  9"""Substrate SS58 address.
 10
 11The `SS58 encoded address format`_ is based on the Bitcoin Base58Check format,
 12but with a few modification specifically designed to suite Substrate-based
 13chains.
 14
 15.. _SS58 encoded address format:
 16    https://docs.substrate.io/reference/address-formats/
 17"""
 18
 19
 20# TODO: replace with dataclasses
 21
 22# == Burn related
 23MinBurn = NewType("MinBurn", int)
 24MaxBurn = NewType("MaxBurn", int)
 25BurnConfig = NewType("BurnConfig", dict[MinBurn, MaxBurn])
 26
 27class VoteMode (Enum):
 28    authority = "0"
 29    vote = "1"
 30
 31
 32class GovernanceConfiguration(TypedDict):
 33    proposal_cost: int
 34    proposal_expiration: int
 35    vote_mode: int # 0: Authority, 1: Vote
 36    proposal_reward_treasury_allocation: float
 37    max_proposal_reward_treasury_allocation: int
 38    proposal_reward_interval: int
 39
 40
 41
 42class NetworkParams(TypedDict):
 43    # max
 44    max_name_length: int
 45    min_name_length: int # dont change the position
 46    max_allowed_subnets: int
 47    max_allowed_modules: int
 48    max_registrations_per_block: int
 49    max_allowed_weights: int
 50
 51    # mins
 52    floor_delegation_fee: int
 53    floor_founder_share: int
 54    min_weight_stake: int
 55
 56    # S0 governance
 57    curator: Ss58Address
 58    general_subnet_application_cost: int
 59
 60    # Other
 61    subnet_immunity_period: int
 62    min_burn: int
 63    max_burn: int
 64    governance_config: GovernanceConfiguration
 65
 66    kappa: int
 67    rho: int
 68
 69
 70class SubnetParamsMaps(TypedDict):
 71    netuid_to_founder: dict[int, Ss58Address]
 72    netuid_to_founder_share: dict[int, int]
 73    netuid_to_incentive_ratio: dict[int, int]
 74    netuid_to_max_allowed_uids: dict[int, int]
 75    netuid_to_max_allowed_weights: dict[int, int]
 76    netuid_to_min_allowed_weights: dict[int, int]
 77    netuid_to_max_weight_age: dict[int, int]
 78    netuid_to_name: dict[int, str]
 79    netuid_to_tempo: dict[int, int]
 80    netuid_to_trust_ratio: dict[int, int]
 81    netuid_to_bonds_ma: dict[int, int]
 82    netuid_to_maximum_set_weight_calls_per_epoch: dict[int, int]
 83    netuid_to_target_registrations_per_interval: dict[int, int]
 84    netuid_to_target_registrations_interval: dict[int, int]
 85    netuid_to_emission: dict[int, int]
 86    netuid_to_max_registrations_per_interval: dict[int, int]
 87    netuid_to_adjustment_alpha: dict[int, int]
 88    netuid_to_min_immunity_stake: dict[int, int]
 89    netuid_to_immunity_period: dict[int, int]
 90    netuid_to_governance_configuration: dict[int, GovernanceConfiguration]
 91
 92
 93class SubnetParams(TypedDict):
 94    name: str
 95    tempo: int
 96    min_allowed_weights: int
 97    max_allowed_weights: int
 98    max_allowed_uids: int
 99    max_weight_age: int
100    trust_ratio: int
101    founder_share: int
102    incentive_ratio: int
103    founder: Ss58Address
104    maximum_set_weight_calls_per_epoch: int | None
105    bonds_ma: int | None
106    target_registrations_interval: int
107    target_registrations_per_interval: int
108    max_registrations_per_interval: int
109    adjustment_alpha: int
110    min_immunity_stake: int
111    immunity_period: int
112    governance_config: GovernanceConfiguration
113
114
115# redundant "TypedDict" inheritance because of pdoc warns.
116# see https://github.com/mitmproxy/pdoc/blob/26d40827ddbe1658e8ac46cd092f17a44cf0287b/pdoc/doc.py#L691-L692
117class SubnetParamsWithEmission(SubnetParams, TypedDict):
118    """SubnetParams with emission field."""
119
120    emission: int
121    """Subnet emission percentage (0-100).
122    """
123
124
125class ModuleInfo(TypedDict):
126    uid: int
127    key: Ss58Address
128    name: str
129    address: str  # "<ip>:<port>"
130    emission: int
131    incentive: int
132    dividends: int
133    stake_from: list[tuple[str, int]]  # TODO: type key with Ss58Address
134    regblock: int  # block number
135    last_update: int  # block number
136    stake: int
137    delegation_fee: int
138    metadata: str
139
140
141class ModuleInfoWithBalance(ModuleInfo):
142    balance: int
143
144
145class ModuleInfoWithOptionalBalance(ModuleInfo):
146    balance: int | None