scan.h

// Copyright (c) 2026-present 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_WALLET_SCAN_H
#define BITCOIN_WALLET_SCAN_H

#include <uint256.h>
#include <util/time.h>

#include <atomic>
#include <functional>
#include <optional>

namespace wallet {
class CWallet;

/** Result of a wallet scan */
struct ScanResult {
    enum { SUCCESS, FAILURE, USER_ABORT } status = SUCCESS;

    //! Hash and height of most recent block that was successfully scanned.
    //! Unset if no blocks were scanned due to read errors or the chain
    //! being empty.
    uint256 last_scanned_block;
    std::optional<int> last_scanned_height;

    //! Height of the most recent block that could not be scanned due to
    //! read errors or pruning. Will be set if status is FAILURE, unset if
    //! status is SUCCESS, and may or may not be set if status is
    //! USER_ABORT.
    uint256 last_failed_block;
};

/** RAII object to check and reserve a wallet rescan */
class WalletRescanReserver
{
private:
    using Clock = std::chrono::steady_clock;
    using NowFn = std::function<Clock::time_point()>;
    CWallet& m_wallet;
    bool m_could_reserve{false};
    NowFn m_now;
public:
    explicit WalletRescanReserver(CWallet& w) : m_wallet(w) {}

    bool reserve(bool with_passphrase = false);
    bool isReserved() const;

    Clock::time_point now() const { return m_now ? m_now() : Clock::now(); };

    void setNow(NowFn now) { m_now = std::move(now); }

    ~WalletRescanReserver();
};

class ChainScanner {
private:
    CWallet& m_wallet;

    std::atomic<bool> m_abort{false};
    std::atomic<bool> m_scanning{false};
    std::atomic<bool> m_scanning_with_passphrase{false};
    std::atomic<SteadyClock::time_point> m_scanning_start{SteadyClock::time_point{}};
    std::atomic<double> m_scanning_progress{0};

    //! Progress window and tip tracked across Scan loop iterations. The
    //! current block's progress is a plain local in Scan; only the window
    //! bounds are shared with the helpers, and UpdateTipIfChanged is the
    //! sole mutator.
    struct LoopState {
        double progress_begin{0};
        double progress_end{0};
        uint256 tip_hash;
    };

    //! Locate block_hash in the chain, queueing its active-chain successor
    //! into next_block if it exists and is within the scan range. Returns
    //! whether the block itself is still in the active chain.
    bool QueueNextBlock(const uint256& block_hash, int block_height, std::optional<std::pair<uint256, int>>& next_block, std::optional<int> max_height);
    bool ScanBlock(const uint256& block_hash, int block_height, bool save_progress);
    void UpdateProgress(const LoopState& state, double progress_current, int block_height);
    void UpdateTipIfChanged(LoopState& state);

    //! Only WalletRescanReserver may reserve and release scans, so that
    //! reservations are always managed RAII-style.
    friend class WalletRescanReserver;
    bool TryReserve(bool with_passphrase = false);
    void Release();

public:
    explicit ChainScanner(CWallet& wallet) : m_wallet(wallet) {}

    void Abort() { m_abort = true; }
    bool IsAborting() const { return m_abort; }
    bool IsScanning() const { return m_scanning; }
    bool IsScanningWithPassphrase() const { return m_scanning_with_passphrase; }
    SteadyClock::duration ScanningDuration() const { return m_scanning ? SteadyClock::now() - m_scanning_start.load() : SteadyClock::duration{}; }
    double ScanningProgress() const { return m_scanning ? m_scanning_progress.load() : 0; }

    /** Scan active chain for relevant transactions after importing keys. Should
     * be called whenever new keys are added to the wallet, with the oldest key
     * creation time.
     * @return Earliest timestamp that could be successfully scanned from. Timestamp
     * returned will be higher than startTime if relevant blocks could not be read. */
    int64_t ScanFromTime(int64_t startTime, const WalletRescanReserver& reserver);

    /**
     * Scan the block chain (starting in start_block) for transactions
     * from or to us. If max_height is not set, the
     * mempool will be scanned as well.
     *
     * @param[in] start_block Scan starting block. If block is not on the active
     *                        chain, the scan will return SUCCESS immediately.
     * @param[in] start_height Height of start_block
     * @param[in] max_height  Optional max scanning height. If unset there is
     *                        no maximum and scanning can continue to the tip
     *
     * @return ScanResult returning scan information and indicating success or
     *         failure. Return status will be set to SUCCESS if scan was
     *         successful. FAILURE if a complete rescan was not possible (due to
     *         pruning or corruption). USER_ABORT if the rescan was aborted before
     *         it could complete.
     *
     * @pre Caller needs to make sure start_block (and the optional stop_block) are on
     * the main chain after the addition of any new keys you want to detect
     * transactions for.
     */
    ScanResult Scan(const uint256& start_block, int start_height, std::optional<int> max_height,
                    const WalletRescanReserver& reserver, bool save_progress);

};

} // namespace wallet

#endif // BITCOIN_WALLET_SCAN_H