bt.subtensor

Subtensor Class Reference Documentation

Introduction

The Subtensor is utilized for managing interactions with the subtensor chain. It serves as an interface to communicate with "Finney", Bittensor's main blockchain network, or others, enabling operations like querying and transacting.

Examples


1# Creating a default chain connection to remote finney instance.
2sub = bt.subtensor()
3
4# Parsing --subtensor.network and --subtensor.chain_endpoint from the command line
5sub = bt.subtensor( config = bt.subtensor.config() )
6
7# Connecting subtensor's default local entrypoint "ws://127.0.0.1:9944"
8sub = bt.subtensor( network = 'local' )
9
10# Connecting to a specific endpoint
11sub = bt.subtensor( chain_endpoint = "ws://127.0.0.1:9944" )

Methods

Extrinsics

Methods

nominate


1nominate(self, wallet: 'bittensor.Wallet', wait_for_finalization: bool = False, wait_for_inclusion: bool = True) -> bool

Designates the wallet's hotkey as a delegate.

delegate


1delegate(self, wallet: 'bittensor.wallet', delegate_ss58: Optional[str] = None, amount: Union[Balance, float] = None, wait_for_inclusion: bool = True, wait_for_finalization: bool = False, prompt: bool = False) -> bool

Adds a specific amount of stake to a delegate using a wallet.

undelegate


1undelegate(self, wallet: 'bittensor.wallet', delegate_ss58: Optional[str] = None, amount: Union[Balance, float] = None, wait_for_inclusion: bool = True, wait_for_finalization: bool = False, prompt: bool = False) -> bool

Removes a specific amount of stake from a delegate using a wallet.

set_weights


1set_weights(self, wallet: 'bittensor.wallet', netuid: int, uids: Union[torch.LongTensor, list], weights: Union[torch.FloatTensor, list], version_key: int = bittensor.__version_as_int__, wait_for_inclusion:bool = False, wait_for_finalization:bool = False, prompt:bool = False) -> bool

Sets weights for a given netuid.

register


1register(self, wallet: 'bittensor.Wallet', netuid: int, wait_for_inclusion: bool = False, wait_for_finalization: bool = True, prompt: bool = False, max_allowed_attempts: int = 3, output_in_place: bool = True, cuda: bool = False, dev_id: Union[List[int], int] = 0, TPB: int = 256, num_processes: Optional[int] = None, update_interval: Optional[int] = None, log_verbose: bool = False) -> bool

Registers the wallet to the chain.

burned_register


1burned_register(self, wallet: 'bittensor.Wallet', netuid: int, wait_for_inclusion: bool = False, wait_for_finalization: bool = True, prompt: bool = False) -> bool

Registers the wallet to the chain by recycling TAO.

transfer


1transfer(self, wallet: 'bittensor.wallet', dest: str, amount: Union[Balance, float], wait_for_inclusion: bool = True, wait_for_finalization: bool = False, prompt: bool = False) -> bool

Transfers funds from the wallet to a destination public key address.

get_existential_deposit


1get_existential_deposit(self, block: Optional[int] = None) -> Optional[Balance]

Returns the existential deposit for the chain.

serve


1serve(self, wallet: 'bittensor.wallet', ip: str, port: int, protocol: int, netuid: int, placeholder1: int = 0, placeholder2: int = 0, wait_for_inclusion: bool = False, wait_for_finalization = True, prompt: bool = False) -> bool

Starts serving on a specific IP, port and protocol for a given netuid.

serve_axon


1serve_axon(self, netuid: int, axon: 'bittensor.Axon', use_upnpc: bool = False, wait_for_inclusion: bool = False, wait_for_finalization: bool = True, prompt: bool
2
3 = False) -> bool

Starts serving an Axon for a given netuid.

serve_prometheus


1serve_prometheus(self, wallet: 'bittensor.wallet', port: int, netuid: int, wait_for_inclusion: bool = False, wait_for_finalization: bool = True) -> bool

Starts serving a Prometheus server on a specific port for a given netuid.

add_stake


1add_stake(self, wallet: 'bittensor.wallet', hotkey_ss58: Optional[str] = None, amount: Union[Balance, float] = None, wait_for_inclusion: bool = True, wait_for_finalization: bool = False, prompt: bool = False) -> bool

