Skip to content

Resource Allocation API

Relevant Source Files

The Resource Allocation API is a FastAPI-based web service that provides programmatic access to GPU compute resources within the NI Compute Subnet. It serves as the primary interface for external clients to discover, allocate, deallocate, and manage computational resources provided by subnet miners.

This system handles the complete lifecycle of resource allocation, from initial discovery through active management of allocated containers. For information about the underlying miner resource provisioning, see Miner System. For details about the validation and scoring of these resources, see Validator System.

The Resource Allocation API is implemented as the RegisterAPI class in neurons/register_api.py:229-3251 . It operates as a standalone FastAPI application that interfaces with the Bittensor network, local databases, and distributed state management systems.

graph TB
    subgraph "External Clients"
        CLI["CLI Client"]
        WEB["Web Applications"]
        API_CLIENTS["API Clients"]
    end
    
    subgraph "RegisterAPI Core"
        FASTAPI["FastAPI Application"]
        ROUTES["Route Handlers"]
        MODELS["Pydantic Models"]
    end
    
    subgraph "Resource Management"
        ALLOCATE["_allocate_container()"]
        HOTKEY_ALLOC["_allocate_container_hotkey()"]
        HEALTH_CHECK["_check_allocation()"]
    end
    
    subgraph "State Management"
        LOCAL_DB["ComputeDb (SQLite)"]
        WANDB_STATE["WandB Integration"]
        METAGRAPH["Bittensor Metagraph"]
    end
    
    subgraph "Network Communication"
        DENDRITE["Bittensor Dendrite"]
        MINERS["Subnet Miners"]
    end
    
    CLI --> FASTAPI
    WEB --> FASTAPI
    API_CLIENTS --> FASTAPI
    
    FASTAPI --> ROUTES
    ROUTES --> MODELS
    ROUTES --> ALLOCATE
    ROUTES --> HOTKEY_ALLOC
    
    ALLOCATE --> DENDRITE
    HOTKEY_ALLOC --> DENDRITE
    DENDRITE --> MINERS
    
    ROUTES --> LOCAL_DB
    ROUTES --> WANDB_STATE
    HEALTH_CHECK --> METAGRAPH
    
    HEALTH_CHECK --> DENDRITE

Sources: neurons/register_api.py:229-3251

The RegisterAPI class initializes a FastAPI application with SSL support and middleware for IP whitelisting when enabled. The application runs on port 8903 by default and requires SSL certificates for secure communication.

graph LR
    subgraph "RegisterAPI.__init__()"
        CONFIG["Configuration Setup"]
        WALLET["Bittensor Wallet"]
        SUBTENSOR["ComputeSubnetSubtensor"]
        DENDRITE["Bittensor Dendrite"]
        METAGRAPH["Network Metagraph"]
        WANDB["ComputeWandb"]
        FASTAPI_APP["FastAPI Application"]
    end
    
    CONFIG --> WALLET
    CONFIG --> SUBTENSOR
    WALLET --> DENDRITE
    SUBTENSOR --> METAGRAPH
    CONFIG --> WANDB
    CONFIG --> FASTAPI_APP
    
    FASTAPI_APP --> ROUTES["_setup_routes()"]
    ROUTES --> MIDDLEWARE["IPWhitelistMiddleware"]

Sources: neurons/register_api.py:229-342 , neurons/register_api.py:314-323

The API uses Pydantic models to define request and response structures:

ModelPurposeKey Fields
DeviceRequirementGPU resource specificationsgpu_type, gpu_size, ram, timeline
DockerRequirementContainer configurationbase_image, ssh_key, dockerfile
AllocationAllocation response datahotkey, ssh_ip, ssh_port, uuid_key
ResourceResource informationgpu_name, gpu_capacity, allocate_status
ResourceQueryResource filteringgpu_name, cpu_count_min/max, capacity ranges

Sources: neurons/register_api.py:147-214 , neurons/register_api.py:156-168

  • Endpoint: POST /service/allocate_spec
  • Handler: neurons/register_api.py:434-547
  • Purpose: Allocates resources based on GPU specifications and requirements
  • Process: Discovers suitable miners, validates availability, provisions container
  • Endpoint: POST /service/allocate_hotkey
  • Handler: neurons/register_api.py:576-695
  • Purpose: Allocates a specific miner’s resources by hotkey
  • Process: Direct allocation to specified miner with container provisioning
  • Endpoint: POST /service/deallocate
  • Handler: neurons/register_api.py:725-850
  • Purpose: Releases allocated resources and cleans up containers
  • Process: Validates UUID, sends deallocation signal to miner, updates state

The API provides Docker container lifecycle management:

