Merge pull request #353 from frstrtr/dgb/think-p1-walk-bounds

dgb: SSOT think() Phase-1 desired-walk bounds + KAT (Phase-B pool/share)

Author: frstrtr

.github/workflows/build.yml

@@ -84,7 +84,7 @@ jobs:
                     dgb_gentx_coinbase_test dgb_connection_coinbase_test dgb_pplns_payout_split_test nmc_auxpow_merkle_test nmc_template_builder_test nmc_auxpow_wire_test nmc_reconstruct_won_block_test dgb_gentx_share_path_test dgb_conn_pplns_producer_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_template_other_txs_test dgb_coinbase_value_parity_test dgb_submit_classify_test dgb_aux_parent_coinbase_parity_test dgb_template_capture_test dgb_aux_doge_db_commitment_bind_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_regrind_block_test dgb_won_block_finalize_test dgb_share_target_genesis_test dgb_pool_msg_wire_test dgb_get_shares_walk_test dgb_download_stops_test v37_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_regrind_block_test dgb_won_block_finalize_test dgb_share_target_genesis_test dgb_pool_msg_wire_test dgb_get_shares_walk_test dgb_download_stops_test dgb_think_p1_walk_bounds_test v37_test \
             -j$(nproc)
 
       - name: Run tests
@@ -216,7 +216,7 @@ jobs:
                     dgb_gentx_coinbase_test dgb_connection_coinbase_test dgb_pplns_payout_split_test nmc_auxpow_merkle_test nmc_template_builder_test nmc_auxpow_wire_test nmc_reconstruct_won_block_test dgb_gentx_share_path_test dgb_conn_pplns_producer_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_template_other_txs_test dgb_coinbase_value_parity_test dgb_submit_classify_test dgb_aux_parent_coinbase_parity_test dgb_template_capture_test dgb_aux_doge_db_commitment_bind_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_regrind_block_test dgb_won_block_finalize_test dgb_share_target_genesis_test dgb_pool_msg_wire_test dgb_get_shares_walk_test dgb_download_stops_test test_coin_broadcaster test_multiaddress_pplns test_pplns_stress \
+                    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_regrind_block_test dgb_won_block_finalize_test dgb_share_target_genesis_test dgb_pool_msg_wire_test dgb_get_shares_walk_test dgb_download_stops_test dgb_think_p1_walk_bounds_test test_coin_broadcaster test_multiaddress_pplns test_pplns_stress \
                     v37_test \
             -j$(nproc)
 

src/impl/dgb/test/CMakeLists.txt

@@ -605,4 +605,17 @@ if (BUILD_TESTING AND GTest_FOUND)
         dgb_coin pool sharechain)
     gtest_add_tests(dgb_download_stops_test "" AUTO)
 
+    # dgb_think_p1_walk_bounds_test: FENCED, additive KAT pinning the think()
+    # Phase-1 desired-set walk bounds in think_p1_walk_bounds.hpp vs the p2pool
+    # data.py think() oracle (walk_count clamp min(5,max(0,h-CL)) / unrooted full
+    # height; inclusive prune threshold 2*CL+10). Pure arithmetic -> links only
+    # core. MUST also be in the build.yml --target allowlist (#143 NOT_BUILT trap).
+    add_executable(dgb_think_p1_walk_bounds_test think_p1_walk_bounds_test.cpp)
+    target_link_libraries(dgb_think_p1_walk_bounds_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_think_p1_walk_bounds_test "" AUTO)
+
 endif()

src/impl/dgb/test/think_p1_walk_bounds_test.cpp

