Introduce SubtensorApi interface for SDK

[basfroman]

Depends: opentensor/async-substrate-interface#100 (until this PR is merged, most tests fail)

SubtensorApi – Usage Guide

The SubtensorApi is a high-level, unified interface to interact with the Bittensor blockchain. It wraps both the synchronous and asynchronous Subtensor implementations, providing modular access to chain subsystems like wallets, delegates, neurons, and more.

---

1. Basic Synchronous Usage (default)

import bittensor as bt

sub = bt.SubtensorApi()

print(sub.block)  # Get current block number
print(sub.delegates.get_delegate_identities())
sub.chain.tx_rate_limit()

---

2. Asynchronous Usage

import bittensor as bt
import asyncio

async def main():
    sub = bt.SubtensorApi(async_subtensor=True)
    async with sub:
        print(await sub.block)
        print(await sub.delegates.get_delegate_identities())
        await sub.chain.tx_rate_limit()

asyncio.run(main())

---

3. Legacy Method Support

You can enable all legacy methods from the original Subtensor class directly on this interface:

import bittensor as bt

sub = bt.SubtensorApi(legacy_methods=True)
print(sub.bonds(0))  # Classic method usage

---

4. Retry and Fallback RPC Nodes

Enable redundancy and resilience with fallback chains and retry logic:

import bittensor as bt

sub = bt.SubtensorApi(
    "local",
    fallback_chains=[
        "wss://fallback1.taonetwork.com:9944",
        "wss://lite.sub.latent.to:443",
    ],
    retry_forever=True,
)
print(sub.block)

---

5. Mock Mode for Testing

Use mock=True to simulate the interface without connecting to the blockchain:

import bittensor as bt

sub = bt.SubtensorApi(mock=True)
print(sub)  # Output: "<Network: None, Chain: Mock, Sync version>"

---

6. Subsystem Overview

All methods are grouped into logical modules for better organization and readability. Some methods may belong to more than one group if they span multiple functional areas. This does not compromise the internal logic — rather, it enhances discoverability and cohesion. Method equivalence between SubtensorApi and the original Subtensor is automatically verified by test coverage on every pull request (PR).

The following properties are modular access points for specialized subsystems:

Property	Description
chain	Blockchain interaction methods
commitments	Commitment and reveal logic
delegates	Delegate management tools
extrinsics	Transaction construction and signing
metagraphs	Metagraph data and operations
neurons	Neuron-level APIs
queries	General query endpoints
stakes	Staking operations
subnets	Subnet access and management
wallets	Wallet creation, import/export

---

7. Custom Configuration Support

You can pass a pre-built Config object:

import argparse
import bittensor as bt
parser = argparse.ArgumentParser('Miner')
bt.SubtensorApi.add_args(parser)
config = bt.config(parser)
sub = bt.SubtensorApi(config=config)

print(sub)

---

8. Using as a Context Manager (Synchronous)

import bittensor as bt

with bt.SubtensorApi() as sub:
    print(sub.block)

---

9. Using as a Context Manager (Asynchronous)

import bittensor as bt
import asyncio

async def main():
    async with bt.SubtensorApi(async_subtensor=True) as sub:
        print(await sub.block)

asyncio.run(main())

[thewhaleking]

Small changes, otherwise g2g