███████╗██╗   ██╗██████╗ ████████╗███████╗███╗   ██╗███████╗ ██████╗ ██████╗
██╔════╝██║   ██║██╔══██╗╚══██╔══╝██╔════╝████╗  ██║██╔════╝██╔═══██╗██╔══██╗
███████╗██║   ██║██████╔╝   ██║   █████╗  ██╔██╗ ██║███████╗██║   ██║██████╔╝
╚════██║██║   ██║██╔══██╗   ██║   ██╔══╝  ██║╚██╗██║╚════██║██║   ██║██╔══██╗
███████║╚██████╔╝██████╔╝   ██║   ███████╗██║ ╚████║███████║╚██████╔╝██║  ██║
╚══════╝ ╚═════╝ ╚═════╝    ╚═╝   ╚══════╝╚═╝  ╚═══╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝

Subtensor

The Bittensor monorepo. It contains the subtensor chain (a Substrate-based blockchain), the Python SDK and btcli, the documentation, and the website that renders it — all in one place so a single change can be validated end-to-end before it ships.

Full documentation: bittensor.com/docs

That site is the source of truth for using Bittensor: install, wallets, staking, subnets, EVM, every transaction and query, error codes, and contributor guides. The markdown lives in docs/ and is published by website/.

What Bittensor is

Bittensor is an open network where independent subnets produce digital commodities — compute, inference, storage, prediction — and the chain pays participants in TAO in proportion to the value they contribute. Miners produce, validators score, subnet owners define incentive mechanisms, and stakers back validators.

The subtensor chain is the trust layer: it runs consensus, records subnet and neuron state, handles staking and emissions, and moves value. Work itself happens off-chain inside subnets; the chain coordinates and pays for it. Subtensor also exposes a full EVM (Frontier) and ink!/wasm smart contracts alongside native Substrate extrinsics.

What's in this repo

Area	Path	What it is
Chain runtime	pallets/, runtime/	FRAME pallets and the composed runtime. pallets/subtensor/ is the core (staking, subnets, emissions, weights).
Node	node/	The node-subtensor binary: networking, RPC, chain specs.
EVM	precompiles/	Precompiles that expose substrate functionality to EVM contracts.
Wasm contracts	chain-extensions/, ink-contract/	Chain extensions and ink! contract sources.
Shared Rust	common/, primitives/, support/	Shared types, math primitives, lints, macros, weight tooling.
Client core	sdk/bittensor-core/	The Rust core for Bittensor clients (keypairs, keyfiles, SCALE codec, extrinsic assembly, RFC-0078 digest, drand timelock, ML-KEM) — built against the same crate revisions as the chain; Python bindings in sdk/bittensor-core-py/.
Python SDK	sdk/python/	The bittensor package and btcli CLI. Generated from chain metadata so reads, writes, and docs cannot drift.
Documentation	docs/	Source for bittensor.com/docs. docs/tx/, docs/query/, and docs/errors.mdx are generated — do not hand-edit.
Website	website/	Yarn + Turbo monorepo; apps/bittensor-website renders marketing pages and these docs.
Tests	ts-tests/, clones/, eco-tests/	Moonwall/zombienet integration tests, mainnet-clone regression harness, indexer contract tests.
Operations	chainspecs/, scripts/, Dockerfile	Chain specs, CI/dev scripts, production and localnet Docker images.

Deeper map: Repository layout.

How the monorepo fits together

A runtime change can break the SDK, the docs, or live mainnet state. This repo keeps those surfaces in sync:

1. Metadata-driven SDK. The Python layer (bittensor.storage, runtime_api, calls, constants) is emitted from a node's runtime metadata. Hand-written reads and intents sit on top; the CLI (btcli query …, btcli tx …) is generated from the same registries. CI proves every chain call is either wrapped by an intent or explicitly marked raw-only.

2. Docs generated from the same registries. Transaction, query, and error reference pages in docs/ are built from the SDK catalogs, so bittensor.com/docs always matches what btcli and import bittensor expose.

3. CI validates the whole stack. On every PR, Rust checks run alongside a mainnet-clone upgrade (your runtime applied to a copy of live state), Python SDK suites, and a docs build. Runtime migrations are replayed with try-runtime.

4. Release train. Merging to main builds the runtime once (deterministic srtool build) and promotes it devnet → testnet → mainnet. The SDK and docs publish after the chain upgrade lands. See Release process.

Where to start

Pick the path that matches what you are doing — the linked docs have the detail.

You want to…	Start here
Install the SDK and run your first query/tx	Quickstart
Use btcli or the Python API day-to-day	CLI · SDK README
Build an agent on top of the chain	For agents · /catalog/intents.json
Understand subnets, TAO, epochs, wallets	Concepts
Run a local chain for development	Local development
Operate a mainnet/testnet node	Running a node
Develop or change the chain/runtime	Rust setup · Testing
Contribute a PR	Contributing · CONTRIBUTING.md

Minimal local chain (Docker)

docker run --rm --name local_chain \
  -p 9944:9944 -p 9945:9945 \
  ghcr.io/raofoundation/subtensor-localnet:devnet

Then connect with btcli --network local query is-fast-blocks or bittensor.Client("local"). See local development for building from source, the Alice dev account, and faucet behavior.

Minimal chain build (from source)

./scripts/init.sh        # Rust toolchain + wasm target
./scripts/localnet.sh    # build and launch a fast-blocks localnet

The node binary is node-subtensor (cargo build --release → ./target/release/node-subtensor). Extrinsic and query reference: Transactions · Queries.

Minimal SDK dev (from this repo)

cd sdk/python
just sync    # uv environment; builds bittensor-core from ../bittensor-core-py (in sdk/)
just check   # lint, typecheck, unit tests, codegen gates (same as CI)

End-to-end tests against a running localnet: just e2e. See SDK tests.

Chain architecture (high level)

                    ┌─────────────────────────────────────┐
                    │           node-subtensor            │
                    │  (libp2p, RPC, tx pool, executor)   │
                    └─────────────────┬───────────────────┘
                                      │ executes
                    ┌─────────────────▼───────────────────┐
                    │     node-subtensor-runtime (wasm)     │
                    │  ┌─────────────┐  ┌────────────────┐  │
                    │  │ pallet-     │  │ Frontier EVM   │  │
                    │  │ subtensor   │  │ + precompiles  │  │
                    │  │ + swap,     │  │ + pallet-      │  │
                    │  │   shield,   │  │   contracts    │  │
                    │  │   proxy, …  │  └────────────────┘  │
                    │  └─────────────┘                       │
                    └───────────────────────────────────────┘

• Runtime (runtime/src/lib.rs): composes pallets, defines spec_version, hosts migrations and runtime APIs.
• Core pallet (pallets/subtensor/): subnets, registration, staking, weights, emissions, delegates, commitments.
• EVM: Substrate accounts (ss58) and EVM accounts (h160) are separate signing domains on the same chain; precompiles bridge staking and balances into Solidity. Guide: EVM.
• Networks: finney (mainnet), test (testnet), local (dev node). Public endpoints and lite vs archive nodes: The network.

Contributing

Open PRs against main. Runtime-affecting changes need tests, a spec_version bump (or the no-spec-version-bump label), and three positive reviews. Full lifecycle and release train: Contributing.

License

See LICENSE. Individual crates may declare their own SPDX identifier in Cargo.toml / pyproject.toml.

Community

• Discord
• GitHub