🌐 System Overview

Three-Tier Architecture

  • Validator: Network coordination and scoring validation
  • Miner: Resource aggregation and Bittensor network interface
  • Worker: Hardware monitoring and compute task execution
┌────────────────────────┐ ┌───────────────────┐ ┌────────────────────────┐ │ Validator │ │ Miner │ │ Worker(s) │ │ (Bittensor) │ Encrypted │ (Bittensor) │ │ │ │ │ ←── Communication ─── │ │ ←── WebSocket ──→ │ • System Monitoring │ │ • Challenge Creation │ (via bittensor) │ • Worker Mgmt. │ (1 : N) │ • Challenge Execution │ │ • Score Validation │ │ • Resource Agg. │ │ • VMGW Session │ │ • Weight Calculation │ │ • Task Routing │ │ • Libvirt Mgmt. │ └────────────────────────┘ └───────────────────┘ └────────────────────────┘

📊 Scoring System

Miners earn rewards through a scoring system designed to incentivize active compute provision and network participation.

Score Components (Weighted)

  • Lease Revenue (100%): Active compute rentals generate the primary score
  • Availability Multiplier: Based on 169-hour online presence

Lease Revenue

  • Workers with active compute rentals earn lease scores
  • Idle workers score zero on this component
  • Integrated with compute marketplace APIs

Worker Management

  • Maximum 100 workers per miner
  • Final score sums all worker performance (capped at 100)

⛏️ Miner Documentation

ByteLeap Miners aggregate worker resources and serve as the interface between compute providers and the Bittensor network. This is the recommended starting point for new users.

Prerequisites

  • Python 3.8+
  • Bittensor wallet with registered hotkey

Installation

# Setup environment
git clone https://github.com/byteleapai/byteleap-Miner
python3 -m venv venv
source ./venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Configuration

Configure your miner in config/miner_config.yaml:

  • Network settings (netuid, wallet paths)
  • Worker management settings
  • WebSocket server configuration

Running the Miner

Start Miner

Aggregates workers and communicates with Bittensor:

python scripts/run_miner.py --config config/miner_config.yaml

Production Deployment

For production use, run with PM2:

pm2 start ecosystem.config.js
📝 Note: Workers should be deployed separately using the byteleap-worker repository. See the Worker Setup section below.

Technical Architecture

┌────────────────────────┐ ┌───────────────────┐ ┌────────────────────────┐ │ Validator │ │ Miner │ │ Worker(s) │ │ (Bittensor) │ Encrypted │ (Bittensor) │ │ │ │ │ ←── Communication ─── │ │ ←── WebSocket ──→ │ • System Monitoring │ │ • Challenge Creation │ (via bittensor) │ • Worker Mgmt. │ (1 : N) │ • Challenge Execution │ │ • Score Validation │ │ • Resource Agg. │ │ • VMGW Session │ │ • Weight Calculation │ │ • Task Routing │ │ • Libvirt Mgmt. │ └────────────────────────┘ └───────────────────┘ └────────────────────────┘

Core Components

Miner (neurons/miner/)

  • Worker lifecycle management via WebSocket
  • Resource aggregation and reporting
  • Bittensor network communication
  • Challenge distribution and result collection

Shared Libraries (neurons/shared/)

  • Cryptographic challenge protocols
  • Merkle tree verification system
  • Configuration management
  • Network communication utilities

💻 Worker Documentation

ByteLeap Worker is the compute resource provider component that connects to Miners via WebSocket and provides hardware resources for computational challenges and VM orchestration.

📝 Note: Workers are deployed separately from Miners. Each Worker connects to a Miner via WebSocket to provide compute resources.

Hardware Requirements

  • CPU: Physical CPU with 8+ cores
  • Memory: 32 GB RAM or higher
  • GPU: One of the following NVIDIA models:
    • GeForce RTX 3090, 4090, 5090
    • Data center GPUs: A100, H100, H200, B200
  • Storage: 500GB+ available disk space
  • System: Must be a physical machine or bare metal — deployment on Docker or virtual machines is not supported
  • OS: Ubuntu 22.04+ or compatible Linux distribution
  • Kernel: Linux kernel version >= 6.0.0

BIOS/UEFI Configuration

Before running the worker installation script, you must enable virtualization and IOMMU support in your system BIOS/UEFI settings. This is required for GPU passthrough and VM orchestration.

⚠️ Important: BIOS/UEFI settings must be configured before proceeding with installation. Changes require a system reboot to take effect.

