Add a page which proves the best share PoW

api/internal/state/aggregator.go

@@ -25,6 +25,15 @@ type HashratePoint struct {
 	V float64 `json:"v"` // H/s
 }
 
+// BestSharePow wraps the PoW reproduction record ckpool logs for a new
+// best share (patch 0008) with the time we ingested it. Persisted as
+// JSON in the kv store so the header of the best share survives
+// restarts.
+type BestSharePow struct {
+	logmon.PowData
+	SeenAt time.Time `json:"seen_at"`
+}
+
 // StratumServer describes one entry in ckpool's serverurl[] array. ckpool
 // tags every client with the index of the bind it arrived on, but the index
 // alone doesn't say what that bind *is* — that depends on how the deployment
@@ -64,6 +73,12 @@ type Snapshot struct {
 	BestShareHash string `json:"best_share_hash,omitempty"`
 	// Network difficulty at the time the best share was found.
 	BestShareNetDiff float64 `json:"best_share_net_diff,omitempty"`
+	// Full PoW reproduction data (raw block header, coinbase, merkle
+	// branches) for the best share seen since ckpool patch 0008 was
+	// deployed. May describe a lower-diff share than BestDiff when the
+	// all-time best predates the patch — the UI compares hashes and
+	// shows a disclaimer in that case.
+	BestSharePow *BestSharePow `json:"best_share_pow,omitempty"`
 	// Last best-diff value acknowledged by the user via the UI.
 	// The frontend shows a "new best" glow when best_diff > this.
 	AckedBestDiff float64 `json:"acked_best_diff"`
@@ -177,6 +192,7 @@ const (
 	kvBestDiff         = "best_diff"
 	kvBestShareHash    = "best_share_hash"
 	kvBestShareNetDiff = "best_share_net_diff"
+	kvBestSharePow     = "best_share_pow"
 
 	kvAllTimeAccepted = "alltime_accepted"
 	kvAllTimeRejected = "alltime_rejected"
@@ -329,6 +345,19 @@ type Aggregator struct {
 	bestShareHash    string
 	bestShareNetDiff float64 // network difficulty when best share was found
 
+	// PoW reproduction data for the best share seen since ckpool patch
+	// 0008 went live. Tracked as its own high-water mark (by SDiff)
+	// because the all-time best share may predate the patch and have no
+	// reconstructible header. Never mutated after assignment, so the
+	// pointer is safe to hand out in snapshots.
+	bestPow *BestSharePow
+	// PoW data lines arrive on the share channel just before their
+	// matching "Accepted client" line. Park them here keyed by header
+	// hash until the accepted event confirms the share, so data from a
+	// share that ends up rejected (e.g. below the client's vardiff
+	// right after a ckpool restart) is never persisted.
+	pendingPow map[string]*logmon.PowData
+
 	// Last best-diff value acknowledged by the user in the UI.
 	ackedBestDiff float64
 
@@ -352,6 +381,7 @@ func New(ck *ckpool.Client, rpc *bitcoind.RPC, interval time.Duration, log *slog
 		Log:                  log,
 		sessionRejectReasons: make(map[string]int64),
 		alltimeRejectReasons: make(map[string]int64),
+		pendingPow:           make(map[string]*logmon.PowData),
 		ready:                make(chan struct{}),
 		notifierDone:         make(chan struct{}, 1),
 	}
@@ -572,6 +602,7 @@ func (a *Aggregator) refresh(ctx context.Context) {
 	next.BestDiff = a.bestDiff
 	next.BestShareHash = a.bestShareHash
 	next.BestShareNetDiff = a.bestShareNetDiff
+	next.BestSharePow = a.bestPow
 	next.AckedBestDiff = a.ackedBestDiff
 	now := time.Now()
 
@@ -821,6 +852,17 @@ func (a *Aggregator) IngestShareEvents(ctx context.Context, events <-chan logmon
 				return
 			}
 			a.mu.Lock()
+			if ev.Pow != nil {
+				// PoW reproduction line (patch 0008). Park it until the
+				// matching "Accepted client" event arrives; a bounded
+				// reset guards against unmatched entries piling up.
+				if len(a.pendingPow) >= 16 {
+					a.pendingPow = make(map[string]*logmon.PowData)
+				}
+				a.pendingPow[ev.Pow.Hash] = ev.Pow
+				a.mu.Unlock()
+				continue
+			}
 			if ev.Rejected {
 				reason := ev.Reason
 				if reason == "" {
@@ -836,6 +878,25 @@ func (a *Aggregator) IngestShareEvents(ctx context.Context, events <-chan logmon
 				a.alltimeDiffCount++
 				a.sessionDiffSum += ev.Diff
 				a.alltimeDiffSum += ev.Diff
+				// Promote parked PoW data once its share is confirmed
+				// accepted and beats the best PoW record we hold. This
+				// high-water mark is separate from bestDiff: the
+				// all-time best share may predate ckpool patch 0008,
+				// in which case this tracks the best share since the
+				// patch went live and the UI discloses the difference.
+				if pow, ok := a.pendingPow[ev.Hash]; ok {
+					delete(a.pendingPow, ev.Hash)
+					if a.bestPow == nil || pow.SDiff > a.bestPow.SDiff {
+						a.bestPow = &BestSharePow{PowData: *pow, SeenAt: time.Now()}
+						if a.Store != nil {
+							if data, err := json.Marshal(a.bestPow); err == nil {
+								_ = a.Store.SetKV(kvBestSharePow, string(data))
+							}
+						}
+						a.Log.Info("best share PoW data captured",
+							"sdiff", pow.SDiff, "height", pow.Height, "hash", pow.Hash)
+					}
+				}
 				// Track hash of the best share from log parsing.
 				if ev.Hash != "" && ev.Diff > a.bestDiff {
 					a.bestDiff = ev.Diff
@@ -971,6 +1032,16 @@ func (a *Aggregator) loadPersistedState() {
 			a.mu.Unlock()
 		}
 	}
+	if v, err := a.Store.GetKV(kvBestSharePow); err == nil && v != "" {
+		var pow BestSharePow
+		if uerr := json.Unmarshal([]byte(v), &pow); uerr == nil && pow.Header != "" {
+			a.mu.Lock()
+			a.bestPow = &pow
+			a.mu.Unlock()
+		} else if uerr != nil {
+			a.Log.Warn("best_share_pow load failed", "err", uerr)
+		}
+	}
 
 	// One-time backfill: if we have no hash (pre-upgrade), scan the
 	// ckpool log for the highest-difficulty accepted share and use its hash.
@@ -998,6 +1069,41 @@ func (a *Aggregator) loadPersistedState() {
 		}
 	}
 
+	// One-time backfill: if we hold no PoW record but the log already
+	// contains confirmed "Best share PoW data" lines (fresh database, or
+	// events dropped under load), adopt the best of them. Without this
+	// the PoW inspector would wait for a share beating ckpool's
+	// in-process best, which after a long ckpool uptime can take
+	// arbitrarily long.
+	a.mu.RLock()
+	needsPowBackfill := a.bestPow == nil && a.LogFilePath != ""
+	a.mu.RUnlock()
+	if needsPowBackfill {
+		pow, at, seen, unparseable, err := logmon.FindBestPowData(a.LogFilePath)
+		switch {
+		case err != nil:
+			a.Log.Warn("best share PoW backfill: log scan failed", "err", err)
+		case pow == nil:
+			// Deliberately loud: "no record" is indistinguishable from a
+			// broken pipeline without the counts.
+			a.Log.Info("best share PoW backfill: no confirmed record adopted",
+				"pow_lines_seen", seen, "unparseable", unparseable)
+		default:
+			if at.IsZero() {
+				at = time.Now()
+			}
+			best := &BestSharePow{PowData: *pow, SeenAt: at}
+			a.mu.Lock()
+			a.bestPow = best
+			a.mu.Unlock()
+			if data, jerr := json.Marshal(best); jerr == nil {
+				_ = a.Store.SetKV(kvBestSharePow, string(data))
+			}
+			a.Log.Info("backfilled best share PoW data from log",
+				"sdiff", pow.SDiff, "hash", pow.Hash, "pow_lines_seen", seen)
+		}
+	}
+
 	// Restore acknowledged best diff.
 	if v, err := a.Store.GetKV(kvAckedBestDiff); err == nil && v != "" {
 		if f, perr := strconv.ParseFloat(v, 64); perr == nil {

api/internal/state/pow_e2e_test.go

@@ -0,0 +1,121 @@
+package state
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/kamadopool/kamado-api/internal/logmon"
+)
+
+// The two lines below are the verbatim output of ckpool patch 0008's
+// jansson code (replicated against ckpool's in-tree jansson 2.14 with
+// identical calls and JSON_COMPACT), using Bitcoin block 125552's real
+// header and hash. If ckpool's encoding and this pipeline ever drift,
+// this test is the tripwire.
+const (
+	ckpoolPowLine = `[2026-08-31 18:00:01.123] Best share PoW data {"sdiff":62953.415063916997,"netdiff":136597951737045.02,"height":911234,"hash":"00000000000000001e8d6829a8a21adc5d38d0a473b144b6765798e61f98bd1d","header":"0100000081cd02ab7e569e8bcd9317e2fe99f2de44d49ab2b8851ba4a308000000000000e320b6c2fffc8d750423db8b1eb942ae710e951ed797f7affc8892b0f1fc122bc7f5d74df2b9441a42a14695","coinbase":"01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff2703e2e60d04858ee468086b616d61646f2f04a1b2c3d40011223344556677ffffffff0100f2052a010000001600140123456789abcdef0123456789abcdef0123456700000000","cb1len":41,"merklebranches":["fff2525b8931402dd09222c50775608f75787bd2b87e56995a7bdd30f79702c4","6359f0868171b1d194cbee1af2f16ea598ae8fad666d9b012c8ed2b79a236ec4"],"enonce1":"a1b2c3d4","nonce2":"0011223344556677","workername":"bc1qexample.axe1"}` + "\n"
+	ckpoolAcceptLine = `[2026-08-31 18:00:01.124] Accepted client 271 share diff 62953.4/512/1.02K: 00000000000000001e8d6829a8a21adc5d38d0a473b144b6765798e61f98bd1d` + "\n"
+)
+
+// End to end: real ckpool log bytes -> real Tailer.Run -> aggregator
+// ingest -> snapshot JSON. Exercises the exact production path.
+func TestPowEndToEnd_LogToSnapshot(t *testing.T) {
+	f, err := os.CreateTemp("", "ckpool_e2e*.log")
+	if err != nil {
+		t.Fatal(err)
+	}
+	f.Close()
+	t.Cleanup(func() { _ = os.Remove(f.Name()) })
+
+	tl := logmon.New(f.Name(), discardLog())
+	tl.PollWait = 10 * time.Millisecond
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	go tl.Run(ctx)
+
+	a := New(nil, nil, time.Minute, discardLog())
+	go a.IngestShareEvents(ctx, tl.Shares)
+
+	// Give the tailer a moment to open the (empty) file and seek to the
+	// end, then append what ckpool would write.
+	time.Sleep(50 * time.Millisecond)
+	lf, err := os.OpenFile(f.Name(), os.O_APPEND|os.O_WRONLY, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := lf.WriteString(ckpoolPowLine + ckpoolAcceptLine); err != nil {
+		t.Fatal(err)
+	}
+	lf.Close()
+
+	deadline := time.Now().Add(5 * time.Second)
+	for {
+		a.mu.RLock()
+		pow := a.bestPow
+		a.mu.RUnlock()
+		if pow != nil {
+			if pow.Hash != "00000000000000001e8d6829a8a21adc5d38d0a473b144b6765798e61f98bd1d" {
+				t.Fatalf("hash = %s", pow.Hash)
+			}
+			if pow.SDiff != 62953.415063916997 || pow.NetDiff != 136597951737045.02 {
+				t.Fatalf("sdiff/netdiff = %v/%v", pow.SDiff, pow.NetDiff)
+			}
+			if len(pow.Header) != 160 || len(pow.MerkleBranches) != 2 {
+				t.Fatalf("header len %d, branches %d", len(pow.Header), len(pow.MerkleBranches))
+			}
+			break
+		}
+		if time.Now().After(deadline) {
+			t.Fatal("bestPow never populated from the tailed log")
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+
+	// The snapshot must expose it under best_share_pow with the flattened
+	// PowData fields — this is the contract the UI reads.
+	snap := Snapshot{BestSharePow: func() *BestSharePow {
+		a.mu.RLock()
+		defer a.mu.RUnlock()
+		return a.bestPow
+	}()}
+	data, err := json.Marshal(snap)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out map[string]any
+	if err := json.Unmarshal(data, &out); err != nil {
+		t.Fatal(err)
+	}
+	powJSON, ok := out["best_share_pow"].(map[string]any)
+	if !ok {
+		t.Fatalf("snapshot JSON missing best_share_pow: %s", data)
+	}
+	for _, key := range []string{"sdiff", "netdiff", "height", "hash", "header", "coinbase", "cb1len", "merklebranches", "enonce1", "nonce2", "workername", "seen_at"} {
+		if _, ok := powJSON[key]; !ok {
+			t.Errorf("best_share_pow JSON missing %q", key)
+		}
+	}
+}
+
+// The startup backfill must recover the same record from an existing
+// log file (the path taken when live events were missed).
+func TestPowEndToEnd_Backfill(t *testing.T) {
+	path := tempLogFile(t, ckpoolPowLine, ckpoolAcceptLine)
+	pow, at, _, _, err := logmon.FindBestPowData(path)
+	if err != nil {
+		t.Fatalf("scan error: %v", err)
+	}
+	if pow == nil {
+		t.Fatal("FindBestPowData found nothing in verbatim ckpool output")
+	}
+	if pow.SDiff != 62953.415063916997 || len(pow.MerkleBranches) != 2 {
+		t.Fatalf("got %+v", pow)
+	}
+	want := time.Date(2026, 8, 31, 18, 0, 1, 0, time.Local)
+	if !at.Equal(want) {
+		t.Errorf("timestamp = %v, want %v", at, want)
+	}
+}

api/internal/state/pow_test.go

@@ -0,0 +1,207 @@
+package state
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/kamadopool/kamado-api/internal/logmon"
+)
+
+// ingest runs IngestShareEvents over the given events and waits for the
+// goroutine to drain them.
+func ingest(t *testing.T, a *Aggregator, events ...logmon.ShareEvent) {
+	t.Helper()
+	ch := make(chan logmon.ShareEvent, len(events))
+	for _, ev := range events {
+		ch <- ev
+	}
+	close(ch)
+	done := make(chan struct{})
+	go func() {
+		a.IngestShareEvents(context.Background(), ch)
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("IngestShareEvents did not drain")
+	}
+}
+
+func powFixture(hash string, sdiff float64) *logmon.PowData {
+	return &logmon.PowData{
+		SDiff:          sdiff,
+		NetDiff:        1.36e14,
+		Height:         911111,
+		Hash:           hash,
+		Header:         "00000020" + "aa" + "bb", // content is opaque to the aggregator
+		Coinbase:       "0100",
+		CB1Len:         41,
+		MerkleBranches: []string{"cd"},
+		Enonce1:        "a1b2c3d4",
+		Nonce2:         "0011223344556677",
+		Workername:     "bc1qexample.axe",
+	}
+}
+
+// A PoW data line followed by its matching accepted share must promote
+// the parked record to bestPow and persist it.
+func TestPowPairing_AcceptedPromotes(t *testing.T) {
+	s := openTempStore(t)
+	a := New(nil, nil, time.Minute, discardLog())
+	a.Store = s
+
+	const hash = "0000000000abcdef0000000000000000000000000000000000000000deadbeef"
+	ingest(t, a,
+		logmon.ShareEvent{SeenAt: time.Now(), Pow: powFixture(hash, 5000)},
+		logmon.ShareEvent{SeenAt: time.Now(), Diff: 5000, Hash: hash},
+	)
+
+	a.mu.RLock()
+	pow := a.bestPow
+	a.mu.RUnlock()
+	if pow == nil {
+		t.Fatal("bestPow not set after accepted share matched PoW data")
+	}
+	if pow.Hash != hash || pow.SDiff != 5000 {
+		t.Errorf("bestPow = %+v, want hash %s sdiff 5000", pow.PowData, hash)
+	}
+
+	// Reload from the store to verify persistence round-trips.
+	b := New(nil, nil, time.Minute, discardLog())
+	b.Store = s
+	b.loadPersistedState()
+	b.mu.RLock()
+	reloaded := b.bestPow
+	b.mu.RUnlock()
+	if reloaded == nil || reloaded.Hash != hash || reloaded.CB1Len != 41 {
+		t.Fatalf("persisted bestPow did not reload, got %+v", reloaded)
+	}
+}
+
+// PoW data for a share that is never confirmed accepted (e.g. rejected
+// below vardiff right after a ckpool restart) must not become bestPow.
+func TestPowPairing_UnmatchedIsNotPromoted(t *testing.T) {
+	a := New(nil, nil, time.Minute, discardLog())
+
+	ingest(t, a,
+		logmon.ShareEvent{SeenAt: time.Now(), Pow: powFixture("aa11", 9000)},
+		logmon.ShareEvent{SeenAt: time.Now(), Rejected: true, Reason: "Above target"},
+	)
+
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	if a.bestPow != nil {
+		t.Errorf("bestPow = %+v, want nil for unconfirmed PoW data", a.bestPow)
+	}
+	if _, ok := a.pendingPow["aa11"]; !ok {
+		t.Error("pending PoW entry missing; expected it parked until matched or evicted")
+	}
+}
+
+// The all-time best share may hugely outrank anything recent (found
+// before header capture existed). The PoW record must still populate
+// from the first confirmed share — it tracks "best since the feature
+// went live", never waiting for the all-time best to be beaten — while
+// leaving the all-time bestDiff/bestShareHash untouched.
+func TestPowPairing_BelowAllTimeBestStillPopulates(t *testing.T) {
+	a := New(nil, nil, time.Minute, discardLog())
+	a.mu.Lock()
+	a.bestDiff = 4.2e11 // legacy all-time best, no PoW data recorded for it
+	a.bestShareHash = "legacyhash"
+	a.mu.Unlock()
+
+	ingest(t, a,
+		logmon.ShareEvent{SeenAt: time.Now(), Pow: powFixture("smallhash", 1234)},
+		logmon.ShareEvent{SeenAt: time.Now(), Diff: 1234, Hash: "smallhash"},
+	)
+
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	if a.bestPow == nil || a.bestPow.Hash != "smallhash" {
+		t.Fatalf("bestPow = %+v, want the 1234-diff record despite the 4.2e11 all-time best", a.bestPow)
+	}
+	if a.bestDiff != 4.2e11 || a.bestShareHash != "legacyhash" {
+		t.Errorf("all-time best mutated: diff %v hash %q", a.bestDiff, a.bestShareHash)
+	}
+}
+
+// With no persisted PoW record, loadPersistedState must adopt the best
+// confirmed record already present in the ckpool log, so the inspector
+// never waits for ckpool's long-lived in-process best to be beaten.
+func TestPowBackfill_FromLog(t *testing.T) {
+	logPath := tempLogFile(t,
+		`[2026-08-30 09:15:42.123] Best share PoW data {"sdiff":777,"netdiff":1.3e14,"height":911111,"hash":"eeee","header":"00000020aabb","coinbase":"0100","cb1len":41,"merklebranches":[],"enonce1":"a1","nonce2":"b2","workername":"w"}`+"\n",
+		`[2026-08-30 09:15:42.124] Accepted client 7 share diff 777/42/1.0K: eeee`+"\n",
+	)
+	s := openTempStore(t)
+	a := New(nil, nil, time.Minute, discardLog())
+	a.Store = s
+	a.LogFilePath = logPath
+	a.loadPersistedState()
+
+	a.mu.RLock()
+	pow := a.bestPow
+	a.mu.RUnlock()
+	if pow == nil || pow.Hash != "eeee" || pow.SDiff != 777 {
+		t.Fatalf("bestPow = %+v, want backfilled eeee/777", pow)
+	}
+	if pow.SeenAt.IsZero() {
+		t.Error("SeenAt is zero, want the log line timestamp")
+	}
+
+	// A persisted record must suppress the backfill on the next load,
+	// even when the log holds a lower-diff record.
+	b := New(nil, nil, time.Minute, discardLog())
+	b.Store = s
+	b.LogFilePath = tempLogFile(t,
+		`[2026-08-31 10:00:00.000] Best share PoW data {"sdiff":5,"netdiff":1.3e14,"height":911112,"hash":"ffff","header":"00000020ccdd","coinbase":"0100","cb1len":41,"merklebranches":[],"enonce1":"a1","nonce2":"b2","workername":"w"}`+"\n",
+		`[2026-08-31 10:00:00.001] Accepted client 7 share diff 5/42/1.0K: ffff`+"\n",
+	)
+	b.loadPersistedState()
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	if b.bestPow == nil || b.bestPow.Hash != "eeee" {
+		t.Fatalf("bestPow = %+v, want the persisted eeee record kept", b.bestPow)
+	}
+}
+
+func tempLogFile(t *testing.T, lines ...string) string {
+	t.Helper()
+	f, err := os.CreateTemp("", "ckpool_pow*.log")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, l := range lines {
+		if _, werr := f.WriteString(l); werr != nil {
+			t.Fatal(werr)
+		}
+	}
+	f.Close()
+	t.Cleanup(func() { _ = os.Remove(f.Name()) })
+	return f.Name()
+}
+
+// A lower-diff PoW record (ckpool restarts reset its in-process best,
+// so it re-logs on the first share of each run) must not replace a
+// higher one already held.
+func TestPowPairing_LowerDiffDoesNotReplace(t *testing.T) {
+	a := New(nil, nil, time.Minute, discardLog())
+
+	ingest(t, a,
+		logmon.ShareEvent{SeenAt: time.Now(), Pow: powFixture("high", 9000)},
+		logmon.ShareEvent{SeenAt: time.Now(), Diff: 9000, Hash: "high"},
+		// ckpool restarted: first share of the new process is its
+		// in-process best and gets logged again at a lower diff.
+		logmon.ShareEvent{SeenAt: time.Now(), Pow: powFixture("low", 42)},
+		logmon.ShareEvent{SeenAt: time.Now(), Diff: 42, Hash: "low"},
+	)
+
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	if a.bestPow == nil || a.bestPow.Hash != "high" {
+		t.Fatalf("bestPow = %+v, want the 9000-diff record kept", a.bestPow)
+	}
+}