validation.h
1 // Copyright (c) 2009-2010 Satoshi Nakamoto 2 // Copyright (c) 2009-2022 The Bitcoin Core developers 3 // Distributed under the MIT software license, see the accompanying 4 // file COPYING or http://www.opensource.org/licenses/mit-license.php. 5 6 #ifndef BITCOIN_VALIDATION_H 7 #define BITCOIN_VALIDATION_H 8 9 #include <arith_uint256.h> 10 #include <attributes.h> 11 #include <chain.h> 12 #include <checkqueue.h> 13 #include <kernel/chain.h> 14 #include <consensus/amount.h> 15 #include <deploymentstatus.h> 16 #include <kernel/chainparams.h> 17 #include <kernel/chainstatemanager_opts.h> 18 #include <kernel/cs_main.h> // IWYU pragma: export 19 #include <node/blockstorage.h> 20 #include <policy/feerate.h> 21 #include <policy/packages.h> 22 #include <policy/policy.h> 23 #include <script/script_error.h> 24 #include <sync.h> 25 #include <txdb.h> 26 #include <txmempool.h> // For CTxMemPool::cs 27 #include <uint256.h> 28 #include <util/check.h> 29 #include <util/fs.h> 30 #include <util/hasher.h> 31 #include <util/result.h> 32 #include <util/translation.h> 33 #include <versionbits.h> 34 35 #include <atomic> 36 #include <map> 37 #include <memory> 38 #include <optional> 39 #include <set> 40 #include <stdint.h> 41 #include <string> 42 #include <thread> 43 #include <type_traits> 44 #include <utility> 45 #include <vector> 46 47 class Chainstate; 48 class CTxMemPool; 49 class ChainstateManager; 50 struct ChainTxData; 51 class DisconnectedBlockTransactions; 52 struct PrecomputedTransactionData; 53 struct LockPoints; 54 struct AssumeutxoData; 55 namespace node { 56 class SnapshotMetadata; 57 } // namespace node 58 namespace Consensus { 59 struct Params; 60 } // namespace Consensus 61 namespace util { 62 class SignalInterrupt; 63 } // namespace util 64 65 /** Block files containing a block-height within MIN_BLOCKS_TO_KEEP of ActiveChain().Tip() will not be pruned. */ 66 static const unsigned int MIN_BLOCKS_TO_KEEP = 288; 67 static const signed int DEFAULT_CHECKBLOCKS = 6; 68 static constexpr int DEFAULT_CHECKLEVEL{3}; 69 // Require that user allocate at least 550 MiB for block & undo files (blk???.dat and rev???.dat) 70 // At 1MB per block, 288 blocks = 288MB. 71 // Add 15% for Undo data = 331MB 72 // Add 20% for Orphan block rate = 397MB 73 // We want the low water mark after pruning to be at least 397 MB and since we prune in 74 // full block file chunks, we need the high water mark which triggers the prune to be 75 // one 128MB block file + added 15% undo data = 147MB greater for a total of 545MB 76 // Setting the target to >= 550 MiB will make it likely we can respect the target. 77 static const uint64_t MIN_DISK_SPACE_FOR_BLOCK_FILES = 550 * 1024 * 1024; 78 79 /** Current sync state passed to tip changed callbacks. */ 80 enum class SynchronizationState { 81 INIT_REINDEX, 82 INIT_DOWNLOAD, 83 POST_INIT 84 }; 85 86 extern GlobalMutex g_best_block_mutex; 87 extern std::condition_variable g_best_block_cv; 88 /** Used to notify getblocktemplate RPC of new tips. */ 89 extern uint256 g_best_block; 90 91 /** Documentation for argument 'checklevel'. */ 92 extern const std::vector<std::string> CHECKLEVEL_DOC; 93 94 CAmount GetBlockSubsidy(int nHeight, const Consensus::Params& consensusParams); 95 96 bool FatalError(kernel::Notifications& notifications, BlockValidationState& state, const bilingual_str& message); 97 98 /** Guess verification progress (as a fraction between 0.0=genesis and 1.0=current tip). */ 99 double GuessVerificationProgress(const ChainTxData& data, const CBlockIndex* pindex); 100 101 /** Prune block files up to a given height */ 102 void PruneBlockFilesManual(Chainstate& active_chainstate, int nManualPruneHeight); 103 104 /** 105 * Validation result for a transaction evaluated by MemPoolAccept (single or package). 106 * Here are the expected fields and properties of a result depending on its ResultType, applicable to 107 * results returned from package evaluation: 108 *+---------------------------+----------------+-------------------+------------------+----------------+-------------------+ 109 *| Field or property | VALID | INVALID | MEMPOOL_ENTRY | DIFFERENT_WITNESS | 110 *| | |--------------------------------------| | | 111 *| | | TX_RECONSIDERABLE | Other | | | 112 *+---------------------------+----------------+-------------------+------------------+----------------+-------------------+ 113 *| txid in mempool? | yes | no | no* | yes | yes | 114 *| wtxid in mempool? | yes | no | no* | yes | no | 115 *| m_state | yes, IsValid() | yes, IsInvalid() | yes, IsInvalid() | yes, IsValid() | yes, IsValid() | 116 *| m_replaced_transactions | yes | no | no | no | no | 117 *| m_vsize | yes | no | no | yes | no | 118 *| m_base_fees | yes | no | no | yes | no | 119 *| m_effective_feerate | yes | yes | no | no | no | 120 *| m_wtxids_fee_calculations | yes | yes | no | no | no | 121 *| m_other_wtxid | no | no | no | no | yes | 122 *+---------------------------+----------------+-------------------+------------------+----------------+-------------------+ 123 * (*) Individual transaction acceptance doesn't return MEMPOOL_ENTRY and DIFFERENT_WITNESS. It returns 124 * INVALID, with the errors txn-already-in-mempool and txn-same-nonwitness-data-in-mempool 125 * respectively. In those cases, the txid or wtxid may be in the mempool for a TX_CONFLICT. 126 */ 127 struct MempoolAcceptResult { 128 /** Used to indicate the results of mempool validation. */ 129 enum class ResultType { 130 VALID, //!> Fully validated, valid. 131 INVALID, //!> Invalid. 132 MEMPOOL_ENTRY, //!> Valid, transaction was already in the mempool. 133 DIFFERENT_WITNESS, //!> Not validated. A same-txid-different-witness tx (see m_other_wtxid) already exists in the mempool and was not replaced. 134 }; 135 /** Result type. Present in all MempoolAcceptResults. */ 136 const ResultType m_result_type; 137 138 /** Contains information about why the transaction failed. */ 139 const TxValidationState m_state; 140 141 /** Mempool transactions replaced by the tx. */ 142 const std::optional<std::list<CTransactionRef>> m_replaced_transactions; 143 /** Virtual size as used by the mempool, calculated using serialized size and sigops. */ 144 const std::optional<int64_t> m_vsize; 145 /** Raw base fees in satoshis. */ 146 const std::optional<CAmount> m_base_fees; 147 /** The feerate at which this transaction was considered. This includes any fee delta added 148 * using prioritisetransaction (i.e. modified fees). If this transaction was submitted as a 149 * package, this is the package feerate, which may also include its descendants and/or 150 * ancestors (see m_wtxids_fee_calculations below). 151 */ 152 const std::optional<CFeeRate> m_effective_feerate; 153 /** Contains the wtxids of the transactions used for fee-related checks. Includes this 154 * transaction's wtxid and may include others if this transaction was validated as part of a 155 * package. This is not necessarily equivalent to the list of transactions passed to 156 * ProcessNewPackage(). 157 * Only present when m_result_type = ResultType::VALID. */ 158 const std::optional<std::vector<Wtxid>> m_wtxids_fee_calculations; 159 160 /** The wtxid of the transaction in the mempool which has the same txid but different witness. */ 161 const std::optional<uint256> m_other_wtxid; 162 163 static MempoolAcceptResult Failure(TxValidationState state) { 164 return MempoolAcceptResult(state); 165 } 166 167 static MempoolAcceptResult FeeFailure(TxValidationState state, 168 CFeeRate effective_feerate, 169 const std::vector<Wtxid>& wtxids_fee_calculations) { 170 return MempoolAcceptResult(state, effective_feerate, wtxids_fee_calculations); 171 } 172 173 static MempoolAcceptResult Success(std::list<CTransactionRef>&& replaced_txns, 174 int64_t vsize, 175 CAmount fees, 176 CFeeRate effective_feerate, 177 const std::vector<Wtxid>& wtxids_fee_calculations) { 178 return MempoolAcceptResult(std::move(replaced_txns), vsize, fees, 179 effective_feerate, wtxids_fee_calculations); 180 } 181 182 static MempoolAcceptResult MempoolTx(int64_t vsize, CAmount fees) { 183 return MempoolAcceptResult(vsize, fees); 184 } 185 186 static MempoolAcceptResult MempoolTxDifferentWitness(const uint256& other_wtxid) { 187 return MempoolAcceptResult(other_wtxid); 188 } 189 190 // Private constructors. Use static methods MempoolAcceptResult::Success, etc. to construct. 191 private: 192 /** Constructor for failure case */ 193 explicit MempoolAcceptResult(TxValidationState state) 194 : m_result_type(ResultType::INVALID), m_state(state) { 195 Assume(!state.IsValid()); // Can be invalid or error 196 } 197 198 /** Constructor for success case */ 199 explicit MempoolAcceptResult(std::list<CTransactionRef>&& replaced_txns, 200 int64_t vsize, 201 CAmount fees, 202 CFeeRate effective_feerate, 203 const std::vector<Wtxid>& wtxids_fee_calculations) 204 : m_result_type(ResultType::VALID), 205 m_replaced_transactions(std::move(replaced_txns)), 206 m_vsize{vsize}, 207 m_base_fees(fees), 208 m_effective_feerate(effective_feerate), 209 m_wtxids_fee_calculations(wtxids_fee_calculations) {} 210 211 /** Constructor for fee-related failure case */ 212 explicit MempoolAcceptResult(TxValidationState state, 213 CFeeRate effective_feerate, 214 const std::vector<Wtxid>& wtxids_fee_calculations) 215 : m_result_type(ResultType::INVALID), 216 m_state(state), 217 m_effective_feerate(effective_feerate), 218 m_wtxids_fee_calculations(wtxids_fee_calculations) {} 219 220 /** Constructor for already-in-mempool case. It wouldn't replace any transactions. */ 221 explicit MempoolAcceptResult(int64_t vsize, CAmount fees) 222 : m_result_type(ResultType::MEMPOOL_ENTRY), m_vsize{vsize}, m_base_fees(fees) {} 223 224 /** Constructor for witness-swapped case. */ 225 explicit MempoolAcceptResult(const uint256& other_wtxid) 226 : m_result_type(ResultType::DIFFERENT_WITNESS), m_other_wtxid(other_wtxid) {} 227 }; 228 229 /** 230 * Validation result for package mempool acceptance. 231 */ 232 struct PackageMempoolAcceptResult 233 { 234 PackageValidationState m_state; 235 /** 236 * Map from wtxid to finished MempoolAcceptResults. The client is responsible 237 * for keeping track of the transaction objects themselves. If a result is not 238 * present, it means validation was unfinished for that transaction. If there 239 * was a package-wide error (see result in m_state), m_tx_results will be empty. 240 */ 241 std::map<uint256, MempoolAcceptResult> m_tx_results; 242 243 explicit PackageMempoolAcceptResult(PackageValidationState state, 244 std::map<uint256, MempoolAcceptResult>&& results) 245 : m_state{state}, m_tx_results(std::move(results)) {} 246 247 explicit PackageMempoolAcceptResult(PackageValidationState state, CFeeRate feerate, 248 std::map<uint256, MempoolAcceptResult>&& results) 249 : m_state{state}, m_tx_results(std::move(results)) {} 250 251 /** Constructor to create a PackageMempoolAcceptResult from a single MempoolAcceptResult */ 252 explicit PackageMempoolAcceptResult(const uint256& wtxid, const MempoolAcceptResult& result) 253 : m_tx_results{ {wtxid, result} } {} 254 }; 255 256 /** 257 * Try to add a transaction to the mempool. This is an internal function and is exposed only for testing. 258 * Client code should use ChainstateManager::ProcessTransaction() 259 * 260 * @param[in] active_chainstate Reference to the active chainstate. 261 * @param[in] tx The transaction to submit for mempool acceptance. 262 * @param[in] accept_time The timestamp for adding the transaction to the mempool. 263 * It is also used to determine when the entry expires. 264 * @param[in] bypass_limits When true, don't enforce mempool fee and capacity limits, 265 * and set entry_sequence to zero. 266 * @param[in] test_accept When true, run validation checks but don't submit to mempool. 267 * 268 * @returns a MempoolAcceptResult indicating whether the transaction was accepted/rejected with reason. 269 */ 270 MempoolAcceptResult AcceptToMemoryPool(Chainstate& active_chainstate, const CTransactionRef& tx, 271 int64_t accept_time, bool bypass_limits, bool test_accept) 272 EXCLUSIVE_LOCKS_REQUIRED(cs_main); 273 274 /** 275 * Validate (and maybe submit) a package to the mempool. See doc/policy/packages.md for full details 276 * on package validation rules. 277 * @param[in] test_accept When true, run validation checks but don't submit to mempool. 278 * @param[in] client_maxfeerate If exceeded by an individual transaction, rest of (sub)package evalution is aborted. 279 * Only for sanity checks against local submission of transactions. 280 * @returns a PackageMempoolAcceptResult which includes a MempoolAcceptResult for each transaction. 281 * If a transaction fails, validation will exit early and some results may be missing. It is also 282 * possible for the package to be partially submitted. 283 */ 284 PackageMempoolAcceptResult ProcessNewPackage(Chainstate& active_chainstate, CTxMemPool& pool, 285 const Package& txns, bool test_accept, const std::optional<CFeeRate>& client_maxfeerate) 286 EXCLUSIVE_LOCKS_REQUIRED(cs_main); 287 288 /* Mempool validation helper functions */ 289 290 /** 291 * Check if transaction will be final in the next block to be created. 292 */ 293 bool CheckFinalTxAtTip(const CBlockIndex& active_chain_tip, const CTransaction& tx) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 294 295 /** 296 * Calculate LockPoints required to check if transaction will be BIP68 final in the next block 297 * to be created on top of tip. 298 * 299 * @param[in] tip Chain tip for which tx sequence locks are calculated. For 300 * example, the tip of the current active chain. 301 * @param[in] coins_view Any CCoinsView that provides access to the relevant coins for 302 * checking sequence locks. For example, it can be a CCoinsViewCache 303 * that isn't connected to anything but contains all the relevant 304 * coins, or a CCoinsViewMemPool that is connected to the 305 * mempool and chainstate UTXO set. In the latter case, the caller 306 * is responsible for holding the appropriate locks to ensure that 307 * calls to GetCoin() return correct coins. 308 * @param[in] tx The transaction being evaluated. 309 * 310 * @returns The resulting height and time calculated and the hash of the block needed for 311 * calculation, or std::nullopt if there is an error. 312 */ 313 std::optional<LockPoints> CalculateLockPointsAtTip( 314 CBlockIndex* tip, 315 const CCoinsView& coins_view, 316 const CTransaction& tx); 317 318 /** 319 * Check if transaction will be BIP68 final in the next block to be created on top of tip. 320 * @param[in] tip Chain tip to check tx sequence locks against. For example, 321 * the tip of the current active chain. 322 * @param[in] lock_points LockPoints containing the height and time at which this 323 * transaction is final. 324 * Simulates calling SequenceLocks() with data from the tip passed in. 325 * The LockPoints should not be considered valid if CheckSequenceLocksAtTip returns false. 326 */ 327 bool CheckSequenceLocksAtTip(CBlockIndex* tip, 328 const LockPoints& lock_points); 329 330 /** 331 * Closure representing one script verification 332 * Note that this stores references to the spending transaction 333 */ 334 class CScriptCheck 335 { 336 private: 337 CTxOut m_tx_out; 338 const CTransaction *ptxTo; 339 unsigned int nIn; 340 unsigned int nFlags; 341 bool cacheStore; 342 ScriptError error{SCRIPT_ERR_UNKNOWN_ERROR}; 343 PrecomputedTransactionData *txdata; 344 345 public: 346 CScriptCheck(const CTxOut& outIn, const CTransaction& txToIn, unsigned int nInIn, unsigned int nFlagsIn, bool cacheIn, PrecomputedTransactionData* txdataIn) : 347 m_tx_out(outIn), ptxTo(&txToIn), nIn(nInIn), nFlags(nFlagsIn), cacheStore(cacheIn), txdata(txdataIn) { } 348 349 CScriptCheck(const CScriptCheck&) = delete; 350 CScriptCheck& operator=(const CScriptCheck&) = delete; 351 CScriptCheck(CScriptCheck&&) = default; 352 CScriptCheck& operator=(CScriptCheck&&) = default; 353 354 bool operator()(); 355 356 ScriptError GetScriptError() const { return error; } 357 }; 358 359 // CScriptCheck is used a lot in std::vector, make sure that's efficient 360 static_assert(std::is_nothrow_move_assignable_v<CScriptCheck>); 361 static_assert(std::is_nothrow_move_constructible_v<CScriptCheck>); 362 static_assert(std::is_nothrow_destructible_v<CScriptCheck>); 363 364 /** Initializes the script-execution cache */ 365 [[nodiscard]] bool InitScriptExecutionCache(size_t max_size_bytes); 366 367 /** Functions for validating blocks and updating the block tree */ 368 369 /** Context-independent validity checks */ 370 bool CheckBlock(const CBlock& block, BlockValidationState& state, const Consensus::Params& consensusParams, bool fCheckPOW = true, bool fCheckMerkleRoot = true); 371 372 /** Check a block is completely valid from start to finish (only works on top of our current best block) */ 373 bool TestBlockValidity(BlockValidationState& state, 374 const CChainParams& chainparams, 375 Chainstate& chainstate, 376 const CBlock& block, 377 CBlockIndex* pindexPrev, 378 bool fCheckPOW = true, 379 bool fCheckMerkleRoot = true) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 380 381 /** Check with the proof of work on each blockheader matches the value in nBits */ 382 bool HasValidProofOfWork(const std::vector<CBlockHeader>& headers, const Consensus::Params& consensusParams); 383 384 /** Check if a block has been mutated (with respect to its merkle root and witness commitments). */ 385 bool IsBlockMutated(const CBlock& block, bool check_witness_root); 386 387 /** Return the sum of the claimed work on a given set of headers. No verification of PoW is done. */ 388 arith_uint256 CalculateClaimedHeadersWork(const std::vector<CBlockHeader>& headers); 389 390 enum class VerifyDBResult { 391 SUCCESS, 392 CORRUPTED_BLOCK_DB, 393 INTERRUPTED, 394 SKIPPED_L3_CHECKS, 395 SKIPPED_MISSING_BLOCKS, 396 }; 397 398 /** RAII wrapper for VerifyDB: Verify consistency of the block and coin databases */ 399 class CVerifyDB 400 { 401 private: 402 kernel::Notifications& m_notifications; 403 404 public: 405 explicit CVerifyDB(kernel::Notifications& notifications); 406 ~CVerifyDB(); 407 [[nodiscard]] VerifyDBResult VerifyDB( 408 Chainstate& chainstate, 409 const Consensus::Params& consensus_params, 410 CCoinsView& coinsview, 411 int nCheckLevel, 412 int nCheckDepth) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 413 }; 414 415 enum DisconnectResult 416 { 417 DISCONNECT_OK, // All good. 418 DISCONNECT_UNCLEAN, // Rolled back, but UTXO set was inconsistent with block. 419 DISCONNECT_FAILED // Something else went wrong. 420 }; 421 422 class ConnectTrace; 423 424 /** @see Chainstate::FlushStateToDisk */ 425 enum class FlushStateMode { 426 NONE, 427 IF_NEEDED, 428 PERIODIC, 429 ALWAYS 430 }; 431 432 /** 433 * A convenience class for constructing the CCoinsView* hierarchy used 434 * to facilitate access to the UTXO set. 435 * 436 * This class consists of an arrangement of layered CCoinsView objects, 437 * preferring to store and retrieve coins in memory via `m_cacheview` but 438 * ultimately falling back on cache misses to the canonical store of UTXOs on 439 * disk, `m_dbview`. 440 */ 441 class CoinsViews { 442 443 public: 444 //! The lowest level of the CoinsViews cache hierarchy sits in a leveldb database on disk. 445 //! All unspent coins reside in this store. 446 CCoinsViewDB m_dbview GUARDED_BY(cs_main); 447 448 //! This view wraps access to the leveldb instance and handles read errors gracefully. 449 CCoinsViewErrorCatcher m_catcherview GUARDED_BY(cs_main); 450 451 //! This is the top layer of the cache hierarchy - it keeps as many coins in memory as 452 //! can fit per the dbcache setting. 453 std::unique_ptr<CCoinsViewCache> m_cacheview GUARDED_BY(cs_main); 454 455 //! This constructor initializes CCoinsViewDB and CCoinsViewErrorCatcher instances, but it 456 //! *does not* create a CCoinsViewCache instance by default. This is done separately because the 457 //! presence of the cache has implications on whether or not we're allowed to flush the cache's 458 //! state to disk, which should not be done until the health of the database is verified. 459 //! 460 //! All arguments forwarded onto CCoinsViewDB. 461 CoinsViews(DBParams db_params, CoinsViewOptions options); 462 463 //! Initialize the CCoinsViewCache member. 464 void InitCache() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 465 }; 466 467 enum class CoinsCacheSizeState 468 { 469 //! The coins cache is in immediate need of a flush. 470 CRITICAL = 2, 471 //! The cache is at >= 90% capacity. 472 LARGE = 1, 473 OK = 0 474 }; 475 476 /** 477 * Chainstate stores and provides an API to update our local knowledge of the 478 * current best chain. 479 * 480 * Eventually, the API here is targeted at being exposed externally as a 481 * consumable libconsensus library, so any functions added must only call 482 * other class member functions, pure functions in other parts of the consensus 483 * library, callbacks via the validation interface, or read/write-to-disk 484 * functions (eventually this will also be via callbacks). 485 * 486 * Anything that is contingent on the current tip of the chain is stored here, 487 * whereas block information and metadata independent of the current tip is 488 * kept in `BlockManager`. 489 */ 490 class Chainstate 491 { 492 protected: 493 /** 494 * The ChainState Mutex 495 * A lock that must be held when modifying this ChainState - held in ActivateBestChain() and 496 * InvalidateBlock() 497 */ 498 Mutex m_chainstate_mutex; 499 500 //! Optional mempool that is kept in sync with the chain. 501 //! Only the active chainstate has a mempool. 502 CTxMemPool* m_mempool; 503 504 //! Manages the UTXO set, which is a reflection of the contents of `m_chain`. 505 std::unique_ptr<CoinsViews> m_coins_views; 506 507 //! This toggle exists for use when doing background validation for UTXO 508 //! snapshots. 509 //! 510 //! In the expected case, it is set once the background validation chain reaches the 511 //! same height as the base of the snapshot and its UTXO set is found to hash to 512 //! the expected assumeutxo value. It signals that we should no longer connect 513 //! blocks to the background chainstate. When set on the background validation 514 //! chainstate, it signifies that we have fully validated the snapshot chainstate. 515 //! 516 //! In the unlikely case that the snapshot chainstate is found to be invalid, this 517 //! is set to true on the snapshot chainstate. 518 bool m_disabled GUARDED_BY(::cs_main) {false}; 519 520 //! Cached result of LookupBlockIndex(*m_from_snapshot_blockhash) 521 const CBlockIndex* m_cached_snapshot_base GUARDED_BY(::cs_main) {nullptr}; 522 523 public: 524 //! Reference to a BlockManager instance which itself is shared across all 525 //! Chainstate instances. 526 node::BlockManager& m_blockman; 527 528 //! The chainstate manager that owns this chainstate. The reference is 529 //! necessary so that this instance can check whether it is the active 530 //! chainstate within deeply nested method calls. 531 ChainstateManager& m_chainman; 532 533 explicit Chainstate( 534 CTxMemPool* mempool, 535 node::BlockManager& blockman, 536 ChainstateManager& chainman, 537 std::optional<uint256> from_snapshot_blockhash = std::nullopt); 538 539 //! Return the current role of the chainstate. See `ChainstateManager` 540 //! documentation for a description of the different types of chainstates. 541 //! 542 //! @sa ChainstateRole 543 ChainstateRole GetRole() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 544 545 /** 546 * Initialize the CoinsViews UTXO set database management data structures. The in-memory 547 * cache is initialized separately. 548 * 549 * All parameters forwarded to CoinsViews. 550 */ 551 void InitCoinsDB( 552 size_t cache_size_bytes, 553 bool in_memory, 554 bool should_wipe, 555 fs::path leveldb_name = "chainstate"); 556 557 //! Initialize the in-memory coins cache (to be done after the health of the on-disk database 558 //! is verified). 559 void InitCoinsCache(size_t cache_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 560 561 //! @returns whether or not the CoinsViews object has been fully initialized and we can 562 //! safely flush this object to disk. 563 bool CanFlushToDisk() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 564 { 565 AssertLockHeld(::cs_main); 566 return m_coins_views && m_coins_views->m_cacheview; 567 } 568 569 //! The current chain of blockheaders we consult and build on. 570 //! @see CChain, CBlockIndex. 571 CChain m_chain; 572 573 /** 574 * The blockhash which is the base of the snapshot this chainstate was created from. 575 * 576 * std::nullopt if this chainstate was not created from a snapshot. 577 */ 578 const std::optional<uint256> m_from_snapshot_blockhash; 579 580 /** 581 * The base of the snapshot this chainstate was created from. 582 * 583 * nullptr if this chainstate was not created from a snapshot. 584 */ 585 const CBlockIndex* SnapshotBase() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 586 587 /** 588 * The set of all CBlockIndex entries that have as much work as our current 589 * tip or more, and transaction data needed to be validated (with 590 * BLOCK_VALID_TRANSACTIONS for each block and its parents back to the 591 * genesis block or an assumeutxo snapshot block). Entries may be failed, 592 * though, and pruning nodes may be missing the data for the block. 593 */ 594 std::set<CBlockIndex*, node::CBlockIndexWorkComparator> setBlockIndexCandidates; 595 596 //! @returns A reference to the in-memory cache of the UTXO set. 597 CCoinsViewCache& CoinsTip() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 598 { 599 AssertLockHeld(::cs_main); 600 Assert(m_coins_views); 601 return *Assert(m_coins_views->m_cacheview); 602 } 603 604 //! @returns A reference to the on-disk UTXO set database. 605 CCoinsViewDB& CoinsDB() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 606 { 607 AssertLockHeld(::cs_main); 608 return Assert(m_coins_views)->m_dbview; 609 } 610 611 //! @returns A pointer to the mempool. 612 CTxMemPool* GetMempool() 613 { 614 return m_mempool; 615 } 616 617 //! @returns A reference to a wrapped view of the in-memory UTXO set that 618 //! handles disk read errors gracefully. 619 CCoinsViewErrorCatcher& CoinsErrorCatcher() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 620 { 621 AssertLockHeld(::cs_main); 622 return Assert(m_coins_views)->m_catcherview; 623 } 624 625 //! Destructs all objects related to accessing the UTXO set. 626 void ResetCoinsViews() { m_coins_views.reset(); } 627 628 //! Does this chainstate have a UTXO set attached? 629 bool HasCoinsViews() const { return (bool)m_coins_views; } 630 631 //! The cache size of the on-disk coins view. 632 size_t m_coinsdb_cache_size_bytes{0}; 633 634 //! The cache size of the in-memory coins view. 635 size_t m_coinstip_cache_size_bytes{0}; 636 637 //! Resize the CoinsViews caches dynamically and flush state to disk. 638 //! @returns true unless an error occurred during the flush. 639 bool ResizeCoinsCaches(size_t coinstip_size, size_t coinsdb_size) 640 EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 641 642 /** 643 * Update the on-disk chain state. 644 * The caches and indexes are flushed depending on the mode we're called with 645 * if they're too large, if it's been a while since the last write, 646 * or always and in all cases if we're in prune mode and are deleting files. 647 * 648 * If FlushStateMode::NONE is used, then FlushStateToDisk(...) won't do anything 649 * besides checking if we need to prune. 650 * 651 * @returns true unless a system error occurred 652 */ 653 bool FlushStateToDisk( 654 BlockValidationState& state, 655 FlushStateMode mode, 656 int nManualPruneHeight = 0); 657 658 //! Unconditionally flush all changes to disk. 659 void ForceFlushStateToDisk(); 660 661 //! Prune blockfiles from the disk if necessary and then flush chainstate changes 662 //! if we pruned. 663 void PruneAndFlush(); 664 665 /** 666 * Find the best known block, and make it the tip of the block chain. The 667 * result is either failure or an activated best chain. pblock is either 668 * nullptr or a pointer to a block that is already loaded (to avoid loading 669 * it again from disk). 670 * 671 * ActivateBestChain is split into steps (see ActivateBestChainStep) so that 672 * we avoid holding cs_main for an extended period of time; the length of this 673 * call may be quite long during reindexing or a substantial reorg. 674 * 675 * May not be called with cs_main held. May not be called in a 676 * validationinterface callback. 677 * 678 * Note that if this is called while a snapshot chainstate is active, and if 679 * it is called on a background chainstate whose tip has reached the base block 680 * of the snapshot, its execution will take *MINUTES* while it hashes the 681 * background UTXO set to verify the assumeutxo value the snapshot was activated 682 * with. `cs_main` will be held during this time. 683 * 684 * @returns true unless a system error occurred 685 */ 686 bool ActivateBestChain( 687 BlockValidationState& state, 688 std::shared_ptr<const CBlock> pblock = nullptr) 689 EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex) 690 LOCKS_EXCLUDED(::cs_main); 691 692 // Block (dis)connection on a given view: 693 DisconnectResult DisconnectBlock(const CBlock& block, const CBlockIndex* pindex, CCoinsViewCache& view) 694 EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 695 bool ConnectBlock(const CBlock& block, BlockValidationState& state, CBlockIndex* pindex, 696 CCoinsViewCache& view, bool fJustCheck = false) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 697 698 // Apply the effects of a block disconnection on the UTXO set. 699 bool DisconnectTip(BlockValidationState& state, DisconnectedBlockTransactions* disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs); 700 701 // Manual block validity manipulation: 702 /** Mark a block as precious and reorganize. 703 * 704 * May not be called in a validationinterface callback. 705 */ 706 bool PreciousBlock(BlockValidationState& state, CBlockIndex* pindex) 707 EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex) 708 LOCKS_EXCLUDED(::cs_main); 709 710 /** Mark a block as invalid. */ 711 bool InvalidateBlock(BlockValidationState& state, CBlockIndex* pindex) 712 EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex) 713 LOCKS_EXCLUDED(::cs_main); 714 715 /** Remove invalidity status from a block and its descendants. */ 716 void ResetBlockFailureFlags(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 717 718 /** Replay blocks that aren't fully applied to the database. */ 719 bool ReplayBlocks(); 720 721 /** Whether the chain state needs to be redownloaded due to lack of witness data */ 722 [[nodiscard]] bool NeedsRedownload() const EXCLUSIVE_LOCKS_REQUIRED(cs_main); 723 /** Ensures we have a genesis block in the block tree, possibly writing one to disk. */ 724 bool LoadGenesisBlock(); 725 726 void TryAddBlockIndexCandidate(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 727 728 void PruneBlockIndexCandidates(); 729 730 void ClearBlockIndexCandidates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 731 732 /** Find the last common block of this chain and a locator. */ 733 const CBlockIndex* FindForkInGlobalIndex(const CBlockLocator& locator) const EXCLUSIVE_LOCKS_REQUIRED(cs_main); 734 735 /** Update the chain tip based on database information, i.e. CoinsTip()'s best block. */ 736 bool LoadChainTip() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 737 738 //! Dictates whether we need to flush the cache to disk or not. 739 //! 740 //! @return the state of the size of the coins cache. 741 CoinsCacheSizeState GetCoinsCacheSizeState() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 742 743 CoinsCacheSizeState GetCoinsCacheSizeState( 744 size_t max_coins_cache_size_bytes, 745 size_t max_mempool_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 746 747 std::string ToString() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 748 749 //! Indirection necessary to make lock annotations work with an optional mempool. 750 RecursiveMutex* MempoolMutex() const LOCK_RETURNED(m_mempool->cs) 751 { 752 return m_mempool ? &m_mempool->cs : nullptr; 753 } 754 755 private: 756 bool ActivateBestChainStep(BlockValidationState& state, CBlockIndex* pindexMostWork, const std::shared_ptr<const CBlock>& pblock, bool& fInvalidFound, ConnectTrace& connectTrace) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs); 757 bool ConnectTip(BlockValidationState& state, CBlockIndex* pindexNew, const std::shared_ptr<const CBlock>& pblock, ConnectTrace& connectTrace, DisconnectedBlockTransactions& disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs); 758 759 void InvalidBlockFound(CBlockIndex* pindex, const BlockValidationState& state) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 760 CBlockIndex* FindMostWorkChain() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 761 762 bool RollforwardBlock(const CBlockIndex* pindex, CCoinsViewCache& inputs) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 763 764 void CheckForkWarningConditions() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 765 void InvalidChainFound(CBlockIndex* pindexNew) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 766 767 /** 768 * Make mempool consistent after a reorg, by re-adding or recursively erasing 769 * disconnected block transactions from the mempool, and also removing any 770 * other transactions from the mempool that are no longer valid given the new 771 * tip/height. 772 * 773 * Note: we assume that disconnectpool only contains transactions that are NOT 774 * confirmed in the current chain nor already in the mempool (otherwise, 775 * in-mempool descendants of such transactions would be removed). 776 * 777 * Passing fAddToMempool=false will skip trying to add the transactions back, 778 * and instead just erase from the mempool as needed. 779 */ 780 void MaybeUpdateMempoolForReorg( 781 DisconnectedBlockTransactions& disconnectpool, 782 bool fAddToMempool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs); 783 784 /** Check warning conditions and do some notifications on new chain tip set. */ 785 void UpdateTip(const CBlockIndex* pindexNew) 786 EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 787 788 SteadyClock::time_point m_last_write{}; 789 SteadyClock::time_point m_last_flush{}; 790 791 /** 792 * In case of an invalid snapshot, rename the coins leveldb directory so 793 * that it can be examined for issue diagnosis. 794 */ 795 [[nodiscard]] util::Result<void> InvalidateCoinsDBOnDisk() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 796 797 friend ChainstateManager; 798 }; 799 800 801 enum class SnapshotCompletionResult { 802 SUCCESS, 803 SKIPPED, 804 805 // Expected assumeutxo configuration data is not found for the height of the 806 // base block. 807 MISSING_CHAINPARAMS, 808 809 // Failed to generate UTXO statistics (to check UTXO set hash) for the background 810 // chainstate. 811 STATS_FAILED, 812 813 // The UTXO set hash of the background validation chainstate does not match 814 // the one expected by assumeutxo chainparams. 815 HASH_MISMATCH, 816 817 // The blockhash of the current tip of the background validation chainstate does 818 // not match the one expected by the snapshot chainstate. 819 BASE_BLOCKHASH_MISMATCH, 820 }; 821 822 /** 823 * Provides an interface for creating and interacting with one or two 824 * chainstates: an IBD chainstate generated by downloading blocks, and 825 * an optional snapshot chainstate loaded from a UTXO snapshot. Managed 826 * chainstates can be maintained at different heights simultaneously. 827 * 828 * This class provides abstractions that allow the retrieval of the current 829 * most-work chainstate ("Active") as well as chainstates which may be in 830 * background use to validate UTXO snapshots. 831 * 832 * Definitions: 833 * 834 * *IBD chainstate*: a chainstate whose current state has been "fully" 835 * validated by the initial block download process. 836 * 837 * *Snapshot chainstate*: a chainstate populated by loading in an 838 * assumeutxo UTXO snapshot. 839 * 840 * *Active chainstate*: the chainstate containing the current most-work 841 * chain. Consulted by most parts of the system (net_processing, 842 * wallet) as a reflection of the current chain and UTXO set. 843 * This may either be an IBD chainstate or a snapshot chainstate. 844 * 845 * *Background IBD chainstate*: an IBD chainstate for which the 846 * IBD process is happening in the background while use of the 847 * active (snapshot) chainstate allows the rest of the system to function. 848 */ 849 class ChainstateManager 850 { 851 private: 852 //! The chainstate used under normal operation (i.e. "regular" IBD) or, if 853 //! a snapshot is in use, for background validation. 854 //! 855 //! Its contents (including on-disk data) will be deleted *upon shutdown* 856 //! after background validation of the snapshot has completed. We do not 857 //! free the chainstate contents immediately after it finishes validation 858 //! to cautiously avoid a case where some other part of the system is still 859 //! using this pointer (e.g. net_processing). 860 //! 861 //! Once this pointer is set to a corresponding chainstate, it will not 862 //! be reset until init.cpp:Shutdown(). 863 //! 864 //! It is important for the pointer to not be deleted until shutdown, 865 //! because cs_main is not always held when the pointer is accessed, for 866 //! example when calling ActivateBestChain, so there's no way you could 867 //! prevent code from using the pointer while deleting it. 868 std::unique_ptr<Chainstate> m_ibd_chainstate GUARDED_BY(::cs_main); 869 870 //! A chainstate initialized on the basis of a UTXO snapshot. If this is 871 //! non-null, it is always our active chainstate. 872 //! 873 //! Once this pointer is set to a corresponding chainstate, it will not 874 //! be reset until init.cpp:Shutdown(). 875 //! 876 //! It is important for the pointer to not be deleted until shutdown, 877 //! because cs_main is not always held when the pointer is accessed, for 878 //! example when calling ActivateBestChain, so there's no way you could 879 //! prevent code from using the pointer while deleting it. 880 std::unique_ptr<Chainstate> m_snapshot_chainstate GUARDED_BY(::cs_main); 881 882 //! Points to either the ibd or snapshot chainstate; indicates our 883 //! most-work chain. 884 Chainstate* m_active_chainstate GUARDED_BY(::cs_main) {nullptr}; 885 886 CBlockIndex* m_best_invalid GUARDED_BY(::cs_main){nullptr}; 887 888 //! Internal helper for ActivateSnapshot(). 889 [[nodiscard]] bool PopulateAndValidateSnapshot( 890 Chainstate& snapshot_chainstate, 891 AutoFile& coins_file, 892 const node::SnapshotMetadata& metadata); 893 894 /** 895 * If a block header hasn't already been seen, call CheckBlockHeader on it, ensure 896 * that it doesn't descend from an invalid block, and then add it to m_block_index. 897 * Caller must set min_pow_checked=true in order to add a new header to the 898 * block index (permanent memory storage), indicating that the header is 899 * known to be part of a sufficiently high-work chain (anti-dos check). 900 */ 901 bool AcceptBlockHeader( 902 const CBlockHeader& block, 903 BlockValidationState& state, 904 CBlockIndex** ppindex, 905 bool min_pow_checked) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 906 friend Chainstate; 907 908 /** Most recent headers presync progress update, for rate-limiting. */ 909 std::chrono::time_point<std::chrono::steady_clock> m_last_presync_update GUARDED_BY(::cs_main) {}; 910 911 std::array<ThresholdConditionCache, VERSIONBITS_NUM_BITS> m_warningcache GUARDED_BY(::cs_main); 912 913 //! Return true if a chainstate is considered usable. 914 //! 915 //! This is false when a background validation chainstate has completed its 916 //! validation of an assumed-valid chainstate, or when a snapshot 917 //! chainstate has been found to be invalid. 918 bool IsUsable(const Chainstate* const cs) const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) { 919 return cs && !cs->m_disabled; 920 } 921 922 //! A queue for script verifications that have to be performed by worker threads. 923 CCheckQueue<CScriptCheck> m_script_check_queue; 924 925 public: 926 using Options = kernel::ChainstateManagerOpts; 927 928 explicit ChainstateManager(const util::SignalInterrupt& interrupt, Options options, node::BlockManager::Options blockman_options); 929 930 //! Function to restart active indexes; set dynamically to avoid a circular 931 //! dependency on `base/index.cpp`. 932 std::function<void()> restart_indexes = std::function<void()>(); 933 934 const CChainParams& GetParams() const { return m_options.chainparams; } 935 const Consensus::Params& GetConsensus() const { return m_options.chainparams.GetConsensus(); } 936 bool ShouldCheckBlockIndex() const { return *Assert(m_options.check_block_index); } 937 const arith_uint256& MinimumChainWork() const { return *Assert(m_options.minimum_chain_work); } 938 const uint256& AssumedValidBlock() const { return *Assert(m_options.assumed_valid_block); } 939 kernel::Notifications& GetNotifications() const { return m_options.notifications; }; 940 941 /** 942 * Make various assertions about the state of the block index. 943 * 944 * By default this only executes fully when using the Regtest chain; see: m_options.check_block_index. 945 */ 946 void CheckBlockIndex(); 947 948 /** 949 * Alias for ::cs_main. 950 * Should be used in new code to make it easier to make ::cs_main a member 951 * of this class. 952 * Generally, methods of this class should be annotated to require this 953 * mutex. This will make calling code more verbose, but also help to: 954 * - Clarify that the method will acquire a mutex that heavily affects 955 * overall performance. 956 * - Force call sites to think how long they need to acquire the mutex to 957 * get consistent results. 958 */ 959 RecursiveMutex& GetMutex() const LOCK_RETURNED(::cs_main) { return ::cs_main; } 960 961 const util::SignalInterrupt& m_interrupt; 962 const Options m_options; 963 std::thread m_thread_load; 964 //! A single BlockManager instance is shared across each constructed 965 //! chainstate to avoid duplicating block metadata. 966 node::BlockManager m_blockman; 967 968 /** 969 * Whether initial block download has ended and IsInitialBlockDownload 970 * should return false from now on. 971 * 972 * Mutable because we need to be able to mark IsInitialBlockDownload() 973 * const, which latches this for caching purposes. 974 */ 975 mutable std::atomic<bool> m_cached_finished_ibd{false}; 976 977 /** 978 * Every received block is assigned a unique and increasing identifier, so we 979 * know which one to give priority in case of a fork. 980 */ 981 /** Blocks loaded from disk are assigned id 0, so start the counter at 1. */ 982 int32_t nBlockSequenceId GUARDED_BY(::cs_main) = 1; 983 /** Decreasing counter (used by subsequent preciousblock calls). */ 984 int32_t nBlockReverseSequenceId = -1; 985 /** chainwork for the last block that preciousblock has been applied to. */ 986 arith_uint256 nLastPreciousChainwork = 0; 987 988 // Reset the memory-only sequence counters we use to track block arrival 989 // (used by tests to reset state) 990 void ResetBlockSequenceCounters() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 991 { 992 AssertLockHeld(::cs_main); 993 nBlockSequenceId = 1; 994 nBlockReverseSequenceId = -1; 995 } 996 997 998 /** 999 * In order to efficiently track invalidity of headers, we keep the set of 1000 * blocks which we tried to connect and found to be invalid here (ie which 1001 * were set to BLOCK_FAILED_VALID since the last restart). We can then 1002 * walk this set and check if a new header is a descendant of something in 1003 * this set, preventing us from having to walk m_block_index when we try 1004 * to connect a bad block and fail. 1005 * 1006 * While this is more complicated than marking everything which descends 1007 * from an invalid block as invalid at the time we discover it to be 1008 * invalid, doing so would require walking all of m_block_index to find all 1009 * descendants. Since this case should be very rare, keeping track of all 1010 * BLOCK_FAILED_VALID blocks in a set should be just fine and work just as 1011 * well. 1012 * 1013 * Because we already walk m_block_index in height-order at startup, we go 1014 * ahead and mark descendants of invalid blocks as FAILED_CHILD at that time, 1015 * instead of putting things in this set. 1016 */ 1017 std::set<CBlockIndex*> m_failed_blocks; 1018 1019 /** Best header we've seen so far (used for getheaders queries' starting points). */ 1020 CBlockIndex* m_best_header GUARDED_BY(::cs_main){nullptr}; 1021 1022 //! The total number of bytes available for us to use across all in-memory 1023 //! coins caches. This will be split somehow across chainstates. 1024 int64_t m_total_coinstip_cache{0}; 1025 // 1026 //! The total number of bytes available for us to use across all leveldb 1027 //! coins databases. This will be split somehow across chainstates. 1028 int64_t m_total_coinsdb_cache{0}; 1029 1030 //! Instantiate a new chainstate. 1031 //! 1032 //! @param[in] mempool The mempool to pass to the chainstate 1033 // constructor 1034 Chainstate& InitializeChainstate(CTxMemPool* mempool) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1035 1036 //! Get all chainstates currently being used. 1037 std::vector<Chainstate*> GetAll(); 1038 1039 //! Construct and activate a Chainstate on the basis of UTXO snapshot data. 1040 //! 1041 //! Steps: 1042 //! 1043 //! - Initialize an unused Chainstate. 1044 //! - Load its `CoinsViews` contents from `coins_file`. 1045 //! - Verify that the hash of the resulting coinsdb matches the expected hash 1046 //! per assumeutxo chain parameters. 1047 //! - Wait for our headers chain to include the base block of the snapshot. 1048 //! - "Fast forward" the tip of the new chainstate to the base of the snapshot, 1049 //! faking nTx* block index data along the way. 1050 //! - Move the new chainstate to `m_snapshot_chainstate` and make it our 1051 //! ChainstateActive(). 1052 [[nodiscard]] bool ActivateSnapshot( 1053 AutoFile& coins_file, const node::SnapshotMetadata& metadata, bool in_memory); 1054 1055 //! Once the background validation chainstate has reached the height which 1056 //! is the base of the UTXO snapshot in use, compare its coins to ensure 1057 //! they match those expected by the snapshot. 1058 //! 1059 //! If the coins match (expected), then mark the validation chainstate for 1060 //! deletion and continue using the snapshot chainstate as active. 1061 //! Otherwise, revert to using the ibd chainstate and shutdown. 1062 SnapshotCompletionResult MaybeCompleteSnapshotValidation() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1063 1064 //! Returns nullptr if no snapshot has been loaded. 1065 const CBlockIndex* GetSnapshotBaseBlock() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1066 1067 //! The most-work chain. 1068 Chainstate& ActiveChainstate() const; 1069 CChain& ActiveChain() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChainstate().m_chain; } 1070 int ActiveHeight() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChain().Height(); } 1071 CBlockIndex* ActiveTip() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChain().Tip(); } 1072 1073 //! The state of a background sync (for net processing) 1074 bool BackgroundSyncInProgress() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { 1075 return IsUsable(m_snapshot_chainstate.get()) && IsUsable(m_ibd_chainstate.get()); 1076 } 1077 1078 //! The tip of the background sync chain 1079 const CBlockIndex* GetBackgroundSyncTip() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { 1080 return BackgroundSyncInProgress() ? m_ibd_chainstate->m_chain.Tip() : nullptr; 1081 } 1082 1083 node::BlockMap& BlockIndex() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 1084 { 1085 AssertLockHeld(::cs_main); 1086 return m_blockman.m_block_index; 1087 } 1088 1089 /** 1090 * Track versionbit status 1091 */ 1092 mutable VersionBitsCache m_versionbitscache; 1093 1094 //! @returns true if a snapshot-based chainstate is in use. Also implies 1095 //! that a background validation chainstate is also in use. 1096 bool IsSnapshotActive() const; 1097 1098 std::optional<uint256> SnapshotBlockhash() const; 1099 1100 //! Is there a snapshot in use and has it been fully validated? 1101 bool IsSnapshotValidated() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 1102 { 1103 return m_snapshot_chainstate && m_ibd_chainstate && m_ibd_chainstate->m_disabled; 1104 } 1105 1106 /** Check whether we are doing an initial block download (synchronizing from disk or network) */ 1107 bool IsInitialBlockDownload() const; 1108 1109 /** 1110 * Import blocks from an external file 1111 * 1112 * During reindexing, this function is called for each block file (datadir/blocks/blk?????.dat). 1113 * It reads all blocks contained in the given file and attempts to process them (add them to the 1114 * block index). The blocks may be out of order within each file and across files. Often this 1115 * function reads a block but finds that its parent hasn't been read yet, so the block can't be 1116 * processed yet. The function will add an entry to the blocks_with_unknown_parent map (which is 1117 * passed as an argument), so that when the block's parent is later read and processed, this 1118 * function can re-read the child block from disk and process it. 1119 * 1120 * Because a block's parent may be in a later file, not just later in the same file, the 1121 * blocks_with_unknown_parent map must be passed in and out with each call. It's a multimap, 1122 * rather than just a map, because multiple blocks may have the same parent (when chain splits 1123 * or stale blocks exist). It maps from parent-hash to child-disk-position. 1124 * 1125 * This function can also be used to read blocks from user-specified block files using the 1126 * -loadblock= option. There's no unknown-parent tracking, so the last two arguments are omitted. 1127 * 1128 * 1129 * @param[in] file_in File containing blocks to read 1130 * @param[in] dbp (optional) Disk block position (only for reindex) 1131 * @param[in,out] blocks_with_unknown_parent (optional) Map of disk positions for blocks with 1132 * unknown parent, key is parent block hash 1133 * (only used for reindex) 1134 * */ 1135 void LoadExternalBlockFile( 1136 AutoFile& file_in, 1137 FlatFilePos* dbp = nullptr, 1138 std::multimap<uint256, FlatFilePos>* blocks_with_unknown_parent = nullptr); 1139 1140 /** 1141 * Process an incoming block. This only returns after the best known valid 1142 * block is made active. Note that it does not, however, guarantee that the 1143 * specific block passed to it has been checked for validity! 1144 * 1145 * If you want to *possibly* get feedback on whether block is valid, you must 1146 * install a CValidationInterface (see validationinterface.h) - this will have 1147 * its BlockChecked method called whenever *any* block completes validation. 1148 * 1149 * Note that we guarantee that either the proof-of-work is valid on block, or 1150 * (and possibly also) BlockChecked will have been called. 1151 * 1152 * May not be called in a validationinterface callback. 1153 * 1154 * @param[in] block The block we want to process. 1155 * @param[in] force_processing Process this block even if unrequested; used for non-network block sources. 1156 * @param[in] min_pow_checked True if proof-of-work anti-DoS checks have 1157 * been done by caller for headers chain 1158 * (note: only affects headers acceptance; if 1159 * block header is already present in block 1160 * index then this parameter has no effect) 1161 * @param[out] new_block A boolean which is set to indicate if the block was first received via this call 1162 * @returns If the block was processed, independently of block validity 1163 */ 1164 bool ProcessNewBlock(const std::shared_ptr<const CBlock>& block, bool force_processing, bool min_pow_checked, bool* new_block) LOCKS_EXCLUDED(cs_main); 1165 1166 /** 1167 * Process incoming block headers. 1168 * 1169 * May not be called in a 1170 * validationinterface callback. 1171 * 1172 * @param[in] block The block headers themselves 1173 * @param[in] min_pow_checked True if proof-of-work anti-DoS checks have been done by caller for headers chain 1174 * @param[out] state This may be set to an Error state if any error occurred processing them 1175 * @param[out] ppindex If set, the pointer will be set to point to the last new block index object for the given headers 1176 */ 1177 bool ProcessNewBlockHeaders(const std::vector<CBlockHeader>& block, bool min_pow_checked, BlockValidationState& state, const CBlockIndex** ppindex = nullptr) LOCKS_EXCLUDED(cs_main); 1178 1179 /** 1180 * Sufficiently validate a block for disk storage (and store on disk). 1181 * 1182 * @param[in] pblock The block we want to process. 1183 * @param[in] fRequested Whether we requested this block from a 1184 * peer. 1185 * @param[in] dbp The location on disk, if we are importing 1186 * this block from prior storage. 1187 * @param[in] min_pow_checked True if proof-of-work anti-DoS checks have 1188 * been done by caller for headers chain 1189 * 1190 * @param[out] state The state of the block validation. 1191 * @param[out] ppindex Optional return parameter to get the 1192 * CBlockIndex pointer for this block. 1193 * @param[out] fNewBlock Optional return parameter to indicate if the 1194 * block is new to our storage. 1195 * 1196 * @returns False if the block or header is invalid, or if saving to disk fails (likely a fatal error); true otherwise. 1197 */ 1198 bool AcceptBlock(const std::shared_ptr<const CBlock>& pblock, BlockValidationState& state, CBlockIndex** ppindex, bool fRequested, const FlatFilePos* dbp, bool* fNewBlock, bool min_pow_checked) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 1199 1200 void ReceivedBlockTransactions(const CBlock& block, CBlockIndex* pindexNew, const FlatFilePos& pos) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 1201 1202 /** 1203 * Try to add a transaction to the memory pool. 1204 * 1205 * @param[in] tx The transaction to submit for mempool acceptance. 1206 * @param[in] test_accept When true, run validation checks but don't submit to mempool. 1207 */ 1208 [[nodiscard]] MempoolAcceptResult ProcessTransaction(const CTransactionRef& tx, bool test_accept=false) 1209 EXCLUSIVE_LOCKS_REQUIRED(cs_main); 1210 1211 //! Load the block tree and coins database from disk, initializing state if we're running with -reindex 1212 bool LoadBlockIndex() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 1213 1214 //! Check to see if caches are out of balance and if so, call 1215 //! ResizeCoinsCaches() as needed. 1216 void MaybeRebalanceCaches() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1217 1218 /** Update uncommitted block structures (currently: only the witness reserved value). This is safe for submitted blocks. */ 1219 void UpdateUncommittedBlockStructures(CBlock& block, const CBlockIndex* pindexPrev) const; 1220 1221 /** Produce the necessary coinbase commitment for a block (modifies the hash, don't call for mined blocks). */ 1222 std::vector<unsigned char> GenerateCoinbaseCommitment(CBlock& block, const CBlockIndex* pindexPrev) const; 1223 1224 /** This is used by net_processing to report pre-synchronization progress of headers, as 1225 * headers are not yet fed to validation during that time, but validation is (for now) 1226 * responsible for logging and signalling through NotifyHeaderTip, so it needs this 1227 * information. */ 1228 void ReportHeadersPresync(const arith_uint256& work, int64_t height, int64_t timestamp); 1229 1230 //! When starting up, search the datadir for a chainstate based on a UTXO 1231 //! snapshot that is in the process of being validated. 1232 bool DetectSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1233 1234 void ResetChainstates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1235 1236 //! Remove the snapshot-based chainstate and all on-disk artifacts. 1237 //! Used when reindex{-chainstate} is called during snapshot use. 1238 [[nodiscard]] bool DeleteSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1239 1240 //! Switch the active chainstate to one based on a UTXO snapshot that was loaded 1241 //! previously. 1242 Chainstate& ActivateExistingSnapshot(uint256 base_blockhash) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1243 1244 //! If we have validated a snapshot chain during this runtime, copy its 1245 //! chainstate directory over to the main `chainstate` location, completing 1246 //! validation of the snapshot. 1247 //! 1248 //! If the cleanup succeeds, the caller will need to ensure chainstates are 1249 //! reinitialized, since ResetChainstates() will be called before leveldb 1250 //! directories are moved or deleted. 1251 //! 1252 //! @sa node/chainstate:LoadChainstate() 1253 bool ValidatedSnapshotCleanup() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1254 1255 //! @returns the chainstate that indexes should consult when ensuring that an 1256 //! index is synced with a chain where we can expect block index entries to have 1257 //! BLOCK_HAVE_DATA beneath the tip. 1258 //! 1259 //! In other words, give us the chainstate for which we can reasonably expect 1260 //! that all blocks beneath the tip have been indexed. In practice this means 1261 //! when using an assumed-valid chainstate based upon a snapshot, return only the 1262 //! fully validated chain. 1263 Chainstate& GetChainstateForIndexing() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1264 1265 //! Return the [start, end] (inclusive) of block heights we can prune. 1266 //! 1267 //! start > end is possible, meaning no blocks can be pruned. 1268 std::pair<int, int> GetPruneRange( 1269 const Chainstate& chainstate, int last_height_can_prune) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1270 1271 //! Return the height of the base block of the snapshot in use, if one exists, else 1272 //! nullopt. 1273 std::optional<int> GetSnapshotBaseHeight() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1274 1275 CCheckQueue<CScriptCheck>& GetCheckQueue() { return m_script_check_queue; } 1276 1277 ~ChainstateManager(); 1278 }; 1279 1280 /** Deployment* info via ChainstateManager */ 1281 template<typename DEP> 1282 bool DeploymentActiveAfter(const CBlockIndex* pindexPrev, const ChainstateManager& chainman, DEP dep) 1283 { 1284 return DeploymentActiveAfter(pindexPrev, chainman.GetConsensus(), dep, chainman.m_versionbitscache); 1285 } 1286 1287 template<typename DEP> 1288 bool DeploymentActiveAt(const CBlockIndex& index, const ChainstateManager& chainman, DEP dep) 1289 { 1290 return DeploymentActiveAt(index, chainman.GetConsensus(), dep, chainman.m_versionbitscache); 1291 } 1292 1293 template<typename DEP> 1294 bool DeploymentEnabled(const ChainstateManager& chainman, DEP dep) 1295 { 1296 return DeploymentEnabled(chainman.GetConsensus(), dep); 1297 } 1298 1299 /** Identifies blocks that overwrote an existing coinbase output in the UTXO set (see BIP30) */ 1300 bool IsBIP30Repeat(const CBlockIndex& block_index); 1301 1302 /** Identifies blocks which coinbase output was subsequently overwritten in the UTXO set (see BIP30) */ 1303 bool IsBIP30Unspendable(const CBlockIndex& block_index); 1304 1305 #endif // BITCOIN_VALIDATION_H