Intel Platform BIOS/UEFI Settings

Intel platforms require the following BIOS options to be enabled:

Required BIOS Options:

  • Intel Virtualization Technology (VT-x)
    • This enables CPU virtualization support. While not IOMMU itself, most motherboards group it with IOMMU settings.
  • Intel VT-d (Virtualization Technology for Directed I/O)
    • This is the actual IOMMU / DMA Remapping support required for PCI passthrough. This must be enabled.

Typical BIOS Navigation Path:

Menu paths may vary by motherboard manufacturer, but typically follow these patterns:

  • Advanced → CPU Configuration → Intel Virtualization Technology → Enabled
  • Advanced → Chipset Configuration → VT-d → Enabled

Some motherboards may place VT-d under:

  • Advanced → North Bridge / System Agent (SA) Configuration → VT-d
💡 Tips:
  • Save BIOS settings and reboot for changes to take effect.
  • If you cannot find the VT-d option, your BIOS/motherboard may not support it, or your BIOS version may be too old.

AMD Platform BIOS/UEFI Settings

AMD platforms refer to IOMMU as AMD-Vi (also called IOMMU/AMD-IOMMU):

Required BIOS Options:

  • SVM Mode / AMD-V
    • Enables CPU virtualization extensions (default support on Ryzen/Ryzen Threadripper processors).
  • IOMMU / AMD-Vi
    • This is the I/O MMU / DMA remapping switch. Must be enabled for the kernel to properly enable IOMMU.

Typical BIOS Navigation Path:

Paths may vary slightly, but commonly follow these patterns:

  • Advanced → CPU Configuration → SVM Mode → Enabled
  • Advanced → CPU Configuration / Chipset → IOMMU / AMD-Vi → Enabled

Some BIOS versions may categorize IOMMU under:

  • Advanced → North Bridge / Miscellaneous → IOMMU → Enabled
💡 Tips:
  • Save BIOS settings and reboot for changes to take effect.
  • After enabling these options, verify IOMMU is active in the kernel by checking dmesg | grep -i iommu after boot.

Installation Methods

Method 1: Automatic Installation (Recommended)

Use the automated installation script for quick setup:

curl -sSL https://resource.byteleap.ai/install.sh | bash

This script will automatically:

  • Check system requirements
  • Install required dependencies (libvirt, QEMU, cloud-utils, etc.)
  • Upgrade kernel to HWE version if needed
  • Download and install the latest ByteLeap Worker
  • Set up systemd service
⚠️ Important Notes:
  • The script requires root privileges (will prompt for sudo)
  • If NVIDIA driver is detected, you'll need to uninstall it first and reboot
  • After installation, you need to configure the worker before starting

Method 2: Manual Installation

Step 1: Download Binary Package

# Download the latest version
wget https://resource.byteleap.ai/worker-0.0.6.zip

# Extract the package
unzip worker-0.0.6.zip
cd worker-0.0.6

Step 2: Install System Dependencies

# Update package list
sudo apt update

# Install virtualization packages
sudo apt install -y libvirt-daemon-system libvirt-clients qemu-system-x86 \
                    virtinst virt-manager virt-viewer libvirt-dev

# Install additional tools
sudo apt install -y qemu-utils cloud-utils

# Install HWE kernel (for Ubuntu 22.04)
sudo apt install -y linux-generic-hwe-22.04

# Reboot after kernel upgrade
sudo reboot

Step 3: Install Service

# Make binary executable
chmod +x byteleap-worker

# Install as systemd service
sudo ./byteleap-worker install-service

GPU Configuration

After installation, bind your NVIDIA GPUs to the VFIO driver for VM passthrough:

Bind All GPUs

sudo byteleap-worker bind

Bind Specific Number of GPUs

# Bind first 4 GPUs
sudo byteleap-worker bind 4

Verify Binding Status

After binding and rebooting, verify the configuration:

byteleap-worker verify

Expected output:

=== Summary ===
VFIO-bound NVIDIA GPUs: 8
Other NVIDIA GPUs: 0
Total NVIDIA GPUs: 8

Other GPU Commands

# List all GPUs in the system
byteleap-worker list

# Show detailed debug information
byteleap-worker debug

# Unbind GPUs (restore original drivers)
sudo byteleap-worker unbind

Configuration

Before starting the worker, edit the configuration file:

sudo nano /opt/byteleap-worker/config/worker_config.yaml

