diff --git a/docs/btcli/btcli-permissions.md b/docs/btcli/btcli-permissions.md index 667481dff..2f7f4013d 100644 --- a/docs/btcli/btcli-permissions.md +++ b/docs/btcli/btcli-permissions.md @@ -2,6 +2,10 @@ title: "Bittensor CLI: Permissions Guide" --- +import { GovernanceTransitionalState } from "../governance/_governance-transitional-state.mdx"; + + + The Bittensor CLI, `btcli` provides a wide range of functionality, and has a range of different requirements for various commands: some require a coldkey private key to authenticate, some require a hotkey private key, and some require neither. Additionally, different functions require different levels of permissions. Some require the user to have special status like being registered with a node, have a validator permit, or be an active member of the senate. This page details the requirements for all of the `btcli` commands. diff --git a/docs/btcli/btcli.md b/docs/btcli/btcli.md index ae6c9e7e9..293b92935 100644 --- a/docs/btcli/btcli.md +++ b/docs/btcli/btcli.md @@ -2,8 +2,12 @@ title: "Bittensor CLI: btcli Reference Document" --- +import { GovernanceTransitionalState } from "../governance/_governance-transitional-state.mdx"; + # Bittensor CLI: `btcli` Reference Document + + Command line interface (CLI) for Bittensor. Uses the values in the configuration file. These values can be overriden by passing them explicitly in the command line. See [Getting Started](../getting-started/install-btcli.md) to install `btcli`. diff --git a/docs/governance/_governance-transitional-state.mdx b/docs/governance/_governance-transitional-state.mdx new file mode 100644 index 000000000..dd2f7ed4c --- /dev/null +++ b/docs/governance/_governance-transitional-state.mdx @@ -0,0 +1,13 @@ +/* +Governance Transitional State Notice Partial +*/ + +import Admonition from '@theme/Admonition'; + +export const GovernanceTransitionalState = () => ( + +

+ Bittensor governance is currently in a transitional state as the network moves toward full decentralization. For details on planned governance changes, see the Bittensor Roadmap. +

