Skip to content

README.md

Latest commit

 

History

History
238 lines (187 loc) · 12.3 KB

README.md

File metadata and controls

238 lines (187 loc) · 12.3 KB
Raw

BASE

Multi-challenge Bittensor subnet platform with master/validator orchestration.

Miners · Validators · Master · Architecture · Challenges · Security · Website

CI License Bittensor SDK

BASE Banner

Overview

BASE is a multi-challenge Bittensor subnet platform: independent challenge subnets run under one validator network. BASE routes miner traffic to the right challenge, collects each challenge's raw weights, normalizes emissions, maps hotkeys to Bittensor UIDs, and publishes the final vector for validators to submit on-chain. Each challenge lives in its own repository and owns its submissions, scoring, state, and public miner experience; BASE is the orchestration layer that runs them as one subnet.

It runs as a single-host Docker Compose topology (Compose is the only supported operator path). A master application hosts the public proxy, validator coordination plane, aggregation, and digest-aware challenge watcher, with PostgreSQL as the durable control plane and one long-lived combined service per active challenge. The master coordinates and aggregates but never submits on-chain weights and never launches evaluator containers. Online validators use independent Compose projects, register with the master, pull assignments, report results, and submit the master's final vector with their own wallets.

Public SDK release

Immutable Base Python package pin for consumers (including Prism):

Field Value
Version v3.1.2
Wheel https://github.com/BaseIntelligence/base/releases/download/v3.1.2/base-3.1.2-py3-none-any.whl
SHA-256 3a61c2d3a343ed6de55e80215486e3de0c9639276443d08f2ed316bc807f2ff0

There is no LLM gateway in this release. Challenge admission and scoring are owned by each challenge service (Prism is deterministic). Agent-challenge remains diagnostic/incompatible relative to the Compose target path.

Architecture

flowchart LR
    U[Miners] --> P[Public proxy]
    P --> CH[Challenge APIs]
    CH --> AG[Weight aggregator]

    subgraph MASTER [Master - Compose project]
        P
        CP[Coordination plane]
        AG
        WTC[Digest-aware watcher]
        PG[(Control-plane Postgres)]
    end

    CH -- raw-weight push --> AG
    V[Validators - independent Compose] -- register / pull / result --> CP
    V --> VB[Own broker + eval / verify]
    AG --> W[GET /v1/weights/latest]
    V -- fetch weights --> W
    V -- set_weights own hotkey --> BT[Bittensor]
Loading

How It Works

  1. The master tracks active challenges and their emission shares, and auto-deploys their long-lived Compose services from the registry (a newly-registered ACTIVE challenge propagates with no manual step).
  2. Challenge services run isolated from the control plane and each other, each on its own /data volume.
  3. Miners reach a challenge through BASE's public proxy.
  4. Validators register, pull assignments from the coordination plane, execute or verify evaluation on their own side, and post results.
  5. Each challenge computes raw hotkey weights and pushes them to the master for aggregation.
  6. BASE normalizes challenge outputs, applies emission shares, and maps hotkeys to UIDs.
  7. Each validator fetches the final vector from the weights API and calls set_weights on-chain under its own hotkey (tests may use a fake chain). The master aggregates but never submits on-chain.

If a challenge fails, BASE isolates that challenge's contribution without taking down the subnet.

Roles

Role Responsibility
Master Coordinates + aggregates; runs the proxy, coordination plane, broker, digest-aware watcher, and challenge services. Never executes evals or submits on-chain.
Validators Decentralized executors: register + heartbeat, pull assignments, run/verify on their own side, and submit on-chain weights under their own hotkey.
Challenge owners Own an independent repo, image, scoring logic, and state; push raw weights; expose the standard internal weight contract.
Workers Optional miner-funded GPU executors for Prism (Lium/Targon or local), carrying an ExecutionProof.

Miner-Funded GPU Worker Plane

Optional, gated behind compute.worker_plane_enabled (env BASE_COMPUTE__WORKER_PLANE_ENABLED, default off ⇒ byte-for-byte legacy behavior). It moves Prism heavy GPU evaluation onto worker agents in GPU instances the miners fund (rented on Lium or Targon, or local), deployed with the base worker CLI. Validators keep only light plausibility checks, probabilistic replay audits, and weight submission.

  • Signed enrollment — the miner signs a hotkey↔worker binding; provider keys (LIUM_API_KEY / TARGON_API_KEY) stay in the miner's environment and never reach the master.
  • Anti-collusion — a worker never evaluates its owner's submission; each unit replicates across R=2 distinct-owner workers and is reconciled by ExecutionProof.manifest_sha256.
  • Proof tiers — tier 0 (manifest hash + sr25519 signature), tier 1 (pinned image digest), tier 2 (in-guest attestation, gated off on Targon). Audit sampling is tier-modulated.
  • Agent Challenge Phala Intel TDX path (separate from the PRISM worker plane): BASE carries the Phala-tier ExecutionProof / EvalExecutionProof schema (including vm_config ≤ 256 KiB), quote verification helpers, R=1 assignment for attested units, and public-proxy deny rules so agent-challenge capability, internal, and direct result-ingestion routes stay challenge-direct (default off). Flag-off: legacy byte-identical signed submission/env/launch proxy path and R=1 own_runner behavior. Full attested mode uses one miner-funded external eval (R=1) with zero BASE validator re-exec multi-replica assignment; score acceptance remains challenge- owned. Details: Architecture.
  • Admission rule — when enforced, a miner needs ≥1 active bound worker to submit to Prism, else 403 NO_ACTIVE_WORKER.

