251     */
252    void FindFilesToPrune(
253        std::set<int>& setFilesToPrune,
254        int last_prune,
255        const Chainstate& chain,
256        ChainstateManager& chainman);
257
258    //! Since assumedvalid chainstates may be syncing a range of the chain that is very
259    //! far away from the normal/background validation process, we should segment blockfiles
260    //! for assumed chainstates. Otherwise, we might have wildly different height ranges
261    //! mixed into the same block files, which would impair our ability to prune
262    //! effectively.
263    //!
264    //! This data structure maintains separate blockfile number cursors for each
265    //! BlockfileType. The ASSUMED state is initialized, when necessary, in FindNextBlockPos().
266    //!
267    //! The first element is the NORMAL cursor, second is ASSUMED.
268    std::array<std::optional<BlockfileCursor>, BlockfileType::NUM_TYPES>
269        m_blockfile_cursors GUARDED_BY(::cs_main) = {
270            BlockfileCursor{},
271            std::nullopt,
272    };
273    int MaxBlockfileNum() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
274    {
275        AssertLockHeld(::cs_main);
276        static const BlockfileCursor empty_cursor;
277        const auto& normal = m_blockfile_cursors[BlockfileType::NORMAL].value_or(empty_cursor);
278        const auto& assumed = m_blockfile_cursors[BlockfileType::ASSUMED].value_or(empty_cursor);
279        return std::max(normal.file_num, assumed.file_num);
280    }
281
282    /** Global flag to indicate we should check to see if there are
283     *  block/undo files that should be deleted.  Set on startup
284     *  or if we allocate more file space when we're in prune mode
285     */
286    bool m_check_for_pruning = false;
287
288    const bool m_prune_mode;
289
290    const Obfuscation m_obfuscation;
291
292    /**
293     * Map from external index name to oldest block that must not be pruned.
294     *
295     * @note Internally, only blocks at height (height_first - PRUNE_LOCK_BUFFER - 1) and
296     * below will be pruned, but callers should avoid assuming any particular buffer size.
297     */
298    std::unordered_map<std::string, PruneLockInfo> m_prune_locks GUARDED_BY(::cs_main);
299
300    BlockfileType BlockfileTypeForHeight(int height);
301
302    const kernel::BlockManagerOpts m_opts;
303
304    const FlatFileSeq m_block_file_seq;
305    const FlatFileSeq m_undo_file_seq;
306
307protected:
308    std::vector<CBlockFileInfo> m_blockfile_info;
309
310    /** Dirty block index entries. */
311    std::set<CBlockIndex*> m_dirty_blockindex;
312
313    /** Dirty block file entries. */
314    std::set<int> m_dirty_fileinfo;
315
316public:
317    using Options = kernel::BlockManagerOpts;
318    using ReadRawBlockResult = util::Expected<std::vector<std::byte>, ReadRawError>;
319
320    explicit BlockManager(const util::SignalInterrupt& interrupt, Options opts);
321
322    const util::SignalInterrupt& m_interrupt;
323    std::atomic<bool> m_importing{false};
324
325    /**
326     * Whether all blockfiles have been added to the block tree database.
327     * Normally true, but set to false when a reindex is requested and the
328     * database is wiped. The value is persisted in the database across restarts
329     * and will be false until reindexing completes.
330     */
331    std::atomic_bool m_blockfiles_indexed{true};
332
333    BlockMap m_block_index GUARDED_BY(cs_main);
334
335    /**
336     * The height of the base block of an assumeutxo snapshot, if one is in use.
337     *
338     * This controls how blockfiles are segmented by chainstate type to avoid
339     * comingling different height regions of the chain when an assumedvalid chainstate
340     * is in use. If heights are drastically different in the same blockfile, pruning
341     * suffers.
342     *
343     * This is set during ActivateSnapshot() or upon LoadBlockIndex() if a snapshot
344     * had been previously loaded. After the snapshot is validated, this is unset to
345     * restore normal LoadBlockIndex behavior.
346     */
347    std::optional<int> m_snapshot_height;
348
349    std::vector<CBlockIndex*> GetAllBlockIndices() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
350
351    /**
352     * All pairs A->B, where A (or one of its ancestors) misses transactions, but B has transactions.
353     */
354    std::multimap<CBlockIndex*, CBlockIndex*> m_blocks_unlinked;
355    void AddUnlinkedBlock(CBlockIndex* block) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
356
357    std::unique_ptr<BlockTreeDB> m_block_tree_db GUARDED_BY(::cs_main);
358
359    void WriteBlockIndexDB() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
360    bool LoadBlockIndexDB(const std::optional<uint256>& snapshot_blockhash)
361        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
362
363    /**
364     * Remove any pruned block & undo files that are still on disk.
365     * This could happen on some systems if the file was still being read while unlinked,
366     * or if we crash before unlinking.
367     */
368    void ScanAndUnlinkAlreadyPrunedFiles() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
369
370    CBlockIndex* AddToBlockIndex(const CBlockHeader& block, CBlockIndex*& best_header) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
371    /** Create a new block index entry for a given block hash */
372    CBlockIndex* InsertBlockIndex(const uint256& hash) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
373
374    //! Mark one block file as pruned (modify associated database entries)
375    void PruneOneBlockFile(int fileNumber) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
376
377    CBlockIndex* LookupBlockIndex(const uint256& hash) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
378    const CBlockIndex* LookupBlockIndex(const uint256& hash) const EXCLUSIVE_LOCKS_REQUIRED(cs_main);
379
380    /** Get block file info entry for one block file */
381    CBlockFileInfo* GetBlockFileInfo(size_t n) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
382
383    bool WriteBlockUndo(const CBlockUndo& blockundo, BlockValidationState& state, CBlockIndex& block)
384        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
385
386    /** Store block on disk and update block file statistics.
387     *
388     * @param[in]  block        the block to be stored
389     * @param[in]  nHeight      the height of the block
390     *
391     * @returns in case of success, the position to which the block was written to
392     *          in case of an error, an empty FlatFilePos
393     */
394    FlatFilePos WriteBlock(const CBlock& block, int nHeight) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
395
396    /** Update blockfile info while processing a block during reindex. The block must be available on disk.
397     *
398     * @param[in]  block        the block being processed
399     * @param[in]  nHeight      the height of the block
400     * @param[in]  pos          the position of the serialized CBlock on disk
401     */
402    void UpdateBlockInfo(const CBlock& block, unsigned int nHeight, const FlatFilePos& pos) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
403
404    /** Whether running in -prune mode. */
405    [[nodiscard]] bool IsPruneMode() const { return m_prune_mode; }
406
407    /** Attempt to stay below this number of bytes of block files. */
408    [[nodiscard]] uint64_t GetPruneTarget() const { return m_opts.prune_target; }
409    static constexpr auto PRUNE_TARGET_MANUAL{std::numeric_limits<uint64_t>::max()};
410
411    [[nodiscard]] bool LoadingBlocks() const { return m_importing || !m_blockfiles_indexed; }
412
413    /** Calculate the amount of disk space the block & undo files currently use */
414    uint64_t CalculateCurrentUsage() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
415
416    //! Check if all blocks in the [upper_block, lower_block] range have data available as
417    //! defined by the status mask.
418    //! The caller is responsible for ensuring that lower_block is an ancestor of upper_block
419    //! (part of the same chain).
420    bool CheckBlockDataAvailability(const CBlockIndex& upper_block, const CBlockIndex& lower_block, BlockStatus block_status = BLOCK_HAVE_DATA) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
421
422    /**
423     * @brief Returns the earliest block with specified `status_mask` flags set after
424     * the latest block _not_ having those flags.
425     *
426     * This function starts from `upper_block`, which must have all
427     * `status_mask` flags set, and iterates backwards through its ancestors. It
428     * continues as long as each block has all `status_mask` flags set, until
429     * reaching the oldest ancestor or `lower_block`.
430     *
431     * @pre `upper_block` must have all `status_mask` flags set.
432     * @pre `lower_block` must be null or an ancestor of `upper_block`
433     *
434     * @param upper_block The starting block for the search, which must have all
435     *                    `status_mask` flags set.
436     * @param status_mask Bitmask specifying required status flags.
437     * @param lower_block The earliest possible block to return. If null, the
438     *                    search can extend to the genesis block.
439     *
440     * @return A reference to the earliest block between `upper_block`
441     *         and `lower_block`, inclusive, such that every block between the
442     *         returned block and `upper_block` has `status_mask` flags set.
443     */
444    const CBlockIndex& GetFirstBlock(
445        const CBlockIndex& upper_block LIFETIMEBOUND,
446        uint32_t status_mask,
447        const CBlockIndex* lower_block LIFETIMEBOUND = nullptr
448    ) const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
449
450    /** True if any block files have ever been pruned. */
451    bool m_have_pruned = false;
452
453    //! Check whether the block associated with this index entry is pruned or not.
454    bool IsBlockPruned(const CBlockIndex& block) const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
455
456    //! Create or update a prune lock identified by its name
457    void UpdatePruneLock(const std::string& name, const PruneLockInfo& lock_info) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
458
459    //! Delete a prune lock identified by its name. Returns true if the lock existed.
460    bool DeletePruneLock(const std::string& name) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
461
462    /** Open a block file (blk?????.dat) */
463    AutoFile OpenBlockFile(const FlatFilePos& pos, bool fReadOnly) const;
464
465    /** Translation to a filesystem path */
466    fs::path GetBlockPosFilename(const FlatFilePos& pos) const;
467
468    /**
469     *  Actually unlink the specified files
470     */
471    void UnlinkPrunedFiles(const std::set<int>& setFilesToPrune) const;
472
473    /** Functions for disk access for blocks */
474    bool ReadBlock(CBlock& block, const FlatFilePos& pos, const std::optional<uint256>& expected_hash) const;
475    bool ReadBlock(CBlock& block, const CBlockIndex& index) const;
476    ReadRawBlockResult ReadRawBlock(const FlatFilePos& pos, std::optional<std::pair<size_t, size_t>> block_part = std::nullopt) const;
477
478    bool ReadBlockUndo(CBlockUndo& blockundo, const CBlockIndex& index) const;
479
480    void CleanupBlockRevFiles() const;
481};
482
483// Calls ActivateBestChain() even if no blocks are imported.
484void ImportBlocks(ChainstateManager& chainman, std::span<const fs::path> import_paths);
485} // namespace node
486
487#endif // BITCOIN_NODE_BLOCKSTORAGE_H
488