Inside Bitcoin

501    //! All arguments forwarded onto CCoinsViewDB.
502    CoinsViews(DBParams db_params, CoinsViewOptions options);
503
504    //! Initialize the CCoinsViewCache member.
505    void InitCache(int32_t prevoutfetch_threads) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
506};
507
508enum class CoinsCacheSizeState
509{
510    //! The coins cache is in immediate need of a flush.
511    CRITICAL = 2,
512    //! The cache is at >= 90% capacity.
513    LARGE = 1,
514    OK = 0
515};
516
517constexpr int64_t LargeCoinsCacheThreshold(int64_t total_space) noexcept
518{
519    // No periodic flush needed if at least this much space is free
520    constexpr int64_t MAX_BLOCK_COINSDB_USAGE_BYTES{int64_t(10_MiB)};
521    return std::max((total_space * 9) / 10,
522                    total_space - MAX_BLOCK_COINSDB_USAGE_BYTES);
523}
524
525//! Chainstate assumeutxo validity.
526enum class Assumeutxo {
527    //! Every block in the chain has been validated.
528    VALIDATED,
529    //! Blocks after an assumeutxo snapshot have been validated but the snapshot itself has not been validated.
530    UNVALIDATED,
531    //! The assumeutxo snapshot failed validation.
532    INVALID,
533};
534
535/**
536 * Chainstate stores and provides an API to update our local knowledge of the
537 * current best chain.
538 *
539 * Eventually, the API here is targeted at being exposed externally as a
540 * consumable library, so any functions added must only call
541 * other class member functions, pure functions in other parts of the consensus
542 * library, callbacks via the validation interface, or read/write-to-disk
543 * functions (eventually this will also be via callbacks).
544 *
545 * Anything that is contingent on the current tip of the chain is stored here,
546 * whereas block information and metadata independent of the current tip is
547 * kept in `BlockManager`.
548 */
549class Chainstate
550{
551protected:
552    /**
553     * The ChainState Mutex
554     * A lock that must be held when modifying this ChainState - held in ActivateBestChain() and
555     * InvalidateBlock()
556     */
557    Mutex m_chainstate_mutex;
558
559    //! Optional mempool that is kept in sync with the chain.
560    //! Only the active chainstate has a mempool.
561    CTxMemPool* m_mempool;
562
563    //! Manages the UTXO set, which is a reflection of the contents of `m_chain`.
564    std::unique_ptr<CoinsViews> m_coins_views;
565
566    //! Cached result of LookupBlockIndex(*m_from_snapshot_blockhash)
567    mutable const CBlockIndex* m_cached_snapshot_base GUARDED_BY(::cs_main){nullptr};
568
569    //! Target block for this chainstate. If this is not set, chainstate will
570    //! target the most-work, valid block. If this is set, ChainstateManager
571    //! considers this a "historical" chainstate since it will only contain old
572    //! blocks up to the target block, not newer blocks.
573    std::optional<uint256> m_target_blockhash GUARDED_BY(::cs_main);
574
575    //! Cached result of LookupBlockIndex(*m_target_blockhash)
576    mutable const CBlockIndex* m_cached_target_block GUARDED_BY(::cs_main){nullptr};
577
578    std::optional<const char*> m_last_script_check_reason_logged GUARDED_BY(::cs_main){};
579
580public:
581    //! Reference to a BlockManager instance which itself is shared across all
582    //! Chainstate instances.
583    node::BlockManager& m_blockman;
584
585    //! The chainstate manager that owns this chainstate. The reference is
586    //! necessary so that this instance can check whether it is the active
587    //! chainstate within deeply nested method calls.
588    ChainstateManager& m_chainman;
589
590    explicit Chainstate(
591        CTxMemPool* mempool,
592        node::BlockManager& blockman,
593        ChainstateManager& chainman,
594        std::optional<uint256> from_snapshot_blockhash = std::nullopt);
595
596    //! Return path to chainstate leveldb directory.
597    fs::path StoragePath() const;
598
599    //! Return the current role of the chainstate. See `ChainstateManager`
600    //! documentation for a description of the different types of chainstates.
601    //!
602    //! @sa ChainstateRole
603    kernel::ChainstateRole GetRole() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
604
605    /**
606     * Initialize the CoinsViews UTXO set database management data structures. The in-memory
607     * cache is initialized separately.
608     *
609     * All parameters forwarded to CoinsViews.
610     */
611    void InitCoinsDB(
612        size_t cache_size_bytes,
613        bool in_memory,
614        bool should_wipe);
615
616    //! Initialize the in-memory coins cache (to be done after the health of the on-disk database
617    //! is verified).
618    void InitCoinsCache(size_t cache_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
619
620    //! @returns whether or not the CoinsViews object has been fully initialized and we can
621    //!          safely flush this object to disk.
622    bool CanFlushToDisk() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
623    {
624        AssertLockHeld(::cs_main);
625        return m_coins_views && m_coins_views->m_cacheview;
626    }
627
628    //! The current chain of blockheaders we consult and build on.
629    //! @see CChain, CBlockIndex.
630    CChain m_chain;
631
632    //! Assumeutxo state indicating whether all blocks in the chain were
633    //! validated, or if the chainstate is based on an assumeutxo snapshot and
634    //! the snapshot has not been validated.
635    Assumeutxo m_assumeutxo GUARDED_BY(::cs_main);
636
637    /**
638     * The blockhash which is the base of the snapshot this chainstate was created from.
639     *
640     * std::nullopt if this chainstate was not created from a snapshot.
641     */
642    const std::optional<uint256> m_from_snapshot_blockhash;
643
644    //! Hash of the UTXO set at the target block, computed when the chainstate
645    //! reaches the target block, and null before then.
646    std::optional<AssumeutxoHash> m_target_utxohash GUARDED_BY(::cs_main);
647
648    /**
649     * The base of the snapshot this chainstate was created from.
650     *
651     * nullptr if this chainstate was not created from a snapshot.
652     */
653    const CBlockIndex* SnapshotBase() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
654
655    //! Return target block which chainstate tip is expected to reach, if this
656    //! is a historic chainstate being used to validate a snapshot, or null if
657    //! chainstate targets the most-work block. Requires the block index to be
658    //! loaded, so prefer TargetBlockHash() when the block itself is not needed.
659    const CBlockIndex* TargetBlock() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
660    //! Return hash of the target block, or nullopt if chainstate targets the
661    //! most-work block. Unlike TargetBlock(), does not require the block index
662    //! to be loaded.
663    std::optional<uint256> TargetBlockHash() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
664    {
665        AssertLockHeld(::cs_main);
666        return m_target_blockhash;
667    }
668    //! Set target block for this chainstate. If null, chainstate will target
669    //! the most-work valid block. If non-null chainstate will be a historic
670    //! chainstate and target the specified block.
671    void SetTargetBlock(CBlockIndex* block) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
672    //! Set target block for this chainstate using just a block hash. Useful
673    //! when the block database has not been loaded yet.
674    void SetTargetBlockHash(uint256 block_hash) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
675
676    //! Return true if chainstate reached target block.
677    bool ReachedTarget() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
678    {
679        const CBlockIndex* target_block{TargetBlock()};
680        assert(!target_block || target_block->GetAncestor(m_chain.Height()) == m_chain.Tip());
681        return target_block && target_block == m_chain.Tip();
682    }
683
684    /**
685     * The set of all CBlockIndex entries that have as much work as our current
686     * tip or more, and transaction data needed to be validated (with
687     * BLOCK_VALID_TRANSACTIONS for each block and its parents back to the
688     * genesis block or an assumeutxo snapshot block). Entries may be failed,
689     * though, and pruning nodes may be missing the data for the block.
690     */
691    std::set<CBlockIndex*, node::CBlockIndexWorkComparator> setBlockIndexCandidates;
692
693    //! @returns A reference to the in-memory cache of the UTXO set.
694    CCoinsViewCache& CoinsTip() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
695    {
696        AssertLockHeld(::cs_main);
697        Assert(m_coins_views);
698        return *Assert(m_coins_views->m_cacheview);
699    }
700
701    //! @returns A reference to the on-disk UTXO set database.
702    CCoinsViewDB& CoinsDB() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
703    {
704        AssertLockHeld(::cs_main);
705        return Assert(m_coins_views)->m_dbview;
706    }
707
708    //! @returns A pointer to the mempool.
709    CTxMemPool* GetMempool()
710    {
711        return m_mempool;
712    }
713
714    //! @returns A reference to a wrapped view of the in-memory UTXO set that
715    //!     handles disk read errors gracefully.
716    CCoinsViewErrorCatcher& CoinsErrorCatcher() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
717    {
718        AssertLockHeld(::cs_main);
719        return Assert(m_coins_views)->m_catcherview;
720    }
721
722    //! Destructs all objects related to accessing the UTXO set.
723    void ResetCoinsViews() { m_coins_views.reset(); }
724
725    //! The cache size of the on-disk coins view.
726    size_t m_coinsdb_cache_size_bytes{0};
727
728    //! The cache size of the in-memory coins view.
729    size_t m_coinstip_cache_size_bytes{0};
730
731    //! Resize the CoinsViews caches dynamically and flush state to disk.
732    //! @returns true unless an error occurred during the flush.
733    bool ResizeCoinsCaches(size_t coinstip_size, size_t coinsdb_size)
734        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
735
736    /**
737     * Update the on-disk chain state.
738     * The caches and indexes are flushed depending on the mode we're called with
739     * if they're too large, if it's been a while since the last write,
740     * or always and in all cases if we're in prune mode and are deleting files.
741     *
742     * If FlushStateMode::NONE is used, then FlushStateToDisk(...) won't do anything
743     * besides checking if we need to prune.
744     *
745     * @returns true unless a system error occurred
746     */
747    bool FlushStateToDisk(
748        BlockValidationState& state,
749        FlushStateMode mode,
750        int nManualPruneHeight = 0);