gui: add sync overlay and out-of-sync action guards

Add a SyncOverlay widget that covers the main window while the wallet
is catching up, preventing users from attempting operations that require
an up-to-date chain state. The overlay shows sync progress and can be
permanently dismissed for the session via a "Hide" button.

Even after dismissing the overlay, per-action guards remain in place:
- Beacon wizard: blocked with a warning dialog
- Voting page: blocked with a warning dialog
- Send coins: warned with a Yes/No confirmation (allows proceeding)

This addresses a common support issue where users attempt to set up
beacons or vote before their wallet has finished synchronizing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jamescowens

src/qt/CMakeLists.txt

@@ -78,6 +78,7 @@ add_library(gridcoinqt STATIC
     researcher/researcherwizardsummarypage.cpp
     rpcconsole.cpp
     sendcoinsdialog.cpp
+    syncoverlay.cpp
     sendcoinsentry.cpp
     sidestaketablemodel.cpp
     signverifymessagedialog.cpp

src/qt/bitcoingui.cpp

@@ -45,6 +45,7 @@
 #include "upgradeqt.h"
 #include "voting/votingmodel.h"
 #include "voting/polltablemodel.h"
+#include "syncoverlay.h"
 #include "updatedialog.h"
 
 #ifdef Q_OS_MAC
@@ -110,6 +111,8 @@ BitcoinGUI::BitcoinGUI(QWidget* parent)
         , trayIcon(nullptr)
         , notificator(nullptr)
         , rpcConsole(nullptr)
+        , m_sync_overlay(nullptr)
+        , m_in_sync(false)
         , nWeight(0)
 {
     QSettings settings;
@@ -216,6 +219,11 @@ BitcoinGUI::BitcoinGUI(QWidget* parent)
 
     setCentralWidget(centralWidget);
 
+    // Create sync overlay — sits on top of the central widget and blocks
+    // interaction until the wallet is in sync (or the user dismisses it).
+    m_sync_overlay = new SyncOverlay(centralWidget);
+    m_sync_overlay->setVisible(true);
+
     // Create status bar
     statusBar();
 
@@ -1078,13 +1086,14 @@ void BitcoinGUI::setNumBlocks(int count, int nTotalBlocks)
     // Note: It is a really good question why the GUI uses a different standard than the core for determining whether
     // the client is in sync.
     // TODO: Review this and decide whether to converge the sync standards.
-    bool in_sync = false;
 
     // return if we have no connection to the network
     if (!clientModel || clientModel->getNumConnections() == 0)
     {
         labelBlocksIcon->setPixmap(GRC::ScaleStatusIcon(this, ":/icons/status_sync_stalled_" + sSheet));
         labelBlocksIcon->setToolTip(tr("Sync: no connections."));
+        m_in_sync = false;
+        m_sync_overlay->setSyncState(true, 0, 0);
         return;
     }
 
@@ -1123,7 +1132,7 @@ void BitcoinGUI::setNumBlocks(int count, int nTotalBlocks)
         labelBlocksIcon->setPixmap(GRC::ScaleStatusIcon(this, ":/icons/status_sync_done_" + sSheet));
 
         overviewPage->showOutOfSyncWarning(false);
-        in_sync = true;
+        m_in_sync = true;
         statusbarAlertsLabel->setText(clientModel->getStatusBarWarnings());
     }
     else
@@ -1132,9 +1141,11 @@ void BitcoinGUI::setNumBlocks(int count, int nTotalBlocks)
         tooltip = tr("Catching up...") + QString("<br>") + tooltip;
 
         overviewPage->showOutOfSyncWarning(true);
-        in_sync = false;
+        m_in_sync = false;
     }
 
+    m_sync_overlay->setSyncState(!m_in_sync, count, nTotalBlocks);
+
     if(!text.isEmpty())
     {
         tooltip += QString("<br>");
@@ -1145,7 +1156,7 @@ void BitcoinGUI::setNumBlocks(int count, int nTotalBlocks)
     tooltip = QString("<nobr>") + tooltip + QString("</nobr>");
 
     labelBlocksIcon->setToolTip(tooltip);
-    overviewPage->setHeight(count, nTotalBlocks, in_sync);
+    overviewPage->setHeight(count, nTotalBlocks, m_in_sync);
 }
 
 void BitcoinGUI::setDifficulty(double difficulty)
@@ -1471,6 +1482,18 @@ void BitcoinGUI::peersClicked()
         rpcConsole->showPeersTab();
 }
 
