doc: Improve ChainstateManager documentation, use consistent terms

src/validation.cpp

@@ -6120,7 +6120,7 @@ SnapshotCompletionResult ChainstateManager::MaybeValidateSnapshot(Chainstate& va
         return SnapshotCompletionResult::STATS_FAILED;
     }
 
-    // Compare the background validation chainstate's UTXO set hash against the hard-coded
+    // Compare the validated chainstate's UTXO set hash against the hard-coded
     // assumeutxo hash we expect.
     //
     // TODO: For belt-and-suspenders, we could cache the UTXO set

src/validation.h

@@ -756,9 +756,9 @@ public:
      * validationinterface callback.
      *
      * Note that if this is called while a snapshot chainstate is active, and if
-     * it is called on a background chainstate whose tip has reached the base block
+     * it is called on a validated chainstate whose tip has reached the base
-     * of the snapshot, its execution will take *MINUTES* while it hashes the
+     * block of the snapshot, its execution will take *MINUTES* while it hashes
-     * background UTXO set to verify the assumeutxo value the snapshot was activated
+     * the UTXO set to verify the assumeutxo value the snapshot was activated
      * with. `cs_main` will be held during this time.
      *
      * @returns true unless a system error occurred
@@ -897,41 +897,34 @@ enum class SnapshotCompletionResult {
     // base block.
     MISSING_CHAINPARAMS,
 
-    // Failed to generate UTXO statistics (to check UTXO set hash) for the background
+    // Failed to generate UTXO statistics (to check UTXO set hash) for the
-    // chainstate.
+    // validated chainstate.
     STATS_FAILED,
 
-    // The UTXO set hash of the background validation chainstate does not match
+    // The UTXO set hash of the validated chainstate does not match the one
-    // the one expected by assumeutxo chainparams.
+    // expected by assumeutxo chainparams.
     HASH_MISMATCH,
 };
 
 /**
- * Provides an interface for creating and interacting with one or two
+ * Interface for managing multiple \ref Chainstate objects, where each
- * chainstates: an IBD chainstate generated by downloading blocks, and
+ * chainstate is associated with chainstate* subdirectory in the data directory
- * an optional snapshot chainstate loaded from a UTXO snapshot. Managed
+ * and contains a database of UTXOs existing at a different point in history.
- * chainstates can be maintained at different heights simultaneously.
+ * (See \ref Chainstate class for more information.)
  *
- * This class provides abstractions that allow the retrieval of the current
+ * Normally there is exactly one Chainstate, which contains the UTXO set of
- * most-work chainstate ("Active") as well as chainstates which may be in
+ * chain tip if syncing is completed, or the UTXO set the most recent validated
- * background use to validate UTXO snapshots.
+ * block if the initial sync is still in progress.
  *
- * Definitions:
+ * However, if an assumeutxo snapshot is loaded before syncing is completed,
- *
+ * there will be two chainstates. The original fully validated chainstate will
- * *IBD chainstate*: a chainstate whose current state has been "fully"
+ * continue to exist and download new blocks in the background. But the new
- *   validated by the initial block download process.
+ * snapshot which is loaded will become a second chainstate. The second
- *
+ * chainstate will be used as the chain tip for the wallet and RPCs even though
- * *Snapshot chainstate*: a chainstate populated by loading in an
+ * it is only assumed to be valid. When the initial chainstate catches up to the
- *    assumeutxo UTXO snapshot.
+ * snapshot height and confirms that the assumeutxo snapshot is actually valid,
- *
+ * the second chainstate will be marked validated and become the only chainstate
- * *Active chainstate*: the chainstate containing the current most-work
+ * again.
- *    chain. Consulted by most parts of the system (net_processing,
- *    wallet) as a reflection of the current chain and UTXO set.
- *    This may either be an IBD chainstate or a snapshot chainstate.
- *
- * *Background IBD chainstate*: an IBD chainstate for which the
- *    IBD process is happening in the background while use of the
- *    active (snapshot) chainstate allows the rest of the system to function.
  */
 class ChainstateManager
 {