dgb(#172): share-path gentx KAT — prove generate_share_transaction emits SSOT framing

frstrtr · frstrtr · commit cadec972d028 · 2026-06-19T01:42:50.000Z
Round-trip equivalence KAT (op_return ref_hash is share-derived, cannot pin a fixed oracle vector): generate_share_transaction(share) txid == verbatim re-derivation through the SAME assemble_gentx_coinbase SSOT. Proves the #172 collapse behaviorally, not structurally. 3/3 PASS, txid 9e2b78d5. Wired into ctest + BOTH build.yml allowlists in this commit (#143 NOT_BUILT trap).
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -67,8 +67,8 @@ jobs:
                     test_phase4_embedded \
                     test_mweb_builder \
                     test_address_resolution test_compute_share_target \
-                    test_utxo test_dgb_subsidy dgb_share_test dgb_block_assembly_test dgb_gentx_coinbase_test \
-                    nmc_auxpow_merkle_test \
+                    test_utxo test_dgb_subsidy dgb_share_test dgb_block_assembly_test \
+                    dgb_gentx_coinbase_test nmc_auxpow_merkle_test dgb_gentx_share_path_test \
                     rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test header_chain_test \
                     v37_test \
             -j$(nproc)
@@ -198,8 +198,8 @@ jobs:
                     test_phase4_embedded \
                     test_mweb_builder \
                     test_address_resolution test_compute_share_target \
-                    test_utxo test_dgb_subsidy dgb_share_test dgb_block_assembly_test dgb_gentx_coinbase_test \
-                    nmc_auxpow_merkle_test \
+                    test_utxo test_dgb_subsidy dgb_share_test dgb_block_assembly_test \
+                    dgb_gentx_coinbase_test nmc_auxpow_merkle_test dgb_gentx_share_path_test \
                     rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test header_chain_test \
                     test_coin_broadcaster test_multiaddress_pplns test_pplns_stress \
                     v37_test \
diff --git a/src/impl/dgb/test/CMakeLists.txt b/src/impl/dgb/test/CMakeLists.txt
@@ -54,6 +54,20 @@ if (BUILD_TESTING AND GTest_FOUND)
         dgb_coin pool sharechain)
     gtest_add_tests(dgb_gentx_coinbase_test "" AUTO)
 