+
+); diff --git a/docs/governance/governance.md b/docs/governance/governance.md index 13a82b084..57ca15600 100644 --- a/docs/governance/governance.md +++ b/docs/governance/governance.md @@ -1,66 +1,11 @@ --- -title: "Governance Overview" +title: "Governance" --- import { SdkVersion } from "../sdk/_sdk-version.mdx"; +import { GovernanceTransitionalState } from "./_governance-transitional-state.mdx"; -# Governance Overview +# Governance -Bittensor's governance protocol transitions the management of the network from centralization within the foundation to community ownership over time. + -The first stage of this transition to decentralized management is the creation of a bicameral legislature. In this stage, the [Triumvirate](../resources/glossary.md#triumvirate) creates proposals for the [Senate](./senate.md) to approve. - -Triumvirate members are Opentensor Foundation employees, while the Senate is formed from the top K delegate hotkeys. - -## Proposals - -Proposals are encapsulations of other extrinsics and will be executed only after meeting both of the two conditions: - -1. The proposal has obtained (50% + 1) approvals from the Senate, and -2. A member of the Triumvirate has closed the proposal. - -The above guarantees that the Senate must reach a majority consensus to execute a proposal. - -:::tip Execution of a proposal -When a proposal is executed, the calldata passed to it during its creation are included in the same block as the close extrinsic. -::: - -## Security - -Before the governance protocol existed, all administrative actions within the network (e.g., changing hyperparameters, creating new subnetworks, chain upgrades) required permission via a single privileged key, known as `sudo`. If the `sudo` private key were somehow compromised, a malicious actor could take over the network and execute any privileged extrinsics. - -Under the governance protocol, a malicious actor would have to compromise a Triumvirate member and control a majority of Senate seats in order to approve a proposal. - -## Example - -Consider the following: - -- The Triumvirate contains three seats, with members `Alice`, `Bob`, and `Charlie`. -- The Senate has three members elected to participate: `Dave`, `Eve`, and `Ferdie`. - -**Triumvirate** - -`Bob` has a novel concept for a subnet and wishes to deploy it on the Bittensor network. `Bob` creates a proposal with the calldata: - - - -```python -SubtensorModule.SudoAddNetwork(netuid, tempo, modality) -``` - -and sends the transaction to the network in order to broadcast the proposal. - -**Senate** - -- `Dave`, `Eve`, and `Ferdie` all own the nominated delegate hotkeys, and they individually control more than two percent of the network's total stakes. -- Using `btcli`, they can view the proposal and the calldata, which it will execute upon approval. -- `Dave` and `Ferdie` decided they wanted to approve this new subnet, and they both approved the proposal. -- `Eve` disagrees with the concept and disapproves of the proposal. - -Even though the Senate may have twelve members at any time, it is not guaranteed that there will be twelve occupied seats. With a Senate size of three, the approval threshold will be two approvals. Since `Dave` and `Ferdie` both approved this proposal, a member of the Triumvirate can now execute it. - -**Closing** - -`Alice` sees Senate has passed the proposal and executes the `close` extrinsic to execute the calldata within the proposal. - -Bittensor now has a new subnet on which `Alice`, `Bob`, or `Charlie` can create further proposals to change hyperparameters, allow or disallow registration, and control any other configuration previously controlled by the `sudo` private key. diff --git a/docs/governance/senate.md b/docs/governance/senate.md index e103388b4..46513ef73 100644 --- a/docs/governance/senate.md +++ b/docs/governance/senate.md @@ -2,47 +2,8 @@ title: "Senate" --- -# Senate - -The Senate is a group of delegates who have elected to participate in proposals, and who control a significant portion of total network stake. - -All members of the network who have delegated stake to any of these Senate members are represented by the party that controls the delegate they've chosen to stake with. This allows any holder within the network to be represented, and to make their opinion known by delegating with organizations who represent their interests. - -## Requirements - -In order to participate in the Senate, a coldkey must: - -- Have registered with any subnetwork as a hotkey-coldkey pair. -- Have a hotkey stake value is greater than 2% of the network's total stake amount, through delegation or self-stake. -- Have elected to participate in the Senate. - - -Once all four of the requirements have been fulfilled by a coldkey-hotkey pair, they can vote on any proposal created by the [Triumvirate](../resources/glossary#triumvirate). - -In the case that the Senate has all twelve seats filled, and a delegate wishes to join, they will replace the lowest stake member as long as they have more stake in the network. - - - -## Viewing proposals - -Anyone can view proposals currently before the senate. This is an unpermissioned request. - -```shell -btcli sudo proposals -``` - -## Voting - -Senators can vote using the following command. You will be prompted for the proposal hash, which can be obtained in the proposals overview using `btcli sudo proposals`. - -After entering a proposal hash, you will then be prompted to either cast an approval or a disapproval. Once confirmed, the vote will be included in the next block and counted in the vote. - -``` -btcli sudo senate-vote -``` + diff --git a/docs/governance/senators-btcli-guide.md b/docs/governance/senators-btcli-guide.md index 0d897ed9d..83f25cf92 100644 --- a/docs/governance/senators-btcli-guide.md +++ b/docs/governance/senators-btcli-guide.md @@ -2,8 +2,12 @@ title: "Senator's Guide to `BTCLI`" --- +import { GovernanceTransitionalState } from "./_governance-transitional-state.mdx"; + # Senator's Guide to `BTCLI` + + Governance participants (senate members, sudo-level accounts) can propose changes, cast votes, or execute privileged commands that affect the entire network. They must have a **coldkey** with the relevant governance role (senate membership or sudo privileges). See [Requirements for Senate participation](./senate) diff --git a/docs/learn/roadmap.md b/docs/learn/roadmap.md new file mode 100644 index 000000000..4045e0102 --- /dev/null +++ b/docs/learn/roadmap.md @@ -0,0 +1,195 @@ +--- +title: "Bittensor Roadmap" +--- + +# Bittensor Roadmap + +This document outlines current major development initiatives for the Bittensor protocol, which currently include: + +- [Solving the MEV problem](#solving-the-mev-problem) +- [Perfecting the Emissions Model](#perfecting-the-emissions-model) +- [The Path to Decentralization](#the-path-to-decentralization) +- [Subnet Governance](#subnet-governance) + +See also: +- [Bittensor Development Roadmap](https://www.notion.so/292ae7e8d21280f4b1b2f652c10f7f09?v=292ae7e8d212806ab31b000ca578c69b&p=2bfae7e8d2128018947cfbab29f9e03e&pm=s) +- [Church of RAO Roadmap forum](https://forum.bittensor.church/c/roadmap/9/l/latest?board=default) +- [Proposal: On-Chain Governance System for Bittensor](https://hackmd.io/mHQ9sPiCRn-vyc7ZTKBfWw) + +## Solving the MEV problem + +Throughout Bittensor's history, Maximal Extractable Value (MEV) attackers have taken a significant toll on the Bittensor token economy, as is true for many blockchain token economies. + +Maximal Extractable Value (MEV) occurs when network participants exploit transaction visibility in the mempool to profit from foreknowledge of pending transactions—enabling front-running, sandwich attacks, and other forms of parasitic extraction. MEV is a fundamental problem for Substrate/Polkadot-based chains, like Bittensor's Subtensor blockchain, as discussed in this recent Polkadot [forum thread](https://forum.polkadot.network/t/encrypted-mempools-turning-polkadots-mev-leak-into-treasury-revenue/15817). + +Bittensor's [price protection mechanism](./price-protection) has offered stakers a strong degree of protection for some time, but using it correctly can be a dauntingly complex and laborious task for many users and requires the use of programmable clients (e.g. BTCLI or the Python SDK) rather than simpler trading apps. + +Bittensor's MEV Shield, introduced in December 2025, encrypts transaction details until block inclusion and provides easy, automated protection from MEV exploits. A number of follow-up optimizations and edge-case fixes are currently in research and development and are expected to roll out to mainnet in Spring 2026, providing a mature, comprehensive, and seamless-to-use solution to the MEV problem for Bittensor. + +See [MEV Shield: Encrypted Mempool Protection](../concepts/mev-shield/) + + +## Perfecting the Emissions Model + +Bittensor's Emissions algorithm, which determines the flow of liquidity into subnets, where they are then used to incentivize participants, is continually evolving. The research and development team and many contributors from the community are working hard to invent, mathematically explore, computationally simulate and rigorously crash test, the implications of possible variants of how Bittensor could distribute tokens. All of this is required in order to find the ideal protocol for the goals of Bittensor, to promote a Bittensor ecosystem that can excel both in producing better commodities and creating a fair environment for all participants. + +The most recent major change was the shift in December 2025 to the 'TAO flow' emissions model, wherein subnets' relative emissions are determined by their net flow of TAO into/out of the subnet due to staking, whereas previously emissions were based on price. + +Further refinements are currently being explored by Opentensor Foundation researchers. Any changes to the emissions model are expected to undergo community review and discussion prior to introduction to mainnet. + +See [Emissions](../learn/emissions) + +## The Path to Decentralization + +The bulk of heavy development in Bittensor currently is oriented toward the transition from an operationally centralized project toward its eventual, planned state of full decentralization. + +Bittensor was initially created by a small team, the Opentensor Foundation (OTF) that has maintained careful operational control since its inception, in order to protect the project and ensure it could function. Eventually achieving full decentralization while maintaining operational soundness and security along every step of the way requires careful planning and execution of a series of precise steps, delegating various components of all of the control that OTF has had over the project. + +There are three essential components to this control, which must be transitioned together: + +- Blockchain validation +- Operational control (sudo/triumvirate) +- Governance + + +The protocol for decentralized governance of Bittensor is still in research and development. For the current proposal, on which this document is based, see the [governance design document](https://hackmd.io/mHQ9sPiCRn-vyc7ZTKBfWw). + + +### Decentralized Blockchain Validation + +Transitioning from Proof of Authority (PoA) to Nominated Proof of Stake (NPoS) is a foundational step toward true decentralization. + +Block production will be distributed across elected validators, and OTF will no longer have direct control. The network at that point becomes permissionlessly decentralized at the consensus layer. + +**Current Blockers:** +- Trustless MEV Shield (see below) +- Validator incentive model finalized + +#### Trustless MEV Shield + +The current MEV Shield implementation relies on a single encryption key held by the block validator, which works effectively in the Proof-of-Authority model. However, this centralized approach must be adapted to a trustless model before the NPoS transition can occur. + +#### Validator Incentives for NPoS + +The economics of running an NPoS validator need to be defined. Current thinking: +- Initially, validator incentives will likely be modest (approximately break-even) +- This is intentional — early validators should be enthusiastic participants, not pure profit-seekers +- Additional incentive mechanisms are being researched, potentially including: + - Transaction fee distribution to validators + - Registration fee allocation + +### Operational Control + +Currently, operational control of the Bittensor blockchain is exercised through the [Triumvirate](../resources/glossary#triumvirate), a [multisig](../keys/multisig) 2-of-3 that controls [sudo](../resources/glossary#sudo) operations. The Triumvirate consists of trusted developers appointed by Opentensor Foundation, who have held their keys since early in Bittensor's history, essentially acting as stewards of the blockchain on behalf of the Bittensor community. While this centralized model was beneficial in bootstrapping Bittensor, transitioning to a decentralized model is required to fulfill Bittensor's mandate for true decentralization. + +### Decentralized Governance + +The on-chain governance system being developed for Bittensor will replace the current sudo-based control with a checks-and-balanced based model. Authorized proposer accounts will submit proposals for protocol changes and runtime upgrades. The Triumvirate will vote on submitted proposals. Two collective bodies will provide oversight and accountability: the Economic Collective, composed of the top 16 validators by total stake, and the Building Collective, composed of the top 16 subnet owners by moving average price with a minimum age of 6 months. Once any proposal clears the triumvirate, these Collectives will have the power to delay the proposal for more discussion and ultimately reject it, or fast-track it for immediate deployment during a delay period following Triumvirate approval. During this delay period, members of both collectives can vote aye/nay on proposals (the exact mechanics of whether votes are considered independently per-collective or aggregated across both collectives is still being finalized). Either collective can fast-track a proposal to next-block execution with supermajority—more than 2/3—of "aye" votes, or cancel it outright with a simple majority—more than 1/2—of "nay" votes. Nay votes from both collectives accumulate to create delays based on the collective with the most nays, following an exponential backoff function (2^n × a base delay; base delay initially proposed as 1 hour, configurable), giving stakeholders time to respond to controversial proposals. + +Additionally, each collective can replace one Triumvirate member every six months through a rotating seat mechanism, ensuring accountability. Collective members who mark themselves as eligible can be randomly selected as replacement candidates, creating a pathway for major stakeholders—validators and subnet owners—to directly participate in governance leadership. + +The governance design balances efficiency with decentralization through several key principles. Gradual implementation ensures network stability is maintained throughout the transition, with the system initially coexisting alongside the current sudo implementation before fully replacing it. Stake-weighted and subnet-owner participation aligns incentives across different types of stakeholders. Checks and balances between proposal submission, Triumvirate approval, and collective oversight prevent concentration of power, while transparent on-chain processes maintain verifiability and accountability. + +The initial proposed implementation focuses on enabling proposal submission by authorized proposers, on-chain Triumvirate voting on proposals, and collective oversight through delay, fast-tracking, and cancellation mechanisms. Some details remain open and are expected to be refined through testing and community feedback (e.g., how collective voting is counted across bodies, and the nomination/acceptance flow for replacements). + +![Proposed Governance of Bittensor](/img/docs/proposal-flow.svg) + + + +## Subnet Governance + +A number of mechanisms are being researched that would give the Bittensor community formal, on-chain mechanisms for governance at the subnet level, as well as provide subnet developers with more tools for building out their token economies. The most prominent features under development are: + +### Subnet Treasury and Voting Power + +Many subnets have a need to fund work that doesn't map cleanly onto the mining work judged by validators. The Treasury feature provides a contract-controlled budget, where distributions can be decided via stake-weighted voting, in contrast to emissions which are determined by Yuma Consensus operating over the matrix of weights set by validators. + +### Subnet Policing + +Bittensor is not a platform for trading arbitrary tokens in order to extract money through luck or trickery; it is designed as a platform for funding the creation of digital commodities. It may be inevitable that subnet owners will attempt to extract emissions in a way that, from that perspective, is cheating rather than good-faith participation. This can include varieties of 'self-mining' or colluding with miners, attempting to dampen root sell pressure while still receiving injections of TAO liquidity, or attempting to use a subnet to launch a [Ponzi scheme](https://en.wikipedia.org/wiki/Ponzi_scheme) or other extractive project devoid of value. + +Historically, this sort of problem has been handled by the community of validators acting in policing roll, by submit weight matrices that burn the subnet's emissions instead of rewarding them to miners. + +The research and development and community of subnet owners and validators are currently exploring mechanisms that can optimally capture the spirit of Bittensor's need to enforce good behavior by subnet owners, in a robust, decentralized way that itself is immune to exploitation. \ No newline at end of file diff --git a/docs/resources/glossary.md b/docs/resources/glossary.md index 87128e451..511760701 100644 --- a/docs/resources/glossary.md +++ b/docs/resources/glossary.md @@ -777,7 +777,9 @@ The Bittensor SDK offers the [`bittensor.core.subtensor`](pathname:///python-api ### Sudo -A privileged key for administrative actions, replaced by governance protocol for enhanced security. +A privileged role required for administrative actions, such as changing the values of chain state variables, and subnet hyperparameters that are not accessible to subnet owners. + +On Bittensor mainnet ('finney'), sudo is controlled by the triumvirate. **See also:** [Governance](../governance/governance.md), [btcli Permissions](../btcli/btcli-permissions.md) @@ -815,7 +817,7 @@ The process of sending TAO tokens from one wallet address to another in the Bitt ### Triumvirate -A group of three Opentensor Foundation employees responsible for creating proposals. +A group of three Opentensor Foundation employees that controls the sudo key. **See also:** [Governance](../governance/governance.md), [Senate](../governance/senate.md) diff --git a/sidebars.js b/sidebars.js index dd26ca019..a1eb82300 100644 --- a/sidebars.js +++ b/sidebars.js @@ -46,6 +46,7 @@ const sidebars = { collapsed: true, items: [ "learn/introduction", + "learn/roadmap", "resources/questions-and-answers", "subnets/understanding-subnets", "learn/anatomy-of-incentive-mechanism", diff --git a/static/img/docs/proposal-flow.svg b/static/img/docs/proposal-flow.svg new file mode 100644 index 000000000..b822be6f1 --- /dev/null +++ b/static/img/docs/proposal-flow.svg @@ -0,0 +1 @@ +On-Chain Governance: Proposal FlowOn-Chain Governance: Proposal FlowAuthorized ProposerTriumvirateEconomic CollectiveBuilding CollectiveChainAuthorized ProposerAuthorized ProposerTriumvirateTriumvirateEconomic CollectiveEconomic CollectiveBuilding CollectiveBuilding CollectiveChainChainProposal SubmissionAn authorized proposer submits a proposal containing a runtime upgradeor any root extrinsic.submit_proposal(call)Proposal enters "Triumvirate Voting".Triumvirate Voting Period7 days to reach 2/3 votes2/3 nay votes rejects immediatelyvote(aye/nay)opt[2-of-3 ayes reached]approve[2-of-3 nays reached OR 7 day timeout]rejectDelay Period for Collectives OversightDelay Period (initially 1 hour)Either collective can vote to approve or delay proposalpar[A Collective votes]vote(aye/nay)[Building Collective votes]vote(aye/nay)opt[Fast-track]More than 2/3 of aye vote for any collective fast tracks the proposalopt[Cancel]More than 1/2 of nay vote for any collective cancels the proposalopt[Delay adjustments]recompute delay as votes changeWhen delay is reduced below time already elapsed,the delay period ends and execution begins.ExecutionAfter the delay period expires (and if not cancelled),the chain executes the call with root privilege.If execution fails, it is not retried and is cleaned up.execute(call as Root)alt[success]cleanup[failure]cleanup (no retry) \ No newline at end of file