DOCSEARCHbyAlgolia
Submit Docs

Subtensor Documentation

repository·main·Indexed 18 days ago

https://github.com/raofoundation/subtensor

Implementation of the Bittensor blockchain. This monorepo contains the Substrate-based blockchain (subtensor), Python SDK, btcli command-line interface, and documentation. It includes technical details on the Crowdloan Pallet for fund raising and subnet leasing, the Drand Bridge Pallet for verifiable on-chain randomness, and the pallet-limit-orders for off-chain limit order execution (LimitBuy, TakeProfit, and StopLoss).

Tokens
473.5K
Snippets
1.5K
Records
2K
Agent score
58%

What's inside subtensor

  1. Overview of pallet-shield for MEV shielding

    main

    The pallet-shield is a FRAME pallet designed for opt-in, per-block ephemeral-key encrypted transactions. It provides MEV (Maximal Extractable Value) shielding by allowing users to encrypt their extrinsics, preventing front-running and sandwich attacks.

    Block authors rotate ML-KEM-768 key pairs every slot via a mandatory inherent. Users encrypt their extrinsics to the next block author's encapsulation key, ensuring that only the intended block author can decrypt and include the transaction.

  2. Overview of Bittensor components

    main

    Bittensor is a decentralized network where subnets produce digital commodities. The architecture consists of:

    • Subnets: Independent networks producing compute, inference, storage, etc.
    • Miners: Participants that produce value.
    • Validators: Participants that score miners.
    • Stakers: Participants that back validators with TAO.
    • Subtensor (The Chain): The trust layer that runs consensus, manages staking/emissions, and coordinates subnets. It also provides an EVM (Frontier) and ink!/wasm smart contract environment.

  3. Use the Drand Bridge Pallet in Substrate Runtimes

    main

    The Drand Bridge Pallet is a FRAME pallet that allows Substrate-based chains to bridge to drand's Quicknet, providing verifiable on-chain randomness every 3 seconds. This randomness can be consumed by both runtime modules (pallets) and ink! smart contracts.

    Node Requirements

    To use this pallet, your node must support:

    • arkworks host functions
    • Offchain workers
    • For smart contract support: The Contracts pallet and the drand chain extension must be enabled.

  4. Understand the Apps Monorepo structure and deployment

    main

    The Apps Monorepo contains the frontend applications and shared configuration packages used by the Bittensor ecosystem.

    Apps

    • @raofoundation/bittensor-website: The primary website.
      • Staging: Automatically deployed to staging when changes are pushed to the main branch via the deploy-docs.yml workflow.
      • Production: Promoted to production automatically via watch-mainnet-release.yml once a runtime release is executed on-chain.

    Shared Packages

    • @raofoundation/ui: Shared frontend UI components.
    • eslint-config-custom: Shared ESLint configurations.
    • tsconfig: Shared TypeScript configurations.

  5. Manage crowdloans with the Crowdloan Pallet

    main

    The Crowdloan Pallet allows users to create and manage generic crowdloans designed to raise funds for either transferring assets to a target address or executing an arbitrary call.

    Core Workflow

    1. Creation: A creator establishes a crowdloan by providing a deposit, a cap, an end block, and either a target address OR a call (but not both or neither).
    2. Contribution: Users contribute funds to the crowdloan. Contributions can be withdrawn as long as the crowdloan is not yet finalized or dissolved.
    3. Finalization: Once the cap is reached, the creator can finalize the crowdloan.
      • If a target address was provided: Funds are transferred to that account.
      • If a call was provided: The call is dispatched using the creator's origin, and the current crowdloan ID is stored as a temporary item.
    4. Failure Handling: If the cap is not reached, the creator can refund contributors and then dissolve the crowdloan to reclaim their initial deposit.

    Key Constraints

    • The target address or call provided at creation is immutable.
    • Only the minimum contribution, maximum contribution, end block, and cap can be updated by the creator after creation.

  6. Use btcli command groups

    main

    The btcli tool is organized into functional groups. Most commands are dynamically generated from the same registries as the Python API:

    • btcli query <name>: Used for all read operations. Run query --help to see commands grouped by topic.
    • btcli tx <name>: Used for all transactions. Run tx --help to see commands grouped by pallet. All transaction commands support --dry-run, --yes, and --proxy-for.
    • btcli evm: Access the EVM layer (keys, funding, precompiles, and contract deployment).
    • btcli tools: Provides a JSON catalog of every transaction operation with schemas, intended for use by agents.

    Hand-written workflow groups: wallet, stake, subnets, weights, axon, proxy, multisig, crowd, lock, timelock, and config provide high-level wrappers for common tasks.

  7. Understand the Subtensor monorepo structure

    main

    The Subtensor repository is a monorepo containing the Substrate chain, Python SDK, documentation, and websites. This structure allows a single Pull Request to validate runtime changes against all dependent client surfaces (SDKs, docs, etc.) via a single CI run.

    The repository is organized into four primary functional areas:

    1. The Chain: Rust-based Substrate logic (pallets, runtime, node).
    2. Tests and Test Harnesses: Integration tests (TypeScript) and mainnet-clone regression tests.
    3. SDK, Docs, and Web: Client-side tools including the Rust core, Python SDK, and documentation.
    4. Chain Data and Operations: Chain specifications, genesis state, and deployment scripts.

  8. What is the max-weight-limit hyperparameter?

    main
    The max_weight_limit is a hyperparameter that defines a normalized-fraction cap on any single weight within a submitted vector. After the chain normalizes the submitted vector, no individual weight may exceed max_weight_limit / 65535 of the total weight. It is important to note that this is not a raw u16 ceiling per weight, but a relative limit based on the normalized total.

  9. What is included in bittensor-core

    main

    The bittensor-core package (imported as bittensor_core) contains all primitives whose logic is strictly defined by the chain. This ensures parity between the Python client and the subtensor runtime.

    Included primitives:

    • Key Primitives: sr25519, ed25519, and SS58 address formats.
    • Encryption: Keyfile encryption/decryption, drand timelock encryption, and ML-KEM-768.
    • Data & Encoding: SCALE codec, runtime-metadata engine, and RFC-0078 merkleized-metadata digest.
    • Chain Operations: Extrinsic assembly.

    Note: Product-level logic such as intents, policy, CLI UX, and transports are not in this package; they reside in the higher-level Python SDK.

  10. What is Yuma Consensus?

    main

    Yuma Consensus is Bittensor's subjective utility consensus mechanism. It is designed for high-volume networks where utility is subjective (e.g., community-curated content) rather than objectively measurable (e.g., storage or computation).

    Its primary goal is to reward subnet validators for producing evaluations of miner-value that align with the stake-weighted consensus of other validators. It protects the network by:

    • Penalizing selfish scoring: Using down-correction to the majority consensus and slashing the voting stake of 'cabals' (colluding minority groups).
    • Protecting honest servers: Preventing minority cabals from unfairly low-scoring honest servers by using stake-based median scoring.

    Note: Yuma Consensus pertains to subnet validation, not blockchain validation (which is handled by Substrate).

  11. How the v11 Metagraph works

    main

    In v11, the metagraph is no longer a collection of parallel NumPy arrays (like mg.S, mg.W, mg.B). Instead, it is a plain typed object containing per-neuron records.

    MetagraphNeuron Fields:

    • uid, hotkey, coldkey
    • incentive, dividends, rank, trust, consensus (all 0..1 floats)
    • emission, alpha_stake, tao_stake, total_stake (Balances)
    • axon (string in format "ip:port" or None)

    Metagraph Object Access:

    • Access lists via mg.hotkeys, mg.coldkeys, or mg.validators.
    • Access specific neurons via mg.neuron(uid) or mg.by_hotkey("...").
    • To get weight or bond matrices, use await client.weights.weights(netuid=...) or await client.weights.bonds(netuid=...).
    • To refetch the metagraph for a specific block, use client.subnets.metagraph(netuid, block=...).

    Note on Persistence: The .save() and .load() methods are removed. You must persist mg.raw yourself if needed.

    Note on Wire Format: The metagraph returned by client.subnets.metagraph has decoded text for name and symbol. If you require the compact-u16 vector wire format, call the runtime API directly:

    mg = await client.subnets.metagraph(netuid=1)
for n in mg:                      # MetagraphNeuron, ordered by uid
    n.uid, n.hotkey, n.coldkey
    n.incentive, n.dividends, n.rank, n.trust, n.consensus   # 0..1 floats
    n.emission, n.alpha_stake, n.tao_stake, n.total_stake    # Balance
    n.axon                        # "ip:port" or None
mg.hotkeys, mg.coldkeys, mg.validators
mg.neuron(5), mg.by_hotkey("5F...")

# To get the undecoded wire record:
await client.runtime(bt.runtime_api.SubnetInfoRuntimeApi.get_metagraph, [netuid])

  12. Handle Subnet Ownership and Emissions changes

    main

    Starting with the v11 package/runtime, subnet ownership and emission calculations have changed:

    Subnet Ownership

    For subnets that are at least one year old, ownership transfers to the highest-conviction hotkey when total conviction reaches 10% of SubnetAlphaOut. Existing conviction counts toward this threshold.

    Cross-subnet Emissions

    Allocation now uses EMA price adjusted by miner burn. The root_proportion is no longer included in the inter-subnet split (though it still applies inside each subnet for injection caps and root dividends). You must update any emission calculations or forecasts to account for this change.