dash(oracle): embedded ORACLE-SHADOW validator + graduation gate (first slice) [DRAFT]

[frstrtr]

Review fixes landed (commit 8ac2ee3)

• REQUIRED — false-graduation vector fixed: NonEmptyTemplate now classifies on the embedded side only (!e.empty_template) — dashd's near-always-non-empty template can no longer tick the class while the embedded arm serves empty templates.
• (a/b) dashd-side rpc-error: + proposal-mode tip-race reasons (inconclusive/not-best-prevblk/stale) now VOID the sample (no count, no streak reset) instead of false-REJECT.
• (c) ledger identity commit key = git describe --tags --always --dirty; no-git/dev fallbacks are never-inherit.
• (d) creditPool INVARIANT base now = the connected block N-1's committed value (getblock v2 → tx[0].cbTx.creditPoolBalance), not dashd's previous template projection.
• (e) the compare runs on a dedicated coalescing worker thread, all dashd RPCs outside the ledger mutex — a hung dashd cannot stall tip processing or block /embedded_oracle; worker joined before node_coin_state/rpc unwind.
• (f) the 11-KAT test_dash_embedded_oracle_shadow is folded into the already-CI-allowlisted test_dash_embedded_gbt target (20 tests green) — no build.yml workflow edit needed.

Rebuilt clean; serve path still untouched (consensus-neutral).

---

Summary

First working slice of the DASH Embedded ORACLE-SHADOW VALIDATOR — the operator's directive toward a fully daemonless c2pool, safely. Run c2pool ALONGSIDE a Dash Core daemon and use dashd as a continuous realtime oracle: on every new tip, verify the daemonless embedded DIP4 CbTx/template arm against what dashd would produce, catching consensus bugs throughout the alpha, plus an objective graduation criterion that says when it is safe to disable the external dashd.

OBSERVE-only / consensus-neutral. The serve/consensus/share path is untouched — the shadow is a separate new_tip subscriber that only reads the SAME embedded build path (NodeCoinState::select_work) + the SAME dashd RPC closure the serve arm holds. Empty diff-grep over work_source.cpp, coinbase_builder.hpp, share_check.hpp, pplns.hpp, node_coin_state.hpp, embedded_gbt.hpp, coin_state_maintainer.hpp.

Design doc: frstrtr/the docs/c2pool-dash-embedded-oracle-shadow-validator.md (committed). Implements the five §6 conditions of c2pool-dash-oracle-shadow-adversarial-critique.md.

What the first slice does

• --embedded-oracle-shadow mode (+ --oracle-graduation-blocks N, --oracle-class-coverage K). Arms when the coin-P2P feed is present (--coin-p2p-connect).
• Per-block VERDICT = dashd getblocktemplate{mode:proposal} of the fully-assembled embedded block (NodeRPC::propose_block_hex) — TestBlockValidity, mempool-independent. This is the authoritative pass/fail (the oracle the soaks used, which the naive field-only draft dropped). A served height counts CLEAN only when the proposal is ACCEPTED.
• Per-block DIAGNOSIS = regime-aware field compare vs dashd getblocktemplate:
  • EQUALITY (counts): nHeight, CbTx version, bits, mintime, payee IDENTITY, platform burn amount, normalized subsidy (coinbasevalue − Σfees), MN/quorum roots on empty templates.
  • INVARIANT (counts on violation): creditPool normalized-base (committed − platformReward − ownΔ == creditPool(N−1) per side) — the exact check that caught the seed bug 3×.
  • CONSTRAINT (range): bestCL* — sig-equality only when the two nodes' CL heights coincide.
  • informational (NEVER counts): raw coinbasevalue, MN/payee amounts, tx set — the separate-mempool false-positives.
• Divergence handling: [EMB-ORACLE] DIVERGENCE height=<h> class=<c> field=<f> … structured logs + a persistent JSONL ledger under the data-dir.
• Graduation ledger + /embedded_oracle JSON endpoint: GRADUATED ⇔ N consecutive served+proposal-accepted clean blocks AND ≥K served coverage of each class (dkg_window, superblock, post_restart_cold, quorum_rotation, credit_pool_transition, non_empty_template) AND ≥1 reorg AND serve-rate floor AND not-revoked. Selection-bias fix: fall-closed classes are recorded and declared as residual serve-gaps (disabling dashd removes the fallback those classes rely on). Verdict gives the exact still_needed + residual_serve_gaps breakdown.
• Alignment on (height, prev_hash); ledger hard-keyed to {c2pool_commit, comparator_version, dashd_version, net} (a new binary does not inherit an old streak); revocable by chain-drift sentinels (unknown CbTx version / payload parse fail).

Scope of the graduation claim

GRADUATED == chain-state / CbTx-validity equivalence over the served domain (reward-safe daemonless block construction). Soundness rests on the embedded arm's independent chain-state derivation (own SPV/mnlistdiff/quorum/credit-pool pipeline), NOT peer diversity — DASH has no CoinPeerManager. Full network-standalone daemonless operation additionally needs the separate network-layer gate (independent mempool/relay/propagation/peers); the verdict says so.

Build + tests

• c2pool-dash builds; --selftest passes; --help shows the flag.
• test_dash_embedded_oracle_shadow — 11 hermetic KATs (green) pinning the regime model, the fee-difference-is-not-a-divergence keystone, the creditPool invariant, the bestCL constraint, and the graduation predicate (+ serve-rate floor, fall-closed serve-gap declaration, revocation).

Follow-ups (scoped in the design doc)

• Embedded selector must EXCLUDE special-tx types (1–4, 6, 8, 9) until their state machines exist (§1.1 latent bug — a consensus-path change, separate).
• Nonzero-fee pinning of the platform-reward / MN-amount models (all soaks ran fees=0).
• Confirm-before-count settle re-sample; full mainnet DKG-window table; phase-diverse restart automation; live-CLSIG getdata leg.
• CoinPeerManager port to DASH — the network-layer gate.