See the miner worker deployment guide.

Documentation

Audience Guide Contents
Miners Miner guide Choose a challenge, submit through the proxy, track leaderboards
Miners Worker deployment Deploy a miner-funded GPU worker on Lium/Targon
Validators Validator guide Run an independent validator and submit on-chain weights
Operators Compose deployment Supported single-host master and validator install
Operators Deploy from scratch Operator navigation for Compose-only bring-up
Operators Foundation master guide Master reference notes
Developers Architecture Control-plane vs challenge vs validator topology
Developers Challenges The challenge model
Developers Challenge integration The API contract a challenge must expose
Developers Security model Trust boundaries and secret handling
Developers Versioning SemVer, Git tag, and GHCR tag policy
Developers Reward semantics Terminal-Bench scorer reward mapping

Deploy

Docker Compose is the only supported shipping operator path. Scripts live under deploy/compose/ (install-master.sh, install-validator.sh, docker-compose.yml, docker-compose.validator.yml).

Install the master control plane (PostgreSQL + master application + one long-lived container per active challenge) with:

./deploy/compose/install-master.sh --project-name base-mission-master --port 3180

Install each agent-only independent validator with an explicit Base master URL (validators never run master, PostgreSQL, or challenge control-plane services; shipping Compose mounts host docker.sock for later challenges-on-validator prep):

# Public network Base master API (authoritative shipping example)
./deploy/compose/install-validator.sh \
  --project-name base-validator-live \
  --master-url https://chain.joinbase.ai

# Local disposable master (secondary; smoke/dev only)
./deploy/compose/install-validator.sh \
  --project-name base-mission-validator-a \
  --master-url http://127.0.0.1:3180

The public Base master / coordination / weights API for this network is https://chain.joinbase.ai (verify GET /health → role=master). Local disposable masters remain valid for smoke only via an explicit loopback --master-url. Any other historical public hostname is non-authoritative only (may return 502); do not document it as the shipping master URL.

Production topology

Piece Live production
Master runtime Compose project base-master-prod on 86.38.238.235 (Swarm inactive after cutover)
Public master API https://chain.joinbase.ai only (role=master). Other historical hostnames are non-authoritative secondary.
Example validator validator-5gzi: agent-only Compose at 31.22.104.239, master_url=https://chain.joinbase.ai
Challenges Prism healthy/active. agent-challenge registry-active; gateway-free image digests may start after allowlist pin (no LLM gateway on Compose).
REAL-PROVIDER TEE (Lium/Targon) BLOCKED
On-chain weights Validators call set_weights with their own wallets. Master and ops track do not.
Public website https://joinbase.ai (Vercel project platform, repo echobt/frontend-platform-figma) → API https://chain.joinbase.ai

Typical master services: base-master-validator, master-postgres, and one challenge-<slug> per active challenge (for example challenge-prism). Validators are separate Compose projects with their own identity and wallet. The digest-aware watcher keeps challenge containers aligned with pinned image digests.

curl -fsS http://127.0.0.1:3180/health
curl -fsS http://127.0.0.1:3180/version
curl -fsS http://127.0.0.1:3180/v1/registry

Full walkthrough: Compose deployment and Deploy from scratch.

Historical deploy/swarm/ material is unsupported for new installs and is retained only as frozen reference. LLM gateway services, tokens, and provider clients are removed from the target path. Base and Prism never launch evaluator containers from this Compose project.

Validation Quick Reference

Run from the repository root with Docker Compose available.

uv sync --extra dev --extra master
uv run ruff check .
uv run ruff format --check .
uv run mypy src tests
uv run pytest -m "not postgres" --cov=base --cov-report=term-missing --cov-fail-under=80

Evidence for local validation should live in a local, gitignored directory and must never contain tokens, credentialed database URLs, registry credentials, or private keys.

Repository Layout

platform/
  src/base/         # CLI, APIs, orchestration, Bittensor wrappers
  alembic/          # PostgreSQL migrations
  config/           # YAML example configs
  docker/           # Dockerfiles and OCI image assets
  deploy/compose/   # Supported Compose installers and manifests
  deploy/swarm/     # Historical Swarm installers (unsupported)
  docs/             # Project, miner, validator, and challenge docs
  tests/            # Unit / runtime validation tests

License

Apache-2.0