dgb: M3 §7b DigiShield Scrypt-only ancestor walk + work-credit predicate

Isolates the consensus quirk flagged at header_chain.hpp DIGISHIELD INSERTION
POINT: the Scrypt difficulty window must walk Scrypt-algo ancestors ONLY and
skip continuity (non-Scrypt) headers; folding a continuity header into the
window corrupts the Scrypt retarget and breaks the THIRD INVARIANT work-
neutrality. Adds header_credits_work() as the single SSOT predicate the
validate() work-accounting and the retarget walk both consult, so they cannot
drift. Header-only (deps: dgb_block_algo.hpp + std), so it links into the
standalone GTest guard with no dgb OBJECT lib.

- coin/dgb_digishield.hpp: scrypt_window_ancestors(), header_credits_work()
- test/digishield_walk_test.cpp: 6 guards (zero-bits Scrypt, interleave skip,
  leading-continuity run, exhausted chain, zero window, work predicate)
- wired into BOTH ctest foreach AND both build.yml --target allowlists (#143)

Per-algo DigiShield target math layers on top in the following slice.

Author: frstrtr

.github/workflows/build.yml

@@ -68,7 +68,7 @@ jobs:
                     test_mweb_builder \
                     test_address_resolution test_compute_share_target \
                     test_utxo test_dgb_subsidy dgb_share_test \
-                    rpc_request_test softfork_check_test genesis_check_test algo_select_test \
+                    rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test \
                     v37_test \
             -j$(nproc)
 
@@ -196,7 +196,7 @@ jobs:
                     test_mweb_builder \
                     test_address_resolution test_compute_share_target \
                     test_utxo test_dgb_subsidy dgb_share_test \
-                    rpc_request_test softfork_check_test genesis_check_test algo_select_test \
+                    rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test \
                     test_coin_broadcaster test_multiaddress_pplns test_pplns_stress \
                     v37_test \
             -j$(nproc)

src/impl/dgb/coin/dgb_digishield.hpp

@@ -0,0 +1,73 @@
+#pragma once
+// ---------------------------------------------------------------------------
+// DGB DigiShield Scrypt-only ancestor walk  (M3 §7b — SCRYPT-ONLY VALIDATION).
+//
+// DigiByte retargets per-block per-algo with DigiShield/MultiShield, NOT
+// Bitcoin's 2016-block window. For the V36 Scrypt-only lane the difficulty
+// window must walk SCRYPT-ALGO ancestors ONLY. On a mixed-algo chain the
+// header sequence interleaves Scrypt headers (full PoW validate) with
+// non-Scrypt headers accepted by continuity (work-neutral). Folding a
+// continuity header into the retarget window corrupts the Scrypt target AND
+// re-introduces the work-neutrality break documented as the THIRD INVARIANT
+// in coin/header_chain.hpp. This header isolates that walk so the trap lives
+// in one consensus-pinned, separately-guarded place — exactly the failure the
+// header_chain.hpp DIGISHIELD INSERTION POINT note warns is "easy to get wrong
+// on a mixed-algo chain".
+//
+// This is the ancestor-selection step only; the per-algo DigiShield target
+// math (LWMA/MultiShield) layers on top in the following slice and consumes
+// the indices this returns.
+//
+// Header-only: depends ONLY on coin/dgb_block_algo.hpp + std, so it links into
+// the standalone CI guard (GTest-only, no dgb OBJECT lib) like algo_select.
+// ---------------------------------------------------------------------------
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <vector>
+
+#include <impl/dgb/coin/dgb_block_algo.hpp>
+
+namespace dgb::coin {
+
+// THIRD-INVARIANT work-accounting predicate. Only a Scrypt header credits
+// cumulative work / best-chain weight; a continuity (known non-Scrypt) header
+// extends the header chain but is work-neutral. This is the single predicate
+// HeaderChain::validate() consults before adding a header's work, so the
+// invariant cannot drift between the validate() path and the retarget walk.
+inline bool header_credits_work(int32_t n_version) noexcept
+{
+    return is_scrypt_header(n_version);
+}
+
+// Collect the Scrypt-algo ancestors that form a DigiShield retarget window.
+//
+//   version_at(k) -> nVersion of the header k positions back from the search
+//                    start (k = 0 is the nearest candidate ancestor).
+//   depth         -> how many positions are walkable (chain length behind).
+//   window        -> number of Scrypt ancestors the retarget needs.
+//
+// Returns the k-indices of the first `window` SCRYPT headers, nearest-first,
+// skipping every non-Scrypt (continuity) header. Returns fewer than `window`
+// only when the available chain is exhausted (early-chain / genesis region).
+// Unknown-algo headers never enter a validated chain (REJECT at ingest), so
+// the walk treats anything not Scrypt as a skip.
+inline std::vector<std::size_t> scrypt_window_ancestors(
+    const std::function<int32_t(std::size_t)>& version_at,
+    std::size_t depth,
+    std::size_t window)
+{
+    std::vector<std::size_t> out;
+    if (window == 0) return out;
+    out.reserve(window);
+    for (std::size_t k = 0; k < depth && out.size() < window; ++k)
+    {
+        if (is_scrypt_header(version_at(k)))
+            out.push_back(k);
+        // else: continuity header -> skipped, contributes no window sample
+    }
+    return out;
+}
+
+} // namespace dgb::coin

src/impl/dgb/coin/header_chain.hpp

@@ -34,5 +34,8 @@
 // ONLY — never the interleaved multi-algo header chain. On a mixed-algo chain
 // the previous-block / window walk must skip non-Scrypt (continuity) headers;
 // folding them into the window corrupts the Scrypt retarget and re-introduces
-// the work-neutrality break above. Easy to get wrong on a mixed-algo chain.
+// the work-neutrality break above. Easy to get wrong on a mixed-algo chain. The Scrypt-only
+// ancestor selection for that window is implemented + guarded in
+// coin/dgb_digishield.hpp (scrypt_window_ancestors + header_credits_work);
+// the per-algo target math layers on top of it.
 namespace c2pool::dgb { /* TODO(M3): HeaderChain w/ Scrypt-only validate() + accept-by-continuity */ }

src/impl/dgb/test/CMakeLists.txt

@@ -25,7 +25,7 @@ if (BUILD_TESTING AND GTest_FOUND)
     # transport rpc.cpp wiring is deferred (Option-B scope). Each MUST appear
     # in BOTH this ctest registration AND the build.yml --target allowlist,
     # or it becomes a #143-style NOT_BUILT sentinel that reds master.
-    foreach(dgb_guard rpc_request_test softfork_check_test genesis_check_test algo_select_test)
+    foreach(dgb_guard rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test)
         add_executable(${dgb_guard} ${dgb_guard}.cpp)
         target_link_libraries(${dgb_guard} PRIVATE
             GTest::gtest_main GTest::gtest nlohmann_json::nlohmann_json)

src/impl/dgb/test/digishield_walk_test.cpp

@@ -0,0 +1,84 @@
+// ---------------------------------------------------------------------------
+// dgb M3 §7b DigiShield Scrypt-only ancestor-walk regression guard.
+//
+// Pins the consensus quirk flagged at coin/header_chain.hpp's DIGISHIELD
+// INSERTION POINT: on a mixed-algo DGB chain the Scrypt difficulty window must
+// walk SCRYPT ancestors ONLY and SKIP continuity (non-Scrypt) headers. Folding
+// a continuity header into the window corrupts the Scrypt retarget and breaks
+// work-neutrality (THIRD INVARIANT). Also pins header_credits_work() == the
+// Scrypt predicate, so the validate() work-accounting and the retarget walk
+// share one SSOT and cannot drift apart.
+//
+// Links ONLY the header-only helpers + gtest -- no dgb OBJECT lib / transport.
+// ---------------------------------------------------------------------------
+
+#include <cstdint>
+#include <vector>
+
+#include <gtest/gtest.h>
+
+#include <impl/dgb/coin/dgb_digishield.hpp>
+
+using namespace dgb::coin;
+
+static constexpr int32_t PRIMARY = 2; // BLOCK_VERSION_DEFAULT
+static constexpr int32_t SCRYPT   = PRIMARY | DGB_BLOCK_VERSION_SCRYPT;
+static constexpr int32_t SHA256D  = PRIMARY | DGB_BLOCK_VERSION_SHA256D;
+static constexpr int32_t SKEIN    = PRIMARY | DGB_BLOCK_VERSION_SKEIN;
+static constexpr int32_t ODO      = PRIMARY | DGB_BLOCK_VERSION_ODO;
+
+// Build a version_at() over a fixed nearest-first chain.
+static std::function<int32_t(std::size_t)> chain(const std::vector<int32_t>& c)
+{
+    return [c](std::size_t k) { return c.at(k); };
+}
+
+TEST(DigishieldWalk, WorkCreditPredicateIsScryptOnly)
+{
+    EXPECT_TRUE (header_credits_work(SCRYPT));
+    EXPECT_TRUE (header_credits_work(PRIMARY));        // bare primary == Scrypt
+    EXPECT_FALSE(header_credits_work(SHA256D));
+    EXPECT_FALSE(header_credits_work(SKEIN));
+    EXPECT_FALSE(header_credits_work(ODO));
+}
+
+TEST(DigishieldWalk, AllScryptChainTakesContiguousWindow)
+{
+    std::vector<int32_t> c(10, SCRYPT);
+    auto w = scrypt_window_ancestors(chain(c), c.size(), 4);
+    ASSERT_EQ(w.size(), 4u);
+    EXPECT_EQ(w, (std::vector<std::size_t>{0, 1, 2, 3}));
+}
+
+TEST(DigishieldWalk, SkipsInterleavedContinuityHeaders)
+{
+    // Mixed: S, sha, S, skein, S, odo, S  -> Scrypt at k = 0,2,4,6.
+    std::vector<int32_t> c{SCRYPT, SHA256D, SCRYPT, SKEIN, SCRYPT, ODO, SCRYPT};
+    auto w = scrypt_window_ancestors(chain(c), c.size(), 3);
+    ASSERT_EQ(w.size(), 3u);
+    EXPECT_EQ(w, (std::vector<std::size_t>{0, 2, 4}));  // continuity skipped
+}
+
+TEST(DigishieldWalk, LeadingContinuityRunIsSkipped)
+{
+    // Nearest headers are all non-Scrypt; first Scrypt sample is deep.
+    std::vector<int32_t> c{SHA256D, SKEIN, ODO, SCRYPT, SCRYPT};
+    auto w = scrypt_window_ancestors(chain(c), c.size(), 2);
+    ASSERT_EQ(w.size(), 2u);
+    EXPECT_EQ(w, (std::vector<std::size_t>{3, 4}));
+}
+
+TEST(DigishieldWalk, ExhaustedChainReturnsFewerThanWindow)
+{
+    // Only 2 Scrypt headers exist but the window wants 4 (early-chain region).
+    std::vector<int32_t> c{SCRYPT, SHA256D, SCRYPT, SHA256D};
+    auto w = scrypt_window_ancestors(chain(c), c.size(), 4);
+    ASSERT_EQ(w.size(), 2u);
+    EXPECT_EQ(w, (std::vector<std::size_t>{0, 2}));
+}
+
+TEST(DigishieldWalk, ZeroWindowIsEmpty)
+{
+    std::vector<int32_t> c(4, SCRYPT);
+    EXPECT_TRUE(scrypt_window_ancestors(chain(c), c.size(), 0).empty());
+}