communex.types

  1"""
  2Common types for the communex module.
  3"""
  4
  5from enum import Enum
  6from typing import NewType, TypedDict
  7
  8from pydantic import BaseModel
  9
 10Ss58Address = NewType("Ss58Address", str)
 11"""Substrate SS58 address.
 12
 13The `SS58 encoded address format`_ is based on the Bitcoin Base58Check format,
 14but with a few modification specifically designed to suite Substrate-based
 15chains.
 16
 17.. _SS58 encoded address format:
 18    https://docs.substrate.io/reference/address-formats/
 19"""
 20
 21
 22# TODO: replace with dataclasses
 23
 24# == Burn related
 25MinBurn = NewType("MinBurn", int)
 26MaxBurn = NewType("MaxBurn", int)
 27BurnConfig = NewType("BurnConfig", dict[MinBurn, MaxBurn])
 28
 29
 30class VoteMode(Enum):
 31    authority = "Authority"
 32    vote = "Vote"
 33
 34
 35class subnetDecryptionInfo(BaseModel):
 36    node_id: Ss58Address
 37    node_public_key: bytes
 38    block_assigned: int
 39
 40
 41class DisplayGovernanceConfiguration(TypedDict):
 42    proposal_cost: float
 43    proposal_expiration: float
 44    vote_mode: VoteMode
 45    proposal_reward_treasury_allocation: float
 46    max_proposal_reward_treasury_allocation: float
 47    proposal_reward_interval: int
 48
 49
 50class GovernanceConfiguration(TypedDict):
 51    proposal_cost: int
 52    proposal_expiration: int
 53    vote_mode: int  # 0: Authority, 1: Vote
 54    proposal_reward_treasury_allocation: float
 55    max_proposal_reward_treasury_allocation: int
 56    proposal_reward_interval: int
 57
 58
 59class DisplayBurnConfiguration(TypedDict):
 60    min_burn: float
 61    max_burn: float
 62    adjustment_alpha: int
 63    target_registrations_interval: int
 64    target_registrations_per_interval: int
 65    max_registrations_per_interval: int
 66
 67
 68class BurnConfiguration(TypedDict):
 69    min_burn: int
 70    max_burn: int
 71    adjustment_alpha: int
 72    target_registrations_interval: int
 73    target_registrations_per_interval: int
 74    max_registrations_per_interval: int
 75
 76
 77class NetworkParams(TypedDict):
 78    # max
 79    max_name_length: int
 80    min_name_length: int  # dont change the position
 81    max_allowed_subnets: int
 82    max_allowed_modules: int
 83    max_registrations_per_block: int
 84    max_allowed_weights: int
 85
 86    # mins
 87    floor_delegation_fee: int
 88    floor_founder_share: int
 89    min_weight_stake: int
 90
 91    # S0 governance
 92    curator: Ss58Address
 93    general_subnet_application_cost: int
 94
 95    # Other
 96    subnet_immunity_period: int
 97    governance_config: GovernanceConfiguration
 98
 99    kappa: int
100    rho: int
101
102    subnet_registration_cost: int
103
104
105class SubnetParamsMaps(TypedDict):
106    netuid_to_founder: dict[int, Ss58Address]
107    netuid_to_founder_share: dict[int, int]
108    netuid_to_incentive_ratio: dict[int, int]
109    netuid_to_max_allowed_uids: dict[int, int]
110    netuid_to_max_allowed_weights: dict[int, int]
111    netuid_to_min_allowed_weights: dict[int, int]
112    netuid_to_max_weight_age: dict[int, int]
113    netuid_to_name: dict[int, str]
114    netuid_to_tempo: dict[int, int]
115    netuid_to_bonds_ma: dict[int, int]
116    netuid_to_maximum_set_weight_calls_per_epoch: dict[int, int]
117    netuid_to_emission: dict[int, int]
118    netuid_to_immunity_period: dict[int, int]
119    netuid_to_governance_configuration: dict[int, GovernanceConfiguration]
120    netuid_to_min_validator_stake: dict[int, int]
121    netuid_to_max_allowed_validators: dict[int, int]
122    netuid_to_module_burn_config: dict[int, BurnConfiguration]
123    netuid_to_subnet_metadata: dict[int, str]
124    netuid_to_max_encryption_period: dict[int, int]
125    netuid_to_copier_margin: dict[int, int]
126    netuid_to_use_weights_encryption: dict[int, int]
127
128
129# WIP
130class UpdatableSubnetParams(TypedDict):
131    tempo: int
132
133
134class SubnetParams(UpdatableSubnetParams, TypedDict):
135    name: str
136    min_allowed_weights: int
137    max_allowed_weights: int
138    max_allowed_uids: int
139    max_weight_age: int
140    founder_share: int
141    incentive_ratio: int
142    founder: Ss58Address
143    maximum_set_weight_calls_per_epoch: int | None
144    bonds_ma: int | None
145    immunity_period: int
146    governance_config: GovernanceConfiguration
147    min_validator_stake: int | None
148    max_allowed_validators: int | None
149    module_burn_config: BurnConfiguration
150    subnet_metadata: str | None
151    max_encryption_period: int
152    copier_margin: int
153    use_weights_encryption: int
154
155
156class DisplaySubnetParams(TypedDict):
157    name: str
158    tempo: int
159    min_allowed_weights: int
160    max_allowed_weights: int
161    max_allowed_uids: int
162    max_weight_age: int
163    trust_ratio: int
164    founder_share: int
165    incentive_ratio: int
166    founder: Ss58Address
167    maximum_set_weight_calls_per_epoch: int | None
168    bonds_ma: int
169    immunity_period: int
170    governance_config: DisplayGovernanceConfiguration
171    min_validator_stake: float
172    max_allowed_validators: int | None
173    module_burn_config: DisplayBurnConfiguration
174    subnet_metadata: str | None
175    emission: float
176    max_encryption_period: int
177    copier_margin: int
178    use_weights_encryption: int
179
180
181# redundant "TypedDict" inheritance because of pdoc warns.
182# see https://github.com/mitmproxy/pdoc/blob/26d40827ddbe1658e8ac46cd092f17a44cf0287b/pdoc/doc.py#L691-L692
183
184
185class SubnetParamsWithEmission(SubnetParams, TypedDict):
186    """SubnetParams with emission field."""
187
188    emission: int
189    """Subnet emission percentage (0-100).
190    """
191
192
193class ModuleInfo(TypedDict):
194    uid: int
195    key: Ss58Address
196    name: str
197    address: str  # "<ip>:<port>"
198    emission: int
199    incentive: int
200    dividends: int
201    stake_from: list[tuple[Ss58Address, int]]
202    regblock: int  # block number
203    last_update: int  # block number
204    stake: int
205    stake_delegation_fee: int
206    validator_weight_fee: int
207    metadata: str | None
208
209
210class ModuleInfoWithBalance(ModuleInfo):
211    balance: int
212
213
214class ModuleInfoWithOptionalBalance(ModuleInfo):
215    balance: int | None