BTCLI v10

[thewhaleking]

Placeholder Issue

Todo:

• RFC (RFC005 - BTCLI v10.md)
• Architecture doc
• TUI (Commander)
• Rewrite

[thewhaleking]

RFC:

BTCLI v10

Author: Benjamin Himes
Creation Date: Mar 31, 2026
Submission Date: Apr 10, 2026
Finalized Date: Apr 20, 2026
Status: Approved

Approvals

• Roman Chkhaidze
• Ibraheem Nadeem
• Cameron Fairchild

Background

BTCLI is the CLI for interactions with the Bittensor blockchain. It allows the user to perform various tasks, including wallet management, staking, transfers, proxy calls, and to grab various information, including balances, stake, metagraph info, etc.

The current major version (v9) was released as a rewrite using the Typer framework on 13 February 2025. This has generally worked out quite well. The community is quite happy with it. However, because of the number of features we have added over the previous 13 months, sometimes with very quick deadlines for shipping, we have lost track of some of the initial vision.

Not covered in this doc

Specific implementation details of Commander TUI, JSON Schemas

Problems

Integration of Commander TUI

With the current situation, in order to integrate the proposed Commander TUI, we would need to basically copy the entire logic of most of the public API, and then adjust the returns to only use JSON, which we would then parse. This is doable, but ugly, and will become increasingly difficult to maintain.

JSON Outputs

There are 6-7 “standard” JSON return types, and none of these are correctly integrated. I was working on a PR to standardize these, but it will involve a big refactor just to get these correct. Furthermore, if we do change these, we are changing the public API and thus will necessitate a major version change.

MEV Shield Code Reuse

The wait_for_extrinsic_by_hash code to handle MEV Shield transactions is repeated and slightly altered ~23 times — some including status.stop(), some not. This is not ideal.

Proxy

Proxy handling sucks. It was tacked on, and the way we currently do it is horrendous:

class CliManager:
   ...
   def some_transaction(wallet_name: str, ..., proxy: Optional[str] = None):
       validation_logic()
       return self._run(some_transaction, wallet=wallet, ..., proxy=proxy)

def some_transaction(wallet: Wallet, ..., proxy: Optional[str] = None):
    coldkey_ss58 = proxy or wallet.coldkeypub.ss58_address
    signer_balance = substrate.get_balance(wallet.coldkeypub.ss58_address)
    actual_balance = substrate.get_balance(coldkey_ss58)
    ...

It makes it hell to read and maintain.

Asking wallet for staking operations

We always ask the wallet for staking operations (apart from path). Makes no sense generally, complicates the flow of things, and is confusing to users.

No Returns In Broken Tests

We use --json-output for the majority of our e2e tests. However, when something breaks, it’s a pain because you have to re-run the tests locally, and add --verbose to figure out what’s going on or where it’s broken. It’s quite difficult to debug these sometimes, and never possible to do see the true failure on GitHub Actions.

Announce Only broken

We have logic for --announce-only but it’s not well implemented throughout the commands, because it would involve a large refactor to display to the user the results (as the results are currently set for not announce-only).

Two styles for events

In some situations, we grab the event data with event[“event”] and in others we use event. These two are basically identical, save for the event_idx, where the inner event gives the event type index and the outer event gives the index of the event within the extrinsic. This gives a look of inconsistency, though not a bug.

Proxy Address Table

It’s confusing, especially when it comes to differentiating between Pure Proxies and non-Pure Proxies.

Wallet History doesn’t work

Wallet History hasn’t worked for the better part of two years, due to a change in the Tao Stats API.

Max UIDs gone from Subnets Show

Because of the change to the runtime struct (SubnetInfoV2), we no longer display Max UIDs in Subnet Show.

Proposed Solution

BTCLI v10. A large refactor of the existing codebase directly addressing the concerns above.

Architecture

There will be two separate “entry” paths: Commander and CLI. These should consist of just passthrough functions which pass on their args to the private function which performs the same logic as is currently done. This will mean that we really only need to keep in sync the args of these functions, and allow the private functions to handle the processing, data validation, etc. These should also pass through their class, so the processing private function knows how to handle things like verbose outputs, prompts, etc., which will need to be handled differently, depending on Commander/CLI/CLI JSON.

The return types of all of these should be defined data classes, which are handled in a standardized way, depending on their end destination: Commander/CLI/CLI JSON.

CLI JSON should be a first class citizen. Currently, it’s an afterthought. With the serialisation of these standardized data classes, each command will need to include in its documentation the specific schema that is used for it. Also be able to download the JSON instead of just piping to stdout.

The wait_for_extrinsic_by_hash logic should be incorporated into sign_and_send_extrinsic, and anywhere the status is currently stopped should be used in a try:except block.

Because of the growing importance of adding batching, every command will need to be able to return (in its return dataclass) a prepared call that can be either executed directly or added to a batch for processing once the batch is completed and executed. I’m thinking something like this:

