communex.types

  1"""
  2Common types for the communex module.
  3"""
  4
  5from enum import Enum
  6from typing import NewType, TypedDict
  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
 27
 28class VoteMode (Enum):
 29    authority = "Authority"
 30    vote = "Vote"
 31
 32
 33class DisplayGovernanceConfiguration(TypedDict):
 34    proposal_cost: float
 35    proposal_expiration: float
 36    vote_mode: VoteMode
 37    proposal_reward_treasury_allocation: float
 38    max_proposal_reward_treasury_allocation: float
 39    proposal_reward_interval: int
 40
 41
 42class GovernanceConfiguration(TypedDict):
 43    proposal_cost: int
 44    proposal_expiration: int
 45    vote_mode: int  # 0: Authority, 1: Vote
 46    proposal_reward_treasury_allocation: float
 47    max_proposal_reward_treasury_allocation: int
 48    proposal_reward_interval: int
 49
 50
 51class DisplayBurnConfiguration(TypedDict):
 52    min_burn: float
 53    max_burn: float
 54    adjustment_alpha: int
 55    target_registrations_interval: int
 56    target_registrations_per_interval: int
 57    max_registrations_per_interval: int
 58
 59
 60class BurnConfiguration(TypedDict):
 61    min_burn: int
 62    max_burn: int
 63    adjustment_alpha: int
 64    target_registrations_interval: int
 65    target_registrations_per_interval: int
 66    max_registrations_per_interval: int
 67
 68
 69class NetworkParams(TypedDict):
 70    # max
 71    max_name_length: int
 72    min_name_length: int  # dont change the position
 73    max_allowed_subnets: int
 74    max_allowed_modules: int
 75    max_registrations_per_block: int
 76    max_allowed_weights: int
 77
 78    # mins
 79    floor_delegation_fee: int
 80    floor_founder_share: int
 81    min_weight_stake: int
 82
 83    # S0 governance
 84    curator: Ss58Address
 85    general_subnet_application_cost: int
 86
 87    # Other
 88    subnet_immunity_period: int
 89    governance_config: GovernanceConfiguration
 90
 91    kappa: int
 92    rho: int
 93
 94    subnet_registration_cost: int
 95
 96
 97class SubnetParamsMaps(TypedDict):
 98    netuid_to_founder: dict[int, Ss58Address]
 99    netuid_to_founder_share: dict[int, int]
100    netuid_to_incentive_ratio: dict[int, int]
101    netuid_to_max_allowed_uids: dict[int, int]
102    netuid_to_max_allowed_weights: dict[int, int]
103    netuid_to_min_allowed_weights: dict[int, int]
104    netuid_to_max_weight_age: dict[int, int]
105    netuid_to_name: dict[int, str]
106    netuid_to_tempo: dict[int, int]
107    netuid_to_trust_ratio: dict[int, int]
108    netuid_to_bonds_ma: dict[int, int]
109    netuid_to_maximum_set_weight_calls_per_epoch: dict[int, int]
110    netuid_to_emission: dict[int, int]
111    netuid_to_immunity_period: dict[int, int]
112    netuid_to_governance_configuration: dict[int, GovernanceConfiguration]
113    netuid_to_min_validator_stake: dict[int, int]
114    netuid_to_max_allowed_validators: dict[int, int]
115    netuid_to_module_burn_config: dict[int, BurnConfiguration]
116    netuid_to_subnet_metadata: dict[int, str]
117
118class SubnetParams(TypedDict):
119    name: str
120    tempo: int
121    min_allowed_weights: int
122    max_allowed_weights: int
123    max_allowed_uids: int
124    max_weight_age: int
125    trust_ratio: int
126    founder_share: int
127    incentive_ratio: int
128    founder: Ss58Address
129    maximum_set_weight_calls_per_epoch: int | None
130    bonds_ma: int | None
131    immunity_period: int
132    governance_config: GovernanceConfiguration
133    min_validator_stake: int | None
134    max_allowed_validators: int | None
135    module_burn_config: BurnConfiguration
136    subnet_metadata: str | None
137
138
139class DisplaySubnetParams(TypedDict):
140    name: str
141    tempo: int
142    min_allowed_weights: int
143    max_allowed_weights: int
144    max_allowed_uids: int
145    max_weight_age: int
146    trust_ratio: int
147    founder_share: int
148    incentive_ratio: int
149    founder: Ss58Address
150    maximum_set_weight_calls_per_epoch: int | None
151    bonds_ma: int
152    immunity_period: int
153    governance_config: DisplayGovernanceConfiguration
154    min_validator_stake: float
155    max_allowed_validators: int | None
156    module_burn_config: DisplayBurnConfiguration
157    subnet_metadata: str | None
158    emission: float
159
160# redundant "TypedDict" inheritance because of pdoc warns.
161# see https://github.com/mitmproxy/pdoc/blob/26d40827ddbe1658e8ac46cd092f17a44cf0287b/pdoc/doc.py#L691-L692
162class SubnetParamsWithEmission(SubnetParams, TypedDict):
163    """SubnetParams with emission field."""
164
165    emission: int
166    """Subnet emission percentage (0-100).
167    """
168
169
170class ModuleInfo(TypedDict):
171    uid: int
172    key: Ss58Address
173    name: str
174    address: str  # "<ip>:<port>"
175    emission: int
176    incentive: int
177    dividends: int
178    stake_from: list[tuple[Ss58Address, int]]
179    regblock: int  # block number
180    last_update: int  # block number
181    stake: int
182    delegation_fee: int
183    metadata: str | None
184
185
186class ModuleInfoWithBalance(ModuleInfo):
187    balance: int
188
189
190class ModuleInfoWithOptionalBalance(ModuleInfo):
191    balance: int | None