Sentinel SDK

Sentinel SDK is a Python toolkit for extracting and working with Bittensor blockchain data. It provides a typed, versioned API for reading chain state — extrinsics, events, hyperparameters, metagraph snapshots, and subnet info — without dealing with raw substrate calls.

Features:

• Blockchain data extraction — extrinsics, events, hyperparameters, metagraph snapshots, and subnet info with typed Pydantic DTOs
• Pluggable providers — connect via the Bittensor SDK directly or through Pylon caching proxy
• CLI — query chain data from the terminal (extrinsics, events, hyperparameters, metagraph)
• Testing utilities — factories and a fake provider for writing tests without a live node (see docs/testing.md)
• Versioned API — uses ApiVer (sentinel.v1) to guarantee backwards compatibility

Installation

pip install bittensor-sentinel

Usage

[!IMPORTANT] This package uses ApiVer, make sure to import sentinel.v1.

As a library

from sentinel.v1.providers.bittensor import bittensor_provider
from sentinel.v1.services.sentinel import sentinel_service

provider = bittensor_provider()
service = sentinel_service(provider)

# Extract extrinsics and events from a block
block = service.ingest_block(block_number=4_000_000)
for extrinsic in block.extrinsics:
    print(extrinsic.call.call_module, extrinsic.call.call_function)

# Extract metagraph snapshot for a subnet
subnet = service.ingest_subnet(netuid=1, block_number=4_000_000)
snapshot = subnet.metagraph
for neuron in snapshot.neurons:
    print(neuron.uid, neuron.neuron.hotkey.hotkey)

CLI

# Read extrinsics from a block
sentinel extrinsics --block 4000000

# Read events from a block
sentinel events --block 4000000

# Query subnet metagraph
sentinel subnet --netuid 1 metagraph

# JSON output
sentinel -f json extrinsics --block 4000000

Pylon provider

Pylon is a caching proxy for the Bittensor network that provides faster neuron and validator queries. Sentinel supports it as an alternative provider.

1. Run a Pylon instance (see Pylon documentation).
2. Set the environment variables (optional — PYLON_URL defaults to http://localhost:8000):

   export PYLON_URL="http://your-pylon-instance:8090"
   export PYLON_OPEN_ACCESS_TOKEN="your-token"  # only if Pylon requires authentication
   

Use PylonProvider as an alternative for the supported provider operations:

from sentinel.v1.providers.pylon import pylon_provider

# Uses PYLON_URL env var, or pass url directly
provider = pylon_provider(url="http://localhost:8090")

# Fetch metagraph (constructed from Pylon neuron data, always lite mode)
metagraph = provider.get_metagraph(netuid=1, block_number=100000, lite=True)

# Pylon-specific methods (not in the base BlockchainProvider interface)
neurons = provider.get_neurons(netuid=1, block_number=100000)
validators = provider.get_validators(netuid=1, block_number=100000)
latest = provider.get_latest_neurons(netuid=1)

[!NOTE] PylonProvider does not support full block info, block events, extrinsics listing or status, subnet hyperparameters, subnet registry listing (get_all_subnets_netuids), historical block timestamps (get_block_timestamp), or subnet emission state (get_subnet_emission_enabled). Unsupported event/extrinsic operations and the three named methods raise NotImplementedError; full block info and subnet hyperparameters return None. Use BittensorProvider for full chain access.

Or via CLI with the --provider pylon flag:

sentinel subnet --netuid 1 --provider pylon metagraph
sentinel subnet --netuid 1 --provider pylon --network http://my-pylon:8090 metagraph

Versioning

This package uses Semantic Versioning. TL;DR you are safe to use compatible release version specifier ~=MAJOR.MINOR in your pyproject.toml or requirements.txt.

Additionally, this package uses ApiVer to further reduce the risk of breaking changes. This means, the public API of this package is explicitly versioned, e.g. sentinel.v1, and will not change in a backwards-incompatible way even when sentinel.v2 is released.

Internal packages, i.e. prefixed by sentinel._ do not share these guarantees and may change in a backwards-incompatible way at any time even in patch releases.

Development

Pre-requisites:

• uv
• nox
• docker and docker compose plugin

Ideally, you should run nox -t format lint before every commit to ensure that the code is properly formatted and linted. Before submitting a PR, make sure that tests pass as well, you can do so using:

nox -t check # equivalent to `nox -t format lint test`

If you wish to install dependencies into .venv so your IDE can pick them up, you can do so using:

uv sync --all-extras --dev

Release process

Run nox -s make_release -- X.Y.Z where X.Y.Z is the version you're releasing and follow the printed instructions.