bittensor.core.subtensor

Contents

bittensor.core.subtensor#

The bittensor.core.subtensor.Subtensor module in Bittensor serves as a crucial interface for interacting with the Bittensor blockchain, facilitating a range of operations essential for the decentralized machine learning network.

Attributes#

KEY_NONCE

Classes#

ParamWithTypes

dict() -> new empty dictionary

Subtensor

The Subtensor class in Bittensor serves as a crucial interface for interacting with the Bittensor blockchain,

Module Contents#

bittensor.core.subtensor.KEY_NONCE: dict[str, int]#
class bittensor.core.subtensor.ParamWithTypes#

Bases: TypedDict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

Initialize self. See help(type(self)) for accurate signature.

name: str#
type: str#
class bittensor.core.subtensor.Subtensor(network=None, config=None, _mock=False, log_verbose=False, connection_timeout=600)#

The Subtensor class in Bittensor serves as a crucial interface for interacting with the Bittensor blockchain, facilitating a range of operations essential for the decentralized machine learning network.

This class enables neurons (network participants) to engage in activities such as registering on the network, managing staked weights, setting inter-neuronal weights, and participating in consensus mechanisms.

The Bittensor network operates on a digital ledger where each neuron holds stakes (S) and learns a set of inter-peer weights (W). These weights, set by the neurons themselves, play a critical role in determining the ranking and incentive mechanisms within the network. Higher-ranked neurons, as determined by their contributions and trust within the network, receive more incentives.

The Subtensor class connects to various Bittensor networks like the main finney network or local test networks, providing a gateway to the blockchain layer of Bittensor. It leverages a staked weighted trust system and consensus to ensure fair and distributed incentive mechanisms, where incentives (I) are primarily allocated to neurons that are trusted by the majority of the network.

Additionally, Bittensor introduces a speculation-based reward mechanism in the form of bonds (B), allowing neurons to accumulate bonds in other neurons, speculating on their future value. This mechanism aligns with market-based speculation, incentivizing neurons to make judicious decisions in their inter-neuronal investments.

Example Usage:

from bittensor.core.subtensor import Subtensor

# Connect to the main Bittensor network (Finney).
finney_subtensor = Subtensor(network='finney')

# Close websocket connection with the Bittensor network.
finney_subtensor.close()

# Register a new neuron on the network.
wallet = bittensor_wallet.Wallet(...)  # Assuming a wallet instance is created.
netuid = 1
success = finney_subtensor.register(wallet=wallet, netuid=netuid)

# Set inter-neuronal weights for collaborative learning.
success = finney_subtensor.set_weights(wallet=wallet, netuid=netuid, uids=[...], weights=[...])

# Get the metagraph for a specific subnet using given subtensor connection
metagraph = finney_subtensor.metagraph(netuid=netuid)

By facilitating these operations, the Subtensor class is instrumental in maintaining the decentralized intelligence and dynamic learning environment of the Bittensor network, as envisioned in its foundational principles and mechanisms described in the NeurIPS paper. paper.

Initializes a Subtensor interface for interacting with the Bittensor blockchain.

Note

Currently subtensor defaults to the finney network. This will change in a future release.

We strongly encourage users to run their own local subtensor node whenever possible. This increases decentralization and resilience of the network. In a future release, local subtensor will become the default and the fallback to finney removed. Please plan ahead for this change. We will provide detailed instructions on how to run a local subtensor node in the documentation in a subsequent release.

