Merge pull request #349 from frstrtr/ltc-doge/f11-reapply-value-invariance-kat

ltc(v36): re-apply F11 canonical donation fold + value-invariance KAT

Author: frstrtr

src/impl/ltc/share_check.hpp

@@ -929,6 +929,39 @@ inline std::vector<unsigned char> get_share_script(const auto* obj)
 //
 // Reference: frstrtr/p2pool-merged-v36  p2pool/data.py  generate_transaction()
 // ============================================================================
+// ---------------------------------------------------------------------------
+// F11: canonical exclude-then-append donation handling for the payout sort.
+//
+// Mirrors p2pool data.py generate_transaction: the per-miner payout dests
+// exclude BOTH donation scripts; any COMBINED_DONATION_SCRIPT-keyed weight is
+// folded into the single donation-last output, and any DONATION_SCRIPT (P2PK)
+// keyed weight is dropped. Value-invariant: the COMBINED weight is moved (not
+// destroyed) into the donation output; dropping the P2PK key is value-neutral
+// only because that key never accrues weight in canonical v36 operation.
+//
+// Re-applied after PR-0 S1 (133ae6bc) overwrote the original F11 (18dd9457) on
+// a stale base. Guarded by test/f11_donation_invariance_test.cpp.
+// ---------------------------------------------------------------------------
+template <typename AmountsMap>
+inline std::vector<std::pair<std::vector<unsigned char>, uint64_t>>
+build_payout_outputs_excluding_donation(
+    const AmountsMap& amounts,
+    const std::vector<unsigned char>& combined_donation_script,
+    const std::vector<unsigned char>& p2pk_donation_script,
+    uint64_t& donation_amount)
+{
+    if (auto it = amounts.find(combined_donation_script); it != amounts.end())
+        donation_amount += it->second;
+    std::vector<std::pair<std::vector<unsigned char>, uint64_t>> payout_outputs;
+    payout_outputs.reserve(amounts.size());
+    for (const auto& kv : amounts) {
+        if (kv.first == combined_donation_script || kv.first == p2pk_donation_script)
+            continue;
+        payout_outputs.emplace_back(kv.first, kv.second);
+    }
+    return payout_outputs;
+}
+
 template <typename ShareT, typename TrackerT>
 uint256 generate_share_transaction(const ShareT& share, TrackerT& tracker, const core::CoinParams& params, bool dump_diag = false, bool v36_active = false)
 {
@@ -1118,8 +1151,12 @@ uint256 generate_share_transaction(const ShareT& share, TrackerT& tracker, const
     auto gst_t2 = std::chrono::steady_clock::now(); // after amounts
     // Python: sorted(dests, key=lambda a: (amounts[a], a))[-4000:]
     // = ascending by (amount, script), keep last 4000 (highest amounts)
-    std::vector<std::pair<std::vector<unsigned char>, uint64_t>> payout_outputs(
-        amounts.begin(), amounts.end());
+    // F11: exclude BOTH donation scripts from per-miner dests; fold COMBINED
+    // weight into donation-last output (p2pool data.py generate_transaction).
+    const std::vector<unsigned char> combined_donation_script = params.donation_script_func(36);
+    const std::vector<unsigned char> p2pk_donation_script = params.donation_script_func(35);
+    auto payout_outputs = build_payout_outputs_excluding_donation(
+        amounts, combined_donation_script, p2pk_donation_script, donation_amount);
     std::sort(payout_outputs.begin(), payout_outputs.end(),
         [](const auto& a, const auto& b) {
             if (a.second != b.second) return a.second < b.second; // asc by amount
@@ -2391,8 +2428,12 @@ uint256 create_local_share_v35(
         // V35: no minimum donation enforcement (unlike v36)
         uint64_t donation_amount = (subsidy > sum_amounts) ? (subsidy - sum_amounts) : 0;
 
-        std::vector<std::pair<std::vector<unsigned char>, uint64_t>> payout_outputs(
-            amounts.begin(), amounts.end());
+        // F11: exclude BOTH donation scripts from per-miner dests; fold COMBINED
+        // weight into donation-last output (p2pool data.py generate_transaction).
+        const std::vector<unsigned char> combined_donation_script = params.donation_script_func(36);
+        const std::vector<unsigned char> p2pk_donation_script = params.donation_script_func(35);
+        auto payout_outputs = build_payout_outputs_excluding_donation(
+            amounts, combined_donation_script, p2pk_donation_script, donation_amount);
         std::sort(payout_outputs.begin(), payout_outputs.end(),
             [](const auto& a, const auto& b) {
                 if (a.second != b.second) return a.second < b.second;
@@ -2931,8 +2972,12 @@ uint256 create_local_share(
             }
         }
 
-        std::vector<std::pair<std::vector<unsigned char>, uint64_t>> payout_outputs(
-            amounts.begin(), amounts.end());
+        // F11: exclude BOTH donation scripts from per-miner dests; fold COMBINED
+        // weight into donation-last output (p2pool data.py generate_transaction).
+        const std::vector<unsigned char> combined_donation_script = params.donation_script_func(36);
+        const std::vector<unsigned char> p2pk_donation_script = params.donation_script_func(35);
+        auto payout_outputs = build_payout_outputs_excluding_donation(
+            amounts, combined_donation_script, p2pk_donation_script, donation_amount);
         std::sort(payout_outputs.begin(), payout_outputs.end(),
             [](const auto& a, const auto& b) {
                 if (a.second != b.second) return a.second < b.second;

src/impl/ltc/test/CMakeLists.txt

@@ -1,5 +1,5 @@
 if (BUILD_TESTING AND GTest_FOUND)
-    add_executable(share_test share_test.cpp)
+    add_executable(share_test share_test.cpp f11_donation_invariance_test.cpp)
     target_link_libraries(share_test PRIVATE
         GTest::gtest_main GTest::gtest
         core ltc

src/impl/ltc/test/f11_donation_invariance_test.cpp

@@ -0,0 +1,182 @@
+// F11 value-invariance KAT — guards the canonical exclude-then-append donation
+// handling in the LTC v36 payout sort (src/impl/ltc/share_check.hpp,
+// build_payout_outputs_excluding_donation).
+//
+// Backfills the coverage gap that let PR-0 S1 (133ae6bc) silently revert the
+// original F11 (18dd9457) on a stale base: there was no test asserting the
+// parity arithmetic, so the regression shipped unnoticed.
+//
+// Invariant under test (mirrors p2pool data.py generate_transaction):
+//   - per-miner payout dests EXCLUDE both donation scripts (COMBINED P2SH + P2PK)
+//   - COMBINED_DONATION_SCRIPT-keyed weight FOLDS into the single donation-last
+//     output (moved, not destroyed)
+//   - DONATION_SCRIPT (P2PK)-keyed weight is DROPPED — value-neutral ONLY because
+//     that key never accrues weight in canonical v36 operation
+//   - total coinbase value out == subsidy  (no value created/destroyed)
+//
+// Portable shape: BTC asserts the same invariant set against its own
+// build_payout_outputs_excluding_donation + its own donation constants.
+// Coordinated with btc-heap-opt-2026-05.
+
+#include <gtest/gtest.h>
+
+#include <map>
+#include <vector>
+#include <cstdint>
+#include <numeric>
+
+#include <impl/ltc/share.hpp>
+#include <impl/ltc/config_pool.hpp>
+#include <impl/ltc/share_check.hpp>
+
+namespace {
+
+using Script  = std::vector<unsigned char>;
+using Amounts = std::map<Script, uint64_t>;
+
+Script combined_script() {
+    return Script(ltc::PoolConfig::COMBINED_DONATION_SCRIPT.begin(),
+                  ltc::PoolConfig::COMBINED_DONATION_SCRIPT.end());
+}
+Script p2pk_script() {
+    return Script(ltc::PoolConfig::DONATION_SCRIPT.begin(),
+                  ltc::PoolConfig::DONATION_SCRIPT.end());
+}
+// Distinct miner payout scripts (P2PKH-shaped; bytes are arbitrary but != donation).
+Script miner(unsigned char tag) {
+    return Script{0x76, 0xa9, 0x14, tag, tag, tag, tag, tag, tag, tag, tag, tag, tag,
+                  tag, tag, tag, tag, tag, tag, tag, tag, tag, tag, 0x88, 0xac};
+}
+
+uint64_t sum_amounts(const Amounts& a) {
+    uint64_t s = 0; for (auto& kv : a) s += kv.second; return s;
+}
+uint64_t sum_outputs(const std::vector<std::pair<Script, uint64_t>>& o) {
+    uint64_t s = 0; for (auto& kv : o) s += kv.second; return s;
+}
+bool contains_script(const std::vector<std::pair<Script, uint64_t>>& o, const Script& s) {
+    for (auto& kv : o) if (kv.first == s) return true;
+    return false;
+}
+
+// Reproduces the production pre-fold accounting at each gentx site:
+//   donation_amount = subsidy - sum(amounts), then the helper folds COMBINED in.
+struct FoldResult {
+    std::vector<std::pair<Script, uint64_t>> payout_outputs;
+    uint64_t donation_amount;
+};
+FoldResult run_fold(const Amounts& amounts, uint64_t subsidy) {
+    uint64_t sa = sum_amounts(amounts);
+    uint64_t donation_amount = (subsidy > sa) ? (subsidy - sa) : 0;
+    auto outs = ltc::build_payout_outputs_excluding_donation(
+        amounts, combined_script(), p2pk_script(), donation_amount);
+    return {outs, donation_amount};
+}
+
+} // namespace
+
+// Canonical case: COMBINED weight present, no P2PK weight. The fold must be
+// fully value-invariant — every satoshi of subsidy is accounted for.
+TEST(LTC_F11_DonationInvariance, CombinedFoldedNoP2PK) {
+    const uint64_t subsidy = 1000;
+    Amounts amounts{
+        {miner(0x01), 100},
+        {miner(0x02), 250},
+        {miner(0x03),  75},
+        {combined_script(), 40},   // donation weight keyed by COMBINED P2SH
+    };
+
+    auto r = run_fold(amounts, subsidy);
+
+    // per-miner dests exclude the donation script
+    EXPECT_EQ(r.payout_outputs.size(), 3u);
+    EXPECT_FALSE(contains_script(r.payout_outputs, combined_script()));
+    EXPECT_FALSE(contains_script(r.payout_outputs, p2pk_script()));
+    EXPECT_TRUE(contains_script(r.payout_outputs, miner(0x01)));
+    EXPECT_TRUE(contains_script(r.payout_outputs, miner(0x02)));
+    EXPECT_TRUE(contains_script(r.payout_outputs, miner(0x03)));
+
+    // known answer: donation-last output grew by exactly the COMBINED weight
+    // donation_initial = 1000 - (100+250+75+40) = 535 ; +40 folded = 575
+    EXPECT_EQ(r.donation_amount, 575u);
+    EXPECT_EQ(sum_outputs(r.payout_outputs), 425u);
+
+    // VALUE INVARIANCE: per-miner outputs + donation-last == subsidy
+    EXPECT_EQ(sum_outputs(r.payout_outputs) + r.donation_amount, subsidy);
+}
+
+// Both donation scripts present; P2PK at canonical weight 0. Both excluded from
+// per-miner dests; dropping the 0-weight P2PK key is value-neutral.
+TEST(LTC_F11_DonationInvariance, BothDonationScriptsExcluded_P2PKZeroWeight) {
+    const uint64_t subsidy = 5000;
+    Amounts amounts{
+        {miner(0x0a), 1200},
+        {miner(0x0b),  800},
+        {combined_script(), 333},
+        {p2pk_script(), 0},        // canonical: P2PK never accrues weight
+    };
+
+    auto r = run_fold(amounts, subsidy);
+
+    EXPECT_EQ(r.payout_outputs.size(), 2u);
+    EXPECT_FALSE(contains_script(r.payout_outputs, combined_script()));
+    EXPECT_FALSE(contains_script(r.payout_outputs, p2pk_script()));
+
+    // donation_initial = 5000 - (1200+800+333+0) = 2667 ; +333 = 3000
+    EXPECT_EQ(r.donation_amount, 3000u);
+    EXPECT_EQ(sum_outputs(r.payout_outputs) + r.donation_amount, subsidy);
+}
+
+// No donation keys at all: the fold is an identity over the miner set and the
+// donation-last output is unchanged.
+TEST(LTC_F11_DonationInvariance, NoDonationKeys_Identity) {
+    const uint64_t subsidy = 2000;
+    Amounts amounts{
+        {miner(0x21), 600},
+        {miner(0x22), 400},
+    };
+
+    auto r = run_fold(amounts, subsidy);
+
+    EXPECT_EQ(r.payout_outputs.size(), 2u);
+    EXPECT_EQ(r.donation_amount, 1000u);  // 2000 - 1000, no fold
+    EXPECT_EQ(sum_outputs(r.payout_outputs) + r.donation_amount, subsidy);
+}
+
+// Boundary documentation: if the P2PK key DID carry weight (non-canonical),
+// dropping it would destroy exactly that many satoshis. This locks the reason
+// the canonical invariant requires P2PK weight == 0, so a future change that
+// starts keying weight on the P2PK script cannot pass silently.
+TEST(LTC_F11_DonationInvariance, DroppedP2PKWeightLeaksExactlyThatWeight) {
+    const uint64_t subsidy = 1000;
+    const uint64_t p2pk_weight = 30;  // NON-canonical, for the boundary proof
+    Amounts amounts{
+        {miner(0x31), 200},
+        {combined_script(), 50},
+        {p2pk_script(), p2pk_weight},
+    };
+
+    auto r = run_fold(amounts, subsidy);
+
+    // COMBINED still folds correctly; P2PK weight is dropped (not folded).
+    EXPECT_FALSE(contains_script(r.payout_outputs, p2pk_script()));
+    // Total is short by EXACTLY the dropped P2PK weight — value is conserved
+    // iff p2pk_weight == 0.
+    EXPECT_EQ(sum_outputs(r.payout_outputs) + r.donation_amount, subsidy - p2pk_weight);
+}
+
+// Pin the actual consensus donation bytes so a constant change trips this test.
+TEST(LTC_F11_DonationInvariance, RealDonationConstantsPinned) {
+    auto c = combined_script();
+    ASSERT_EQ(c.size(), 23u);                 // P2SH: OP_HASH160 <20> OP_EQUAL
+    EXPECT_EQ(c.front(), 0xa9);
+    EXPECT_EQ(c[1], 0x14);
+    EXPECT_EQ(c.back(), 0x87);
+
+    auto p = p2pk_script();
+    ASSERT_EQ(p.size(), 67u);                 // P2PK: OP_PUSHBYTES_65 <65> OP_CHECKSIG
+    EXPECT_EQ(p.front(), 0x41);
+    EXPECT_EQ(p.back(), 0xac);
+
+    EXPECT_NE(c, p);
+}