class Transfer:
    executed: bool = False
    success: Optional[bool] = None
    call: Optional[GenericCall] = None
    extrinsic_id: Optional[int] = None
    data: Optional[dict] = None
    
    def process_json(self) -> None:
        json_console.print_json(data=JSONOut.from_enum(Single)(self.data))
        # prints like {"success": True, "extrinsic_id": 23832-10, ...}

    def process_cli(self) -> None:
        if x and y:
            whatever()
        console.print(":green_check: Success. Your extrinsic has been included as ")

    def process_tui(self) -> SomeDataStruct:
        if x and y:
            whatever()
        return SomeDataStruct(self.data)

Every transaction should have the option to use a proxy. Rather than what we do currently, we should always set a signer ss58 and a real ss58 inside every validation function (which will be private functions in the future):

class CliManager:
   ...
   def some_transaction(wallet_name: str, ..., proxy: Optional[str] = None):
       validation_logic()
       signer_ss58 = proxy or wallet.coldkeypub.ss58_address
       real_ss58 = wallet.coldkeypub.ss58_address
       return self._run(some_transaction, wallet=wallet, real=real_ss58, signer=signer_ss58, ..., proxy=proxy)

def some_transaction(wallet: Wallet, ..., signer_ss58: str, real_ss58: str, proxy: Optional[str] = None):
    signer_balance = substrate.get_balance(signer_ss58)
    actual_balance = substrate.get_balance(real_ss58)
    ...

This will make things substantially easier to maintain and also to do things that verify the transaction cost doesn’t exceed the balance.

The majority of transactions do a few checks before submitting the transaction: usually verifying that there is enough balance and/or stake to make the transaction, and there is enough balance to cover the transaction cost. A single reusable function that takes a balance amount, a stake amount, and expected balances should cover this, with the caveat that for batch transactions the transaction cost is only checked at completion of the batch (before submitting the batch transaction). Potentially for a batch transaction, this process is handled normally, but then also checked at the end, so for a batch output, the returned dataclass includes items like balance_reduction: int and stake_reduction: dict[int, int], which is then all summed and passed through to this function at the end.

Other code that should have reusable functions: check if subnet owner. Something like:

class Interface(Enum):
    CLI = 0
    JSON = 1
    TUI = 2

@dataclass
class OwnerStatus(ErrorCheck):
    success: bool
    message: Optional[str]

def process_error(interface_type: Enum, error_check: ErrorCheck):
    if interface_type == Interface.CLI:
        print_error(error_check.message)
    elif interface_type == Interface.JSON:
        # this will actually use some standardised JSON error class
        json_console.print_json(data={"success": False, "message": error_check.message})
    elif interface_type == Interface.TUI:
        # handle in some yet-to-be-known way

def check_if_subnet_owner(
    netuid: int,
    expected_owner: str,  # ss58
):
    subnet_owner = await subtensor.query(
        module="SubtensorModule",
        storage_function="SubnetOwner",
        params=[netuid],
    )
    if subnet_owner != expected_owner:
        return OwnerStatus(False, "This wallet doesn't own the specified subnet.")
    return OwnerStatus(True, None)


def trim(netuid: int, real_ss58: str, interface_type: Enum...):
    if not (is_owner := check_if_subnet_owner(netuid, real_ss58)).success:
        return process_error(interface_type, is_owner)
    ...

We should probably have some sort of --skip-checks flag for CLI that would disable checks like above. This can be useful for speeding things up for power users, or for situations where we didn’t account for something, and it’s faster to get them working than to issue a hotfix.

JSON and TUI should always have some sort of output. As mentioned above RFC005 - BTCLI v10, we need some reliable way of debugging. This might involve wrapping everything in a try:except and spitting the output into an err_msg field or something, which is logged, so it can be viewed within the GitHub Actions runner.

We need a better framework for creating unit and e2e tests. Currently we have very little, and this results in structures patched and created per-test, which is highly inefficient. The conftest.py file should include a large variety of patched objects which can be used for crafting individual unit tests. This will reduce noise, as community PRs tend to be 90% tests.

For the Proxy Address Table, I would like to have Dera rework the wording/naming, because it’s confusing to users (see: https://github.com/latent-to/btcli/pull/917/changes, for example)

We should allow users to sign mev protection transactions with a different key (see: #824)

I think we can integrate free and paid wallet history API endpoints with Tao.App. The key should be able to be set in the config or in an env var, with histories of different lengths depending on if the key is free or paid.

Shamir's Secret Sharing (SSS) and Slip39 (#407) was proposed. I’m not sure if it makes sense to actually add, but if we do, we’d have to do it from the get. We’re going to skip this for v10 initially. May get added eventually, but not any time soon.

We should add in Max UIDs for Subnets Show.

Alternatives

Refactor individually starting with the JSON Outputs, then MEV Shield Reuse, then hobble together the Commander implementation. This isn’t ideal, but could be easier to multiprocess between multiple developers than v10, as v10 will really need a single developer dedicated to it.

Rewrite the whole thing, but also using SDK v10 as the base lib. This will mostly only be useful for replacing the subtensor_interface.py file and the handful of extrinsics files. It also slightly complicates things because it will rely on a specific branch of bittensor to install to run the e2e tests.