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
 95class SubnetParamsMaps(TypedDict):
 96    netuid_to_founder: dict[int, Ss58Address]
 97    netuid_to_founder_share: dict[int, int]
 98    netuid_to_incentive_ratio: dict[int, int]
 99    netuid_to_max_allowed_uids: dict[int, int]
100    netuid_to_max_allowed_weights: dict[int, int]
101    netuid_to_min_allowed_weights: dict[int, int]
102    netuid_to_max_weight_age: dict[int, int]
103    netuid_to_name: dict[int, str]
104    netuid_to_tempo: dict[int, int]
105    netuid_to_trust_ratio: dict[int, int]
106    netuid_to_bonds_ma: dict[int, int]
107    netuid_to_maximum_set_weight_calls_per_epoch: dict[int, int]
108    netuid_to_emission: dict[int, int]
109    netuid_to_immunity_period: dict[int, int]
110    netuid_to_governance_configuration: dict[int, GovernanceConfiguration]
111    netuid_to_min_validator_stake: dict[int, int]
112    netuid_to_max_allowed_validators: dict[int, int]
113    netuid_to_module_burn_config: dict[int, BurnConfiguration]
114    netuid_to_subnet_metadata: dict[int, str]
115
116
117class SubnetParams(TypedDict):
118    name: str
119    tempo: int
120    min_allowed_weights: int
121    max_allowed_weights: int
122    max_allowed_uids: int
123    max_weight_age: int
124    trust_ratio: int
125    founder_share: int
126    incentive_ratio: int
127    founder: Ss58Address
128    maximum_set_weight_calls_per_epoch: int | None
129    bonds_ma: int | None
130    immunity_period: int
131    governance_config: GovernanceConfiguration
132    min_validator_stake: int | None
133    max_allowed_validators: int | None
134    module_burn_config: BurnConfiguration
135    subnet_metadata: str | None
136
137
138class DisplaySubnetParams(TypedDict):
139    name: str
140    tempo: int
141    min_allowed_weights: int
142    max_allowed_weights: int
143    max_allowed_uids: int
144    max_weight_age: int
145    trust_ratio: int
146    founder_share: int
147    incentive_ratio: int
148    founder: Ss58Address
149    maximum_set_weight_calls_per_epoch: int | None
150    bonds_ma: int
151    immunity_period: int
152    governance_config: DisplayGovernanceConfiguration
153    min_validator_stake: float
154    max_allowed_validators: int | None
155    module_burn_config: DisplayBurnConfiguration
156    subnet_metadata: str | None
157    emission: float
158
159# redundant "TypedDict" inheritance because of pdoc warns.
160# see https://github.com/mitmproxy/pdoc/blob/26d40827ddbe1658e8ac46cd092f17a44cf0287b/pdoc/doc.py#L691-L692
161class SubnetParamsWithEmission(SubnetParams, TypedDict):
162    """SubnetParams with emission field."""
163
164    emission: int
165    """Subnet emission percentage (0-100).
166    """
167
168
169class ModuleInfo(TypedDict):
170    uid: int
171    key: Ss58Address
172    name: str
173    address: str  # "<ip>:<port>"
174    emission: int
175    incentive: int
176    dividends: int
177    stake_from: list[tuple[Ss58Address, int]]
178    regblock: int  # block number
179    last_update: int  # block number
180    stake: int
181    delegation_fee: int
182    metadata: str | None
183
184
185class ModuleInfoWithBalance(ModuleInfo):
186    balance: int
187
188
189class ModuleInfoWithOptionalBalance(ModuleInfo):
190    balance: int | None