bittensor.utils.balance

bittensor.utils.balance#

Classes#

Balance

Represents the bittensor balance of the wallet, stored as rao (int).

FixedPoint

Represents a fixed point U64F64 number.

Functions#

check_balance_amount(amount[, allow_none])

Validate that the provided value is a Balance instance.

fixed_to_float(fixed[, frac_bits, total_bits])

Converts a fixed-point value (e.g., U64F64) into a floating-point number.

rao(amount[, netuid])

Helper function to create a Balance object from an int (Rao)

tao(amount[, netuid])

Helper function to create a Balance object from a float (Tao)

Module Contents#

class bittensor.utils.balance.Balance(balance)[source]#

Represents the bittensor balance of the wallet, stored as rao (int).

This class provides a way to interact with balances in two different units: rao and tao. It provides methods to convert between these units, as well as to perform arithmetic and comparison operations.

Variables:

  • unit (str) – A string representing the symbol for the tao unit.

  • rao_unit (str) – A string representing the symbol for the rao unit.

  • rao (int) – An integer that stores the balance in rao units.

  • tao (float) – A float property that gives the balance in tao units.

Parameters:

balance (Union[int, float])

Note

To ensure arithmetic operations between Balance instances work correctly, they must set the same unit for each using the netuid.

Examples

balance_wallet_default = Balance.from_tao(10, netuid=14) balance_wallet_secret = Balance.from_tao(2, netuid=14) total_balance = balance_wallet_default + balance_wallet_secret

# or

balance_wallet_default = Balance.from_tao(10).set_unit(netuid=14) balance_wallet_secret = Balance.from_tao(2).set_unit(netuid=14) total_balance = balance_wallet_default + balance_wallet_secret

The from_tao() and from_rao() methods accept the netuid parameter to set the appropriate unit symbol.

Note

When performing arithmetic or comparison operations where the first operand is a Balance instance and the second operand is not, the second operand is implicitly interpreted as a raw amount in rao, using the same unit (netuid) as the first operand. This allows interoperability with integer or float values, but may result in unexpected behavior if the caller assumes the second operand is in tao.

Example

balance = Balance.from_tao(10, netuid=14) result = balance + 5000 # 5 will be treated as 5000 rao, not 5 tao print(result) output: τ10.000005000

Initialize a Balance object. If balance is an int, it’s assumed to be in rao. If balance is a float, it’s assumed to be in tao.

Parameters:

  • balance (Union[int, float])

  • rao (in either)

  • balance

static from_float(amount, netuid=0)[source]#

Given tao, return Balance() object with rao(int) and tao(float), where rao = int(tao*pow(10,9))

Parameters:

  • amount (float) – The amount in tao.

  • netuid (int) – The subnet uid for set currency unit.

Returns:

A Balance object representing the given amount.

Return type:

Balance

static from_rao(amount, netuid=0)[source]#

Given rao, return Balance object with rao(int) and tao(float), where rao = int(tao*pow(10,9))

Parameters:

  • amount (int) – The amount in rao.

  • netuid (int) – The subnet uid for set currency unit.

Returns:

A Balance object representing the given amount.

Return type:

Balance

static from_tao(amount, netuid=0)[source]#

Given tao, return Balance object with rao(int) and tao(float), where rao = int(tao*pow(10,9))

Parameters:

  • amount (float) – The amount in tao.

  • netuid (int) – The subnet uid for set currency unit.

Returns:

A Balance object representing the given amount.

Return type:

Balance

static get_unit(netuid)[source]#
Parameters:

netuid (int)

Return type:

str

netuid: int = 0#
rao: int#
rao_unit: str#
set_unit(netuid)[source]#
Parameters:

netuid (int)

property tao#
unit: str#
class bittensor.utils.balance.FixedPoint[source]#

Bases: TypedDict

Represents a fixed point U64F64 number. Where bits is a U128 representation of the fixed point number.

This matches the type of the Alpha shares.

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

bits: int#
bittensor.utils.balance.check_balance_amount(amount, allow_none=True)#

Validate that the provided value is a Balance instance.

This function ensures that the amount argument is a Balance object. If a non-Balance type is passed, it raises a BalanceTypeError to enforce consistent usage of Balance objects across arithmetic operations.

Parameters:

  • amount (Optional[Balance]) – The value to validate.

  • allow_none (bool) – if False then a BalanceTypeError is raised if the value is None.

Returns:

Always returns None if validation passes.

Return type:

None

Raises:

BalanceTypeError – If amount is not a Balance instance and not None.

bittensor.utils.balance.fixed_to_float(fixed, frac_bits=64, total_bits=128)[source]#

Converts a fixed-point value (e.g., U64F64) into a floating-point number.

Parameters:

  • fixed (Union[FixedPoint, scalecodec.ScaleType])

  • frac_bits (int)

  • total_bits (int)

Return type:

float

bittensor.utils.balance.rao(amount, netuid=0)[source]#

Helper function to create a Balance object from an int (Rao)

Parameters:
Return type:

Balance

bittensor.utils.balance.tao(amount, netuid=0)[source]#

Helper function to create a Balance object from a float (Tao)

Parameters:
Return type:

Balance