AIEP Miner

Open-source TypeScript reference implementation of the AIEP architecture — applied to ASIC mining fleet control.

---

What is this?

AIEP Miner connects to ASIC miners over a local network, ingests telemetry, calculates profitability, makes governed control decisions, and records every input, decision, suppression, and action in an append-only evidence ledger — following the exact invariants of the AIEP kernel.

This repo exists to:

1. Prove the AIEP architecture works on real hardware.
2. Give the mining community auditable, non-opaque fleet automation.
3. Demonstrate that AI/LLM reasoning (PIEA, phase 7+) can be added above a deterministic control loop without compromising auditability.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  controller-api  (Fastify REST)        dashboard  (React+Vite)  │
└────────────┬───────────────────────────────────┬────────────────┘
             │                                   │ /api proxy
             ▼                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                         orchestrator                             │
│  poll → divergence-check → profit-engine → decide → execute     │
└────┬──────────┬──────────────────┬─────────────┬───────────────┘
     │          │                  │             │
  miner-     telemetry-       profit-       execution-
  adapter    ingestion         engine        surface
     │                                          │
  (CGMiner TCP)                           evidence-ledger
                                           (JSONL/SQLite)

Every step writes to the ledger. No action is taken without a DecisionRecord. No decision is suppressed without a NegativeProofRecord.

---

Packages

Package	Description
@aiep-miner/kernel	Re-exports @aiep/kernel primitives — GENOME_LOCKFILE-verified
@aiep-miner/schema	Canonical TypeScript types for all records
@aiep-miner/miner-adapter	CGMiner TCP adapter + stub adapter for testing
@aiep-miner/telemetry-ingestion	Polls miners, normalises telemetry, fetches BTC price
@aiep-miner/profit-engine	Revenue vs energy cost calculation
@aiep-miner/divergence-detector	Safety thresholds — temperature, comms, price staleness
@aiep-miner/evidence-ledger	Append-only JSONL ledger
@aiep-miner/execution-surface	Governed dispatch — gates MANUAL mode and HOLD decisions
@aiep-miner/orchestrator	7-step control loop using all packages above

---

Quick start

Prerequisites

• Node.js 20+
• pnpm 9+
• (Optional) An ASIC miner running CGMiner with API port 4028 open on LAN

Install and build

pnpm install
pnpm -r build

Configure

cp .env.example .env
# Edit .env — set MINER_0_IP, energy cost, etc.
# For multi-operator see OPERATOR_0_* pattern in .env.example

Run

# Start the API (port 3001)
pnpm --filter controller-api start

# Start the dashboard (port 5173)
pnpm --filter dashboard dev

Open http://localhost:5173 — click Run cycle to trigger the first control loop.

Without hardware

Leave MINER_0_IP unset — the API defaults to the stubAdapter which produces realistic randomised telemetry.

---

Operator modes

OPERATOR_MODE	Behaviour
AUTO (default)	Orchestrator takes RUN/STOP/RESTART automatically
MANUAL	All automatic actions are suppressed with NegativeProofRecord. Only explicit /miners/:id/start etc. commands are executed

---

Multi-operator deployment

A single controller process can govern multiple independent operators, each with their own miners, ledger partition, and credentials.

Config

Option A — OPERATORS_JSON (full JSON array, recommended for container environments):

OPERATORS_JSON='[{"operatorId":"op-1","label":"Operator 1","operatorMode":"AUTO","apiSecret":"secret1","miners":[...],"site":{...}}]'

Option B — indexed env vars:

OPERATOR_0_ID=operator-alpha
OPERATOR_0_LABEL=Alpha Mining Ltd
OPERATOR_0_MODE=AUTO
OPERATOR_0_SECRET=secret-for-alpha
OPERATOR_0_MINER_0_IP=192.168.1.101
OPERATOR_0_MINER_0_ID=antminer-001
# ...
OPERATOR_1_ID=operator-beta
OPERATOR_1_SECRET=secret-for-beta
OPERATOR_1_MINER_0_IP=192.168.2.101

Option C — legacy single-operator env vars (existing .env files work unchanged).

Routes

Pattern	Scope
/operators/:operatorId/miners	Multi-operator fleet
/operators/:operatorId/ledger/*	Per-operator ledger
/operators/:operatorId/loop/run-once	Per-operator cycle
/miners, /ledger/*, /loop/run-once	Single-operator convenience aliases

Auth

All routes require Authorization: Bearer <operatorId>:<hmac> where the HMAC is HMAC-SHA256(apiSecret, "<operatorId>:<METHOD>:<URL>"). Set AUTH_DISABLED=true for local dev only.

Ledger isolation

In multi-operator mode the ledger is automatically partitioned:

ledger/
  operator-alpha/decisions.jsonl
  operator-alpha/telemetry.jsonl
  operator-beta/decisions.jsonl
  ...

Dashboard

The dashboard reads the /health operator list at startup. When multiple operators are configured it shows an operator selector in the header — FleetView and LedgerView route to the selected operator automatically.

---

Evidence ledger

Every record type is written to ./ledger/<type>.jsonl. All records are content-hashed with @aiep/kernel. Telemetry records chain via priorRecordHash.

ledger/
  telemetry.jsonl
  prices.jsonl
  profits.jsonl
  decisions.jsonl
  receipts.jsonl
  negative-proofs.jsonl

Records can be inspected at any time via:

• GET /ledger/status
• GET /ledger/decisions
• GET /ledger/telemetry
• etc.

---

Licence

Apache 2.0 — see LICENSE.

Patent notice: Commercial deployment of the AIEP protocol invariants (kernel, evidence-ledger, divergence-detector, execution-surface) requires an AIEP licence from Phatfella Ltd. See NOTICE and AIEP_LICENSING.md for details.

---

Roadmap

Phase	Status
1 — Core packages + evidence ledger	✅
2 — Controller API (Fastify)	✅
3 — Dashboard (React+Vite, Cloudflare Pages)	✅
4 — Multi-operator: per-operator ledger, HMAC auth, dual routing	✅
5 — SQLite ledger backend	⏳
6 — Docker Compose + Raspberry Pi node-agent	⏳
7 — PIEA reasoning layer (analysis above the loop)	📋 planned
8 — Federation: P264/P265/P269 cross-operator evidence sharing	📋 planned