validation.h
1 // Copyright (c) 2009-2010 Satoshi Nakamoto 2 // Copyright (c) 2009-present 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 <consensus/amount.h> 14 #include <cuckoocache.h> 15 #include <deploymentstatus.h> 16 #include <kernel/chain.h> 17 #include <kernel/chainparams.h> 18 #include <kernel/chainstatemanager_opts.h> 19 #include <kernel/cs_main.h> // IWYU pragma: export 20 #include <node/blockstorage.h> 21 #include <policy/feerate.h> 22 #include <policy/packages.h> 23 #include <policy/policy.h> 24 #include <script/script_error.h> 25 #include <script/sigcache.h> 26 #include <script/verify_flags.h> 27 #include <sync.h> 28 #include <txdb.h> 29 #include <txmempool.h> 30 #include <uint256.h> 31 #include <util/byte_units.h> 32 #include <util/check.h> 33 #include <util/fs.h> 34 #include <util/hasher.h> 35 #include <util/result.h> 36 #include <util/time.h> 37 #include <util/translation.h> 38 #include <versionbits.h> 39 40 #include <algorithm> 41 #include <atomic> 42 #include <cstdint> 43 #include <map> 44 #include <memory> 45 #include <optional> 46 #include <set> 47 #include <span> 48 #include <string> 49 #include <type_traits> 50 #include <utility> 51 #include <vector> 52 53 class Chainstate; 54 class CTxMemPool; 55 class ChainstateManager; 56 struct ChainTxData; 57 class DisconnectedBlockTransactions; 58 struct PrecomputedTransactionData; 59 struct LockPoints; 60 struct AssumeutxoData; 61 namespace node { 62 class SnapshotMetadata; 63 } // namespace node 64 namespace Consensus { 65 struct Params; 66 } // namespace Consensus 67 namespace util { 68 class SignalInterrupt; 69 } // namespace util 70 71 /** Block files containing a block-height within MIN_BLOCKS_TO_KEEP of ActiveChain().Tip() will not be pruned. */ 72 static const unsigned int MIN_BLOCKS_TO_KEEP = 288; 73 static const signed int DEFAULT_CHECKBLOCKS = 6; 74 static constexpr int DEFAULT_CHECKLEVEL{3}; 75 // Require that user allocate at least 550 MiB for block & undo files (blk???.dat and rev???.dat) 76 // At 1MB per block, 288 blocks = 288MB. 77 // Add 15% for Undo data = 331MB 78 // Add 20% for Orphan block rate = 397MB 79 // We want the low water mark after pruning to be at least 397 MB and since we prune in 80 // full block file chunks, we need the high water mark which triggers the prune to be 81 // one 128MB block file + added 15% undo data = 147MB greater for a total of 545MB 82 // Setting the target to >= 550 MiB will make it likely we can respect the target. 83 static const uint64_t MIN_DISK_SPACE_FOR_BLOCK_FILES = 550 * 1024 * 1024; 84 85 /** Maximum number of dedicated script-checking threads allowed */ 86 static constexpr int MAX_SCRIPTCHECK_THREADS{15}; 87 88 /** Current sync state passed to tip changed callbacks. */ 89 enum class SynchronizationState { 90 INIT_REINDEX, 91 INIT_DOWNLOAD, 92 POST_INIT 93 }; 94 95 /** Documentation for argument 'checklevel'. */ 96 extern const std::vector<std::string> CHECKLEVEL_DOC; 97 98 CAmount GetBlockSubsidy(int nHeight, const Consensus::Params& consensusParams); 99 100 bool FatalError(kernel::Notifications& notifications, BlockValidationState& state, const bilingual_str& message); 101 102 /** Prune block files up to a given height */ 103 void PruneBlockFilesManual(Chainstate& active_chainstate, int nManualPruneHeight); 104 105 /** 106 * Validation result for a transaction evaluated by MemPoolAccept (single or package). 107 * Here are the expected fields and properties of a result depending on its ResultType, applicable to 108 * results returned from package evaluation: 109 *+---------------------------+----------------+-------------------+------------------+----------------+-------------------+ 110 *| Field or property | VALID | INVALID | MEMPOOL_ENTRY | DIFFERENT_WITNESS | 111 *| | |--------------------------------------| | | 112 *| | | TX_RECONSIDERABLE | Other | | | 113 *+---------------------------+----------------+-------------------+------------------+----------------+-------------------+ 114 *| txid in mempool? | yes | no | no* | yes | yes | 115 *| wtxid in mempool? | yes | no | no* | yes | no | 116 *| m_state | yes, IsValid() | yes, IsInvalid() | yes, IsInvalid() | yes, IsValid() | yes, IsValid() | 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::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<Wtxid> 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 Wtxid& 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 Wtxid& 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<Wtxid, MempoolAcceptResult> m_tx_results; 242 243 explicit PackageMempoolAcceptResult(PackageValidationState state, 244 std::map<Wtxid, MempoolAcceptResult>&& results) 245 : m_state{state}, m_tx_results(std::move(results)) {} 246 247 explicit PackageMempoolAcceptResult(PackageValidationState state, CFeeRate feerate, 248 std::map<Wtxid, 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 Wtxid& 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 evaluation 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 script_verify_flags m_flags; 341 bool cacheStore; 342 PrecomputedTransactionData *txdata; 343 SignatureCache* m_signature_cache; 344 345 public: 346 CScriptCheck(const CTxOut& outIn, const CTransaction& txToIn, SignatureCache& signature_cache, unsigned int nInIn, script_verify_flags flags, bool cacheIn, PrecomputedTransactionData* txdataIn) : 347 m_tx_out(outIn), ptxTo(&txToIn), nIn(nInIn), m_flags(flags), cacheStore(cacheIn), txdata(txdataIn), m_signature_cache(&signature_cache) { } 348 349 CScriptCheck(const CScriptCheck&) = delete; 350 CScriptCheck& operator=(const CScriptCheck&) = delete; 351 CScriptCheck(CScriptCheck&&) = default; 352 CScriptCheck& operator=(CScriptCheck&&) = default; 353 354 std::optional<std::pair<ScriptError, std::string>> operator()(); 355 }; 356 357 // CScriptCheck is used a lot in std::vector, make sure that's efficient 358 static_assert(std::is_nothrow_move_assignable_v<CScriptCheck>); 359 static_assert(std::is_nothrow_move_constructible_v<CScriptCheck>); 360 static_assert(std::is_nothrow_destructible_v<CScriptCheck>); 361 362 /** 363 * Convenience class for initializing and passing the script execution cache 364 * and signature cache. 365 */ 366 class ValidationCache 367 { 368 private: 369 //! Pre-initialized hasher to avoid having to recreate it for every hash calculation. 370 CSHA256 m_script_execution_cache_hasher; 371 372 public: 373 CuckooCache::cache<uint256, SignatureCacheHasher> m_script_execution_cache; 374 SignatureCache m_signature_cache; 375 376 ValidationCache(size_t script_execution_cache_bytes, size_t signature_cache_bytes); 377 378 ValidationCache(const ValidationCache&) = delete; 379 ValidationCache& operator=(const ValidationCache&) = delete; 380 381 //! Return a copy of the pre-initialized hasher. 382 CSHA256 ScriptExecutionCacheHasher() const { return m_script_execution_cache_hasher; } 383 }; 384 385 /** Functions for validating blocks and updating the block tree */ 386 387 /** Context-independent validity checks */ 388 bool CheckBlock(const CBlock& block, BlockValidationState& state, const Consensus::Params& consensusParams, bool fCheckPOW = true, bool fCheckMerkleRoot = true); 389 390 /** 391 * Verify a block, including transactions. 392 * 393 * @param[in] block The block we want to process. Must connect to the 394 * current tip. 395 * @param[in] chainstate The chainstate to connect to. 396 * @param[in] check_pow perform proof-of-work check, nBits in the header 397 * is always checked 398 * @param[in] check_merkle_root check the merkle root 399 * 400 * @return Valid or Invalid state. This doesn't currently return an Error state, 401 * and shouldn't unless there is something wrong with the existing 402 * chainstate. (This is different from functions like AcceptBlock which 403 * can fail trying to save new data.) 404 * 405 * For signets the challenge verification is skipped when check_pow is false. 406 */ 407 BlockValidationState TestBlockValidity( 408 Chainstate& chainstate, 409 const CBlock& block, 410 bool check_pow, 411 bool check_merkle_root) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 412 413 /** Check with the proof of work on each blockheader matches the value in nBits */ 414 bool HasValidProofOfWork(const std::vector<CBlockHeader>& headers, const Consensus::Params& consensusParams); 415 416 /** Check if a block has been mutated (with respect to its merkle root and witness commitments). */ 417 bool IsBlockMutated(const CBlock& block, bool check_witness_root); 418 419 /** Return the sum of the claimed work on a given set of headers. No verification of PoW is done. */ 420 arith_uint256 CalculateClaimedHeadersWork(std::span<const CBlockHeader> headers); 421 422 enum class VerifyDBResult { 423 SUCCESS, 424 CORRUPTED_BLOCK_DB, 425 INTERRUPTED, 426 SKIPPED_L3_CHECKS, 427 SKIPPED_MISSING_BLOCKS, 428 }; 429 430 /** RAII wrapper for VerifyDB: Verify consistency of the block and coin databases */ 431 class CVerifyDB 432 { 433 private: 434 kernel::Notifications& m_notifications; 435 436 public: 437 explicit CVerifyDB(kernel::Notifications& notifications); 438 ~CVerifyDB(); 439 [[nodiscard]] VerifyDBResult VerifyDB( 440 Chainstate& chainstate, 441 const Consensus::Params& consensus_params, 442 CCoinsView& coinsview, 443 int nCheckLevel, 444 int nCheckDepth) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 445 }; 446 447 enum DisconnectResult 448 { 449 DISCONNECT_OK, // All good. 450 DISCONNECT_UNCLEAN, // Rolled back, but UTXO set was inconsistent with block. 451 DISCONNECT_FAILED // Something else went wrong. 452 }; 453 454 class ConnectTrace; 455 456 /** @see Chainstate::FlushStateToDisk */ 457 inline constexpr std::array FlushStateModeNames{"NONE", "IF_NEEDED", "PERIODIC", "ALWAYS"}; 458 enum class FlushStateMode: uint8_t { 459 NONE, 460 IF_NEEDED, 461 PERIODIC, 462 ALWAYS 463 }; 464 465 /** 466 * A convenience class for constructing the CCoinsView* hierarchy used 467 * to facilitate access to the UTXO set. 468 * 469 * This class consists of an arrangement of layered CCoinsView objects, 470 * preferring to store and retrieve coins in memory via `m_cacheview` but 471 * ultimately falling back on cache misses to the canonical store of UTXOs on 472 * disk, `m_dbview`. 473 */ 474 class CoinsViews { 475 476 public: 477 //! The lowest level of the CoinsViews cache hierarchy sits in a leveldb database on disk. 478 //! All unspent coins reside in this store. 479 CCoinsViewDB m_dbview GUARDED_BY(cs_main); 480 481 //! This view wraps access to the leveldb instance and handles read errors gracefully. 482 CCoinsViewErrorCatcher m_catcherview GUARDED_BY(cs_main); 483 484 //! This is the top layer of the cache hierarchy - it keeps as many coins in memory as 485 //! can fit per the dbcache setting. 486 std::unique_ptr<CCoinsViewCache> m_cacheview GUARDED_BY(cs_main); 487 488 //! This constructor initializes CCoinsViewDB and CCoinsViewErrorCatcher instances, but it 489 //! *does not* create a CCoinsViewCache instance by default. This is done separately because the 490 //! presence of the cache has implications on whether or not we're allowed to flush the cache's 491 //! state to disk, which should not be done until the health of the database is verified. 492 //! 493 //! All arguments forwarded onto CCoinsViewDB. 494 CoinsViews(DBParams db_params, CoinsViewOptions options); 495 496 //! Initialize the CCoinsViewCache member. 497 void InitCache() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 498 }; 499 500 enum class CoinsCacheSizeState 501 { 502 //! The coins cache is in immediate need of a flush. 503 CRITICAL = 2, 504 //! The cache is at >= 90% capacity. 505 LARGE = 1, 506 OK = 0 507 }; 508 509 constexpr int64_t LargeCoinsCacheThreshold(int64_t total_space) noexcept 510 { 511 // No periodic flush needed if at least this much space is free 512 constexpr int64_t MAX_BLOCK_COINSDB_USAGE_BYTES{int64_t(10_MiB)}; 513 return std::max((total_space * 9) / 10, 514 total_space - MAX_BLOCK_COINSDB_USAGE_BYTES); 515 } 516 517 /** 518 * Chainstate stores and provides an API to update our local knowledge of the 519 * current best chain. 520 * 521 * Eventually, the API here is targeted at being exposed externally as a 522 * consumable library, so any functions added must only call 523 * other class member functions, pure functions in other parts of the consensus 524 * library, callbacks via the validation interface, or read/write-to-disk 525 * functions (eventually this will also be via callbacks). 526 * 527 * Anything that is contingent on the current tip of the chain is stored here, 528 * whereas block information and metadata independent of the current tip is 529 * kept in `BlockManager`. 530 */ 531 class Chainstate 532 { 533 protected: 534 /** 535 * The ChainState Mutex 536 * A lock that must be held when modifying this ChainState - held in ActivateBestChain() and 537 * InvalidateBlock() 538 */ 539 Mutex m_chainstate_mutex; 540 541 //! Optional mempool that is kept in sync with the chain. 542 //! Only the active chainstate has a mempool. 543 CTxMemPool* m_mempool; 544 545 //! Manages the UTXO set, which is a reflection of the contents of `m_chain`. 546 std::unique_ptr<CoinsViews> m_coins_views; 547 548 //! This toggle exists for use when doing background validation for UTXO 549 //! snapshots. 550 //! 551 //! In the expected case, it is set once the background validation chain reaches the 552 //! same height as the base of the snapshot and its UTXO set is found to hash to 553 //! the expected assumeutxo value. It signals that we should no longer connect 554 //! blocks to the background chainstate. When set on the background validation 555 //! chainstate, it signifies that we have fully validated the snapshot chainstate. 556 //! 557 //! In the unlikely case that the snapshot chainstate is found to be invalid, this 558 //! is set to true on the snapshot chainstate. 559 bool m_disabled GUARDED_BY(::cs_main) {false}; 560 561 //! Cached result of LookupBlockIndex(*m_from_snapshot_blockhash) 562 mutable const CBlockIndex* m_cached_snapshot_base GUARDED_BY(::cs_main){nullptr}; 563 564 std::optional<const char*> m_last_script_check_reason_logged GUARDED_BY(::cs_main){}; 565 566 public: 567 //! Reference to a BlockManager instance which itself is shared across all 568 //! Chainstate instances. 569 node::BlockManager& m_blockman; 570 571 //! The chainstate manager that owns this chainstate. The reference is 572 //! necessary so that this instance can check whether it is the active 573 //! chainstate within deeply nested method calls. 574 ChainstateManager& m_chainman; 575 576 explicit Chainstate( 577 CTxMemPool* mempool, 578 node::BlockManager& blockman, 579 ChainstateManager& chainman, 580 std::optional<uint256> from_snapshot_blockhash = std::nullopt); 581 582 //! Return the current role of the chainstate. See `ChainstateManager` 583 //! documentation for a description of the different types of chainstates. 584 //! 585 //! @sa ChainstateRole 586 ChainstateRole GetRole() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 587 588 /** 589 * Initialize the CoinsViews UTXO set database management data structures. The in-memory 590 * cache is initialized separately. 591 * 592 * All parameters forwarded to CoinsViews. 593 */ 594 void InitCoinsDB( 595 size_t cache_size_bytes, 596 bool in_memory, 597 bool should_wipe, 598 fs::path leveldb_name = "chainstate"); 599 600 //! Initialize the in-memory coins cache (to be done after the health of the on-disk database 601 //! is verified). 602 void InitCoinsCache(size_t cache_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 603 604 //! @returns whether or not the CoinsViews object has been fully initialized and we can 605 //! safely flush this object to disk. 606 bool CanFlushToDisk() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 607 { 608 AssertLockHeld(::cs_main); 609 return m_coins_views && m_coins_views->m_cacheview; 610 } 611 612 //! The current chain of blockheaders we consult and build on. 613 //! @see CChain, CBlockIndex. 614 CChain m_chain; 615 616 /** 617 * The blockhash which is the base of the snapshot this chainstate was created from. 618 * 619 * std::nullopt if this chainstate was not created from a snapshot. 620 */ 621 const std::optional<uint256> m_from_snapshot_blockhash; 622 623 /** 624 * The base of the snapshot this chainstate was created from. 625 * 626 * nullptr if this chainstate was not created from a snapshot. 627 */ 628 const CBlockIndex* SnapshotBase() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 629 630 /** 631 * The set of all CBlockIndex entries that have as much work as our current 632 * tip or more, and transaction data needed to be validated (with 633 * BLOCK_VALID_TRANSACTIONS for each block and its parents back to the 634 * genesis block or an assumeutxo snapshot block). Entries may be failed, 635 * though, and pruning nodes may be missing the data for the block. 636 */ 637 std::set<CBlockIndex*, node::CBlockIndexWorkComparator> setBlockIndexCandidates; 638 639 //! @returns A reference to the in-memory cache of the UTXO set. 640 CCoinsViewCache& CoinsTip() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 641 { 642 AssertLockHeld(::cs_main); 643 Assert(m_coins_views); 644 return *Assert(m_coins_views->m_cacheview); 645 } 646 647 //! @returns A reference to the on-disk UTXO set database. 648 CCoinsViewDB& CoinsDB() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 649 { 650 AssertLockHeld(::cs_main); 651 return Assert(m_coins_views)->m_dbview; 652 } 653 654 //! @returns A pointer to the mempool. 655 CTxMemPool* GetMempool() 656 { 657 return m_mempool; 658 } 659 660 //! @returns A reference to a wrapped view of the in-memory UTXO set that 661 //! handles disk read errors gracefully. 662 CCoinsViewErrorCatcher& CoinsErrorCatcher() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 663 { 664 AssertLockHeld(::cs_main); 665 return Assert(m_coins_views)->m_catcherview; 666 } 667 668 //! Destructs all objects related to accessing the UTXO set. 669 void ResetCoinsViews() { m_coins_views.reset(); } 670 671 //! Does this chainstate have a UTXO set attached? 672 bool HasCoinsViews() const { return (bool)m_coins_views; } 673 674 //! The cache size of the on-disk coins view. 675 size_t m_coinsdb_cache_size_bytes{0}; 676 677 //! The cache size of the in-memory coins view. 678 size_t m_coinstip_cache_size_bytes{0}; 679 680 //! Resize the CoinsViews caches dynamically and flush state to disk. 681 //! @returns true unless an error occurred during the flush. 682 bool ResizeCoinsCaches(size_t coinstip_size, size_t coinsdb_size) 683 EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 684 685 /** 686 * Update the on-disk chain state. 687 * The caches and indexes are flushed depending on the mode we're called with 688 * if they're too large, if it's been a while since the last write, 689 * or always and in all cases if we're in prune mode and are deleting files. 690 * 691 * If FlushStateMode::NONE is used, then FlushStateToDisk(...) won't do anything 692 * besides checking if we need to prune. 693 * 694 * @returns true unless a system error occurred 695 */ 696 bool FlushStateToDisk( 697 BlockValidationState& state, 698 FlushStateMode mode, 699 int nManualPruneHeight = 0); 700 701 //! Unconditionally flush all changes to disk. 702 void ForceFlushStateToDisk(); 703 704 //! Prune blockfiles from the disk if necessary and then flush chainstate changes 705 //! if we pruned. 706 void PruneAndFlush(); 707 708 /** 709 * Find the best known block, and make it the tip of the block chain. The 710 * result is either failure or an activated best chain. pblock is either 711 * nullptr or a pointer to a block that is already loaded (to avoid loading 712 * it again from disk). 713 * 714 * ActivateBestChain is split into steps (see ActivateBestChainStep) so that 715 * we avoid holding cs_main for an extended period of time; the length of this 716 * call may be quite long during reindexing or a substantial reorg. 717 * 718 * May not be called with cs_main held. May not be called in a 719 * validationinterface callback. 720 * 721 * Note that if this is called while a snapshot chainstate is active, and if 722 * it is called on a background chainstate whose tip has reached the base block 723 * of the snapshot, its execution will take *MINUTES* while it hashes the 724 * background UTXO set to verify the assumeutxo value the snapshot was activated 725 * with. `cs_main` will be held during this time. 726 * 727 * @returns true unless a system error occurred 728 */ 729 bool ActivateBestChain( 730 BlockValidationState& state, 731 std::shared_ptr<const CBlock> pblock = nullptr) 732 EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex) 733 LOCKS_EXCLUDED(::cs_main); 734 735 // Block (dis)connection on a given view: 736 DisconnectResult DisconnectBlock(const CBlock& block, const CBlockIndex* pindex, CCoinsViewCache& view) 737 EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 738 bool ConnectBlock(const CBlock& block, BlockValidationState& state, CBlockIndex* pindex, 739 CCoinsViewCache& view, bool fJustCheck = false) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 740 741 // Apply the effects of a block disconnection on the UTXO set. 742 bool DisconnectTip(BlockValidationState& state, DisconnectedBlockTransactions* disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs); 743 744 // Manual block validity manipulation: 745 /** Mark a block as precious and reorganize. 746 * 747 * May not be called in a validationinterface callback. 748 */ 749 bool PreciousBlock(BlockValidationState& state, CBlockIndex* pindex) 750 EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex) 751 LOCKS_EXCLUDED(::cs_main); 752 753 /** Mark a block as invalid. */ 754 bool InvalidateBlock(BlockValidationState& state, CBlockIndex* pindex) 755 EXCLUSIVE_LOCKS_REQUIRED(!m_chainstate_mutex) 756 LOCKS_EXCLUDED(::cs_main); 757 758 /** Set invalidity status to all descendants of a block */ 759 void SetBlockFailureFlags(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 760 761 /** Remove invalidity status from a block, its descendants and ancestors and reconsider them for activation */ 762 void ResetBlockFailureFlags(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 763 764 /** Replay blocks that aren't fully applied to the database. */ 765 bool ReplayBlocks(); 766 767 /** Whether the chain state needs to be redownloaded due to lack of witness data */ 768 [[nodiscard]] bool NeedsRedownload() const EXCLUSIVE_LOCKS_REQUIRED(cs_main); 769 /** Ensures we have a genesis block in the block tree, possibly writing one to disk. */ 770 bool LoadGenesisBlock(); 771 772 void TryAddBlockIndexCandidate(CBlockIndex* pindex) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 773 774 void PruneBlockIndexCandidates(); 775 776 void ClearBlockIndexCandidates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 777 778 /** Find the last common block of this chain and a locator. */ 779 const CBlockIndex* FindForkInGlobalIndex(const CBlockLocator& locator) const EXCLUSIVE_LOCKS_REQUIRED(cs_main); 780 781 /** Update the chain tip based on database information, i.e. CoinsTip()'s best block. */ 782 bool LoadChainTip() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 783 784 //! Dictates whether we need to flush the cache to disk or not. 785 //! 786 //! @return the state of the size of the coins cache. 787 CoinsCacheSizeState GetCoinsCacheSizeState() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 788 789 CoinsCacheSizeState GetCoinsCacheSizeState( 790 size_t max_coins_cache_size_bytes, 791 size_t max_mempool_size_bytes) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 792 793 std::string ToString() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 794 795 //! Indirection necessary to make lock annotations work with an optional mempool. 796 RecursiveMutex* MempoolMutex() const LOCK_RETURNED(m_mempool->cs) 797 { 798 return m_mempool ? &m_mempool->cs : nullptr; 799 } 800 801 protected: 802 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); 803 bool ConnectTip( 804 BlockValidationState& state, 805 CBlockIndex* pindexNew, 806 std::shared_ptr<const CBlock> block_to_connect, 807 ConnectTrace& connectTrace, 808 DisconnectedBlockTransactions& disconnectpool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs); 809 810 void InvalidBlockFound(CBlockIndex* pindex, const BlockValidationState& state) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 811 CBlockIndex* FindMostWorkChain() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 812 813 bool RollforwardBlock(const CBlockIndex* pindex, CCoinsViewCache& inputs) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 814 815 void CheckForkWarningConditions() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 816 void InvalidChainFound(CBlockIndex* pindexNew) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 817 818 /** 819 * Make mempool consistent after a reorg, by re-adding or recursively erasing 820 * disconnected block transactions from the mempool, and also removing any 821 * other transactions from the mempool that are no longer valid given the new 822 * tip/height. 823 * 824 * Note: we assume that disconnectpool only contains transactions that are NOT 825 * confirmed in the current chain nor already in the mempool (otherwise, 826 * in-mempool descendants of such transactions would be removed). 827 * 828 * Passing fAddToMempool=false will skip trying to add the transactions back, 829 * and instead just erase from the mempool as needed. 830 */ 831 void MaybeUpdateMempoolForReorg( 832 DisconnectedBlockTransactions& disconnectpool, 833 bool fAddToMempool) EXCLUSIVE_LOCKS_REQUIRED(cs_main, m_mempool->cs); 834 835 /** Check warning conditions and do some notifications on new chain tip set. */ 836 void UpdateTip(const CBlockIndex* pindexNew) 837 EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 838 839 NodeClock::time_point m_next_write{NodeClock::time_point::max()}; 840 841 /** 842 * In case of an invalid snapshot, rename the coins leveldb directory so 843 * that it can be examined for issue diagnosis. 844 */ 845 [[nodiscard]] util::Result<void> InvalidateCoinsDBOnDisk() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 846 847 friend ChainstateManager; 848 }; 849 850 enum class SnapshotCompletionResult { 851 SUCCESS, 852 SKIPPED, 853 854 // Expected assumeutxo configuration data is not found for the height of the 855 // base block. 856 MISSING_CHAINPARAMS, 857 858 // Failed to generate UTXO statistics (to check UTXO set hash) for the background 859 // chainstate. 860 STATS_FAILED, 861 862 // The UTXO set hash of the background validation chainstate does not match 863 // the one expected by assumeutxo chainparams. 864 HASH_MISMATCH, 865 866 // The blockhash of the current tip of the background validation chainstate does 867 // not match the one expected by the snapshot chainstate. 868 BASE_BLOCKHASH_MISMATCH, 869 }; 870 871 /** 872 * Provides an interface for creating and interacting with one or two 873 * chainstates: an IBD chainstate generated by downloading blocks, and 874 * an optional snapshot chainstate loaded from a UTXO snapshot. Managed 875 * chainstates can be maintained at different heights simultaneously. 876 * 877 * This class provides abstractions that allow the retrieval of the current 878 * most-work chainstate ("Active") as well as chainstates which may be in 879 * background use to validate UTXO snapshots. 880 * 881 * Definitions: 882 * 883 * *IBD chainstate*: a chainstate whose current state has been "fully" 884 * validated by the initial block download process. 885 * 886 * *Snapshot chainstate*: a chainstate populated by loading in an 887 * assumeutxo UTXO snapshot. 888 * 889 * *Active chainstate*: the chainstate containing the current most-work 890 * chain. Consulted by most parts of the system (net_processing, 891 * wallet) as a reflection of the current chain and UTXO set. 892 * This may either be an IBD chainstate or a snapshot chainstate. 893 * 894 * *Background IBD chainstate*: an IBD chainstate for which the 895 * IBD process is happening in the background while use of the 896 * active (snapshot) chainstate allows the rest of the system to function. 897 */ 898 class ChainstateManager 899 { 900 private: 901 //! The chainstate used under normal operation (i.e. "regular" IBD) or, if 902 //! a snapshot is in use, for background validation. 903 //! 904 //! Its contents (including on-disk data) will be deleted *upon shutdown* 905 //! after background validation of the snapshot has completed. We do not 906 //! free the chainstate contents immediately after it finishes validation 907 //! to cautiously avoid a case where some other part of the system is still 908 //! using this pointer (e.g. net_processing). 909 //! 910 //! Once this pointer is set to a corresponding chainstate, it will not 911 //! be reset until init.cpp:Shutdown(). 912 //! 913 //! It is important for the pointer to not be deleted until shutdown, 914 //! because cs_main is not always held when the pointer is accessed, for 915 //! example when calling ActivateBestChain, so there's no way you could 916 //! prevent code from using the pointer while deleting it. 917 std::unique_ptr<Chainstate> m_ibd_chainstate GUARDED_BY(::cs_main); 918 919 //! A chainstate initialized on the basis of a UTXO snapshot. If this is 920 //! non-null, it is always our active chainstate. 921 //! 922 //! Once this pointer is set to a corresponding chainstate, it will not 923 //! be reset until init.cpp:Shutdown(). 924 //! 925 //! It is important for the pointer to not be deleted until shutdown, 926 //! because cs_main is not always held when the pointer is accessed, for 927 //! example when calling ActivateBestChain, so there's no way you could 928 //! prevent code from using the pointer while deleting it. 929 std::unique_ptr<Chainstate> m_snapshot_chainstate GUARDED_BY(::cs_main); 930 931 //! Points to either the ibd or snapshot chainstate; indicates our 932 //! most-work chain. 933 Chainstate* m_active_chainstate GUARDED_BY(::cs_main) {nullptr}; 934 935 CBlockIndex* m_best_invalid GUARDED_BY(::cs_main){nullptr}; 936 937 /** The last header for which a headerTip notification was issued. */ 938 CBlockIndex* m_last_notified_header GUARDED_BY(GetMutex()){nullptr}; 939 940 bool NotifyHeaderTip() LOCKS_EXCLUDED(GetMutex()); 941 942 //! Internal helper for ActivateSnapshot(). 943 //! 944 //! De-serialization of a snapshot that is created with 945 //! the dumptxoutset RPC. 946 //! To reduce space the serialization format of the snapshot avoids 947 //! duplication of tx hashes. The code takes advantage of the guarantee by 948 //! leveldb that keys are lexicographically sorted. 949 [[nodiscard]] util::Result<void> PopulateAndValidateSnapshot( 950 Chainstate& snapshot_chainstate, 951 AutoFile& coins_file, 952 const node::SnapshotMetadata& metadata); 953 954 /** 955 * If a block header hasn't already been seen, call CheckBlockHeader on it, ensure 956 * that it doesn't descend from an invalid block, and then add it to m_block_index. 957 * Caller must set min_pow_checked=true in order to add a new header to the 958 * block index (permanent memory storage), indicating that the header is 959 * known to be part of a sufficiently high-work chain (anti-dos check). 960 */ 961 bool AcceptBlockHeader( 962 const CBlockHeader& block, 963 BlockValidationState& state, 964 CBlockIndex** ppindex, 965 bool min_pow_checked) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 966 friend Chainstate; 967 968 /** Most recent headers presync progress update, for rate-limiting. */ 969 MockableSteadyClock::time_point m_last_presync_update GUARDED_BY(GetMutex()){}; 970 971 //! Return true if a chainstate is considered usable. 972 //! 973 //! This is false when a background validation chainstate has completed its 974 //! validation of an assumed-valid chainstate, or when a snapshot 975 //! chainstate has been found to be invalid. 976 bool IsUsable(const Chainstate* const cs) const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) { 977 return cs && !cs->m_disabled; 978 } 979 980 //! A queue for script verifications that have to be performed by worker threads. 981 CCheckQueue<CScriptCheck> m_script_check_queue; 982 983 //! Timers and counters used for benchmarking validation in both background 984 //! and active chainstates. 985 SteadyClock::duration GUARDED_BY(::cs_main) time_check{}; 986 SteadyClock::duration GUARDED_BY(::cs_main) time_forks{}; 987 SteadyClock::duration GUARDED_BY(::cs_main) time_connect{}; 988 SteadyClock::duration GUARDED_BY(::cs_main) time_verify{}; 989 SteadyClock::duration GUARDED_BY(::cs_main) time_undo{}; 990 SteadyClock::duration GUARDED_BY(::cs_main) time_index{}; 991 SteadyClock::duration GUARDED_BY(::cs_main) time_total{}; 992 int64_t GUARDED_BY(::cs_main) num_blocks_total{0}; 993 SteadyClock::duration GUARDED_BY(::cs_main) time_connect_total{}; 994 SteadyClock::duration GUARDED_BY(::cs_main) time_flush{}; 995 SteadyClock::duration GUARDED_BY(::cs_main) time_chainstate{}; 996 SteadyClock::duration GUARDED_BY(::cs_main) time_post_connect{}; 997 998 public: 999 using Options = kernel::ChainstateManagerOpts; 1000 1001 explicit ChainstateManager(const util::SignalInterrupt& interrupt, Options options, node::BlockManager::Options blockman_options); 1002 1003 //! Function to restart active indexes; set dynamically to avoid a circular 1004 //! dependency on `base/index.cpp`. 1005 std::function<void()> snapshot_download_completed = std::function<void()>(); 1006 1007 const CChainParams& GetParams() const { return m_options.chainparams; } 1008 const Consensus::Params& GetConsensus() const { return m_options.chainparams.GetConsensus(); } 1009 bool ShouldCheckBlockIndex() const; 1010 const arith_uint256& MinimumChainWork() const { return *Assert(m_options.minimum_chain_work); } 1011 const uint256& AssumedValidBlock() const { return *Assert(m_options.assumed_valid_block); } 1012 kernel::Notifications& GetNotifications() const { return m_options.notifications; }; 1013 1014 /** 1015 * Make various assertions about the state of the block index. 1016 * 1017 * By default this only executes fully when using the Regtest chain; see: m_options.check_block_index. 1018 */ 1019 void CheckBlockIndex() const; 1020 1021 /** 1022 * Alias for ::cs_main. 1023 * Should be used in new code to make it easier to make ::cs_main a member 1024 * of this class. 1025 * Generally, methods of this class should be annotated to require this 1026 * mutex. This will make calling code more verbose, but also help to: 1027 * - Clarify that the method will acquire a mutex that heavily affects 1028 * overall performance. 1029 * - Force call sites to think how long they need to acquire the mutex to 1030 * get consistent results. 1031 */ 1032 RecursiveMutex& GetMutex() const LOCK_RETURNED(::cs_main) { return ::cs_main; } 1033 1034 const util::SignalInterrupt& m_interrupt; 1035 const Options m_options; 1036 //! A single BlockManager instance is shared across each constructed 1037 //! chainstate to avoid duplicating block metadata. 1038 node::BlockManager m_blockman; 1039 1040 ValidationCache m_validation_cache; 1041 1042 /** 1043 * Whether initial block download has ended and IsInitialBlockDownload 1044 * should return false from now on. 1045 * 1046 * Mutable because we need to be able to mark IsInitialBlockDownload() 1047 * const, which latches this for caching purposes. 1048 */ 1049 mutable std::atomic<bool> m_cached_finished_ibd{false}; 1050 1051 /** 1052 * Every received block is assigned a unique and increasing identifier, so we 1053 * know which one to give priority in case of a fork. 1054 */ 1055 /** Blocks loaded from disk are assigned id SEQ_ID_INIT_FROM_DISK{1} 1056 * (SEQ_ID_BEST_CHAIN_FROM_DISK{0} if they belong to the best chain loaded from disk), 1057 * so start the counter after that. **/ 1058 int32_t nBlockSequenceId GUARDED_BY(::cs_main) = SEQ_ID_INIT_FROM_DISK + 1; 1059 /** Decreasing counter (used by subsequent preciousblock calls). */ 1060 int32_t nBlockReverseSequenceId = -1; 1061 /** chainwork for the last block that preciousblock has been applied to. */ 1062 arith_uint256 nLastPreciousChainwork = 0; 1063 1064 // Reset the memory-only sequence counters we use to track block arrival 1065 // (used by tests to reset state) 1066 void ResetBlockSequenceCounters() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 1067 { 1068 AssertLockHeld(::cs_main); 1069 nBlockSequenceId = SEQ_ID_INIT_FROM_DISK + 1; 1070 nBlockReverseSequenceId = -1; 1071 } 1072 1073 1074 /** Best header we've seen so far for which the block is not known to be invalid 1075 (used, among others, for getheaders queries' starting points). 1076 In case of multiple best headers with the same work, it could point to any 1077 because CBlockIndexWorkComparator tiebreaker rules are not applied. */ 1078 CBlockIndex* m_best_header GUARDED_BY(::cs_main){nullptr}; 1079 1080 //! The total number of bytes available for us to use across all in-memory 1081 //! coins caches. This will be split somehow across chainstates. 1082 size_t m_total_coinstip_cache{0}; 1083 // 1084 //! The total number of bytes available for us to use across all leveldb 1085 //! coins databases. This will be split somehow across chainstates. 1086 size_t m_total_coinsdb_cache{0}; 1087 1088 //! Instantiate a new chainstate. 1089 //! 1090 //! @param[in] mempool The mempool to pass to the chainstate 1091 // constructor 1092 Chainstate& InitializeChainstate(CTxMemPool* mempool) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1093 1094 //! Get all chainstates currently being used. 1095 std::vector<Chainstate*> GetAll(); 1096 1097 //! Construct and activate a Chainstate on the basis of UTXO snapshot data. 1098 //! 1099 //! Steps: 1100 //! 1101 //! - Initialize an unused Chainstate. 1102 //! - Load its `CoinsViews` contents from `coins_file`. 1103 //! - Verify that the hash of the resulting coinsdb matches the expected hash 1104 //! per assumeutxo chain parameters. 1105 //! - Wait for our headers chain to include the base block of the snapshot. 1106 //! - "Fast forward" the tip of the new chainstate to the base of the snapshot. 1107 //! - Move the new chainstate to `m_snapshot_chainstate` and make it our 1108 //! ChainstateActive(). 1109 [[nodiscard]] util::Result<CBlockIndex*> ActivateSnapshot( 1110 AutoFile& coins_file, const node::SnapshotMetadata& metadata, bool in_memory); 1111 1112 //! Once the background validation chainstate has reached the height which 1113 //! is the base of the UTXO snapshot in use, compare its coins to ensure 1114 //! they match those expected by the snapshot. 1115 //! 1116 //! If the coins match (expected), then mark the validation chainstate for 1117 //! deletion and continue using the snapshot chainstate as active. 1118 //! Otherwise, revert to using the ibd chainstate and shutdown. 1119 SnapshotCompletionResult MaybeCompleteSnapshotValidation() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1120 1121 //! Returns nullptr if no snapshot has been loaded. 1122 const CBlockIndex* GetSnapshotBaseBlock() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1123 1124 //! The most-work chain. 1125 Chainstate& ActiveChainstate() const; 1126 CChain& ActiveChain() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChainstate().m_chain; } 1127 int ActiveHeight() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChain().Height(); } 1128 CBlockIndex* ActiveTip() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { return ActiveChain().Tip(); } 1129 1130 //! The state of a background sync (for net processing) 1131 bool BackgroundSyncInProgress() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { 1132 return IsUsable(m_snapshot_chainstate.get()) && IsUsable(m_ibd_chainstate.get()); 1133 } 1134 1135 //! The tip of the background sync chain 1136 const CBlockIndex* GetBackgroundSyncTip() const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()) { 1137 return BackgroundSyncInProgress() ? m_ibd_chainstate->m_chain.Tip() : nullptr; 1138 } 1139 1140 node::BlockMap& BlockIndex() EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 1141 { 1142 AssertLockHeld(::cs_main); 1143 return m_blockman.m_block_index; 1144 } 1145 1146 /** 1147 * Track versionbit status 1148 */ 1149 mutable VersionBitsCache m_versionbitscache; 1150 1151 //! @returns true if a snapshot-based chainstate is in use. Also implies 1152 //! that a background validation chainstate is also in use. 1153 bool IsSnapshotActive() const; 1154 1155 std::optional<uint256> SnapshotBlockhash() const; 1156 1157 //! Is there a snapshot in use and has it been fully validated? 1158 bool IsSnapshotValidated() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main) 1159 { 1160 return m_snapshot_chainstate && m_ibd_chainstate && m_ibd_chainstate->m_disabled; 1161 } 1162 1163 /** Check whether we are doing an initial block download (synchronizing from disk or network) */ 1164 bool IsInitialBlockDownload() const; 1165 1166 /** Guess verification progress (as a fraction between 0.0=genesis and 1.0=current tip). */ 1167 double GuessVerificationProgress(const CBlockIndex* pindex) const EXCLUSIVE_LOCKS_REQUIRED(GetMutex()); 1168 1169 /** 1170 * Import blocks from an external file 1171 * 1172 * During reindexing, this function is called for each block file (datadir/blocks/blk?????.dat). 1173 * It reads all blocks contained in the given file and attempts to process them (add them to the 1174 * block index). The blocks may be out of order within each file and across files. Often this 1175 * function reads a block but finds that its parent hasn't been read yet, so the block can't be 1176 * processed yet. The function will add an entry to the blocks_with_unknown_parent map (which is 1177 * passed as an argument), so that when the block's parent is later read and processed, this 1178 * function can re-read the child block from disk and process it. 1179 * 1180 * Because a block's parent may be in a later file, not just later in the same file, the 1181 * blocks_with_unknown_parent map must be passed in and out with each call. It's a multimap, 1182 * rather than just a map, because multiple blocks may have the same parent (when chain splits 1183 * or stale blocks exist). It maps from parent-hash to child-disk-position. 1184 * 1185 * This function can also be used to read blocks from user-specified block files using the 1186 * -loadblock= option. There's no unknown-parent tracking, so the last two arguments are omitted. 1187 * 1188 * 1189 * @param[in] file_in File containing blocks to read 1190 * @param[in] dbp (optional) Disk block position (only for reindex) 1191 * @param[in,out] blocks_with_unknown_parent (optional) Map of disk positions for blocks with 1192 * unknown parent, key is parent block hash 1193 * (only used for reindex) 1194 * */ 1195 void LoadExternalBlockFile( 1196 AutoFile& file_in, 1197 FlatFilePos* dbp = nullptr, 1198 std::multimap<uint256, FlatFilePos>* blocks_with_unknown_parent = nullptr); 1199 1200 /** 1201 * Process an incoming block. This only returns after the best known valid 1202 * block is made active. Note that it does not, however, guarantee that the 1203 * specific block passed to it has been checked for validity! 1204 * 1205 * If you want to *possibly* get feedback on whether block is valid, you must 1206 * install a CValidationInterface (see validationinterface.h) - this will have 1207 * its BlockChecked method called whenever *any* block completes validation. 1208 * 1209 * Note that we guarantee that either the proof-of-work is valid on block, or 1210 * (and possibly also) BlockChecked will have been called. 1211 * 1212 * May not be called in a validationinterface callback. 1213 * 1214 * @param[in] block The block we want to process. 1215 * @param[in] force_processing Process this block even if unrequested; used for non-network block sources. 1216 * @param[in] min_pow_checked True if proof-of-work anti-DoS checks have 1217 * been done by caller for headers chain 1218 * (note: only affects headers acceptance; if 1219 * block header is already present in block 1220 * index then this parameter has no effect) 1221 * @param[out] new_block A boolean which is set to indicate if the block was first received via this call 1222 * @returns If the block was processed, independently of block validity 1223 */ 1224 bool ProcessNewBlock(const std::shared_ptr<const CBlock>& block, bool force_processing, bool min_pow_checked, bool* new_block) LOCKS_EXCLUDED(cs_main); 1225 1226 /** 1227 * Process incoming block headers. 1228 * 1229 * May not be called in a 1230 * validationinterface callback. 1231 * 1232 * @param[in] headers The block headers themselves 1233 * @param[in] min_pow_checked True if proof-of-work anti-DoS checks have been done by caller for headers chain 1234 * @param[out] state This may be set to an Error state if any error occurred processing them 1235 * @param[out] ppindex If set, the pointer will be set to point to the last new block index object for the given headers 1236 * @returns false if AcceptBlockHeader fails on any of the headers, true otherwise (including if headers were already known) 1237 */ 1238 bool ProcessNewBlockHeaders(std::span<const CBlockHeader> headers, bool min_pow_checked, BlockValidationState& state, const CBlockIndex** ppindex = nullptr) LOCKS_EXCLUDED(cs_main); 1239 1240 /** 1241 * Sufficiently validate a block for disk storage (and store on disk). 1242 * 1243 * @param[in] pblock The block we want to process. 1244 * @param[in] fRequested Whether we requested this block from a 1245 * peer. 1246 * @param[in] dbp The location on disk, if we are importing 1247 * this block from prior storage. 1248 * @param[in] min_pow_checked True if proof-of-work anti-DoS checks have 1249 * been done by caller for headers chain 1250 * 1251 * @param[out] state The state of the block validation. 1252 * @param[out] ppindex Optional return parameter to get the 1253 * CBlockIndex pointer for this block. 1254 * @param[out] fNewBlock Optional return parameter to indicate if the 1255 * block is new to our storage. 1256 * 1257 * @returns False if the block or header is invalid, or if saving to disk fails (likely a fatal error); true otherwise. 1258 */ 1259 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); 1260 1261 void ReceivedBlockTransactions(const CBlock& block, CBlockIndex* pindexNew, const FlatFilePos& pos) EXCLUSIVE_LOCKS_REQUIRED(cs_main); 1262 1263 /** 1264 * Try to add a transaction to the memory pool. 1265 * 1266 * @param[in] tx The transaction to submit for mempool acceptance. 1267 * @param[in] test_accept When true, run validation checks but don't submit to mempool. 1268 */ 1269 [[nodiscard]] MempoolAcceptResult ProcessTransaction(const CTransactionRef& tx, bool test_accept=false) 1270 EXCLUSIVE_LOCKS_REQUIRED(cs_main); 1271 1272 //! Load the block tree and coins database from disk, initializing state if we're running with -reindex 1273 bool LoadBlockIndex() EXCLUSIVE_LOCKS_REQUIRED(cs_main); 1274 1275 //! Check to see if caches are out of balance and if so, call 1276 //! ResizeCoinsCaches() as needed. 1277 void MaybeRebalanceCaches() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1278 1279 /** 1280 * Update uncommitted block structures (currently: only the witness reserved 1281 * value). This is safe for submitted blocks as long as they honor 1282 * default_witness_commitment from the template. 1283 */ 1284 void UpdateUncommittedBlockStructures(CBlock& block, const CBlockIndex* pindexPrev) const; 1285 1286 /** Produce the necessary coinbase commitment for a block (modifies the hash, don't call for mined blocks). */ 1287 std::vector<unsigned char> GenerateCoinbaseCommitment(CBlock& block, const CBlockIndex* pindexPrev) const; 1288 1289 /** This is used by net_processing to report pre-synchronization progress of headers, as 1290 * headers are not yet fed to validation during that time, but validation is (for now) 1291 * responsible for logging and signalling through NotifyHeaderTip, so it needs this 1292 * information. */ 1293 void ReportHeadersPresync(const arith_uint256& work, int64_t height, int64_t timestamp); 1294 1295 //! When starting up, search the datadir for a chainstate based on a UTXO 1296 //! snapshot that is in the process of being validated. 1297 bool DetectSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1298 1299 void ResetChainstates() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1300 1301 //! Remove the snapshot-based chainstate and all on-disk artifacts. 1302 //! Used when reindex{-chainstate} is called during snapshot use. 1303 [[nodiscard]] bool DeleteSnapshotChainstate() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1304 1305 //! Switch the active chainstate to one based on a UTXO snapshot that was loaded 1306 //! previously. 1307 Chainstate& ActivateExistingSnapshot(uint256 base_blockhash) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1308 1309 //! If we have validated a snapshot chain during this runtime, copy its 1310 //! chainstate directory over to the main `chainstate` location, completing 1311 //! validation of the snapshot. 1312 //! 1313 //! If the cleanup succeeds, the caller will need to ensure chainstates are 1314 //! reinitialized, since ResetChainstates() will be called before leveldb 1315 //! directories are moved or deleted. 1316 //! 1317 //! @sa node/chainstate:LoadChainstate() 1318 bool ValidatedSnapshotCleanup() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1319 1320 //! @returns the chainstate that indexes should consult when ensuring that an 1321 //! index is synced with a chain where we can expect block index entries to have 1322 //! BLOCK_HAVE_DATA beneath the tip. 1323 //! 1324 //! In other words, give us the chainstate for which we can reasonably expect 1325 //! that all blocks beneath the tip have been indexed. In practice this means 1326 //! when using an assumed-valid chainstate based upon a snapshot, return only the 1327 //! fully validated chain. 1328 Chainstate& GetChainstateForIndexing() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1329 1330 //! Return the [start, end] (inclusive) of block heights we can prune. 1331 //! 1332 //! start > end is possible, meaning no blocks can be pruned. 1333 std::pair<int, int> GetPruneRange( 1334 const Chainstate& chainstate, int last_height_can_prune) EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1335 1336 //! Return the height of the base block of the snapshot in use, if one exists, else 1337 //! nullopt. 1338 std::optional<int> GetSnapshotBaseHeight() const EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1339 1340 //! If, due to invalidation / reconsideration of blocks, the previous 1341 //! best header is no longer valid / guaranteed to be the most-work 1342 //! header in our block-index not known to be invalid, recalculate it. 1343 void RecalculateBestHeader() EXCLUSIVE_LOCKS_REQUIRED(::cs_main); 1344 1345 CCheckQueue<CScriptCheck>& GetCheckQueue() { return m_script_check_queue; } 1346 1347 ~ChainstateManager(); 1348 }; 1349 1350 /** Deployment* info via ChainstateManager */ 1351 template<typename DEP> 1352 bool DeploymentActiveAfter(const CBlockIndex* pindexPrev, const ChainstateManager& chainman, DEP dep) 1353 { 1354 return DeploymentActiveAfter(pindexPrev, chainman.GetConsensus(), dep, chainman.m_versionbitscache); 1355 } 1356 1357 template<typename DEP> 1358 bool DeploymentActiveAt(const CBlockIndex& index, const ChainstateManager& chainman, DEP dep) 1359 { 1360 return DeploymentActiveAt(index, chainman.GetConsensus(), dep, chainman.m_versionbitscache); 1361 } 1362 1363 template<typename DEP> 1364 bool DeploymentEnabled(const ChainstateManager& chainman, DEP dep) 1365 { 1366 return DeploymentEnabled(chainman.GetConsensus(), dep); 1367 } 1368 1369 /** Identifies blocks that overwrote an existing coinbase output in the UTXO set (see BIP30) */ 1370 bool IsBIP30Repeat(const CBlockIndex& block_index); 1371 1372 /** Identifies blocks which coinbase output was subsequently overwritten in the UTXO set (see BIP30) */ 1373 bool IsBIP30Unspendable(const uint256& block_hash, int block_height); 1374 1375 // Returns the script flags which should be checked for a given block 1376 script_verify_flags GetBlockScriptFlags(const CBlockIndex& block_index, const ChainstateManager& chainman); 1377 1378 #endif // BITCOIN_VALIDATION_H