@@ -0,0 +1,67 @@
+// dgb think() Phase-1 desired-set walk BOUNDS conformance KAT.
+//
+// FENCED, additive (no production code touched this slice). Pins
+// src/impl/dgb/think_p1_walk_bounds.hpp against the p2pool data.py think()
+// Phase-1 oracle for the two pure decisions per unverified head:
+//   walk_count = head_height                              if unrooted (no last)
+//              = min(5, max(0, head_height - CHAIN_LENGTH)) otherwise
+//   in_pruning_zone = head_height >= 2*CHAIN_LENGTH + 10   (inclusive)
+//
+// Expectations are HAND-DERIVED from the oracle formula, NOT read back from the
+// code under test — a conformance KAT that asks its subject for the answer
+// passes vacuously. Pure arithmetic: links only core (no chain standup). MUST
+// appear in BOTH this dir's CMakeLists.txt AND the build.yml --target allowlist,
+// or it becomes a #143 NOT_BUILT sentinel (compiled-out, silently "passing").
+
+#include <impl/dgb/think_p1_walk_bounds.hpp>
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+
+namespace {
+
+// ---- walk_count: unrooted head (has_last == false) → full accumulated height
+TEST(ThinkP1WalkBounds, UnrootedWalksFullHeight)
+{
+    EXPECT_EQ(dgb::think_p1_walk_count(0,   false, 10), 0);
+    EXPECT_EQ(dgb::think_p1_walk_count(1,   false, 10), 1);
+    EXPECT_EQ(dgb::think_p1_walk_count(3,   false, 10), 3);
+    EXPECT_EQ(dgb::think_p1_walk_count(100, false, 10), 100);
+    // chain_length must not influence the unrooted branch.
+    EXPECT_EQ(dgb::think_p1_walk_count(7,   false, 9999), 7);
+}
+
+// ---- walk_count: rooted head (has_last == true) → min(5, max(0, h - CL))
+TEST(ThinkP1WalkBounds, RootedClampsAtFiveFloorsAtZero)
+{
+    constexpr int32_t CL = 10;
+    // below/at CHAIN_LENGTH → floored to 0
+    EXPECT_EQ(dgb::think_p1_walk_count(8,  true, CL), 0);   // max(0,-2)=0
+    EXPECT_EQ(dgb::think_p1_walk_count(10, true, CL), 0);   // max(0, 0)=0 (boundary)
+    // between CL and CL+5 → exact difference
+    EXPECT_EQ(dgb::think_p1_walk_count(11, true, CL), 1);   // min(5,1)=1
+    EXPECT_EQ(dgb::think_p1_walk_count(12, true, CL), 2);   // min(5,2)=2
+    EXPECT_EQ(dgb::think_p1_walk_count(15, true, CL), 5);   // min(5,5)=5 (boundary)
+    // above CL+5 → clamped to 5
+    EXPECT_EQ(dgb::think_p1_walk_count(16, true, CL), 5);   // min(5,6)=5
+    EXPECT_EQ(dgb::think_p1_walk_count(20, true, CL), 5);   // min(5,10)=5
+    EXPECT_EQ(dgb::think_p1_walk_count(999, true, CL), 5);
+}
+
+// ---- pruning zone: inclusive threshold 2*CL + 10
+TEST(ThinkP1WalkBounds, PruningZoneInclusiveThreshold)
+{
+    constexpr int32_t CL = 10;            // threshold = 2*10 + 10 = 30
+    EXPECT_FALSE(dgb::think_p1_in_pruning_zone(0,  CL));
+    EXPECT_FALSE(dgb::think_p1_in_pruning_zone(29, CL));
+    EXPECT_TRUE (dgb::think_p1_in_pruning_zone(30, CL));   // inclusive lower bound
+    EXPECT_TRUE (dgb::think_p1_in_pruning_zone(31, CL));
+    EXPECT_TRUE (dgb::think_p1_in_pruning_zone(1000, CL));
+
+    constexpr int32_t CL2 = 24;           // threshold = 2*24 + 10 = 58
+    EXPECT_FALSE(dgb::think_p1_in_pruning_zone(57, CL2));
+    EXPECT_TRUE (dgb::think_p1_in_pruning_zone(58, CL2));
+}
+
+} // namespace

src/impl/dgb/think_p1_walk_bounds.hpp

@@ -0,0 +1,57 @@
+#pragma once
+
+// SSOT for the think() Phase-1 desired-set walk BOUNDS — the two pure integer
+// decisions that govern, per unverified sharechain head, (a) how far back to
+// walk attempting verification and (b) whether to skip emitting a parent
+// (desired) request because the head already sits in the prune zone.
+//
+// These two formulas are currently OPEN-CODED 2-3x inline in share_tracker.hpp
+// think() Phase 1 (the walk0 branch and the for/else branch each re-derive the
+// pruning threshold; the walk-count clamp carries the magic literal 5). A silent
+// drift between the duplicated copies — or against the p2pool oracle — would
+// change which parents a c2pool-dgb node requests during sync, with NO compile
+// error. Lifting them to a single header-only SSOT lets a KAT pin the exact
+// arithmetic (clamp at 5, floor at 0, inclusive prune threshold 2*CL+10).
+//
+// Oracle: p2pool data.py:2077-2108  OkayTracker.think(), per unverified head:
+//     # walk back at most a few shares trying to verify one
+//     to_test = self.get_chain(head, min(5, max(0, height - net.CHAIN_LENGTH)))
+//     ...
+//   and c2pool's node-local prune-zone guard: a head at/over
+//   2*CHAIN_LENGTH+10 has parents that clean_tracker would immediately re-prune,
+//   so no parent request is emitted for it.
+//
+// Per-coin isolation: dgb/ only. Header-only, additive; this slice does NOT yet
+// rewire share_tracker.hpp (that is the byte-identity-fenced delegation
+// follow-on) — it pins the bounds as free functions so the KAT exercises them
+// with no ShareTracker/NodeImpl standup. Consensus-neutral: pure arithmetic,
+// no value semantics changed.
+
+#include <algorithm>
+#include <cstdint>
+
+namespace dgb {
+
+// How far back think() Phase 1 walks from an unverified head attempting to
+// verify one share.
+//   has_last == false (unrooted head, no resolved segment): walk the full
+//       accumulated height.
+//   has_last == true: walk at most 5, and only the shares ABOVE CHAIN_LENGTH
+//       (max(0, height - CHAIN_LENGTH)) — older shares are already settled.
+inline int32_t think_p1_walk_count(int32_t head_height, bool has_last,
+                                   int32_t chain_length)
+{
+    if (!has_last)
+        return head_height;
+    return std::min(5, std::max(0, head_height - chain_length));
+}
+
+// Prune-zone guard (inclusive). A head whose accumulated height has reached
+// 2*CHAIN_LENGTH+10 will have any requested parent immediately re-pruned by
+// clean_tracker, so think() suppresses the parent (desired) request for it.
+inline bool think_p1_in_pruning_zone(int32_t head_height, int32_t chain_length)
+{
+    return head_height >= 2 * chain_length + 10;
+}
+
+} // namespace dgb