+    # --- #172 share-path gentx KAT (collapse consumption proof) ------------
+    # Proves generate_share_transaction (the verification SSOT call site #172
+    # rewired) EMITS assemble_gentx_coinbase framing for a real v36 share, via
+    # a round-trip equivalence (the op_return ref_hash is share-derived, so it
+    # cannot be pinned to a fixed oracle vector). Links the dgb OBJECT lib like
+    # dgb_share_test. MUST also be in the build.yml --target allowlist (#143).
+    add_executable(dgb_gentx_share_path_test gentx_share_path_test.cpp)
+    target_link_libraries(dgb_gentx_share_path_test PRIVATE
+        GTest::gtest_main GTest::gtest
+        core dgb
+        c2pool_payout c2pool_merged_mining c2pool_hashrate c2pool_storage
+        dgb_coin pool sharechain)
+    gtest_add_tests(dgb_gentx_share_path_test "" AUTO)
+
     foreach(dgb_guard rpc_request_test softfork_check_test genesis_check_test algo_select_test digishield_walk_test header_chain_test)
         add_executable(${dgb_guard} ${dgb_guard}.cpp)
         target_link_libraries(${dgb_guard} PRIVATE
diff --git a/src/impl/dgb/test/gentx_share_path_test.cpp b/src/impl/dgb/test/gentx_share_path_test.cpp
@@ -0,0 +1,264 @@
+// DGB #82 / #172 — share-path gentx KAT.
+//
+// The helper-level KAT (gentx_coinbase_test) pins dgb::coin::assemble_gentx_coinbase
+// directly against oracle vectors. This test proves the *consumption* side of
+// the #172 collapse: that generate_share_transaction() — the verification SSOT
+// call site that #172 rewired onto assemble_gentx_coinbase — actually EMITS the
+// SSOT framing for a real share, not merely that the pure helper does.
+//
+// The OP_RETURN ref commitment is share-derived:
+//   ref_hash = check_merkle_link(Hash(ref_serialization), m_ref_merkle_link)
+// so the share-path gentx cannot be pinned to a fixed 0xab..×32 oracle byte
+// vector (criterion 1: no oracle vector regeneration). Instead we assert a
+// round-trip equivalence: generate_share_transaction(share) == a verbatim
+// re-derivation of the same per-share inputs handed to the SAME SSOT assembler.
+// If the share path ever stops routing through the SSOT, or builds the coinbase
+// inputs differently, the two txids diverge and this fails — which is exactly
+// "the collapse is what's tested."
+//
+// A v36 MergedMiningShare with a NULL parent is used so the PPLNS walk is
+// skipped entirely (no tracker chain entries are touched): payout_outputs is
+// empty and donation_amount == subsidy. That isolates the coinbase framing +
+// op_return derivation, which is the SSOT contract under test.
+//
+// MUST appear in BOTH test/CMakeLists.txt AND the build.yml --target allowlist
+// or it becomes a #143-style NOT_BUILT sentinel that reds master.
+
+#include <gtest/gtest.h>
+
+#include <impl/dgb/share.hpp>
+#include <impl/dgb/share_tracker.hpp>
+#include <impl/dgb/share_check.hpp>
+#include <impl/dgb/params.hpp>
+#include <impl/dgb/coin/gentx_coinbase.hpp>
+
+#include <core/pack.hpp>
+#include <core/hash.hpp>
+#include <core/uint256.hpp>
+
+#include <cstdint>
+#include <optional>
+#include <span>
+#include <utility>
+#include <vector>
+
+namespace {
+
+// A v36 share with a null parent => PPLNS skipped (empty payouts, donation ==
+// subsidy). Coinbase script / nonce / timestamp / last_txout_nonce are set to
+// non-trivial values so the op_return ref derivation is exercised.
+dgb::MergedMiningShare make_v36_share()
+{
+    dgb::MergedMiningShare s;
+    s.m_prev_hash.SetNull();                 // null parent => PPLNS walk skipped
+    s.m_coinbase.m_data = { 0x03, 0xa1, 0xb2, 0xc3, 0x04, 0x11, 0x22, 0x33, 0x44 };
+    s.m_nonce = 0x12345678;
+    s.m_pubkey_hash.SetNull();
+    s.m_pubkey_type = 0;
+    s.m_subsidy = 500000000ull;
+    s.m_donation = 0;
+    s.m_stale_info = dgb::none;
+    s.m_desired_version = 36;
+    s.m_segwit_data = std::nullopt;
+    s.m_far_share_hash.SetNull();
+    s.m_max_bits = 0x1e0fffff;
+    s.m_bits = 0x1e0fffff;
+    s.m_timestamp = 1718700000;
+    s.m_absheight = 1000;
+    // m_abswork default-constructs to zero (uint128)
+    s.m_merged_payout_hash.SetNull();
+    s.m_last_txout_nonce = 0x0001020304050607ull;
+    // m_ref_merkle_link left empty => check_merkle_link returns Hash(ref) directly
+    return s;
+}
+
+// Verbatim re-derivation of generate_share_transaction's per-share coinbase
+// inputs (v36 path), ending in the SAME SSOT assembler. Mirrors share_check.hpp
+// section 4/5 byte-for-byte via the identical pack primitives.
+template <typename ShareT>
+dgb::coin::GentxCoinbase rederive_via_ssot(
+    const ShareT& share, const core::CoinParams& params)
+{
+    constexpr int64_t ver = ShareT::version;
+
+    // null parent => empty payouts, donation_amount == subsidy
+    std::vector<std::pair<std::vector<unsigned char>, uint64_t>> payout_outputs;
+    uint64_t donation_amount = share.m_subsidy;
+
+    // no segwit_data => no witness-commitment vout
+    std::optional<std::vector<unsigned char>> segwit_commitment_script;
+
+    auto donation_script = params.donation_script_func(ver);
+
+    std::vector<unsigned char> op_return_script;
+    {
+        PackStream ref_stream;
+        {
+            auto hex = params.active_identifier_hex();
+            for (size_t i = 0; i + 1 < hex.size(); i += 2)
+            {
+                unsigned char byte = static_cast<unsigned char>(
+                    std::stoul(hex.substr(i, 2), nullptr, 16));
+                ref_stream.write(std::span<const std::byte>(
+                    reinterpret_cast<const std::byte*>(&byte), 1));
+            }
+        }
+        {
+            ref_stream << share.m_prev_hash;
+            ref_stream << share.m_coinbase;
+            ref_stream << share.m_nonce;
+
+            if constexpr (requires { share.m_address; })
+                ref_stream << share.m_address;
+            else if constexpr (requires { share.m_pubkey_type; })
+            {
+                ref_stream << share.m_pubkey_hash;
+                ref_stream << share.m_pubkey_type;
+            }
+            else
+                ref_stream << share.m_pubkey_hash;
+
+            if constexpr (core::version_gate::is_v36_active(ver))
+                ::Serialize(ref_stream, VarInt(share.m_subsidy));
+            else
+                ref_stream << share.m_subsidy;
+
+            ref_stream << share.m_donation;
+            {
+                uint8_t si = static_cast<uint8_t>(share.m_stale_info);
+                ref_stream << si;
+            }
+            ::Serialize(ref_stream, VarInt(share.m_desired_version));
+
+            if constexpr (requires { share.m_segwit_data; })
+            {
+                if constexpr (ver >= dgb::SEGWIT_ACTIVATION_VERSION)
+                {
+                    if (share.m_segwit_data.has_value()) {
+                        ref_stream << share.m_segwit_data.value();
+                    } else {
+                        std::vector<uint256> empty_branch;
+                        ref_stream << empty_branch;
+                        uint256 zero_root;
+                        ref_stream << zero_root;
+                    }
+                }
+            }
+
+            if constexpr (core::version_gate::is_v36_active(ver))
+            {
+                if constexpr (requires { share.m_merged_addresses; })
+                    ref_stream << share.m_merged_addresses;
+            }
+
+            if constexpr (ver < 34)
+            {
+                if constexpr (requires { share.m_tx_info; })
+                    ref_stream << share.m_tx_info;
+            }
+
+            ref_stream << share.m_far_share_hash;
+            ref_stream << share.m_max_bits;
+            ref_stream << share.m_bits;
+            ref_stream << share.m_timestamp;
+            ref_stream << share.m_absheight;
+
+            if constexpr (core::version_gate::is_v36_active(ver))
+            {
+                if constexpr (requires { share.m_abswork; })
+                    ::Serialize(ref_stream, Using<dgb::AbsworkV36Format>(share.m_abswork));
+            }
+            else
+            {
+                ref_stream << share.m_abswork;
+            }
+
+            if constexpr (core::version_gate::is_v36_active(ver))
+            {
+                if constexpr (requires { share.m_merged_coinbase_info; })
+                    ref_stream << share.m_merged_coinbase_info;
+                if constexpr (requires { share.m_merged_payout_hash; })
+                    ref_stream << share.m_merged_payout_hash;
+            }
+        }
+
+        if constexpr (core::version_gate::is_v36_active(ver))
+        {
+            if constexpr (requires { share.m_message_data; })
+                ref_stream << share.m_message_data;
+        }
+
+        auto ref_span = std::span<const unsigned char>(
+            reinterpret_cast<const unsigned char*>(ref_stream.data()), ref_stream.size());
+        uint256 hash_ref = Hash(ref_span);
+        uint256 ref_hash = dgb::check_merkle_link(hash_ref, share.m_ref_merkle_link);
+
+        op_return_script.push_back(0x6a); // OP_RETURN
+        op_return_script.push_back(0x28); // PUSH 40
+        op_return_script.insert(op_return_script.end(), ref_hash.data(), ref_hash.data() + 32);
+        {
+            uint64_t nonce = share.m_last_txout_nonce;
+            auto* p = reinterpret_cast<const unsigned char*>(&nonce);
+            op_return_script.insert(op_return_script.end(), p, p + 8);
+        }
+    }
+
+    return dgb::coin::assemble_gentx_coinbase(
+        share.m_coinbase.m_data, segwit_commitment_script, payout_outputs,
+        donation_amount, donation_script, op_return_script);
+}
+
+// --- Test 1: share path emits SSOT framing (round-trip equivalence) -----------
+TEST(DgbGentxSharePath, GenerateShareTransactionEmitsSsotFraming)
+{
+    auto params = dgb::make_coin_params(/*testnet=*/false);
+    dgb::ShareTracker tracker;                 // empty chain
+    auto share = make_v36_share();
+
+    // Route A: the verification SSOT call site under test.
+    uint256 actual = dgb::generate_share_transaction(
+        share, tracker, params, /*dump_diag=*/false, /*v36_active=*/true);
+
+    // Route B: verbatim re-derivation through the SAME assembler.
+    auto expected = rederive_via_ssot(share, params);
+
+    EXPECT_EQ(actual, expected.txid)
+        << "generate_share_transaction no longer emits assemble_gentx_coinbase framing";
+}
+
+// --- Test 2: determinism (the SSOT path is a pure function of the share) -------
+TEST(DgbGentxSharePath, Deterministic)
+{
+    auto params = dgb::make_coin_params(false);
+    dgb::ShareTracker tracker;
+    auto share = make_v36_share();
+
+    uint256 a = dgb::generate_share_transaction(share, tracker, params, false, true);
+    uint256 b = dgb::generate_share_transaction(share, tracker, params, false, true);
+    EXPECT_EQ(a, b);
+}
+
+// --- Test 3: coinbase-affecting fields flow into the SSOT gentx ----------------
+// last_txout_nonce feeds the op_return; coinbase script feeds vin[0]. Changing
+// either must change the gentx txid (proves the share data reaches the SSOT,
+// not a cached/stubbed value).
+TEST(DgbGentxSharePath, CoinbaseInputsAreLoadBearing)
+{
+    auto params = dgb::make_coin_params(false);
+    dgb::ShareTracker tracker;
+
+    auto base = make_v36_share();
+    uint256 h0 = dgb::generate_share_transaction(base, tracker, params, false, true);
+
+    auto bumped_nonce = base;
+    bumped_nonce.m_last_txout_nonce ^= 0xffull;
+    uint256 h1 = dgb::generate_share_transaction(bumped_nonce, tracker, params, false, true);
+    EXPECT_NE(h0, h1) << "last_txout_nonce did not reach the op_return commitment";
+
+    auto bumped_cb = base;
+    bumped_cb.m_coinbase.m_data.push_back(0x99);
+    uint256 h2 = dgb::generate_share_transaction(bumped_cb, tracker, params, false, true);
+    EXPECT_NE(h0, h2) << "coinbase script did not reach the gentx vin";
+}
+
+} // namespace
