dgb(#82 4b/4c): scrypt_pow.hpp digest CALL SSOT + satisfaction-gate KAT

Land the foundational slice of embedded real work-gen: coin/scrypt_pow.hpp
wraps btclibs scrypt_1024_1_1_256(80-byte header) and decodes the 32-byte
digest via the existing u256::from_le_bytes (dgb_arith256.hpp), closing the
documented "the scrypt CALL itself lands at the ingest boundary in a
following slice" TODO. Single SSOT so the nonce grinder (next slice) and the
header_chain ingest boundary can never disagree on PoW byte order.

V36 Scrypt-only: this is the ONLY PoW digest DGB validates; the other four
algos are accept-by-continuity and never reach here.

dgb_scrypt_pow_test (5/5): pins the digest bytes over a fixed header (vector
captured from btclibs scrypt itself, the DGB-Scrypt algo SSOT) and proves the
little-endian decode compares correctly against SetCompact-shaped targets the
way header_chain.hpp satisfaction gate does (pow_hash <= target, MSB-first).
Reuses header_chain_test scrypt TU set (real scrypt, header-only u256, no core
/ no OBJECT lib). Registered in CMake + both build.yml --target allowlists.

End-to-end agreement with DigiByte Core is proven by the live node-B ACCEPT
integration test (4b/4c tip-extension bar), not this unit KAT.

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_coin_node_seam_test dgb_block_broadcast_test dgb_won_block_dispatch_test dgb_forced_won_share_dualpath_test dgb_scrypt_pow_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_coin_node_seam_test dgb_block_broadcast_test dgb_won_block_dispatch_test dgb_forced_won_share_dualpath_test dgb_scrypt_pow_test \
                     test_coin_broadcaster test_multiaddress_pplns test_pplns_stress \
                     v37_test \
             -j$(nproc)

src/impl/dgb/coin/scrypt_pow.hpp

@@ -0,0 +1,47 @@
+#pragma once
+// ---------------------------------------------------------------------------
+// DGB-Scrypt proof-of-work digest CALL  (M3 §7b / Stage 4b-4c work-gen).
+//
+// The satisfaction gate in coin/header_chain.hpp compares HeaderSample::pow_hash
+// (a coin/dgb_arith256.hpp u256) against the SetCompact target -- hash <= target.
+// dgb_arith256.hpp::u256::from_le_bytes already documents the decode convention
+// (the scrypt output is read little-endian, mirroring bitcoin UintToArith256),
+// and ends: "the scrypt CALL itself lands at the ingest boundary in a following
+// slice." THIS header is that call: the single place the DGB-Scrypt algo hash is
+// computed, so the embedded work-gen (nonce grinder) and the ingest boundary
+// share ONE digest SSOT and can never disagree on byte order.
+//
+// V36 is Scrypt-ONLY (project_v36_dgb_scrypt_only): this is the ONLY PoW digest
+// DGB validates. The other four DGB algos (SHA256d/Skein/Qubit/Odocrypt) are
+// accept-by-continuity and never reach this function.
+//
+// scrypt_1024_1_1_256 is the canonical pooler/ArtForz Scrypt(N=1024,r=1,p=1)
+// from btclibs (src/btclibs/crypto/scrypt.*), the SAME routine DigiByte Core /
+// Litecoin Core use for the Scrypt algo. It links transitively here via
+// core -> btclibs (target_link_libraries(core PUBLIC ... btclibs)).
+// ---------------------------------------------------------------------------
+
+#include <array>
+#include <cstdint>
+
+#include <btclibs/crypto/scrypt.h>   // scrypt_1024_1_1_256
+#include <impl/dgb/coin/dgb_arith256.hpp>  // dgb::coin::u256
+
+namespace dgb::coin {
+
+// scrypt_1024_1_1_256 over the 80-byte serialized block header -> pow_hash u256.
+// The 32-byte digest is decoded little-endian (from_le_bytes) so the result
+// drops straight into the header_chain satisfaction gate with no reshape.
+inline u256 scrypt_pow_hash(const unsigned char header80[80]) {
+    char digest[32];
+    scrypt_1024_1_1_256(reinterpret_cast<const char*>(header80), digest);
+    return u256::from_le_bytes(reinterpret_cast<const unsigned char*>(digest));
+}
+
+// std::array convenience overload (the form the reconstructed-header builder and
+// the nonce grinder carry the 80 header bytes in).
+inline u256 scrypt_pow_hash(const std::array<unsigned char, 80>& header80) {
+    return scrypt_pow_hash(header80.data());
+}
+
+}  // namespace dgb::coin

src/impl/dgb/test/CMakeLists.txt

@@ -342,4 +342,17 @@ if (BUILD_TESTING AND GTest_FOUND)
     target_link_libraries(header_chain_test PRIVATE
         GTest::gtest_main GTest::gtest nlohmann_json::nlohmann_json)
     gtest_add_tests(header_chain_test "" AUTO)
+
+    # --- Stage 4b/4c: DGB-Scrypt PoW digest CALL (coin/scrypt_pow.hpp) --------
+    # Pins scrypt_pow_hash = scrypt_1024_1_1_256(80-byte header) decoded via
+    # u256::from_le_bytes, plus the satisfaction-gate byte order (pow_hash <=
+    # target) header_chain.hpp compares. Reuses the SAME _dgb_scrypt_tus set as
+    # header_chain_test (real scrypt, not synthetic) -- header-only u256, no core
+    # / no dgb OBJECT lib, the standalone-guard discipline dgb_arith256.hpp keeps.
+    # Same target name, so it stays in BOTH build.yml --target allowlists.
+    add_executable(dgb_scrypt_pow_test scrypt_pow_test.cpp ${_dgb_scrypt_tus})
+    target_include_directories(dgb_scrypt_pow_test PRIVATE ${CMAKE_SOURCE_DIR}/src/btclibs)
+    target_link_libraries(dgb_scrypt_pow_test PRIVATE
+        GTest::gtest_main GTest::gtest)
+    gtest_add_tests(dgb_scrypt_pow_test "" AUTO)
 endif()

src/impl/dgb/test/scrypt_pow_test.cpp

@@ -0,0 +1,81 @@
+// DGB-Scrypt PoW digest CALL guard (coin/scrypt_pow.hpp) -- Stage 4b/4c.
+//
+// Pins (1) the scrypt_1024_1_1_256 digest bytes over a fixed 80-byte header and
+// (2) that the little-endian u256 decode compares correctly against SetCompact-
+// shaped targets the way the coin/header_chain.hpp satisfaction gate does
+// (pow_hash <= target == valid PoW). The byte order proven here is exactly what
+// the embedded nonce grinder must satisfy for node B to ACCEPT a reconstructed
+// block, so this is the unit floor under the live tip-extension test.
+//
+// The digest vector is pinned from btclibs scrypt_1024_1_1_256 itself (the DGB-
+// Scrypt algo SSOT, same routine as DigiByte Core); end-to-end agreement with
+// DigiByte Core is proven by the live node-B ACCEPT integration test, not here.
+
+#include <array>
+#include <gtest/gtest.h>
+
+#include <impl/dgb/coin/scrypt_pow.hpp>
+
+using dgb::coin::u256;
+using dgb::coin::scrypt_pow_hash;
+
+namespace {
+
+// Deterministic 80-byte header: byte i = (i*7+1) mod 251. Arbitrary content but
+// fixed; the conversion + comparison proof does not depend on header semantics.
+std::array<unsigned char, 80> fixed_header() {
+    std::array<unsigned char, 80> h{};
+    for (int i = 0; i < 80; ++i) h[i] = static_cast<unsigned char>((i * 7 + 1) % 251);
+    return h;
+}
+
+// scrypt_1024_1_1_256(fixed_header) little-endian u256 limbs (limb[0] = LSB),
+// captured from btclibs. digest LE-in-memory:
+//   632b7c4db1da77a9683731a4a7a97761a2f600f66a1af420919a3aa0d4869a6c
+constexpr uint64_t L0 = 0xa977dab14d7c2b63ULL;
+constexpr uint64_t L1 = 0x6177a9a7a4313768ULL;
+constexpr uint64_t L2 = 0x20f41a6af600f6a2ULL;
+constexpr uint64_t L3 = 0x6c9a86d4a03a9a91ULL;
+
+u256 expected_pow() {
+    u256 r;
+    r.limb[0] = L0; r.limb[1] = L1; r.limb[2] = L2; r.limb[3] = L3;
+    return r;
+}
+
+// --- KAT: the digest CALL is byte-exact ------------------------------------
+TEST(DgbScryptPowKAT, DigestMatchesPinnedVector) {
+    EXPECT_TRUE(scrypt_pow_hash(fixed_header()) == expected_pow());
+}
+
+// The pointer overload and the std::array overload are the same SSOT.
+TEST(DgbScryptPowKAT, PointerAndArrayOverloadsAgree) {
+    auto h = fixed_header();
+    EXPECT_TRUE(scrypt_pow_hash(h.data()) == scrypt_pow_hash(h));
+}
+
+// --- satisfaction-gate byte order (header_chain.hpp: pow_hash <= target) ----
+// A target one ULP above the digest in the MOST-significant limb accepts;
+// one ULP below rejects. This is the exact comparison header_chain runs, so it
+// proves from_le_bytes feeds the gate in the right (MSB-first compare) order.
+TEST(DgbScryptPowKAT, SatisfiesTargetJustAbove) {
+    u256 pow = scrypt_pow_hash(fixed_header());
+    u256 target_above = expected_pow();
+    target_above.limb[3] = L3 + 1;   // strictly greater
+    EXPECT_FALSE(pow > target_above); // pow <= target -> valid PoW
+}
+
+TEST(DgbScryptPowKAT, FailsTargetJustBelow) {
+    u256 pow = scrypt_pow_hash(fixed_header());
+    u256 target_below = expected_pow();
+    target_below.limb[3] = L3 - 1;   // strictly less
+    EXPECT_TRUE(pow > target_below);  // pow > target -> PoW failed (high-hash)
+}
+
+// Equal target is satisfied (hash <= target is inclusive).
+TEST(DgbScryptPowKAT, SatisfiesEqualTarget) {
+    u256 pow = scrypt_pow_hash(fixed_header());
+    EXPECT_FALSE(pow > expected_pow());
+}
+
+}  // namespace