Parameters:

  • network (Optional[str]) – The network name to connect to (e.g., finney, local). This can also be the chain endpoint (e.g., wss://entrypoint-finney.opentensor.ai:443) and will be correctly parsed into the network and chain endpoint. If not specified, defaults to the main Bittensor network.

  • config (Optional[bittensor.core.config.Config]) – Configuration object for the subtensor. If not provided, a default configuration is used.

  • _mock (bool) – If set to True, uses a mocked connection for testing purposes. Default is False.

  • log_verbose (bool) – Whether to enable verbose logging. If set to True, detailed log information about the connection and network operations will be provided. Default is True.

  • connection_timeout (int) – The maximum time in seconds to keep the connection alive. Default is 600.

This initialization sets up the connection to the specified Bittensor network, allowing for various blockchain operations such as neuron registration, stake management, and setting weights.

__repr__()#
Return type:

str

__str__()#
Return type:

str

_config#
_connection_timeout#
_do_serve_axon#
_encode_params(call_definition, params)#

Returns a hex encoded string of the params using their types.

Parameters:
Return type:

str

_get_hyperparameter(param_name, netuid, block=None)#

Retrieves a specified hyperparameter for a specific subnet.

Parameters:

  • param_name (str) – The name of the hyperparameter to retrieve.

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

The value of the specified hyperparameter if the subnet exists, None otherwise.

Return type:

Optional[Union[int, float]]

_get_substrate()#

Establishes a connection to the Substrate node using configured parameters.

classmethod add_args(parser, prefix=None)#

Adds command-line arguments to the provided ArgumentParser for configuring the Subtensor settings.

Parameters:

  • parser (argparse.ArgumentParser) – The ArgumentParser object to which the Subtensor arguments will be added.

  • prefix (Optional[str]) – An optional prefix for the argument names. If provided, the prefix is prepended to each argument name.

Arguments added:

–subtensor.network: The Subtensor network flag. Possible values are ‘finney’, ‘test’, ‘archive’, and ‘local’. Overrides the chain endpoint if set. –subtensor.chain_endpoint: The Subtensor chain endpoint flag. If set, it overrides the network flag. –subtensor._mock: If true, uses a mocked connection to the chain.

Example

parser = argparse.ArgumentParser() Subtensor.add_args(parser)

property block: int#

Returns current chain block.

Returns:

Current chain block.

Return type:

block (int)

blocks_since_last_update(netuid, uid)#

Returns the number of blocks since the last update for a specific UID in the subnetwork.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • uid (int) – The unique identifier of the neuron.

Returns:

The number of blocks since the last update, or None if the subnetwork or UID does not exist.

Return type:

Optional[int]

bonds(netuid, block=None)#

Retrieves the bond distribution set by neurons within a specific subnet of the Bittensor network. Bonds represent the investments or commitments made by neurons in one another, indicating a level of trust and perceived value. This bonding mechanism is integral to the network’s market-based approach to measuring and rewarding machine intelligence.

Parameters:

  • netuid (int) – The network UID of the subnet to query.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

A list of tuples mapping each neuron’s UID to its bonds with other neurons.

Return type:

list[tuple[int, list[tuple[int, int]]]]

Understanding bond distributions is crucial for analyzing the trust dynamics and market behavior within the subnet. It reflects how neurons recognize and invest in each other’s intelligence and contributions, supporting diverse and niche systems within the Bittensor ecosystem.

burned_register(wallet, netuid, wait_for_inclusion=False, wait_for_finalization=True)#

Registers a neuron on the Bittensor network by recycling TAO. This method of registration involves recycling TAO tokens, allowing them to be re-mined by performing work on the network.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet associated with the neuron to be registered.

  • netuid (int) – The unique identifier of the subnet.

  • wait_for_inclusion (bool, optional) – Waits for the transaction to be included in a block. Defaults to False.

  • wait_for_finalization (bool, optional) – Waits for the transaction to be finalized on the blockchain. Defaults to True.

Returns:

True if the registration is successful, False otherwise.

Return type:

bool

close()#

Cleans up resources for this subtensor instance like active websocket connection and active extensions.

commit(wallet, netuid, data)#

Commits arbitrary data to the Bittensor network by publishing metadata.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet associated with the neuron committing the data.

  • netuid (int) – The unique identifier of the subnetwork.

  • data (str) – The data to be committed to the network.

commit_weights(wallet, netuid, salt, uids, weights, version_key=settings.version_as_int, wait_for_inclusion=False, wait_for_finalization=False, max_retries=5)#

Commits a hash of the neuron’s weights to the Bittensor blockchain using the provided wallet. This action serves as a commitment or snapshot of the neuron’s current weight distribution.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet associated with the neuron committing the weights.

  • netuid (int) – The unique identifier of the subnet.

  • salt (list[int]) – list of randomly generated integers as salt to generated weighted hash.

  • uids (np.ndarray) – NumPy array of neuron UIDs for which weights are being committed.

  • weights (np.ndarray) – NumPy array of weight values corresponding to each UID.

  • version_key (int) – Version key for compatibility with the network. Default is int representation of Bittensor version..

  • wait_for_inclusion (bool) – Waits for the transaction to be included in a block. Default is False.

  • wait_for_finalization (bool) – Waits for the transaction to be finalized on the blockchain. Default is False.

  • max_retries (int) – The number of maximum attempts to commit weights. Default is 5.

Returns:

True if the weight commitment is successful, False otherwise. And msg, a string value describing the success or potential error.

Return type:

tuple[bool, str]

This function allows neurons to create a tamper-proof record of their weight distribution at a specific point in time, enhancing transparency and accountability within the Bittensor network.

static config()#

Creates and returns a Bittensor configuration object.

Returns:

A Bittensor configuration object configured with arguments added by the subtensor.add_args method.

Return type:

config (bittensor.core.config.Config)

static determine_chain_endpoint_and_network(network)#

Determines the chain endpoint and network from the passed network or chain_endpoint.

Parameters:

network (str) – The network flag. The choices are: finney (main network), archive (archive network +300 blocks), local (local running network), test (test network).

Returns:

The network and chain endpoint flag. If passed, overrides the network argument.

Return type:

tuple[Optional[str], Optional[str]]

difficulty(netuid, block=None)#

Retrieves the ‘Difficulty’ hyperparameter for a specified subnet in the Bittensor network.

This parameter is instrumental in determining the computational challenge required for neurons to participate in consensus and validation processes.

Parameters:

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

The value of the ‘Difficulty’ hyperparameter if the subnet exists, None otherwise.

Return type:

Optional[int]

The ‘Difficulty’ parameter directly impacts the network’s security and integrity by setting the computational effort required for validating transactions and participating in the network’s consensus mechanism.

get_all_subnets_info(block=None)#

Retrieves detailed information about all subnets within the Bittensor network. This function provides comprehensive data on each subnet, including its characteristics and operational parameters.

Parameters:

block (Optional[int]) – The blockchain block number for the query.

Returns:

A list of SubnetInfo objects, each containing detailed information about a subnet.

Return type:

list[SubnetInfo]

Gaining insights into the subnets’ details assists in understanding the network’s composition, the roles of different subnets, and their unique features.

get_balance(address, block=None)#

Retrieves the token balance of a specific address within the Bittensor network. This function queries the blockchain to determine the amount of Tao held by a given account.

Parameters:

  • address (str) – The Substrate address in ss58 format.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

Returns:

The account balance at the specified block, represented as a Balance object.

Return type:

bittensor.utils.balance.Balance

This function is important for monitoring account holdings and managing financial transactions within the Bittensor ecosystem. It helps in assessing the economic status and capacity of network participants.

get_block_hash(block_id)#

Retrieves the hash of a specific block on the Bittensor blockchain. The block hash is a unique identifier representing the cryptographic hash of the block’s content, ensuring its integrity and immutability.

Parameters:

block_id (int) – The block number for which the hash is to be retrieved.

Returns:

The cryptographic hash of the specified block.

Return type:

str

The block hash is a fundamental aspect of blockchain technology, providing a secure reference to each block’s data. It is crucial for verifying transactions, ensuring data consistency, and maintaining the trustworthiness of the blockchain.

get_commitment(netuid, uid, block=None)#

Retrieves the on-chain commitment for a specific neuron in the Bittensor network.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • uid (int) – The unique identifier of the neuron.

  • block (Optional[int]) – The block number to retrieve the commitment from. If None, the latest block is used. Default is None.

Returns:

The commitment data as a string.

Return type:

str

get_current_block()#

Returns the current block number on the Bittensor blockchain. This function provides the latest block number, indicating the most recent state of the blockchain.

Returns:

The current chain block number.

Return type:

int

Knowing the current block number is essential for querying real-time data and performing time-sensitive operations on the blockchain. It serves as a reference point for network activities and data synchronization.

get_delegate_by_hotkey(hotkey_ss58, block=None)#

Retrieves detailed information about a delegate neuron based on its hotkey. This function provides a comprehensive view of the delegate’s status, including its stakes, nominators, and reward distribution.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the delegate’s hotkey.

  • block (Optional[int]) – The blockchain block number for the query. Default is None.

Returns:

Detailed information about the delegate neuron, None if not found.

Return type:

Optional[DelegateInfo]

This function is essential for understanding the roles and influence of delegate neurons within the Bittensor network’s consensus and governance structures.

get_delegate_take(hotkey_ss58, block=None)#

Retrieves the delegate ‘take’ percentage for a neuron identified by its hotkey. The ‘take’ represents the percentage of rewards that the delegate claims from its nominators’ stakes.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the neuron’s hotkey.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

The delegate take percentage, None if not available.

Return type:

Optional[float]

The delegate take is a critical parameter in the network’s incentive structure, influencing the distribution of rewards among neurons and their nominators.

get_existential_deposit(block=None)#

Retrieves the existential deposit amount for the Bittensor blockchain. The existential deposit is the minimum amount of TAO required for an account to exist on the blockchain. Accounts with balances below this threshold can be reaped to conserve network resources.

Parameters:

block (Optional[int]) – Block number at which to query the deposit amount. If None, the current block is used.

Returns:

The existential deposit amount, or None if the query fails.

Return type:

Optional[bittensor.utils.balance.Balance]

The existential deposit is a fundamental economic parameter in the Bittensor network, ensuring efficient use of storage and preventing the proliferation of dust accounts.

get_netuids_for_hotkey(hotkey_ss58, block=None)#

Retrieves a list of subnet UIDs (netuids) for which a given hotkey is a member. This function identifies the specific subnets within the Bittensor network where the neuron associated with the hotkey is active.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the neuron’s hotkey.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

Returns:

A list of netuids where the neuron is a member.

Return type:

list[int]

get_neuron_for_pubkey_and_subnet(hotkey_ss58, netuid, block=None)#

Retrieves information about a neuron based on its public key (hotkey SS58 address) and the specific subnet UID (netuid). This function provides detailed neuron information for a particular subnet within the Bittensor network.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the neuron’s hotkey.

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

Returns:

Detailed information about the neuron if found, None otherwise.

Return type:

Optional[bittensor.core.chain_data.neuron_info.NeuronInfo]

This function is crucial for accessing specific neuron data and understanding its status, stake, and other attributes within a particular subnet of the Bittensor ecosystem.

get_prometheus_info(netuid, hotkey_ss58, block=None)#

Returns the prometheus information for this hotkey account.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • hotkey_ss58 (str) – The SS58 address of the hotkey.

  • block (Optional[int]) – The block number to retrieve the prometheus information from. If None, the latest block is used. Default is None.

Returns:

A PrometheusInfo object containing the prometheus information, or None if the prometheus information is not found.

Return type:

Optional[bittensor.core.chain_data.prometheus_info.PrometheusInfo]

get_subnet_burn_cost(block=None)#

Retrieves the burn cost for registering a new subnet within the Bittensor network. This cost represents the amount of Tao that needs to be locked or burned to establish a new subnet.

Parameters:

block (Optional[int]) – The blockchain block number for the query.

Returns:

The burn cost for subnet registration.

Return type:

int

The subnet burn cost is an important economic parameter, reflecting the network’s mechanisms for controlling the proliferation of subnets and ensuring their commitment to the network’s long-term viability.

get_subnet_hyperparameters(netuid, block=None)#

Retrieves the hyperparameters for a specific subnet within the Bittensor network. These hyperparameters define the operational settings and rules governing the subnet’s behavior.

Parameters:

  • netuid (int) – The network UID of the subnet to query.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

The subnet’s hyperparameters, or None if not available.

Return type:

Optional[bittensor.core.chain_data.subnet_hyperparameters.SubnetHyperparameters]

Understanding the hyperparameters is crucial for comprehending how subnets are configured and managed, and how they interact with the network’s consensus and incentive mechanisms.

get_subnets(block=None)#

Retrieves a list of all subnets currently active within the Bittensor network. This function provides an overview of the various subnets and their identifiers.

Parameters:

block (Optional[int]) – The blockchain block number for the query.

Returns:

A list of network UIDs representing each active subnet.

Return type:

list[int]

This function is valuable for understanding the network’s structure and the diversity of subnets available for neuron participation and collaboration.

get_total_subnets(block=None)#

Retrieves the total number of subnets within the Bittensor network as of a specific blockchain block.

Parameters:

block (Optional[int]) – The blockchain block number for the query.

Returns:

The total number of subnets in the network.

Return type:

Optional[int]

Understanding the total number of subnets is essential for assessing the network’s growth and the extent of its decentralized infrastructure.

get_transfer_fee(wallet, dest, value)#

Calculates the transaction fee for transferring tokens from a wallet to a specified destination address. This function simulates the transfer to estimate the associated cost, taking into account the current network conditions and transaction complexity.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet from which the transfer is initiated.

  • dest (str) – The SS58 address of the destination account.

  • value (Union[bittensor.utils.balance.Balance, float, int]) – The amount of tokens to be transferred, specified as a Balance object, or in Tao (float) or Rao (int) units.

Returns:

The estimated transaction fee for the transfer, represented as a Balance object.

Return type:

bittensor.utils.balance.Balance

Estimating the transfer fee is essential for planning and executing token transactions, ensuring that the wallet has sufficient funds to cover both the transfer amount and the associated costs. This function provides a crucial tool for managing financial operations within the Bittensor network.

get_uid_for_hotkey_on_subnet(hotkey_ss58, netuid, block=None)#

Retrieves the unique identifier (UID) for a neuron’s hotkey on a specific subnet.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the neuron’s hotkey.

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

The UID of the neuron if it is registered on the subnet, None otherwise.

Return type:

Optional[int]

The UID is a critical identifier within the network, linking the neuron’s hotkey to its operational and governance activities on a particular subnet.

classmethod help()#

Print help to stdout.

immunity_period(netuid, block=None)#

Retrieves the ‘ImmunityPeriod’ hyperparameter for a specific subnet. This parameter defines the duration during which new neurons are protected from certain network penalties or restrictions.

Parameters:

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

The value of the ‘ImmunityPeriod’ hyperparameter if the subnet exists, None otherwise.

Return type:

Optional[int]

The ‘ImmunityPeriod’ is a critical aspect of the network’s governance system, ensuring that new participants have a grace period to establish themselves and contribute to the network without facing immediate punitive actions.

is_hotkey_registered(hotkey_ss58, netuid=None, block=None)#

Determines whether a given hotkey (public key) is registered in the Bittensor network, either globally across any subnet or specifically on a specified subnet. This function checks the registration status of a neuron identified by its hotkey, which is crucial for validating its participation and activities within the network.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the neuron’s hotkey.

  • netuid (Optional[int]) – The unique identifier of the subnet to check the registration. If None, the registration is checked across all subnets.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

Returns:

True if the hotkey is registered in the specified context (either any subnet or a specific subnet), False otherwise.

Return type:

bool

This function is important for verifying the active status of neurons in the Bittensor network. It aids in understanding whether a neuron is eligible to participate in network processes such as consensus, validation, and incentive distribution based on its registration status.

is_hotkey_registered_any(hotkey_ss58, block=None)#

Checks if a neuron’s hotkey is registered on any subnet within the Bittensor network.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the neuron’s hotkey.

  • block (Optional[int]) – The blockchain block number at which to perform the check.

Returns:

True if the hotkey is registered on any subnet, False otherwise.

Return type:

bool

This function is essential for determining the network-wide presence and participation of a neuron.

is_hotkey_registered_on_subnet(hotkey_ss58, netuid, block=None)#

Checks if a neuron’s hotkey is registered on a specific subnet within the Bittensor network.

Parameters:

  • hotkey_ss58 (str) – The SS58 address of the neuron’s hotkey.

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number at which to perform the check.

Returns:

True if the hotkey is registered on the specified subnet, False otherwise.

Return type:

bool

This function helps in assessing the participation of a neuron in a particular subnet, indicating its specific area of operation or influence within the network.

log_verbose#
max_weight_limit(netuid, block=None)#

Returns network MaxWeightsLimit hyperparameter.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • block (Optional[int]) – The block number to retrieve the parameter from. If None, the latest block is used. Default is None.

Returns:

The value of the MaxWeightsLimit hyperparameter, or None if the subnetwork does not exist or the parameter is not found.

Return type:

Optional[float]

metagraph(netuid, lite=True, block=None)#

Returns a synced metagraph for a specified subnet within the Bittensor network. The metagraph represents the network’s structure, including neuron connections and interactions.

Parameters:

  • netuid (int) – The network UID of the subnet to query.

  • lite (bool) – If true, returns a metagraph using a lightweight sync (no weights, no bonds). Default is True.

  • block (Optional[int]) – Block number for synchronization, or None for the latest block.

Returns:

The metagraph representing the subnet’s structure and neuron relationships.

Return type:

bittensor.core.metagraph.Metagraph

The metagraph is an essential tool for understanding the topology and dynamics of the Bittensor network’s decentralized architecture, particularly in relation to neuron interconnectivity and consensus processes.

min_allowed_weights(netuid, block=None)#

Returns network MinAllowedWeights hyperparameter.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • block (Optional[int]) – The block number to retrieve the parameter from. If None, the latest block is used. Default is None.

Returns:

The value of the MinAllowedWeights hyperparameter, or None if the subnetwork does not exist or the parameter is not found.

Return type:

Optional[int]

neuron_for_uid(uid, netuid, block=None)#

Retrieves detailed information about a specific neuron identified by its unique identifier (UID) within a specified subnet (netuid) of the Bittensor network. This function provides a comprehensive view of a neuron’s attributes, including its stake, rank, and operational status.

Parameters:

  • uid (Optional[int]) – The unique identifier of the neuron.

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

Detailed information about the neuron if found, None otherwise.

Return type:

bittensor.core.chain_data.neuron_info.NeuronInfo

This function is crucial for analyzing individual neurons’ contributions and status within a specific subnet, offering insights into their roles in the network’s consensus and validation mechanisms.

neurons(netuid, block=None)#

Retrieves a list of all neurons within a specified subnet of the Bittensor network. This function provides a snapshot of the subnet’s neuron population, including each neuron’s attributes and network interactions.

Parameters:

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

A list of NeuronInfo objects detailing each neuron’s characteristics in the subnet.

Return type:

list[bittensor.core.chain_data.neuron_info.NeuronInfo]

Understanding the distribution and status of neurons within a subnet is key to comprehending the network’s decentralized structure and the dynamics of its consensus and governance processes.

neurons_lite(netuid, block=None)#

Retrieves a list of neurons in a ‘lite’ format from a specific subnet of the Bittensor network. This function provides a streamlined view of the neurons, focusing on key attributes such as stake and network participation.

Parameters:

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

A list of simplified neuron information for the subnet.

Return type:

list[bittensor.core.chain_data.neuron_info_lite.NeuronInfoLite]

This function offers a quick overview of the neuron population within a subnet, facilitating efficient analysis of the network’s decentralized structure and neuron dynamics.

query_constant(module_name, constant_name, block=None)#

Retrieves a constant from the specified module on the Bittensor blockchain. This function is used to access fixed parameters or values defined within the blockchain’s modules, which are essential for understanding the network’s configuration and rules.

Parameters:

  • module_name (str) – The name of the module containing the constant.

  • constant_name (str) – The name of the constant to retrieve.

  • block (Optional[int]) – The blockchain block number at which to query the constant.

Returns:

The value of the constant if found, None otherwise.

Return type:

Optional[scalecodec.ScaleType]

Constants queried through this function can include critical network parameters such as inflation rates, consensus rules, or validation thresholds, providing a deeper understanding of the Bittensor network’s operational parameters.

query_map(module, name, block=None, params=None)#

Queries map storage from any module on the Bittensor blockchain. This function retrieves data structures that represent key-value mappings, essential for accessing complex and structured data within the blockchain modules.

Parameters:

  • module (str) – The name of the module from which to query the map storage.

  • name (str) – The specific storage function within the module to query.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

  • params (Optional[list[object]]) – Parameters to be passed to the query.

Returns:

A data structure representing the map storage if found, None otherwise.

Return type:

result (substrateinterface.base.QueryMapResult)

This function is particularly useful for retrieving detailed and structured data from various blockchain modules, offering insights into the network’s state and the relationships between its different components.

query_map_subtensor(name, block=None, params=None)#

Queries map storage from the Subtensor module on the Bittensor blockchain. This function is designed to retrieve a map-like data structure, which can include various neuron-specific details or network-wide attributes.

Parameters:

  • name (str) – The name of the map storage function to query.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

  • params (Optional[list[object]]) – A list of parameters to pass to the query function.

Returns:

An object containing the map-like data structure, or None if not found.

Return type:

QueryMapResult (substrateinterface.base.QueryMapResult)

This function is particularly useful for analyzing and understanding complex network structures and relationships within the Bittensor ecosystem, such as inter-neuronal connections and stake distributions.

query_module(module, name, block=None, params=None)#

Queries any module storage on the Bittensor blockchain with the specified parameters and block number. This function is a generic query interface that allows for flexible and diverse data retrieval from various blockchain modules.

Parameters:

  • module (str) – The name of the module from which to query data.

  • name (str) – The name of the storage function within the module.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

  • params (Optional[list[object]]) – A list of parameters to pass to the query function.

Returns:

An object containing the requested data if found, None otherwise.

Return type:

Optional[scalecodec.ScaleType]

This versatile query function is key to accessing a wide range of data and insights from different parts of the Bittensor blockchain, enhancing the understanding and analysis of the network’s state and dynamics.

query_runtime_api(runtime_api, method, params, block=None)#

Queries the runtime API of the Bittensor blockchain, providing a way to interact with the underlying runtime and retrieve data encoded in Scale Bytes format. This function is essential for advanced users who need to interact with specific runtime methods and decode complex data types.

Parameters:

  • runtime_api (str) – The name of the runtime API to query.

  • method (str) – The specific method within the runtime API to call.

  • params (Optional[list[ParamWithTypes]]) – The parameters to pass to the method call.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

Returns:

The Scale Bytes encoded result from the runtime API call, or None if the call fails.

Return type:

Optional[str]

This function enables access to the deeper layers of the Bittensor blockchain, allowing for detailed and specific interactions with the network’s runtime environment.

query_subtensor(name, block=None, params=None)#

Queries named storage from the Subtensor module on the Bittensor blockchain. This function is used to retrieve specific data or parameters from the blockchain, such as stake, rank, or other neuron-specific attributes.

Parameters:

  • name (str) – The name of the storage function to query.

  • block (Optional[int]) – The blockchain block number at which to perform the query.

  • params (Optional[list[object]]) – A list of parameters to pass to the query function.

Returns:

An object containing the requested data.

Return type:

query_response (scalecodec.ScaleType)

This query function is essential for accessing detailed information about the network and its neurons, providing valuable insights into the state and dynamics of the Bittensor ecosystem.

recycle(netuid, block=None)#

Retrieves the ‘Burn’ hyperparameter for a specified subnet. The ‘Burn’ parameter represents the amount of Tao that is effectively recycled within the Bittensor network.

Parameters:

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

The value of the ‘Burn’ hyperparameter if the subnet exists, None otherwise.

Return type:

Optional[Balance]

Understanding the ‘Burn’ rate is essential for analyzing the network registration usage, particularly how it is correlated with user activity and the overall cost of participation in a given subnet.

register(wallet, netuid, wait_for_inclusion=False, wait_for_finalization=True, max_allowed_attempts=3, output_in_place=True, cuda=False, dev_id=0, tpb=256, num_processes=None, update_interval=None, log_verbose=False)#

Registers a neuron on the Bittensor network using the provided wallet.

Registration is a critical step for a neuron to become an active participant in the network, enabling it to stake, set weights, and receive incentives.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet associated with the neuron to be registered.

  • netuid (int) – The unique identifier of the subnet.

  • wait_for_inclusion (bool) – Waits for the transaction to be included in a block. Defaults to False.

  • wait_for_finalization (bool) – Waits for the transaction to be finalized on the blockchain. Defaults to True.

  • max_allowed_attempts (int) – Maximum number of attempts to register the wallet.

  • output_in_place (bool) – If true, prints the progress of the proof of work to the console in-place. Meaning the progress is printed on the same lines. Defaults to True.

  • cuda (bool) – If true, the wallet should be registered using CUDA device(s). Defaults to False.

  • dev_id (Union[List[int], int]) – The CUDA device id to use, or a list of device ids. Defaults to 0 (zero).

  • tpb (int) – The number of threads per block (CUDA). Default to 256.

  • num_processes (Optional[int]) – The number of processes to use to register. Default to None.

  • update_interval (Optional[int]) – The number of nonces to solve between updates. Default to None.

  • log_verbose (bool) – If true, the registration process will log more information. Default to False.

Returns:

True if the registration is successful, False otherwise.

Return type:

bool

This function facilitates the entry of new neurons into the network, supporting the decentralized growth and scalability of the Bittensor ecosystem.

reveal_weights(wallet, netuid, uids, weights, salt, version_key=settings.version_as_int, wait_for_inclusion=False, wait_for_finalization=False, max_retries=5)#

Reveals the weights for a specific subnet on the Bittensor blockchain using the provided wallet. This action serves as a revelation of the neuron’s previously committed weight distribution.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet associated with the neuron revealing the weights.

  • netuid (int) – The unique identifier of the subnet.

  • uids (np.ndarray) – NumPy array of neuron UIDs for which weights are being revealed.

  • weights (np.ndarray) – NumPy array of weight values corresponding to each UID.

  • salt (np.ndarray) – NumPy array of salt values corresponding to the hash function.

  • version_key (int) – Version key for compatibility with the network. Default is int representation of Bittensor version.

  • wait_for_inclusion (bool) – Waits for the transaction to be included in a block. Default is False.

  • wait_for_finalization (bool) – Waits for the transaction to be finalized on the blockchain. Default is False.

  • max_retries (int) – The number of maximum attempts to reveal weights. Default is 5.

Returns:

True if the weight revelation is successful, False otherwise. And msg, a string value describing the success or potential error.

Return type:

tuple[bool, str]

This function allows neurons to reveal their previously committed weight distribution, ensuring transparency and accountability within the Bittensor network.

root_register(wallet, wait_for_inclusion=False, wait_for_finalization=True)#

Registers the neuron associated with the wallet on the root network. This process is integral for participating in the highest layer of decision-making and governance within the Bittensor network.

Parameters:

  • wallet (bittensor.wallet) – The wallet associated with the neuron to be registered on the root network.

  • wait_for_inclusion (bool) – Waits for the transaction to be included in a block. Defaults to False.

  • wait_for_finalization (bool) – Waits for the transaction to be finalized on the blockchain. Defaults to True.

Returns:

True if the registration on the root network is successful, False otherwise.

Return type:

bool

This function enables neurons to engage in the most critical and influential aspects of the network’s governance, signifying a high level of commitment and responsibility in the Bittensor ecosystem.

root_set_weights(wallet, netuids, weights, version_key=0, wait_for_inclusion=False, wait_for_finalization=False)#

Sets the weights for neurons on the root network. This action is crucial for defining the influence and interactions of neurons at the root level of the Bittensor network.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet associated with the neuron setting the weights.

  • netuids (Union[NDArray[np.int64], torch.LongTensor, list]) – The list of neuron UIDs for which weights are being set.

  • weights (Union[NDArray[np.float32], torch.FloatTensor, list]) – The corresponding weights to be set for each UID.

  • version_key (int, optional) – Version key for compatibility with the network. Default is 0.

  • wait_for_inclusion (bool, optional) – Waits for the transaction to be included in a block. Defaults to False.

  • wait_for_finalization (bool, optional) – Waits for the transaction to be finalized on the blockchain. Defaults to False.

Returns:

True if the setting of root-level weights is successful, False otherwise.

Return type:

bool

This function plays a pivotal role in shaping the root network’s collective intelligence and decision-making processes, reflecting the principles of decentralized governance and collaborative learning in Bittensor.

serve_axon(netuid, axon, wait_for_inclusion=False, wait_for_finalization=True)#

Registers an Axon serving endpoint on the Bittensor network for a specific neuron. This function is used to set up the Axon, a key component of a neuron that handles incoming queries and data processing tasks.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • axon (bittensor.core.axon.Axon) – The Axon instance to be registered for serving.

  • wait_for_inclusion (bool) – Waits for the transaction to be included in a block. Default is False.

  • wait_for_finalization (bool) – Waits for the transaction to be finalized on the blockchain. Default is True.

Returns:

True if the Axon serve registration is successful, False otherwise.

Return type:

bool

By registering an Axon, the neuron becomes an active part of the network’s distributed computing infrastructure, contributing to the collective intelligence of Bittensor.

set_weights(wallet, netuid, uids, weights, version_key=settings.version_as_int, wait_for_inclusion=False, wait_for_finalization=False, max_retries=5)#

Sets the inter-neuronal weights for the specified neuron. This process involves specifying the influence or trust a neuron places on other neurons in the network, which is a fundamental aspect of Bittensor’s decentralized learning architecture.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet associated with the neuron setting the weights.

  • netuid (int) – The unique identifier of the subnet.

  • uids (Union[NDArray[np.int64], torch.LongTensor, list]) – The list of neuron UIDs that the weights are being set for.

  • weights (Union[NDArray[np.float32], torch.FloatTensor, list]) – The corresponding weights to be set for each UID.

  • version_key (int) – Version key for compatibility with the network. Default is int representation of Bittensor version..

  • wait_for_inclusion (bool) – Waits for the transaction to be included in a block. Default is False.

  • wait_for_finalization (bool) – Waits for the transaction to be finalized on the blockchain. Default is False.

  • max_retries (int) – The number of maximum attempts to set weights. Default is 5.

Returns:

True if the setting of weights is successful, False otherwise. And msg, a string value describing the success or potential error.

Return type:

tuple[bool, str]

This function is crucial in shaping the network’s collective intelligence, where each neuron’s learning and contribution are influenced by the weights it sets towards others【81†source】.

static setup_config(network, config)#

Sets up and returns the configuration for the Subtensor network and endpoint.

This method determines the appropriate network and chain endpoint based on the provided network string or configuration object. It evaluates the network and endpoint in the following order of precedence: 1. Provided network string. 2. Configured chain endpoint in the config object. 3. Configured network in the config object. 4. Default chain endpoint. 5. Default network.

Parameters:

  • network (Optional[str]) – The name of the Subtensor network. If None, the network and endpoint will be determined from the config object.

  • config (bittensor.core.config.Config) – The configuration object containing the network and chain endpoint settings.

Returns:

A tuple containing the formatted WebSocket endpoint URL and the evaluated network name.

Return type:

tuple

state_call(method, data, block=None)#

Makes a state call to the Bittensor blockchain, allowing for direct queries of the blockchain’s state. This function is typically used for advanced queries that require specific method calls and data inputs.

Parameters:

  • method (str) – The method name for the state call.

  • data (str) – The data to be passed to the method.

  • block (Optional[int]) – The blockchain block number at which to perform the state call.

Returns:

The result of the rpc call.

Return type:

result (dict[Any, Any])

The state call function provides a more direct and flexible way of querying blockchain data, useful for specific use cases where standard queries are insufficient.

subnet_exists(netuid, block=None)#

Checks if a subnet with the specified unique identifier (netuid) exists within the Bittensor network.

Parameters:

  • netuid (int) – The unique identifier of the subnet.

  • block (Optional[int]) – The blockchain block number at which to check the subnet’s existence.

Returns:

True if the subnet exists, False otherwise.

Return type:

bool

This function is critical for verifying the presence of specific subnets in the network, enabling a deeper understanding of the network’s structure and composition.

subnetwork_n(netuid, block=None)#

Returns network SubnetworkN hyperparameter.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • block (Optional[int]) – The block number to retrieve the parameter from. If None, the latest block is used. Default is None.

Returns:

The value of the SubnetworkN hyperparameter, or None if the subnetwork does not exist or the parameter is not found.

Return type:

Optional[int]

substrate: substrateinterface.base.SubstrateInterface = None#
tempo(netuid, block=None)#

Returns network Tempo hyperparameter.

Parameters:

  • netuid (int) – The unique identifier of the subnetwork.

  • block (Optional[int]) – The block number to retrieve the parameter from. If None, the latest block is used. Default is None.

Returns:

The value of the Tempo hyperparameter, or None if the subnetwork does not exist or the parameter is not found.

Return type:

Optional[int]

transfer(wallet, dest, amount, wait_for_inclusion=True, wait_for_finalization=False)#

Executes a transfer of funds from the provided wallet to the specified destination address. This function is used to move TAO tokens within the Bittensor network, facilitating transactions between neurons.

Parameters:

  • wallet (bittensor_wallet.Wallet) – The wallet from which funds are being transferred.

  • dest (str) – The destination public key address.

  • amount (Union[bittensor.utils.balance.Balance, float]) – The amount of TAO to be transferred.

  • wait_for_inclusion (bool) – Waits for the transaction to be included in a block. Default is True.

  • wait_for_finalization (bool) – Waits for the transaction to be finalized on the blockchain. Default is False.

Returns:

True if the transfer is successful, False otherwise.

Return type:

transfer_extrinsic (bool)

This function is essential for the fluid movement of tokens in the network, supporting various economic activities such as staking, delegation, and reward distribution.

weights(netuid, block=None)#

Retrieves the weight distribution set by neurons within a specific subnet of the Bittensor network. This function maps each neuron’s UID to the weights it assigns to other neurons, reflecting the network’s trust and value assignment mechanisms.

Parameters:

  • netuid (int) – The network UID of the subnet to query.

  • block (Optional[int]) – The blockchain block number for the query.

Returns:

A list of tuples mapping each neuron’s UID to its assigned weights.

Return type:

list[tuple[int, list[tuple[int, int]]]]

The weight distribution is a key factor in the network’s consensus algorithm and the ranking of neurons, influencing their influence and reward allocation within the subnet.

weights_rate_limit(netuid)#

Returns network WeightsSetRateLimit hyperparameter.

Parameters:

netuid (int) – The unique identifier of the subnetwork.

Returns:

The value of the WeightsSetRateLimit hyperparameter, or None if the subnetwork does not exist or the parameter is not found.

Return type:

Optional[int]

Contents