interfaces: expose UTXO snapshot functionaility in node interface

- Added a new virtual method `snapshot` to the node interface for loading UTXO snapshots.
- Updated the implementation in `interfaces.cpp` to activate the snapshot using a path.
- Added `snapshot.h` to src/interfaces to process the path and extract the metada
- Added `getMetadata` and `getActivationResults` methods for use by GUI and/or RPC
- Added error handling method and member variable

This change enhances the user ability to load utxo snapshots through the GUI

Author: D33r-Gee

src/interfaces/node.h

@@ -12,6 +12,7 @@
 #include <net_types.h>
 #include <netaddress.h>
 #include <netbase.h>
+#include <node/utxo_snapshot.h>
 #include <support/allocators/secure.h>
 #include <util/translation.h>
 
@@ -204,6 +205,9 @@ class Node
     //! List rpc commands.
     virtual std::vector<std::string> listRpcCommands() = 0;
 
+    //! UTXO Snapshot interface.
+    virtual std::unique_ptr<Snapshot> snapshot(const fs::path& path) = 0;
+
     //! Get unspent output associated with a transaction.
     virtual std::optional<Coin> getUnspentOutput(const COutPoint& output) = 0;
 
@@ -233,6 +237,10 @@ class Node
     using ShowProgressFn = std::function<void(const std::string& title, int progress, bool resume_possible)>;
     virtual std::unique_ptr<Handler> handleShowProgress(ShowProgressFn fn) = 0;
 
+     //! Register handler for snapshot load progress.
+    using SnapshotLoadProgressFn = std::function<void(double progress)>;
+    virtual std::unique_ptr<Handler> handleSnapshotLoadProgress(SnapshotLoadProgressFn fn) = 0;
+
     //! Register handler for wallet loader constructed messages.
     using InitWalletFn = std::function<void()>;
     virtual std::unique_ptr<Handler> handleInitWallet(InitWalletFn fn) = 0;

src/interfaces/snapshot.h

@@ -0,0 +1,40 @@
+// Copyright (c) 2024 The Bitcoin Core developers
+// Distributed under the MIT software license, see the accompanying
+// file COPYING or http://www.opensource.org/licenses/mit-license.php.
+
+#ifndef BITCOIN_INTERFACES_SNAPSHOT_H
+#define BITCOIN_INTERFACES_SNAPSHOT_H
+
+#include <memory>
+#include <optional>
+#include <uint256.h>
+
+class CBlockIndex;
+namespace node {
+class SnapshotMetadata;
+}
+
+namespace interfaces {
+
+//! Interface for managing UTXO snapshots.
+class Snapshot
+{
+public:
+    virtual ~Snapshot() = default;
+
+    //! Activate the snapshot, making it the active chainstate.
+    virtual bool activate() = 0;
+
+    //! Get the snapshot metadata.
+    virtual const node::SnapshotMetadata& getMetadata() const = 0;
+
+    //! Get the activation result (block index of the snapshot base).
+    virtual std::optional<const CBlockIndex*> getActivationResult() const = 0;
+
+    //! Get the last error message from activation attempt.
+    virtual std::string getLastError() const = 0;
+};
+
+} // namespace interfaces
+
+#endif // BITCOIN_INTERFACES_SNAPSHOT_H

src/node/interfaces.cpp

@@ -18,6 +18,7 @@
 #include <interfaces/handler.h>
 #include <interfaces/mining.h>
 #include <interfaces/node.h>
+#include <interfaces/snapshot.h>
 #include <interfaces/types.h>
 #include <interfaces/wallet.h>
 #include <kernel/chain.h>
@@ -38,6 +39,7 @@
 #include <node/kernel_notifications.h>
 #include <node/transaction.h>
 #include <node/types.h>
+#include <node/utxo_snapshot.h>
 #include <node/warnings.h>
 #include <policy/feerate.h>
 #include <policy/fees.h>
@@ -80,6 +82,7 @@ using interfaces::Handler;
 using interfaces::MakeSignalHandler;
 using interfaces::Mining;
 using interfaces::Node;
+using interfaces::Snapshot;
 using interfaces::WalletLoader;
 using node::BlockAssembler;
 using node::BlockWaitOptions;
@@ -89,6 +92,73 @@ namespace node {
 // All members of the classes in this namespace are intentionally public, as the
 // classes themselves are private.
 namespace {
+class SnapshotImpl : public interfaces::Snapshot
+{
+public:
+    SnapshotImpl(ChainstateManager& chainman, const fs::path& path, bool in_memory)
+        : m_chainman(chainman), m_path(path), m_in_memory(in_memory), m_metadata(chainman.GetParams().MessageStart()) {}
+
+    bool activate() override
+    {
+        m_last_error.clear();
+
+        if (!fs::exists(m_path)) {
+            m_last_error = "Snapshot file does not exist";
+            return false;
+        }
+
+        FILE* snapshot_file{fsbridge::fopen(m_path, "rb")};
+        AutoFile afile{snapshot_file};
+        if (afile.IsNull()) {
+            m_last_error = "Unable to open snapshot file for reading";
+            return false;
+        }
+
+        try {
+            afile >> m_metadata;
+        } catch (const std::ios_base::failure& e) {
+            m_last_error = strprintf("Unable to parse metadata: %s", e.what());
+            return false;
+        }
+
+        auto result = m_chainman.ActivateSnapshot(afile, m_metadata, m_in_memory);
+        if (result.has_value()) {
+            m_activation_result = result.value();
+            return true;
+        } else {
+            m_activation_result = std::nullopt;
+            m_last_error = util::ErrorString(result).original;
+            return false;
+        }
+    }
+
+    const node::SnapshotMetadata& getMetadata() const override
+    {
+        return m_metadata;
+    }
+
+    std::optional<const CBlockIndex*> getActivationResult() const override
+    {
+        if (m_activation_result.has_value()) {
+            return m_activation_result;
+        }
+        return std::nullopt;
+    }
+
+    std::string getLastError() const override
+    {
+        return m_last_error;
+    }
+
+private:
+    ChainstateManager& m_chainman;
+    fs::path m_path;
+    bool m_in_memory;
+    node::SnapshotMetadata m_metadata;
+    std::optional<const CBlockIndex*> m_activation_result;
+    std::string m_last_error;
+};
+
 #ifdef ENABLE_EXTERNAL_SIGNER
 class ExternalSignerImpl : public interfaces::ExternalSigner
 {
@@ -356,6 +426,10 @@ class NodeImpl : public Node
         return ::tableRPC.execute(req);
     }
     std::vector<std::string> listRpcCommands() override { return ::tableRPC.listCommands(); }
+    std::unique_ptr<interfaces::Snapshot> snapshot(const fs::path& path) override
+    {
+        return std::make_unique<SnapshotImpl>(chainman(), path, /*in_memory=*/ false);
+    }
     std::optional<Coin> getUnspentOutput(const COutPoint& output) override
     {
         LOCK(::cs_main);
@@ -385,6 +459,10 @@ class NodeImpl : public Node
     {
         return MakeSignalHandler(::uiInterface.ShowProgress_connect(fn));
     }
+    std::unique_ptr<Handler> handleSnapshotLoadProgress(SnapshotLoadProgressFn fn) override
+    {
+        return MakeSignalHandler(::uiInterface.SnapshotLoadProgress_connect(fn));
+    }
     std::unique_ptr<Handler> handleInitWallet(InitWalletFn fn) override
     {
         return MakeSignalHandler(::uiInterface.InitWallet_connect(fn));