Back to Components

# Pool Hub

Miner registry with scoring engine, Redis/PostgreSQL backing, and comprehensive metrics. Live matching API deployed.

● Live

## Overview

The AITBC Pool Hub serves as the central coordination service for miners, providing efficient job matching, reputation scoring, and performance tracking.

### Key Features

- Miner registry with comprehensive metadata
- Dynamic scoring engine based on performance
- Redis for fast caching and PostgreSQL for persistence
- Real-time job matching API
- Comprehensive metrics and monitoring
- Load balancing and failover support

## Architecture

The Pool Hub is designed for high availability and performance:

#### Data Layer

Redis for hot data, PostgreSQL for historical records

#### Scoring Engine

Dynamic scoring based on success rate, latency, and availability

#### Matching API

RESTful API for real-time job-to-miner matching

#### Monitoring

Prometheus metrics and Grafana dashboards

## API Reference

### Miner Registration

    # Register miner
    POST /api/v1/miners/register
    {
      "address": "0x...",
      "endpoint": "http://miner.example.com:8080",
      "capabilities": {
        "models": ["llama3.2", "mistral"],
        "gpu_memory": 16384,
        "max_concurrent_jobs": 4
      },
      "stake": 10000
    }

### Job Matching

    # Find suitable miners
    POST /api/v1/match
    {
      "job_type": "inference",
      "model": "llama3.2",
      "requirements": {
        "min_gpu_memory": 8192,
        "max_latency": 5000
      }
    }

    # Response
    {
      "miners": [
        {
          "address": "0x...",
          "endpoint": "http://miner1.example.com",
          "score": 0.95,
          "estimated_time": 2000
        }
      ]
    }

### Miner Status

    # Update miner status
    POST /api/v1/miners/{address}/status
    {
      "available": true,
      "current_load": 2,
      "gpu_utilization": 0.75,
      "temperature": 65
    }

## Scoring System

The scoring engine evaluates miners based on multiple factors:

### Scoring Factors

- Success Rate (40%): Job completion success percentage
- Latency (25%): Average response time
- Availability (20%): Uptime percentage
- Reputation (15%): Historical performance and stake amount

### Score Calculation

    score = (success_rate * 0.4) +
            (latency_score * 0.25) +
            (availability * 0.2) +
            (reputation_score * 0.15)

## Configuration

### Environment Variables

    # Database
    REDIS_URL=redis://localhost:6379
    DATABASE_URL=postgresql://user:pass@localhost/poolhub

    # API
    API_HOST=0.0.0.0
    API_PORT=8000

    # Scoring
    SCORE_UPDATE_INTERVAL=60
    MAX_MINER_SCORE=1.0
    MIN_SUCCESS_RATE=0.8

    # Monitoring
    METRICS_PORT=9090
    LOG_LEVEL=info

### Scoring Configuration

    # config/scoring.toml
    [scoring]
    update_interval = 60  # seconds
    decay_factor = 0.95   # daily decay

    [weights]
    success_rate = 0.4
    latency = 0.25
    availability = 0.2
    reputation = 0.15

    [thresholds]
    min_success_rate = 0.8
    max_latency = 5000
    min_availability = 0.95

## Deployment

### Docker Compose

    version: '3.8'
    services:
      pool-hub:
        image: aitbc/pool-hub:latest
        ports:
          - "8000:8000"
          - "9090:9090"
        environment:
          - REDIS_URL=redis://redis:6379
          - DATABASE_URL=postgresql://postgres:pass@db:5432/poolhub
        depends_on:
          - redis
          - db

      redis:
        image: redis:7-alpine
        volumes:
          - redis_data:/data

      db:
        image: postgres:15
        environment:
          - POSTGRES_DB=poolhub
          - POSTGRES_USER=postgres
          - POSTGRES_PASSWORD=pass
        volumes:
          - db_data:/var/lib/postgresql/data

## Monitoring

### Key Metrics

- `poolhub_miners_total` - Total registered miners
- `poolhub_jobs_matched_total` - Total jobs matched
- `poolhub_match_duration` - Match operation duration
- `poolhub_miner_score` - Individual miner scores
- `poolhub_api_requests_total` - API request count

### Health Checks

    # Health endpoint
    GET /health

    # Detailed status
    GET /api/v1/status

    # Metrics endpoint
    GET /metrics