Bitcoin Core 29.99.0
P2P Digital Currency
chain.h
Go to the documentation of this file.
1// Copyright (c) 2018-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#ifndef BITCOIN_INTERFACES_CHAIN_H
6#define BITCOIN_INTERFACES_CHAIN_H
7
8#include <blockfilter.h>
9#include <common/settings.h>
11#include <util/result.h>
12
13#include <cstddef>
14#include <cstdint>
15#include <functional>
16#include <map>
17#include <memory>
18#include <optional>
19#include <string>
20#include <vector>
21
22class ArgsManager;
23class CBlock;
24class CBlockUndo;
25class CFeeRate;
26class CRPCCommand;
27class CScheduler;
28class Coin;
29class uint256;
30enum class MemPoolRemovalReason;
31enum class RBFTransactionState;
32enum class ChainstateRole;
33struct bilingual_str;
34struct CBlockLocator;
35struct FeeCalculation;
36namespace node {
37struct NodeContext;
38} // namespace node
39
40namespace interfaces {
41
42class Handler;
43class Wallet;
44
49{
50public:
51 FoundBlock& hash(uint256& hash) { m_hash = &hash; return *this; }
52 FoundBlock& height(int& height) { m_height = &height; return *this; }
53 FoundBlock& time(int64_t& time) { m_time = &time; return *this; }
54 FoundBlock& maxTime(int64_t& max_time) { m_max_time = &max_time; return *this; }
55 FoundBlock& mtpTime(int64_t& mtp_time) { m_mtp_time = &mtp_time; return *this; }
57 FoundBlock& inActiveChain(bool& in_active_chain) { m_in_active_chain = &in_active_chain; return *this; }
61 FoundBlock& nextBlock(const FoundBlock& next_block) { m_next_block = &next_block; return *this; }
64 FoundBlock& data(CBlock& data) { m_data = &data; return *this; }
65
66 uint256* m_hash = nullptr;
67 int* m_height = nullptr;
68 int64_t* m_time = nullptr;
69 int64_t* m_max_time = nullptr;
70 int64_t* m_mtp_time = nullptr;
71 bool* m_in_active_chain = nullptr;
73 const FoundBlock* m_next_block = nullptr;
74 CBlock* m_data = nullptr;
75 mutable bool found = false;
76};
77
79struct BlockInfo {
80 const uint256& hash;
81 const uint256* prev_hash = nullptr;
82 int height = -1;
83 int file_number = -1;
84 unsigned data_pos = 0;
85 const CBlock* data = nullptr;
86 const CBlockUndo* undo_data = nullptr;
87 // The maximum time in the chain up to and including this block.
88 // A timestamp that can only move forward.
89 unsigned int chain_time_max{0};
90
92};
93
98enum class SettingsAction {
99 WRITE,
101};
102
103using SettingsUpdate = std::function<std::optional<interfaces::SettingsAction>(common::SettingsValue&)>;
104
129class Chain
130{
131public:
132 virtual ~Chain() = default;
133
137 virtual std::optional<int> getHeight() = 0;
138
140 virtual uint256 getBlockHash(int height) = 0;
141
144 virtual bool haveBlockOnDisk(int height) = 0;
145
148
151 virtual CBlockLocator getActiveChainLocator(const uint256& block_hash) = 0;
152
156 virtual std::optional<int> findLocatorFork(const CBlockLocator& locator) = 0;
157
159 virtual bool hasBlockFilterIndex(BlockFilterType filter_type) = 0;
160
163 virtual std::optional<bool> blockFilterMatchesAny(BlockFilterType filter_type, const uint256& block_hash, const GCSFilter::ElementSet& filter_set) = 0;
164
167 virtual bool findBlock(const uint256& hash, const FoundBlock& block={}) = 0;
168
173 virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock& block={}) = 0;
174
177 virtual bool findAncestorByHeight(const uint256& block_hash, int ancestor_height, const FoundBlock& ancestor_out={}) = 0;
178
181 virtual bool findAncestorByHash(const uint256& block_hash,
182 const uint256& ancestor_hash,
183 const FoundBlock& ancestor_out={}) = 0;
184
187 virtual bool findCommonAncestor(const uint256& block_hash1,
188 const uint256& block_hash2,
189 const FoundBlock& ancestor_out={},
190 const FoundBlock& block1_out={},
191 const FoundBlock& block2_out={}) = 0;
192
196 virtual void findCoins(std::map<COutPoint, Coin>& coins) = 0;
197
200 virtual double guessVerificationProgress(const uint256& block_hash) = 0;
201
205 virtual bool hasBlocks(const uint256& block_hash, int min_height = 0, std::optional<int> max_height = {}) = 0;
206
209
211 virtual bool isInMempool(const uint256& txid) = 0;
212
214 virtual bool hasDescendantsInMempool(const uint256& txid) = 0;
215
219 virtual bool broadcastTransaction(const CTransactionRef& tx,
220 const CAmount& max_tx_fee,
221 bool relay,
222 std::string& err_string) = 0;
223
225 virtual void getTransactionAncestry(const uint256& txid, size_t& ancestors, size_t& descendants, size_t* ancestorsize = nullptr, CAmount* ancestorfees = nullptr) = 0;
226
228 // feerate, including bumping its ancestors. For example, if the target feerate is 10sat/vbyte
229 // and this outpoint refers to a mempool transaction at 3sat/vbyte, the bump fee includes the
230 // cost to bump the mempool transaction to 10sat/vbyte (i.e. 7 * mempooltx.vsize). If that
231 // transaction also has, say, an unconfirmed parent with a feerate of 1sat/vbyte, the bump fee
232 // includes the cost to bump the parent (i.e. 9 * parentmempooltx.vsize).
233 //
234 // If the outpoint comes from an unconfirmed transaction that is already above the target
235 // feerate or bumped by its descendant(s) already, it does not need to be bumped. Its bump fee
236 // is 0. Likewise, if any of the transaction's ancestors are already bumped by a transaction
237 // in our mempool, they are not included in the transaction's bump fee.
238 //
239 // Also supported is bump-fee calculation in the case of replacements. If an outpoint
240 // conflicts with another transaction in the mempool, it is assumed that the goal is to replace
241 // that transaction. As such, the calculation will exclude the to-be-replaced transaction, but
242 // will include the fee-bumping cost. If bump fees of descendants of the to-be-replaced
243 // transaction are requested, the value will be 0. Fee-related RBF rules are not included as
244 // they are logically distinct.
245 //
246 // Any outpoints that are otherwise unavailable from the mempool (e.g. UTXOs from confirmed
247 // transactions or transactions not yet broadcast by the wallet) are given a bump fee of 0.
248 //
249 // If multiple outpoints come from the same transaction (which would be very rare because
250 // it means that one transaction has multiple change outputs or paid the same wallet using multiple
251 // outputs in the same transaction) or have shared ancestry, the bump fees are calculated
252 // independently, i.e. as if only one of them is spent. This may result in double-fee-bumping. This
253 // caveat can be rectified per use of the sister-function CalculateCombinedBumpFee(…).
254 virtual std::map<COutPoint, CAmount> calculateIndividualBumpFees(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
255
257 // as in CalculateIndividualBumpFees(…).
258 // Unlike CalculateIndividualBumpFees(…), this does not return individual
259 // bump fees per outpoint, but a single bump fee for the shared ancestry.
260 // The combined bump fee may be used to correct overestimation due to
261 // shared ancestry by multiple UTXOs after coin selection.
262 virtual std::optional<CAmount> calculateCombinedBumpFee(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
263
267 virtual void getPackageLimits(unsigned int& limit_ancestor_count, unsigned int& limit_descendant_count) = 0;
268
271
273 virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation* calc = nullptr) = 0;
274
276 virtual unsigned int estimateMaxBlocks() = 0;
277
279 virtual CFeeRate mempoolMinFee() = 0;
280
282 virtual CFeeRate relayMinFee() = 0;
283
286
288 virtual CFeeRate relayDustFee() = 0;
289
291 virtual bool havePruned() = 0;
292
294 virtual std::optional<int> getPruneHeight() = 0;
295
297 virtual bool isReadyToBroadcast() = 0;
298
300 virtual bool isInitialBlockDownload() = 0;
301
303 virtual bool shutdownRequested() = 0;
304
306 virtual void initMessage(const std::string& message) = 0;
307
309 virtual void initWarning(const bilingual_str& message) = 0;
310
312 virtual void initError(const bilingual_str& message) = 0;
313
315 virtual void showProgress(const std::string& title, int progress, bool resume_possible) = 0;
316
319 {
320 public:
321 virtual ~Notifications() = default;
324 virtual void blockConnected(ChainstateRole role, const BlockInfo& block) {}
325 virtual void blockDisconnected(const BlockInfo& block) {}
326 virtual void updatedBlockTip() {}
327 virtual void chainStateFlushed(ChainstateRole role, const CBlockLocator& locator) {}
328 };
329
332 {
334 bool connect_undo_data = false;
336 bool disconnect_data = false;
339 };
340
342 virtual std::unique_ptr<Handler> handleNotifications(std::shared_ptr<Notifications> notifications) = 0;
343
346 virtual void waitForNotificationsIfTipChanged(const uint256& old_tip) = 0;
347
350 virtual std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) = 0;
351
353 virtual bool rpcEnableDeprecated(const std::string& method) = 0;
354
356 virtual void rpcRunLater(const std::string& name, std::function<void()> fn, int64_t seconds) = 0;
357
359 virtual common::SettingsValue getSetting(const std::string& arg) = 0;
360
362 virtual std::vector<common::SettingsValue> getSettingsList(const std::string& arg) = 0;
363
365 virtual common::SettingsValue getRwSetting(const std::string& name) = 0;
366
372 virtual bool updateRwSetting(const std::string& name, const SettingsUpdate& update_function) = 0;
373
378 virtual bool overwriteRwSetting(const std::string& name, common::SettingsValue value, SettingsAction action = SettingsAction::WRITE) = 0;
379
383 virtual bool deleteRwSettings(const std::string& name, SettingsAction action = SettingsAction::WRITE) = 0;
384
393 virtual void requestMempoolTransactions(Notifications& notifications) = 0;
394
396 virtual bool hasAssumedValidChain() = 0;
397
400 virtual node::NodeContext* context() { return nullptr; }
401};
402
406{
407public:
408 virtual ~ChainClient() = default;
409
411 virtual void registerRpcs() = 0;
412
414 virtual bool verify() = 0;
415
417 virtual bool load() = 0;
418
420 virtual void start(CScheduler& scheduler) = 0;
421
423 virtual void stop() = 0;
424
426 virtual void setMockTime(int64_t time) = 0;
427
429 virtual void schedulerMockForward(std::chrono::seconds delta_seconds) = 0;
430};
431
433std::unique_ptr<Chain> MakeChain(node::NodeContext& node);
434
435} // namespace interfaces
436
437#endif // BITCOIN_INTERFACES_CHAIN_H
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
#define LIFETIMEBOUND
Definition: attributes.h:16
const auto command
BlockFilterType
Definition: blockfilter.h:93
Definition: block.h:69
Undo information for a CBlock.
Definition: undo.h:63
Fee rate in satoshis per kilovirtualbyte: CAmount / kvB.
Definition: feerate.h:33
Simple class for background tasks that should be run periodically or once "after a while".
Definition: scheduler.h:40
The basic transaction that is broadcasted on the network and contained in blocks.
Definition: transaction.h:296
A UTXO entry.
Definition: coins.h:33
std::unordered_set< Element, ByteVectorHash > ElementSet
Definition: blockfilter.h:32
Chain notifications.
Definition: chain.h:319
virtual void blockConnected(ChainstateRole role, const BlockInfo &block)
Definition: chain.h:324
virtual void chainStateFlushed(ChainstateRole role, const CBlockLocator &locator)
Definition: chain.h:327
virtual void transactionRemovedFromMempool(const CTransactionRef &tx, MemPoolRemovalReason reason)
Definition: chain.h:323
virtual void blockDisconnected(const BlockInfo &block)
Definition: chain.h:325
virtual void updatedBlockTip()
Definition: chain.h:326
virtual void transactionAddedToMempool(const CTransactionRef &tx)
Definition: chain.h:322
virtual ~Notifications()=default
Interface to let node manage chain clients (wallets, or maybe tools for monitoring and analysis in th...
Definition: chain.h:406
virtual void schedulerMockForward(std::chrono::seconds delta_seconds)=0
Mock the scheduler to fast forward in time.
virtual void stop()=0
Shut down client.
virtual ~ChainClient()=default
virtual bool load()=0
Load saved state.
virtual void registerRpcs()=0
Register rpcs.
virtual void start(CScheduler &scheduler)=0
Start client execution and provide a scheduler.
virtual bool verify()=0
Check for errors before loading.
virtual void setMockTime(int64_t time)=0
Set mock time.
Interface giving clients (wallet processes, maybe other analysis tools in the future) ability to acce...
Definition: chain.h:130
virtual void rpcRunLater(const std::string &name, std::function< void()> fn, int64_t seconds)=0
Run function after given number of seconds. Cancel any previous calls with same name.
virtual std::unique_ptr< Handler > handleRpc(const CRPCCommand &command)=0
Register handler for RPC.
virtual CBlockLocator getTipLocator()=0
Get locator for the current chain tip.
virtual bool isInitialBlockDownload()=0
Check if in IBD.
virtual bool hasDescendantsInMempool(const uint256 &txid)=0
Check if transaction has descendants in mempool.
virtual std::optional< int > getHeight()=0
Get current chain height, not including genesis block (returns 0 if chain only contains genesis block...
virtual CBlockLocator getActiveChainLocator(const uint256 &block_hash)=0
Return a locator that refers to a block in the active chain.
virtual std::optional< bool > blockFilterMatchesAny(BlockFilterType filter_type, const uint256 &block_hash, const GCSFilter::ElementSet &filter_set)=0
Returns whether any of the elements match the block via a BIP 157 block filter or std::nullopt if the...
virtual bool overwriteRwSetting(const std::string &name, common::SettingsValue value, SettingsAction action=SettingsAction::WRITE)=0
Replace a setting in <datadir>/settings.json with a new value.
virtual bool rpcEnableDeprecated(const std::string &method)=0
Check if deprecated RPC is enabled.
virtual bool hasBlocks(const uint256 &block_hash, int min_height=0, std::optional< int > max_height={})=0
Return true if data is available for all blocks in the specified range of blocks.
virtual std::unique_ptr< Handler > handleNotifications(std::shared_ptr< Notifications > notifications)=0
Register handler for notifications.
virtual RBFTransactionState isRBFOptIn(const CTransaction &tx)=0
Check if transaction is RBF opt in.
virtual bool findCommonAncestor(const uint256 &block_hash1, const uint256 &block_hash2, const FoundBlock &ancestor_out={}, const FoundBlock &block1_out={}, const FoundBlock &block2_out={})=0
Find most recent common ancestor between two blocks and optionally return block information.
virtual uint256 getBlockHash(int height)=0
Get block hash. Height must be valid or this function will abort.
virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock &block={})=0
Find first block in the chain with timestamp >= the given time and height >= than the given height,...
virtual bool findAncestorByHash(const uint256 &block_hash, const uint256 &ancestor_hash, const FoundBlock &ancestor_out={})=0
Return whether block descends from a specified ancestor, and optionally return ancestor information.
virtual node::NodeContext * context()
Get internal node context.
Definition: chain.h:400
virtual bool deleteRwSettings(const std::string &name, SettingsAction action=SettingsAction::WRITE)=0
Delete a given setting in <datadir>/settings.json.
virtual void showProgress(const std::string &title, int progress, bool resume_possible)=0
Send progress indicator.
virtual bool havePruned()=0
Check if any block has been pruned.
virtual bool updateRwSetting(const std::string &name, const SettingsUpdate &update_function)=0
Updates a setting in <datadir>/settings.json.
virtual void findCoins(std::map< COutPoint, Coin > &coins)=0
Look up unspent output information.
virtual bool shutdownRequested()=0
Check if shutdown requested.
virtual bool hasBlockFilterIndex(BlockFilterType filter_type)=0
Returns whether a block filter index is available.
virtual common::SettingsValue getRwSetting(const std::string &name)=0
Return <datadir>/settings.json setting value.
virtual void getTransactionAncestry(const uint256 &txid, size_t &ancestors, size_t &descendants, size_t *ancestorsize=nullptr, CAmount *ancestorfees=nullptr)=0
Calculate mempool ancestor and descendant counts for the given transaction.
virtual common::SettingsValue getSetting(const std::string &arg)=0
Get settings value.
virtual bool isReadyToBroadcast()=0
Check if the node is ready to broadcast transactions.
virtual bool hasAssumedValidChain()=0
Return true if an assumed-valid chain is in use.
virtual std::optional< CAmount > calculateCombinedBumpFee(const std::vector< COutPoint > &outpoints, const CFeeRate &target_feerate)=0
Calculate the combined bump fee for an input set per the same strategy.
virtual bool findAncestorByHeight(const uint256 &block_hash, int ancestor_height, const FoundBlock &ancestor_out={})=0
Find ancestor of block at specified height and optionally return ancestor information.
virtual bool findBlock(const uint256 &hash, const FoundBlock &block={})=0
Return whether node has the block and optionally return block metadata or contents.
virtual double guessVerificationProgress(const uint256 &block_hash)=0
Estimate fraction of total transactions verified if blocks up to the specified block hash are verifie...
virtual std::map< COutPoint, CAmount > calculateIndividualBumpFees(const std::vector< COutPoint > &outpoints, const CFeeRate &target_feerate)=0
For each outpoint, calculate the fee-bumping cost to spend this outpoint at the specified.
virtual void waitForNotificationsIfTipChanged(const uint256 &old_tip)=0
Wait for pending notifications to be processed unless block hash points to the current chain tip.
virtual CFeeRate mempoolMinFee()=0
Mempool minimum fee.
virtual void initMessage(const std::string &message)=0
Send init message.
virtual bool isInMempool(const uint256 &txid)=0
Check if transaction is in mempool.
virtual unsigned int estimateMaxBlocks()=0
Fee estimator max target.
virtual bool broadcastTransaction(const CTransactionRef &tx, const CAmount &max_tx_fee, bool relay, std::string &err_string)=0
Transaction is added to memory pool, if the transaction fee is below the amount specified by max_tx_f...
virtual void getPackageLimits(unsigned int &limit_ancestor_count, unsigned int &limit_descendant_count)=0
Get the node's package limits.
virtual std::optional< int > findLocatorFork(const CBlockLocator &locator)=0
Return height of the highest block on chain in common with the locator, which will either be the orig...
virtual bool haveBlockOnDisk(int height)=0
Check that the block is available on disk (i.e.
virtual ~Chain()=default
virtual util::Result< void > checkChainLimits(const CTransactionRef &tx)=0
Check if transaction will pass the mempool's chain limits.
virtual std::vector< common::SettingsValue > getSettingsList(const std::string &arg)=0
Get list of settings values.
virtual CFeeRate relayDustFee()=0
Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend.
virtual void requestMempoolTransactions(Notifications &notifications)=0
Synchronously send transactionAddedToMempool notifications about all current mempool transactions to ...
virtual void initError(const bilingual_str &message)=0
Send init error.
virtual void initWarning(const bilingual_str &message)=0
Send init warning.
virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation *calc=nullptr)=0
Estimate smart fee.
virtual CFeeRate relayMinFee()=0
Relay current minimum fee (from -minrelaytxfee and -incrementalrelayfee settings).
virtual CFeeRate relayIncrementalFee()=0
Relay incremental fee setting (-incrementalrelayfee), reflecting cost of relay.
virtual std::optional< int > getPruneHeight()=0
Get the current prune height.
Helper for findBlock to selectively return pieces of block data.
Definition: chain.h:49
FoundBlock & time(int64_t &time)
Definition: chain.h:53
FoundBlock & hash(uint256 &hash)
Definition: chain.h:51
CBlock * m_data
Definition: chain.h:74
const FoundBlock * m_next_block
Definition: chain.h:73
FoundBlock & mtpTime(int64_t &mtp_time)
Definition: chain.h:55
int64_t * m_max_time
Definition: chain.h:69
FoundBlock & locator(CBlockLocator &locator)
Return locator if block is in the active chain.
Definition: chain.h:59
int64_t * m_time
Definition: chain.h:68
bool * m_in_active_chain
Definition: chain.h:71
FoundBlock & nextBlock(const FoundBlock &next_block)
Return next block in the active chain if current block is in the active chain.
Definition: chain.h:61
FoundBlock & maxTime(int64_t &max_time)
Definition: chain.h:54
uint256 * m_hash
Definition: chain.h:66
int64_t * m_mtp_time
Definition: chain.h:70
FoundBlock & height(int &height)
Definition: chain.h:52
FoundBlock & inActiveChain(bool &in_active_chain)
Return whether block is in the active (most-work) chain.
Definition: chain.h:57
FoundBlock & data(CBlock &data)
Read block data from disk.
Definition: chain.h:64
CBlockLocator * m_locator
Definition: chain.h:72
256-bit opaque blob.
Definition: uint256.h:196
ChainstateRole
This enum describes the various roles a specific Chainstate instance can take.
Definition: chain.h:25
MemPoolRemovalReason
Reason why a transaction was removed from the mempool, this is passed to the notification signal.
SettingsAction
The action to be taken after updating a settings value.
Definition: chain.h:98
std::unique_ptr< Chain > MakeChain(node::NodeContext &node)
Return implementation of Chain interface.
Definition: interfaces.cpp:997
std::function< std::optional< interfaces::SettingsAction >(common::SettingsValue &)> SettingsUpdate
Definition: chain.h:103
Definition: messages.h:20
RBFTransactionState
The rbf state of unconfirmed transactions.
Definition: rbf.h:29
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:423
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
Bilingual messages:
Definition: translation.h:24
Block data sent with blockConnected, blockDisconnected notifications.
Definition: chain.h:79
unsigned data_pos
Definition: chain.h:84
const uint256 * prev_hash
Definition: chain.h:81
const CBlock * data
Definition: chain.h:85
const uint256 & hash
Definition: chain.h:80
BlockInfo(const uint256 &hash LIFETIMEBOUND)
Definition: chain.h:91
const CBlockUndo * undo_data
Definition: chain.h:86
unsigned int chain_time_max
Definition: chain.h:89
Options specifying which chain notifications are required.
Definition: chain.h:332
bool connect_undo_data
Include undo data with block connected notifications.
Definition: chain.h:334
bool disconnect_undo_data
Include undo data with block disconnected notifications.
Definition: chain.h:338
bool disconnect_data
Include block data with block disconnected notifications.
Definition: chain.h:336
NodeContext struct containing references to chain state and connection state.
Definition: context.h:56