EndpointPurposeHandler Location
/service/restart_dockerRestart allocated container neurons/register_api.py:920-1012
/service/pause_dockerPause container execution neurons/register_api.py:1027-1114
/service/unpause_dockerResume paused container neurons/register_api.py:1129-1215
/service/exchange_docker_keyUpdate SSH keys neurons/register_api.py:1230-1317
graph TD
    subgraph "Resource Listing"
        SQL_LIST["/list/resources_sql"]
        WANDB_LIST["/list/resources_wandb"]
        ALLOC_LIST["/list/allocations_sql"]
    end
    
    subgraph "Data Sources"
        COMPUTE_DB["ComputeDb (Local)"]
        WANDB_API["WandB API"]
        MINER_SPECS["get_miner_details()"]
    end
    
    subgraph "Filtering & Pagination"
        RESOURCE_QUERY["ResourceQuery Model"]
        PAGINATE["_paginate_list()"]
    end
    
    SQL_LIST --> COMPUTE_DB
    SQL_LIST --> MINER_SPECS
    WANDB_LIST --> WANDB_API
    WANDB_LIST --> MINER_SPECS
    
    SQL_LIST --> RESOURCE_QUERY
    WANDB_LIST --> RESOURCE_QUERY
    RESOURCE_QUERY --> PAGINATE
    
    ALLOC_LIST --> COMPUTE_DB

Sources: neurons/register_api.py:1441-1644 , neurons/register_api.py:1847-2053 , neurons/register_api.py:1346-1419

The allocation process involves candidate discovery, availability checking, and container provisioning:

sequenceDiagram
    participant Client
    participant RegisterAPI
    participant ComputeDb
    participant Dendrite
    participant Miner
    participant WandB
    
    Client->>RegisterAPI: "/service/allocate_spec"
    RegisterAPI->>ComputeDb: "select_allocate_miners_hotkey()"
    ComputeDb-->>RegisterAPI: "candidate_hotkeys[]"
    
    RegisterAPI->>Dendrite: "Allocate(checking=True)"
    Dendrite->>Miner: "Check availability"
    Miner-->>Dendrite: "availability_response"
    Dendrite-->>RegisterAPI: "final_candidates[]"
    
    RegisterAPI->>RegisterAPI: "Sort by scores"
    RegisterAPI->>Dendrite: "Allocate(checking=False)"
    Dendrite->>Miner: "Provision container"
    Miner-->>Dendrite: "ssh_credentials"
    Dendrite-->>RegisterAPI: "allocation_response"
    
    RegisterAPI->>ComputeDb: "update_allocation_db()"
    RegisterAPI->>WandB: "_update_allocation_wandb()"
    RegisterAPI-->>Client: "Allocation details"

Sources: neurons/register_api.py:2733-2805 , neurons/register_api.py:2807-2889

The _check_allocation() method continuously monitors allocated resources:

  • Frequency: Every 180 seconds (ALLOCATE_CHECK_PERIOD)
  • Timeout Handling: Deallocates after 20 consecutive failures (ALLOCATE_CHECK_COUNT)
  • Notifications: Sends webhook notifications for status changes
  • Implementation: neurons/register_api.py:3002-3100

Resource state is maintained across multiple systems:

SystemUpdate MethodPurpose
Local SQLiteupdate_allocation_db()Persistent allocation tracking
WandB_update_allocation_wandb()Distributed state sharing
Metagraph_refresh_metagraph()Network topology updates

Sources: neurons/register_api.py:2891-2919 , neurons/register_api.py:2921-2929

The API integrates deeply with Bittensor network components:

  • Subtensor: Uses ComputeSubnetSubtensor for blockchain interaction
  • Dendrite: Communicates with miners via Allocate protocol messages
  • Metagraph: Maintains current network state and miner information
  • Wallet: Provides cryptographic identity for API operations

Sources: neurons/register_api.py:264-276

The API uses ComputeDb for local state persistence with the following key operations:

WandB serves as distributed state management:

  • Allocated Hotkeys: Tracks resources across all validators
  • Miner Specifications: Hardware details and availability
  • Penalized Hotkeys: Blacklist management
  • Implementation: Via ComputeWandb class integration

Sources: neurons/register_api.py:1646-1702 , neurons/register_api.py:1870-1872

The API implements several security measures:

  • SSL/TLS: Required certificates for HTTPS communication
  • IP Whitelisting: Optional middleware for access control (IPWhitelistMiddleware)
  • RSA Encryption: Key pair generation for secure miner communication
  • UUID Validation: Prevents unauthorized resource access

Sources: neurons/register_api.py:120-134 , neurons/register_api.py:3214-3227

Key configuration constants defined in the module:

ConstantValuePurpose
DEFAULT_API_PORT8903Default API server port
DATA_SYNC_PERIOD600Metagraph refresh interval
ALLOCATE_CHECK_PERIOD180Health check frequency
ALLOCATE_CHECK_COUNT20Max failures before deallocation
VALID_VALIDATOR_HOTKEYSArrayAuthorized validator hotkeys

Sources: neurons/register_api.py:86-116

The API runs with SSL certificates located at cert/server.key, cert/server.cer, and cert/ca.cer, and terminates if these certificates are not found.