doc: Improve ChainstateManager documentation, use consistent terms

ryanofsky · ryanofsky · commit 82be652e40ec · 2025-12-12T06:49:59.000-04:00
diff --git a/src/validation.cpp b/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
diff --git a/src/validation.h b/src/validation.h
@@ -756,9 +756,9 @@ class Chainstate
      * 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
-     * of the snapshot, its execution will take *MINUTES* while it hashes the
-     * background UTXO set to verify the assumeutxo value the snapshot was activated
+     * it is called on a validated chainstate whose tip has reached the base
+     * block of the snapshot, its execution will take *MINUTES* while it hashes
+     * 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
-    // chainstate.
+    // Failed to generate UTXO statistics (to check UTXO set hash) for the
+    // validated chainstate.
     STATS_FAILED,
 
-    // The UTXO set hash of the background validation chainstate does not match
-    // the one expected by assumeutxo chainparams.
+    // The UTXO set hash of the validated chainstate does not match the one
+    // expected by assumeutxo chainparams.
     HASH_MISMATCH,
 };
 
 /**
- * Provides an interface for creating and interacting with one or two
- * chainstates: an IBD chainstate generated by downloading blocks, and
- * an optional snapshot chainstate loaded from a UTXO snapshot. Managed
- * chainstates can be maintained at different heights simultaneously.
+ * Interface for managing multiple \ref Chainstate objects, where each
+ * chainstate is associated with chainstate* subdirectory in the data directory
+ * and contains a database of UTXOs existing at a different point in history.
+ * (See \ref Chainstate class for more information.)
  *
- * This class provides abstractions that allow the retrieval of the current
- * most-work chainstate ("Active") as well as chainstates which may be in
- * background use to validate UTXO snapshots.
+ * Normally there is exactly one Chainstate, which contains the UTXO set of
+ * chain tip if syncing is completed, or the UTXO set the most recent validated
+ * block if the initial sync is still in progress.
  *
- * Definitions:
- *
- * *IBD chainstate*: a chainstate whose current state has been "fully"
- *   validated by the initial block download process.
- *
- * *Snapshot chainstate*: a chainstate populated by loading in an
- *    assumeutxo UTXO snapshot.
- *
- * *Active chainstate*: the chainstate containing the current most-work
- *    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.
+ * However, if an assumeutxo snapshot is loaded before syncing is completed,
+ * there will be two chainstates. The original fully validated chainstate will
+ * continue to exist and download new blocks in the background. But the new
+ * 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
+ * it is only assumed to be valid. When the initial chainstate catches up to the
+ * snapshot height and confirms that the assumeutxo snapshot is actually valid,
+ * the second chainstate will be marked validated and become the only chainstate
+ * again.
  */
 class ChainstateManager
 {

Original file line number	Diff line number	Diff line change
`@@ -6120,7 +6120,7 @@ SnapshotCompletionResult ChainstateManager::MaybeValidateSnapshot(Chainstate& va`
`6120`	`6120`	`return SnapshotCompletionResult::STATS_FAILED;`
`6121`	`6121`	`}`
`6122`	`6122`
`6123`		`- // Compare the background validation chainstate's UTXO set hash against the hard-coded`
	`6123`	`+ // Compare the validated chainstate's UTXO set hash against the hard-coded`
`6124`	`6124`	`// assumeutxo hash we expect.`
`6125`	`6125`	`//`
`6126`	`6126`	`// TODO: For belt-and-suspenders, we could cache the UTXO set`