Add pool operator admin dashboard + payout worker systemd unit

Dashboard: new /admin (HTML) + /api/admin/summary (JSON) routes on
the existing simplepool-dashboard app. Basic auth gated on
ADMIN_USER + ADMIN_PASSWORD env vars — both required or the routes
return 503 (fail-closed if someone forgets to set them). Both routes
render:

- Thunder reserve balance (live JSON-RPC probe to
  THUNDER_RPC_URL/balance, 1.5s timeout so the page doesn't hang if
  Thunder is down)
- PPS ledger totals (accrued / paid / owed / workers with a balance)
- Per-worker balances table (name, thunder address, owed, accrued,
  paid, updated) — sorted by owed desc
- In-flight payouts table (empty when clean; non-empty rows need
  operator reconciliation per payout/README.md)

Warning banner fires when totals.owed > reserve.available_sats —
that's the "reserve short, payout worker skipping ticks" state.

dashboard/lib/admin.js: read-only SQL against the same shares.db the
public dashboard reads, plus a minimal Thunder JSON-RPC client for
balance(). Same handle pattern as stats.js.

deploy/systemd/simplepool-payout.service: template unit for the
Node payout worker. Follows the same @user@/@root@ substitution
convention as the existing units in deploy/systemd/. Runs as a
long-lived service; skips ticks gracefully when the Thunder reserve
is short (the current forknet state).

deploy/systemd/simplepool-dashboard.service: extended with the new
env vars (THUNDER_RPC_URL default, plus commented POOL_THUNDER_
RESERVE_ADDRESS / ADMIN_USER / ADMIN_PASSWORD placeholders) so
operators know what to fill in.

Verified live on forknet server. Behind basic auth at
http://45.33.100.24:8081/admin — currently showing:
  reserve.available_sats = 0     (no BTC has crossed to Thunder)
  totals.owed             = 127k  (PPS accruals for the one ASIC)
  workers[0]              = 3Z6z1hPySN…  <— miner's Thunder address
  inFlight                = []
  "⚠ Reserve is short" banner shown

Author: rsantacroce

dashboard/lib/admin.js

@@ -0,0 +1,103 @@
+// PPS pool operator queries + Thunder reserve balance probe.
+//
+// All read-only against the same shares.db handle the public dashboard
+// uses. Thunder is queried over its JSON-RPC HTTP endpoint (default
+// http://127.0.0.1:6009) with a short timeout — we never block a
+// request on a slow / down Thunder node.
+
+function unwrap(handle) {
+    if (typeof handle?.get === 'function') return handle.get();
+    return handle;
+}
+
+/* Pool-wide totals across pps_credits. `owed` is the outstanding sat
+ * balance the payout worker is responsible for draining. */
+export function poolTotals(handle) {
+    const db = unwrap(handle);
+    if (!db) return { accrued: 0, paid: 0, owed: 0, workers: 0 };
+    const r = db.prepare(`
+        SELECT COALESCE(SUM(accrued_sats), 0) AS accrued,
+               COALESCE(SUM(paid_sats),    0) AS paid,
+               COUNT(*)                       AS workers
+        FROM   pps_credits
+    `).get();
+    return {
+        accrued: Number(r.accrued),
+        paid:    Number(r.paid),
+        owed:    Number(r.accrued) - Number(r.paid),
+        workers: Number(r.workers),
+    };
+}
+
+/* Per-worker balances, sorted by outstanding first. `thunder_address`
+ * is what the payout worker will target. */
+export function perWorkerBalances(handle) {
+    const db = unwrap(handle);
+    if (!db) return [];
+    return db.prepare(`
+        SELECT  w.id                          AS worker_id,
+                w.name                        AS worker_name,
+                w.payout_address              AS thunder_address,
+                c.accrued_sats                AS accrued,
+                c.paid_sats                   AS paid,
+                (c.accrued_sats - c.paid_sats) AS owed,
+                c.last_updated                AS last_updated
+        FROM    pps_credits c
+        JOIN    workers     w ON w.id = c.worker_id
+        ORDER BY owed DESC
+    `).all().map(r => ({
+        ...r,
+        accrued:      Number(r.accrued),
+        paid:         Number(r.paid),
+        owed:         Number(r.owed),
+        last_updated: Number(r.last_updated),
+    }));
+}
+
+/* Current in-flight payouts. A row with an empty txid means the
+ * broadcast may or may not have gone out (worker crashed between
+ * INSERT and RPC); a row with a txid means the broadcast succeeded
+ * but the finalize transaction crashed. Either state requires
+ * operator attention — see payout/README.md for the reconciliation
+ * runbook. */
+export function inFlight(handle) {
+    const db = unwrap(handle);
+    if (!db) return [];
+    return db.prepare(`
+        SELECT  p.id, p.worker_id, w.name AS worker_name,
+                w.payout_address AS thunder_address,
+                p.sats, p.txid, p.started_at
+        FROM    payouts_in_flight p
+        JOIN    workers           w ON w.id = p.worker_id
+        ORDER BY p.started_at ASC
+    `).all().map(r => ({
+        ...r,
+        sats: Number(r.sats),
+        started_at: Number(r.started_at),
+    }));
+}
+
+/* Minimal Thunder JSON-RPC client — we only need `balance()`. Short
+ * timeout so the admin page renders promptly even when Thunder is
+ * unreachable. */
+export async function thunderBalance(rpcUrl, timeoutMs = 1500) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(rpcUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'balance', params: [] }),
+            signal: ctrl.signal,
+        });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const body = await res.json();
+        if (body.error) throw new Error(`${body.error.code} ${body.error.message}`);
+        return { ok: true, available_sats: Number(body.result?.available_sats ?? 0),
+                 total_sats: Number(body.result?.total_sats ?? 0) };
+    } catch (e) {
+        return { ok: false, error: e.message, available_sats: 0, total_sats: 0 };
+    } finally {
+        clearTimeout(t);
+    }
+}

