From ce610a6ff445bb8a812e650c91f501a1ecf0b19c Mon Sep 17 00:00:00 2001
From: Andrew Toth <andrewstoth@gmail.com>
Date: Sat, 7 Mar 2026 14:41:12 -0500
Subject: [PATCH] fuzz: update harnesses to cover
 CoinsViewOverlay::StartFetching

Co-authored-by: l0rinc <pap.lorinc@gmail.com>
Co-authored-by: sedited <seb.kung@gmail.com>
---
 src/test/fuzz/coins_view.cpp     | 61 ++++++++++++++++++++++++++++++--
 src/test/fuzz/coinscache_sim.cpp | 58 ++++++++++++++++++++++++------
 2 files changed, 107 insertions(+), 12 deletions(-)

diff --git a/src/test/fuzz/coins_view.cpp b/src/test/fuzz/coins_view.cpp
index 62e577fd186..62f7461442d 100644
--- a/src/test/fuzz/coins_view.cpp
+++ b/src/test/fuzz/coins_view.cpp
@@ -10,6 +10,7 @@
 #include <kernel/chainstatemanager_opts.h>
 #include <kernel/cs_main.h>
 #include <policy/policy.h>
+#include <primitives/block.h>
 #include <primitives/transaction.h>
 #include <script/interpreter.h>
 #include <test/fuzz/FuzzedDataProvider.h>
@@ -92,6 +93,46 @@ public:
 std::shared_ptr<ThreadPool> g_thread_pool{std::make_shared<ThreadPool>("view_fuzz")};
 Mutex g_thread_pool_mutex;
 
+void StartPoolIfNeeded() EXCLUSIVE_LOCKS_REQUIRED(!g_thread_pool_mutex)
+{
+    LOCK(g_thread_pool_mutex);
+    if (!g_thread_pool->WorkersCount()) g_thread_pool->Start(DEFAULT_PREVOUTFETCH_THREADS);
+}
+
+//! Build a random block and seed a view with utxos for its inputs.
+CBlock BuildRandomBlock(FuzzedDataProvider& fuzzed_data_provider, CCoinsView& view)
+{
+    CBlock block;
+    CMutableTransaction coinbase;
+    coinbase.vin.emplace_back();
+    block.vtx.push_back(MakeTransactionRef(coinbase));
+
+    CCoinsViewCache seed_cache{&view, /*deterministic=*/true};
+    seed_cache.SetBestBlock(uint256::ONE);
+
+    Txid prevhash{Txid::FromUint256(ConsumeUInt256(fuzzed_data_provider))};
+    LIMITED_WHILE(fuzzed_data_provider.ConsumeBool(), 100)
+    {
+        CMutableTransaction tx;
+        LIMITED_WHILE(fuzzed_data_provider.ConsumeBool(), 100)
+        {
+            const Txid txid{fuzzed_data_provider.ConsumeBool()
+                                ? Txid::FromUint256(ConsumeUInt256(fuzzed_data_provider))
+                                : prevhash};
+            const COutPoint outpoint{txid, fuzzed_data_provider.ConsumeIntegral<uint32_t>()};
+            if (auto coin{ConsumeDeserializable<Coin>(fuzzed_data_provider)}; coin && !coin->IsSpent()) {
+                seed_cache.AddCoin(outpoint, std::move(*coin), /*possible_overwrite=*/true);
+            }
+            tx.vin.emplace_back(outpoint);
+        }
+        prevhash = tx.GetHash();
+        block.vtx.push_back(MakeTransactionRef(tx));
+    }
+
+    seed_cache.Flush();
+    return block;
+}
+
 } // namespace
 
 void initialize_coins_view()
