Merge bitcoin/bitcoin#27157: init: Return ChainstateLoadStatus::INTERRUPTED when verification was interrupted.

c5825e14f8999a8c5f5121027af9e07ac51ab42e doc: add explanation for fail_on_insufficient_dbcache (Ryan Ofsky)
7dff7da4f5eafa89546565a63362e57516e4064e init: Return more fitting ChainStateLoadStatus if verification was interrupted (Martin Zumsande)

Pull request description:

  This addresses two outstanding comments by ryanofsky from #25574:
  * return `ChainstateLoadStatus::INTERRUPTED` instead of `ChainstateLoadStatus::SUCCESS`  if verification was stopped by an interrupt. This would coincide with straightforward expectation, and it avoids a misleading [log entry](https://github.com/mzumsande/bitcoin/blob/c5825e14f8999a8c5f5121027af9e07ac51ab42e/src/init.cpp#L1526) in `init` for the block index load time (because that would include the verificiation, which didn't complete). It shouldn't affect node behavior otherwise because the shutdown signal would be caught in init anyway. In test, this would lead to an assert ([link](https://github.com/mzumsande/bitcoin/blob/c5825e14f8999a8c5f5121027af9e07ac51ab42e/src/test/util/setup_common.cpp#L230)), which also makes more sense because benign interrupts are not expected there during init.
  This can be tested by setting a large value for `-checkblocks`, interrupting the node during block verification and observing the log.
   https://github.com/bitcoin/bitcoin/pull/25574#discussion_r1110050930
  * add documentation for `require_full_verification` https://github.com/bitcoin/bitcoin/pull/25574#discussion_r1110031541

ACKs for top commit:
  MarcoFalke:
    thanks lgtm ACK c5825e14f8999a8c5f5121027af9e07ac51ab42e

Tree-SHA512: ca1c71a1b046d30083337dd9ef6d52e66fa1ac8c4ecd807716e4aa6a894179a81df41caee916fa30997fd6e0b284412a3c8f2919d19c29d826fb580ffb89fd73

2 files changed, 6 insertions, 1 deletions

diff --git a/src/node/chainstate.cpp b/src/node/chainstate.cpp
index 41c0ff2118..626010d26f 100644
--- a/src/node/chainstate.cpp
+++ b/src/node/chainstate.cpp
@@ -198,9 +198,10 @@ ChainstateLoadResult VerifyLoadedChainstate(ChainstateManager& chainman, const C
                 options.check_blocks);
             switch (result) {
             case VerifyDBResult::SUCCESS:
-            case VerifyDBResult::INTERRUPTED:
             case VerifyDBResult::SKIPPED_MISSING_BLOCKS:
                 break;
+            case VerifyDBResult::INTERRUPTED:
+                return {ChainstateLoadStatus::INTERRUPTED, _("Block verification was interrupted")};
             case VerifyDBResult::CORRUPTED_BLOCK_DB:
                 return {ChainstateLoadStatus::FAILURE, _("Corrupted block database detected")};
             case VerifyDBResult::SKIPPED_L3_CHECKS:
diff --git a/src/node/chainstate.h b/src/node/chainstate.h
index 7838a62d0c..77240cafe9 100644
--- a/src/node/chainstate.h
+++ b/src/node/chainstate.h
@@ -25,6 +25,10 @@ struct ChainstateLoadOptions {
     bool reindex{false};
     bool reindex_chainstate{false};
     bool prune{false};
+    //! Setting require_full_verification to true will require all checks at
+    //! check_level (below) to succeed for loading to succeed. Setting it to
+    //! false will skip checks if cache is not big enough to run them, so may be
+    //! helpful for running with a small cache.
     bool require_full_verification{true};
     int64_t check_blocks{DEFAULT_CHECKBLOCKS};
     int64_t check_level{DEFAULT_CHECKLEVEL};