+void BitcoinGUI::recheckCurrentTabAction()
+{
+    QWidget* current = centralWidget->currentWidget();
+
+    if (current == overviewPage)        overviewAction->setChecked(true);
+    else if (current == sendCoinsPage)  sendCoinsAction->setChecked(true);
+    else if (current == receiveCoinsPage) receiveCoinsAction->setChecked(true);
+    else if (current == transactionView) historyAction->setChecked(true);
+    else if (current == addressBookPage) addressBookAction->setChecked(true);
+    else if (current == votingPage)     votingAction->setChecked(true);
+}
+
 void BitcoinGUI::gotoOverviewPage()
 {
     overviewAction->setChecked(true);
@@ -1519,6 +1542,22 @@ void BitcoinGUI::gotoReceiveCoinsPage()
 
 void BitcoinGUI::gotoSendCoinsPage()
 {
+    if (!m_in_sync) {
+        QMessageBox::StandardButton reply = QMessageBox::warning(this,
+            tr("Wallet Not In Sync"),
+            tr("The wallet is not yet in sync with the network. Your balance "
+               "may be inaccurate, and transactions created while out of sync "
+               "may not confirm properly.\n\n"
+               "Are you sure you want to proceed?"),
+            QMessageBox::Yes | QMessageBox::No,
+            QMessageBox::No);
+
+        if (reply != QMessageBox::Yes) {
+            recheckCurrentTabAction();
+            return;
+        }
+    }
+
     sendCoinsAction->setChecked(true);
     centralWidget->setCurrentWidget(sendCoinsPage);
 
@@ -1528,6 +1567,15 @@ void BitcoinGUI::gotoSendCoinsPage()
 
 void BitcoinGUI::gotoVotingPage()
 {
+    if (!m_in_sync) {
+        QMessageBox::warning(this,
+            tr("Wallet Not In Sync"),
+            tr("The wallet must be in sync to access the voting system. "
+               "Please wait for synchronization to complete."));
+        recheckCurrentTabAction();
+        return;
+    }
+
     votingAction->setChecked(true);
     centralWidget->setCurrentWidget(votingPage);
 

src/qt/bitcoingui.h

@@ -32,6 +32,7 @@ class Notificator;
 class RPCConsole;
 class DiagnosticsDialog;
 class ClickLabel;
+class SyncOverlay;
 class UpdateDialog;
 
 QT_BEGIN_NAMESPACE
@@ -113,6 +114,9 @@ class BitcoinGUI : public QMainWindow
     SignVerifyMessageDialog *signVerifyMessageDialog;
     std::unique_ptr<UpdateDialog> updateMessageDialog;
 
+    SyncOverlay *m_sync_overlay;
+    bool m_in_sync;
+
     QLabel *statusbarAlertsLabel;
     QLabel *labelEncryptionIcon;
     QLabel *labelStakingIcon;
@@ -191,6 +195,8 @@ class BitcoinGUI : public QMainWindow
     void createTrayIconMenu();
     /** Set Icons */
     void setIcons();
+    /** Re-check the toolbar action that matches the currently displayed page. */
+    void recheckCurrentTabAction();
 
 
 public slots:

src/qt/researcher/researchermodel.cpp

@@ -23,6 +23,7 @@
 #include "qt/researcher/researchermodel.h"
 #include "qt/researcher/researcherwizard.h"
 
+#include <QApplication>
 #include <QIcon>
 #include <QMessageBox>
 #include <QTimer>
@@ -205,6 +206,15 @@ void ResearcherModel::showWizard(WalletModel* wallet_model)
         return;
     }
 
+    if (outOfSync()) {
+        QMessageBox::warning(QApplication::activeWindow(),
+            QObject::tr("Wallet Not In Sync"),
+            QObject::tr("The wallet must be in sync to manage beacons. Please wait "
+               "for synchronization to complete before using the researcher "
+               "and beacon configuration wizard."));
+        return;
+    }
+
     m_wizard_open = true;
 
     ResearcherWizard *wizard = new ResearcherWizard(nullptr, this, wallet_model);

src/qt/syncoverlay.cpp

@@ -0,0 +1,178 @@
+// Copyright (c) 2025 The Gridcoin developers
+// Distributed under the MIT/X11 software license, see the accompanying
+// file COPYING or https://opensource.org/licenses/mit-license.php.
+
+#include "qt/syncoverlay.h"
+#include "qt/decoration.h"
+
+#include <QEvent>
+#include <QHBoxLayout>
+#include <QLabel>
+#include <QPainter>
+#include <QPushButton>
+#include <QVBoxLayout>
+
+SyncOverlay::SyncOverlay(QWidget* parent)
+    : QWidget(parent)
+    , m_dismissed(false)
+    , m_out_of_sync(true)
+{
+    // Fill the entire parent widget area and sit on top of everything.
+    setAttribute(Qt::WA_TranslucentBackground, false);
+
+    if (parent) {
+        parent->installEventFilter(this);
+        resize(parent->size());
+    }
+
+    // --- Central panel ---
+
+    QWidget* panel = new QWidget(this);
+    panel->setObjectName("syncOverlayPanel");
+    panel->setStyleSheet(
+        "#syncOverlayPanel {"
+        "  background-color: palette(window);"
+        "  border: 1px solid palette(mid);"
+        "  border-radius: 8px;"
+        "}"
+    );
+    panel->setFixedWidth(480);
+
+    // Icon
+    m_icon_label = new QLabel(panel);
+    m_icon_label->setPixmap(GRC::ScaleIcon(this, ":/icons/no_result", 48));
+    m_icon_label->setAlignment(Qt::AlignCenter);
+
+    // Title
+    m_title_label = new QLabel(panel);
+    m_title_label->setText(tr("Wallet is syncing"));
+    m_title_label->setAlignment(Qt::AlignCenter);
+    QFont title_font = m_title_label->font();
+    title_font.setPointSize(title_font.pointSize() + 4);
+    title_font.setBold(true);
+    m_title_label->setFont(title_font);
+
+    // Detail
+    m_detail_label = new QLabel(panel);
+    m_detail_label->setText(
+        tr("The displayed information may be out of date. Your wallet "
+           "automatically synchronizes with the Gridcoin network after a "
+           "connection is established, but this process has not completed yet."
+           "\n\n"
+           "Operations such as beacon management, voting, and sending "
+           "transactions should not be performed until synchronization "
+           "is complete.")
+    );
+    m_detail_label->setAlignment(Qt::AlignCenter);
+    m_detail_label->setWordWrap(true);
+
+    // Hide button
+    m_hide_button = new QPushButton(tr("Hide"), panel);
+    m_hide_button->setFixedWidth(120);
+    connect(m_hide_button, &QPushButton::clicked, this, &SyncOverlay::dismiss);
+
+    // Panel layout
+    QVBoxLayout* panel_layout = new QVBoxLayout(panel);
+    panel_layout->setContentsMargins(32, 24, 32, 24);
+    panel_layout->setSpacing(12);
+    panel_layout->addWidget(m_icon_label);
+    panel_layout->addWidget(m_title_label);
+    panel_layout->addWidget(m_detail_label);
+
+    QHBoxLayout* button_layout = new QHBoxLayout();
+    button_layout->addStretch();
+    button_layout->addWidget(m_hide_button);
+    button_layout->addStretch();
+    panel_layout->addSpacing(8);
+    panel_layout->addLayout(button_layout);
+
+    // Overlay layout — center the panel
+    QVBoxLayout* outer_v = new QVBoxLayout(this);
+    outer_v->setContentsMargins(0, 0, 0, 0);
+
+    QHBoxLayout* outer_h = new QHBoxLayout();
+    outer_h->addStretch();
+    outer_h->addWidget(panel);
+    outer_h->addStretch();
+
+    outer_v->addStretch();
+    outer_v->addLayout(outer_h);
+    outer_v->addStretch();
+}
+
+bool SyncOverlay::eventFilter(QObject* watched, QEvent* event)
+{
+    if (watched == parent() && event->type() == QEvent::Resize) {
+        resize(parentWidget()->size());
+        raise();
+    }
+
+    return QWidget::eventFilter(watched, event);
+}
+
+void SyncOverlay::setSyncState(bool out_of_sync, int blocks, int total_blocks)
+{
+    m_out_of_sync = out_of_sync;
+
+    if (!out_of_sync) {
+        // In sync — hide unconditionally and reset dismissed state so the
+        // overlay will reappear if the wallet falls out of sync again later.
+        m_dismissed = false;
+        QWidget::hide();
+        return;
+    }
+
+    if (m_dismissed) {
+        return;
+    }
+
+    // Update progress detail. Only show block count and percentage when the
+    // peer median is meaningful (blocks < total_blocks). Otherwise fall back
+    // to the generic message — showing "100%" while out of sync would mislead.
+    if (total_blocks > 0 && blocks < total_blocks) {
+        int pct = static_cast<int>(100.0 * blocks / total_blocks);
+        m_detail_label->setText(
+            tr("The wallet is currently synchronizing with the Gridcoin "
+               "network. Progress: %1 of %2 blocks (%3%)."
+               "\n\n"
+               "Operations such as beacon management, voting, and sending "
+               "transactions should not be performed until synchronization "
+               "is complete.")
+            .arg(blocks)
+            .arg(total_blocks)
+            .arg(pct)
+        );
+    } else {
+        m_detail_label->setText(
+            tr("The displayed information may be out of date. Your wallet "
+               "automatically synchronizes with the Gridcoin network after a "
+               "connection is established, but this process has not completed yet."
+               "\n\n"
+               "Operations such as beacon management, voting, and sending "
+               "transactions should not be performed until synchronization "
+               "is complete.")
+        );
+    }
+
+    raise();
+    show();
+}
+
+bool SyncOverlay::isActive() const
+{
+    return m_out_of_sync && !m_dismissed;
+}
+
+void SyncOverlay::paintEvent(QPaintEvent* event)
+{
+    Q_UNUSED(event);
+
+    QPainter painter(this);
+    painter.fillRect(rect(), QColor(0, 0, 0, 160));
+}
+
+void SyncOverlay::dismiss()
+{
+    m_dismissed = true;
+    QWidget::hide();
+}