@@ -102,6 +143,7 @@ void initialize_coins_view()
 void TestCoinsView(FuzzedDataProvider& fuzzed_data_provider, CCoinsViewCache& coins_view_cache, CCoinsView* backend_coins_view)
 {
     auto* const db{dynamic_cast<CCoinsViewDB*>(backend_coins_view)};
+    auto* const overlay{dynamic_cast<CoinsViewOverlay*>(&coins_view_cache)};
     const bool is_db{db != nullptr};
     bool good_data{true};
     auto* original_backend{backend_coins_view};
@@ -129,9 +171,11 @@ void TestCoinsView(FuzzedDataProvider& fuzzed_data_provider, CCoinsViewCache& co
                 }
             },
             [&] {
+                if (overlay && !overlay->AllInputsConsumed()) return; // CoinsViewOverlay::Flush() must have all inputs consumed before being called
                 coins_view_cache.Flush(/*reallocate_cache=*/fuzzed_data_provider.ConsumeBool());
             },
             [&] {
+                if (overlay) return; // CoinsViewOverlay::Sync() is never called in production code
                 coins_view_cache.Sync();
             },
             [&] {
@@ -163,6 +207,7 @@ void TestCoinsView(FuzzedDataProvider& fuzzed_data_provider, CCoinsViewCache& co
                 coins_view_cache.Uncache(random_out_point);
             },
             [&] {
+                if (overlay) return; // // CoinsViewOverlay::SetBackend() is never called in production code
                 const bool use_original_backend{fuzzed_data_provider.ConsumeBool()};
                 if (use_original_backend && backend_coins_view != original_backend) {
                     // FRESH flags valid against the empty backend may be invalid
@@ -346,11 +391,20 @@ void TestCoinsView(FuzzedDataProvider& fuzzed_data_provider, CCoinsViewCache& co
             assert(!exists_using_access_coin && !exists_using_have_coin_in_cache && !exists_using_have_coin);
         }
         // If HaveCoin on the backend is true, it must also be on the cache if the coin wasn't spent.
-        const bool exists_using_have_coin_in_backend = backend_coins_view->HaveCoin(random_out_point);
+        std::optional<Coin> coin_in_backend;
+        bool exists_using_have_coin_in_backend;
+        if (dynamic_cast<CoinsViewOverlay*>(&coins_view_cache)) {
+            // PeekCoin does not mutate cacheCoins, so async workers can keep running.
+            coin_in_backend = backend_coins_view->PeekCoin(random_out_point);
+            exists_using_have_coin_in_backend = coin_in_backend.has_value();
+        } else {
+            exists_using_have_coin_in_backend = backend_coins_view->HaveCoin(random_out_point);
+            coin_in_backend = backend_coins_view->GetCoin(random_out_point);
+        }
         if (!coin_using_access_coin.IsSpent() && exists_using_have_coin_in_backend) {
             assert(exists_using_have_coin);
         }
-        if (auto coin{backend_coins_view->GetCoin(random_out_point)}) {
+        if (coin_in_backend) {
             assert(exists_using_have_coin_in_backend);
             // Note we can't assert that `coin_using_get_coin == *coin` because the coin in
             // the cache may have been modified but not yet flushed.
@@ -387,8 +441,11 @@ FUZZ_TARGET(coins_view_db, .init = initialize_coins_view)
 FUZZ_TARGET(coins_view_overlay, .init = initialize_coins_view) EXCLUSIVE_LOCKS_REQUIRED(!g_thread_pool_mutex)
 {
     SeedRandomStateForTest(SeedRand::ZEROS); // for SaltedTxidHasher
+    StartPoolIfNeeded();
     FuzzedDataProvider fuzzed_data_provider{buffer.data(), buffer.size()};
     MutationGuardCoinsViewCache backend_cache{&CoinsViewEmpty::Get(), /*deterministic=*/true};
     CoinsViewOverlay coins_view_cache{&backend_cache, g_thread_pool, /*deterministic=*/true};
+    CBlock block{BuildRandomBlock(fuzzed_data_provider, backend_cache)};
+    const auto reset_guard{coins_view_cache.StartFetching(block)};
     TestCoinsView(fuzzed_data_provider, coins_view_cache, &backend_cache);
 }
diff --git a/src/test/fuzz/coinscache_sim.cpp b/src/test/fuzz/coinscache_sim.cpp
index 24a0327d7d1..f101b9a5ebb 100644
--- a/src/test/fuzz/coinscache_sim.cpp
+++ b/src/test/fuzz/coinscache_sim.cpp
@@ -5,6 +5,7 @@
 #include <coins.h>
 #include <crypto/sha256.h>
 #include <kernel/chainstatemanager_opts.h>
+#include <primitives/block.h>
 #include <primitives/transaction.h>
 #include <test/fuzz/FuzzedDataProvider.h>
 #include <test/fuzz/fuzz.h>
@@ -37,12 +38,20 @@ struct PrecomputedData
     //! Randomly generated Coin values.
     Coin coins[NUM_COINS];
 
+    //! Block with a tx containing as inputs the above outpoints.
+    CBlock block;
+
     PrecomputedData()
     {
         static const uint8_t PREFIX_O[1] = {'o'}; /** Hash prefix for outpoint hashes. */
         static const uint8_t PREFIX_S[1] = {'s'}; /** Hash prefix for coins scriptPubKeys. */
         static const uint8_t PREFIX_M[1] = {'m'}; /** Hash prefix for coins nValue/fCoinBase. */
 
+        CMutableTransaction coinbase;
+        coinbase.vin.emplace_back();
+        block.vtx.push_back(MakeTransactionRef(coinbase));
+
+        CMutableTransaction tx;
         for (uint32_t i = 0; i < NUM_OUTPOINTS; ++i) {
             uint32_t idx = (i * 1200U) >> 12; /* Map 3 or 4 entries to same txid. */
             const uint8_t ser[4] = {uint8_t(idx), uint8_t(idx >> 8), uint8_t(idx >> 16), uint8_t(idx >> 24)};
@@ -50,7 +59,9 @@ struct PrecomputedData
             CSHA256().Write(PREFIX_O, 1).Write(ser, sizeof(ser)).Finalize(txid.begin());
             outpoints[i].hash = Txid::FromUint256(txid);
             outpoints[i].n = i;
+            tx.vin.emplace_back(outpoints[i]);
         }
+        block.vtx.push_back(MakeTransactionRef(tx));
 
         for (uint32_t i = 0; i < NUM_COINS; ++i) {
             const uint8_t ser[4] = {uint8_t(i), uint8_t(i >> 8), uint8_t(i >> 16), uint8_t(i >> 24)};
@@ -185,6 +196,14 @@ public:
     }
 };
 
+// Hold a non-movable ResetGuard on the heap so StartFetching can remain active
+// for the lifetime of a CoinsViewOverlay cache level.
+struct OverlayFetchScope
+{
+    CCoinsViewCache::ResetGuard guard;
+    OverlayFetchScope(CoinsViewOverlay& view, const CBlock& block) : guard(view.StartFetching(block)) {}
+};
+
 // Reuse a single global thread pool across fuzz iterations. Creating and destroying a pool every
 // iteration leaks memory, since iterations can run faster than the OS can tear down the threads.
 std::shared_ptr<ThreadPool> g_thread_pool{std::make_shared<ThreadPool>("cache_fuzz")};
@@ -200,6 +219,7 @@ void StartPoolIfNeeded() EXCLUSIVE_LOCKS_REQUIRED(!g_thread_pool_mutex)
 
 FUZZ_TARGET(coinscache_sim, .init = [] { static auto setup{MakeNoLogFileContext<>()}; }) EXCLUSIVE_LOCKS_REQUIRED(!g_thread_pool_mutex)
 {
+    SeedRandomStateForTest(SeedRand::ZEROS);
     StartPoolIfNeeded();
     /** Precomputed COutPoint and CCoins values. */
     static const PrecomputedData data;
@@ -208,6 +228,8 @@ FUZZ_TARGET(coinscache_sim, .init = [] { static auto setup{MakeNoLogFileContext<
     CoinsViewBottom bottom;
     /** Real CCoinsViewCache objects. */
     std::vector<std::unique_ptr<CCoinsViewCache>> caches;
+    /** Long-lived StartFetching guard (nullptr unless corresponding level is a CoinsViewOverlay). */
+    std::unique_ptr<OverlayFetchScope> overlay_fetch_scope;
     /** Simulated cache data (sim_caches[0] matches bottom, sim_caches[i+1] matches caches[i]). */
     CacheLevel sim_caches[MAX_CACHES + 1];
     /** Current height in the simulation. */
@@ -383,11 +405,17 @@ FUZZ_TARGET(coinscache_sim, .init = [] { static auto setup{MakeNoLogFileContext<
 
             [&]() { // Add a cache level (if not already at the max).
                 if (caches.size() != MAX_CACHES) {
+                    if (overlay_fetch_scope) {
+                        overlay_fetch_scope.reset();
+                        sim_caches[caches.size()].Wipe();
+                    }
                     // Apply to real caches.
                     if (provider.ConsumeBool()) {
                         caches.emplace_back(new CCoinsViewCache(&*caches.back(), /*deterministic=*/true));
                     } else {
                         caches.emplace_back(new CoinsViewOverlay(&*caches.back(), g_thread_pool, /*deterministic=*/true));
+                        auto& overlay{static_cast<CoinsViewOverlay&>(*caches.back())};
+                        overlay_fetch_scope = std::make_unique<OverlayFetchScope>(overlay, data.block);
                     }
                     // Apply to simulation data.
                     sim_caches[caches.size()].Wipe();
@@ -397,10 +425,16 @@ FUZZ_TARGET(coinscache_sim, .init = [] { static auto setup{MakeNoLogFileContext<
             [&]() { // Remove a cache level.
                 // Apply to real caches (this reduces caches.size(), implicitly doing the same on the simulation data).
                 caches.back()->SanityCheck();
+                overlay_fetch_scope.reset();
                 caches.pop_back();
             },
 
             [&]() { // Flush.
+                // CoinsViewOverlay::Flush() must have all inputs consumed before being called
+                if (auto* overlay{dynamic_cast<CoinsViewOverlay*>(caches.back().get())};
+                    overlay && !overlay->AllInputsConsumed()) {
+                    return;
+                }
                 // Apply to simulation data.
                 flush();
                 // Apply to real caches.
@@ -408,6 +442,7 @@ FUZZ_TARGET(coinscache_sim, .init = [] { static auto setup{MakeNoLogFileContext<
             },
 
             [&]() { // Sync.
+                if (overlay_fetch_scope) return; // CoinsViewOverlay::Sync() is never called in production
                 // Apply to simulation data (note that in our simulation, syncing and flushing is the same thing).
                 flush();
                 // Apply to real caches.
@@ -416,9 +451,13 @@ FUZZ_TARGET(coinscache_sim, .init = [] { static auto setup{MakeNoLogFileContext<
 
             [&]() { // Reset.
                 sim_caches[caches.size()].Wipe();
-                // Apply to real caches.
-                {
-                    const auto reset_guard{caches.back()->CreateResetGuard()};
+                // Apply to real caches. Optionally start fetching again.
+                if (overlay_fetch_scope && provider.ConsumeBool()) {
+                    overlay_fetch_scope.reset();
+                    auto& overlay{static_cast<CoinsViewOverlay&>(*caches.back())};
+                    overlay_fetch_scope = std::make_unique<OverlayFetchScope>(overlay, data.block);
+                } else {
+                    (void)caches.back()->CreateResetGuard();
                 }
             },
 
@@ -442,22 +481,21 @@ FUZZ_TARGET(coinscache_sim, .init = [] { static auto setup{MakeNoLogFileContext<
     }
 
     // Full comparison between caches and simulation data, from bottom to top,
-    // as AccessCoin on a higher cache may affect caches below it.
     for (unsigned sim_idx = 1; sim_idx <= caches.size(); ++sim_idx) {
         auto& cache = *caches[sim_idx - 1];
         size_t cache_size = 0;
 
         for (uint32_t outpointidx = 0; outpointidx < NUM_OUTPOINTS; ++outpointidx) {
             cache_size += cache.HaveCoinInCache(data.outpoints[outpointidx]);
-            const auto& real = cache.AccessCoin(data.outpoints[outpointidx]);
+            const auto real{cache.PeekCoin(data.outpoints[outpointidx])};
             auto sim = lookup(outpointidx, sim_idx);
             if (!sim.has_value()) {
-                assert(real.IsSpent());
+                assert(!real);
             } else {
-                assert(!real.IsSpent());
-                assert(real.out == data.coins[sim->first].out);
-                assert(real.fCoinBase == data.coins[sim->first].fCoinBase);
-                assert(real.nHeight == sim->second);
+                assert(!real->IsSpent());
+                assert(real->out == data.coins[sim->first].out);
+                assert(real->fCoinBase == data.coins[sim->first].fCoinBase);
+                assert(real->nHeight == sim->second);
             }
         }