dgb(#82 4b/4c): embedded nonce grinder over the scrypt_pow.hpp SSOT

grind_won_nonce(header80, target) increments the 80-byte header nonce
[76..79] LE until scrypt_pow_hash(header) <= target -- the EXACT
header_chain.hpp satisfaction gate -- calling THROUGH the #286 digest
CALL SSOT (never a bypass hash), so a nonce it accepts is one node B
ACCEPTs. This is the missing primitive between the faithful won-block
reconstruction and a ProcessNewBlock ACCEPT: the leg-2 A/B delivery
proof reached node B but was consensus-rejected high-hash precisely
because the forced-won seam carried no real PoW.

Fails closed: returns nullopt when no nonce satisfies inside the budget
(or the full 2^32 space wraps) -- a header that does not satisfy its
target is never broadcast, mirroring the reconstructor loud-throw.

dgb_nonce_grinder_test (5/5): finds a satisfying nonce well inside
budget, the winning header satisfies the gate and its reported digest
== the SSOT digest, the winning nonce is written LE into [76..79],
re-grinding from the winner succeeds on iter 1, and an unsatisfiable
target exhausts the budget to nullopt. Reuses the _dgb_scrypt_tus
real-scrypt set; header-only u256, no core / no dgb OBJECT lib. Added
to both build.yml --target allowlists. Fenced src/impl/dgb/ + build.yml.

Wiring grind -> reconstruct -> submit on the live forced-won path and
the node-B ACCEPT gate proof are the explicitly-next integration slice.

Author: frstrtr

.github/workflows/build.yml

@@ -84,7 +84,7 @@ jobs:
                     dgb_gentx_coinbase_test nmc_auxpow_merkle_test nmc_template_builder_test nmc_auxpow_wire_test nmc_reconstruct_won_block_test dgb_gentx_share_path_test dgb_other_tx_resolver_test \
                     dgb_other_tx_assembler_test dgb_reconstruct_won_block_test dgb_reconstruct_closure_test dgb_gentx_unpack_test dgb_work_source_test dgb_template_builder_test dgb_embedded_coin_node_test dgb_embedded_tx_select_test dgb_coinbase_value_parity_test \
                     rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test header_chain_test \
-                    dgb_coin_node_seam_test dgb_block_broadcast_test dgb_won_block_dispatch_test dgb_forced_won_share_dualpath_test dgb_scrypt_pow_test \
+                    dgb_coin_node_seam_test dgb_block_broadcast_test dgb_won_block_dispatch_test dgb_forced_won_share_dualpath_test dgb_scrypt_pow_test dgb_nonce_grinder_test \
                     v37_test \
             -j$(nproc)
 
@@ -217,7 +217,7 @@ jobs:
                     dgb_gentx_coinbase_test nmc_auxpow_merkle_test nmc_template_builder_test nmc_auxpow_wire_test nmc_reconstruct_won_block_test dgb_gentx_share_path_test dgb_other_tx_resolver_test \
                     dgb_other_tx_assembler_test dgb_reconstruct_won_block_test dgb_reconstruct_closure_test dgb_gentx_unpack_test dgb_work_source_test dgb_template_builder_test dgb_embedded_coin_node_test dgb_embedded_tx_select_test dgb_coinbase_value_parity_test \
                     rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test header_chain_test \
-                    dgb_coin_node_seam_test dgb_block_broadcast_test dgb_won_block_dispatch_test dgb_forced_won_share_dualpath_test dgb_scrypt_pow_test \
+                    dgb_coin_node_seam_test dgb_block_broadcast_test dgb_won_block_dispatch_test dgb_forced_won_share_dualpath_test dgb_scrypt_pow_test dgb_nonce_grinder_test \
                     test_coin_broadcaster test_multiaddress_pplns test_pplns_stress \
                     v37_test \
             -j$(nproc)

src/impl/dgb/coin/nonce_grinder.hpp

@@ -0,0 +1,99 @@
+#pragma once
+// ---------------------------------------------------------------------------
+// dgb::coin::grind_won_nonce -- the embedded real work-gen nonce grinder
+// (#82 Stage 4b/4c). Given a reconstructed 80-byte DigiByte block header and
+// the parent target, it increments the header nonce until the DGB-Scrypt PoW
+// digest satisfies the target, returning the winning nonce. This is the
+// missing primitive between the faithful won-block RECONSTRUCTION (#82 leg-2,
+// reconstruct_won_block.hpp) and a node-B ProcessNewBlock ACCEPT: the A/B
+// delivery proof reached node B but was consensus-rejected "high-hash, proof
+// of work failed" precisely because the forced-won seam carried no real PoW.
+// The grinder closes that gap.
+//
+// SSOT call-through: the hash is computed ONLY via scrypt_pow_hash (the #286
+// digest CALL SSOT), never a private/bypass routine -- so a nonce this grinder
+// accepts is, by construction, a nonce node B's own Scrypt validation accepts.
+// The comparison is the EXACT satisfaction gate coin/header_chain.hpp runs:
+// pow_hash <= target (inclusive), MSB-first via u256::operator>.
+//
+// Nonce placement: the canonical bitcoin/DigiByte 80-byte header is
+// version(4)|prev(32)|merkle(32)|time(4)|bits(4)|nonce(4) -- the nonce is the
+// LAST field, bytes [76..79], little-endian. This is the identical layout
+// pack(BlockHeaderType) emits (header_sample_build.hpp serializes the header
+// once and feeds the SAME bytes to sha256d AND scrypt), so a header serialized
+// at the ingest/reconstruct boundary and ground here agree byte-for-byte.
+//
+// Standalone-guard discipline: header-only, depends ONLY on scrypt_pow.hpp
+// (which pulls real btclibs scrypt + the header-only u256). No core, no dgb
+// OBJECT lib -- the same no-link constraint dgb_arith256.hpp / scrypt_pow.hpp
+// keep, so its guard TU links the _dgb_scrypt_tus real-scrypt set, not a
+// synthetic hash. Wiring grind -> reconstruct -> submit onto the live
+// forced-won path (serialize BlockHeaderType, grind, write the winning nonce
+// back) is the explicitly-next integration slice; this is the pure primitive.
+//
+// Per-coin isolation: src/impl/dgb/ only. p2pool-merged-v36 surface: NONE --
+// DGB-Scrypt is a STANDALONE parent; no share format, coinbase commitment, or
+// PPLNS math is touched.
+// ---------------------------------------------------------------------------
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+
+#include <impl/dgb/coin/scrypt_pow.hpp>     // scrypt_pow_hash (PoW digest SSOT, #286)
+#include <impl/dgb/coin/dgb_arith256.hpp>   // dgb::coin::u256 (also via scrypt_pow.hpp)
+
+namespace dgb::coin {
+
+// Byte offset of the 4-byte little-endian nonce in the canonical 80-byte header.
+inline constexpr std::size_t kHeaderNonceOffset = 76;
+
+// Write a 32-bit nonce little-endian into header[76..79] (consensus byte order).
+inline void put_header_nonce_le(std::array<unsigned char, 80>& header, uint32_t nonce) {
+    header[kHeaderNonceOffset + 0] = static_cast<unsigned char>(nonce & 0xffu);
+    header[kHeaderNonceOffset + 1] = static_cast<unsigned char>((nonce >> 8) & 0xffu);
+    header[kHeaderNonceOffset + 2] = static_cast<unsigned char>((nonce >> 16) & 0xffu);
+    header[kHeaderNonceOffset + 3] = static_cast<unsigned char>((nonce >> 24) & 0xffu);
+}
+
+struct GrindOutcome {
+    uint32_t nonce;     // winning nonce -- also left written into header[76..79]
+    u256     pow_hash;  // scrypt_pow_hash of the winning header (<= target)
+    uint64_t iters;     // nonces tried, 1-based -- the search budget consumed
+};
+
+// Grind header[76..79] from start_nonce until scrypt_pow_hash(header) <= target.
+//
+//   header      : the reconstructed 80-byte header; on success its nonce field
+//                 is left set to the winning value (caller broadcasts THIS blob)
+//   target      : compact_to_target(nBits) for the parent -- the SAME u256 the
+//                 satisfaction gate compares pow_hash against
+//   start_nonce : where to begin the search (default 0)
+//   max_iters   : search budget. Regtest powLimit is trivially easy, so the live
+//                 forced-won path satisfies in very few iters; this is the guard
+//                 that the grinder TERMINATES (no infinite loop), not an expected
+//                 ceiling. Defaults to the full 2^32 nonce space.
+//
+// Returns the winning {nonce, pow_hash, iters} on success, or std::nullopt if
+// the budget (or the full 2^32 space) is exhausted with no satisfying nonce.
+// "No nonce found in budget" is a hard failure the caller MUST NOT broadcast a
+// header for -- failing closed mirrors the reconstructor's loud-throw posture:
+// a header that does not satisfy its target is rejected by the daemon anyway.
+inline std::optional<GrindOutcome>
+grind_won_nonce(std::array<unsigned char, 80>& header, const u256& target,
+                uint32_t start_nonce = 0,
+                uint64_t max_iters = (uint64_t{1} << 32)) {
+    uint32_t nonce = start_nonce;
+    for (uint64_t tried = 1; tried <= max_iters; ++tried) {
+        put_header_nonce_le(header, nonce);
+        u256 pow = scrypt_pow_hash(header);
+        if (!(pow > target))                 // pow <= target -> valid PoW (inclusive)
+            return GrindOutcome{nonce, pow, tried};
+        ++nonce;
+        if (nonce == start_nonce) break;     // wrapped full 2^32 space, none satisfied
+    }
+    return std::nullopt;
+}
+
+}  // namespace dgb::coin

src/impl/dgb/test/CMakeLists.txt

@@ -355,4 +355,20 @@ if (BUILD_TESTING AND GTest_FOUND)
     target_link_libraries(dgb_scrypt_pow_test PRIVATE
         GTest::gtest_main GTest::gtest)
     gtest_add_tests(dgb_scrypt_pow_test "" AUTO)
+
+    # --- Stage 4b/4c: DGB-Scrypt nonce grinder (coin/nonce_grinder.hpp) -------
+    # Pins grind_won_nonce: increments the 80-byte header nonce until
+    # scrypt_pow_hash(header) <= target (the EXACT header_chain.hpp satisfaction
+    # gate), calling THROUGH the #286 scrypt_pow.hpp digest SSOT -- never a
+    # bypass hash -- so the nonce it finds is one node B accepts. Asserts it
+    # terminates well inside the test budget, writes the winning nonce LE into
+    # [76..79], and fails closed (nullopt) when no nonce satisfies in budget.
+    # Reuses the SAME _dgb_scrypt_tus real-scrypt set as dgb_scrypt_pow_test --
+    # header-only u256, no core / no dgb OBJECT lib. Same standalone-guard
+    # discipline; MUST stay in BOTH build.yml --target allowlists (#143 trap).
+    add_executable(dgb_nonce_grinder_test nonce_grinder_test.cpp ${_dgb_scrypt_tus})
+    target_include_directories(dgb_nonce_grinder_test PRIVATE ${CMAKE_SOURCE_DIR}/src/btclibs)
+    target_link_libraries(dgb_nonce_grinder_test PRIVATE
+        GTest::gtest_main GTest::gtest)
+    gtest_add_tests(dgb_nonce_grinder_test "" AUTO)
 endif()

src/impl/dgb/test/nonce_grinder_test.cpp

@@ -0,0 +1,113 @@
+// DGB nonce grinder guard (coin/nonce_grinder.hpp) -- #82 Stage 4b/4c.
+//
+// Proves the embedded real work-gen primitive: grind_won_nonce increments the
+// header nonce until the DGB-Scrypt PoW digest satisfies the target, computing
+// the hash ONLY through scrypt_pow_hash (the #286 digest CALL SSOT) and using
+// the EXACT satisfaction comparison coin/header_chain.hpp runs (pow_hash <=
+// target). The nonce it returns is therefore the nonce node B's own Scrypt
+// validation accepts -- this is the unit floor under the live tip-extension
+// (ProcessNewBlock ACCEPT) integration test.
+//
+// Real scrypt (the _dgb_scrypt_tus set), header-only u256 -- the same no-core /
+// no-OBJECT-lib standalone-guard discipline as scrypt_pow_test / dgb_arith256.
+
+#include <array>
+#include <cstdint>
+#include <optional>
+
+#include <gtest/gtest.h>
+
+#include <impl/dgb/coin/nonce_grinder.hpp>
+#include <impl/dgb/coin/scrypt_pow.hpp>
+
+using dgb::coin::u256;
+using dgb::coin::grind_won_nonce;
+using dgb::coin::scrypt_pow_hash;
+using dgb::coin::kHeaderNonceOffset;
+
+namespace {
+
+// Arbitrary fixed 76-byte header prefix; the grinder owns bytes [76..79].
+std::array<unsigned char, 80> base_header() {
+    std::array<unsigned char, 80> h{};
+    for (int i = 0; i < 80; ++i) h[i] = static_cast<unsigned char>((i * 13 + 5) % 251);
+    return h;
+}
+
+uint32_t read_nonce_le(const std::array<unsigned char, 80>& h) {
+    return  (uint32_t)h[kHeaderNonceOffset + 0]
+         | ((uint32_t)h[kHeaderNonceOffset + 1] << 8)
+         | ((uint32_t)h[kHeaderNonceOffset + 2] << 16)
+         | ((uint32_t)h[kHeaderNonceOffset + 3] << 24);
+}
+
+// Target accepting ~1/4 of uniform digests: top two bits of the MS limb zero
+// (pow.limb[3] <= 0x3fff... with all lower limbs maxed). Expected ~4 iters, so
+// termination "well inside the test budget" is overwhelming; max_iters is the
+// hard ceiling, not the expected cost.
+u256 easy_quarter_target() {
+    u256 t;
+    t.limb[0] = 0xffffffffffffffffULL;
+    t.limb[1] = 0xffffffffffffffffULL;
+    t.limb[2] = 0xffffffffffffffffULL;
+    t.limb[3] = 0x3fffffffffffffffULL;
+    return t;
+}
+
+constexpr uint64_t kTestBudget = uint64_t{1} << 20;  // 1,048,576 vs ~4 expected
+
+// --- grinder finds a satisfying nonce, well inside budget -------------------
+TEST(DgbNonceGrinderKAT, FindsSatisfyingNonceWithinBudget) {
+    auto h = base_header();
+    auto out = grind_won_nonce(h, easy_quarter_target(), 0, kTestBudget);
+    ASSERT_TRUE(out.has_value());
+    EXPECT_GE(out->iters, uint64_t{1});
+    // P(iters > 200) = (3/4)^200 ~ 1e-25 -- terminates inside budget by construction.
+    EXPECT_LE(out->iters, uint64_t{200});
+}
+
+// --- the winning header actually satisfies the gate (pow <= target) ---------
+TEST(DgbNonceGrinderKAT, WinningHeaderSatisfiesTarget) {
+    auto h = base_header();
+    u256 target = easy_quarter_target();
+    auto out = grind_won_nonce(h, target, 0, kTestBudget);
+    ASSERT_TRUE(out.has_value());
+    // Recompute through the SAME #286 SSOT over the mutated header.
+    u256 pow = scrypt_pow_hash(h);
+    EXPECT_FALSE(pow > target);          // pow <= target -> valid PoW
+    EXPECT_TRUE(pow == out->pow_hash);   // reported digest == SSOT digest (no bypass)
+}
+
+// --- the winning nonce is left written into header[76..79], little-endian ----
+TEST(DgbNonceGrinderKAT, WritesWinningNonceLittleEndian) {
+    auto h = base_header();
+    auto out = grind_won_nonce(h, easy_quarter_target(), 0, kTestBudget);
+    ASSERT_TRUE(out.has_value());
+    EXPECT_EQ(read_nonce_le(h), out->nonce);
+}
+
+// --- determinism + start_nonce honored: re-grinding from the winner hits it
+//     on the first try (the found nonce truly satisfies AND start is respected).
+TEST(DgbNonceGrinderKAT, ReGrindFromWinnerSucceedsImmediately) {
+    auto h = base_header();
+    auto first = grind_won_nonce(h, easy_quarter_target(), 0, kTestBudget);
+    ASSERT_TRUE(first.has_value());
+    auto h2 = base_header();
+    auto again = grind_won_nonce(h2, easy_quarter_target(), first->nonce, kTestBudget);
+    ASSERT_TRUE(again.has_value());
+    EXPECT_EQ(again->nonce, first->nonce);
+    EXPECT_EQ(again->iters, uint64_t{1});  // satisfied on the first nonce tried
+}
+
+// --- fail-closed: an unsatisfiable target inside a small budget -> nullopt ----
+// target == 1 (limb[0]=1, rest 0): essentially no scrypt digest is <= 1, so the
+// grinder MUST exhaust the budget and return nullopt rather than loop forever.
+TEST(DgbNonceGrinderKAT, ReturnsNulloptWhenNoNonceInBudget) {
+    auto h = base_header();
+    u256 impossible;            // all-zero ...
+    impossible.limb[0] = 1;     // ... except 1 -> target = 1
+    auto out = grind_won_nonce(h, impossible, 0, /*max_iters=*/256);
+    EXPECT_FALSE(out.has_value());
+}
+
+}  // namespace