Key configuration items:

# Worker identification
worker_name: "my-worker-01"  # Set a unique name for your worker

# Miner connection
miner_url: "ws://miner.example.com:8080/ws"  # Your miner's WebSocket URL

# Task execution
max_concurrent_tasks: 4  # Maximum number of concurrent tasks

# VM Gateway (optional)
vmgw:
  enable: true  # Enable VM orchestration features

Service Management

Start the Service

sudo systemctl start byteleap-worker

Stop the Service

sudo systemctl stop byteleap-worker

Restart the Service

sudo systemctl restart byteleap-worker

Check Service Status

sudo systemctl status byteleap-worker
# or
byteleap-worker service-status

View Logs

# Follow logs in real-time
sudo journalctl -u byteleap-worker -f

# View recent logs
sudo journalctl -u byteleap-worker -n 100

Enable Auto-start on Boot

sudo systemctl enable byteleap-worker

Additional Commands

Download Base VM Image

sudo byteleap-worker download

Uninstall Service

sudo byteleap-worker uninstall-service

Troubleshooting

GPU Binding Issues

If GPU binding fails, run the debug command:

byteleap-worker debug

This will show detailed information about:

  • System configuration
  • Kernel parameters
  • VFIO modules status
  • GPU driver status
  • Configuration files

Service Won't Start

Check the service logs:

sudo journalctl -u byteleap-worker -n 50

Common issues:

  • Configuration file errors
  • Missing dependencies
  • GPU not properly bound to VFIO
  • Insufficient permissions

Connection Issues

Verify your miner URL is correct and accessible:

# Test WebSocket connection
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
     -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: test" \
     http://your-miner-url/ws

VM Gateway Integration

Workers can optionally connect to a VM gateway for virtual machine orchestration:

  • Dedicated client thread manages enrollment, certificate lifecycle, and mTLS WebSocket session
  • Enrollment tokens are fetched from validators via miner relay
  • Certificate artifacts are persisted beside the worker config file
  • Automatic certificate validation and renewal ensures continuous connectivity

Updating

The worker includes an automatic update mechanism. When a new version is available:

  1. The worker will automatically download and install the update
  2. The service will restart with the new version
  3. Check logs to verify successful update

To manually check for updates:

# Check current version
byteleap-worker --version

# Reinstall latest version
curl -sSL https://resource.byteleap.ai/install.sh | bash

🛡️ Validator Documentation

ByteLeap Validator is the network coordination node for Bittensor SN128, managing challenge validation, weight calculation, and network scoring for the distributed compute resource platform.

Validator Responsibilities

  • Challenge Validation: Two-phase verification protocol for computational integrity
  • Weight Management: Network-wide scoring and weight updates
  • Resource Tracking: PostgreSQL-based miner and worker performance monitoring
  • Secure Communication: Session-based encryption with miners

Prerequisites

  • Python 3.8+
  • PostgreSQL 12+
  • Bittensor wallet with registered hotkey
  • Sufficient TAO stake for network participation

Installation

# Setup environment

git clone https://github.com/byteleapai/byteleap-Validator
python3 -m venv venv
source ./venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Setup PostgreSQL database, skip this if you use sqlite (default config)
# (cp scripts/setup_database.sh /tmp; cd /tmp; sudo -u postgres /tmp/setup_database.sh setup)

Configuration

Configure your validator in config/validator_config.yaml:

  • Network settings (netuid, wallet paths)
  • Database connection parameters
  • Challenge verification settings
  • Weight update intervals

Running the Validator

Start Validator

python scripts/run_validator.py --config config/validator_config.yaml

Database Management

# Apply database migrations
./scripts/db_migrate.py upgrade

# Check database connection
./scripts/db_migrate.py check

Development Setup

Database Operations (PostgreSQL)

# PostgreSQL Setup (RHEL/CentOS)
yum install postgresql-server postgresql-contrib
/usr/bin/postgresql-setup --initdb
systemctl restart postgresql

# Configure access
vi /var/lib/pgsql/data/pg_hba.conf
# Add: host all all 127.0.0.1/32 md5
systemctl restart postgresql

🔌 API Reference

📝 Note: API documentation is currently in development. Check back soon for comprehensive API reference and integration guides.

The ByteLeap API will provide programmatic access to:

  • Compute marketplace integration
  • Worker status and performance metrics
  • Challenge submission and verification
  • Network scoring and weight information

📄 License

MIT License - see the LICENSE file for details.