doc: Add and edit some comments around assumeutxo

Co-authored-by: Ryan Ofsky <[email protected]>

src/net_processing.cpp

@@ -1931,6 +1931,8 @@ void PeerManagerImpl::BlockConnected(
         }
     }
 
+    // The following task can be skipped since we don't maintain a mempool for
+    // the ibd/background chainstate.
     if (role == ChainstateRole::BACKGROUND) {
         return;
     }

src/rpc/blockchain.cpp

@@ -2855,6 +2855,9 @@ return RPCHelpMan{
         return data;
     };
 
+    // We present the IBD/background chainstate as "normal" to users, since
+    // it should not matter to them if there is also a snapshot chainstate.
+    // To users, the IBD chainstate should always be considered "normal".
     if (chainman.GetAll().size() > 1) {
         for (Chainstate* chainstate : chainman.GetAll()) {
             obj.pushKV(

src/validation.cpp

@@ -68,8 +68,8 @@
 #include <numeric>
 #include <optional>
 #include <string>
-#include <utility>
 #include <tuple>
+#include <utility>
 
 using kernel::CCoinsStats;
 using kernel::CoinStatsHashType;
@@ -5361,7 +5361,7 @@ bool ChainstateManager::PopulateAndValidateSnapshot(
     // ActivateSnapshot(), but is done so that we avoid doing the long work of staging
     // a snapshot that isn't actually usable.
     if (WITH_LOCK(::cs_main, return !CBlockIndexWorkComparator()(ActiveTip(), snapshot_start_block))) {
-        LogPrintf("[snapshot] activation failed - height does not exceed active chainstate\n");
+        LogPrintf("[snapshot] activation failed - work does not exceed active chainstate\n");
         return false;
     }
 

src/validation.h

@@ -836,9 +836,10 @@ class ChainstateManager
     //! Once this pointer is set to a corresponding chainstate, it will not
     //! be reset until init.cpp:Shutdown().
     //!
-    //! This is especially important when, e.g., calling ActivateBestChain()
-    //! on all chainstates because we are not able to hold ::cs_main going into
-    //! that call.
+    //! It is important for the pointer to not be deleted until shutdown,
+    //! because cs_main is not always held when the pointer is accessed, for
+    //! example when calling ActivateBestChain, so there's no way you could
+    //! prevent code from using the pointer while deleting it.
     std::unique_ptr<Chainstate> m_ibd_chainstate GUARDED_BY(::cs_main);
 
     //! A chainstate initialized on the basis of a UTXO snapshot. If this is
@@ -847,17 +848,14 @@ class ChainstateManager
     //! Once this pointer is set to a corresponding chainstate, it will not
     //! be reset until init.cpp:Shutdown().
     //!
-    //! This is especially important when, e.g., calling ActivateBestChain()
-    //! on all chainstates because we are not able to hold ::cs_main going into
-    //! that call.
+    //! It is important for the pointer to not be deleted until shutdown,
+    //! because cs_main is not always held when the pointer is accessed, for
+    //! example when calling ActivateBestChain, so there's no way you could
+    //! prevent code from using the pointer while deleting it.
     std::unique_ptr<Chainstate> m_snapshot_chainstate GUARDED_BY(::cs_main);
 
     //! Points to either the ibd or snapshot chainstate; indicates our
     //! most-work chain.
-    //!
-    //! This is especially important when, e.g., calling ActivateBestChain()
-    //! on all chainstates because we are not able to hold ::cs_main going into
-    //! that call.
     Chainstate* m_active_chainstate GUARDED_BY(::cs_main) {nullptr};
 
     CBlockIndex* m_best_invalid GUARDED_BY(::cs_main){nullptr};