Introduction

The chain now runs spec version 431, and the release changes both the network's economics and the software used to interact with it. Subnet ownership is now contestable through a time-weighted commitment mechanism called conviction. Emission between subnets is now allocated purely in proportion to each subnet's moving-average price. The Python SDK and the btcli command line now ship together as bittensor v11, built on a new Rust core. The documentation has been rebuilt at bittensor.com/docs. And the chain, SDK, CLI, documentation, and website are now developed and released together from a single repository.

This page explains each change, the reasoning behind it, and the actions required of network participants. Each section links to the relevant documentation.

Ownership by conviction

Locking alpha on a subnet accrues conviction: a time-weighted commitment score credited to a hotkey chosen by the locker. Prior to this upgrade, conviction was recorded on-chain but had no effect. As of spec 431, it governs subnet ownership:

If a subnet is more than one year old, and the total conviction across its lockers exceeds ten percent of its outstanding alpha, ownership of the subnet — including the owner's share of emissions — transfers to the hotkey with the highest conviction.

Ownership becomes contestable once both conditions hold: the subnet is older than one year, and total conviction exceeds ten percent of its outstanding alpha. At that point the hotkey with the highest conviction takes ownership.

Subnet ownership is therefore no longer fixed at registration; it is contestable through open, on-chain rules. Two lock modes are available, and both are exponential processes rather than fixed terms. A perpetual lock's conviction approaches its locked mass asymptotically — it never quite completes. The chain's maturity rate sets the exponential time constant, roughly 43 days at current values: after one time constant conviction stands at about 63% of the locked mass, after two about 86%, and so on. A decaying lock — the default — frees its locked mass on the chain's unlock rate, a time constant of roughly 130 days, after which about 37% of the mass remains locked; its conviction peaks and then unwinds. Both rates are governance-set storage values — read them from chain state before planning a lock rather than relying on the figures here — and there is one exception: locks credited to the subnet owner's own hotkey mature instantly, so their conviction always equals their locked mass. The mechanism is designed to reward long-horizon commitment to a subnet's success. The lock modes, the conviction formula, and a worked example are documented in the conviction guide.

Emissions, simplified

Each block, the chain divides TAO emission between subnets. As of this upgrade, that division is determined solely by each subnet's moving-average price, weighted by a miner-burn penalty. The root-proportion term has been removed from the cross-subnet calculation. Previously, this term reduced a subnet's emission share as its alpha issuance grew, which structurally disadvantaged older subnets. Root proportion continues to operate within each subnet — capping liquidity injection and reserving the root stakers' share of dividends — but it no longer affects how emission is divided between subnets.

Three subnets with an identical moving-average price. Before v431, the root-proportion term reduced each subnet's share as its alpha issuance grew; after, the same price earns the same emission regardless of age.

The result is that a subnet's emission share is a direct function of its market price. The full formula and its parameters are documented in emissions.

One package: bittensor v11

bittensor v11 consolidates the SDK and the btcli command line into a single package, installed with pip install bittensor. It replaces the separate bittensor-cli and bittensor-wallet packages. Existing wallet keyfiles are unchanged and fully compatible.

The package is built on a new Rust core covering keys, keyfiles, encoding, and timelock encryption. The following measurements were taken against the live network, before and after the change:

Transaction submission and inclusion remain bound by chain block time; the improvements are concentrated in startup, decoding, and construction. v11 is also a major revision of the API: the Subtensor class is replaced by a client-and-intent model with planning, policy gates, and typed results. The migration guide maps every v9/v10 call to its v11 equivalent, and the quickstart covers new installations.

To upgrade an existing environment, uninstall the old packages first — both own the btcli command, so order matters:

pip uninstall -y bittensor-cli bittensor-wallet
pip install -U bittensor

In the new SDK, chain state is read through a typed client, and every transaction is an intent that can be planned before it is executed:

import asyncio
import bittensor as sub
from bittensor.wallet import Wallet

async def main():
    wallet = Wallet(name="my_coldkey", hotkey="my_hotkey")
    async with sub.Client("finney") as client:
        balance = await client.balances.get("5F...coldkey")

        intent = sub.Transfer(dest_ss58="5F...dest", amount_tao=1.5)
        plan = await client.plan(intent, wallet)      # fee and effects; nothing submitted
        result = await client.execute(intent, wallet)
        if not result.success:
            print(result.error.code, result.error.remediation)

asyncio.run(main())

The CLI is generated from the same catalog: every transaction is a btcli tx command and every query a btcli query command, with hand-written groups wrapping the familiar workflows and the v9 shorthands preserved as aliases. Every mutation supports --dry-run, which shows the fee, the predicted effects, and any policy verdict without submitting:

btcli config set network finney
btcli wallet balance my_coldkey
btcli query metagraph --netuid 1
btcli tx transfer --dest 5F...dest --amount-tao 1.5 --dry-run
btcli tx transfer --dest 5F...dest --amount-tao 1.5 -w my_coldkey

Beyond the consolidation, v11 adds capabilities that did not exist in the old stack:

