Subtensor Architecture
How Subtensor works under the hood. This guide explains the runtime architecture, what you can query, and what's computed on-chain.
What is Subtensor?
Subtensor is the blockchain layer of the Bittensor network. It's built on Substrate, the same framework that powers Polkadot, and handles:
Runtime Architecture
Subtensor is a Substrate runtime compiled to WebAssembly (WASM). The blockchain logic runs inside a WASM virtual machine on every node, so runtime upgrades can be deployed without restarting the network.
Upgradeable on-chain
Queryable interface
The metadata describes what you can call and query. The WASM runtime contains the actual logic. You can query metadata, but you can't query the Rust code directly.
What's in Metadata
Runtime metadata describes the interface to the blockchain – this is what you can query and interact with via RPC.
Pallets
Modules that group related functionality. SubtensorModule, Balances, System, etc.
View all palletsEvents
Notifications emitted when things happen. StakeAdded, NeuronRegistered, WeightsSet.
Calls
Extrinsics you can submit. add_stake, register, set_weights, transfer.
Storage
On-chain state you can query. Alpha, Uids, Weights, TotalIssuance.
Constants
Fixed values baked into the runtime. Can change on runtime upgrade.
Errors
Failure modes for calls. NotEnoughBalanceToStake, InvalidUid, etc.
Block Execution Flow
Each block goes through a defined execution flow. Understanding this helps you know when things happen.
on_initialize
Start of block. Epoch checks happen here. If tempo blocks have passed, epoch() runs.
Execute Extrinsics
User transactions are processed in order. Each call either succeeds (emits events) or fails (returns error). Storage is updated.
on_finalize
End of block. Cleanup and finalization. Block hash is computed.
Block Produced
Block is sealed and propagated to other nodes. ~12 second block time.
Epochs and Yuma Consensus
An epoch is a period after which rewards are calculated and distributed. Each subnet has its own tempo (epoch length in blocks).
What Happens Each Epoch
Gather the weight matrix from all validators : who scored whom and how much.
Miners get incentive (based on their rank). Validators get dividends (based on their bonds/stake).
The consensus algorithm is compiled Rust code – not queryable metadata. To understand
the math, you need to read the source code in epoch/math.rs.
Key Storage Items
All of these values are stored on-chain and queryable via RPC. They differ in when they update: some change immediately when a user submits a transaction, others are recomputed by Yuma Consensus at each epoch boundary.
| Value | Updates | Storage Key |
|---|---|---|
| Stake amount | On transaction | SubtensorModule.Alpha |
| Weight matrix | On transaction | SubtensorModule.Weights |
| Neuron UID | On transaction | SubtensorModule.Uids |
| Rank | Each epoch | SubtensorModule.Rank |
| Trust | Each epoch | SubtensorModule.Trust |
| Incentive | Each epoch | SubtensorModule.Incentive |
| Dividends | Each epoch | SubtensorModule.Dividends |
| Pending emissions | Each block | SubtensorModule.PendingServerEmission, PendingValidatorEmission |
Source Code Reference
The Subtensor runtime is open source. Key files for understanding the implementation:
pallets/subtensor/src/
Main SubtensorModule pallet. Staking, registration, weights, delegation
epoch/run_epoch.rs
Yuma consensus implementation. Covers epoch_mechanism(), rank, trust, incentive, dividends
epoch/math.rs
Math utilities. Weighted median, matrix operations, EMA, normalization
staking/
Staking operations. Covers add_stake, remove_stake, stake management