Merge bitcoin/bitcoin#34642: wallet: call SyncWithValidationInterfaceQueue after disconnecting chain notifications

98e8af4bb991fd8edeb15c0fb8afa66bff6b5cac wallet: Drain validation interface queue after notifications disconnect (Ava Chow)
52992ebe1c55c8f7219b824f05d22fbc18acb794 interfaces: Add waitForNotifications() to call SyncWithValidationInterfaceQueue() (Ava Chow)

Pull request description:

  When the wallet disconnects chain notifications, it is expecting no further notifications to execute, but this is not the case. This results in test failures such as in #34354. Instead of disconnecting the notifications and continuing shutdown, we should wait for the validation interface queue to be drained before the rest of wallet shutdown. This is achieved by adding an `interfaces::Chain::waitForNotifications()` function which calls `SyncWithValidationInterfaceQueue()`.

  Fixes #34354

ACKs for top commit:
  stickies-v:
    utACK 98e8af4bb991fd8edeb15c0fb8afa66bff6b5cac
  furszy:
    ACK 98e8af4bb991fd8edeb15c0fb8afa66bff6b5cac
  rkrux:
    crACK 98e8af4bb991fd8edeb15c0fb8afa66bff6b5cac
  sedited:
    ACK 98e8af4bb991fd8edeb15c0fb8afa66bff6b5cac

Tree-SHA512: 263628556f740cb633d3970c22a0dfdb52a644bd1d0cd5a69c2970524edbb0e25d592cb39fc9bf1d0c281eebce09578526e2958dffee9026fc7473db35bd0dec

src/interfaces/chain.h

@@ -326,12 +326,18 @@ public:
     };
 
     //! Register handler for notifications.
+    //! Some notifications are asynchronous and may still execute after the handler is disconnected.
+    //! Use waitForNotifications() after the handler is disconnected to ensure all pending notifications
+    //! have been processed.
     virtual std::unique_ptr<Handler> handleNotifications(std::shared_ptr<Notifications> notifications) = 0;
 
     //! Wait for pending notifications to be processed unless block hash points to the current
     //! chain tip.
     virtual void waitForNotificationsIfTipChanged(const uint256& old_tip) = 0;
 
+    //! Wait for all pending notifications up to this point to be processed
+    virtual void waitForNotifications() = 0;
+
     //! Register handler for RPC. Command is not copied, so reference
     //! needs to remain valid until Handler is disconnected.
     virtual std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) = 0;

src/node/interfaces.cpp

@@ -785,6 +785,10 @@ public:
         if (!old_tip.IsNull() && old_tip == WITH_LOCK(::cs_main, return chainman().ActiveChain().Tip()->GetBlockHash())) return;
         validation_signals().SyncWithValidationInterfaceQueue();
     }
+    void waitForNotifications() override
+    {
+        validation_signals().SyncWithValidationInterfaceQueue();
+    }
     std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) override
     {
         return std::make_unique<RpcHandlerImpl>(command);

src/wallet/wallet.cpp

@@ -169,7 +169,7 @@ bool RemoveWallet(WalletContext& context, const std::shared_ptr<CWallet>& wallet
     WITH_LOCK(wallet->cs_wallet, wallet->WriteBestBlock());
 
     // Unregister with the validation interface which also drops shared pointers.
-    wallet->m_chain_notifications_handler.reset();
+    wallet->DisconnectChainNotifications();
     {
         LOCK(context.wallets_mutex);
         std::vector<std::shared_ptr<CWallet>>::iterator i = std::find(context.wallets.begin(), context.wallets.end(), wallet);
@@ -3117,7 +3117,7 @@ std::shared_ptr<CWallet> CWallet::CreateNew(WalletContext& context, const std::s
     walletInstance->TopUpKeyPool();
 
     if (chain && !AttachChain(walletInstance, *chain, /*rescan_required=*/false, error, warnings)) {
-        walletInstance->m_chain_notifications_handler.reset(); // Reset this pointer so that the wallet will actually be unloaded
+        walletInstance->DisconnectChainNotifications();
         return nullptr;
     }
 
@@ -3158,7 +3158,7 @@ std::shared_ptr<CWallet> CWallet::LoadExisting(WalletContext& context, const std
     walletInstance->TopUpKeyPool();
 
     if (chain && !AttachChain(walletInstance, *chain, rescan_required, error, warnings)) {
-        walletInstance->m_chain_notifications_handler.reset(); // Reset this pointer so that the wallet will actually be unloaded
+        walletInstance->DisconnectChainNotifications();
         return nullptr;
     }
 
@@ -4577,4 +4577,14 @@ std::optional<WalletTXO> CWallet::GetTXO(const COutPoint& outpoint) const
     }
     return it->second;
 }
+
+void CWallet::DisconnectChainNotifications()
+{
+    if (m_chain_notifications_handler) {
+        m_chain_notifications_handler->disconnect();
+        chain().waitForNotifications();
+        m_chain_notifications_handler.reset();
+    }
+}
+
 } // namespace wallet

src/wallet/wallet.h

@@ -1072,6 +1072,9 @@ public:
     //! Find the private key for the given key id from the wallet's descriptors, if available
     //! Returns nullopt when no descriptor has the key or if the wallet is locked.
     std::optional<CKey> GetKey(const CKeyID& keyid) const;
+
+    //! Disconnect chain notifications and wait for all notifications to be processed
+    void DisconnectChainNotifications();
 };
 
 /**