Inside Bitcoin

751
752    //! Flush all changes to disk.
753    void ForceFlushStateToDisk(bool wipe_cache = true);
754
755    //! Prune blockfiles from the disk if necessary and then flush chainstate changes
756    //! if we pruned.
757    void PruneAndFlush();
758
759    /**
760     * Find the best known block, and make it the tip of the block chain. The
761     * result is either failure or an activated best chain. pblock is either
762     * nullptr or a pointer to a block that is already loaded (to avoid loading
763     * it again from disk).
764     *
765     * ActivateBestChain is split into steps (see ActivateBestChainStep) so that
766     * we avoid holding cs_main for an extended period of time; the length of this
767     * call may be quite long during reindexing or a substantial reorg.
768     *
769     * May not be called with cs_main held. May not be called in a
770     * validationinterface callback.
771     *
772     * Note that if this is called while a snapshot chainstate is active, and if
773     * it is called on a validated chainstate whose tip has reached the base
774     * block of the snapshot, its execution will take *MINUTES* while it hashes
775     * the UTXO set to verify the assumeutxo value the snapshot was activated
776     * with. `cs_main` will be held during this time.
777     *
778     * @returns true unless a system error occurred
779     */
780    bool ActivateBestChain(
781        BlockValidationState& state,
782        std::shared_ptr<const CBlock> pblock = nullptr)
783        EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex)
784        LOCKS_EXCLUDED(::cs_main);
785
786    // Block (dis)connection on a given view:
787    DisconnectResult DisconnectBlock(const CBlock& block, const CBlockIndex* pindex, CCoinsViewCache& view)
788        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
789    bool ConnectBlock(const CBlock& block, BlockValidationState& state, CBlockIndex* pindex,
790                      CCoinsViewCache& view, bool fJustCheck = false) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
791
792    // Apply the effects of a block disconnection on the UTXO set.
793    bool DisconnectTip(BlockValidationState& state, DisconnectedBlockTransactions* disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);
794
795    // Manual block validity manipulation:
796    /** Mark a block as precious and reorganize.
797     *
798     * May not be called in a validationinterface callback.
799     */
800    bool PreciousBlock(BlockValidationState& state, CBlockIndex* pindex)
801        EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex)
802        LOCKS_EXCLUDED(::cs_main);
803
804    /** Mark a block as invalid. */
805    bool InvalidateBlock(BlockValidationState& state, CBlockIndex* pindex)
806        EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex)
807        LOCKS_EXCLUDED(::cs_main);
808
809    /** Set invalidity status to all descendants of a block */
810    void SetBlockFailureFlags(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
811
812    /** Remove invalidity status from a block, its descendants and ancestors and reconsider them for activation */
813    void ResetBlockFailureFlags(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
814
815    /** Replay blocks that aren't fully applied to the database. */
816    bool ReplayBlocks();
817
818    /** Whether the chain state needs to be redownloaded due to lack of witness data */
819    [[nodiscard]] bool NeedsRedownload() const EXCLUSIVE_LOCKS_REQUIRED(cs_main);
820
821    /** Add a block to the candidate set if it has as much work as the current tip. */
822    void TryAddBlockIndexCandidate(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
823
824    void PruneBlockIndexCandidates();
825
826    void ClearBlockIndexCandidates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
827
828    /** Populate the candidate set by calling TryAddBlockIndexCandidate on all valid block indices. */
829    void PopulateBlockIndexCandidates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
830
831    /** Find the last common block of this chain and a locator. */
832    const CBlockIndex* FindForkInGlobalIndex(const CBlockLocator& locator) const EXCLUSIVE_LOCKS_REQUIRED(cs_main);
833
834    /** Update the chain tip based on database information, i.e. CoinsTip()'s best block. */
835    bool LoadChainTip() EXCLUSIVE_LOCKS_REQUIRED(cs_main);
836
837    //! Dictates whether we need to flush the cache to disk or not.
838    //!
839    //! @return the state of the size of the coins cache.
840    CoinsCacheSizeState GetCoinsCacheSizeState() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
841
842    CoinsCacheSizeState GetCoinsCacheSizeState(
843        size_t max_coins_cache_size_bytes,
844        size_t max_mempool_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
845
846    std::string ToString() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
847
848    //! Get the last block that was flushed to disk.
849    const CBlockIndex* GetLastFlushedBlock() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) { return m_last_flushed_block; }
850
851    //! Indirection necessary to make lock annotations work with an optional mempool.
852    RecursiveMutex* MempoolMutex() const LOCK_RETURNED(m_mempool->cs)
853    {
854        return m_mempool ? &m_mempool->cs : nullptr;
855    }
856
857    //! Return the [start, end] (inclusive) of block heights we can prune.
858    //!
859    //! start > end is possible, meaning no blocks can be pruned.
860    std::pair<int, int> GetPruneRange(int last_height_can_prune) const EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
861
862protected:
863    bool ActivateBestChainStep(BlockValidationState& state, CBlockIndex& index_most_work, const std::shared_ptr<const CBlock>& pblock, bool& fInvalidFound, std::vector<ConnectedBlock>& connected_blocks) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);
864    bool ConnectTip(
865        BlockValidationState& state,
866        CBlockIndex* pindexNew,
867        std::shared_ptr<const CBlock> block_to_connect,
868        std::vector<ConnectedBlock>& connected_blocks,
869        DisconnectedBlockTransactions& disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);
870
871    void InvalidBlockFound(CBlockIndex* pindex, const BlockValidationState& state) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
872    CBlockIndex* FindMostWorkChain() EXCLUSIVE_LOCKS_REQUIRED(cs_main);
873
874    bool RollforwardBlock(const CBlockIndex* pindex, CCoinsViewCache& inputs) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
875
876    void CheckForkWarningConditions() EXCLUSIVE_LOCKS_REQUIRED(cs_main);
877    void InvalidChainFound(CBlockIndex* pindexNew) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
878
879    /**
880     * Make mempool consistent after a reorg, by re-adding or recursively erasing
881     * disconnected block transactions from the mempool, and also removing any
882     * other transactions from the mempool that are no longer valid given the new
883     * tip/height.
884     *
885     * Note: we assume that disconnectpool only contains transactions that are NOT
886     * confirmed in the current chain nor already in the mempool (otherwise,
887     * in-mempool descendants of such transactions would be removed).
888     *
889     * Passing fAddToMempool=false will skip trying to add the transactions back,
890     * and instead just erase from the mempool as needed.
891     */
892    void MaybeUpdateMempoolForReorg(
893        DisconnectedBlockTransactions& disconnectpool,
894        bool fAddToMempool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs);
895
896    /** Check warning conditions and do some notifications on new chain tip set. */
897    void UpdateTip(const CBlockIndex* pindexNew)
898        EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
899
900    NodeClock::time_point m_next_write{NodeClock::time_point::max()};
901    const CBlockIndex* m_last_flushed_block GUARDED_BY(::cs_main){nullptr};
902
903    /**
904     * In case of an invalid snapshot, rename the coins leveldb directory so
905     * that it can be examined for issue diagnosis.
906     */
907    [[nodiscard]] util::Result<void> InvalidateCoinsDBOnDisk() EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
908
909    friend ChainstateManager;
910};
911
912enum class SnapshotCompletionResult {
913    SUCCESS,
914    SKIPPED,
915
916    // Expected assumeutxo configuration data is not found for the height of the
917    // base block.
918    MISSING_CHAINPARAMS,
919
920    // Failed to generate UTXO statistics (to check UTXO set hash) for the
921    // validated chainstate.
922    STATS_FAILED,
923
924    // The UTXO set hash of the validated chainstate does not match the one
925    // expected by assumeutxo chainparams.
926    HASH_MISMATCH,
927};
928
929/**
930 * Interface for managing multiple \ref Chainstate objects, where each
931 * chainstate is associated with chainstate* subdirectory in the data directory
932 * and contains a database of UTXOs existing at a different point in history.
933 * (See \ref Chainstate class for more information.)
934 *
935 * Normally there is exactly one Chainstate, which contains the UTXO set of
936 * chain tip if syncing is completed, or the UTXO set the most recent validated
937 * block if the initial sync is still in progress.
938 *
939 * However, if an assumeutxo snapshot is loaded before syncing is completed,
940 * there will be two chainstates. The original fully validated chainstate will
941 * continue to exist and download new blocks in the background. But the new
942 * snapshot which is loaded will become a second chainstate. The second
943 * chainstate will be used as the chain tip for the wallet and RPCs even though
944 * it is only assumed to be valid. When the initial chainstate catches up to the
945 * snapshot height and confirms that the assumeutxo snapshot is actually valid,
946 * the second chainstate will be marked validated and become the only chainstate
947 * again.
948 */
949class ChainstateManager
950{
951private:
952
953    /** The last header for which a headerTip notification was issued. */
954    CBlockIndex* m_last_notified_header GUARDED_BY(GetMutex()){nullptr};
955
956    bool NotifyHeaderTip() LOCKS_EXCLUDED(GetMutex());
957
958    //! Internal helper for ActivateSnapshot().
959    //!
960    //! De-serialization of a snapshot that is created with
961    //! the dumptxoutset RPC.
962    //! To reduce space the serialization format of the snapshot avoids
963    //! duplication of tx hashes. The code takes advantage of the guarantee by
964    //! leveldb that keys are lexicographically sorted.
965    [[nodiscard]] util::Result<void> PopulateAndValidateSnapshot(
966        Chainstate& snapshot_chainstate,
967        AutoFile& coins_file,
968        const node::SnapshotMetadata& metadata);
969
970    /**
971     * If a block header hasn't already been seen, call CheckBlockHeader on it, ensure
972     * that it doesn't descend from an invalid block, and then add it to m_block_index.
973     * Caller must set min_pow_checked=true in order to add a new header to the
974     * block index (permanent memory storage), indicating that the header is
975     * known to be part of a sufficiently high-work chain (anti-dos check).
976     */
977    bool AcceptBlockHeader(
978        const CBlockHeader& block,
979        BlockValidationState& state,
980        CBlockIndex** ppindex,
981        bool min_pow_checked) EXCLUSIVE_LOCKS_REQUIRED(cs_main);
982    friend Chainstate;
983
984    /** Most recent headers presync progress update, for rate-limiting. */
985    MockableSteadyClock::time_point m_last_presync_update GUARDED_BY(GetMutex()){};
986
987    //! A queue for script verifications that have to be performed by worker threads.
988    CCheckQueue<CScriptCheck> m_script_check_queue;
989
990    //! Timers and counters used for benchmarking validation in both background
991    //! and active chainstates.
992    SteadyClock::duration GUARDED_BY(::cs_main) time_check{};
993    SteadyClock::duration GUARDED_BY(::cs_main) time_forks{};
994    SteadyClock::duration GUARDED_BY(::cs_main) time_connect{};
995    SteadyClock::duration GUARDED_BY(::cs_main) time_verify{};
996    SteadyClock::duration GUARDED_BY(::cs_main) time_undo{};
997    SteadyClock::duration GUARDED_BY(::cs_main) time_index{};
998    SteadyClock::duration GUARDED_BY(::cs_main) time_total{};
999    int64_t GUARDED_BY(::cs_main) num_blocks_total{0};
1000    SteadyClock::duration GUARDED_BY(::cs_main) time_connect_total{};