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