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