Inside Bitcoin

1001    SteadyClock::duration GUARDED_BY(::cs_main) time_flush{};
1002    SteadyClock::duration GUARDED_BY(::cs_main) time_chainstate{};
1003    SteadyClock::duration GUARDED_BY(::cs_main) time_post_connect{};
1004
1005protected:
1006    CBlockIndex* m_best_invalid GUARDED_BY(::cs_main){nullptr};
1007
1008public:
1009    using Options = kernel::ChainstateManagerOpts;
1010
1011    explicit ChainstateManager(const util::SignalInterrupt& interrupt, Options options, node::BlockManager::Options blockman_options);
1012
1013    //! Function to restart active indexes; set dynamically to avoid a circular
1014    //! dependency on `base/index.cpp`.
1015    std::function<void()> snapshot_download_completed = std::function<void()>();
1016
1017    const CChainParams& GetParams() const { return m_options.chainparams; }
1018    const Consensus::Params& GetConsensus() const { return m_options.chainparams.GetConsensus(); }
1019    bool ShouldCheckBlockIndex() const;
1020    const arith_uint256& MinimumChainWork() const { return *Assert(m_options.minimum_chain_work); }
1021    const uint256& AssumedValidBlock() const { return *Assert(m_options.assumed_valid_block); }
1022    kernel::Notifications& GetNotifications() const { return m_options.notifications; };
1023
1024    /**
1025     * Make various assertions about the state of the block index.
1026     *
1027     * By default this only executes fully when using the Regtest chain; see: m_options.check_block_index.
1028     */
1029    void CheckBlockIndex() const;
1030
1031    /**
1032     * Alias for ::cs_main.
1033     * Should be used in new code to make it easier to make ::cs_main a member
1034     * of this class.
1035     * Generally, methods of this class should be annotated to require this
1036     * mutex. This will make calling code more verbose, but also help to:
1037     * - Clarify that the method will acquire a mutex that heavily affects
1038     *   overall performance.
1039     * - Force call sites to think how long they need to acquire the mutex to
1040     *   get consistent results.
1041     */
1042    RecursiveMutex& GetMutex() const LOCK_RETURNED(::cs_main) { return ::cs_main; }
1043
1044    const util::SignalInterrupt& m_interrupt;
1045    const Options m_options;
1046    //! A single BlockManager instance is shared across each constructed
1047    //! chainstate to avoid duplicating block metadata.
1048    node::BlockManager m_blockman;
1049
1050    ValidationCache m_validation_cache;
1051
1052    /**
1053     * Whether initial block download (IBD) is ongoing.
1054     *
1055     * This value is used for lock-free IBD checks, and latches from true to
1056     * false once block loading has finished and the current chain tip has
1057     * enough work and is recent.
1058     */
1059    std::atomic_bool m_cached_is_ibd{true};
1060
1061    /**
1062     * Every received block is assigned a unique and increasing identifier, so we
1063     * know which one to give priority in case of a fork.
1064     */
1065    /** Blocks loaded from disk are assigned id SEQ_ID_INIT_FROM_DISK{1}
1066     * (SEQ_ID_BEST_CHAIN_FROM_DISK{0} if they belong to the best chain loaded from disk),
1067     * so start the counter after that. **/
1068    int32_t nBlockSequenceId GUARDED_BY(::cs_main) = SEQ_ID_INIT_FROM_DISK + 1;
1069    /** Decreasing counter (used by subsequent preciousblock calls). */
1070    int32_t nBlockReverseSequenceId = -1;
1071    /** chainwork for the last block that preciousblock has been applied to. */
1072    arith_uint256 nLastPreciousChainwork = 0;
1073
1074    // Reset the memory-only sequence counters we use to track block arrival
1075    // (used by tests to reset state)
1076    void ResetBlockSequenceCounters() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
1077    {
1078        AssertLockHeld(::cs_main);
1079        nBlockSequenceId = SEQ_ID_INIT_FROM_DISK + 1;
1080        nBlockReverseSequenceId = -1;
1081    }
1082
1083
1084    /** Best header we've seen so far for which the block is not known to be invalid
1085        (used, among others, for getheaders queries' starting points).
1086        In case of multiple best headers with the same work, it could point to any
1087        because CBlockIndexWorkComparator tiebreaker rules are not applied. */
1088    CBlockIndex* m_best_header GUARDED_BY(::cs_main){nullptr};
1089
1090    //! The total number of bytes available for us to use across all in-memory
1091    //! coins caches. This will be split somehow across chainstates.
1092    size_t m_total_coinstip_cache{0};
1093    //
1094    //! The total number of bytes available for us to use across all leveldb
1095    //! coins databases. This will be split somehow across chainstates.
1096    size_t m_total_coinsdb_cache{0};
1097
1098    /// Ensures a genesis block is in the block tree, possibly writing one to disk.
1099    [[nodiscard]] bool LoadGenesisBlock();
1100
1101    //! Instantiate a new chainstate.
1102    //!
1103    //! @param[in] mempool              The mempool to pass to the chainstate
1104    //                                  constructor
1105    Chainstate& InitializeChainstate(CTxMemPool* mempool) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
1106
1107    //! Construct and activate a Chainstate on the basis of UTXO snapshot data.
1108    //!
1109    //! Steps:
1110    //!
1111    //! - Initialize an unused Chainstate.
1112    //! - Load its `CoinsViews` contents from `coins_file`.
1113    //! - Verify that the hash of the resulting coinsdb matches the expected hash
1114    //!   per assumeutxo chain parameters.
1115    //! - Wait for our headers chain to include the base block of the snapshot.
1116    //! - "Fast forward" the tip of the new chainstate to the base of the snapshot.
1117    //! - Construct the new Chainstate and add it to m_chainstates.
1118    [[nodiscard]] util::Result<CBlockIndex*> ActivateSnapshot(
1119        AutoFile& coins_file, const node::SnapshotMetadata& metadata, bool in_memory);
1120
1121    //! Try to validate an assumeutxo snapshot by using a validated historical
1122    //! chainstate targeted at the snapshot block. When the target block is
1123    //! reached, the UTXO hash is computed and saved to
1124    //! `validated_cs.m_target_utxohash`, and `unvalidated_cs.m_assumeutxo` will
1125    //! be updated from UNVALIDATED to either VALIDATED or INVALID depending on
1126    //! whether the hash matches. The INVALID case should not happen in practice
1127    //! because the software should refuse to load unrecognized snapshots, but
1128    //! if it does happen, it is a fatal error.
1129    SnapshotCompletionResult MaybeValidateSnapshot(Chainstate& validated_cs, Chainstate& unvalidated_cs) EXCLUSIVE_LOCKS_REQUIRED(::cs_main);
1130
1131    //! Return current chainstate targeting the most-work, network tip.
1132    Chainstate& CurrentChainstate() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
1133    {
1134        for (auto& cs : m_chainstates) {
1135            if (cs && cs->m_assumeutxo != Assumeutxo::INVALID && !cs->TargetBlockHash()) return *cs;
1136        }
1137        abort();
1138    }
1139
1140    //! Return historical chainstate targeting a specific block, if any.
1141    Chainstate* HistoricalChainstate() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
1142    {
1143        for (auto& cs : m_chainstates) {
1144            if (cs && cs->m_assumeutxo != Assumeutxo::INVALID && cs->TargetBlockHash() && !cs->m_target_utxohash) return cs.get();
1145        }
1146        return nullptr;
1147    }
1148
1149    //! Return fully validated chainstate that should be used for indexing, to
1150    //! support indexes that need to index blocks in order and can't start from
1151    //! the snapshot block.
1152    Chainstate& ValidatedChainstate() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
1153    {
1154        for (auto* cs : {&CurrentChainstate(), HistoricalChainstate()}) {
1155            if (cs && cs->m_assumeutxo == Assumeutxo::VALIDATED) return *cs;
1156        }
1157        abort();
1158    }
1159
1160    //! Remove a chainstate.
1161    std::unique_ptr<Chainstate> RemoveChainstate(Chainstate& chainstate) EXCLUSIVE_LOCKS_REQUIRED(GetMutex())
1162    {
1163        auto it{std::find_if(m_chainstates.begin(), m_chainstates.end(), [&](auto& cs) { return cs.get() == &chainstate; })};
1164        if (it != m_chainstates.end()) {
1165            auto ret{std::move(*it)};
1166            m_chainstates.erase(it);
1167            return ret;
1168        }
1169        return nullptr;
1170    }
1171
1172    //! Alternatives to CurrentChainstate() used by older code to query latest
1173    //! chainstate information without locking cs_main. Newer code should avoid
1174    //! querying ChainstateManager and use Chainstate objects directly, or
1175    //! should use CurrentChainstate() instead.
1176    //! @{
1177    Chainstate& ActiveChainstate() const;
1178    CChain& ActiveChain() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChainstate().m_chain; }
1179    int ActiveHeight() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChain().Height(); }
1180    CBlockIndex* ActiveTip() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChain().Tip(); }
1181    //! @}
1182
1183    /**
1184     * Update and possibly latch the IBD status.
1185     *
1186     * If block loading has finished and the current chain tip has enough work
1187     * and is recent, set `m_cached_is_ibd` to false. This function never sets
1188     * the flag back to true.
1189     *
1190     * This should be called after operations that may affect IBD exit
1191     * conditions (e.g. after updating the active chain tip, or after
1192     * `ImportBlocks()` finishes).
1193     */
1194    void UpdateIBDStatus() EXCLUSIVE_LOCKS_REQUIRED(cs_main);
1195
1196    node::BlockMap& BlockIndex() EXCLUSIVE_LOCKS_REQUIRED(::cs_main)
1197    {
1198        AssertLockHeld(::cs_main);
1199        return m_blockman.m_block_index;
1200    }
1201
1202    /**
1203     * Track versionbit status
1204     */
1205    mutable VersionBitsCache m_versionbitscache;
1206
1207    /** Check whether we are doing an initial block download (synchronizing from disk or network) */
1208    bool IsInitialBlockDownload() const noexcept;
1209
1210    /** Guess verification progress (as a fraction between 0.0=genesis and 1.0=current tip).
1211    * This is also the case in the assumeutxo context, meaning that the progress reported for
1212    * the snapshot chainstate may suggest that all historical blocks have already been verified
1213    * even though that may not actually be the case. */
1214    double GuessVerificationProgress(const CBlockIndex* pindex) const EXCLUSIVE_LOCKS_REQUIRED(GetMutex());
1215
1216    /** Guess background verification progress in case assume-utxo was used (as a fraction between 0.0=genesis and 1.0=snapshot blocks). */
1217    double GetBackgroundVerificationProgress(const CBlockIndex& pindex) const EXCLUSIVE_LOCKS_REQUIRED(GetMutex());
1218
1219    /**
1220     * Import blocks from an external file
1221     *
1222     * During reindexing, this function is called for each block file (datadir/blocks/blk?????.dat).
1223     * It reads all blocks contained in the given file and attempts to process them (add them to the
1224     * block index). The blocks may be out of order within each file and across files. Often this
1225     * function reads a block but finds that its parent hasn't been read yet, so the block can't be
1226     * processed yet. The function will add an entry to the blocks_with_unknown_parent map (which is
1227     * passed as an argument), so that when the block's parent is later read and processed, this
1228     * function can re-read the child block from disk and process it.
1229     *
1230     * Because a block's parent may be in a later file, not just later in the same file, the
1231     * blocks_with_unknown_parent map must be passed in and out with each call. It's a multimap,
1232     * rather than just a map, because multiple blocks may have the same parent (when chain splits
1233     * or stale blocks exist). It maps from parent-hash to child-disk-position.
1234     *
1235     * This function can also be used to read blocks from user-specified block files using the
1236     * -loadblock= option. There's no unknown-parent tracking, so the last two arguments are omitted.
1237     *
1238     *
1239     * @param[in]     file_in                       File containing blocks to read
1240     * @param[in]     dbp                           (optional) Disk block position (only for reindex)
1241     * @param[in,out] blocks_with_unknown_parent    (optional) Map of disk positions for blocks with
1242     *                                              unknown parent, key is parent block hash
1243     *                                              (only used for reindex)
1244     * */
1245    void LoadExternalBlockFile(
1246        AutoFile& file_in,
1247        FlatFilePos* dbp = nullptr,
1248        std::multimap<uint256, FlatFilePos>* blocks_with_unknown_parent = nullptr);
1249
1250    /**