Bitcoin Core 29.99.0
P2P Digital Currency
base.cpp
Go to the documentation of this file.
1// Copyright (c) 2017-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#include <chainparams.h>
6#include <common/args.h>
7#include <index/base.h>
8#include <interfaces/chain.h>
9#include <kernel/chain.h>
10#include <logging.h>
11#include <node/abort.h>
12#include <node/blockstorage.h>
13#include <node/context.h>
14#include <node/database_args.h>
15#include <node/interface_ui.h>
16#include <tinyformat.h>
17#include <util/string.h>
18#include <util/thread.h>
19#include <util/translation.h>
20#include <validation.h>
21
22#include <chrono>
23#include <memory>
24#include <optional>
25#include <stdexcept>
26#include <string>
27#include <thread>
28#include <utility>
29
30constexpr uint8_t DB_BEST_BLOCK{'B'};
31
32constexpr auto SYNC_LOG_INTERVAL{30s};
34
35template <typename... Args>
36void BaseIndex::FatalErrorf(util::ConstevalFormatString<sizeof...(Args)> fmt, const Args&... args)
37{
38 auto message = tfm::format(fmt, args...);
39 node::AbortNode(m_chain->context()->shutdown_request, m_chain->context()->exit_status, Untranslated(message), m_chain->context()->warnings.get());
40}
41
43{
44 CBlockLocator locator;
45 bool found = chain.findBlock(block_hash, interfaces::FoundBlock().locator(locator));
46 assert(found);
47 assert(!locator.IsNull());
48 return locator;
49}
50
51BaseIndex::DB::DB(const fs::path& path, size_t n_cache_size, bool f_memory, bool f_wipe, bool f_obfuscate) :
53 .path = path,
54 .cache_bytes = n_cache_size,
55 .memory_only = f_memory,
56 .wipe_data = f_wipe,
57 .obfuscate = f_obfuscate,
58 .options = [] { DBOptions options; node::ReadDatabaseArgs(gArgs, options); return options; }()}}
59{}
60
62{
63 bool success = Read(DB_BEST_BLOCK, locator);
64 if (!success) {
65 locator.SetNull();
66 }
67 return success;
68}
69
71{
72 batch.Write(DB_BEST_BLOCK, locator);
73}
74
75BaseIndex::BaseIndex(std::unique_ptr<interfaces::Chain> chain, std::string name)
76 : m_chain{std::move(chain)}, m_name{std::move(name)} {}
77
79{
80 Interrupt();
81 Stop();
82}
83
85{
87
88 // May need reset if index is being restarted.
90
91 // m_chainstate member gives indexing code access to node internals. It is
92 // removed in followup https://github.com/bitcoin/bitcoin/pull/24230
94 return &m_chain->context()->chainman->GetChainstateForIndexing());
95 // Register to validation interface before setting the 'm_synced' flag, so that
96 // callbacks are not missed once m_synced is true.
97 m_chain->context()->validation_signals->RegisterValidationInterface(this);
98
99 CBlockLocator locator;
100 if (!GetDB().ReadBestBlock(locator)) {
101 locator.SetNull();
102 }
103
104 LOCK(cs_main);
105 CChain& index_chain = m_chainstate->m_chain;
106
107 if (locator.IsNull()) {
108 SetBestBlockIndex(nullptr);
109 } else {
110 // Setting the best block to the locator's top block. If it is not part of the
111 // best chain, we will rewind to the fork point during index sync
112 const CBlockIndex* locator_index{m_chainstate->m_blockman.LookupBlockIndex(locator.vHave.at(0))};
113 if (!locator_index) {
114 return InitError(Untranslated(strprintf("%s: best block of the index not found. Please rebuild the index.", GetName())));
115 }
116 SetBestBlockIndex(locator_index);
117 }
118
119 // Child init
120 const CBlockIndex* start_block = m_best_block_index.load();
121 if (!CustomInit(start_block ? std::make_optional(interfaces::BlockRef{start_block->GetBlockHash(), start_block->nHeight}) : std::nullopt)) {
122 return false;
123 }
124
125 // Note: this will latch to true immediately if the user starts up with an empty
126 // datadir and an index enabled. If this is the case, indexation will happen solely
127 // via `BlockConnected` signals until, possibly, the next restart.
128 m_synced = start_block == index_chain.Tip();
129 m_init = true;
130 return true;
131}
132
134{
136
137 if (!pindex_prev) {
138 return chain.Genesis();
139 }
140
141 const CBlockIndex* pindex = chain.Next(pindex_prev);
142 if (pindex) {
143 return pindex;
144 }
145
146 return chain.Next(chain.FindFork(pindex_prev));
147}
148
150{
151 const CBlockIndex* pindex = m_best_block_index.load();
152 if (!m_synced) {
153 std::chrono::steady_clock::time_point last_log_time{0s};
154 std::chrono::steady_clock::time_point last_locator_write_time{0s};
155 while (true) {
156 if (m_interrupt) {
157 LogPrintf("%s: m_interrupt set; exiting ThreadSync\n", GetName());
158
159 SetBestBlockIndex(pindex);
160 // No need to handle errors in Commit. If it fails, the error will be already be
161 // logged. The best way to recover is to continue, as index cannot be corrupted by
162 // a missed commit to disk for an advanced index state.
163 Commit();
164 return;
165 }
166
167 const CBlockIndex* pindex_next = WITH_LOCK(cs_main, return NextSyncBlock(pindex, m_chainstate->m_chain));
168 // If pindex_next is null, it means pindex is the chain tip, so
169 // commit data indexed so far.
170 if (!pindex_next) {
171 SetBestBlockIndex(pindex);
172 // No need to handle errors in Commit. See rationale above.
173 Commit();
174
175 // If pindex is still the chain tip after committing, exit the
176 // sync loop. It is important for cs_main to be locked while
177 // setting m_synced = true, otherwise a new block could be
178 // attached while m_synced is still false, and it would not be
179 // indexed.
181 pindex_next = NextSyncBlock(pindex, m_chainstate->m_chain);
182 if (!pindex_next) {
183 m_synced = true;
184 break;
185 }
186 }
187 if (pindex_next->pprev != pindex && !Rewind(pindex, pindex_next->pprev)) {
188 FatalErrorf("%s: Failed to rewind index %s to a previous chain tip", __func__, GetName());
189 return;
190 }
191 pindex = pindex_next;
192
193
194 CBlock block;
195 interfaces::BlockInfo block_info = kernel::MakeBlockInfo(pindex);
196 if (!m_chainstate->m_blockman.ReadBlock(block, *pindex)) {
197 FatalErrorf("%s: Failed to read block %s from disk",
198 __func__, pindex->GetBlockHash().ToString());
199 return;
200 } else {
201 block_info.data = &block;
202 }
203 if (!CustomAppend(block_info)) {
204 FatalErrorf("%s: Failed to write block %s to index database",
205 __func__, pindex->GetBlockHash().ToString());
206 return;
207 }
208
209 auto current_time{std::chrono::steady_clock::now()};
210 if (last_log_time + SYNC_LOG_INTERVAL < current_time) {
211 LogPrintf("Syncing %s with block chain from height %d\n",
212 GetName(), pindex->nHeight);
213 last_log_time = current_time;
214 }
215
216 if (last_locator_write_time + SYNC_LOCATOR_WRITE_INTERVAL < current_time) {
217 SetBestBlockIndex(pindex);
218 last_locator_write_time = current_time;
219 // No need to handle errors in Commit. See rationale above.
220 Commit();
221 }
222 }
223 }
224
225 if (pindex) {
226 LogPrintf("%s is enabled at height %d\n", GetName(), pindex->nHeight);
227 } else {
228 LogPrintf("%s is enabled\n", GetName());
229 }
230}
231
233{
234 // Don't commit anything if we haven't indexed any block yet
235 // (this could happen if init is interrupted).
236 bool ok = m_best_block_index != nullptr;
237 if (ok) {
238 CDBBatch batch(GetDB());
239 ok = CustomCommit(batch);
240 if (ok) {
241 GetDB().WriteBestBlock(batch, GetLocator(*m_chain, m_best_block_index.load()->GetBlockHash()));
242 ok = GetDB().WriteBatch(batch);
243 }
244 }
245 if (!ok) {
246 LogError("%s: Failed to commit latest %s state\n", __func__, GetName());
247 return false;
248 }
249 return true;
250}
251
252bool BaseIndex::Rewind(const CBlockIndex* current_tip, const CBlockIndex* new_tip)
253{
254 assert(current_tip == m_best_block_index);
255 assert(current_tip->GetAncestor(new_tip->nHeight) == new_tip);
256
257 if (!CustomRewind({current_tip->GetBlockHash(), current_tip->nHeight}, {new_tip->GetBlockHash(), new_tip->nHeight})) {
258 return false;
259 }
260
261 // In the case of a reorg, ensure persisted block locator is not stale.
262 // Pruning has a minimum of 288 blocks-to-keep and getting the index
263 // out of sync may be possible but a users fault.
264 // In case we reorg beyond the pruned depth, ReadBlock would
265 // throw and lead to a graceful shutdown
266 SetBestBlockIndex(new_tip);
267 if (!Commit()) {
268 // If commit fails, revert the best block index to avoid corruption.
269 SetBestBlockIndex(current_tip);
270 return false;
271 }
272
273 return true;
274}
275
276void BaseIndex::BlockConnected(ChainstateRole role, const std::shared_ptr<const CBlock>& block, const CBlockIndex* pindex)
277{
278 // Ignore events from the assumed-valid chain; we will process its blocks
279 // (sequentially) after it is fully verified by the background chainstate. This
280 // is to avoid any out-of-order indexing.
281 //
282 // TODO at some point we could parameterize whether a particular index can be
283 // built out of order, but for now just do the conservative simple thing.
284 if (role == ChainstateRole::ASSUMEDVALID) {
285 return;
286 }
287
288 // Ignore BlockConnected signals until we have fully indexed the chain.
289 if (!m_synced) {
290 return;
291 }
292
293 const CBlockIndex* best_block_index = m_best_block_index.load();
294 if (!best_block_index) {
295 if (pindex->nHeight != 0) {
296 FatalErrorf("%s: First block connected is not the genesis block (height=%d)",
297 __func__, pindex->nHeight);
298 return;
299 }
300 } else {
301 // Ensure block connects to an ancestor of the current best block. This should be the case
302 // most of the time, but may not be immediately after the sync thread catches up and sets
303 // m_synced. Consider the case where there is a reorg and the blocks on the stale branch are
304 // in the ValidationInterface queue backlog even after the sync thread has caught up to the
305 // new chain tip. In this unlikely event, log a warning and let the queue clear.
306 if (best_block_index->GetAncestor(pindex->nHeight - 1) != pindex->pprev) {
307 LogPrintf("%s: WARNING: Block %s does not connect to an ancestor of "
308 "known best chain (tip=%s); not updating index\n",
309 __func__, pindex->GetBlockHash().ToString(),
310 best_block_index->GetBlockHash().ToString());
311 return;
312 }
313 if (best_block_index != pindex->pprev && !Rewind(best_block_index, pindex->pprev)) {
314 FatalErrorf("%s: Failed to rewind index %s to a previous chain tip",
315 __func__, GetName());
316 return;
317 }
318 }
319 interfaces::BlockInfo block_info = kernel::MakeBlockInfo(pindex, block.get());
320 if (CustomAppend(block_info)) {
321 // Setting the best block index is intentionally the last step of this
322 // function, so BlockUntilSyncedToCurrentChain callers waiting for the
323 // best block index to be updated can rely on the block being fully
324 // processed, and the index object being safe to delete.
325 SetBestBlockIndex(pindex);
326 } else {
327 FatalErrorf("%s: Failed to write block %s to index",
328 __func__, pindex->GetBlockHash().ToString());
329 return;
330 }
331}
332
334{
335 // Ignore events from the assumed-valid chain; we will process its blocks
336 // (sequentially) after it is fully verified by the background chainstate.
337 if (role == ChainstateRole::ASSUMEDVALID) {
338 return;
339 }
340
341 if (!m_synced) {
342 return;
343 }
344
345 const uint256& locator_tip_hash = locator.vHave.front();
346 const CBlockIndex* locator_tip_index;
347 {
348 LOCK(cs_main);
349 locator_tip_index = m_chainstate->m_blockman.LookupBlockIndex(locator_tip_hash);
350 }
351
352 if (!locator_tip_index) {
353 FatalErrorf("%s: First block (hash=%s) in locator was not found",
354 __func__, locator_tip_hash.ToString());
355 return;
356 }
357
358 // This checks that ChainStateFlushed callbacks are received after BlockConnected. The check may fail
359 // immediately after the sync thread catches up and sets m_synced. Consider the case where
360 // there is a reorg and the blocks on the stale branch are in the ValidationInterface queue
361 // backlog even after the sync thread has caught up to the new chain tip. In this unlikely
362 // event, log a warning and let the queue clear.
363 const CBlockIndex* best_block_index = m_best_block_index.load();
364 if (best_block_index->GetAncestor(locator_tip_index->nHeight) != locator_tip_index) {
365 LogPrintf("%s: WARNING: Locator contains block (hash=%s) not on known best "
366 "chain (tip=%s); not writing index locator\n",
367 __func__, locator_tip_hash.ToString(),
368 best_block_index->GetBlockHash().ToString());
369 return;
370 }
371
372 // No need to handle errors in Commit. If it fails, the error will be already be logged. The
373 // best way to recover is to continue, as index cannot be corrupted by a missed commit to disk
374 // for an advanced index state.
375 Commit();
376}
377
378bool BaseIndex::BlockUntilSyncedToCurrentChain() const
379{
381
382 if (!m_synced) {
383 return false;
384 }
385
386 {
387 // Skip the queue-draining stuff if we know we're caught up with
388 // m_chain.Tip().
389 LOCK(cs_main);
390 const CBlockIndex* chain_tip = m_chainstate->m_chain.Tip();
391 const CBlockIndex* best_block_index = m_best_block_index.load();
392 if (best_block_index->GetAncestor(chain_tip->nHeight) == chain_tip) {
393 return true;
394 }
395 }
396
397 LogPrintf("%s: %s is catching up on block notifications\n", __func__, GetName());
398 m_chain->context()->validation_signals->SyncWithValidationInterfaceQueue();
399 return true;
400}
401
403{
404 m_interrupt();
405}
406
408{
409 if (!m_init) throw std::logic_error("Error: Cannot start a non-initialized index");
410
411 m_thread_sync = std::thread(&util::TraceThread, GetName(), [this] { Sync(); });
412 return true;
413}
414
416{
417 if (m_chain->context()->validation_signals) {
418 m_chain->context()->validation_signals->UnregisterValidationInterface(this);
419 }
420
421 if (m_thread_sync.joinable()) {
422 m_thread_sync.join();
423 }
424}
425
427{
428 IndexSummary summary{};
429 summary.name = GetName();
430 summary.synced = m_synced;
431 if (const auto& pindex = m_best_block_index.load()) {
432 summary.best_block_height = pindex->nHeight;
433 summary.best_block_hash = pindex->GetBlockHash();
434 } else {
435 summary.best_block_height = 0;
436 summary.best_block_hash = m_chain->getBlockHash(0);
437 }
438 return summary;
439}
440
442{
444
445 if (AllowPrune() && block) {
446 node::PruneLockInfo prune_lock;
447 prune_lock.height_first = block->nHeight;
448 WITH_LOCK(::cs_main, m_chainstate->m_blockman.UpdatePruneLock(GetName(), prune_lock));
449 }
450
451 // Intentionally set m_best_block_index as the last step in this function,
452 // after updating prune locks above, and after making any other references
453 // to *this, so the BlockUntilSyncedToCurrentChain function (which checks
454 // m_best_block_index as an optimization) can be used to wait for the last
455 // BlockConnected notification and safely assume that prune locks are
456 // updated and that the index object is safe to delete.
457 m_best_block_index = block;
458}
ArgsManager gArgs
Definition: args.cpp:42
static const CBlockIndex * NextSyncBlock(const CBlockIndex *pindex_prev, CChain &chain) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
Definition: base.cpp:133
constexpr uint8_t DB_BEST_BLOCK
Definition: base.cpp:30
constexpr auto SYNC_LOCATOR_WRITE_INTERVAL
Definition: base.cpp:33
constexpr auto SYNC_LOG_INTERVAL
Definition: base.cpp:32
CBlockLocator GetLocator(interfaces::Chain &chain, const uint256 &block_hash)
Definition: base.cpp:42
ArgsManager & args
Definition: bitcoind.cpp:277
void WriteBestBlock(CDBBatch &batch, const CBlockLocator &locator)
Write block locator of the chain that the index is in sync with.
Definition: base.cpp:70
DB(const fs::path &path, size_t n_cache_size, bool f_memory=false, bool f_wipe=false, bool f_obfuscate=false)
Definition: base.cpp:51
bool ReadBestBlock(CBlockLocator &locator) const
Read block locator of the chain that the index is in sync with.
Definition: base.cpp:61
void Stop()
Stops the instance from staying in sync with blockchain updates.
Definition: base.cpp:415
virtual bool CustomInit(const std::optional< interfaces::BlockRef > &block)
Initialize internal state from the database and block index.
Definition: base.h:111
void SetBestBlockIndex(const CBlockIndex *block)
Update the internal best block index as well as the prune lock.
Definition: base.cpp:441
bool Init()
Initializes the sync state and registers the instance to the validation interface so that it stays in...
Definition: base.cpp:84
virtual ~BaseIndex()
Destructor interrupts sync thread if running and blocks until it exits.
Definition: base.cpp:78
virtual bool CustomCommit(CDBBatch &batch)
Virtual method called internally by Commit that can be overridden to atomically commit more index sta...
Definition: base.h:118
const std::string & GetName() const LIFETIMEBOUND
Get the name of the index for display in logs.
Definition: base.h:135
bool BlockUntilSyncedToCurrentChain() const LOCKS_EXCLUDED(void Interrupt()
Blocks the current thread until the index is caught up to the current state of the block chain.
Definition: base.cpp:402
virtual bool AllowPrune() const =0
void BlockConnected(ChainstateRole role, const std::shared_ptr< const CBlock > &block, const CBlockIndex *pindex) override
Notifies listeners of a block being connected.
Definition: base.cpp:276
std::atomic< bool > m_synced
Whether the index is in sync with the main chain.
Definition: base.h:75
CThreadInterrupt m_interrupt
Definition: base.h:81
BaseIndex(std::unique_ptr< interfaces::Chain > chain, std::string name)
Definition: base.cpp:75
IndexSummary GetSummary() const
Get a summary of the index and its state.
Definition: base.cpp:426
const std::string m_name
Definition: base.h:104
virtual DB & GetDB() const =0
void Sync()
Sync the index with the block index starting from the current best block.
Definition: base.cpp:149
std::thread m_thread_sync
Definition: base.h:80
bool Commit()
Write the current index state (eg.
Definition: base.cpp:232
virtual bool CustomRewind(const interfaces::BlockRef &current_tip, const interfaces::BlockRef &new_tip)
Rewind index to an earlier chain tip during a chain reorg.
Definition: base.h:122
void FatalErrorf(util::ConstevalFormatString< sizeof...(Args)> fmt, const Args &... args)
Definition: base.cpp:36
Chainstate * m_chainstate
Definition: base.h:103
bool Rewind(const CBlockIndex *current_tip, const CBlockIndex *new_tip)
Loop over disconnected blocks and call CustomRewind.
Definition: base.cpp:252
bool StartBackgroundSync()
Starts the initial sync process on a background thread.
Definition: base.cpp:407
void ChainStateFlushed(ChainstateRole role, const CBlockLocator &locator) override
Notifies listeners of the new active block chain on-disk.
Definition: base.cpp:333
std::unique_ptr< interfaces::Chain > m_chain
Definition: base.h:102
std::atomic< bool > m_init
Whether the index has been initialized or not.
Definition: base.h:67
std::atomic< const CBlockIndex * > m_best_block_index
The last block in the chain that the index is in sync with.
Definition: base.h:78
virtual bool CustomAppend(const interfaces::BlockInfo &block)
Write update index entries for a newly connected block.
Definition: base.h:114
Definition: block.h:69
The block chain is a tree shaped structure starting with the genesis block at the root,...
Definition: chain.h:141
CBlockIndex * pprev
pointer to the index of the predecessor of this block
Definition: chain.h:147
uint256 GetBlockHash() const
Definition: chain.h:243
CBlockIndex * GetAncestor(int height)
Efficiently find an ancestor of this block.
Definition: chain.cpp:120
int nHeight
height of the entry in the chain. The genesis block has height 0
Definition: chain.h:153
An in-memory indexed chain of blocks.
Definition: chain.h:417
CBlockIndex * Tip() const
Returns the index entry for the tip of this chain, or nullptr if none.
Definition: chain.h:433
Batch of changes queued to be written to a CDBWrapper.
Definition: dbwrapper.h:74
void Write(const K &key, const V &value)
Definition: dbwrapper.h:98
bool WriteBatch(CDBBatch &batch, bool fSync=false)
Definition: dbwrapper.cpp:285
CChain m_chain
The current chain of blockheaders we consult and build on.
Definition: validation.h:587
node::BlockManager & m_blockman
Reference to a BlockManager instance which itself is shared across all Chainstate instances.
Definition: validation.h:542
std::string ToString() const
Definition: uint256.cpp:21
Interface giving clients (wallet processes, maybe other analysis tools in the future) ability to acce...
Definition: chain.h:130
virtual bool findBlock(const uint256 &hash, const FoundBlock &block={})=0
Return whether node has the block and optionally return block metadata or contents.
Helper for findBlock to selectively return pieces of block data.
Definition: chain.h:49
bool ReadBlock(CBlock &block, const FlatFilePos &pos, const std::optional< uint256 > &expected_hash={}) const
Functions for disk access for blocks.
CBlockIndex * LookupBlockIndex(const uint256 &hash) EXCLUSIVE_LOCKS_REQUIRED(cs_main)
bool IsPruneMode() const
Whether running in -prune mode.
Definition: blockstorage.h:349
256-bit opaque blob.
Definition: uint256.h:196
RecursiveMutex cs_main
Mutex to guard access to validation specific variables, such as reading or changing the chainstate.
Definition: cs_main.cpp:8
bool InitError(const bilingual_str &str)
Show error message.
ChainstateRole
This enum describes the various roles a specific Chainstate instance can take.
Definition: chain.h:25
#define LogError(...)
Definition: logging.h:263
#define LogPrintf(...)
Definition: logging.h:266
interfaces::BlockInfo MakeBlockInfo(const CBlockIndex *index, const CBlock *data)
Return data from block index.
Definition: chain.cpp:14
void AbortNode(const std::function< bool()> &shutdown_request, std::atomic< int > &exit_status, const bilingual_str &message, node::Warnings *warnings)
Definition: abort.cpp:18
void ReadDatabaseArgs(const ArgsManager &args, DBOptions &options)
void format(std::ostream &out, FormatStringCheck< sizeof...(Args)> fmt, const Args &... args)
Format list of arguments to the stream according to given format string.
Definition: tinyformat.h:1079
void TraceThread(std::string_view thread_name, std::function< void()> thread_func)
A wrapper for do-something-once thread functions.
Definition: thread.cpp:16
const char * name
Definition: rest.cpp:49
Describes a place in the block chain to another node such that if the other node doesn't have the sam...
Definition: block.h:124
std::vector< uint256 > vHave
Definition: block.h:134
bool IsNull() const
Definition: block.h:152
void SetNull()
Definition: block.h:147
User-controlled performance and debug options.
Definition: dbwrapper.h:28
Application-specific storage settings.
Definition: dbwrapper.h:34
std::string name
Definition: base.h:26
Block data sent with blockConnected, blockDisconnected notifications.
Definition: chain.h:79
const CBlock * data
Definition: chain.h:85
Hash/height pair to help track and identify blocks.
Definition: types.h:13
A wrapper for a compile-time partially validated format string.
Definition: string.h:92
#define AssertLockNotHeld(cs)
Definition: sync.h:147
#define LOCK(cs)
Definition: sync.h:257
#define WITH_LOCK(cs, code)
Run code while locking a mutex.
Definition: sync.h:302
#define EXCLUSIVE_LOCKS_REQUIRED(...)
Definition: threadsafety.h:49
#define strprintf
Format arguments and return the string or write to given std::ostream (see tinyformat::format doc for...
Definition: tinyformat.h:1172
bilingual_str Untranslated(std::string original)
Mark a bilingual_str as untranslated.
Definition: translation.h:82
AssertLockHeld(pool.cs)
assert(!tx.IsCoinBase())