From 24b766d721f914eae521f8d1dba5fd71763d10ca Mon Sep 17 00:00:00 2001 From: philanthrope Date: Thu, 16 Nov 2023 17:06:02 -0500 Subject: [PATCH] Adds docstrings for CLI for Sphynx documentation (#1579) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Release/6.2.0 (#1567) * (un)Staking multiple avoid tx limit (#1244) * add tx rate limit * wait for tx limit if not done multi stake/unstake * dont "decrypt" hotkey * additional logging for prometheus * additional logging for prometheus (#1246) * Dataset fix (#1249) * fix * added try except * Grab delegates details from GitHub (#1245) * add url to init * add dataclass and util functions * use in cli * remove delegates json --------- Co-authored-by: joeylegere * Add raw spec for local test and new bins (#1243) * add spec and new bins * fix config netuid * use dot get * check if config netuid is list * add start to mockstatus * add attr to mock neuron * add info to mock from neurons * change ordering of neuron dict to namespace * remove test for wandb for axon * use regex for looser match * fix blacklist metagraph mock * use real mock netuid * use mock network and netuid in constructor * fix patch * patch delegate check * use mock network and netuid * remove check for wallet hotkey * fix tests for subtensor init * dont set netuid for overview test * typo in docstring * add mock status stop * add low mock tx limit * oops typo * use dot get * add wait for final and incl args * use args during setup * update bins and use 100ms blocktime * pass block arg * remove bittensor.logging and a old test * use random port * backward fix * fix block time to 1s * compile no symb on linux * compile no symb mac * remove useless init on var * use dot get for new flags * update test durations * update test durations * use dot get for config * output error msg * mock to_default * remove to defaults in help * reduce neruons, remove flaky test * deactivate test * mvoe key pair tests out of the subtensor interface --------- Co-authored-by: Eugene * Fix list_delegates on non-archive nodes (#1232) * Change how pull of archival data is handled * fix for list_delegates too * . * use empty dict * fix spacing * specify exception * log out * add space in log message * use warning instead * Blacklist fixes + depreciation of old signatures (#1240) * fixes blacklist error message + remove * remove checks for parse signature * remove sign v1 tests * fix for the syanpse checks * fix tests and remove duplicate sign * Improve development workflow documentation * [BIT-636] Change u16 weight normalization to max-upscaling (#1241) * Change u16 weight normalization to max-upscaling Use full u16 bitwidth so that max_weight=U16_MAX, then rely on subtensor epoch to properly normalize weights in I32F32. This means that weights submission extrinsic to subtensor does not have to be pre-normalized. * Skip zero sum in weight conversion * Round u16 weights * remove duplicate command #1228 (#1231) * remove duplicate command #1228 * Extract create_parser for cli testing * mark as private * use in tests and test for duplicates * fix test using mock prompt answers * test_forward_priority_2nd_request_timeout fix (#1276) fix * Remove btcli query and btcli set_weights (#1144) . * Merge releases 4.0.0 and 4.0.1 back to staging (#1306) * bump version * Fix permissions for release github script (#1224) Co-authored-by: Cameron Fairchild * should be 4.1.0 * Revert "should be 4.1.0" This reverts commit 3db08ea24f4fc4775bd46858e6c77cfa165d85ed. * Staging into Release branch (#1275) * (un)Staking multiple avoid tx limit (#1244) * add tx rate limit * wait for tx limit if not done multi stake/unstake * dont "decrypt" hotkey * additional logging for prometheus (#1246) * Dataset fix (#1249) * fix * added try except * Grab delegates details from GitHub (#1245) * add url to init * add dataclass and util functions * use in cli * remove delegates json --------- Co-authored-by: joeylegere * Add raw spec for local test and new bins (#1243) * add spec and new bins * fix config netuid * use dot get * check if config netuid is list * add start to mockstatus * add attr to mock neuron * add info to mock from neurons * change ordering of neuron dict to namespace * remove test for wandb for axon * use regex for looser match * fix blacklist metagraph mock * use real mock netuid * use mock network and netuid in constructor * fix patch * patch delegate check * use mock network and netuid * remove check for wallet hotkey * fix tests for subtensor init * dont set netuid for overview test * typo in docstring * add mock status stop * add low mock tx limit * oops typo * use dot get * add wait for final and incl args * use args during setup * update bins and use 100ms blocktime * pass block arg * remove bittensor.logging and a old test * use random port * backward fix * fix block time to 1s * compile no symb on linux * compile no symb mac * remove useless init on var * use dot get for new flags * update test durations * update test durations * use dot get for config * output error msg * mock to_default * remove to defaults in help * reduce neruons, remove flaky test * deactivate test * mvoe key pair tests out of the subtensor interface --------- Co-authored-by: Eugene * Fix list_delegates on non-archive nodes (#1232) * Change how pull of archival data is handled * fix for list_delegates too * . * use empty dict * fix spacing * specify exception * log out * add space in log message * use warning instead * Blacklist fixes + depreciation of old signatures (#1240) * fixes blacklist error message + remove * remove checks for parse signature * remove sign v1 tests * fix for the syanpse checks * fix tests and remove duplicate sign * [BIT-636] Change u16 weight normalization to max-upscaling (#1241) * Change u16 weight normalization to max-upscaling Use full u16 bitwidth so that max_weight=U16_MAX, then rely on subtensor epoch to properly normalize weights in I32F32. This means that weights submission extrinsic to subtensor does not have to be pre-normalized. * Skip zero sum in weight conversion * Round u16 weights * remove duplicate command #1228 (#1231) * remove duplicate command #1228 * Extract create_parser for cli testing * mark as private * use in tests and test for duplicates * fix test using mock prompt answers * test_forward_priority_2nd_request_timeout fix (#1276) fix * Remove btcli query and btcli set_weights (#1144) . --------- Co-authored-by: Eugene-hu <85906264+Eugene-hu@users.noreply.github.com> Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: joeylegere Co-authored-by: Eugene Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> * Remove codecov (#1282) * Use alt new preseal (#1269) * use new preseal for reg * bump cubit req * fix arg order issue * cubit req back * use alt impl * fix typehint * use 512 * modify tests for new format * refactor functions to use helpers and remove useless * refactor functions * add test for CPU solver * modify tests for privitized module and methods * private register cuda * move formatting funcs * use powsolution * privitize most methods * fix test * fix perms * remove test script * remove debug * fix call * fix seal * fix combined hash * move to method * fix test using real example * update mock bins * use new builder * fix block update tests * fix some patching in tests * mock live display for some tests * fix chain mock * update linux bin * add mock network flag * set max diff at 0 for mock netuid 1 * set min diff too * add try catch for setup * add some logging during tests * don't submit on cli register * update test durations * fix test to use mock keypair * return mock wallet * should use subtensor instance during rereg * update node subtensor bins * use fixtures and multiple subtensor instances * changelog update * skip CLI tests (#1284) * skip tests * dont test mock functions * update test durations * [Release] v4.0.0 (#1271) * bump version * Fix permissions for release github script (#1224) Co-authored-by: Cameron Fairchild * should be 4.1.0 * Revert "should be 4.1.0" This reverts commit 3db08ea24f4fc4775bd46858e6c77cfa165d85ed. * Staging into Release branch (#1275) * (un)Staking multiple avoid tx limit (#1244) * add tx rate limit * wait for tx limit if not done multi stake/unstake * dont "decrypt" hotkey * additional logging for prometheus (#1246) * Dataset fix (#1249) * fix * added try except * Grab delegates details from GitHub (#1245) * add url to init * add dataclass and util functions * use in cli * remove delegates json --------- Co-authored-by: joeylegere * Add raw spec for local test and new bins (#1243) * add spec and new bins * fix config netuid * use dot get * check if config netuid is list * add start to mockstatus * add attr to mock neuron * add info to mock from neurons * change ordering of neuron dict to namespace * remove test for wandb for axon * use regex for looser match * fix blacklist metagraph mock * use real mock netuid * use mock network and netuid in constructor * fix patch * patch delegate check * use mock network and netuid * remove check for wallet hotkey * fix tests for subtensor init * dont set netuid for overview test * typo in docstring * add mock status stop * add low mock tx limit * oops typo * use dot get * add wait for final and incl args * use args during setup * update bins and use 100ms blocktime * pass block arg * remove bittensor.logging and a old test * use random port * backward fix * fix block time to 1s * compile no symb on linux * compile no symb mac * remove useless init on var * use dot get for new flags * update test durations * update test durations * use dot get for config * output error msg * mock to_default * remove to defaults in help * reduce neruons, remove flaky test * deactivate test * mvoe key pair tests out of the subtensor interface --------- Co-authored-by: Eugene * Fix list_delegates on non-archive nodes (#1232) * Change how pull of archival data is handled * fix for list_delegates too * . * use empty dict * fix spacing * specify exception * log out * add space in log message * use warning instead * Blacklist fixes + depreciation of old signatures (#1240) * fixes blacklist error message + remove * remove checks for parse signature * remove sign v1 tests * fix for the syanpse checks * fix tests and remove duplicate sign * [BIT-636] Change u16 weight normalization to max-upscaling (#1241) * Change u16 weight normalization to max-upscaling Use full u16 bitwidth so that max_weight=U16_MAX, then rely on subtensor epoch to properly normalize weights in I32F32. This means that weights submission extrinsic to subtensor does not have to be pre-normalized. * Skip zero sum in weight conversion * Round u16 weights * remove duplicate command #1228 (#1231) * remove duplicate command #1228 * Extract create_parser for cli testing * mark as private * use in tests and test for duplicates * fix test using mock prompt answers * test_forward_priority_2nd_request_timeout fix (#1276) fix * Remove btcli query and btcli set_weights (#1144) . --------- Co-authored-by: Eugene-hu <85906264+Eugene-hu@users.noreply.github.com> Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: joeylegere Co-authored-by: Eugene Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> * Remove codecov (#1282) * Use alt new preseal (#1269) * use new preseal for reg * bump cubit req * fix arg order issue * cubit req back * use alt impl * fix typehint * use 512 * modify tests for new format * refactor functions to use helpers and remove useless * refactor functions * add test for CPU solver * modify tests for privitized module and methods * private register cuda * move formatting funcs * use powsolution * privitize most methods * fix test * fix perms * remove test script * remove debug * fix call * fix seal * fix combined hash * move to method * fix test using real example * update mock bins * use new builder * fix block update tests * fix some patching in tests * mock live display for some tests * fix chain mock * update linux bin * add mock network flag * set max diff at 0 for mock netuid 1 * set min diff too * add try catch for setup * add some logging during tests * don't submit on cli register * update test durations * fix test to use mock keypair * return mock wallet * should use subtensor instance during rereg * update node subtensor bins * use fixtures and multiple subtensor instances * changelog update * skip CLI tests (#1284) * skip tests * dont test mock functions * update test durations --------- Co-authored-by: Eduardo García Co-authored-by: Eugene-hu <85906264+Eugene-hu@users.noreply.github.com> Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: joeylegere Co-authored-by: Eugene Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> * fix my delegates * fix perms on changelog script * update version * fix changelog script * Catch bad endpoint protocol (#1296) * catch protocol not good * add protocol 4 * catch assertion and return bool * catch assertion errors * changelog --------- Co-authored-by: Eduardo García Co-authored-by: Eugene-hu <85906264+Eugene-hu@users.noreply.github.com> Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: joeylegere Co-authored-by: Eugene Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> * Update DEVELOPMENT_WORKFLOW.md * final fixes * staging updates and fixes (#1540) * fix cli test * fix double-counted hotkeys per subnet and non-iterable stake obj (#1539) * fix double-counted hotkeys per subnet and non-iterable stake obj * run black * Add root get_weights command to btcli (#1536) * Add root get_weights command to btcli * Use a percentage for viewing weights instead of float values * run black, fix cli test --------- Co-authored-by: ifrit98 * Fix typo (#1543) Co-authored-by: philanthrope * remove duplicated debug message in dendrite (#1544) * Cli fix (#1541) don't break on mismatched coldkey from local wallet <> chain * update faucet helpstr (#1542) * Added mechanism to sum all delegated tao (#1547) Co-authored-by: Ala Shaabana * Dict hash fix (#1548) * use dict() when hasing body objects to not convert arbitrary objects to str * recreate synapse in axon dependency to avoid duplicating code * black * Merge master (#1552) Release/6.1.0 (#1550) * Fix typo (#1543) * remove duplicated debug message in dendrite (#1544) * Cli fix (#1541) don't break on mismatched coldkey from local wallet <> chain * update faucet helpstr (#1542) * Added mechanism to sum all delegated tao (#1547) * Dict hash fix (#1548) * use dict() when hasing body objects to not convert arbitrary objects to str * recreate synapse in axon dependency to avoid duplicating code * black * update version * update changelog --------- Co-authored-by: Cameron Fairchild Co-authored-by: Eugene Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: Cameron Fairchild Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> Co-authored-by: Eduardo García Co-authored-by: Ayden Brewer Co-authored-by: Steffen Cruz Co-authored-by: Ala Shaabana * Streaming fix (#1551) * yield chunks immediately in process_streaming_responss so clients can access * break streaming into separate call funcs * update docstrings, types * black * duplicate debug msg * add warning for mismatched streaming arg + subclass * Fix typos (#1553) * Release/6.1.0 (#1550) Co-authored-by: ifrit98 * Fix typo (#1543) Co-authored-by: philanthrope * remove duplicated debug message in dendrite (#1544) * Cli fix (#1541) don't break on mismatched coldkey from local wallet <> chain * update faucet helpstr (#1542) * Added mechanism to sum all delegated tao (#1547) Co-authored-by: Ala Shaabana * Dict hash fix (#1548) * use dict() when hasing body objects to not convert arbitrary objects to str * recreate synapse in axon dependency to avoid duplicating code * black * update version * update changelog --------- Co-authored-by: Cameron Fairchild Co-authored-by: Eugene Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: Cameron Fairchild Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> Co-authored-by: Eduardo García Co-authored-by: Ayden Brewer Co-authored-by: Steffen Cruz Co-authored-by: Ala Shaabana * fix typos --------- Co-authored-by: philanthrope Co-authored-by: Cameron Fairchild Co-authored-by: Eugene Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: Cameron Fairchild Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> Co-authored-by: Eduardo García Co-authored-by: Ayden Brewer Co-authored-by: Steffen Cruz Co-authored-by: Ala Shaabana * Normalize weights in r get weights table (#1556) * Normalize weights in r get weights table * use numpy and make table look nicer * apply black * add max 1 to prevent div0 --------- Co-authored-by: Cameron Fairchild * Dendrite & Synapse updates and fixes (#1555) * remove tensor header objects to not overflow headers * update tests to reflect removal of tensor headers * ensure consistent method for calling in synapse methods * fix dendrite UnClosesedSession error * fix docstring and add tests for close/aclose * rm extra delete * run black * add default synapse dict() consistency test * call del on session after close_session(), fix tests * update dendrite dummy clsname * add dendrite.query finally block * fix test * rm root flag in metagraph (#1558) * rm root flag in metagraph * run black * typo * Max Faucet Runs == 3 (#1560) add exceptions * replace unknown wallet params (chain mismatch) with key values (#1559) * replace unknown wallet params (chain mismatch) with key values * run black * rm debug prints * Remove PoW registration cli and associated extrinsic (#1557) * Remove PoW registration cli and associated extrinsic * run black * no mo pow, no mo pow tests * remove now deprecated PoW reregister routine * remove deprecated tests * more test fixes * remove _do_pow call * return PoW but still kill reregister (unused) * run black * return test to networks choices in btcli, fix chain_endpoint selection * fix pow args * Add btcli wallet balance (#1564) * begin adding balance command * skip validator that hasn't set weights yet on root * finish balances command * formatter * issue warning for nonexistent coldkeypub.txt rather than break * Dendrite fixes (#1561) * make sure a session exists before trying to close it * don't double iterate over async generator, simply return it * black * less DRY violations * fix typehints * add versioning * update changelog * remove unused registration utils * fix typos --------- Co-authored-by: Cameron Fairchild Co-authored-by: Eugene Co-authored-by: Eugene-hu <85906264+Eugene-hu@users.noreply.github.com> Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: joeylegere Co-authored-by: Cameron Fairchild Co-authored-by: “quac88” <“mac2@thrasher.com”> Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> Co-authored-by: Eduardo García Co-authored-by: Ayden Brewer Co-authored-by: Steffen Cruz Co-authored-by: Ala Shaabana Co-authored-by: Ala Shaabana Co-authored-by: omahs <73983677+omahs@users.noreply.github.com> Co-authored-by: Cameron Fairchild Co-authored-by: Cameron Fairchild * add show_delegates docstring * docstring should go under function name * re-add missing delegate-take-command * delegates docs completed * identity * inspect * list docstr * metagraph * update metagraph doc, add misc and network * overiew, regiser, and root docstrings * update senate * update stake and transfer * wallet * delegated stake fix --------- Co-authored-by: Cameron Fairchild Co-authored-by: Eugene Co-authored-by: Eugene-hu <85906264+Eugene-hu@users.noreply.github.com> Co-authored-by: isabella618033 <49876827+isabella618033@users.noreply.github.com> Co-authored-by: joeylegere Co-authored-by: Cameron Fairchild Co-authored-by: “quac88” <“mac2@thrasher.com”> Co-authored-by: opentaco <93473497+opentaco@users.noreply.github.com> Co-authored-by: Eduardo García Co-authored-by: Ayden Brewer Co-authored-by: Steffen Cruz Co-authored-by: Ala Shaabana Co-authored-by: Ala Shaabana Co-authored-by: omahs <73983677+omahs@users.noreply.github.com> Co-authored-by: Cameron Fairchild Co-authored-by: Cameron Fairchild --- bittensor/cli.py | 1 + bittensor/commands/__init__.py | 2 +- bittensor/commands/delegates.py | 247 +++++++++++++++++++++++++++++++- bittensor/commands/identity.py | 76 ++++++++++ bittensor/commands/inspect.py | 38 +++++ bittensor/commands/list.py | 25 ++++ bittensor/commands/metagraph.py | 44 ++++++ bittensor/commands/misc.py | 109 +++----------- bittensor/commands/network.py | 179 +++++++++++++++++++++++ bittensor/commands/overview.py | 37 +++++ bittensor/commands/register.py | 94 ++++++++++++ bittensor/commands/root.py | 99 +++++++++++++ bittensor/commands/senate.py | 109 ++++++++++++++ bittensor/commands/stake.py | 53 +++++++ bittensor/commands/transfer.py | 22 +++ bittensor/commands/unstake.py | 26 ++++ bittensor/commands/wallets.py | 173 ++++++++++++++++++++++ 17 files changed, 1240 insertions(+), 94 deletions(-) diff --git a/bittensor/cli.py b/bittensor/cli.py index 71fcf9e116..48313080ae 100644 --- a/bittensor/cli.py +++ b/bittensor/cli.py @@ -67,6 +67,7 @@ "weights": RootSetWeightsCommand, "get_weights": RootGetWeightsCommand, "senate_vote": VoteCommand, + "senate": SenateCommand, "register": RootRegisterCommand, "proposals": ProposalsCommand, "delegate": DelegateStakeCommand, diff --git a/bittensor/commands/__init__.py b/bittensor/commands/__init__.py index 88a0bcea46..322a1c0ff5 100644 --- a/bittensor/commands/__init__.py +++ b/bittensor/commands/__init__.py @@ -88,7 +88,7 @@ from .inspect import InspectCommand from .metagraph import MetagraphCommand from .list import ListCommand -from .misc import UpdateCommand, ListSubnetsCommand +from .misc import UpdateCommand from .senate import ( SenateCommand, ProposalsCommand, diff --git a/bittensor/commands/delegates.py b/bittensor/commands/delegates.py index 740d3e3c8a..8d817ce005 100644 --- a/bittensor/commands/delegates.py +++ b/bittensor/commands/delegates.py @@ -53,7 +53,51 @@ def show_delegates( prev_delegates: Optional[List["bittensor.DelegateInfo"]], width: Optional[int] = None, ): - """Pretty prints a table of delegates sorted by total stake.""" + """ + Displays a formatted table of Bittensor network delegates with detailed statistics + to the console. The table is sorted by total stake in descending order and provides + a snapshot of delegate performance and status, helping users make informed decisions + for staking or nominating. + + This is a helper function that is called by the 'list_delegates' and 'my_delegates' + and not intended to be used directly in user code unless specifically required. + + Parameters: + - delegates (List[bittensor.DelegateInfo]): A list of delegate information objects + to be displayed. + - prev_delegates (Optional[List[bittensor.DelegateInfo]]): A list of delegate + information objects from a previous state, used to calculate changes in stake. + Defaults to None. + - width (Optional[int]): The width of the console output table. Defaults to None, + which will make the table expand to the maximum width of the console. + + The output table includes the following columns: + - INDEX: The numerical index of the delegate. + - DELEGATE: The name of the delegate. + - SS58: The truncated SS58 address of the delegate. + - NOMINATORS: The number of nominators supporting the delegate. + - DELEGATE STAKE(τ): The stake that is directly delegated to the delegate. + - TOTAL STAKE(τ): The total stake held by the delegate, including nominators' stake. + - CHANGE/(4h): The percentage change in the delegate's stake over the past 4 hours. + - SUBNETS: A list of subnets the delegate is registered with. + - VPERMIT: Validator permits held by the delegate for the subnets. + - NOMINATOR/(24h)/kτ: The earnings per 1000 τ staked by nominators in the last 24 hours. + - DELEGATE/(24h): The earnings of the delegate in the last 24 hours. + - Desc: A brief description provided by the delegate. + + Usage: + This function is typically used within the Bittensor CLI to show current delegate + options to users who are considering where to stake their tokens. + + Example usage: + >>> show_delegates(current_delegates, previous_delegates, width=80) + + Note: + This function is primarily for display purposes within a command-line interface and does + not return any values. It relies on the 'rich' Python library to render the table in the + console. + """ + delegates.sort(key=lambda delegate: delegate.total_stake, reverse=True) prev_delegates_dict = {} if prev_delegates is not None: @@ -172,6 +216,36 @@ def show_delegates( class DelegateStakeCommand: + """ + Executes the 'delegate' command, which stakes Tao to a specified delegate on the + Bittensor network. This action allocates the user's Tao to support a delegate, + potentially earning staking rewards in return. + + Optional Arguments: + - wallet.name: The name of the wallet to use for the command. + - delegate_ss58key: The SS58 address of the delegate to stake to. + - amount: The amount of Tao to stake. + - all: If specified, the command stakes all available Tao. + + The command interacts with the user to determine the delegate and the amount of Tao + to be staked. If the '--all' flag is used, it delegates the entire available balance. + + Usage: + The user must specify the delegate's SS58 address and the amount of Tao to stake. The + function sends a transaction to the subtensor network to delegate the specified amount + to the chosen delegate. These values are prompted if not provided. + + Example usage: + >>> btcli delegate --delegate_ss58key --amount + >>> btcli delegate --delegate_ss58key --all + + Note: + This command modifies the blockchain state and may incur transaction fees. It requires + user confirmation and interaction, and is designed to be used within the Bittensor CLI + environment. The user should ensure the delegate's address and the amount to be staked + are correct before executing the command. + """ + @staticmethod def run(cli): """Delegates stake to a chain delegate.""" @@ -269,6 +343,37 @@ def check_config(config: "bittensor.config"): class DelegateUnstakeCommand: + """ + Executes the 'undelegate' command, allowing users to withdraw their staked Tao from + a delegate on the Bittensor network. This process is known as "undelegating" and it + reverses the delegation process, freeing up the staked tokens. + + Optional Arguments: + - wallet.name: The name of the wallet to use for the command. + - delegate_ss58key: The SS58 address of the delegate to undelegate from. + - amount: The amount of Tao to undelegate. + - all: If specified, the command undelegates all staked Tao from the delegate. + + The command prompts the user for the amount of Tao to undelegate and the SS58 address + of the delegate from which to undelegate. If the '--all' flag is used, it will attempt + to undelegate the entire staked amount from the specified delegate. + + Usage: + The user must provide the delegate's SS58 address and the amount of Tao to undelegate. + The function will then send a transaction to the Bittensor network to process the + undelegation. + + Example usage: + >>> btcli undelegate --delegate_ss58key --amount + >>> btcli undelegate --delegate_ss58key --all + + Note: + This command can result in a change to the blockchain state and may incur transaction + fees. It is interactive and requires confirmation from the user before proceeding. It + should be used with care as undelegating can affect the delegate's total stake and + potentially the user's staking rewards. + """ + @staticmethod def run(cli): """Undelegates stake from a chain delegate.""" @@ -366,6 +471,43 @@ def check_config(config: "bittensor.config"): class ListDelegatesCommand: + """ + Displays a formatted table of Bittensor network delegates, providing a comprehensive + overview of delegate statistics and information. This table helps users make informed + decisions on which delegates to allocate their Tao stake. + + Optional Arguments: + - wallet.name: The name of the wallet to use for the command. + - subtensor.network: The name of the network to use for the command. + + The table columns include: + - INDEX: The delegate's index in the sorted list. + - DELEGATE: The name of the delegate. + - SS58: The delegate's unique SS58 address (truncated for display). + - NOMINATORS: The count of nominators backing the delegate. + - DELEGATE STAKE(τ): The amount of delegate's own stake (not the TAO delegated from any nominators). + - TOTAL STAKE(τ): The delegate's cumulative stake, including self-staked and nominators' stakes. + - CHANGE/(4h): The percentage change in the delegate's stake over the last four hours. + - SUBNETS: The subnets to which the delegate is registered. + - VPERMIT: Indicates the subnets for which the delegate has validator permits. + - NOMINATOR/(24h)/kτ: The earnings per 1000 τ staked by nominators in the last 24 hours. + - DELEGATE/(24h): The total earnings of the delegate in the last 24 hours. + - DESCRIPTION: A brief description of the delegate's purpose and operations. + + Sorting is done based on the 'TOTAL STAKE' column in descending order. Changes in stake + are highlighted: increases in green and decreases in red. Entries with no previous data + are marked with 'NA'. Each delegate's name is a hyperlink to their respective URL, if available. + + Example usage: + >>> btcli root list_delegates + >>> btcli root list_delegates --wallet.name my_wallet + >>> btcli root list_delegates --subtensor.network finney # can also be `test` or `local` + + Note: + This function is part of the Bittensor CLI tools and is intended for use within a console + application. It prints directly to the console and does not return any value. + """ + @staticmethod def run(cli): r""" @@ -405,6 +547,36 @@ def check_config(config: "bittensor.config"): class NominateCommand: + """ + Executes the 'nominate' command, which facilitates a wallet to become a delegate + on the Bittensor network. This command handles the nomination process, including + wallet unlocking and verification of the hotkey's current delegate status. + + The command performs several checks: + - Verifies that the hotkey is not already a delegate to prevent redundant nominations. + - Tries to nominate the wallet and reports success or failure. + + Upon success, the wallet's hotkey is registered as a delegate on the network. + + Optional Arguments: + - wallet.name: The name of the wallet to use for the command. + - wallet.hotkey: The name of the hotkey to use for the command. + + Usage: + To run the command, the user must have a configured wallet with both hotkey and + coldkey. If the wallet is not already nominated, this command will initiate the + process. + + Example usage: + >>> btcli root nominate + >>> btcli root nominate --wallet.name my_wallet --wallet.hotkey my_hotkey + + Note: + This function is intended to be used as a CLI command. It prints the outcome directly + to the console and does not return any value. It should not be called programmatically + in user code due to its interactive nature and side effects on the network state. + """ + @staticmethod def run(cli): r"""Nominate wallet.""" @@ -467,6 +639,47 @@ def check_config(config: "bittensor.config"): class MyDelegatesCommand: + """ + Executes the 'my_delegates' command within the Bittensor CLI, which retrieves and + displays a table of delegated stakes from a user's wallet(s) to various delegates + on the Bittensor network. The command provides detailed insights into the user's + staking activities and the performance of their chosen delegates. + + Optional Arguments: + - wallet.name: The name of the wallet to use for the command. + - all: If specified, the command aggregates information across all wallets. + + The table output includes the following columns: + - Wallet: The name of the user's wallet. + - OWNER: The name of the delegate's owner. + - SS58: The truncated SS58 address of the delegate. + - Delegation: The amount of Tao staked by the user to the delegate. + - τ/24h: The earnings from the delegate to the user over the past 24 hours. + - NOMS: The number of nominators for the delegate. + - OWNER STAKE(τ): The stake amount owned by the delegate. + - TOTAL STAKE(τ): The total stake amount held by the delegate. + - SUBNETS: The list of subnets the delegate is a part of. + - VPERMIT: Validator permits held by the delegate for various subnets. + - 24h/kτ: Earnings per 1000 Tao staked over the last 24 hours. + - Desc: A description of the delegate. + + The command also sums and prints the total amount of Tao delegated across all wallets. + + Usage: + The command can be run as part of the Bittensor CLI suite of tools and requires + no parameters if a single wallet is used. If multiple wallets are present, the + --all flag can be specified to aggregate information across all wallets. + + Example usage: + >>> btcli my_delegates + >>> btcli my_delegates --all + >>> btcli my_delegates --wallet.name my_wallet + + Note: + This function is typically called by the CLI parser and is not intended to be used + directly in user code. + """ + @staticmethod def run(cli): """Delegates stake to a chain delegate.""" @@ -625,6 +838,34 @@ def check_config(config: "bittensor.config"): class SetDelegateTakeCommand: + """ + Executes the 'set_delegate_take' command, which sets the commission rate (take percentage) + for a user's delegate on the Bittensor network. This commission is the fraction of rewards + that the delegate takes from staking operations. + + Optional Arguments: + - wallet.name: The name of the wallet to use for the command. + - delegate.take: The take percentage to set for the delegate. + + The function performs several checks: + - Ensures the take value is within the valid range (0.0 to 1.0). + - Verifies that the hotkey associated with the wallet is registered as a delegate. + - Sets the take percentage on the network if the above conditions are met. + + Usage: + The user is prompted to enter the desired take value, which must be a float between 0 and 1. + The value is then scaled and cast to an integer ratio before being sent to the network. + + Example usage: + >>> btcli root set_delegate_take --take 0.1 + >>> btcli root set_delegate_take --wallet.name my_wallet --wallet.hotkey my_hotkey --take 0.1 + + Note: + This command will result in a change to the blockchain state and may incur transaction fees. + It is interactive and requires input from the user. This function is intended to be used as + part of the Bittensor CLI and not as a standalone function within user code. + """ + @staticmethod def run(cli): r"""Set your delegate's take percentage.""" @@ -673,7 +914,7 @@ def add_args(parser: argparse.ArgumentParser): "set_delegate_take", help="""Set your delegate's take percentage.""" ) set_delegate_take_parser.add_argument( - "--delegate.take", dest="take", type=str, required=False + "--take", dest="take", type=str, required=False ) bittensor.wallet.add_args(set_delegate_take_parser) @@ -689,6 +930,6 @@ def check_config(config: "bittensor.config"): hotkey = Prompt.ask("Enter hotkey name", default=defaults.wallet.hotkey) config.wallet.hotkey = str(hotkey) - if not config.is_set("delegate.take") and not config.no_prompt: + if not config.is_set("take") and not config.no_prompt: take = Prompt.ask("Enter new delegate take value (0 - 1)") config.take = take diff --git a/bittensor/commands/identity.py b/bittensor/commands/identity.py index 20309d6eaa..867cff4cd5 100644 --- a/bittensor/commands/identity.py +++ b/bittensor/commands/identity.py @@ -8,6 +8,52 @@ class SetIdentityCommand: + """ + Executes the 'set_identity' command within the Bittensor network, which allows for the + creation or update of a delegate's on-chain identity. This identity includes various + attributes such as display name, legal name, web URL, PGP fingerprint, and contact + information, among others. + + Optional Arguments: + --display: The display name for the identity. + --legal: The legal name for the identity. + --web: The web URL for the identity. + --riot: The riot handle for the identity. + --email: The email address for the identity. + --pgp_fingerprint: The PGP fingerprint for the identity. + --image: The image URL for the identity. + --info: The info for the identity. + --twitter: The twitter URL for the identity. + + The command prompts the user for the different identity attributes and validates the + input size for each attribute. It provides an option to update an existing validator + hotkey identity. If the user consents to the transaction cost, the identity is updated + on the blockchain. + + Each field has a maximum size of 64 bytes. The PGP fingerprint field is an exception + and has a maximum size of 20 bytes. The user is prompted to enter the PGP fingerprint + as a hex string, which is then converted to bytes. The user is also prompted to enter + the coldkey or hotkey ss58 address for the identity to be updated. If the user does + not have a hotkey, the coldkey address is used by default. + + If setting a validator identity, the hotkey will be used by default. If the user is + setting an identity for a subnet, the coldkey will be used by default. + + Usage: + The user should call this command from the command line and follow the interactive + prompts to enter or update the identity information. The command will display the + updated identity details in a table format upon successful execution. + + Example usage: + >>> btcli root set_identity + + Note: + This command should only be used if the user is willing to incur the 1 TAO transaction + fee associated with setting an identity on the blockchain. It is a high-level command + that makes changes to the blockchain state and should not be used programmatically as + part of other scripts or applications. + """ + def run(cli): r"""Create a new or update existing identity on-chain.""" console = bittensor.__console__ @@ -182,6 +228,36 @@ def add_args(parser: argparse.ArgumentParser): class GetIdentityCommand: + """ + Executes the 'get_identity' command, which retrieves and displays the identity details + of a user's coldkey or hotkey associated with the Bittensor network. This function + queries the subtensor chain for information such as the stake, rank, and trust associated + with the provided key. + + Optional Arguments: + --key: The ss58 address of the coldkey or hotkey to query. + + The command performs the following actions: + - Connects to the subtensor network and retrieves the identity information. + - Displays the information in a structured table format. + + The displayed table includes: + - Address: The ss58 address of the queried key. + - Item: Various attributes of the identity such as stake, rank, and trust. + - Value: The corresponding values of the attributes. + + Usage: + The user must provide an ss58 address as input to the command. If the address is not + provided in the configuration, the user is prompted to enter one. + + Example usage: + >>> btli get_identity --key + + Note: + This function is designed for CLI use and should be executed in a terminal. It is + primarily used for informational purposes and has no side effects on the network state. + """ + def run(cli): r"""Queries the subtensor chain for user identity.""" console = bittensor.__console__ diff --git a/bittensor/commands/inspect.py b/bittensor/commands/inspect.py index 4b24a2da17..c39863bea6 100644 --- a/bittensor/commands/inspect.py +++ b/bittensor/commands/inspect.py @@ -64,6 +64,44 @@ def _get_hotkey_wallets_for_wallet(wallet) -> List["bittensor.wallet"]: class InspectCommand: + """ + Executes the 'inspect' command, which compiles and displays a detailed report of a user's + wallet pairs (coldkey, hotkey) on the Bittensor network. This report includes balance and + staking information for both the coldkey and hotkey associated with the wallet. + + Optional arguments: + -all: If set to True, the command will inspect all wallets located within the specified + path. If set to False, the command will inspect only the wallet specified by the user. + + The command gathers data on: + - Coldkey balance and delegated stakes. + - Hotkey stake and emissions per neuron on the network. + - Delegate names and details fetched from the network. + + The resulting table includes columns for: + - Coldkey: The coldkey associated with the user's wallet. + - Balance: The balance of the coldkey. + - Delegate: The name of the delegate to which the coldkey has staked funds. + - Stake: The amount of stake held by both the coldkey and hotkey. + - Emission: The emission or rewards earned from staking. + - Netuid: The network unique identifier of the subnet where the hotkey is active. + - Hotkey: The hotkey associated with the neuron on the network. + + Usage: + This command can be used to inspect a single wallet or all wallets located within a + specified path. It is useful for a comprehensive overview of a user's participation + and performance in the Bittensor network. + + Example usage: + >>> btcli inspect + >>> btcli inspect --all + + Note: + The 'inspect' command is for displaying information only and does not perform any + transactions or state changes on the Bittensor network. It is intended to be used as + part of the Bittensor CLI and not as a standalone function within user code. + """ + @staticmethod def run(cli): r"""Inspect a cold, hot pair.""" diff --git a/bittensor/commands/list.py b/bittensor/commands/list.py index 209ddf979d..1625d56375 100644 --- a/bittensor/commands/list.py +++ b/bittensor/commands/list.py @@ -25,6 +25,31 @@ class ListCommand: + """ + Executes the 'list' command which enumerates all wallets and their respective hotkeys + present in the user's Bittensor configuration directory. The command organizes the + information in a tree structure, displaying each wallet along with the SS58 addresses + for the coldkey public key and any hotkeys associated with it. + + Optional arguments: + -p, --path: The path to the Bittensor configuration directory. Defaults to '~/.bittensor'. + + The output is presented in a hierarchical tree format, with each wallet as a root node, + and any associated hotkeys as child nodes. The SS58 address is displayed for each + coldkey and hotkey that is not encrypted and exists on the device. + + Usage: + Upon invocation, the command scans the wallet directory and prints a list of all wallets, + indicating whether the public keys are available ('?' denotes unavailable or encrypted keys). + + Example usage: + >>> btcli list --path ~/.bittensor + + Note: + This command is read-only and does not modify the filesystem or the network state. It is + intended for use within the Bittensor CLI to provide a quick overview of the user's wallets. + """ + @staticmethod def run(cli): r"""Lists wallets.""" diff --git a/bittensor/commands/metagraph.py b/bittensor/commands/metagraph.py index 61b35695e1..4457bccd2f 100644 --- a/bittensor/commands/metagraph.py +++ b/bittensor/commands/metagraph.py @@ -25,6 +25,50 @@ class MetagraphCommand: + """ + Executes the 'metagraph' command to retrieve and display the entire metagraph + for a specified network. This metagraph contains detailed information about + all the neurons (nodes) participating in the network, including their stakes, + trust scores, and more. + + Optional arguments: + --netuid: The netuid of the network to query. Defaults to the default network UID. + --subtensor.network: The name of the network to query. Defaults to the default network name. + + The table displayed includes the following columns for each neuron: + - UID: Unique identifier of the neuron. + - STAKE(τ): Total stake of the neuron in Tau (τ). + - RANK: Rank score of the neuron. + - TRUST: Trust score assigned to the neuron by other neurons. + - CONSENSUS: Consensus score of the neuron. + - INCENTIVE: Incentive score representing the neuron's incentive alignment. + - DIVIDENDS: Dividends earned by the neuron. + - EMISSION(p): Emission in Rho (p) received by the neuron. + - VTRUST: Validator trust score indicating the network's trust in the neuron as a validator. + - VAL: Validator status of the neuron. + - UPDATED: Number of blocks since the neuron's last update. + - ACTIVE: Activity status of the neuron. + - AXON: Network endpoint information of the neuron. + - HOTKEY: Partial hotkey (public key) of the neuron. + - COLDKEY: Partial coldkey (public key) of the neuron. + + The command also prints network-wide statistics such as total stake, issuance, + and difficulty. + + Usage: + The user must specify the network UID to query the metagraph. If not specified, + the default network UID is used. + + Example usage: + >>> btcli metagraph --netuid 0 # Root network + >>> btcli metagraph --netuid 1 --subtensor.network test + + Note: + This command provides a snapshot of the network's state at the time of calling. + It is useful for network analysis and diagnostics. It is intended to be used as + part of the Bittensor CLI and not as a standalone function within user code. + """ + @staticmethod def run(cli): r"""Prints an entire metagraph.""" diff --git a/bittensor/commands/misc.py b/bittensor/commands/misc.py index 9d62581201..1b2ae156da 100644 --- a/bittensor/commands/misc.py +++ b/bittensor/commands/misc.py @@ -27,6 +27,25 @@ class UpdateCommand: + """ + Executes the 'update' command to update the local Bittensor package. This command performs a series of operations to ensure that the user's local Bittensor installation is updated to the latest version from the master branch of its GitHub repository. It primarily involves pulling the latest changes from the repository and reinstalling the package. + + Usage: + Upon invocation, the command first checks the user's configuration for the 'no_prompt' setting. If 'no_prompt' is set to True, or if the user explicitly confirms with 'Y' when prompted, the command proceeds to update the local Bittensor package. It changes the current directory to the Bittensor package directory, checks out the master branch of the Bittensor repository, pulls the latest changes, and then reinstalls the package using pip. + + The command structure is as follows: + 1. Change directory to the Bittensor package directory. + 2. Check out the master branch of the Bittensor GitHub repository. + 3. Pull the latest changes with the '--ff-only' option to ensure a fast-forward update. + 4. Reinstall the Bittensor package using pip. + + Example usage: + >>> btcli legacy update + + Note: + This command is intended to be used within the Bittensor CLI to facilitate easy updates of the Bittensor package. It should be used with caution as it directly affects the local installation of the package. It is recommended to ensure that any important data or configurations are backed up before running this command. + """ + @staticmethod def run(cli): if cli.config.no_prompt or cli.config.answer == "Y": @@ -52,93 +71,3 @@ def add_args(parser: argparse.ArgumentParser): ) bittensor.subtensor.add_args(update_parser) - - -class ListSubnetsCommand: - @staticmethod - def run(cli): - r"""List all subnet netuids in the network.""" - subtensor = bittensor.subtensor(config=cli.config) - subnets: List[bittensor.SubnetInfo] = subtensor.get_all_subnets_info() - - rows = [] - total_neurons = 0 - - for subnet in subnets: - total_neurons += subnet.max_n - # netuid, N, Max N, difficulty, network connect, tempo, emission, burn rate - rows.append( - ( - str(subnet.netuid), - str(subnet.subnetwork_n), - str(bittensor.utils.formatting.millify(subnet.max_n)), - str(bittensor.utils.formatting.millify(subnet.difficulty)), - str(subnet.tempo), - str( - [ - f"{cr[0]}: {cr[1] * 100:.1f}%" - for cr in subnet.connection_requirements.items() - ] - if len(subnet.connection_requirements) > 0 - else None - ), - f"{subnet.emission_value / bittensor.utils.RAOPERTAO * 100:0.2f}%", - f"{subnet.burn!s:8.8}", - f"{subnet.owner_ss58}", - ) - ) - - table = Table( - show_footer=True, - width=cli.config.get("width", None), - pad_edge=True, - box=None, - show_edge=True, - ) - table.title = "[white]Subnets - {}".format(subtensor.network) - # netuid, N, Max N, difficulty, network connect, tempo, emission, burn rate - table.add_column( - "[overline white]NETUID", - str(len(subnets)), - footer_style="overline white", - style="bold green", - justify="center", - ) - table.add_column( - "[overline white]NEURONS", - str(total_neurons), - footer_style="overline white", - style="white", - justify="center", - ) - table.add_column("[overline white]MAX_N", style="white", justify="center") - table.add_column("[overline white]DIFFICULTY", style="white", justify="center") - # table.add_column("[overline white]IMMUNITY", style='white') - # table.add_column("[overline white]BATCH SIZE", style='white') - # table.add_column("[overline white]SEQ_LEN", style='white') - table.add_column("[overline white]TEMPO", style="white", justify="center") - # table.add_column("[overline white]MODALITY", style='white') - table.add_column("[overline white]CON_REQ", style="white", justify="center") - # table.add_column("[overline white]STAKE", style="green", justify="center") - table.add_column( - "[overline white]EMISSION", style="white", justify="center" - ) # sums to 100% - table.add_column("[overline white]BURN(\u03C4)", style="white") - table.add_column("[overline white]OWNER(\u03C4)", style="white") - - for row in rows: - table.add_row(*row) - - bittensor.__console__.print(table) - - @staticmethod - def check_config(config: "bittensor.config"): - pass - - @staticmethod - def add_args(parser: argparse.ArgumentParser): - list_subnets_parser = parser.add_parser( - "list_subnets", help="""List all subnets on the network""" - ) - - bittensor.subtensor.add_args(list_subnets_parser) diff --git a/bittensor/commands/network.py b/bittensor/commands/network.py index d2bbdf4a85..37507f7241 100644 --- a/bittensor/commands/network.py +++ b/bittensor/commands/network.py @@ -28,6 +28,31 @@ class RegisterSubnetworkCommand: + """ + Executes the 'register_subnetwork' command to register a new subnetwork on the Bittensor network. This command facilitates the creation and registration of a subnetwork, which involves interaction with the user's wallet and the Bittensor subtensor. It ensures that the user has the necessary credentials and configurations to successfully register a new subnetwork. + + Usage: + Upon invocation, the command performs several key steps to register a subnetwork: + 1. It copies the user's current configuration settings. + 2. It accesses the user's wallet using the provided configuration. + 3. It initializes the Bittensor subtensor object with the user's configuration. + 4. It then calls the `register_subnetwork` function of the subtensor object, passing the user's wallet and a prompt setting based on the user's configuration. + + If the user's configuration does not specify a wallet name and 'no_prompt' is not set, the command will prompt the user to enter a wallet name. This name is then used in the registration process. + + The command structure includes: + - Copying the user's configuration. + - Accessing and preparing the user's wallet. + - Initializing the Bittensor subtensor. + - Registering the subnetwork with the necessary credentials. + + Example usage: + >>> btcli subnets create + + Note: + This command is intended for advanced users of the Bittensor network who wish to contribute by adding new subnetworks. It requires a clear understanding of the network's functioning and the roles of subnetworks. Users should ensure that they have secured their wallet and are aware of the implications of adding a new subnetwork to the Bittensor ecosystem. + """ + @staticmethod def run(cli): r"""Register a subnetwork""" @@ -58,6 +83,32 @@ def add_args(cls, parser: argparse.ArgumentParser): class SubnetLockCostCommand: + """ + Executes the 'lock_cost' command to view the locking cost required for creating a new subnetwork on the Bittensor network. This command is designed to provide users with the current cost of registering a new subnetwork, which is a critical piece of information for anyone considering expanding the network's infrastructure. + + The current implementation anneals the cost of creating a subnet over a period of two days. If the cost is unappealing currently, check back in a day or two to see if it has reached an amenble level. + + Usage: + Upon invocation, the command performs the following operations: + 1. It copies the user's current Bittensor configuration. + 2. It initializes the Bittensor subtensor object with this configuration. + 3. It then retrieves the subnet lock cost using the `get_subnet_burn_cost()` method from the subtensor object. + 4. The cost is displayed to the user in a readable format, indicating the amount of cryptocurrency required to lock for registering a new subnetwork. + + In case of any errors during the process (e.g., network issues, configuration problems), the command will catch these exceptions and inform the user that it failed to retrieve the lock cost, along with the specific error encountered. + + The command structure includes: + - Copying and using the user's configuration for Bittensor. + - Retrieving the current subnet lock cost from the Bittensor network. + - Displaying the cost in a user-friendly manner. + + Example usage: + >>> btcli subnets lock_cost + + Note: + This command is particularly useful for users who are planning to contribute to the Bittensor network by adding new subnetworks. Understanding the lock cost is essential for these users to make informed decisions about their potential contributions and investments in the network. + """ + @staticmethod def run(cli): r"""View locking cost of creating a new subnetwork""" @@ -88,6 +139,38 @@ def add_args(cls, parser: argparse.ArgumentParser): class SubnetListCommand: + """ + Executes the 'list' command to list all subnets and their detailed information on the Bittensor network. + This command is designed to provide users with comprehensive information about each subnet within the + network, including its unique identifier (netuid), the number of neurons, maximum neuron capacity, + emission rate, tempo, recycle register cost (burn), proof of work (PoW) difficulty, and the name or + SS58 address of the subnet owner. + + Usage: + Upon invocation, the command performs the following actions: + 1. It initializes the Bittensor subtensor object with the user's configuration. + 2. It retrieves a list of all subnets in the network along with their detailed information. + 3. The command compiles this data into a table format, displaying key information about each subnet. + + In addition to the basic subnet details, the command also fetches delegate information to provide the + name of the subnet owner where available. If the owner's name is not available, the owner's SS58 + address is displayed. + + The command structure includes: + - Initializing the Bittensor subtensor and retrieving subnet information. + - Calculating the total number of neurons across all subnets. + - Constructing a table that includes columns for NETUID, N (current neurons), MAX_N (maximum neurons), + EMISSION, TEMPO, BURN, POW (proof of work difficulty), and SUDO (owner's name or SS58 address). + - Displaying the table with a footer that summarizes the total number of subnets and neurons. + + Example usage: + >>> btcli subnets list + + Note: + This command is particularly useful for users seeking an overview of the Bittensor network's structure + and the distribution of its resources and ownership information for each subnet. + """ + @staticmethod def run(cli): r"""List all subnet netuids in the network.""" @@ -171,6 +254,25 @@ def add_args(parser: argparse.ArgumentParser): class SubnetSudoCommand: + """ + Executes the 'set' command to set hyperparameters for a specific subnet on the Bittensor network. + This command allows subnet owners to modify various hyperparameters of theirs subnet, such as its tempo, + emission rates, and other network-specific settings. + + Usage: + The command first prompts the user to enter the hyperparameter they wish to change and its new value. + It then uses the user's wallet and configuration settings to authenticate and send the hyperparameter update + to the specified subnet. + + Example usage: + >>> btcli sudo set --netuid 1 --param 'tempo' --value '0.5' + + Note: + This command requires the user to specify the subnet identifier (netuid) and both the hyperparameter + and its new value. It is intended for advanced users who are familiar with the network's functioning + and the impact of changing these parameters. + """ + @staticmethod def run(cli): r"""Set subnet hyperparameters.""" @@ -217,6 +319,45 @@ def add_args(parser: argparse.ArgumentParser): class SubnetHyperparamsCommand: + """ + Executes the 'hyperparameters' command to view the current hyperparameters of a specific subnet on + the Bittensor network. This command is useful for users who wish to understand the configuration and + operational parameters of a particular subnet. + + Usage: + Upon invocation, the command fetches and displays a list of all hyperparameters for the specified subnet. + These include settings like tempo, emission rates, and other critical network parameters that define + the subnet's behavior. + + Example usage: + >>> btcli subnets hyperparameters --netuid 1 + + Subnet Hyperparameters - NETUID: 1 - finney + HYPERPARAMETER VALUE + rho 10 + kappa 32767 + immunity_period 7200 + min_allowed_weights 8 + max_weight_limit 455 + tempo 99 + min_difficulty 1000000000000000000 + max_difficulty 1000000000000000000 + weights_version 2013 + weights_rate_limit 100 + adjustment_interval 112 + activity_cutoff 5000 + registration_allowed True + target_regs_per_interval 2 + min_burn 1000000000 + max_burn 100000000000 + bonds_moving_avg 900000 + max_regs_per_block 1 + + Note: + The user must specify the subnet identifier (netuid) for which they want to view the hyperparameters. + This command is read-only and does not modify the network state or configurations. + """ + @staticmethod def run(cli): r"""View hyperparameters of a subnetwork.""" @@ -260,6 +401,44 @@ def add_args(parser: argparse.ArgumentParser): class SubnetGetHyperparamsCommand: + """ + Executes the 'get' command to retrieve the hyperparameters of a specific subnet on the Bittensor network. + This command is similar to the 'hyperparameters' command but may be used in different contexts within the CLI. + + Usage: + The command connects to the Bittensor network, queries the specified subnet, and returns a detailed list + of all its hyperparameters. This includes crucial operational parameters that determine the subnet's + performance and interaction within the network. + + Example usage: + >>> btcli sudo get --netuid 1 + + Subnet Hyperparameters - NETUID: 1 - finney + HYPERPARAMETER VALUE + rho 10 + kappa 32767 + immunity_period 7200 + min_allowed_weights 8 + max_weight_limit 455 + tempo 99 + min_difficulty 1000000000000000000 + max_difficulty 1000000000000000000 + weights_version 2013 + weights_rate_limit 100 + adjustment_interval 112 + activity_cutoff 5000 + registration_allowed True + target_regs_per_interval 2 + min_burn 1000000000 + max_burn 100000000000 + bonds_moving_avg 900000 + max_regs_per_block 1 + + Note: + Users need to provide the netuid of the subnet whose hyperparameters they wish to view. This command is + designed for informational purposes and does not alter any network settings or configurations. + """ + @staticmethod def run(cli): r"""View hyperparameters of a subnetwork.""" diff --git a/bittensor/commands/overview.py b/bittensor/commands/overview.py index 733ec81d7c..39fc465b07 100644 --- a/bittensor/commands/overview.py +++ b/bittensor/commands/overview.py @@ -36,6 +36,43 @@ class OverviewCommand: + """ + Executes the 'overview' command to present a detailed overview of the user's registered accounts on the Bittensor network. + This command compiles and displays comprehensive information about each neuron associated with the user's wallets, + including both hotkeys and coldkeys. It is especially useful for users managing multiple accounts or seeking a summary + of their network activities and stake distributions. + + Usage: + The command offers various options to customize the output. Users can filter the displayed data by specific netuids, + sort by different criteria, and choose to include all wallets in the user's configuration directory. The output is + presented in a tabular format with the following columns: + - COLDKEY: The SS58 address of the coldkey. + - HOTKEY: The SS58 address of the hotkey. + - UID: Unique identifier of the neuron. + - ACTIVE: Indicates if the neuron is active. + - STAKE(τ): Amount of stake in the neuron, in Tao. + - RANK: The rank of the neuron within the network. + - TRUST: Trust score of the neuron. + - CONSENSUS: Consensus score of the neuron. + - INCENTIVE: Incentive score of the neuron. + - DIVIDENDS: Dividends earned by the neuron. + - EMISSION(p): Emission received by the neuron, in Rho. + - VTRUST: Validator trust score of the neuron. + - VPERMIT: Indicates if the neuron has a validator permit. + - UPDATED: Time since last update. + - AXON: IP address and port of the neuron. + - HOTKEY_SS58: Human-readable representation of the hotkey. + + Example usage: + >>> btcli wallet overview + >>> btcli wallet overview --all --sort_by stake --sort_order descending + + Note: + This command is read-only and does not modify the network state or account configurations. It provides a quick and + comprehensive view of the user's network presence, making it ideal for monitoring account status, stake distribution, + and overall contribution to the Bittensor network. + """ + @staticmethod def run(cli: "bittensor.cli"): r"""Prints an overview for the wallet's colkey.""" diff --git a/bittensor/commands/register.py b/bittensor/commands/register.py index 32c7f97fc4..1db114a714 100644 --- a/bittensor/commands/register.py +++ b/bittensor/commands/register.py @@ -27,6 +27,35 @@ class RegisterCommand: + """ + Executes the 'register' command to register a neuron on the Bittensor network by recycling some TAO (the network's native token). + This command is used to add a new neuron to a specified subnet within the network, contributing to the decentralization and robustness of Bittensor. + + Usage: + Before registering, the command checks if the specified subnet exists and whether the user's balance is sufficient to cover the registration cost. + The registration cost is determined by the current recycle amount for the specified subnet. If the balance is insufficient or the subnet does not exist, + the command will exit with an appropriate error message. + + If the preconditions are met, and the user confirms the transaction (if 'no_prompt' is not set), the command proceeds to register the neuron by burning the required amount of TAO. + + The command structure includes: + - Verification of subnet existence. + - Checking the user's balance against the current recycle amount for the subnet. + - User confirmation prompt for proceeding with registration. + - Execution of the registration process. + + Columns Displayed in the Confirmation Prompt: + - Balance: The current balance of the user's wallet in TAO. + - Cost to Register: The required amount of TAO needed to register on the specified subnet. + + Example usage: + >>> btcli subnets register --netuid 1 + + Note: + This command is critical for users who wish to contribute a new neuron to the network. It requires careful consideration of the subnet selection and + an understanding of the registration costs. Users should ensure their wallet is sufficiently funded before attempting to register a neuron. + """ + @staticmethod def run(cli): r"""Register neuron by recycling some TAO.""" @@ -109,6 +138,39 @@ def check_config(config: "bittensor.config"): class PowRegisterCommand: + """ + Executes the 'pow_register' command to register a neuron on the Bittensor network using Proof of Work (PoW). + This method is an alternative registration process that leverages computational work for securing a neuron's place on the network. + + Usage: + The command starts by verifying the existence of the specified subnet. If the subnet does not exist, it terminates with an error message. + On successful verification, the PoW registration process is initiated, which requires solving computational puzzles. + + Optional arguments: + - --netuid (int): The netuid for the subnet on which to serve the neuron. Mandatory for specifying the target subnet. + - --pow_register.num_processes (int): The number of processors to use for PoW registration. Defaults to the system's default setting. + - --pow_register.update_interval (int): The number of nonces to process before checking for the next block during registration. + Affects the frequency of update checks. + - --pow_register.no_output_in_place (bool): When set, disables the output of registration statistics in place. Useful for cleaner logs. + - --pow_register.verbose (bool): Enables verbose output of registration statistics for detailed information. + - --pow_register.cuda.use_cuda (bool): Enables the use of CUDA for GPU-accelerated PoW calculations. Requires a CUDA-compatible GPU. + - --pow_register.cuda.no_cuda (bool): Disables the use of CUDA, defaulting to CPU-based calculations. + - --pow_register.cuda.dev_id (int): Specifies the CUDA device ID, useful for systems with multiple CUDA-compatible GPUs. + - --pow_register.cuda.TPB (int): Sets the number of Threads Per Block for CUDA operations, affecting the GPU calculation dynamics. + + The command also supports additional wallet and subtensor arguments, enabling further customization of the registration process. + + Example usage: + >>> btcli pow_register --netuid 1 --pow_register.num_processes 4 --cuda.use_cuda + + Note: + This command is suited for users with adequate computational resources to participate in PoW registration. It requires a sound understanding + of the network's operations and PoW mechanics. Users should ensure their systems meet the necessary hardware and software requirements, + particularly when opting for CUDA-based GPU acceleration. + + This command may be disabled according on the subnet owner's directive. For example, on netuid 1 this is permanently disabled. + """ + @staticmethod def run(cli): r"""Register neuron.""" @@ -261,6 +323,38 @@ def check_config(config: "bittensor.config"): class RunFaucetCommand: + """ + Executes the 'faucet' command to obtain test TAO tokens by performing Proof of Work (PoW). + This command is particularly useful for users who need test tokens for operations on the Bittensor testnet. + + Usage: + The command uses the PoW mechanism to validate the user's effort and rewards them with test TAO tokens. + It is typically used in testnet environments where real value transactions are not necessary. + + Optional arguments: + - --faucet.num_processes (int): Specifies the number of processors to use for the PoW operation. + A higher number of processors may increase the chances of successful computation. + - --faucet.update_interval (int): Sets the frequency of nonce processing before checking for the next block, + which impacts the PoW operation's responsiveness. + - --faucet.no_output_in_place (bool): When set, it disables in-place output of registration statistics for cleaner log visibility. + - --faucet.verbose (bool): Enables verbose output for detailed statistical information during the PoW process. + - --faucet.cuda.use_cuda (bool): Activates the use of CUDA for GPU acceleration in the PoW process, suitable for CUDA-compatible GPUs. + - --faucet.cuda.no_cuda (bool): Disables the use of CUDA, opting for CPU-based calculations. + - --faucet.cuda.dev_id (int[]): Allows selection of specific CUDA device IDs for the operation, useful in multi-GPU setups. + - --faucet.cuda.TPB (int): Determines the number of Threads Per Block for CUDA operations, affecting GPU calculation efficiency. + + These options provide flexibility in configuring the PoW process according to the user's hardware capabilities and preferences. + + Example usage: + >>> btcli wallet faucet --faucet.num_processes 4 --faucet.cuda.use_cuda + + Note: + This command is meant for use in testnet environments where users can experiment with the network without using real TAO tokens. + It's important for users to have the necessary hardware setup, especially when opting for CUDA-based GPU calculations. + + **THIS COMMAND IS CURRENTLY DISABLED!** + """ + @staticmethod def run(cli): r"""Register neuron.""" diff --git a/bittensor/commands/root.py b/bittensor/commands/root.py index 78c31fa3d7..0517f94628 100644 --- a/bittensor/commands/root.py +++ b/bittensor/commands/root.py @@ -33,6 +33,24 @@ class RootRegisterCommand: + """ + Executes the 'register' command to register a wallet to the root network of the Bittensor network. + This command is used to formally acknowledge a wallet's participation in the network's root layer. + + Usage: + The command registers the user's wallet with the root network, which is a crucial step for participating in network governance and other advanced functions. + + Optional arguments: + - None. The command primarily uses the wallet and subtensor configurations. + + Example usage: + >>> btcli root register + + Note: + This command is important for users seeking to engage deeply with the Bittensor network, particularly in aspects related to network governance and decision-making. + It is a straightforward process but requires the user to have an initialized and configured wallet. + """ + @staticmethod def run(cli): r"""Register to root network.""" @@ -62,6 +80,35 @@ def check_config(config: "bittensor.config"): class RootList: + """ + Executes the 'list' command to display the members of the root network on the Bittensor network. + This command provides an overview of the neurons that constitute the network's foundational layer. + + Usage: + Upon execution, the command fetches and lists the neurons in the root network, showing their unique identifiers (UIDs), names, addresses, stakes, + and whether they are part of the senate (network governance body). + + Optional arguments: + - None. The command uses the subtensor configuration to retrieve data. + + Example usage: + >>> btcli root list + + UID NAME ADDRESS STAKE(τ) SENATOR + 0 5CaCUPsSSdKWcMJbmdmJdnWVa15fJQuz5HsSGgVdZffpHAUa 27086.37070 Yes + 1 RaoK9 5GmaAk7frPXnAxjbQvXcoEzMGZfkrDee76eGmKoB3wxUburE 520.24199 No + 2 Openτensor Foundaτion 5F4tQyWrhfGVcNhoqeiNsR6KjD4wMZ2kfhLj4oHYuyHbZAc3 1275437.45895 Yes + 3 RoundTable21 5FFApaS75bv5pJHfAp2FVLBj9ZaXuFDjEypsaBNc1wCfe52v 84718.42095 Yes + 4 5HK5tp6t2S59DywmHRWPBVJeJ86T61KjurYqeooqj8sREpeN 168897.40859 Yes + 5 Rizzo 5CXRfP2ekFhe62r7q3vppRajJmGhTi7vwvb2yr79jveZ282w 53383.34400 No + 6 τaosτaτs and BitAPAI 5Hddm3iBFD2GLT5ik7LZnT3XJUnRnN8PoeCFgGQgawUVKNm8 646944.73569 Yes + ... + + Note: + This command is useful for users interested in understanding the composition and governance structure of the Bittensor network's root layer. + It provides insights into which neurons hold significant influence and responsibility within the network. + """ + @staticmethod def run(cli): r"""List the root network""" @@ -144,6 +191,26 @@ def check_config(config: "bittensor.config"): class RootSetWeightsCommand: + """ + Executes the 'weights' command to set the weights for the root network on the Bittensor network. + This command is used by network senators to influence the distribution of network rewards and responsibilities. + + Usage: + The command allows setting weights for different subnets within the root network. + Users need to specify the netuids (network unique identifiers) and corresponding weights they wish to assign. + + Optional arguments: + - --netuids (str): A comma-separated list of netuids for which weights are to be set. + - --weights (str): Corresponding weights for the specified netuids, in comma-separated format. + + Example usage: + >>> btcli root weights --netuids 1,2,3 --weights 0.3,0.3,0.4 + + Note: + This command is particularly important for network senators and requires a comprehensive understanding of the network's dynamics. + It is a powerful tool that directly impacts the network's operational mechanics and reward distribution. + """ + @staticmethod def run(cli): r"""Set weights for root network.""" @@ -214,6 +281,38 @@ def check_config(config: "bittensor.config"): class RootGetWeightsCommand: + """ + Executes the 'get_weights' command to retrieve the weights set for the root network on the Bittensor network. + This command provides visibility into how network responsibilities and rewards are distributed among various subnets. + + Usage: + The command outputs a table listing the weights assigned to each subnet within the root network. + This information is crucial for understanding the current influence and reward distribution among the subnets. + + Optional arguments: + - None. The command fetches weight information based on the subtensor configuration. + + Example usage: + >>> btcli root get_weights + + Root Network Weights + UID 0 1 2 3 4 5 8 9 11 13 18 19 + 1 100.00% - - - - - - - - - - - + 2 - 40.00% 5.00% 10.00% 10.00% 10.00% 10.00% 5.00% - - 10.00% - + 3 - - 25.00% - 25.00% - 25.00% - - - 25.00% - + 4 - - 7.00% 7.00% 20.00% 20.00% 20.00% - 6.00% - 20.00% - + 5 - 20.00% - 10.00% 15.00% 15.00% 15.00% 5.00% - - 10.00% 10.00% + 6 - - - - 10.00% 10.00% 25.00% 25.00% - - 30.00% - + 7 - 60.00% - - 20.00% - - - 20.00% - - - + 8 - 49.35% - 7.18% 13.59% 21.14% 1.53% 0.12% 7.06% 0.03% - - + 9 100.00% - - - - - - - - - - - + ... + + Note: + This command is essential for users interested in the governance and operational dynamics of the Bittensor network. + It offers transparency into how network rewards and responsibilities are allocated across different subnets. + """ + @staticmethod def run(cli): r"""Get weights for root network.""" diff --git a/bittensor/commands/senate.py b/bittensor/commands/senate.py index ba4165ce47..1e283dea60 100644 --- a/bittensor/commands/senate.py +++ b/bittensor/commands/senate.py @@ -20,6 +20,7 @@ import bittensor from rich.prompt import Prompt, Confirm from rich.table import Table +from rich.console import Console from typing import List, Union, Optional, Dict, Tuple from .utils import get_delegates_details, DelegatesDetails from . import defaults @@ -28,9 +29,27 @@ class SenateCommand: + """ + Executes the 'senate' command to view the members of Bittensor's governance protocol, known as the Senate. + This command lists the delegates involved in the decision-making process of the Bittensor network. + + Usage: + The command retrieves and displays a list of Senate members, showing their names and wallet addresses. + This information is crucial for understanding who holds governance roles within the network. + + Example usage: + >>> btcli root senate + + Note: + This command is particularly useful for users interested in the governance structure and participants of the Bittensor network. + It provides transparency into the network's decision-making body. + """ + @staticmethod def run(cli): r"""View Bittensor's governance protocol proposals""" + console = bittensor.__console__ + config = cli.config.copy() subtensor: bittensor.subtensor = bittensor.subtensor(config=config) @@ -136,9 +155,27 @@ def display_votes( class ProposalsCommand: + """ + Executes the 'proposals' command to view active proposals within Bittensor's governance protocol. + This command displays the details of ongoing proposals, including votes, thresholds, and proposal data. + + Usage: + The command lists all active proposals, showing their hash, voting threshold, number of ayes and nays, + detailed votes by address, end block number, and call data associated with each proposal. + + Example usage: + >>> btcli root proposals + + Note: + This command is essential for users who are actively participating in or monitoring the governance of the Bittensor network. + It provides a detailed view of the proposals being considered, along with the community's response to each. + """ + @staticmethod def run(cli): r"""View Bittensor's governance protocol proposals""" + console = bittensor.__console__ + config = cli.config.copy() subtensor: bittensor.subtensor = bittensor.subtensor(config=config) @@ -222,6 +259,27 @@ def add_args(cls, parser: argparse.ArgumentParser): class ShowVotesCommand: + """ + Executes the 'proposal_votes' command to view the votes for a specific proposal in Bittensor's governance protocol. + This command provides a detailed breakdown of the votes cast by the senators for a particular proposal. + + Usage: + Users need to specify the hash of the proposal they are interested in. The command then displays the voting addresses + and their respective votes (Aye or Nay) for the specified proposal. + + Optional arguments: + - --proposal (str): The hash of the proposal for which votes need to be displayed. + + Example usage: + >>> btcli root proposal_votes --proposal + + Note: + This command is crucial for users seeking detailed insights into the voting behavior of the Senate on specific governance proposals. + It helps in understanding the level of consensus or disagreement within the Senate on key decisions. + + **THIS COMMAND IS DEPRECATED: Please use `btcli root proposals` to see vote status.** + """ + @staticmethod def run(cli): r"""View Bittensor's governance protocol proposals active votes""" @@ -297,6 +355,22 @@ def add_args(cls, parser: argparse.ArgumentParser): class SenateRegisterCommand: + """ + Executes the 'senate_register' command to register as a member of the Senate in Bittensor's governance protocol. + This command is used by delegates who wish to participate in the governance and decision-making process of the network. + + Usage: + The command checks if the user's hotkey is a delegate and not already a Senate member before registering them to the Senate. + Successful execution allows the user to participate in proposal voting and other governance activities. + + Example usage: + >>> btcli root senate_register + + Note: + This command is intended for delegates who are interested in actively participating in the governance of the Bittensor network. + It is a significant step towards engaging in network decision-making processes. + """ + @staticmethod def run(cli): r"""Register to participate in Bittensor's governance protocol proposals""" @@ -349,6 +423,22 @@ def add_args(cls, parser: argparse.ArgumentParser): class SenateLeaveCommand: + """ + Executes the 'senate_leave' command to discard membership in Bittensor's Senate. + This command allows a Senate member to voluntarily leave the governance body. + + Usage: + The command checks if the user's hotkey is currently a Senate member before processing the request to leave the Senate. + It effectively removes the user from participating in future governance decisions. + + Example usage: + >>> btcli root senate_leave + + Note: + This command is relevant for Senate members who wish to step down from their governance responsibilities within the Bittensor network. + It should be used when a member no longer desires to participate in the Senate activities. + """ + @staticmethod def run(cli): r"""Discard membership in Bittensor's governance protocol proposals""" @@ -392,6 +482,25 @@ def add_args(cls, parser: argparse.ArgumentParser): class VoteCommand: + """ + Executes the 'senate_vote' command to cast a vote on an active proposal in Bittensor's governance protocol. + This command is used by Senate members to vote on various proposals that shape the network's future. + + Usage: + The user needs to specify the hash of the proposal they want to vote on. The command then allows the Senate member + to cast an 'Aye' or 'Nay' vote, contributing to the decision-making process. + + Optional arguments: + - --proposal (str): The hash of the proposal to vote on. + + Example usage: + >>> btcli root senate_vote --proposal + + Note: + This command is crucial for Senate members to exercise their voting rights on key proposals. It plays a vital role in the governance + and evolution of the Bittensor network. + """ + @staticmethod def run(cli): r"""Vote in Bittensor's governance protocol proposals""" diff --git a/bittensor/commands/stake.py b/bittensor/commands/stake.py index acf5f76a49..51f54afe97 100644 --- a/bittensor/commands/stake.py +++ b/bittensor/commands/stake.py @@ -29,6 +29,33 @@ class StakeCommand: + """ + Executes the 'add' command to stake tokens to one or more hotkeys from a user's coldkey on the Bittensor network. + This command is used to allocate tokens to different hotkeys, securing their position and influence on the network. + + Usage: + Users can specify the amount to stake, the hotkeys to stake to (either by name or SS58 address), + and whether to stake to all hotkeys. The command checks for sufficient balance and hotkey registration + before proceeding with the staking process. + + Optional arguments: + - --all (bool): When set, stakes all available tokens from the coldkey. + - --uid (int): The unique identifier of the neuron to which the stake is to be added. + - --amount (float): The amount of TAO tokens to stake. + - --max_stake (float): Sets the maximum amount of TAO to have staked in each hotkey. + - --hotkeys (list): Specifies hotkeys by name or SS58 address to stake to. + - --all_hotkeys (bool): When set, stakes to all hotkeys associated with the wallet, excluding any specified in --hotkeys. + + The command prompts for confirmation before executing the staking operation. + + Example usage: + >>> btcli stake add --amount 100 --wallet.name --wallet.hotkey + + Note: + This command is critical for users who wish to distribute their stakes among different neurons (hotkeys) on the network. + It allows for a strategic allocation of tokens to enhance network participation and influence. + """ + @staticmethod def run(cli): r"""Stake token of amount to hotkey(s).""" @@ -302,6 +329,32 @@ def _get_hotkey_wallets_for_wallet(wallet) -> List["bittensor.wallet"]: class StakeShow: + """ + Executes the 'show' command to list all stake accounts associated with a user's wallet on the Bittensor network. + This command provides a comprehensive view of the stakes associated with both hotkeys and delegates linked to the user's coldkey. + + Usage: + The command lists all stake accounts for a specified wallet or all wallets in the user's configuration directory. + It displays the coldkey, balance, account details (hotkey/delegate name), stake amount, and the rate of return. + + Optional arguments: + - --all (bool): When set, the command checks all coldkey wallets instead of just the specified wallet. + + The command compiles a table showing: + - Coldkey: The coldkey associated with the wallet. + - Balance: The balance of the coldkey. + - Account: The name of the hotkey or delegate. + - Stake: The amount of TAO staked to the hotkey or delegate. + - Rate: The rate of return on the stake, typically shown in TAO per day. + + Example usage: + >>> btcli stake show --all + + Note: + This command is essential for users who wish to monitor their stake distribution and returns across various accounts on the Bittensor network. + It provides a clear and detailed overview of the user's staking activities. + """ + @staticmethod def run(cli): r"""Show all stake accounts.""" diff --git a/bittensor/commands/transfer.py b/bittensor/commands/transfer.py index b0c51486f0..9735d81577 100644 --- a/bittensor/commands/transfer.py +++ b/bittensor/commands/transfer.py @@ -26,6 +26,28 @@ class TransferCommand: + """ + Executes the 'transfer' command to transfer TAO tokens from one account to another on the Bittensor network. + This command is used for transactions between different accounts, enabling users to send tokens to other participants on the network. + + Usage: + The command requires specifying the destination address (public key) and the amount of TAO to be transferred. + It checks for sufficient balance and prompts for confirmation before proceeding with the transaction. + + Optional arguments: + - --dest (str): The destination address for the transfer. This can be in the form of an SS58 or ed2519 public key. + - --amount (float): The amount of TAO tokens to transfer. + + The command displays the user's current balance before prompting for the amount to transfer, ensuring transparency and accuracy in the transaction. + + Example usage: + >>> btcli wallet transfer --dest 5Dp8... --amount 100 + + Note: + This command is crucial for executing token transfers within the Bittensor network. Users should verify the destination address and amount + before confirming the transaction to avoid errors or loss of funds. + """ + @staticmethod def run(cli): r"""Transfer token of amount to destination.""" diff --git a/bittensor/commands/unstake.py b/bittensor/commands/unstake.py index f7e8d41201..4a0bafe139 100644 --- a/bittensor/commands/unstake.py +++ b/bittensor/commands/unstake.py @@ -28,6 +28,32 @@ class UnStakeCommand: + """ + Executes the 'remove' command to unstake TAO tokens from one or more hotkeys and transfer them back to the user's coldkey on the Bittensor network. + This command is used to withdraw tokens previously staked to different hotkeys. + + Usage: + Users can specify the amount to unstake, the hotkeys to unstake from (either by name or SS58 address), + and whether to unstake from all hotkeys. The command checks for sufficient stake and prompts for confirmation before proceeding with the unstaking process. + + Optional arguments: + - --all (bool): When set, unstakes all staked tokens from the specified hotkeys. + - --amount (float): The amount of TAO tokens to unstake. + - --hotkey_ss58address (str): The SS58 address of the hotkey to unstake from. + - --max_stake (float): Sets the maximum amount of TAO to remain staked in each hotkey. + - --hotkeys (list): Specifies hotkeys by name or SS58 address to unstake from. + - --all_hotkeys (bool): When set, unstakes from all hotkeys associated with the wallet, excluding any specified in --hotkeys. + + The command prompts for confirmation before executing the unstaking operation. + + Example usage: + >>> btcli stake remove --amount 100 --hotkeys hk1,hk2 + + Note: + This command is important for users who wish to reallocate their stakes or withdraw them from the network. + It allows for flexible management of token stakes across different neurons (hotkeys) on the network. + """ + @classmethod def check_config(cls, config: "bittensor.config"): if not config.is_set("wallet.name") and not config.no_prompt: diff --git a/bittensor/commands/wallets.py b/bittensor/commands/wallets.py index 9e892b5524..30405f7d12 100644 --- a/bittensor/commands/wallets.py +++ b/bittensor/commands/wallets.py @@ -26,6 +26,30 @@ class RegenColdkeyCommand: + """ + Executes the 'regen_coldkey' command to regenerate a coldkey for a wallet on the Bittensor network. + This command is used to create a new coldkey from an existing mnemonic, seed, or JSON file. + + Usage: + Users can specify a mnemonic, a seed string, or a JSON file path to regenerate a coldkey. + The command supports optional password protection for the generated key and can overwrite an existing coldkey. + + Optional arguments: + - --mnemonic (str): A mnemonic phrase used to regenerate the key. + - --seed (str): A seed hex string used for key regeneration. + - --json (str): Path to a JSON file containing an encrypted key backup. + - --json_password (str): Password to decrypt the JSON file. + - --use_password (bool): Enables password protection for the generated key. + - --overwrite_coldkey (bool): Overwrites the existing coldkey with the new one. + + Example usage: + >>> btcli wallet regen_coldkey --mnemonic "word1 word2 ... word12" + + Note: + This command is critical for users who need to regenerate their coldkey, possibly for recovery or security reasons. + It should be used with caution to avoid overwriting existing keys unintentionally. + """ + def run(cli): r"""Creates a new coldkey under this wallet.""" wallet = bittensor.wallet(config=cli.config) @@ -126,6 +150,27 @@ def add_args(parser: argparse.ArgumentParser): class RegenColdkeypubCommand: + """ + Executes the 'regen_coldkeypub' command to regenerate the public part of a coldkey (coldkeypub) for a wallet on the Bittensor network. + This command is used when a user needs to recreate their coldkeypub from an existing public key or SS58 address. + + Usage: + The command requires either a public key in hexadecimal format or an SS58 address to regenerate the coldkeypub. + It optionally allows overwriting an existing coldkeypub file. + + Optional arguments: + - --public_key_hex (str): The public key in hex format. + - --ss58_address (str): The SS58 address of the coldkey. + - --overwrite_coldkeypub (bool): Overwrites the existing coldkeypub file with the new one. + + Example usage: + >>> btcli wallet regen_coldkeypub --ss58_address 5DkQ4... + + Note: + This command is particularly useful for users who need to regenerate their coldkeypub, perhaps due to file corruption or loss. + It is a recovery-focused utility that ensures continued access to wallet functionalities. + """ + def run(cli): r"""Creates a new coldkeypub under this wallet.""" wallet = bittensor.wallet(config=cli.config) @@ -191,6 +236,31 @@ def add_args(parser: argparse.ArgumentParser): class RegenHotkeyCommand: + """ + Executes the 'regen_hotkey' command to regenerate a hotkey for a wallet on the Bittensor network. + Similar to regenerating a coldkey, this command creates a new hotkey from a mnemonic, seed, or JSON file. + + Usage: + Users can provide a mnemonic, seed string, or a JSON file to regenerate the hotkey. + The command supports optional password protection and can overwrite an existing hotkey. + + Optional arguments: + - --mnemonic (str): A mnemonic phrase used to regenerate the key. + - --seed (str): A seed hex string used for key regeneration. + - --json (str): Path to a JSON file containing an encrypted key backup. + - --json_password (str): Password to decrypt the JSON file. + - --use_password (bool): Enables password protection for the generated key. + - --overwrite_hotkey (bool): Overwrites the existing hotkey with the new one. + + Example usage: + >>> btcli wallet regen_hotkey + >>> btcli wallet regen_hotkey --seed 0x1234... + + Note: + This command is essential for users who need to regenerate their hotkey, possibly for security upgrades or key recovery. + It should be used cautiously to avoid accidental overwrites of existing keys. + """ + def run(cli): r"""Creates a new coldkey under this wallet.""" wallet = bittensor.wallet(config=cli.config) @@ -296,6 +366,27 @@ def add_args(parser: argparse.ArgumentParser): class NewHotkeyCommand: + """ + Executes the 'new_hotkey' command to create a new hotkey under a wallet on the Bittensor network. + This command is used to generate a new hotkey for managing a neuron or participating in the network. + + Usage: + The command creates a new hotkey with an optional word count for the mnemonic and supports password protection. + It also allows overwriting an existing hotkey. + + Optional arguments: + - --n_words (int): The number of words in the mnemonic phrase. + - --use_password (bool): Enables password protection for the generated key. + - --overwrite_hotkey (bool): Overwrites the existing hotkey with the new one. + + Example usage: + >>> btcli wallet new_hotkey --n_words 24 + + Note: + This command is useful for users who wish to create additional hotkeys for different purposes, + such as running multiple miners or separating operational roles within the network. + """ + def run(cli): """Creates a new hotke under this wallet.""" wallet = bittensor.wallet(config=cli.config) @@ -352,6 +443,27 @@ def add_args(parser: argparse.ArgumentParser): class NewColdkeyCommand: + """ + Executes the 'new_coldkey' command to create a new coldkey under a wallet on the Bittensor network. + This command generates a coldkey, which is essential for holding balances and performing high-value transactions. + + Usage: + The command creates a new coldkey with an optional word count for the mnemonic and supports password protection. + It also allows overwriting an existing coldkey. + + Optional arguments: + - --n_words (int): The number of words in the mnemonic phrase. + - --use_password (bool): Enables password protection for the generated key. + - --overwrite_coldkey (bool): Overwrites the existing coldkey with the new one. + + Example usage: + >>> btcli wallet new_coldkey --n_words 15 + + Note: + This command is crucial for users who need to create a new coldkey for enhanced security or as part of setting up a new wallet. + It's a foundational step in establishing a secure presence on the Bittensor network. + """ + def run(cli): r"""Creates a new coldkey under this wallet.""" wallet = bittensor.wallet(config=cli.config) @@ -404,6 +516,28 @@ def add_args(parser: argparse.ArgumentParser): class WalletCreateCommand: + """ + Executes the 'create' command to generate both a new coldkey and hotkey under a specified wallet on the Bittensor network. + This command is a comprehensive utility for creating a complete wallet setup with both cold and hotkeys. + + Usage: + The command facilitates the creation of a new coldkey and hotkey with an optional word count for the mnemonics. + It supports password protection for the coldkey and allows overwriting of existing keys. + + Optional arguments: + - --n_words (int): The number of words in the mnemonic phrase for both keys. + - --use_password (bool): Enables password protection for the coldkey. + - --overwrite_coldkey (bool): Overwrites the existing coldkey with the new one. + - --overwrite_hotkey (bool): Overwrites the existing hotkey with the new one. + + Example usage: + >>> btcli wallet create --n_words 21 + + Note: + This command is ideal for new users setting up their wallet for the first time or for those who wish to completely renew their wallet keys. + It ensures a fresh start with new keys for secure and effective participation in the network. + """ + def run(cli): r"""Creates a new coldkey and hotkey under this wallet.""" wallet = bittensor.wallet(config=cli.config) @@ -481,6 +615,26 @@ def _get_coldkey_wallets_for_path(path: str) -> List["bittensor.wallet"]: class UpdateWalletCommand: + """ + Executes the 'update' command to check and potentially update the security of the wallets in the Bittensor network. + This command is used to enhance wallet security using modern encryption standards. + + Usage: + The command checks if any of the wallets need an update in their security protocols. + It supports updating all legacy wallets or a specific one based on the user's choice. + + Optional arguments: + - --all (bool): When set, updates all legacy wallets. + - --no_prompt (bool): Disables user prompting during the update process. + + Example usage: + >>> btcli wallet update --all + + Note: + This command is important for maintaining the highest security standards for users' wallets. + It is recommended to run this command periodically to ensure wallets are up-to-date with the latest security practices. + """ + @staticmethod def run(cli): """Check if any of the wallets needs an update.""" @@ -554,6 +708,25 @@ def list_coldkeypub_files(dir_path): class WalletBalanceCommand: + """ + Executes the 'balance' command to check the balance of the wallet on the Bittensor network. + This command provides a detailed view of the wallet's coldkey balances, including free and staked balances. + + Usage: + The command lists the balances of all wallets in the user's configuration directory, showing the wallet name, + coldkey address, and the respective free and staked balances. + + Optional arguments: + None. The command uses the wallet and subtensor configurations to fetch balance data. + + Example usage: + >>> btcli wallet balance + + Note: + This command is essential for users to monitor their financial status on the Bittensor network. + It helps in keeping track of assets and ensuring the wallet's financial health. + """ + @staticmethod def run(cli): """Check the balance of the wallet."""