dashboard/server.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { renderFile } from 'ejs';
 import { openDb } from './lib/db.js';
 import * as stats from './lib/stats.js';
+import * as admin from './lib/admin.js';        /* PPS ADMIN PATCH */
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PORT = parseInt(process.env.PORT || '8081', 10);
@@ -67,6 +68,56 @@ app.get('/api/blocks', (req, res) => {
 });
 app.get('/healthz', (req, res) => res.json({ ok: true, db_ready: db.ready() }));
 
+
+/* PPS ADMIN PATCH — pool operator view. Basic auth via ADMIN_USER /
+ * ADMIN_PASSWORD env vars; both required or the routes 503 (so we
+ * fail closed if someone forgets to set them). */
+const ADMIN_USER = process.env.ADMIN_USER || '';
+const ADMIN_PASS = process.env.ADMIN_PASSWORD || '';
+const RESERVE_ADDRESS = process.env.POOL_THUNDER_RESERVE_ADDRESS || '(unset)';
+const THUNDER_RPC_URL = process.env.THUNDER_RPC_URL || 'http://127.0.0.1:6009';
+
+function requireAdminAuth(req, res, next) {
+    if (!ADMIN_USER || !ADMIN_PASS) {
+        return res.status(503).send('admin disabled — set ADMIN_USER + ADMIN_PASSWORD');
+    }
+    const h = req.headers.authorization || '';
+    if (h.startsWith('Basic ')) {
+        const [u, p] = Buffer.from(h.slice(6), 'base64').toString('utf8').split(':');
+        if (u === ADMIN_USER && p === ADMIN_PASS) return next();
+    }
+    res.setHeader('WWW-Authenticate', 'Basic realm="simplepool admin"');
+    return res.status(401).send('unauthorised');
+}
+
+async function adminSummary() {
+    const [reserve, totals, workers, inFlight] = await Promise.all([
+        admin.thunderBalance(THUNDER_RPC_URL),
+        Promise.resolve(admin.poolTotals(db)),
+        Promise.resolve(admin.perWorkerBalances(db)),
+        Promise.resolve(admin.inFlight(db)),
+    ]);
+    return { reserve, reserveAddress: RESERVE_ADDRESS, totals, workers, inFlight };
+}
+
+app.get('/admin', requireAdminAuth, async (req, res) => {
+    try {
+        const data = await adminSummary();
+        res.render('admin', data);
+    } catch (e) {
+        res.status(500).send('admin: ' + e.message);
+    }
+});
+
+app.get('/api/admin/summary', requireAdminAuth, async (req, res) => {
+    try {
+        res.json(await adminSummary());
+    } catch (e) {
+        res.status(500).json({ error: e.message });
+    }
+});
+/* END PPS ADMIN PATCH */
+
 app.use((req, res) => res.status(404).render('404', { what: 'page' }));
 
 app.listen(PORT, () => {

dashboard/views/admin.ejs

@@ -0,0 +1,152 @@
+<%
+const fmtN   = (n) => new Intl.NumberFormat('en-US').format(n || 0);
+const fmtTs  = (t) => t ? new Date(t * 1000).toISOString().replace('T', ' ').slice(0, 19) + 'Z' : '—';
+const ago = (t) => {
+    if (!t) return '—';
+    const s = Math.max(0, Math.floor(Date.now() / 1000) - t);
+    if (s < 60) return s + 's ago';
+    if (s < 3600) return Math.floor(s / 60) + 'm ago';
+    if (s < 86400) return Math.floor(s / 3600) + 'h ago';
+    return Math.floor(s / 86400) + 'd ago';
+};
+const fmtSats = (sats) => {
+    if (!sats) return '0 sats';
+    const btc = sats / 1e8;
+    if (btc >= 0.01) return fmtN(sats) + ' sats (' + btc.toFixed(8) + ' BTC)';
+    return fmtN(sats) + ' sats';
+};
+%>
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta http-equiv="refresh" content="15">
+    <title>admin · simplepool</title>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <header class="top">
+        <a href="/" class="brand">simplepool</a>
+        <span class="tag">pool operator</span>
+    </header>
+    <main class="wrap">
+        <section class="card info">
+            <h2>Pool operator view</h2>
+            <p class="muted small">
+                Read-only. Reserve balance is a live probe of Thunder's
+                JSON-RPC; everything else is the same SQLite the pool
+                writes. Reconciliation is manual — see
+                <code>payout/README.md</code> for the runbook.
+            </p>
+        </section>
+
+        <section class="card">
+            <h2>Thunder reserve</h2>
+            <% if (reserve.ok) { %>
+                <div class="grid">
+                    <div><label>Available</label><strong><%= fmtSats(reserve.available_sats) %></strong></div>
+                    <div><label>Total</label><strong><%= fmtSats(reserve.total_sats) %></strong></div>
+                </div>
+                <p class="mono small muted" style="margin-top:0.5em;word-break:break-all"><%= reserveAddress %></p>
+            <% } else { %>
+                <p class="muted">Thunder RPC unreachable: <em><%= reserve.error %></em></p>
+                <p class="mono small muted" style="margin-top:0.5em;word-break:break-all"><%= reserveAddress %></p>
+            <% } %>
+        </section>
+
+        <section class="card">
+            <h2>PPS ledger totals</h2>
+            <div class="grid">
+                <div><label>Owed (needs payout)</label><strong><%= fmtSats(totals.owed) %></strong></div>
+                <div><label>Accrued (all time)</label><strong><%= fmtSats(totals.accrued) %></strong></div>
+                <div><label>Paid (all time)</label><strong><%= fmtSats(totals.paid) %></strong></div>
+                <div><label>Workers with a balance</label><strong><%= fmtN(totals.workers) %></strong></div>
+            </div>
+            <% if (reserve.ok && totals.owed > reserve.available_sats) { %>
+                <p class="muted small" style="margin-top:0.75em;color:#c66">
+                    ⚠ Reserve is short by
+                    <%= fmtSats(totals.owed - reserve.available_sats) %>.
+                    The payout worker will keep skipping ticks until this is closed
+                    (deposit BTC into the reserve via the two-step deposit service).
+                </p>
+            <% } %>
+        </section>
+
+        <section class="card">
+            <h2>Per-worker balances</h2>
+            <% if (workers.length === 0) { %>
+                <p class="muted">No workers have a PPS balance yet.</p>
+            <% } else { %>
+            <table>
+                <thead>
+                    <tr>
+                        <th>Worker</th>
+                        <th>Thunder address</th>
+                        <th>Owed</th>
+                        <th>Accrued</th>
+                        <th>Paid</th>
+                        <th>Updated</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <% workers.forEach(w => { %>
+                    <tr>
+                        <td class="mono small"><%= w.worker_name %></td>
+                        <td class="mono small"><%= w.thunder_address %></td>
+                        <td><strong><%= fmtSats(w.owed) %></strong></td>
+                        <td><%= fmtSats(w.accrued) %></td>
+                        <td><%= fmtSats(w.paid) %></td>
+                        <td class="muted small" title="<%= fmtTs(w.last_updated) %>"><%= ago(w.last_updated) %></td>
+                    </tr>
+                    <% }) %>
+                </tbody>
+            </table>
+            <% } %>
+        </section>
+
+        <section class="card">
+            <h2>In-flight payouts</h2>
+            <% if (inFlight.length === 0) { %>
+                <p class="muted">Nothing in flight — clean.</p>
+            <% } else { %>
+            <p class="muted small">
+                Rows here need operator attention. Empty <em>txid</em>
+                means the Thunder broadcast may not have gone out; a
+                set <em>txid</em> means the broadcast succeeded but the
+                DB finalize crashed. Never auto-resolved.
+            </p>
+            <table>
+                <thead>
+                    <tr>
+                        <th>#</th>
+                        <th>Worker</th>
+                        <th>Amount</th>
+                        <th>Age</th>
+                        <th>txid</th>
+                        <th>State</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <% inFlight.forEach(r => { %>
+                    <tr>
+                        <td><%= r.id %></td>
+                        <td class="mono small"><%= r.worker_name %></td>
+                        <td><%= fmtSats(r.sats) %></td>
+                        <td class="muted small" title="<%= fmtTs(r.started_at) %>"><%= ago(r.started_at) %></td>
+                        <td class="mono small"><%= r.txid || '—' %></td>
+                        <td><%= r.txid ? 'broadcast, finalize pending' : 'unbroadcast' %></td>
+                    </tr>
+                    <% }) %>
+                </tbody>
+            </table>
+            <% } %>
+        </section>
+    </main>
+    <footer class="foot">
+        <span>read-only · auto-refresh 15s</span>
+        <span class="sep">·</span>
+        <span>pool operator view</span>
+    </footer>
+</body>
+</html>

deploy/systemd/simplepool-dashboard.service

@@ -11,6 +11,14 @@ Group=@USER@
 WorkingDirectory=@ROOT@/dashboard
 Environment=PORT=8081
 Environment=PROXY_DB_PATH=@ROOT@/data/shares.db
+# --- PPS admin panel — /admin route ---
+# When ADMIN_USER + ADMIN_PASSWORD are both set, /admin serves the pool
+# operator view (reserve balance, ledger totals, per-worker owed,
+# in-flight payouts). Without both, /admin returns 503 (fail-closed).
+Environment=THUNDER_RPC_URL=http://127.0.0.1:6009
+# Environment=POOL_THUNDER_RESERVE_ADDRESS=<paste from proxy.conf>
+# Environment=ADMIN_USER=admin
+# Environment=ADMIN_PASSWORD=<generate with `openssl rand -base64 21`>
 ExecStart=/usr/bin/node @ROOT@/dashboard/server.js
 Restart=on-failure
 RestartSec=3

deploy/systemd/simplepool-payout.service

@@ -0,0 +1,34 @@
+[Unit]
+Description=simplepool Thunder payout worker
+Documentation=https://github.com/rsantacroce/simplepool
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=@USER@
+Group=@USER@
+WorkingDirectory=@ROOT@/payout
+# All required env vars must be set here — the worker exits if any is
+# missing. THUNDER_FROM_ADDRESS must equal pool_thunder_reserve_address
+# in proxy.conf so payouts drain from the same Thunder wallet the
+# coinbase is depositing into.
+Environment=PAYOUT_DB_PATH=@ROOT@/data/shares.db
+Environment=THUNDER_RPC_URL=http://127.0.0.1:6009
+# Environment=THUNDER_FROM_ADDRESS=<paste from proxy.conf>
+Environment=PAYOUT_MIN_SATS=10000
+Environment=PAYOUT_INTERVAL_MS=30000
+ExecStart=/usr/bin/node @ROOT@/payout/index.js
+Restart=on-failure
+RestartSec=5
+StandardOutput=journal
+StandardError=journal
+
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=full
+ProtectHome=read-only
+ReadWritePaths=@ROOT@/data
+
+[Install]
+WantedBy=multi-user.target