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

c5825e1 doc: add explanation for fail_on_insufficient_dbcache (Ryan Ofsky)
7dff7da 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.
   bitcoin/bitcoin#25574 (comment)
  * add documentation for `require_full_verification` bitcoin/bitcoin#25574 (comment)

ACKs for top commit:
  MarcoFalke:
    thanks lgtm ACK c5825e1

Tree-SHA512: ca1c71a1b046d30083337dd9ef6d52e66fa1ac8c4ecd807716e4aa6a894179a81df41caee916fa30997fd6e0b284412a3c8f2919d19c29d826fb580ffb89fd73

Author: fanquake

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:

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};