fix(btc): prepend coinbase placeholder leaf in stratum merkle branches (#570)

* fix(btc): prepend coinbase placeholder leaf in stratum merkle branches

get_stratum_merkle_branches treated wd->m_hashes[0] as the coinbase
placeholder, but the producers (rpc.cpp, coin/template_builder.hpp) fill
m_hashes as the pure tx-hash list [tx1..txN] with NO coinbase slot. For
any populated (>=1 mempool tx) block this folded tx2 as the first sibling
and dropped tx1, so the stratum header merkle root diverged from the
serialized body -> bad-txnmrklroot rejection. Coinbase-only blocks
(empty m_hashes) early-return {} and collapse to coinbase_txid, so the
bug was latent until the first populated won block.

Fix (fenced to stratum/work_source.cpp, zero coinbase-byte reshape):
- get_stratum_merkle_branches: prepend uint256::ZERO coinbase placeholder
  leaf before the branch fold; empty-mempool early return unchanged.
- mining_submit: non-fatal body-vs-header merkle self-check recomputing
  compute_merkle_root([coinbase_txid, tx1..txN]) and logging OK/DIVERGENCE
  before submit, so the leaf-set class is caught loudly not silently.

Mirrors bch-embedded-steward fenced fix; per-coin isolation preserved.
btc_share_test 39/39 green; make btc exit 0.

* test(btc): KAT pinning stratum merkle coinbase leaf-0 contract (#570)

Extract the stratum coinbase branch fold into a pure SSOT helper
btc::coin::stratum_merkle_siblings() (template_builder.hpp) and delegate
get_stratum_merkle_branches() to it, so the wire path, the mining_submit
self-check, and tests all exercise one fold.

Add btc_share_test gtest stratum_merkle_branch_test.cpp (CI-bound, 39->42):
- FoldReconstructsBodyRoot: production siblings folded against a coinbase
  txid equal compute_merkle_root([coinbase, tx1..txN]) for N in
  {0,1,2,3,4,5,7,16} (covers the N=1 case the latent bug corrupted + odd
  last-element duplication).
- CoinbaseOnlyHasNoBranches: empty template -> no branches, coinbase IS root.
- PreFixBuilderDivergesOnPopulated: the pre-#570 builder (no leaf-0
  placeholder) diverges from the body root on every populated template ->
  flip-RED proof the guard is not blind.

No consensus change; test + refactor only, BTC-fenced.

---------

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

Author: frstrtr

src/impl/btc/coin/template_builder.hpp

@@ -88,6 +88,48 @@ inline uint256 compute_merkle_root(std::vector<uint256> hashes) {
     return hashes[0];
 }
 
+/// Stratum coinbase merkle branch siblings for a populated template.
+///
+/// PRODUCER/CONSUMER CONTRACT: `tx_hashes` is the pure tx-hash list
+/// [tx1..txN] with NO coinbase slot (template_builder / GBT transactions[]).
+/// The stratum merkle tree has the coinbase as leaf 0, so we prepend a
+/// placeholder leaf before folding. At each level we emit the SIBLING of the
+/// left-most (coinbase-descended) node -- exactly the branch list a miner
+/// folds against its own coinbase txid to rebuild the header merkle root:
+///     acc = coinbase_txid
+///     for b in siblings: acc = merkle_hash_pair(acc, b)
+///     acc == compute_merkle_root([coinbase_txid, tx1..txN])
+///
+/// SSOT for both BTCWorkSource::get_stratum_merkle_branches() (which hex-
+/// encodes these for the wire) and the merkle self-check in mining_submit.
+/// Without the leaf-0 prepend, tx1 is dropped and the folded root diverges
+/// from the serialized body -> bad-txnmrklroot on any populated won block.
+/// Returns {} for an empty (coinbase-only) template.
+inline std::vector<uint256> stratum_merkle_siblings(const std::vector<uint256>& tx_hashes) {
+    if (tx_hashes.empty()) return {};
+
+    std::vector<uint256> level;
+    level.reserve(tx_hashes.size() + 1);
+    level.push_back(uint256::ZERO);  // coinbase placeholder leaf (leaf 0)
+    level.insert(level.end(), tx_hashes.begin(), tx_hashes.end());
+
+    std::vector<uint256> siblings;
+    while (level.size() > 1) {
+        siblings.push_back(level[1]);  // right-sibling of the coinbase node
+
+        std::vector<uint256> next;
+        next.reserve((level.size() + 2) / 2);
+        next.push_back(uint256::ZERO);  // placeholder for combo of (cb, level[1])
+        for (size_t i = 2; i < level.size(); i += 2) {
+            const uint256& l = level[i];
+            const uint256& r = (i + 1 < level.size()) ? level[i + 1] : level[i];
+            next.push_back(merkle_hash_pair(l, r));
+        }
+        level = std::move(next);
+    }
+    return siblings;
+}
+
 // ─── CoinNodeInterface ────────────────────────────────────────────────────────
 
 /// Abstract interface for obtaining work and submitting blocks.

src/impl/btc/stratum/work_source.cpp

@@ -275,12 +275,22 @@ std::vector<std::string> BTCWorkSource::get_stratum_merkle_branches() const
     auto wd = cached_template();
     if (!wd || wd->m_hashes.empty()) return {};
 
-    // wd->m_hashes[0] is the coinbase placeholder — the actual coinbase
-    // hash doesn't matter for branch computation since the miner provides
-    // their own coinbase. We only need the structure.
-    std::vector<uint256> level = wd->m_hashes;
+    // PRODUCER/CONSUMER CONTRACT: wd->m_hashes is the pure tx-hash list
+    // [tx1..txN] with NO coinbase slot (filled by rpc.cpp / template_builder.hpp
+    // straight from GBT transactions[]). The stratum merkle tree, however, has
+    // the coinbase as leaf 0. Prepend a placeholder leaf for it before folding
+    // — the actual coinbase hash doesn't matter for branch computation since
+    // the miner provides their own coinbase; we only need the leaf STRUCTURE.
+    // Without this prepend, level[1] below would be tx2 (not tx1), tx1 would be
+    // dropped, and the header merkle root would diverge from the serialized
+    // body → bad-txnmrklroot rejection on any populated (>=1 tx) won block.
+    // SSOT: branch sibling structure lives in btc::coin::stratum_merkle_siblings
+    // (template_builder.hpp) so the merkle self-check in mining_submit and any
+    // KAT exercise the SAME fold as the wire path. We only hex-encode here.
+    std::vector<uint256> level = btc::coin::stratum_merkle_siblings(wd->m_hashes);
     std::vector<std::string> branches;
-    while (level.size() > 1) {
+    branches.reserve(level.size());
+    for (const auto& sib : level) {
         // Right-sibling of the left-most node = level[1].
         // Wire encoding: hex of LE-internal bytes (NOT GetHex() which is
         // BE display). Matches cgminer convention + LTC's working
@@ -289,19 +299,7 @@ std::vector<std::string> BTCWorkSource::get_stratum_merkle_branches() const
         // the bytes on the wire MUST be the same LE-internal bytes the
         // pool used to build the merkle tree. GetHex() reverses them and
         // produces a totally different merkle root in the miner's view.
-        branches.push_back(HexStr(std::span<const unsigned char>(level[1].data(), 32)));
-
-        // Ascend: place a placeholder for the next-level coinbase combo,
-        // then hash subsequent pairs (duplicate last on odd count).
-        std::vector<uint256> next;
-        next.reserve((level.size() + 2) / 2);
-        next.push_back(uint256::ZERO);  // placeholder for combo of (cb, level[1])
-        for (size_t i = 2; i < level.size(); i += 2) {
-            const uint256& l = level[i];
-            const uint256& r = (i + 1 < level.size()) ? level[i + 1] : level[i];
-            next.push_back(btc::coin::merkle_hash_pair(l, r));
-        }
-        level = std::move(next);
+        branches.push_back(HexStr(std::span<const unsigned char>(sib.data(), 32)));
     }
     return branches;
 }
@@ -761,6 +759,34 @@ nlohmann::json BTCWorkSource::mining_submit(
 
     uint256 pow_hash = Hash(std::span<const uint8_t>(header.data(), header.size()));
 
+    // ── Non-fatal merkle self-check (producer/consumer contract guard) ──
+    // Recompute the body merkle root over the full leaf set
+    // [coinbase_txid, tx1..txN] and compare it to the branch-folded header
+    // root above. If get_stratum_merkle_branches and the serialized body ever
+    // disagree on the leaf structure (the latent bad-txnmrklroot class), this
+    // logs a loud DIVERGENCE BEFORE the block is submitted and rejected. Uses
+    // the current cached template's leaf set; a template roll between job
+    // freeze and submit can produce a benign mismatch, so this is advisory
+    // only and never rejects the share.
+    if (auto wd_chk = cached_template()) {
+        std::vector<uint256> body_leaves;
+        body_leaves.reserve(wd_chk->m_hashes.size() + 1);
+        body_leaves.push_back(coinbase_txid);
+        body_leaves.insert(body_leaves.end(), wd_chk->m_hashes.begin(), wd_chk->m_hashes.end());
+        uint256 body_root = btc::coin::compute_merkle_root(body_leaves);
+        if (body_root == merkle_root) {
+            LOG_DEBUG_OTHER << "[BTC-STRATUM] merkle self-check OK: body root matches header"
+                            << " (" << body_leaves.size() << " leaves)";
+        } else {
+            LOG_WARNING << "[BTC-STRATUM] merkle self-check DIVERGENCE: header root="
+                        << HexStr(std::span<const uint8_t>(merkle_root.data(), 32))
+                        << " body root="
+                        << HexStr(std::span<const uint8_t>(body_root.data(), 32))
+                        << " over " << body_leaves.size() << " leaves"
+                        << " — block would be rejected bad-txnmrklroot (template roll or leaf-set bug)";
+        }
+    }
+
     // Decode share target (separate from block target — pre-this-fix we
     // were comparing pow_hash against block target which is network
     // difficulty, so every share got rejected as low-diff. The miner

src/impl/btc/test/CMakeLists.txt

@@ -1,7 +1,7 @@
 if (BUILD_TESTING AND GTest_FOUND)
     # btc twin of ltc share_test — uniquely named to avoid the CMP0002 target
     # collision with src/impl/ltc/test (both subdirs build in the same tree).
-    add_executable(btc_share_test share_test.cpp f11_donation_invariance_test.cpp f10b_version_punish_removal_test.cpp g01_share_format_parity_test.cpp auto_ratchet_sim_test.cpp block_broadcast_guard_test.cpp block_broadcast_connect_test.cpp regtest_sharechain_isolation_test.cpp)
+    add_executable(btc_share_test share_test.cpp f11_donation_invariance_test.cpp f10b_version_punish_removal_test.cpp g01_share_format_parity_test.cpp auto_ratchet_sim_test.cpp block_broadcast_guard_test.cpp block_broadcast_connect_test.cpp regtest_sharechain_isolation_test.cpp stratum_merkle_branch_test.cpp)
     target_link_libraries(btc_share_test PRIVATE
         GTest::gtest_main GTest::gtest
         core btc

src/impl/btc/test/stratum_merkle_branch_test.cpp

@@ -0,0 +1,106 @@
+// Producer/consumer merkle-branch contract KAT for the BTC stratum work source.
+//
+// Regression guard for the latent bad-txnmrklroot defect fixed in PR #570.
+// BTCWorkSource::get_stratum_merkle_branches() folds wd->m_hashes (the pure
+// [tx1..txN] list, with NO coinbase slot) into stratum coinbase branches. The
+// miner rebuilds the header merkle root by folding ITS coinbase txid against
+// those branches; that reconstruction MUST equal
+// compute_merkle_root([coinbase, tx1..txN]) — the exact root the serialized
+// block body commits to. Pre-#570 the branch builder omitted the leaf-0
+// coinbase placeholder, so tx1 was dropped and every populated (>=1 tx) won
+// block was rejected bad-txnmrklroot.
+//
+// SSOT under test: btc::coin::stratum_merkle_siblings (template_builder.hpp),
+// which get_stratum_merkle_branches() now delegates to. Revert the leaf-0
+// prepend there and FoldReconstructsBodyRoot goes RED.
+
+#include <gtest/gtest.h>
+
+#include <impl/btc/coin/template_builder.hpp>
+#include <core/uint256.hpp>
+
+#include <vector>
+
+using btc::coin::compute_merkle_root;
+using btc::coin::merkle_hash_pair;
+using btc::coin::stratum_merkle_siblings;
+
+namespace {
+
+// Miner-side reconstruction: fold the coinbase txid against the branch siblings.
+uint256 fold_branches(const uint256& coinbase, const std::vector<uint256>& sibs) {
+    uint256 acc = coinbase;
+    for (const auto& s : sibs) acc = merkle_hash_pair(acc, s);
+    return acc;
+}
+
+// Body-side truth: the full merkle root committed by the serialized block over
+// [coinbase, tx1..txN].
+uint256 body_root(const uint256& coinbase, const std::vector<uint256>& txs) {
+    std::vector<uint256> leaves;
+    leaves.reserve(txs.size() + 1);
+    leaves.push_back(coinbase);
+    leaves.insert(leaves.end(), txs.begin(), txs.end());
+    return compute_merkle_root(leaves);
+}
+
+std::vector<uint256> make_txs(unsigned n) {
+    std::vector<uint256> v;
+    v.reserve(n);
+    for (unsigned i = 0; i < n; ++i) v.push_back(uint256((uint64_t)(0x1000u + i)));
+    return v;
+}
+
+// The pre-#570 BUGGY branch builder: folds tx_hashes with NO coinbase leaf-0
+// placeholder. Replicated here only to PROVE this KAT catches the regression.
+std::vector<uint256> buggy_siblings(const std::vector<uint256>& tx_hashes) {
+    if (tx_hashes.empty()) return {};
+    std::vector<uint256> level = tx_hashes;  // BUG: missing coinbase leaf-0
+    std::vector<uint256> sibs;
+    while (level.size() > 1) {
+        sibs.push_back(level[1]);
+        std::vector<uint256> next;
+        next.push_back(uint256::ZERO);
+        for (size_t i = 2; i < level.size(); i += 2) {
+            const uint256& l = level[i];
+            const uint256& r = (i + 1 < level.size()) ? level[i + 1] : level[i];
+            next.push_back(merkle_hash_pair(l, r));
+        }
+        level = std::move(next);
+    }
+    return sibs;
+}
+
+const uint256 COINBASE((uint64_t)0xC0FFEEull);
+
+}  // namespace
+
+// Positive contract: production siblings reconstruct the body root for every
+// template size — including the single-tx (N=1) case the pre-#570 bug silently
+// corrupted, and odd counts (last-element duplication path).
+TEST(StratumMerkleBranch, FoldReconstructsBodyRoot) {
+    for (unsigned n : {0u, 1u, 2u, 3u, 4u, 5u, 7u, 16u}) {
+        auto txs = make_txs(n);
+        auto sibs = stratum_merkle_siblings(txs);
+        EXPECT_EQ(fold_branches(COINBASE, sibs), body_root(COINBASE, txs))
+            << "N=" << n << " branch fold diverged from body merkle root";
+    }
+}
+
+// Coinbase-only template yields zero branches and the coinbase IS the root.
+TEST(StratumMerkleBranch, CoinbaseOnlyHasNoBranches) {
+    auto sibs = stratum_merkle_siblings(make_txs(0));
+    EXPECT_TRUE(sibs.empty());
+    EXPECT_EQ(fold_branches(COINBASE, sibs), COINBASE);
+}
+
+// flip-RED proof: the pre-#570 builder (no leaf-0 placeholder) diverges from
+// the body root on EVERY populated template — i.e. this KAT would have caught
+// the bad-txnmrklroot defect.
+TEST(StratumMerkleBranch, PreFixBuilderDivergesOnPopulated) {
+    for (unsigned n : {1u, 2u, 3u, 5u}) {
+        auto txs = make_txs(n);
+        EXPECT_NE(fold_branches(COINBASE, buggy_siblings(txs)), body_root(COINBASE, txs))
+            << "N=" << n << " buggy builder unexpectedly matched — guard is blind";
+    }
+}