Per-worker audit view on the admin dashboard

New /admin/worker/:id page that answers 'why is my accrued balance
what it is?' end-to-end:

  - Header: worker name, Thunder payout address, first/last seen
  - Ledger card: owed, accrued (stored), paid, last updated
  - Cross-check card:
      accepted shares, blocks found
      Σ difficulty
      rate (= POOL_PPS_SATS_PER_DIFF env)
      Σ FLOOR(difficulty × rate) — the authoritative sum
      pps_credits.accrued (stored) with ✓ or ⚠ match indicator
      + note on per-share vs sum-then-truncate drift
  - Daily breakdown table (last 30 days with activity):
      day, shares, Σ diff, sats credited, blocks
  - Recent shares table (last 100, newest first):
      id, when, difficulty, credit_sats, is_block, running_accrued

Runing_accrued is computed client-side by walking oldest-first over
the recent slice, so miners can see their balance grow one share at
a time.

lib/admin.js exposes workerAudit(handle, workerId, { rate, ... }) —
does the SQL for the cross-check (per-share truncation matches what
the C proxy does), the daily rollup, and the recent-shares slice in
three prepared statements against the read-only handle.

server.js: adds /admin/worker/:id (HTML) and /api/admin/worker/:id
(JSON) behind the same basic auth. New POOL_PPS_SATS_PER_DIFF env
var defaults to 1000 and MUST equal proxy.conf's pps_sats_per_diff
or the cross-check flips to ⚠.

admin.ejs: adds an 'audit →' link on each worker row of the summary
page so operators drill down with one click.

deploy/systemd/simplepool-dashboard.service: documents the new env
var alongside the existing admin config.

Author: rsantacroce

dashboard/lib/admin.js

@@ -77,6 +77,103 @@ export function inFlight(handle) {
     }));
 }
 
+/* Per-worker audit — "why is my accrued balance N sats?" answered with
+ * the formula, a cross-check, per-day rollup, and the last N shares.
+ *
+ * The C proxy credits each accepted share `FLOOR(difficulty * rate)`
+ * sats where `rate` is proxy.conf's pps_sats_per_diff. Truncation is
+ * per-share, not once at the end, so `Σ FLOOR(diff × rate)` is the
+ * authoritative cross-check — NOT `FLOOR(Σ diff × rate)`. Both are
+ * shown so operators can spot a config drift immediately. */
+export function workerAudit(handle, workerId, { rate, recentLimit = 100, dayLimit = 30 } = {}) {
+    const db = unwrap(handle);
+    if (!db) return null;
+    const worker = db.prepare(`
+        SELECT w.id, w.name, w.payout_address, w.first_seen, w.last_seen,
+               c.accrued_sats, c.paid_sats, c.last_updated
+        FROM   workers w
+        LEFT JOIN pps_credits c ON c.worker_id = w.id
+        WHERE  w.id = ?
+    `).get(workerId);
+    if (!worker) return null;
+
+    const totals = db.prepare(`
+        SELECT COUNT(*)                                       AS share_count,
+               COALESCE(SUM(difficulty), 0)                   AS sum_difficulty,
+               COALESCE(SUM(CAST(difficulty * ? AS INTEGER)), 0) AS accrued_computed,
+               MIN(ts)                                        AS first_ts,
+               MAX(ts)                                        AS last_ts,
+               COUNT(*) FILTER (WHERE is_block = 1)           AS blocks_found
+        FROM   shares
+        WHERE  worker_id = ? AND is_block IS NOT NULL
+    `).get(rate, workerId);
+
+    /* Day-level rollup: (day, shares, sum_diff, sats_credited). Only
+     * days with activity, most-recent first. */
+    const days = db.prepare(`
+        SELECT DATE(ts, 'unixepoch') AS day,
+               COUNT(*)              AS shares,
+               SUM(difficulty)       AS sum_diff,
+               SUM(CAST(difficulty * ? AS INTEGER)) AS accrued_delta,
+               COUNT(*) FILTER (WHERE is_block = 1) AS blocks
+        FROM   shares
+        WHERE  worker_id = ?
+        GROUP  BY day
+        ORDER  BY day DESC
+        LIMIT  ?
+    `).all(rate, workerId, dayLimit);
+
+    /* Most-recent shares, cheapest to derive running_accrued client-side. */
+    const recent = db.prepare(`
+        SELECT id, ts, difficulty, is_block, block_hash,
+               CAST(difficulty * ? AS INTEGER) AS credit_sats
+        FROM   shares
+        WHERE  worker_id = ?
+        ORDER  BY ts DESC
+        LIMIT  ?
+    `).all(rate, workerId, recentLimit);
+
+    return {
+        worker: {
+            id: Number(worker.id),
+            name: worker.name,
+            thunder_address: worker.payout_address,
+            first_seen: Number(worker.first_seen),
+            last_seen:  Number(worker.last_seen),
+        },
+        rate,
+        ledger: {
+            accrued: Number(worker.accrued_sats || 0),
+            paid:    Number(worker.paid_sats    || 0),
+            owed:    Number(worker.accrued_sats || 0) - Number(worker.paid_sats || 0),
+            last_updated: Number(worker.last_updated || 0),
+        },
+        totals: {
+            share_count:     Number(totals.share_count),
+            sum_difficulty:  Number(totals.sum_difficulty),
+            accrued_computed: Number(totals.accrued_computed),
+            first_ts:        Number(totals.first_ts || 0),
+            last_ts:         Number(totals.last_ts  || 0),
+            blocks_found:    Number(totals.blocks_found),
+        },
+        days: days.map(d => ({
+            day:           d.day,
+            shares:        Number(d.shares),
+            sum_diff:      Number(d.sum_diff),
+            accrued_delta: Number(d.accrued_delta),
+            blocks:        Number(d.blocks),
+        })),
+        recent: recent.map(r => ({
+            id:          Number(r.id),
+            ts:          Number(r.ts),
+            difficulty:  Number(r.difficulty),
+            is_block:    Number(r.is_block),
+            block_hash:  r.block_hash,
+            credit_sats: Number(r.credit_sats),
+        })),
+    };
+}
+
 /* Minimal Thunder JSON-RPC client — we only need `balance()`. Short
  * timeout so the admin page renders promptly even when Thunder is
  * unreachable. */

