dgb(#82 gate): grind->reconstruct->submit JOINT (won_block_finalize.hpp)

The missing composition between leg-2's faithful won-block reconstruction
and a node-B ProcessNewBlock ACCEPT. finalize_won_block_pow takes a
reconstructed block (header[0..79] with merkle_root already set -- merkle
FIRST, integrator-pinned ordering) and grinds the nonce at [76..79] THROUGH
grind_won_nonce -> scrypt_pow_hash (the #286 digest CALL SSOT) until the
DGB-Scrypt PoW satisfies the parent target, splices the winning nonce back,
and regenerates the RPC-fallback hex in lockstep with the P2P-arm bytes.
This closes the "high-hash, proof of work failed" rejection: the forced-won
seam reached node B but carried no real PoW.

SSOT call-through, never a bypass hash -- a finalized block is by
construction one node B's own Scrypt validation accepts. Fail-closed
(nullopt) on sub-80-byte input or no-nonce-in-budget, mirroring
make_reconstruct_closure's never-a-partial-block posture.

Standalone-guard discipline: depends ONLY on nonce_grinder.hpp (real
btclibs scrypt + header-only u256); no core, no dgb OBJECT lib, no
util/HexStr (local lowercase encoder, byte-identical to HexStr). Test links
the SAME _dgb_scrypt_tus set as dgb_nonce_grinder_test.

+5 KATs (dgb_won_block_finalize_test, 5/5 green): finalized header
pow<=target via the same SSOT; winning nonce spliced LE into [76..79]; hex
== bytes; ONLY the 4 nonce bytes mutate (merkle + tx tail untouched);
fail-closed on a 79-byte input. Registered in BOTH build.yml --target
allowlists (#143 trap).

Fenced: src/impl/dgb/** + build.yml allowlist only. p2pool-merged-v36
surface: NONE. DGB-Scrypt standalone parent in the V36 default build.

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_nonce_grinder_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 dgb_won_block_finalize_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_nonce_grinder_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 dgb_won_block_finalize_test \
                     test_coin_broadcaster test_multiaddress_pplns test_pplns_stress \
                     v37_test \
             -j$(nproc)

src/impl/dgb/coin/won_block_finalize.hpp

@@ -0,0 +1,118 @@
+#pragma once
+// ---------------------------------------------------------------------------
+// dgb::coin::finalize_won_block_pow -- the grind->reconstruct->submit JOINT
+// (#82 gate). It is the missing composition between the faithful won-block
+// RECONSTRUCTION (reconstruct_won_block*.hpp, leg-2) and a node-B
+// ProcessNewBlock ACCEPT: the A/B delivery proof reached node B but was
+// consensus-rejected "high-hash, proof of work failed" because the forced-won
+// seam carried no real PoW. This seam grinds the reconstructed block's header
+// nonce until the DGB-Scrypt digest satisfies the parent target, then hands the
+// finalized {bytes, hex} to the existing dual-path broadcaster (P2P relay arm +
+// submitblock RPC fallback) unchanged.
+//
+// ORDERING (integrator-pinned, 2026-06-21): merkle_root is set FIRST (it is
+// already baked into bytes[36..67] by the reconstructor / assemble_won_block),
+// THEN the nonce at bytes[76..79] is ground -- scrypt hashes the full 80 bytes,
+// so grinding before the merkle was fixed would invalidate the found nonce.
+// This seam runs strictly AFTER reconstruction, so that invariant holds by
+// construction.
+//
+// Byte layout: the reconstructor frames the canonical block as
+//   header(80) | tx_count(CompactSize) | [gentx] ++ other_txs
+// where header = version(4)|prev(32)|merkle(32)|time(4)|bits(4)|nonce(4).
+// bytes[0..79] is therefore the exact 80-byte header node B re-hashes, and the
+// nonce is bytes[76..79] little-endian (== nonce_grinder.hpp kHeaderNonceOffset).
+//
+// SSOT call-through: the PoW is computed ONLY via grind_won_nonce ->
+// scrypt_pow_hash (the #286 digest CALL SSOT), the EXACT pow<=target gate
+// header_chain.hpp runs -- so a finalized block this seam emits is, by
+// construction, one node B's own Scrypt validation accepts.
+//
+// FAIL-CLOSED (mirrors make_reconstruct_closure): returns std::nullopt -- never
+// a partial/wrong block -- when the input is too short to frame a header or no
+// satisfying nonce is found inside max_iters. A header that does not satisfy its
+// target is daemon-rejected anyway, so emitting nothing is strictly safer.
+//
+// Standalone-guard discipline: depends ONLY on nonce_grinder.hpp (real btclibs
+// scrypt + header-only u256). NO core, NO dgb OBJECT lib, NO util/HexStr -- the
+// RPC-fallback hex is regenerated with a local lowercase encoder byte-identical
+// to HexStr, so the seam (and its KAT) link exactly like the grinder. Operates
+// on raw {bytes} so it pulls none of the block_assembly/reconstruct include set.
+//
+// Per-coin isolation: src/impl/dgb/ only. p2pool-merged-v36 surface: NONE.
+// DGB-Scrypt is a STANDALONE parent in the V36 default build.
+// ---------------------------------------------------------------------------
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include <impl/dgb/coin/nonce_grinder.hpp>   // grind_won_nonce, GrindOutcome, u256, kHeaderNonceOffset
+
+namespace dgb::coin {
+
+// A reconstructed parent block whose header nonce now satisfies the parent
+// target -- ready for the dual-path broadcaster:
+//   bytes : the blob the embedded P2P relay sends
+//   hex   : the same block for the external submitblock (RPC) fallback
+//   grind : the winning nonce + its pow_hash + iteration count (audit trail)
+struct FinalizedWonBlock {
+    std::vector<unsigned char> bytes;
+    std::string                hex;
+    GrindOutcome               grind;
+};
+
+// Lowercase hex, byte-identical to bitcoin util HexStr -- kept local so this
+// seam stays in the grinder's no-core / no-util standalone lineage.
+inline std::string finalize_block_to_hex(const std::vector<unsigned char>& v) {
+    static constexpr char kHex[] = "0123456789abcdef";
+    std::string s;
+    s.reserve(v.size() * 2);
+    for (unsigned char b : v) {
+        s.push_back(kHex[(b >> 4) & 0xf]);
+        s.push_back(kHex[b & 0xf]);
+    }
+    return s;
+}
+
+// Grind the reconstructed block to a node-acceptable PoW.
+//
+//   block_bytes : a fully reconstructed block (header at [0..79], merkle_root
+//                 ALREADY set); the seam owns header[76..79] only.
+//   target      : compact_to_target(nBits) for the parent -- the SAME u256
+//                 header_chain.hpp / the grinder KAT compare against.
+//   start_nonce / max_iters : forwarded to grind_won_nonce.
+//
+// Returns {bytes, hex, grind} with hex == finalize_block_to_hex(bytes) and the
+// winning nonce spliced into bytes[76..79] LE. Returns std::nullopt (fail-
+// closed) if block_bytes is too short to frame an 80-byte header or no nonce
+// satisfies the target within max_iters.
+inline std::optional<FinalizedWonBlock>
+finalize_won_block_pow(std::vector<unsigned char> block_bytes, const u256& target,
+                       uint32_t start_nonce = 0,
+                       uint64_t max_iters = (uint64_t{1} << 32))
+{
+    if (block_bytes.size() < 80)
+        return std::nullopt;   // too short to frame a header -> fail closed
+
+    std::array<unsigned char, 80> header{};
+    std::copy(block_bytes.begin(), block_bytes.begin() + 80, header.begin());
+
+    auto out = grind_won_nonce(header, target, start_nonce, max_iters);
+    if (!out.has_value())
+        return std::nullopt;   // no satisfying nonce in budget -> fail closed
+
+    // Splice the winning nonce (grinder wrote it LE into header[76..79]) back
+    // into the block; only the 4 nonce bytes change, every tx byte is untouched.
+    std::copy(header.begin() + kHeaderNonceOffset, header.begin() + 80,
+              block_bytes.begin() + kHeaderNonceOffset);
+
+    std::string hex = finalize_block_to_hex(block_bytes);
+    return FinalizedWonBlock{std::move(block_bytes), std::move(hex), *out};
+}
+
+}  // namespace dgb::coin

src/impl/dgb/test/CMakeLists.txt

@@ -371,4 +371,23 @@ if (BUILD_TESTING AND GTest_FOUND)
     target_link_libraries(dgb_nonce_grinder_test PRIVATE
         GTest::gtest_main GTest::gtest)
     gtest_add_tests(dgb_nonce_grinder_test "" AUTO)
+
+    # --- #82 gate: grind->reconstruct->submit JOINT (coin/won_block_finalize.hpp)
+    # Pins finalize_won_block_pow: takes a faithfully reconstructed block (header
+    # at [0..79], merkle_root already set -- merkle FIRST) and grinds the nonce
+    # at [76..79] THROUGH grind_won_nonce -> scrypt_pow_hash (#286 SSOT) until the
+    # DGB-Scrypt PoW satisfies the parent target, splicing the winning nonce back
+    # and regenerating the RPC-fallback hex in lockstep with the P2P-arm bytes.
+    # Asserts: finalized header pow<=target via the same SSOT; nonce spliced LE
+    # into [76..79]; hex == bytes; ONLY the 4 nonce bytes mutate (merkle + tx tail
+    # untouched); fail-closed (nullopt) on a sub-80-byte input. Reuses the SAME
+    # _dgb_scrypt_tus real-scrypt set as dgb_nonce_grinder_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_won_block_finalize_test won_block_finalize_test.cpp ${_dgb_scrypt_tus})
+    target_include_directories(dgb_won_block_finalize_test PRIVATE ${CMAKE_SOURCE_DIR}/src/btclibs)
+    target_link_libraries(dgb_won_block_finalize_test PRIVATE
+        GTest::gtest_main GTest::gtest)
+    gtest_add_tests(dgb_won_block_finalize_test "" AUTO)
+
 endif()

src/impl/dgb/test/won_block_finalize_test.cpp

@@ -0,0 +1,124 @@
+// DGB won-block finalize joint (coin/won_block_finalize.hpp) -- #82 gate.
+//
+// Pins finalize_won_block_pow: the grind->reconstruct->submit composition that
+// turns a faithfully RECONSTRUCTED parent block (header[0..79] with merkle_root
+// already set; merkle FIRST, integrator-pinned ordering) into one whose header
+// nonce satisfies the parent target -- the missing link between leg-2's
+// reconstruction and a node-B ProcessNewBlock ACCEPT. The PoW is computed ONLY
+// through grind_won_nonce -> scrypt_pow_hash (the #286 digest CALL SSOT), so a
+// finalized block is, by construction, one node B's own Scrypt validation
+// accepts. This is the unit floor directly under the live tip-extension gate.
+//
+// Real scrypt (the _dgb_scrypt_tus set), header-only u256 -- the same no-core /
+// no-OBJECT-lib standalone-guard discipline as nonce_grinder_test / scrypt_pow_test.
+
+#include <algorithm>
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include <gtest/gtest.h>
+
+#include <impl/dgb/coin/won_block_finalize.hpp>
+#include <impl/dgb/coin/nonce_grinder.hpp>
+#include <impl/dgb/coin/scrypt_pow.hpp>
+
+using dgb::coin::u256;
+using dgb::coin::scrypt_pow_hash;
+using dgb::coin::kHeaderNonceOffset;
+using dgb::coin::finalize_won_block_pow;
+using dgb::coin::finalize_block_to_hex;
+
+namespace {
+
+// A synthetic reconstructed block: a deterministic 80-byte header (merkle_root
+// already baked in -- finalize never touches it) followed by a short tx tail
+// standing in for tx_count|[gentx]++other_txs. finalize owns header[76..79] only.
+std::vector<unsigned char> synthetic_block(std::size_t tail_len = 37) {
+    std::vector<unsigned char> b;
+    b.reserve(80 + tail_len);
+    for (int i = 0; i < 80; ++i)
+        b.push_back(static_cast<unsigned char>((i * 13 + 5) % 251));
+    for (std::size_t i = 0; i < tail_len; ++i)
+        b.push_back(static_cast<unsigned char>((i * 7 + 3) % 256));
+    return b;
+}
+
+// Target accepting ~1/4 of uniform digests (same shape as nonce_grinder_test):
+// terminates in ~4 iters, so the budget below is never a factor.
+u256 easy_quarter_target() {
+    u256 t;
+    t.limb[0] = 0xffffffffffffffffULL;
+    t.limb[1] = 0xffffffffffffffffULL;
+    t.limb[2] = 0xffffffffffffffffULL;
+    t.limb[3] = 0x3fffffffffffffffULL;
+    return t;
+}
+
+// The 80-byte header sitting at the front of a (finalized) block.
+std::array<unsigned char, 80> header_of(const std::vector<unsigned char>& block) {
+    std::array<unsigned char, 80> h{};
+    std::copy(block.begin(), block.begin() + 80, h.begin());
+    return h;
+}
+
+uint32_t read_nonce_le(const std::vector<unsigned char>& block) {
+    return  (uint32_t)block[kHeaderNonceOffset + 0]
+         | ((uint32_t)block[kHeaderNonceOffset + 1] << 8)
+         | ((uint32_t)block[kHeaderNonceOffset + 2] << 16)
+         | ((uint32_t)block[kHeaderNonceOffset + 3] << 24);
+}
+
+constexpr uint64_t kTestBudget = uint64_t{1} << 20;  // vs ~4 expected
+
+// --- finalize yields a block whose header satisfies the parent target -------
+TEST(DgbWonBlockFinalizeKAT, FinalizesToSatisfyingPoW) {
+    u256 target = easy_quarter_target();
+    auto out = finalize_won_block_pow(synthetic_block(), target, 0, kTestBudget);
+    ASSERT_TRUE(out.has_value());
+    // Re-hash the finalized header through the SAME #286 SSOT.
+    u256 pow = scrypt_pow_hash(header_of(out->bytes));
+    EXPECT_FALSE(pow > target);                  // pow <= target -> valid PoW
+    EXPECT_TRUE(pow == out->grind.pow_hash);     // reported digest == SSOT (no bypass)
+    EXPECT_GE(out->grind.iters, uint64_t{1});
+}
+
+// --- the winning nonce is spliced into block bytes[76..79] little-endian ----
+TEST(DgbWonBlockFinalizeKAT, SplicesWinningNonceLittleEndian) {
+    auto out = finalize_won_block_pow(synthetic_block(), easy_quarter_target(), 0, kTestBudget);
+    ASSERT_TRUE(out.has_value());
+    EXPECT_EQ(read_nonce_le(out->bytes), out->grind.nonce);
+}
+
+// --- RPC-fallback hex stays in lockstep with the P2P-arm bytes --------------
+TEST(DgbWonBlockFinalizeKAT, HexMatchesFinalizedBytes) {
+    auto out = finalize_won_block_pow(synthetic_block(), easy_quarter_target(), 0, kTestBudget);
+    ASSERT_TRUE(out.has_value());
+    EXPECT_EQ(out->hex.size(), out->bytes.size() * 2);
+    EXPECT_EQ(out->hex, finalize_block_to_hex(out->bytes));
+}
+
+// --- ONLY the 4 nonce bytes change: merkle_root + every tx byte untouched ---
+TEST(DgbWonBlockFinalizeKAT, OnlyNonceBytesMutated) {
+    auto in = synthetic_block();
+    auto out = finalize_won_block_pow(in, easy_quarter_target(), 0, kTestBudget);
+    ASSERT_TRUE(out.has_value());
+    ASSERT_EQ(out->bytes.size(), in.size());
+    // header[0..75] (version|prev|merkle|time|bits) identical.
+    for (std::size_t i = 0; i < kHeaderNonceOffset; ++i)
+        EXPECT_EQ(out->bytes[i], in[i]) << "prefix byte " << i << " changed";
+    // tx tail [80..] identical.
+    for (std::size_t i = 80; i < in.size(); ++i)
+        EXPECT_EQ(out->bytes[i], in[i]) << "tail byte " << i << " changed";
+}
+
+// --- fail-closed: too short to frame an 80-byte header -> nullopt -----------
+TEST(DgbWonBlockFinalizeKAT, FailsClosedOnShortInput) {
+    std::vector<unsigned char> shortb(79, 0x11);
+    auto out = finalize_won_block_pow(shortb, easy_quarter_target(), 0, kTestBudget);
+    EXPECT_FALSE(out.has_value());
+}
+
+}  // namespace