Adds a specific amount of stake to a hotkey uid.

add_stake_multiple


1add_stake_multiple(self, wallet: 'bittensor.wallet', hotkey_ss58s: List[str], amounts: List[Union[Balance, float]] = None, wait_for_inclusion: bool = True, wait_for_finalization: bool = False, prompt: bool = False) -> bool

Adds stake to each hotkey in the list from a common coldkey.

unstake


1unstake(self, wallet: 'bittensor.wallet', hotkey_ss58: Optional[str] = None, amount: Union[Balance, float] = None, wait_for_inclusion:bool = True, wait_for_finalization:bool = False, prompt: bool = False) -> bool

Removes stake into the wallet coldkey from the specified hotkey uid.

unstake_multiple


1unstake_multiple(self, wallet: 'bittensor.wallet', hotkey_ss58s: List[str], amounts: List[Union[Balance, float]] = None, wait_for_inclusion: bool = True, wait_for_finalization: bool = False, prompt: bool = False) -> bool

Removes stake from each hotkey in the list to a common coldkey.

Hyperparameters

rho


1rho (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network Rho hyperparameter if the network exists. Accepts an integer netuid representing the unique network ID and an optional integer block representing the block number.

kappa


1kappa (self, netuid: int, block: Optional[int] = None ) -> Optional[float]

Returns the network Kappa hyperparameter if the network exists. Inputs are netuid and an optional block number.

difficulty


1difficulty (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network Difficulty hyperparameter if the network exists. Inputs are netuid and an optional block number.

burn


1burn (self, netuid: int, block: Optional[int] = None ) -> Optional[bittensor.Balance]

Returns the network Burn hyperparameter if the network exists. Inputs are netuid and an optional block number.

immunity_period


1immunity_period (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network ImmunityPeriod hyperparameter if the network exists. Inputs are netuid and an optional block number.

validator_batch_size


1validator_batch_size (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network ValidatorBatchSize hyperparameter if the network exists. Inputs are netuid and an optional block number.

validator_prune_len


1validator_prune_len (self, netuid: int, block: Optional[int] = None ) -> int

Returns the network ValidatorPruneLen hyperparameter if the network exists. Inputs are netuid and an optional block number.

validator_logits_divergence


1validator_logits_divergence (self, netuid: int, block: Optional[int] = None ) -> Optional[float]

Returns the network ValidatorLogitsDivergence hyperparameter if the network exists. Inputs are netuid and an optional block number.

validator_sequence_length


1validator_sequence_length (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network ValidatorSequenceLength hyperparameter if the network exists. Inputs are netuid and an optional block number.

validator_epochs_per_reset


1validator_epochs_per_reset (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network ValidatorEpochsPerReset hyperparameter if the network exists. Inputs are netuid and an optional block number.

validator_epoch_length


1validator_epoch_length (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network ValidatorEpochLen hyperparameter if the network exists. Inputs are netuid and an optional block number.

validator_exclude_quantile


1validator_exclude_quantile (self, netuid: int, block: Optional[int] = None ) -> Optional[float]

Returns the network ValidatorExcludeQuantile hyperparameter if the network exists. Inputs are netuid and an optional block number.

max_allowed_validators


1max_allowed_validators(self, netuid: int, block: Optional[int] = None) -> Optional[int]

Returns the network MaxAllowedValidators hyperparameter if the network exists. Inputs are netuid and an optional block number.

min_allowed_weights


1min_allowed_weights (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network MinAllowedWeights hyperparameter if the network exists. Inputs are netuid and an optional block number.

max_weight_limit


1max_weight_limit (self, netuid: int, block: Optional[int] = None ) -> Optional[float]

Returns the network MaxWeightsLimit hyperparameter if the network exists. Inputs are netuid and an optional block number.

scaling_law_power


1scaling_law_power (self, netuid: int, block: Optional[int] = None ) -> Optional[float]

Returns the network ScalingLawPower hyperparameter if the network exists. Inputs are netuid and an optional block number.

synergy_scaling_law_power


1synergy_scaling_law_power (self, netuid: int, block: Optional[int] = None ) -> Optional[float]

Returns the network SynergyScalingLawPower hyperparameter if the network exists. Inputs are netuid and an optional block number.

subnetwork_n


1subnetwork_n (self, netuid: int, block: Optional[int] = None ) -> int

Returns the network SubnetworkN hyperparameter if the network exists. Inputs are netuid and an optional block number.

max_n


1max_n (self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the network MaxAllowedUids hyperparameter if the network exists. Inputs are netuid and an optional block number.

blocks_since_epoch


1blocks_since_epoch (self, netuid: int, block: Optional[int] = None) -> int

Returns the network BlocksSinceLastStep hyperparameter if the network exists. Inputs are netuid and an optional block number.

tempo


1tempo (self, netuid: int, block: Optional[int] = None) -> int

Returns the network Tempo hyperparameter if the network exists. Inputs are netuid and an optional block number.

Account Functions

get_total_stake_for_hotkey


1get_total_stake_for_hotkey( self, ss58_address: str, block: Optional[int] = None ) -> Optional['bittensor.Balance']

Returns the total stake held on a hotkey including delegated. Inputs are ss58_address and an optional block number.

get_total_stake_for_coldkey


1get_total_stake_for_coldkey( self, ss58_address: str, block: Optional[int] = None ) -> Optional['bittensor.Balance']

Returns the total stake held on a coldkey across all hotkeys including delegates. Inputs are ss58_address and an optional block number.

get_stake_for_coldkey_and_hotkey


1get_stake_for_coldkey_and_hotkey( self, hotkey_ss58: str, coldkey_ss58: str, block: Optional[int] = None ) -> Optional['bittensor.Balance']

Returns the stake under a coldkey - hotkey pairing. Inputs are hotkey_ss58, coldkey_ss58 and an optional block number.

get_stake


1get_stake( self, hotkey_ss58: str, block: Optional[int] = None ) -> List[Tuple[str,'bittensor.Balance']]

Returns a list of stake tuples (coldkey, balance) for each delegating coldkey including the owner. Inputs are hotkey_ss58 and an optional block number.

does_hotkey_exist


1does_hotkey_exist( self, hotkey_ss58: str, block: Optional[int] = None ) -> bool

Returns true if the hotkey is known by the chain and there are accounts. Inputs are hotkey_ss58 and an optional block number.

get_hotkey_owner


1get_hotkey_owner( self, hotkey_ss58: str, block: Optional[int] = None ) -> Optional[str]

Returns the coldkey owner of the passed hotkey if it exists. Inputs are hotkey_ss58 and an optional block number.

get_axon_info


1get_axon_info( self, hotkey_ss58: str, block: Optional[int] = None ) -> Optional[axon_info]

Returns the axon information for the specified hotkey account if it exists. Inputs are hotkey_ss58 and an optional block number.

get_prometheus_info


1get_prometheus_info( self, hotkey_ss58: str, block: Optional[int] = None ) -> Optional[axon_info]

Returns the prometheus information for the specified hotkey account if it exists. Inputs are hotkey_ss58 and an optional block number.

Global State

block


1@property
2def block (self) -> int:

Property that returns the current chain block.

total_issuance


1total_issuance (self, block: Optional[int] = None ) -> 'bittensor.Balance'

Returns the total issuance of tokens as of a specified block. If no block is provided, the default is the current block.

total_stake


1total_stake (self,block: Optional[int] = None ) -> 'bittensor.Balance'

Returns the total amount of stake as of a specified block. If no block is provided, the default is the current block.

serving_rate_limit


1serving_rate_limit (self, block: Optional[int] = None ) -> Optional[int]

Returns the serving rate limit as of a specified block. If no block is provided, the default is the current block.

tx_rate_limit


1tx_rate_limit (self, block: Optional[int] = None ) -> Optional[int]

Returns the transaction rate limit as of a specified block. If no block is provided, the default is the current block.

Subnetwork Stake

subnet_exists


1subnet_exists( self, netuid: int, block: Optional[int] = None ) -> bool

Checks if a subnet with the given netuid exists as of a specified block. If no block is provided, the default is the current block.

get_all_subnet_netuids


1get_all_subnet_netuids( self, block: Optional[int] = None ) -> List[int]

Returns a list of netuids of all subnets as of a specified block. If no block is provided, the default is the current block.

get_total_subnets


1get_total_subnets( self, block: Optional[int] = None ) -> int

Returns the total number of subnets as of a specified block. If no block is provided, the default is the current block.

get_subnet_modality


1get_subnet_modality( self, netuid: int, block: Optional[int] = None ) -> Optional[int]

Returns the modality of a subnet with a specified netuid as of a given block. If no block is provided, the default is the current block.

get_subnet_connection_requirement


1get_subnet_connection_requirement( self, netuid_0: int, netuid_1: int, block: Optional[int] = None) -> Optional[int]

Returns the connection requirement between two subnets with specified netuids as of a given block. If no block is provided, the default is the current block.

get_emission_value_by_subnet


1get_emission_value_by_subnet( self, netuid: int, block: Optional[int] = None ) -> Optional[float]

Returns the emission value of a subnet with the given netuid as of a specified block. If no block is provided, the default is the current block.

get_subnet_connection_requirements


1get_subnet_connection_requirements( self, netuid: int, block: Optional[int] = None) -> Dict[str, int]

Returns a dictionary of the connection requirements of a subnet with the given netuid as of a specified block. If no block is provided, the default is the current block.

get_subnets


1get_subnets( self, block: Optional[int] = None ) -> List[int]

Returns a list of all subnets as of a specified block. If no block is provided, the default is the current block.

get_all_subnets_info


1get_all_subnets_info( self, block: Optional[int] = None ) -> List[SubnetInfo]

Returns a list of information about all subnets as of a specified block. If no block is provided, the default is the current block.

get_subnet_info


1get_subnet_info( self, netuid: int, block: Optional[int] = None ) -> Optional[SubnetInfo]

Returns information about a subnet with a given netuid as of a specified block. If no block is provided, the default is the current block.

Delegation

is_hotkey_delegate


1is_hotkey_delegate( self, hotkey_ss58: str ) -> bool

Checks if a delegate with the specified hotkey exists.

get_delegate_take


1get_delegate_take( self, hotkey_ss58: str, block: Optional[int] = None ) -> Optional[float]

Returns the 'take' (portion of the reward a delegate receives from staking) of a delegate specified by a hotkey as of a given block. If no block is provided, the default is the current block.

get_nominators_for_hotkey


1get_nominators_for_hotkey( self, hotkey_ss58: str, block: Optional[int] = None ) -> List[Tuple[str, Balance]]

Returns a list of tuples, each containing a nominator's address and balance for the delegate specified by a hotkey as of a given block. If no block is provided, the default is the current block.

get_delegate_by_hotkey


1get_delegate_by_hotkey( self, hotkey_ss58: str, block: Optional[int] = None ) -> Optional[DelegateInfo]

Returns information about a delegate specified by a hotkey as of a given block. If no block is provided, the default is the current block.

get_delegates


1get_delegates( self, block: Optional[int] = None ) -> List[DelegateInfo]

Returns a list of all delegates as of a specified block. If no block is provided, the default is the current block.

get_delegated


1get_delegated( self, coldkey_ss58: str, block: Optional[int] = None ) -> List[Tuple[DelegateInfo, Balance]]

Returns a list of delegates that a given coldkey is staked to, as of a specified block. If no block is provided, the default is the current block. Each item in the list is a tuple containing the delegate's information and the staked balance.

Neuron information per subnet

is_hotkey_registered_any


1is_hotkey_registered_any( self, hotkey_ss58: str, block: Optional[int] = None) -> bool

Returns True if the hotkey is registered on any subnet. If no block is specified, the current block is used.

is_hotkey_registered_on_subnet


1is_hotkey_registered_on_subnet( self, hotkey_ss58: str, netuid: int, block: Optional[int] = None) -> bool

Returns True if the hotkey is registered on a specified subnet. If no block is specified, the current block is used.

is_hotkey_registered


1is_hotkey_registered( self, hotkey_ss58: str, netuid: int, block: Optional[int] = None) -> bool

Returns True if the hotkey is registered on a specified subnet. If no block is specified, the current block is used.

get_uid_for_hotkey_on_subnet


1get_uid_for_hotkey_on_subnet( self, hotkey_ss58: str, netuid: int, block: Optional[int] = None) -> int

Returns the user id (uid) for the hotkey on a specified subnet. If no block is specified, the current block is used.

get_all_uids_for_hotkey


1get_all_uids_for_hotkey( self, hotkey_ss58: str, block: Optional[int] = None) -> List[int]

Returns a list of all user ids (uids) for the hotkey. If no block is specified, the current block is used.

get_netuids_for_hotkey


1get_netuids_for_hotkey( self, hotkey_ss58: str, block: Optional[int] = None) -> List[int]

Returns a list of all network user ids (netuids) for the hotkey. If no block is specified, the current block is used.

get_neuron_for_pubkey_and_subnet


1get_neuron_for_pubkey_and_subnet( self, hotkey_ss58: str, netuid: int, block: Optional[int] = None ) -> Optional[NeuronInfo]

Returns the neuron information for the hotkey on a specified subnet. If no block is specified, the current block is used.

get_all_neurons_for_pubkey


1get_all_neurons_for_pubkey( self, hotkey_ss58: str, block: Optional[int] = None ) -> List[NeuronInfo]

Returns a list of all neurons for the hotkey. If no block is specified, the current block is used.

neuron_has_validator_permit


1neuron_has_validator_permit( self, uid: int, netuid: int, block: Optional[int] = None ) -> Optional[bool]

Returns True if the neuron with the given uid has a validator permit for the specified subnet. If no block is specified, the current block is used.

neuron_for_wallet


1neuron_for_wallet( self, wallet: 'bittensor.Wallet', netuid = int, block: Optional[int] = None ) -> Optional[NeuronInfo]

Returns the neuron information for the given wallet on a specified subnet. If no block is specified, the current block is used.

neuron_for_uid


1neuron_for_uid( self, uid: int, netuid: int, block: Optional[int] = None ) -> Optional[NeuronInfo]

Returns the neuron metadata associated with a given user id (uid) and network user id (netuid) at a specified block, or None if it does not exist.

neurons


1neurons(self, netuid: int, block: Optional[int] = None ) -> List[NeuronInfo]

Returns a list of neurons from the chain for a given network user id (netuid) at a specified block.

neuron_for_uid_lite


1neuron_for_uid_lite( self, uid: int, netuid: int, block: Optional[int] = None ) -> Optional[NeuronInfoLite]

Returns the lightweight neuron metadata (without weights and bonds) associated with a given user id (uid) and network user id (netuid) at a specified block, or None if it does not exist.

neurons_lite


1neurons_lite(self, netuid: int, block: Optional[int] = None ) -> List[NeuronInfoLite]

Returns a list of lightweight neurons (without weights and bonds) from the chain for a given network user id (netuid) at a specified block.

metagraph


1metagraph( self, netuid: int, lite: bool = True ) -> 'bittensor.Metagraph'

Returns the metagraph for the subnet associated with a given network user id (netuid). If 'lite' is True, it returns a metagraph using the lightweight sync (no weights, no bonds).

Legacy

Methods

get_balance


1get_balance(self, address: str, block: int = None) -> Balance

Returns the token balance for the given Substrate address at a specified block.

get_current_block


1get_current_block(self) -> int

Returns the current block number on the chain.

get_balances


1get_balances(self, block: int = None) -> Dict[str, Balance]

Returns a dictionary of balances for all addresses at a specified block. The dictionary keys are addresses and values are their corresponding balances.

`str()`

This method is used to provide a string representation of the instance.


1str(obj)

If the network argument equals the chain_endpoint argument, it returns a string that denotes connecting to a chain endpoint without a known network. Otherwise, it represents connecting to a network with a known endpoint.

`repr()`

This method is used to provide an official string representation of the instance.


1repr(obj)

The string returned by this method is identical to the one provided by the __str__() method.

Initialization

To initialize an instance of the Subtensor class, you'll need to provide three arguments:


1import bittensor as bt
2obj = bt.subtensor( config, network, chain_endpoint )

Arguments

config (bt.Config, optional, defaults=bt.subtensor.config()):
Subtensor config object containing arguments from bt.subtensor.config() which are automatically parsed from command line and ENV vars.
network (str, optional, default='finney'):
The subtensor network flag. The likely choices are:
-- local (local running network)
-- finney (main network)
-- mock (mock network for testing.)
If this option is set it overloads subtensor.chain_endpoint with
an entry point node from that network.
chain_endpoint (str, default=None):
The subtensor endpoint flag. If set, overrides the network argument.

glossary

bt.wallet