Adds burned_register to AsyncSubtensor

Author: ibraheem-abe

bittensor/core/async_subtensor.py

@@ -30,7 +30,10 @@
     DynamicInfo,
 )
 from bittensor.core.errors import StakeError
-from bittensor.core.extrinsics.async_registration import register_extrinsic
+from bittensor.core.extrinsics.async_registration import (
+    register_extrinsic,
+    burned_register_extrinsic,
+)
 from bittensor.core.extrinsics.async_root import (
     set_root_weights_extrinsic,
     root_register_extrinsic,
@@ -1224,6 +1227,33 @@ async def neurons_lite(
 
         return NeuronInfoLite.list_from_vec_u8(hex_to_bytes(hex_bytes_result))
 
+    async def burned_register(
+        self,
+        wallet: "Wallet",
+        netuid: int,
+        wait_for_inclusion: bool = False,
+        wait_for_finalization: bool = True,
+    ) -> bool:
+        """
+        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.
+
+        Args:
+            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:
+            bool: ``True`` if the registration is successful, False otherwise.
+        """
+        return await burned_register_extrinsic(
+            subtensor=self,
+            wallet=wallet,
+            netuid=netuid,
+            wait_for_inclusion=wait_for_inclusion,
+            wait_for_finalization=wait_for_finalization,
+        )
+
     async def get_neuron_for_pubkey_and_subnet(
         self,
         hotkey_ss58: str,
@@ -1255,7 +1285,7 @@ async def get_neuron_for_pubkey_and_subnet(
         if uid is None:
             return NeuronInfo.get_null_neuron()
 
-        params = [netuid, uid]
+        params = [netuid, uid.value]
         json_body = await self.substrate.rpc_request(
             method="neuronInfo_getNeuron",
             params=params,
@@ -1761,6 +1791,22 @@ async def weights_rate_limit(
         )
         return None if call is None else int(call)
 
+    async def recycle(self, netuid: int) -> Optional["Balance"]:
+        """
+        Retrieves the 'Burn' hyperparameter for a specified subnet. The 'Burn' parameter represents the amount of Tao that is effectively recycled within the Bittensor network.
+
+        Args:
+            netuid (int): The unique identifier of the subnet.
+            block (Optional[int]): The blockchain block number for the query.
+
+        Returns:
+            Optional[Balance]: The value of the 'Burn' hyperparameter if the subnet exists, None otherwise.
+
+        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.
+        """
+        call = await self.get_hyperparameter(param_name="Burn", netuid=netuid)
+        return None if call is None else Balance.from_rao(int(call.value))
+
     async def blocks_since_last_update(self, netuid: int, uid: int) -> Optional[int]:
         """
         Returns the number of blocks since the last update for a specific UID in the subnetwork.

bittensor/core/extrinsics/async_registration.py

@@ -11,7 +11,7 @@
 
 from bittensor_wallet import Wallet
 
-from bittensor.utils import format_error_message
+from bittensor.utils import format_error_message, unlock_key
 from bittensor.utils.btlogging import logging
 from bittensor.utils.registration import log_no_torch_error, create_pow_async
 
@@ -263,3 +263,140 @@ async def register_extrinsic(
             # Failed to register after max attempts.
             logging.error("[red]No more attempts.[/red]")
             return False
+
+
+async def _do_burned_register(
+    subtensor: "AsyncSubtensor",
+    netuid: int,
+    wallet: "Wallet",
+    wait_for_inclusion: bool = False,
+    wait_for_finalization: bool = True,
+) -> tuple[bool, Optional[str]]:
+    """
+    Performs a burned register extrinsic call to the Subtensor chain.
+
+    This method sends a registration transaction to the Subtensor blockchain using the burned register mechanism.
+
+    Args:
+        subtensor (bittensor.core.async_subtensor.AsyncSubtensor): AsyncSubtensor instance.
+        netuid (int): The network unique identifier to register on.
+        wallet (bittensor_wallet.Wallet): The wallet to be registered.
+        wait_for_inclusion (bool): Whether to wait for the transaction to be included in a block. Default is False.
+        wait_for_finalization (bool): Whether to wait for the transaction to be finalized. Default is True.
+
+    Returns:
+        Tuple[bool, Optional[str]]: A tuple containing a boolean indicating success or failure, and an optional error message.
+    """
+
+    # create extrinsic call
+    call = await subtensor.substrate.compose_call(
+        call_module="SubtensorModule",
+        call_function="burned_register",
+        call_params={
+            "netuid": netuid,
+            "hotkey": wallet.hotkey.ss58_address,
+        },
+    )
+    extrinsic = await subtensor.substrate.create_signed_extrinsic(
+        call=call, keypair=wallet.coldkey
+    )
+    response = await subtensor.substrate.submit_extrinsic(
+        extrinsic=extrinsic,
+        wait_for_inclusion=wait_for_inclusion,
+        wait_for_finalization=wait_for_finalization,
+    )
+
+    # We only wait here if we expect finalization.
+    if not wait_for_finalization and not wait_for_inclusion:
+        return True, None
+
+    # process if registration successful, try again if pow is still valid
+    await response.process_events()
+    if not await response.is_success:
+        return False, format_error_message(error_message=await response.error_message)
+    # Successful registration
+    else:
+        return True, None
+
+
+async def burned_register_extrinsic(
+    subtensor: "AsyncSubtensor",
+    wallet: "Wallet",
+    netuid: int,
+    wait_for_inclusion: bool = False,
+    wait_for_finalization: bool = True,
+) -> bool:
+    """Registers the wallet to chain by recycling TAO.
+
+    Args:
+        subtensor (bittensor.core.async_subtensor.AsyncSubtensor): AsyncSubtensor instance.
+        wallet (bittensor.wallet): Bittensor wallet object.
+        netuid (int): The ``netuid`` of the subnet to register on.
+        wait_for_inclusion (bool): If set, waits for the extrinsic to enter a block before returning ``true``, or returns ``false`` if the extrinsic fails to enter the block within the timeout.
+        wait_for_finalization (bool): If set, waits for the extrinsic to be finalized on the chain before returning ``true``, or returns ``false`` if the extrinsic fails to be finalized within the timeout.
+
+    Returns:
+        success (bool): Flag is ``true`` if extrinsic was finalized or uncluded in the block. If we did not wait for finalization / inclusion, the response is ``true``.
+    """
+    if not await subtensor.subnet_exists(netuid):
+        logging.error(
+            f":cross_mark: [red]Failed error:[/red] subnet [blue]{netuid}[/blue] does not exist."
+        )
+        return False
+
+    if not (unlock := unlock_key(wallet)).success:
+        logging.error(unlock.message)
+        return False
+
+    logging.info(
+        f":satellite: [magenta]Checking Account on subnet[/magenta] [blue]{netuid}[/blue][magenta] ...[/magenta]"
+    )
+    neuron = await subtensor.get_neuron_for_pubkey_and_subnet(
+        wallet.hotkey.ss58_address, netuid=netuid
+    )
+
+    old_balance = await subtensor.get_balance(wallet.coldkeypub.ss58_address)
+
+    if not neuron.is_null:
+        logging.info(":white_heavy_check_mark: [green]Already Registered[/green]")
+        logging.info(f"\t\tuid: [blue]{neuron.uid}[/blue]")
+        logging.info(f"\t\tnetuid: [blue]{neuron.netuid}[/blue]")
+        logging.info(f"\t\thotkey: [blue]{neuron.hotkey}[/blue]")
+        logging.info(f"\t\tcoldkey: [blue]{neuron.coldkey}[/blue]")
+        return True
+
+    logging.info(":satellite: [magenta]Recycling TAO for Registration...[/magenta]")
+
+    recycle_amount = await subtensor.recycle(netuid=netuid)
+    logging.info(f"Recycling {recycle_amount} to register on subnet:{netuid}")
+
+    success, err_msg = await _do_burned_register(
+        subtensor=subtensor,
+        netuid=netuid,
+        wallet=wallet,
+        wait_for_inclusion=wait_for_inclusion,
+        wait_for_finalization=wait_for_finalization,
+    )
+
+    if not success:
+        logging.error(f":cross_mark: [red]Failed error:[/red] {err_msg}")
+        await asyncio.sleep(0.5)
+        return False
+    # Successful registration, final check for neuron and pubkey
+    else:
+        logging.info(":satellite: [magenta]Checking Balance...[/magenta]")
+        new_balance = await subtensor.get_balance(wallet.coldkeypub.ss58_address)
+
+        logging.info(
+            f"Balance: [blue]{old_balance}[/blue] :arrow_right: [green]{new_balance}[/green]"
+        )
+        is_registered = await subtensor.is_hotkey_registered(
+            netuid=netuid, hotkey_ss58=wallet.hotkey.ss58_address
+        )
+        if is_registered:
+            logging.info(":white_heavy_check_mark: [green]Registered[/green]")
+            return True
+        else:
+            # neuron not found, try again
+            logging.error(":cross_mark: [red]Unknown error. Neuron not found.[/red]")
+            return False