Network & Operators

darkreach uses a distributed network of operators and nodes to parallelize prime searches across many machines. Operators manage one or more compute nodes, while the coordinator distributes work and aggregates results.

Architecture

┌─────────────────────────────────────────────────┐
│              Coordinator (api.darkreach.ai)       │
│  Work generation · Block distribution · Results   │
└────────┬───────────────┬───────────────┬──────────┘
         │               │               │
    ┌────▼────┐    ┌─────▼─────┐   ┌─────▼─────┐
    │Operator │    │ Operator  │   │ Operator  │
    │  Alice  │    │   Bob     │   │  Charlie  │
    │ 4 nodes │    │  2 nodes  │   │  1 node   │
    └─────────┘    └───────────┘   └───────────┘

Terminology

Term	Description
Coordinator	Central server that generates work blocks, distributes them to nodes, and collects results
Operator	A person or organization that contributes compute resources. Has an account and manages nodes
Node	A single compute machine running the darkreach CLI in worker mode
Work block	A range of candidates assigned to a node for sieving and testing

Note: The codebase is migrating from “volunteer/worker/fleet” to “operator/node/network” terminology. Both are supported in the API.

Joining the Network

1. Register as an operator

Create an operator account via the dashboard or API:

bash

curl -X POST https://api.darkreach.ai/api/v1/operators \
  -H "Content-Type: application/json" \
  -d '{"name": "alice", "contact_email": "alice@example.com"}'

2. Configure your node

Create a configuration file at ~/.darkreach/config.toml:

toml

[node]
coordinator_url = "https://api.darkreach.ai"
operator_id = "your-operator-id"

[compute]
threads = 8          # Number of search threads (default: all cores)
memory_limit = "4G"  # Maximum memory for sieve buffers

[heartbeat]
interval = 10        # Heartbeat interval in seconds

3. Start the worker

bash

# Connect to the coordinator and start claiming work
darkreach work --coordinator https://api.darkreach.ai

# Or with a direct database connection
darkreach work --database-url postgres://...

The node will register with the coordinator, begin receiving work blocks, and report results automatically.

Work Distribution

Work claiming uses PostgreSQL row-level locking for fairness and crash safety:

sql

-- Each node claims one block at a time
SELECT * FROM work_blocks
WHERE status = 'pending'
ORDER BY priority DESC, created_at ASC
LIMIT 1
FOR UPDATE SKIP LOCKED

Fair — SKIP LOCKED prevents contention between nodes
Crash-safe — Uncompleted blocks return to the pool on transaction rollback
Priority-aware — High-priority campaigns get blocks claimed first

Heartbeat Protocol

Nodes send heartbeats every 10 seconds with progress data:

json

{
  "worker_id": "node-abc123",
  "operator_id": "op-alice",
  "status": "working",
  "current_block": {
    "job_id": 42,
    "progress": 0.67,
    "candidates_tested": 150000,
    "candidates_per_second": 12500
  },
  "system": {
    "cpu_usage": 0.95,
    "memory_mb": 3200,
    "cores": 8
  }
}

Nodes that miss heartbeats for 60 seconds are marked stale. Their in-progress work blocks are reclaimed by other nodes.

Scaling with systemd

For multi-node deployments, use systemd template units:

ini

# /etc/systemd/system/darkreach-worker@.service
[Unit]
Description=darkreach worker %i
After=network-online.target

[Service]
User=darkreach
ExecStart=/usr/local/bin/darkreach work \
  --coordinator https://api.darkreach.ai
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

bash

# Enable and start 4 worker instances
sudo systemctl enable darkreach-worker@{1..4}
sudo systemctl start darkreach-worker@{1..4}

Operator Dashboard

Operators can monitor their nodes at app.darkreach.ai/my-nodes:

Node online/offline status and uptime
Current work block assignments and progress
Compute contribution (core-hours, primes found)
Performance metrics per node

API Endpoints

Method	Path	Description
GET	`/api/v1/operators`	List operators with node counts and stats
POST	`/api/v1/operators`	Register a new operator
GET	`/api/v1/nodes`	List all nodes with status
POST	`/api/v1/nodes/register`	Register a new node under an operator
POST	`/api/v1/nodes/heartbeat`	Node heartbeat with progress
GET	`/api/fleet`	Fleet overview (all nodes + active searches)

Security

Operator registration requires approval for production deployments
Node identity is tied to operator ID — nodes cannot impersonate other operators
All results are re-verifiable via the verification pipeline
Work block results include timing and system metadata for anomaly detection