dashboard/server.js

@@ -76,6 +76,10 @@ 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';
+/* The rate the C proxy uses to convert difficulty → sats. Must match
+ * proxy.conf's pps_sats_per_diff or the worker-audit cross-check goes
+ * red. Passed via the same env-driven config path as the admin creds. */
+const PPS_SATS_PER_DIFF = parseFloat(process.env.POOL_PPS_SATS_PER_DIFF || '1000');
 
 function requireAdminAuth(req, res, next) {
     if (!ADMIN_USER || !ADMIN_PASS) {
@@ -116,6 +120,33 @@ app.get('/api/admin/summary', requireAdminAuth, async (req, res) => {
         res.status(500).json({ error: e.message });
     }
 });
+
+/* Per-worker audit: "why is my balance N sats?" answered end-to-end. */
+function workerAuditFor(workerId) {
+    const audit = admin.workerAudit(db, workerId, { rate: PPS_SATS_PER_DIFF });
+    if (!audit) return null;
+    return audit;
+}
+
+app.get('/admin/worker/:id', requireAdminAuth, (req, res) => {
+    try {
+        const audit = workerAuditFor(parseInt(req.params.id, 10));
+        if (!audit) return res.status(404).render('404', { what: 'worker' });
+        res.render('admin-worker', { audit });
+    } catch (e) {
+        res.status(500).send('admin: ' + e.message);
+    }
+});
+
+app.get('/api/admin/worker/:id', requireAdminAuth, (req, res) => {
+    try {
+        const audit = workerAuditFor(parseInt(req.params.id, 10));
+        if (!audit) return res.status(404).json({ error: 'unknown worker id' });
+        res.json(audit);
+    } catch (e) {
+        res.status(500).json({ error: e.message });
+    }
+});
 /* END PPS ADMIN PATCH */
 
 app.use((req, res) => res.status(404).render('404', { what: 'page' }));

dashboard/views/admin-worker.ejs

@@ -0,0 +1,187 @@
+<%
+const fmtN   = (n) => new Intl.NumberFormat('en-US').format(n || 0);
+const fmtF   = (n, d = 4) => (typeof n === 'number' ? n.toFixed(d) : '—');
+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';
+};
+/* Precompute a running_accrued column for the recent-shares table.
+ * The rows come newest-first, so we walk in reverse to accumulate. */
+const recentAsc = [...audit.recent].reverse();
+let running = 0;
+const withRunning = recentAsc.map(r => {
+    running += r.credit_sats;
+    return { ...r, running_accrued: running };
+}).reverse();
+const naiveAccrued = Math.floor(audit.totals.sum_difficulty * audit.rate);
+const drift = audit.totals.accrued_computed - naiveAccrued;
+%>
+<!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="30">
+    <title>audit · <%= audit.worker.name %> · simplepool</title>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <header class="top">
+        <a href="/" class="brand">simplepool</a>
+        <span class="tag">worker audit</span>
+        <span style="margin-left:1em"><a href="/admin">← back to admin</a></span>
+    </header>
+    <main class="wrap">
+        <section class="card info">
+            <h2>Why is this balance what it is?</h2>
+            <p class="muted small">
+                Answers a miner's "where does <em>my</em> number come from"
+                question at the byte level. Every accepted share credits
+                <code>FLOOR(difficulty × rate)</code> sats, where <em>rate</em>
+                comes from <code>proxy.conf</code>'s
+                <code>pps_sats_per_diff</code>. Truncation is per-share; that's
+                the authoritative sum shown below.
+            </p>
+        </section>
+
+        <section class="card">
+            <h2><%= audit.worker.name %></h2>
+            <div class="grid">
+                <div><label>Thunder address</label><span class="mono small"><%= audit.worker.thunder_address || '—' %></span></div>
+                <div><label>First seen</label><span title="<%= fmtTs(audit.worker.first_seen) %>"><%= ago(audit.worker.first_seen) %></span></div>
+                <div><label>Last seen</label><span title="<%= fmtTs(audit.worker.last_seen) %>"><%= ago(audit.worker.last_seen) %></span></div>
+            </div>
+        </section>
+
+        <section class="card">
+            <h2>Ledger</h2>
+            <div class="grid">
+                <div><label>Owed (needs payout)</label><strong><%= fmtSats(audit.ledger.owed) %></strong></div>
+                <div><label>Accrued (all-time, from pps_credits)</label><strong><%= fmtSats(audit.ledger.accrued) %></strong></div>
+                <div><label>Paid (all-time)</label><strong><%= fmtSats(audit.ledger.paid) %></strong></div>
+                <div><label>Last updated</label><span title="<%= fmtTs(audit.ledger.last_updated) %>"><%= ago(audit.ledger.last_updated) %></span></div>
+            </div>
+        </section>
+
+        <section class="card">
+            <h2>Cross-check</h2>
+            <p class="muted small" style="margin-top:0">
+                The pool credits <code>FLOOR(difficulty × <%= fmtN(audit.rate) %>)</code>
+                sats per accepted share. If the numbers below don't match, the
+                DB has drifted from the C proxy's log — worth investigating.
+            </p>
+            <div class="grid">
+                <div><label>Accepted shares</label><strong><%= fmtN(audit.totals.share_count) %></strong></div>
+                <div><label>Blocks found</label><strong><%= fmtN(audit.totals.blocks_found) %></strong></div>
+                <div><label>Σ difficulty</label><strong><%= fmtF(audit.totals.sum_difficulty, 6) %></strong></div>
+                <div><label>Rate (sats × diff)</label><strong><%= fmtN(audit.rate) %></strong></div>
+                <div><label>Σ FLOOR(diff × rate) — authoritative</label><strong><%= fmtSats(audit.totals.accrued_computed) %></strong></div>
+                <div><label>pps_credits.accrued (stored)</label><strong><%= fmtSats(audit.ledger.accrued) %></strong></div>
+            </div>
+            <% if (audit.ledger.accrued === audit.totals.accrued_computed) { %>
+                <p class="muted small" style="margin-top:0.75em;color:#5b8">
+                    ✓ Stored accrued matches the per-share truncated sum.
+                </p>
+            <% } else { %>
+                <p class="muted small" style="margin-top:0.75em;color:#c66">
+                    ⚠ Stored accrued differs by
+                    <%= fmtSats(audit.ledger.accrued - audit.totals.accrued_computed) %>.
+                    This usually means the DB was populated across a rate change,
+                    OR someone edited pps_credits by hand. Look at the C
+                    proxy log for the WARN line at the last mode/rate change.
+                </p>
+            <% } %>
+            <p class="muted small" style="margin-top:0.5em">
+                (Naive sum FLOOR(Σ diff × rate) would be <%= fmtSats(naiveAccrued) %>;
+                per-share truncation costs
+                <%= drift === 0 ? '0 sats' : Math.abs(drift) + ' sats' %>
+                over the window — the difference is the number of shares whose
+                fractional-sat contribution was rounded down.)
+            </p>
+        </section>
+
+        <section class="card">
+            <h2>Daily breakdown</h2>
+            <% if (audit.days.length === 0) { %>
+                <p class="muted">No activity yet.</p>
+            <% } else { %>
+            <table>
+                <thead>
+                    <tr>
+                        <th>Day (UTC)</th>
+                        <th>Shares</th>
+                        <th>Σ difficulty</th>
+                        <th>Accrued this day</th>
+                        <th>Blocks</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <% audit.days.forEach(d => { %>
+                    <tr>
+                        <td class="mono small"><%= d.day %></td>
+                        <td><%= fmtN(d.shares) %></td>
+                        <td><%= fmtF(d.sum_diff, 6) %></td>
+                        <td><strong><%= fmtSats(d.accrued_delta) %></strong></td>
+                        <td><%= d.blocks > 0 ? d.blocks : '' %></td>
+                    </tr>
+                    <% }) %>
+                </tbody>
+            </table>
+            <% } %>
+        </section>
+
+        <section class="card">
+            <h2>Recent shares (last <%= withRunning.length %>, newest first)</h2>
+            <% if (withRunning.length === 0) { %>
+                <p class="muted">No shares recorded.</p>
+            <% } else { %>
+            <p class="muted small" style="margin-top:0">
+                The <em>credit</em> column is what this share added to your
+                balance. <em>Running accrued</em> is the sum from the oldest
+                visible share up to and including this one.
+            </p>
+            <table>
+                <thead>
+                    <tr>
+                        <th>#</th>
+                        <th>When</th>
+                        <th>Difficulty</th>
+                        <th>Credit</th>
+                        <th>Block?</th>
+                        <th>Running accrued</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <% withRunning.forEach(r => { %>
+                    <tr<%= r.is_block ? ' style="font-weight:600"' : '' %>>
+                        <td class="mono small"><%= r.id %></td>
+                        <td class="mono small" title="<%= fmtTs(r.ts) %>"><%= ago(r.ts) %></td>
+                        <td><%= fmtF(r.difficulty, 6) %></td>
+                        <td><%= fmtSats(r.credit_sats) %></td>
+                        <td><%= r.is_block ? '✓ ' + (r.block_hash ? r.block_hash.slice(0, 10) + '…' : '') : '' %></td>
+                        <td><%= fmtSats(r.running_accrued) %></td>
+                    </tr>
+                    <% }) %>
+                </tbody>
+            </table>
+            <% } %>
+        </section>
+    </main>
+    <footer class="foot">
+        <span>read-only · auto-refresh 30s</span>
+        <span class="sep">·</span>
+        <span>worker audit</span>
+    </footer>
+</body>
+</html>

dashboard/views/admin.ejs

@@ -87,6 +87,7 @@ const fmtSats = (sats) => {
                         <th>Accrued</th>
                         <th>Paid</th>
                         <th>Updated</th>
+                        <th></th>
                     </tr>
                 </thead>
                 <tbody>
@@ -98,6 +99,7 @@ const fmtSats = (sats) => {
                         <td><%= fmtSats(w.accrued) %></td>
                         <td><%= fmtSats(w.paid) %></td>
                         <td class="muted small" title="<%= fmtTs(w.last_updated) %>"><%= ago(w.last_updated) %></td>
+                        <td><a href="/admin/worker/<%= w.worker_id %>" class="small">audit →</a></td>
                     </tr>
                     <% }) %>
                 </tbody>

deploy/systemd/simplepool-dashboard.service

@@ -19,6 +19,9 @@ 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`>
+# Must equal proxy.conf's pps_sats_per_diff — used by the per-worker
+# audit view to cross-check the C proxy's accrual math.
+Environment=POOL_PPS_SATS_PER_DIFF=1000
 ExecStart=/usr/bin/node @ROOT@/dashboard/server.js
 Restart=on-failure
 RestartSec=3