bittensor.core.async_subtensor#
Classes#
Thin layer for interacting with Substrate Interface. Mostly a collection of frequently-used calls. |
|
dict() -> new empty dictionary |
|
Functions#
|
Decodes a dictionary of hexadecimal identities. |
Module Contents#
- class bittensor.core.async_subtensor.AsyncSubtensor(network=DEFAULT_NETWORK)#
Thin layer for interacting with Substrate Interface. Mostly a collection of frequently-used calls.
- Parameters:
network (str)
- async __aenter__()#
- async __aexit__(exc_type, exc_val, exc_tb)#
- __str__()#
- async blocks_since_last_update(netuid, uid)#
Returns the number of blocks since the last update for a specific UID in the subnetwork.
- async bonds(netuid, block_hash=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:
- Returns:
List of tuples mapping each neuron’s UID to its bonds with other neurons.
- Return type:
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.
- async commit_weights(wallet, netuid, salt, uids, weights, version_key=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:
Trueif the weight commitment is successful, False otherwise. And msg, a string value describing the success or potential error.- Return type:
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.
- async does_hotkey_exist(hotkey_ss58, block_hash=None, reuse_block=False)#
Returns true if the hotkey is known by the chain and there are accounts.
- Parameters:
- Returns:
True if the hotkey is known by the chain and there are accounts, False otherwise.
- Return type:
- async encode_params(call_definition, params)#
Returns a hex encoded string of the params using their types.
- async filter_netuids_by_registered_hotkeys(all_netuids, filter_for_netuids, all_hotkeys, block_hash=None, reuse_block=False)#
Filters a given list of all netuids for certain specified netuids and hotkeys
- Parameters:
all_netuids (Iterable[int]) – A list of netuids to filter.
filter_for_netuids (Iterable[int]) – A subset of all_netuids to filter from the main list
all_hotkeys (Iterable[Wallet]) – Hotkeys to filter from the main list
block_hash (str) – hash of the blockchain block number at which to perform the query.
reuse_block (bool) – whether to reuse the last-used blockchain hash when retrieving info.
- Returns:
The filtered list of netuids.
- Return type:
- async get_balance(*addresses, block_hash=None)#
Retrieves the balance for given coldkey(s)
- async get_block_hash(block_id=None)#
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:
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.
- async get_children(hotkey, netuid)#
This method retrieves the children of a given hotkey and netuid. It queries the SubtensorModule’s ChildKeys storage function to get the children and formats them before returning as a tuple.
- async 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:
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.
- async get_delegate_identities(block_hash=None)#
Fetches delegates identities from the chain and GitHub. Preference is given to chain data, and missing info is filled-in by the info from GitHub. At some point, we want to totally move away from fetching this info from GitHub, but chain data is still limited in that regard.
- Parameters:
block_hash (str) – the hash of the blockchain block for the query
- Returns:
DelegatesDetails, …}
- Return type:
Dict {ss58
- async get_delegated(coldkey_ss58, block_hash=None, reuse_block=False)#
Retrieves a list of delegates and their associated stakes for a given coldkey. This function identifies the delegates that a specific account has staked tokens on.
- Parameters:
- Returns:
A list of tuples, each containing a delegate’s information and staked amount.
- Return type:
list[tuple[bittensor.core.chain_data.DelegateInfo, bittensor.utils.balance.Balance]]
This function is important for account holders to understand their stake allocations and their involvement in the network’s delegation and consensus mechanisms.
- async get_delegates(block_hash=None, reuse_block=False)#
Fetches all delegates on the chain
- Parameters:
- Returns:
List of DelegateInfo objects, or an empty list if there are no delegates.
- Return type:
- async get_existential_deposit(block_hash=None, reuse_block=False)#
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:
- Returns:
The existential deposit amount.
- Return type:
The existential deposit is a fundamental economic parameter in the Bittensor network, ensuring efficient use of storage and preventing the proliferation of dust accounts.
- async get_hotkey_owner(hotkey_ss58, block_hash)#
Retrieves the owner of the given hotkey at a specific block hash. This function queries the blockchain for the owner of the provided hotkey. If the hotkey does not exist at the specified block hash, it returns None.
- async get_hyperparameter(param_name, netuid, block_hash=None, reuse_block=False)#
Retrieves a specified hyperparameter for a specific subnet.
- Parameters:
- Returns:
The value of the specified hyperparameter if the subnet exists, or None
- Return type:
Optional[Any]
- async get_netuids_for_hotkey(hotkey_ss58, block_hash=None, reuse_block=False)#
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:
- Returns:
A list of netuids where the neuron is a member.
- Return type:
- async get_stake_for_coldkey_and_hotkey(hotkey_ss58, coldkey_ss58, block_hash=None)#
Retrieves stake information associated with a specific coldkey and hotkey.
- Parameters:
- Returns:
Stake Balance for the given coldkey and hotkey
- Return type:
- async get_stake_info_for_coldkey(coldkey_ss58, block_hash=None, reuse_block=False)#
Retrieves stake information associated with a specific coldkey. This function provides details about the stakes held by an account, including the staked amounts and associated delegates.
- Parameters:
- Returns:
A list of StakeInfo objects detailing the stake allocations for the account.
- Return type:
Stake information is vital for account holders to assess their investment and participation in the network’s delegation and consensus processes.
- async get_subnet_burn_cost(block_hash=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_hash (Optional[int]) – The blockchain block_hash of the block id.
- Returns:
The burn cost for subnet registration.
- Return type:
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.
- async get_subnet_hyperparameters(netuid, block_hash=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:
- Returns:
The subnet’s hyperparameters, or None if not available.
- Return type:
Optional[Union[list, bittensor.core.chain_data.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.
- async get_subnets(block_hash=None)#
Retrieves the list of all subnet unique identifiers (netuids) currently present in the Bittensor network.
- Parameters:
block_hash (Optional[str]) – The hash of the block to retrieve the subnet unique identifiers from.
- Returns:
A list of subnet netuids.
- Return type:
This function provides a comprehensive view of the subnets within the Bittensor network, offering insights into its diversity and scale.
- async get_total_stake_for_coldkey(*ss58_addresses, block_hash=None)#
Returns the total stake held on a coldkey.
- async get_total_stake_for_hotkey(*ss58_addresses, block_hash=None, reuse_block=False)#
Returns the total stake held on a hotkey.
- async get_total_subnets(block_hash=None)#
Retrieves the total number of subnets within the Bittensor network as of a specific blockchain block.
- Parameters:
block_hash (Optional[str]) – The blockchain block_hash representation of block id.
- Returns:
The total number of subnets in the network.
- Return type:
Optional[str]
Understanding the total number of subnets is essential for assessing the network’s growth and the extent of its decentralized infrastructure.
- async 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
SS58address 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:
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.
- async get_uid_for_hotkey_on_subnet(hotkey_ss58, netuid, block_hash=None)#
Retrieves the unique identifier (UID) for a neuron’s hotkey on a specific subnet.
- Parameters:
- Returns:
The UID of the neuron if it is registered on the subnet,
Noneotherwise.- 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.
- async get_vote_data(proposal_hash, block_hash=None, reuse_block=False)#
Retrieves the voting data for a specific proposal on the Bittensor blockchain. This data includes information about how senate members have voted on the proposal.
- Parameters:
- Returns:
An object containing the proposal’s voting data, or None if not found.
- Return type:
Optional[ProposalVoteData]
This function is important for tracking and understanding the decision-making processes within the Bittensor network, particularly how proposals are received and acted upon by the governing body.
- async is_hotkey_delegate(hotkey_ss58, block_hash=None, reuse_block=False)#
Determines whether a given hotkey (public key) is a delegate on the Bittensor network. This function checks if the neuron associated with the hotkey is part of the network’s delegation system.
- Parameters:
- Returns:
True if the hotkey is a delegate, False otherwise.
- Return type:
Being a delegate is a significant status within the Bittensor network, indicating a neuron’s involvement in consensus and governance processes.
- async is_hotkey_registered(netuid, hotkey_ss58)#
Checks to see if the hotkey is registered on a given netuid
- async is_hotkey_registered_any(hotkey_ss58, block_hash=None)#
Checks if a neuron’s hotkey is registered on any subnet within the Bittensor network.
- Parameters:
- Returns:
Trueif the hotkey is registered on any subnet, False otherwise.- Return type:
This function is essential for determining the network-wide presence and participation of a neuron.
- async neuron_for_uid(uid, netuid, block_hash=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:
- Returns:
Detailed information about the neuron if found, a null neuron otherwise
- Return type:
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.
- async neurons(netuid, block_hash=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:
- Returns:
A list of NeuronInfo objects detailing each neuron’s characteristics in the subnet.
- Return type:
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.
- async neurons_lite(netuid, block_hash=None, reuse_block=False)#
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:
- Returns:
A list of simplified neuron information for the subnet.
- Return type:
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.
- async pow_register(wallet, netuid, processors, update_interval, output_in_place, verbose, use_cuda, dev_id, threads_per_block)#
Register neuron.
- Parameters:
wallet (bittensor_wallet.Wallet)
- async query_identity(key, block_hash=None, reuse_block=False)#
Queries the identity of a neuron on the Bittensor blockchain using the given key. This function retrieves detailed identity information about a specific neuron, which is a crucial aspect of the network’s decentralized identity and governance system.
- Parameters:
- Returns:
An object containing the identity information of the neuron if found,
Noneotherwise.- Return type:
The identity information can include various attributes such as the neuron’s stake, rank, and other network-specific details, providing insights into the neuron’s role and status within the Bittensor network.
Note
See the Bittensor CLI documentation for supported identity parameters.
- async query_runtime_api(runtime_api, method, params, block_hash=None, reuse_block=False)#
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[Union[list[list[int]], dict[str, int]]]) – The parameters to pass to the method call.
block_hash (Optional[str]) – The hash of the blockchain block number at which to perform the query.
reuse_block (bool) – Whether to reuse the last-used block hash.
- Returns:
The Scale Bytes encoded result from the runtime API call, or
Noneif 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.
- async register(wallet, netuid, block_hash=None, wait_for_inclusion=True, wait_for_finalization=True)#
Register neuron by recycling some TAO.
- Parameters:
wallet (bittensor_wallet.Wallet) – Bittensor wallet instance.
netuid (int) – Subnet uniq id.
block_hash (Optional[str]) – The hash of the blockchain block for the query.
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.
- Returns:
True if registration was successful, otherwise False.
- Return type:
- async root_set_weights(wallet, netuids, weights)#
Set weights for root network.
- async set_weights(wallet, netuid, uids, weights, version_key=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:
Trueif the setting of weights is successful, False otherwise. And msg, a string value describing the success or potential error.- Return type:
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】.
- async sign_and_send_extrinsic(call, wallet, wait_for_inclusion=True, wait_for_finalization=False)#
Helper method to sign and submit an extrinsic call to chain.
- Parameters:
call (scalecodec.types.GenericCall) – a prepared Call object
wallet (bittensor_wallet.Wallet) – the wallet whose coldkey will be used to sign the extrinsic
wait_for_inclusion (bool) – whether to wait until the extrinsic call is included on the chain
wait_for_finalization (bool) – whether to wait until the extrinsic call is finalized on the chain
- Returns:
(success, error message)
- Return type:
- async subnet_exists(netuid, block_hash=None, reuse_block=False)#
Checks if a subnet with the specified unique identifier (netuid) exists within the Bittensor network.
- Parameters:
- Returns:
True if the subnet exists, False otherwise.
- Return type:
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.
- substrate#
- async transfer(wallet, destination, amount, transfer_all)#
Transfer token of amount to destination.
- Parameters:
- Returns:
True if the transferring was successful, otherwise False.
- Return type:
- async weights(netuid, block_hash=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:
- Returns:
A list of tuples mapping each neuron’s UID to its assigned weights.
- Return type:
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.
- async weights_rate_limit(netuid)#
Returns network WeightsSetRateLimit hyperparameter.
- class bittensor.core.async_subtensor.ParamWithTypes#
Bases:
TypedDictdict() -> 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.