relay

BASE challenge for verifiable web scraping results.

Architecture · Threat model · Open-web policy · Ops / run

---

Overview

relay is the BASE Bittensor challenge service that scores verifiable scrape work. Validators expose work units; miners (via an enclave worker such as basecrawl) complete sealed scrapes and return cryptographically bound proofs; the service runs an L0–L5 verify pipeline and multi-factor scoring, then exports hotkey weights through get_weights.

Authenticity is a hard reward gate: L1 (multi-TEE RATS) and L2 (TLS certificate + report-data binding) must open before respectively weighted credit can enter get_weights. Completeness, geo confidence, anti-bot / integrity scores, and penalties compose secondary factors. Trust is cryptographically-anchored trust-but-audit, not trustless absolute authenticity. See docs/THREAT_MODEL.md.

relay is a Python FastAPI service (uv project) with SQLite via aiosqlite. It does not run the miner browser stack itself; it is the challenge coordination, verify, policy, and scoring plane for the network.

Architecture

flowchart LR
  M[Miners] --> W[work_units]
  W --> E[Enclave scrape]
  E --> V[L0–L5 verify]
  V --> S[Multi-factor scoring]
  S --> G[get_weights]
  Val[Validators / challenge] --> W
  Val --> G

Loading

Layer roles (product architecture names):

Layer	Responsibility
L0	Proof sanity, schema, nonce freshness
L1	Multi-TEE remote attestation (RATS), measurement allowlist
L2	TLS certificate chain + report-data binding to scrape result
L3	Geo session (landmarks, RTT triangulation, composition)
L4	Completeness, assignment binding, quorum / canary
L5	Anti-bot, integrity, attribution

Full design notes: docs/architecture.md.

How it works

1. Challenge operators run the relay API and configure CHALLENGE_* settings (including internal shared token and slug).
2. Tasks are generated and pre-screened by the open-web policy gate, then sealed for content-confidentiality.
3. Miners / coordination pull pending units from /internal/v1/work_units and assign them to enclave workers.
4. The worker fetches the target, builds a ScrapeProof, and submits results (sealed / attested) back to the bridge.
5. /internal/v1/verify runs L0 → L1 → L2 (authenticity hard gate), then L3–L5 factors as applicable.
6. Scoring composes authenticity, completeness, geo, anti-bot, and penalties; optional witness-proxy is a strictly degraded tier.
7. BASE master reads /internal/v1/get_weights for the hotkey → weight map used on-chain.

Roles

Role	Responsibility
Miner	Registers a hotkey, completes assigned scrape work through an enclave worker, earns weight only when authenticity opens and secondary factors score well
Validator / challenge	Runs relay, issues policy-screened tasks, verifies proofs, applies multi-factor scoring, serves get_weights
Enclave worker	Runs the attested scrape stack (e.g. basecrawl capability), produces measurement-bound ScrapeProofs

Documentation

Audience	Guide	Contents
Everyone	Architecture	End-to-end flow, L0–L5, geo, scoring surface
Security / honesty	Threat model	Trust model, residual risk (including TEE.fail), threat map
Operators	Open-web policy	Pre-seal screening order, deny categories, SSRF rules
Operators	Witness proxy	Optional non-TEE degraded tier vs default reject
Operators / compliance	Retention and PII	Retention posture and PII handling
Miners	Miner guide	Registration, work units, proof submission surface

Run

Requires Python >= 3.12 and uv.

cd relay
uv sync --extra dev
chmod 600 .env   # gitignored; CHALLENGE_* settings
uv run uvicorn relay.app:app --host 0.0.0.0 --port 21080

Dev ports used by this challenge stack:

Service	Port	Notes
relay	21080	Primary challenge API
canary	21090	Optional canary fixtures (SSRF-allowlisted)
mock-master	21110	Optional local master stand-in

Key routes

Public (no internal bearer): /health, /version, /registry, /leaderboard, /status, POST /miners/register.

Internal under /internal/v1 (bearer + challenge slug): get_weights, work_units, verify, scoring/*, geo/*, plus task and policy helpers. Auth headers:

Authorization: Bearer <CHALLENGE_SHARED_TOKEN>
X-Base-Challenge-Slug: relay

Miner-signed requests use X-Hotkey, X-Signature, X-Nonce, and X-Timestamp.

Validation

Manufacturer checks only (local or CI):

uv run ruff check .
uv run ruff format --check .
uv run pytest --cov=relay --cov-report=term-missing --cov-fail-under=80

CI workflow: BaseIntelligence/relay CI.

Repository layout

src/relay/
  app.py           # ASGI entry (uvicorn: relay.app:app)
  bridge/          # work_units intake, fold, attribution
  verify/          # L0–L5 pipeline
  geo/             # L3 landmarks, triangulation, composition
  scoring/         # multi-factor scorer, get_weights, audits
  seal/            # task / result encryption
  policy/          # open-web, robots, PII, retention
  confidentiality/ # tiers and assignment boundary
  keyrelease/      # measurement-gated key release
  tasks/           # generator, canary fixtures
  miners/          # miner registration
  public/          # leaderboard, status
  db/              # SQLAlchemy / aiosqlite models
docs/              # architecture, threat model, policy, miner guide
tests/             # pytest suite

License

Apache License 2.0. See LICENSE.