diff --git a/src/validation.cpp b/src/validation.cpp index 9ecfdfa1b1a..2052748343a 100644 --- 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 index e810e872e87..77958b53dd1 100644 --- a/src/validation.h +++ b/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 - * 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 {