From fc69410792edfd76abec46b64218a4657d9e2f0a Mon Sep 17 00:00:00 2001 From: satoshi Date: Tue, 1 Sep 2026 23:23:51 +0300 Subject: [PATCH] Add a page which proves the best share PoW --- .gitignore | 2 + README.md | 4 +- api/internal/logmon/tailer.go | 179 +- api/internal/logmon/tailer_test.go | 154 ++ api/internal/state/aggregator.go | 106 + api/internal/state/pow_e2e_test.go | 121 ++ api/internal/state/pow_test.go | 207 ++ .../0008-log-best-share-pow-data.patch | 90 + ui/src/App.svelte | 7 + ui/src/lib/BestSharePage.svelte | 36 +- ui/src/lib/SharePowPage.svelte | 1779 +++++++++++++++++ ui/src/stores/selection.svelte.ts | 8 + ui/src/types.ts | 25 + 13 files changed, 2708 insertions(+), 10 deletions(-) create mode 100644 api/internal/state/pow_e2e_test.go create mode 100644 api/internal/state/pow_test.go create mode 100644 ckpool/patches/0008-log-best-share-pow-data.patch create mode 100644 ui/src/lib/SharePowPage.svelte diff --git a/.gitignore b/.gitignore index 3644275..7c4eb04 100644 --- a/.gitignore +++ b/.gitignore @@ -43,3 +43,5 @@ logs/ # Environment .env .env.local +giteaNew +giteaNew.pub diff --git a/README.md b/README.md index 9162cd7..d8f19e9 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ CKPool is a high-performance stratum server, but it has no web interface and lim ### Patches Applied to CKPool -Seven patches are applied to upstream commit `cfb0f83` (which itself includes the workbase_id fix, extended ESP32/NerdMiner timeouts, configurable `dropidle`, and vardiff improvements): +Eight patches are applied to upstream commit `cfb0f83` (which itself includes the workbase_id fix, extended ESP32/NerdMiner timeouts, configurable `dropidle`, and vardiff improvements): | Patch | Purpose | |-------|---------| @@ -43,6 +43,7 @@ Seven patches are applied to upstream commit `cfb0f83` (which itself includes th | `0005` | Log ZMQ-to-notify latency for block-update performance monitoring | | `0006` | Expose raw reject count in pool stats | | `0007` | Replace hardcoded "ckpool" branding in the coinbase scriptSig with "kamado" (same 6 bytes, consensus-safe) | +| `0008` | Log full PoW reproduction data (raw 80-byte header, coinbase, merkle branches) when a share sets a new best difficulty | ### Middleware API @@ -77,6 +78,7 @@ The Svelte 5 dashboard connects via WebSocket for real-time push updates (no pol - **User/worker detail pages** — Deep dive into individual miner stats, cumulative work, and luck - **Block history** — Found blocks with height, hash, reward, solving worker, chain name, orphan status - **Best share leaderboard** — "This round" and "all-time" tracking with per-worker breakdown and glowing difficulty range indicators +- **PoW inspector** — Graphical breakdown of the block header behind the best share (version, prev block, merkle root, time, bits, nonce), the raw 80-byte header hex, and the coinbase + merkle branches that reproduce the merkle root — with one-click in-browser verification that replays the real SHA-256 compression rounds as an animation, ending at the share's block hash — self-contained implementation, no external services, works over plain-HTTP LAN - **Transaction accelerator** — Boost transactions via `prioritisetransaction` with marginal fee displacement analysis showing the revenue impact of each boost - **Block-found animation** — Celebratory toast on solve events - **Health banners** — Live status indicators for CKPool, bitcoind, ZMQ, and submit-gap diagnostics diff --git a/api/internal/logmon/tailer.go b/api/internal/logmon/tailer.go index f0883bf..9534806 100644 --- a/api/internal/logmon/tailer.go +++ b/api/internal/logmon/tailer.go @@ -15,6 +15,7 @@ package logmon import ( "bufio" "context" + "encoding/json" "errors" "io" "log/slog" @@ -67,6 +68,31 @@ type ShareEvent struct { Hash string // block header hash (hex, accepted shares only) Rejected bool Reason string // rejection reason (e.g. "Stale", "Duplicate"); empty for accepted + // Pow is set instead of the fields above when the line was a + // "Best share PoW data" record (ckpool patch 0008). It travels on + // the same channel as accepted/rejected events so ordering with + // the matching "Accepted client" line is preserved. + Pow *PowData +} + +// PowData is the proof-of-work reproduction record ckpool logs (patch +// 0008) when a share sets a new process-wide best difficulty: the raw +// 80-byte block header exactly as it was double-SHA256'd, the assembled +// coinbase transaction, and the merkle branch hashes linking that +// coinbase to the merkle root committed in the header. Field names +// mirror the JSON emitted by the patch. +type PowData struct { + SDiff float64 `json:"sdiff"` + NetDiff float64 `json:"netdiff"` + Height int64 `json:"height"` + Hash string `json:"hash"` // display-order (big-endian) block header hash + Header string `json:"header"` // 160 hex chars, hashing byte order + Coinbase string `json:"coinbase"` // full serialized coinbase tx, hex + CB1Len int `json:"cb1len"` // bytes preceding extranonce1 in the coinbase + MerkleBranches []string `json:"merklebranches"` + Enonce1 string `json:"enonce1"` + Nonce2 string `json:"nonce2"` + Workername string `json:"workername"` } // Tailer follows a log file, surviving rotation/truncation, and emits @@ -136,6 +162,40 @@ var ( rejectedInvalRE = regexp.MustCompile(`Rejected client \S+ invalid share (.+)`) ) +// powDataMarker precedes the JSON payload of a PoW reproduction line +// from our patch 0008, logged just before the matching "Accepted client" +// line when a share sets a new process-wide best: +// +// "Best share PoW data {"sdiff":...,"header":"...",...}" +const powDataMarker = "Best share PoW data " + +// parsePowLine extracts the PoW record from a log line carrying +// powDataMarker. It decodes exactly one JSON value starting at the first +// '{' after the marker and deliberately ignores everything after it — +// production logs have carried trailing bytes after the closing brace, +// which silently defeated an end-of-line-anchored regex. Returns +// (nil, nil) when the marker is absent, and a non-nil error for a +// present-but-undecodable record. +func parsePowLine(line string) (*PowData, error) { + i := strings.Index(line, powDataMarker) + if i < 0 { + return nil, nil + } + rest := line[i+len(powDataMarker):] + j := strings.IndexByte(rest, '{') + if j < 0 { + return nil, errors.New("no JSON object after PoW data marker") + } + var pd PowData + if err := json.NewDecoder(strings.NewReader(rest[j:])).Decode(&pd); err != nil { + return nil, err + } + if pd.Header == "" || pd.Hash == "" { + return nil, errors.New("PoW record missing header or hash") + } + return &pd, nil +} + // Run blocks until ctx is cancelled. It opens the file, seeks to either // the saved cursor (if LoadCursor returns one and the inode still // matches) or the end on first-ever run, and reads new lines as they @@ -284,6 +344,22 @@ func (t *Tailer) Run(ctx context.Context) { } func (t *Tailer) handleLine(line string) { + // PoW reproduction data (patch 0008). Must ship on the Shares + // channel so it stays ordered before its "Accepted client" line. + if strings.Contains(line, powDataMarker) { + pd, err := parsePowLine(line) + if err != nil { + t.Log.Warn("logmon: unparseable PoW data line", "err", err) + return + } + if pd != nil { + select { + case t.Shares <- ShareEvent{SeenAt: time.Now(), Pow: pd}: + default: + } + } + return + } // Accepted share: extract share difficulty and block header hash. if m := acceptedShareRE.FindStringSubmatch(line); m != nil { if d, err := strconv.ParseFloat(m[1], 64); err == nil { @@ -384,29 +460,116 @@ func FindBestShareHash(path string) (float64, string) { var bestDiff float64 var bestHash string - scanner := bufio.NewScanner(f) - scanner.Buffer(make([]byte, 0, 64*1024), 256*1024) - for scanner.Scan() { - line := scanner.Text() + _ = scanLines(f, func(line string) { if !strings.Contains(line, "Accepted client") { - continue + return } m := acceptedShareRE.FindStringSubmatch(line) if m == nil { - continue + return } d, err := strconv.ParseFloat(m[1], 64) if err != nil { - continue + return } if d >= bestDiff { bestDiff = d bestHash = m[2] } - } + }) return bestDiff, bestHash } +// scanLines invokes fn for every line of r. Unlike bufio.Scanner, a line +// of any length can never abort the scan: an oversized line is passed to +// fn truncated to the buffer size and its remainder is discarded. A +// months-old production log with one pathological line must not silently +// stop a backfill scan partway through — that failure mode is invisible +// and permanent. +func scanLines(f *os.File, fn func(line string)) error { + r := bufio.NewReaderSize(f, 256*1024) + skipping := false + for { + chunk, isPrefix, err := r.ReadLine() + if len(chunk) > 0 && !skipping { + fn(string(chunk)) + } + skipping = isPrefix + if err != nil { + if errors.Is(err, io.EOF) { + return nil + } + return err + } + } +} + +// logStampRE extracts the "[YYYY-MM-DD HH:MM:SS.mmm]" prefix ckpool +// puts on every log line (local time of the ckpool process). +var logStampRE = regexp.MustCompile(`^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})`) + +// FindBestPowData scans the log for the highest-difficulty "Best share +// PoW data" record (patch 0008) whose share was subsequently confirmed +// by an "Accepted client" line with the same hash. Used as a one-time +// backfill when kamado-api holds no persisted record but the log +// already contains some (fresh database, or PoW events dropped under +// load) — without it the PoW inspector would sit empty until a share +// beat ckpool's in-process best, which after a long uptime can take +// arbitrarily long. The returned time is parsed from the log line's +// timestamp; zero when unparseable. Returns a nil record if no confirmed +// record exists; err reports open/read failures and the returned counts +// say how many PoW lines were seen and how many failed to parse, so the +// caller can log a diagnosable outcome instead of a silent nil. +func FindBestPowData(path string) (best *PowData, bestAt time.Time, seen, unparseable int, err error) { + f, err := os.Open(path) + if err != nil { + return nil, time.Time{}, 0, 0, err + } + defer f.Close() + + // Records awaiting their "Accepted client" confirmation, keyed by + // hash. Bounded the same way as the aggregator's live pairing. + type parked struct { + pow *PowData + at time.Time + } + pending := make(map[string]parked) + err = scanLines(f, func(line string) { + if strings.Contains(line, powDataMarker) { + seen++ + pd, perr := parsePowLine(line) + if perr != nil || pd == nil { + unparseable++ + return + } + var at time.Time + if sm := logStampRE.FindStringSubmatch(line); sm != nil { + at, _ = time.ParseInLocation("2006-01-02 15:04:05", sm[1], time.Local) + } + if len(pending) >= 16 { + pending = make(map[string]parked) + } + pending[pd.Hash] = parked{pow: pd, at: at} + return + } + if !strings.Contains(line, "Accepted client") { + return + } + m := acceptedShareRE.FindStringSubmatch(line) + if m == nil { + return + } + if p, ok := pending[m[2]]; ok { + delete(pending, m[2]) + if best == nil || p.pow.SDiff > best.SDiff { + best = p.pow + bestAt = p.at + } + } + }) + return best, bestAt, seen, unparseable, err +} + // sleep returns false if ctx was cancelled during the wait. func sleep(ctx context.Context, d time.Duration) bool { select { diff --git a/api/internal/logmon/tailer_test.go b/api/internal/logmon/tailer_test.go index c26bd62..394db6d 100644 --- a/api/internal/logmon/tailer_test.go +++ b/api/internal/logmon/tailer_test.go @@ -5,6 +5,8 @@ import ( "io" "log/slog" "os" + "strconv" + "strings" "sync" "testing" "time" @@ -118,6 +120,158 @@ func TestHandleLine_Unrelated(t *testing.T) { } } +func TestHandleLine_PowData(t *testing.T) { + tl := New("/unused", discardLog()) + line := `[2026-08-31 10:11:12.123] Best share PoW data {"sdiff":123456789.5,"netdiff":136597951737045.0,"height":911111,` + + `"hash":"0000000000abcdef0000000000000000000000000000000000000000deadbeef",` + + `"header":"20000000" + "aa",` + "\n" + // Malformed JSON must not emit an event. + tl.handleLine(line) + select { + case ev := <-tl.Shares: + t.Errorf("unexpected ShareEvent from malformed PoW line: %+v", ev) + default: + } + + good := `[2026-08-31 10:11:12.123] Best share PoW data {"sdiff":123456789.5,"netdiff":136597951737045.0,"height":911111,` + + `"hash":"0000000000abcdef0000000000000000000000000000000000000000deadbeef",` + + `"header":"0000002006226e46111a0b59caaf126043eb5bbf28c34f3a5e332a1fc7b2b73cf188910f00000000000000000000000000000000000000000000000000000000000000006859a06817e0377c00000000",` + + `"coinbase":"01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff00ffffffff0100f2052a01000000160014000000000000000000000000000000000000000000000000",` + + `"cb1len":41,"merklebranches":["ab"],"enonce1":"a1b2c3d4","nonce2":"0011223344556677","workername":"bc1qexample.axe"}` + "\n" + tl.handleLine(good) + select { + case ev := <-tl.Shares: + if ev.Pow == nil { + t.Fatalf("ShareEvent.Pow = nil, want parsed PoW data (event %+v)", ev) + } + if ev.Pow.SDiff != 123456789.5 { + t.Errorf("SDiff = %v, want 123456789.5", ev.Pow.SDiff) + } + if ev.Pow.Height != 911111 { + t.Errorf("Height = %d, want 911111", ev.Pow.Height) + } + if len(ev.Pow.Header) != 160 { + t.Errorf("Header length = %d, want 160", len(ev.Pow.Header)) + } + if ev.Pow.CB1Len != 41 { + t.Errorf("CB1Len = %d, want 41", ev.Pow.CB1Len) + } + if len(ev.Pow.MerkleBranches) != 1 || ev.Pow.MerkleBranches[0] != "ab" { + t.Errorf("MerkleBranches = %v, want [ab]", ev.Pow.MerkleBranches) + } + if ev.Pow.Workername != "bc1qexample.axe" { + t.Errorf("Workername = %q", ev.Pow.Workername) + } + default: + t.Fatal("no ShareEvent emitted for PoW data line") + } +} + +func powLine(hash string, sdiff float64) string { + return `[2026-08-30 09:15:42.123] Best share PoW data {"sdiff":` + + strconv.FormatFloat(sdiff, 'f', -1, 64) + + `,"netdiff":1.3e14,"height":911111,"hash":"` + hash + + `","header":"00000020aabb","coinbase":"0100","cb1len":41,` + + `"merklebranches":[],"enonce1":"a1b2c3d4","nonce2":"0011223344556677","workername":"bc1q.axe"}` + "\n" +} + +func acceptedLine(hash string, sdiff float64) string { + return `[2026-08-30 09:15:42.124] Accepted client 7 share diff ` + + strconv.FormatFloat(sdiff, 'f', -1, 64) + `/42/1.0K: ` + hash + "\n" +} + +// FindBestPowData must return the highest-diff record that was +// confirmed accepted, skip unconfirmed ones, and recover the log +// line's timestamp. +func TestFindBestPowData(t *testing.T) { + path := tempLog(t) + appendLines(t, path, + powLine("aaaa", 100), + acceptedLine("aaaa", 100), + // Never confirmed (e.g. rejected below vardiff): must be ignored + // even though it carries the highest diff. + powLine("bbbb", 99999), + powLine("cccc", 500), + acceptedLine("cccc", 500), + ) + + pow, at, seen, unparseable, err := FindBestPowData(path) + if err != nil { + t.Fatalf("scan error: %v", err) + } + if pow == nil { + t.Fatal("FindBestPowData returned nil, want the confirmed 500-diff record") + } + if pow.Hash != "cccc" || pow.SDiff != 500 { + t.Errorf("got hash %s sdiff %v, want cccc/500", pow.Hash, pow.SDiff) + } + if seen != 3 || unparseable != 0 { + t.Errorf("seen=%d unparseable=%d, want 3/0", seen, unparseable) + } + want := time.Date(2026, 8, 30, 9, 15, 42, 0, time.Local) + if !at.Equal(want) { + t.Errorf("timestamp = %v, want %v", at, want) + } +} + +// Production ckpool logs have carried bytes after the JSON's closing +// brace (observed in the field: an end-of-line-anchored regex matched 0 +// of 54 real PoW lines while synthetic lines passed). The parser must +// decode the JSON value and ignore ANY trailing bytes — NULs, \r, +// or an interleaved second message on the same line. +func TestHandleLine_PowDataTrailingGarbage(t *testing.T) { + suffixes := []string{ + "\x00\x00\n", // NUL padding + "\r\n", // CR before LF + " [2026-08-31 18:00:01.125] Accepted client 3 share diff 1.0/1/1: aa\n", // interleaved write + } + for _, suffix := range suffixes { + tl := New("/unused", discardLog()) + tl.handleLine(strings.TrimRight(powLine("cafe", 777), "\n") + suffix) + select { + case ev := <-tl.Shares: + if ev.Pow == nil || ev.Pow.Hash != "cafe" || ev.Pow.SDiff != 777 { + t.Errorf("suffix %q: got %+v, want cafe/777 PoW event", suffix, ev.Pow) + } + default: + t.Errorf("suffix %q: no PoW event emitted", suffix) + } + } +} + +// A pathologically long line earlier in the log must not abort the scan +// before it reaches the PoW records — bufio.Scanner did exactly that, +// silently, which left the backfill permanently empty on real logs. +func TestFindBestPowData_SurvivesOversizedLine(t *testing.T) { + path := tempLog(t) + appendLines(t, path, + "junk "+strings.Repeat("x", 600*1024)+"\n", // > any fixed buffer + powLine("abab", 250), + acceptedLine("abab", 250), + ) + pow, _, seen, _, err := FindBestPowData(path) + if err != nil { + t.Fatalf("scan error: %v", err) + } + if pow == nil || pow.Hash != "abab" || seen != 1 { + t.Fatalf("pow=%+v seen=%d, want abab record found past the oversized line", pow, seen) + } +} + +func TestFindBestPowData_Empty(t *testing.T) { + path := tempLog(t) + appendLines(t, path, + "Stratifier started\n", + acceptedLine("dddd", 10), // accepted share without PoW data (pre-patch line) + ) + if pow, _, _, _, err := FindBestPowData(path); pow != nil || err != nil { + t.Errorf("got %+v err=%v, want nil/nil for log without confirmed PoW records", pow, err) + } + if pow, _, _, _, err := FindBestPowData(path + ".missing"); pow != nil || err == nil { + t.Errorf("got %+v err=%v, want nil record and an error for missing file", pow, err) + } +} + // ---- Tailer.Run integration tests (filesystem + goroutines) ---- func tempLog(t *testing.T) string { diff --git a/api/internal/state/aggregator.go b/api/internal/state/aggregator.go index f09bd14..e7539f5 100644 --- a/api/internal/state/aggregator.go +++ b/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 { diff --git a/api/internal/state/pow_e2e_test.go b/api/internal/state/pow_e2e_test.go new file mode 100644 index 0000000..e7ffb66 --- /dev/null +++ b/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) + } +} diff --git a/api/internal/state/pow_test.go b/api/internal/state/pow_test.go new file mode 100644 index 0000000..beabd6b --- /dev/null +++ b/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) + } +} diff --git a/ckpool/patches/0008-log-best-share-pow-data.patch b/ckpool/patches/0008-log-best-share-pow-data.patch new file mode 100644 index 0000000..f1834b3 --- /dev/null +++ b/ckpool/patches/0008-log-best-share-pow-data.patch @@ -0,0 +1,90 @@ +diff --git a/src/stratifier.c b/src/stratifier.c +index 7940d4fa..a856b3eb 100644 +--- a/src/stratifier.c ++++ b/src/stratifier.c +@@ -5865,6 +5865,65 @@ out_nouserwb: + return wb->coinb2bin; + } + ++/* Kamado (patches/0008): highest share diff for which PoW reproduction ++ * data has been logged in this process run. Deliberately unlocked — a ++ * race between share-processing threads can at worst emit a duplicate ++ * or out-of-order log line, which kamado-api deduplicates by diff. */ ++static double best_pow_diff; ++ ++/* Kamado (patches/0008): log everything needed to independently ++ * reproduce and verify the proof of work of a best share — the ++ * serialized 80-byte block header exactly as it was hashed, plus the ++ * assembled coinbase transaction and merkle branch hashes that ++ * reproduce the merkle root committed in that header. kamado-api ++ * parses this line from the log to power the dashboard PoW inspector. ++ * Needs to be entered with workbase readcount held. */ ++static void log_best_pow_data(const stratum_instance_t *client, const workbase_t *wb, ++ const char *nonce2, const char *coinbase, const int cblen, ++ const uchar *swap, const uchar *hash, const double sdiff) ++{ ++ char header_hex[164], hexhash[68]; ++ json_t *val, *branches; ++ uchar sharehash[32]; ++ char *cb_hex, *s; ++ int i; ++ ++ __bin2hex(header_hex, swap, 80); ++ bswap_256(sharehash, hash); ++ __bin2hex(hexhash, sharehash, 32); ++ cb_hex = bin2hex(coinbase, cblen); ++ if (unlikely(!cb_hex)) ++ return; ++ branches = json_array(); ++ for (i = 0; i < wb->merkles; i++) ++ json_array_append_new(branches, json_string(&wb->merklehash[i][0])); ++ val = json_object(); ++ json_set_double(val, "sdiff", sdiff); ++ json_set_double(val, "netdiff", wb->network_diff); ++ json_set_int(val, "height", wb->height); ++ json_set_string(val, "hash", hexhash); ++ json_set_string(val, "header", header_hex); ++ json_set_string(val, "coinbase", cb_hex); ++ json_set_int(val, "cb1len", wb->coinb1len); ++ json_object_set_new(val, "merklebranches", branches); ++ json_set_string(val, "enonce1", client->enonce1); ++ json_set_string(val, "nonce2", nonce2); ++ json_set_string(val, "workername", client->workername ? client->workername : ""); ++ s = json_dumps(val, JSON_COMPACT); ++ json_decref(val); ++ free(cb_hex); ++ if (likely(s)) { ++ /* Call logmsg directly rather than LOGNOTICE: the LOGMSG ++ * macro splits messages into DEFLOGBUFSIZ (512-byte) chunks, ++ * each written as a separate timestamped log line — and its ++ * length arithmetic drops everything past ~3 chunks. This ++ * record is ~2.5KB of JSON that kamado-api must read back as ++ * one intact line. logmsg itself is unbounded. */ ++ logmsg(LOG_NOTICE, "Best share PoW data %s", s); ++ free(s); ++ } ++} ++ + /* Needs to be entered with workbase readcount and client holding a ref count. */ + static double submission_diff(sdata_t *sdata, const stratum_instance_t *client, const workbase_t *wb, + const char *nonce2, const uint32_t ntime32, uint32_t version_mask, +@@ -5937,6 +5996,19 @@ static double submission_diff(sdata_t *sdata, const stratum_instance_t *client, + /* Calculate the diff of the share here */ + ret = diff_from_target(hash); + ++ /* Kamado (patches/0008): if this is the highest-diff share this ++ * process has seen, log full PoW reproduction data for the ++ * dashboard's best-share header inspector. Skip shares that will ++ * be rejected: stale ones, and those outside the ntime roll ++ * window (mirrors the check in parse_submit). Duplicates cannot ++ * trigger this — an identical share has an equal, not greater, ++ * diff. */ ++ if (unlikely(ret > best_pow_diff && !stale && ++ ntime32 >= wb->ntime32 && ntime32 <= wb->ntime32 + 7000)) { ++ best_pow_diff = ret; ++ log_best_pow_data(client, wb, nonce2, coinbase, cblen, swap, hash, ret); ++ } ++ + /* Test we haven't solved a block regardless of share status */ + test_blocksolve(client, wb, swap, hash, ret, coinbase, cblen, nonce2, nonce, ntime32, version_mask, stale); + diff --git a/ui/src/App.svelte b/ui/src/App.svelte index 53c0f1a..c01377e 100644 --- a/ui/src/App.svelte +++ b/ui/src/App.svelte @@ -14,6 +14,7 @@ import AcceleratorPage from "./lib/AcceleratorPage.svelte"; import StatsPage from "./lib/StatsPage.svelte"; import BestSharePage from "./lib/BestSharePage.svelte"; + import SharePowPage from "./lib/SharePowPage.svelte"; import SharesBar from "./lib/SharesBar.svelte"; import BlockFoundAnimation from "./lib/BlockFoundAnimation.svelte"; import QRCode from "qrcode"; @@ -64,6 +65,12 @@ {/key} + {:else if selection.page === "bestshare-pow"} + {#key 'bestshare-pow'} +
+ +
+ {/key} {:else if selection.worker} {#key selection.worker}
diff --git a/ui/src/lib/BestSharePage.svelte b/ui/src/lib/BestSharePage.svelte index a2bb40e..62d57ad 100644 --- a/ui/src/lib/BestSharePage.svelte +++ b/ui/src/lib/BestSharePage.svelte @@ -1,5 +1,5 @@ + + + +
+ + +
+
Best Share Proof of Work
+

The block header behind the share

+
+ + {#if !pow} +
+
+

+ Header capture was not active when the current best share was found, and CKPool + discards job data once work moves on — so the block header of that share can + no longer be reconstructed. +

+

+ The pool now records the full header, coinbase, and merkle branches as shares come + in. The next accepted share will populate this page, which then tracks the best + share found since header capture was enabled — it does not wait for the + all-time record to be beaten. Once a share does beat the all-time best, the two + converge and this page shows the overall best share. +

+
+
+ {:else} + {#if isNewerThanAllTime} +
+ Showing the best share since header capture was enabled + ({formatDifficulty(pow.sdiff)}, found {foundAt}). The all-time best share + ({formatDifficulty(data.best_diff)}) predates this feature, and its block header + was not recorded and cannot be reconstructed retroactively. +
+ {/if} + + +
+
+
Share Difficulty
+
{formatDifficulty(pow.sdiff)}
+
network was {formatDifficulty(pow.netdiff)} at the time
+
+
+
Mining Block
+
#{pow.height.toLocaleString()}
+
the height this share was trying to solve
+
+
+
Found By
+
{pow.workername || "—"}
+
{foundAt}
+
+
+ + +
+

Block Header — 80 bytes

+

+ This is the block this share was building, drawn as it exists on the wire. The + header's six fields are serialized little-endian into 80 bytes; the + previous block field is what chains it to the + current tip. +

+ +
+ + + +
+
+ BLOCK #{pow.height.toLocaleString()} + header · 80 bytes +
+ {#each fields as f (f.key)} +
+
+
+
+ {f.name} + bytes {f.bytes} +
+
+ {#if f.key === "prev"} + {f.value} + {:else} + {f.value} + {/if} +
+
{f.sub}
+
+
+ {/each} +
+ + transactions — not part of the header; committed by the + merkle root above +
+
+
+
+ + +
+

Raw Header — verify it yourself

+

+ Hash these 160 hex characters with double SHA-256 and reverse the result: you get the + share hash. No trust in this dashboard required. +

+ +
+
+ {#each fields as f (f.key)}{f.raw}{/each} +
+ +
+ +
+ + + replays the full verification — merkle proof, padding, every SHA-256 stage + — from the real computation, locally + +
+ + {#if animating && step} +
+
+ + + +
+ + {#if chapter} +
+ {chapter.n}/{chapter.of} + {chapter.title} +
+ + {/if} + + {#if step.kind === "chapter"} +
{step.ch.title}
+ {:else if step.kind === "merkle-init"} +
SHA-256d(coinbase transaction) → its txid:
+
{step.txid}
+
internal byte order, as used while hashing
+ {:else if step.kind === "merkle-fold"} +
+ Fold level {step.i}/{step.total} — concatenate with branch hash, SHA-256d again: +
+
+ current + {step.left} + branch {step.i} + {step.right} + → new + {step.result} +
+
+ each branch hash summarizes every other transaction in its subtree +
+ {:else if step.kind === "merkle-done"} +
Merkle root reproduced:
+
{step.root}
+
+ {step.matches + ? "= the merkle root committed in the header ✓" + : "≠ the header's merkle root!"} +
+ {:else if step.kind === "padding"} +
+ 80 header bytes + 0x80 marker + 39 zero bytes + + 640-bit length = 128 bytes: +
+
+
+
message block 1 · 512 bits
+
+ {#each padBlock1 as s, i (i)}{s.hex}{/each} +
+
+
+
message block 2 · 512 bits
+
+ {#each padBlock2 as s, i (i)}{s.hex}{/each} +
+
+
+
+ note the merkle root straddling the block + boundary — SHA-256 processes 64 bytes at a time regardless of field layout +
+ {:else if step.kind === "init-h"} +
Eight 32-bit registers start from the SHA-256 constants:
+
+ {#each INIT_H as v, i (i)} +
+ H{i} + {v} +
+ {/each} +
+
+ the fractional parts of the square roots of the first eight primes — "nothing up + my sleeve" numbers +
+ {:else if step.kind === "schedule"} +
+ Block {step.block}/{step.blocks} becomes sixteen 32-bit words w0…w15: +
+
+ {#each step.words as w, i (i)} +
w{i}{w}
+ {/each} +
+
+ rounds 17–64 consume words expanded from these (σ0/σ1 mixing) +
+ {:else if step.kind === "round"} +
+
+
+
+ block {step.block}/{step.blocks} · compression round + {String(step.round).padStart(2, "0")}/64 · + W[t]={step.wt} K[t]={step.kt} +
+
+ {#each step.regs as r, i (i)} +
+ {"abcdefgh"[i]} + {r} +
+ {/each} +
+
+ T1 = h + Σ1(e) + Ch(e,f,g) + K[t] + W[t]  ·  T2 = Σ0(a) + Maj(a,b,c) +  →  a = T1+T2, e = d+T1, rest shift down +
+ {:else if step.kind === "add-h"} +
+ 64 rounds done — the result is added into the running state + (Davies–Meyer), chaining block {step.block} forward: +
+
+ {#each step.state as v, i (i)} +
+ H{i} + {v} +
+ {/each} +
+ {:else if step.kind === "digest"} +
{step.label}:
+
{step.hex}
+ {:else if step.kind === "reverse"} +
{digest2Hex}
+ +
+ {#each finalHashChars as ch}{ch.c}{/each} +
+ {:else if step.kind === "target"} +
+
+ your hash + + {#each finalHashChars as ch}{ch.c}{/each} + +
+
+ share target + {shareTargetHex} +
+
+ network target + {netTargetHex} +
+
+
+ hash < share target — that's what made it a + {formatDifficulty(pow.sdiff)} share. The network target is another + {targetGapX >= 1000 ? formatDifficulty(targetGapX) : targetGapX.toFixed(1)}× + lower: beat it, and this header would have been block #{pow.height.toLocaleString()}. +
+ {/if} +
+ {/if} + + {#if verified && !animating} +
+
Computed block header hash
+
+ {#each finalHashChars as ch}{ch.c}{/each} +
+
+ {finalHash === pow.hash + ? "= the recorded share hash — proof of work is genuine" + : "≠ the recorded share hash!"} +
+
    + {#each checks as c (c.name)} +
  • + {c.ok ? "✓" : "✗"} + + {c.name} + {c.detail} + +
    • + {/each} +
+ +
+ {/if} + +
+
Or from any terminal
+
+
{cliSnippet}
+ +
+
+
+ + +
+

Reproducing the Merkle Root

+

+ The header's merkle root commits to every transaction in the block, but reproducing + it doesn't require the full transaction list — only the coinbase transaction + this pool built and one branch hash per tree level. Each branch hash cryptographically + summarizes the other transactions in its subtree, so the proof below is exactly as + strong as storing all of them. (CKPool discards the full template once work moves on, + which is also why the complete transaction set isn't shown.) +

+ +
Coinbase transaction ({pow.coinbase.length / 2} bytes)
+
+
+ {#each cbSegments as s (s.key)}{s.hex}{/each} +
+ +
+
+ {#each cbSegments as s (s.key)} + + + {s.name} + — {s.desc} + + {/each} +
+ +
+
+ Merkle branches ({branches.length}) +
+ {#if branches.length === 0} +
+ None — the block template contained only the coinbase transaction, so the + merkle root is simply the coinbase txid. +
+ {:else} +
    + {#each branches as b, i (i)} +
  1. {b}
    2. + {/each} +
+
+ Fold upward: start with SHA-256d(coinbase), then for each branch compute + SHA-256d(current ‖ branch). The result is the merkle root in the + header. The "Verify" animation above walks through exactly this. +
+ {/if} +
+ +
+
Stratum work identity
+
+ extranonce1 {pow.enonce1} · extranonce2 + {pow.nonce2} +
+
+
+ {/if} +
+ + diff --git a/ui/src/stores/selection.svelte.ts b/ui/src/stores/selection.svelte.ts index c33a8d7..c53f3d1 100644 --- a/ui/src/stores/selection.svelte.ts +++ b/ui/src/stores/selection.svelte.ts @@ -14,6 +14,7 @@ const WORKER_PREFIX = "#/worker/"; const ACCELERATOR_HASH = "#/accelerator"; const STATS_HASH = "#/stats"; const BESTSHARE_HASH = "#/bestshare"; +const BESTSHARE_POW_HASH = "#/bestshare/pow"; type Selection = { user: string | null; worker: string | null; page: string | null }; @@ -28,6 +29,9 @@ function readHash(): Selection { if (h === STATS_HASH) { return { user: null, worker: null, page: "stats" }; } + if (h === BESTSHARE_POW_HASH) { + return { user: null, worker: null, page: "bestshare-pow" }; + } if (h === BESTSHARE_HASH) { return { user: null, worker: null, page: "bestshare" }; } @@ -73,6 +77,10 @@ export function selectBestShare(): void { window.location.hash = BESTSHARE_HASH; } +export function selectBestSharePow(): void { + window.location.hash = BESTSHARE_POW_HASH; +} + export function clearSelection(): void { window.location.hash = ""; } diff --git a/ui/src/types.ts b/ui/src/types.ts index 0f9f4f9..52e461b 100644 --- a/ui/src/types.ts +++ b/ui/src/types.ts @@ -113,6 +113,26 @@ export type HashratePoint = { v: number; // H/s }; +// PoW reproduction data for the best share seen since ckpool patch 0008 +// went live (logged by ckpool, ingested from the log by kamado-api). +// `header` is the raw 80-byte block header in hashing byte order — +// double-SHA256 it and reverse the digest to get `hash`. `coinbase` plus +// `merklebranches` reproduce the merkle root committed in the header. +export type BestSharePow = { + sdiff: number; + netdiff: number; + height: number; + hash: string; // display-order (big-endian) block header hash + header: string; // 160 hex chars + coinbase: string; // full serialized coinbase tx, hex + cb1len: number; // bytes preceding extranonce1 within the coinbase + merklebranches: string[] | null; + enonce1: string; + nonce2: string; + workername: string; + seen_at: string; // RFC 3339, when kamado-api ingested the record +}; + // One entry per ckpool serverurl[] bind, declared by the deployment via // the STRATUM_SERVERS env. `kind` is the stable tag the UI switches on; // `label` is free text shown on hover. @@ -137,6 +157,11 @@ export type Snapshot = { best_diff: number; best_share_hash?: string; best_share_net_diff?: number; + // Full header/coinbase/merkle-branch record for the best share seen + // since ckpool patch 0008 was deployed. May describe a lower-diff + // share than best_diff when the all-time best predates the patch — + // compare hashes and disclose. + best_share_pow?: BestSharePow; acked_best_diff: number; cumulative_shares: number; next_block_reward_btc: number;