dash(s8): WonBlockRelay embedded-P2P won-block relay framer + KATs (#432)

The framing half of the embedded-P2P broadcast leg of the dual-path
block-viability gate (the dashd-submitblock arm is already proven via the
launcher producer). Frames the standard Dash block-relay handshake the
DashBroadcaster fans out on a won block: inv(MSG_BLOCK,hash) announce ->
peer getdata -> full block message, with a pending-block book keyed by hash.

Pure + socket-free: the block hash is SUPPLIED by the consensus/producer
layer (the X11 header hash on the won-block path), not recomputed here, so
this leaf carries no consensus value. The decision to actually transmit a
real won block onto the live net (on_block_found -> announce -> live sockets)
stays in the operator-gated broadcaster_full keystone.

Header-only, single dash tree. 5/5 ctest green on Linux x86_64 (non-hollow).

Co-authored-by: frstrtr <frstrtr@users.noreply.github.com>

Author: frstrtr

.github/workflows/build.yml

@@ -72,7 +72,7 @@ jobs:
                     test_threading test_weights \
                     test_header_chain test_mempool test_template_builder \
                     test_doge_chain test_compact_blocks test_dash_x11_kat \
-                    test_dash_header_chain test_dash_block_replay test_dash_conformance test_dash_subsidy test_dash_mempool test_dash_simplifiedmns test_dash_quorum test_dash_quorum_root test_dash_mn_state test_dash_embedded_gbt test_dash_smldiff test_dash_p2p_messages test_dash_p2p_connection test_dash_p2p_node test_dash_node_interface test_dash_config test_dash_broadcaster test_dash_share_hash_link \
+                    test_dash_header_chain test_dash_block_replay test_dash_conformance test_dash_subsidy test_dash_mempool test_dash_simplifiedmns test_dash_quorum test_dash_quorum_root test_dash_mn_state test_dash_embedded_gbt test_dash_smldiff test_dash_p2p_messages test_dash_p2p_connection test_dash_p2p_node test_dash_node_interface test_dash_config test_dash_broadcaster test_dash_share_hash_link test_dash_block_relay \
                     test_multiaddress_pplns test_pplns_stress \
                     test_hash_link test_decay_pplns \
                     test_pplns_consensus \
@@ -205,7 +205,7 @@ jobs:
                     test_threading test_weights \
                     test_header_chain test_mempool test_template_builder \
                     test_doge_chain test_compact_blocks test_dash_x11_kat \
-                    test_dash_header_chain test_dash_block_replay test_dash_conformance test_dash_subsidy test_dash_mempool test_dash_simplifiedmns test_dash_quorum test_dash_quorum_root test_dash_mn_state test_dash_embedded_gbt test_dash_smldiff test_dash_p2p_messages test_dash_p2p_connection test_dash_p2p_node test_dash_node_interface test_dash_config test_dash_broadcaster test_dash_share_hash_link \
+                    test_dash_header_chain test_dash_block_replay test_dash_conformance test_dash_subsidy test_dash_mempool test_dash_simplifiedmns test_dash_quorum test_dash_quorum_root test_dash_mn_state test_dash_embedded_gbt test_dash_smldiff test_dash_p2p_messages test_dash_p2p_connection test_dash_p2p_node test_dash_node_interface test_dash_config test_dash_broadcaster test_dash_share_hash_link test_dash_block_relay \
                     test_hash_link test_decay_pplns \
                     test_pplns_consensus \
                     test_v36_script_sorting test_v36_cross_impl_refhash \

src/impl/dash/block_relay.hpp

@@ -0,0 +1,89 @@
+#pragma once
+
+// Phase S8 — WonBlockRelay: embedded-P2P won-block relay framer (LEAF).
+//
+// This is the framing half of the embedded-P2P broadcast leg of the dual-path
+// block-viability gate. The OTHER arm (won block -> dashd submitblock RPC) is
+// already proven (the launcher producer, regtest crossing). When DASH wins a
+// block, the embedded path must also fan it out to the parent-chain (dashd)
+// peers the DashBroadcaster pool holds. Dash/Bitcoin block relay is a two-step
+// handshake, not a raw push:
+//
+//     [we win a block]
+//        -> announce  : send `inv(MSG_BLOCK, hash)` to every live peer
+//     [peer]  -> getdata(MSG_BLOCK, hash)
+//        -> on_getdata_block : answer with the full `block` message
+//
+// This LEAF is the PURE, socket-free framer + pending-block book for exactly
+// that handshake:
+//
+//   * announce(hash, block)      -> the `inv` RawMessage to fan out, and
+//                                   records the block under `hash` so a later
+//                                   getdata can be answered.
+//   * on_getdata_block(hash)     -> the full `block` RawMessage if known, else
+//                                   nullptr (we never serve a block we did not
+//                                   announce).
+//   * knows / pending / forget / clear — the pending-block bookkeeping.
+//
+// SCOPE / NON-CONSENSUS: the block hash is SUPPLIED by the consensus/producer
+// layer (the X11 header hash already computed on the won-block path) — it is
+// NOT recomputed here, so this leaf carries no consensus value and cannot
+// silently diverge a hash. The DECISION to actually transmit a REAL won block
+// onto the live network — wiring on_block_found -> announce -> the live slots'
+// sockets — stays in the operator-gated broadcaster_full keystone. This leaf
+// only builds the wire frames and answers getdata deterministically, so it is
+// unit-testable with zero sockets and zero live dashd, like its sibling leaves
+// (broadcaster.hpp, p2p_messages.hpp). Header-only, single dash tree.
+
+#include "coin/p2p_messages.hpp"
+#include "coin/block.hpp"
+
+#include <core/message.hpp>
+#include <core/uint256.hpp>
+
+#include <map>
+#include <memory>
+#include <vector>
+
+namespace dash
+{
+
+// Won-block relay framer + pending-block book. Non-consensus, socket-free.
+class WonBlockRelay
+{
+public:
+    using inventory_type = dash::coin::p2p::inventory_type;
+    using BlockType      = dash::coin::BlockType;
+
+    // Record a won block under its (consensus-computed) block hash and return
+    // the `inv(MSG_BLOCK, hash)` RawMessage to fan out to the live peers.
+    // Idempotent: re-announcing a known hash refreshes the stored block.
+    std::unique_ptr<RawMessage> announce(const uint256& hash, BlockType block)
+    {
+        m_pending[hash] = std::move(block);
+        std::vector<inventory_type> invs{
+            inventory_type(inventory_type::block, hash)};
+        return dash::coin::p2p::message_inv::make_raw(invs);
+    }
+
+    // Answer a peer's getdata(MSG_BLOCK, hash): the full `block` RawMessage if
+    // the hash was previously announced, else nullptr. We never serve a block
+    // we did not announce.
+    std::unique_ptr<RawMessage> on_getdata_block(const uint256& hash) const
+    {
+        auto it = m_pending.find(hash);
+        if (it == m_pending.end())
+            return nullptr;
+        return dash::coin::p2p::message_block::make_raw(it->second);
+    }
+
+    bool   knows(const uint256& hash) const { return m_pending.count(hash) != 0; }
+    size_t pending() const { return m_pending.size(); }
+    void   forget(const uint256& hash) { m_pending.erase(hash); }
+    void   clear() { m_pending.clear(); }
+
+private:
+    std::map<uint256, BlockType> m_pending;
+};
+
+} // namespace dash

test/CMakeLists.txt

@@ -452,6 +452,16 @@ if (BUILD_TESTING AND GTest_FOUND)
     target_link_libraries(test_dash_broadcaster PRIVATE c2pool_payout c2pool_hashrate c2pool_merged_mining)  # OBJECT-lib SCC direct-naming (#22/#39)
     gtest_add_tests(test_dash_broadcaster "" AUTO)
 
+    add_executable(test_dash_block_relay test_dash_block_relay.cpp)
+    target_link_libraries(test_dash_block_relay PRIVATE
+        GTest::gtest_main GTest::gtest
+        dash_x11 core
+        nlohmann_json::nlohmann_json
+        ${Boost_LIBRARIES}
+    )
+    target_link_libraries(test_dash_block_relay PRIVATE c2pool_payout c2pool_hashrate c2pool_merged_mining)  # OBJECT-lib SCC direct-naming (#22/#39)
+    gtest_add_tests(test_dash_block_relay "" AUTO)
+
     add_executable(test_compact_blocks test_compact_blocks.cpp)
     target_link_libraries(test_compact_blocks PRIVATE
         GTest::gtest_main GTest::gtest

test/test_dash_block_relay.cpp

@@ -0,0 +1,144 @@
+/// Phase S8 — WonBlockRelay (embedded-P2P won-block relay framer) KATs.
+///
+/// Exercises src/impl/dash/block_relay.hpp — the framing half of the
+/// embedded-P2P broadcast leg of the dual-path block-viability gate. Pins the
+/// `inv(MSG_BLOCK,hash)` announce -> getdata -> full `block` handshake that the
+/// DashBroadcaster pool fans out when DASH wins a block, WITHOUT any socket or
+/// live dashd:
+///
+///   (a) announce      — returns an `inv` RawMessage carrying exactly one
+///                       inventory_type, type == MSG_BLOCK (2), hash == the
+///                       supplied (consensus-computed) hash; layout PINNED by
+///                       independent reparse, not a self round-trip.
+///   (b) on_getdata    — a known hash returns the full `block` message whose
+///                       header bytes reconstruct the announced block; an
+///                       UNKNOWN hash returns nullptr (never serve unannounced).
+///   (c) bookkeeping   — knows / pending / forget / clear; re-announce is
+///                       idempotent (refreshes, no duplicate slot).
+///
+/// SCOPE NOTE (honest): pure framer + pending-block book. The block hash is an
+/// INPUT (the consensus layer's X11 header hash) — not recomputed here, so no
+/// consensus value is asserted. The live on_block_found -> announce -> socket
+/// fan-out is the operator-gated broadcaster_full concern and is not claimed.
+
+#include <gtest/gtest.h>
+
+#include <impl/dash/block_relay.hpp>
+#include <impl/dash/coin/p2p_messages.hpp>
+
+#include <core/uint256.hpp>
+#include <core/pack.hpp>
+
+#include <array>
+#include <cstdint>
+#include <cstring>
+#include <vector>
+
+using dash::WonBlockRelay;
+using dash::coin::BlockType;
+using dash::coin::p2p::message_inv;
+using dash::coin::p2p::message_block;
+using dash::coin::p2p::inventory_type;
+
+namespace {
+
+uint256 hash_seq(uint8_t base) {
+    std::array<uint8_t, 32> p{};
+    for (size_t i = 0; i < 32; ++i) p[i] = static_cast<uint8_t>(base + i);
+    uint256 h; std::memcpy(h.data(), p.data(), 32); return h;
+}
+
+BlockType make_block(uint8_t seed) {
+    BlockType b;
+    b.m_version        = 0x20000000u | seed;
+    b.m_previous_block = hash_seq(0x10 + seed);
+    b.m_merkle_root    = hash_seq(0x50 + seed);
+    b.m_timestamp      = 0x5f5e1000u + seed;
+    b.m_bits           = 0x1d00ffffu;
+    b.m_nonce          = 0xdeadbeefu - seed;
+    return b;
+}
+
+} // namespace
+
+// (a) announce frames a single MSG_BLOCK inv for the supplied hash ────────────
+TEST(DashWonBlockRelay, Announce_FramesSingleBlockInv) {
+    WonBlockRelay relay;
+    const uint256 h = hash_seq(0x77);
+
+    auto rmsg = relay.announce(h, make_block(1));
+    ASSERT_NE(rmsg, nullptr);
+    EXPECT_EQ(rmsg->m_command, "inv");
+
+    // Reparse the inv payload independently (layout-sensitive, not self-rt).
+    auto parsed = message_inv::make(rmsg->m_data);
+    ASSERT_EQ(parsed->m_invs.size(), 1u);
+    EXPECT_EQ(static_cast<uint32_t>(parsed->m_invs[0].m_type),
+              static_cast<uint32_t>(inventory_type::block));   // MSG_BLOCK == 2
+    EXPECT_EQ(static_cast<uint32_t>(inventory_type::block), 2u);
+    EXPECT_EQ(parsed->m_invs[0].m_hash, h);
+}
+
+// (b) getdata on a known hash yields the full announced block ─────────────────
+TEST(DashWonBlockRelay, GetData_KnownHash_ReturnsFullBlock) {
+    WonBlockRelay relay;
+    const uint256 h = hash_seq(0x20);
+    const BlockType blk = make_block(4);
+    relay.announce(h, blk);
+
+    auto rmsg = relay.on_getdata_block(h);
+    ASSERT_NE(rmsg, nullptr);
+    EXPECT_EQ(rmsg->m_command, "block");
+
+    auto parsed = message_block::make(rmsg->m_data);
+    EXPECT_EQ(parsed->m_block.m_version,        blk.m_version);
+    EXPECT_EQ(parsed->m_block.m_previous_block, blk.m_previous_block);
+    EXPECT_EQ(parsed->m_block.m_merkle_root,    blk.m_merkle_root);
+    EXPECT_EQ(parsed->m_block.m_timestamp,      blk.m_timestamp);
+    EXPECT_EQ(parsed->m_block.m_bits,           blk.m_bits);
+    EXPECT_EQ(parsed->m_block.m_nonce,          blk.m_nonce);
+}
+
+// (b') never serve a block we did not announce ────────────────────────────────
+TEST(DashWonBlockRelay, GetData_UnknownHash_ReturnsNull) {
+    WonBlockRelay relay;
+    relay.announce(hash_seq(0x01), make_block(1));
+    EXPECT_EQ(relay.on_getdata_block(hash_seq(0xfe)), nullptr);
+    EXPECT_FALSE(relay.knows(hash_seq(0xfe)));
+}
+
+// (c) bookkeeping: knows / pending / forget / clear ───────────────────────────
+TEST(DashWonBlockRelay, Bookkeeping_KnowsPendingForgetClear) {
+    WonBlockRelay relay;
+    EXPECT_EQ(relay.pending(), 0u);
+
+    const uint256 a = hash_seq(0x10), b = hash_seq(0x40);
+    relay.announce(a, make_block(1));
+    relay.announce(b, make_block(2));
+    EXPECT_EQ(relay.pending(), 2u);
+    EXPECT_TRUE(relay.knows(a));
+    EXPECT_TRUE(relay.knows(b));
+
+    relay.forget(a);
+    EXPECT_FALSE(relay.knows(a));
+    EXPECT_EQ(relay.pending(), 1u);
+    EXPECT_EQ(relay.on_getdata_block(a), nullptr);
+
+    relay.clear();
+    EXPECT_EQ(relay.pending(), 0u);
+}
+
+// (c') re-announce of a known hash is idempotent (refresh, no dup) ────────────
+TEST(DashWonBlockRelay, ReAnnounce_SameHash_IsIdempotentRefresh) {
+    WonBlockRelay relay;
+    const uint256 h = hash_seq(0x33);
+
+    relay.announce(h, make_block(1));
+    relay.announce(h, make_block(9));   // refresh under same hash
+    EXPECT_EQ(relay.pending(), 1u);
+
+    auto rmsg = relay.on_getdata_block(h);
+    ASSERT_NE(rmsg, nullptr);
+    auto parsed = message_block::make(rmsg->m_data);
+    EXPECT_EQ(parsed->m_block.m_nonce, make_block(9).m_nonce);  // latest wins
+}