1. Unit-safe money — every Balance is tagged with its currency, so TAO and subnet alpha cannot be silently mixed; arithmetic across units raises instead of producing a wrong number. See money.
2. Policy guardrails — a client can be bound to hard limits (maximum fee, maximum spend, allowed subnets), and any transaction that would exceed them is refused before it is signed. See the transaction model.
3. Typed errors — every failure returns a semantic error code and a remediation hint rather than prose, with the full mapping published as a machine-readable catalog. See errors.
4. Signed requests — hotkey-signed HTTP between validators and miners, so a request provably came from a specific hotkey, covers exactly the bytes received, and cannot be replayed. See signed requests.
5. Timelock encryption — seal data that anyone can open at a known future time and nobody, including the author, can open early; the same mechanism that secures commit-reveal weights, exposed directly. See timelock.
6. Proxies as a first-class signer — every transaction accepts --proxy-for, so a delegate key can act for a coldkey that never comes online; scoped proxy types, announced (delayed) proxies, and pure proxy accounts are all supported. See advanced operations.
7. Multisig accounts — create and operate k-of-n multisig accounts, with the full approve, execute, and cancel flow wrapped by the btcli multisig command group.
8. Atomic batches and MEV-shielded submission— compose several intents into one all-or-nothing transaction, or encrypt a coldkey transaction to the next block's ephemeral key so it cannot be observed or front-run in the mempool.
9. Safer key rotation — hotkey swaps move registrations and stake to a new key, and a leaked coldkey can be evacuated through an announced, five-day-delayed swap that the real owner can dispute. See wallets and keys.
10. Address safety — CLI address arguments resolve from a saved address book or local key names as well as raw ss58, a defense against address poisoning documented in address hygiene.

Hardware and extension signing

Every transaction can now be signed on a Ledger hardware wallet using clear signing. Through merkleized metadata, the device decodes the transaction on its own screen, and the chain verifies the same metadata digest that was signed; the device rejects any transaction it cannot decode and verify. Any command that signs accepts the --ledger flag:

btcli tx transfer --dest 5F...dest --amount-tao 1 --ledger
btcli tx transfer --dest 5F...dest --amount-tao 1 --ledger --ledger-account 1

Setup and usage are documented in signing with a Ledger.

Transactions can also be signed with a browser extension — Talisman, Polkadot.js, or SubWallet. The CLI relays the transaction to the extension through a local bridge, and only the signature is returned; no keyfile, password, or mnemonic is present on the machine running btcli:

btcli extension accounts    # list accounts the extensions expose
btcli tx transfer --dest 5F...dest --amount-tao 1 --signer extension

The full flow is documented in signing with a browser extension.

Documentation, rebuilt

The documentation has been rebuilt and now lives at bittensor.com/docs. The reference pages for all 74 transactions and all 82 queries are generated directly from the SDK, so the reference cannot drift from the released software. Start at the documentation home.

Built for agents

The entire stack — SDK, CLI, documentation, and this website — is designed to be driven by AI agents as well as humans. Every operation is discoverable at runtime with a JSON schema (btcli tools on the CLI, sub.intents.list_tools()in Python) and can be executed by name from a plain dictionary, validated against that schema. Every mutation can be previewed before it spends anything, every failure returns a machine-readable code with a remediation hint, and a Policy can hard-bound what an agent's session is allowed to do — spend caps, fee caps, allowed subnets.

The CLI never traps automation: --json produces machine-readable output on any command, and a non-interactive session missing a confirmation is declined rather than left hanging. The documentation publishes the same catalogs statically — intents, reads, and errors as JSON — every page is fetchable as raw markdown, and the full corpus is available at a single plain-text endpoint for loading into a context window. The complete workflow is documented on the agents page.

One repository, releases on rails

The chain, SDK, CLI, documentation, and this website are now developed in a single repository: github.com/RaoFoundation/subtensor. Releases are produced by an automated pipeline. Every runtime change is tested against a live clone of mainnet state before it merges; a single deterministic build is promoted through devnet and testnet with automated checks at each stage; and the upgrade signed by the keyholders is cryptographically verified against the exact bytes the pipeline produced. A new public devnet, documented in the network overview, joins finney and testnet as a supported environment.

The runtime was also hardened in this release: proxy permissions are now deny-by-default, a crowdloan reentrancy flaw was closed, and the randomness pipeline that secures commit-reveal can no longer be stalled.

What you need to do

Most participants require little or no action. In order of urgency:

1. Python users — uninstall bittensor-cli and bittensor-wallet, then install the new bittensor package. Follow the migration guide; keyfiles are unchanged.
2. Proxy users — proxy permissions are now deny-by-default. Review every existing proxy configuration.
3. Node operators — nodes not yet running the spec 431 binary must upgrade to continue syncing.
4. Indexers and SDK authors — chain metadata now carries typed currency units; verify decoders against the new query reference.
5. Subnet owners and stakers — review the conviction guide. Ownership of subnets older than one year is now contestable.