Bitcoin Core  23.99.0
P2P Digital Currency
chain.h
Go to the documentation of this file.
1 // Copyright (c) 2018-2021 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 <primitives/transaction.h> // For CTransactionRef
9 #include <util/settings.h> // For util::SettingsValue
10 
11 #include <functional>
12 #include <memory>
13 #include <optional>
14 #include <stddef.h>
15 #include <stdint.h>
16 #include <string>
17 #include <vector>
18 
19 class ArgsManager;
20 class CBlock;
21 class CBlockUndo;
22 class CFeeRate;
23 class CRPCCommand;
24 class CScheduler;
25 class Coin;
26 class uint256;
27 enum class MemPoolRemovalReason;
28 enum class RBFTransactionState;
29 struct bilingual_str;
30 struct CBlockLocator;
31 struct FeeCalculation;
32 namespace node {
33 struct NodeContext;
34 } // namespace node
35 
36 namespace interfaces {
37 
38 class Handler;
39 class Wallet;
40 
42 struct BlockKey {
44  int height = -1;
45 };
46 
51 {
52 public:
53  FoundBlock& hash(uint256& hash) { m_hash = &hash; return *this; }
54  FoundBlock& height(int& height) { m_height = &height; return *this; }
55  FoundBlock& time(int64_t& time) { m_time = &time; return *this; }
56  FoundBlock& maxTime(int64_t& max_time) { m_max_time = &max_time; return *this; }
57  FoundBlock& mtpTime(int64_t& mtp_time) { m_mtp_time = &mtp_time; return *this; }
59  FoundBlock& inActiveChain(bool& in_active_chain) { m_in_active_chain = &in_active_chain; return *this; }
63  FoundBlock& nextBlock(const FoundBlock& next_block) { m_next_block = &next_block; return *this; }
66  FoundBlock& data(CBlock& data) { m_data = &data; return *this; }
67 
68  uint256* m_hash = nullptr;
69  int* m_height = nullptr;
70  int64_t* m_time = nullptr;
71  int64_t* m_max_time = nullptr;
72  int64_t* m_mtp_time = nullptr;
73  bool* m_in_active_chain = nullptr;
75  const FoundBlock* m_next_block = nullptr;
76  CBlock* m_data = nullptr;
77  mutable bool found = false;
78 };
79 
81 struct BlockInfo {
82  const uint256& hash;
83  const uint256* prev_hash = nullptr;
84  int height = -1;
85  int file_number = -1;
86  unsigned data_pos = 0;
87  const CBlock* data = nullptr;
88  const CBlockUndo* undo_data = nullptr;
89 
91 };
92 
117 class Chain
118 {
119 public:
120  virtual ~Chain() {}
121 
125  virtual std::optional<int> getHeight() = 0;
126 
128  virtual uint256 getBlockHash(int height) = 0;
129 
132  virtual bool haveBlockOnDisk(int height) = 0;
133 
135  virtual CBlockLocator getTipLocator() = 0;
136 
139  virtual CBlockLocator getActiveChainLocator(const uint256& block_hash) = 0;
140 
144  virtual std::optional<int> findLocatorFork(const CBlockLocator& locator) = 0;
145 
148  virtual bool findBlock(const uint256& hash, const FoundBlock& block={}) = 0;
149 
154  virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock& block={}) = 0;
155 
158  virtual bool findAncestorByHeight(const uint256& block_hash, int ancestor_height, const FoundBlock& ancestor_out={}) = 0;
159 
162  virtual bool findAncestorByHash(const uint256& block_hash,
163  const uint256& ancestor_hash,
164  const FoundBlock& ancestor_out={}) = 0;
165 
168  virtual bool findCommonAncestor(const uint256& block_hash1,
169  const uint256& block_hash2,
170  const FoundBlock& ancestor_out={},
171  const FoundBlock& block1_out={},
172  const FoundBlock& block2_out={}) = 0;
173 
177  virtual void findCoins(std::map<COutPoint, Coin>& coins) = 0;
178 
181  virtual double guessVerificationProgress(const uint256& block_hash) = 0;
182 
186  virtual bool hasBlocks(const uint256& block_hash, int min_height = 0, std::optional<int> max_height = {}) = 0;
187 
189  virtual RBFTransactionState isRBFOptIn(const CTransaction& tx) = 0;
190 
192  virtual bool isInMempool(const uint256& txid) = 0;
193 
195  virtual bool hasDescendantsInMempool(const uint256& txid) = 0;
196 
200  virtual bool broadcastTransaction(const CTransactionRef& tx,
201  const CAmount& max_tx_fee,
202  bool relay,
203  std::string& err_string) = 0;
204 
206  virtual void getTransactionAncestry(const uint256& txid, size_t& ancestors, size_t& descendants, size_t* ancestorsize = nullptr, CAmount* ancestorfees = nullptr) = 0;
207 
211  virtual void getPackageLimits(unsigned int& limit_ancestor_count, unsigned int& limit_descendant_count) = 0;
212 
214  virtual bool checkChainLimits(const CTransactionRef& tx) = 0;
215 
217  virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation* calc = nullptr) = 0;
218 
220  virtual unsigned int estimateMaxBlocks() = 0;
221 
223  virtual CFeeRate mempoolMinFee() = 0;
224 
226  virtual CFeeRate relayMinFee() = 0;
227 
229  virtual CFeeRate relayIncrementalFee() = 0;
230 
232  virtual CFeeRate relayDustFee() = 0;
233 
235  virtual bool havePruned() = 0;
236 
238  virtual bool isReadyToBroadcast() = 0;
239 
241  virtual bool isInitialBlockDownload() = 0;
242 
244  virtual bool shutdownRequested() = 0;
245 
247  virtual void initMessage(const std::string& message) = 0;
248 
250  virtual void initWarning(const bilingual_str& message) = 0;
251 
253  virtual void initError(const bilingual_str& message) = 0;
254 
256  virtual void showProgress(const std::string& title, int progress, bool resume_possible) = 0;
257 
260  {
261  public:
262  virtual ~Notifications() {}
263  virtual void transactionAddedToMempool(const CTransactionRef& tx, uint64_t mempool_sequence) {}
264  virtual void transactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason, uint64_t mempool_sequence) {}
265  virtual void blockConnected(const BlockInfo& block) {}
266  virtual void blockDisconnected(const BlockInfo& block) {}
267  virtual void updatedBlockTip() {}
268  virtual void chainStateFlushed(const CBlockLocator& locator) {}
269  };
270 
272  virtual std::unique_ptr<Handler> handleNotifications(std::shared_ptr<Notifications> notifications) = 0;
273 
276  virtual void waitForNotificationsIfTipChanged(const uint256& old_tip) = 0;
277 
280  virtual std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) = 0;
281 
283  virtual bool rpcEnableDeprecated(const std::string& method) = 0;
284 
286  virtual void rpcRunLater(const std::string& name, std::function<void()> fn, int64_t seconds) = 0;
287 
289  virtual int rpcSerializationFlags() = 0;
290 
292  virtual util::SettingsValue getSetting(const std::string& arg) = 0;
293 
295  virtual std::vector<util::SettingsValue> getSettingsList(const std::string& arg) = 0;
296 
298  virtual util::SettingsValue getRwSetting(const std::string& name) = 0;
299 
302  virtual bool updateRwSetting(const std::string& name, const util::SettingsValue& value, bool write=true) = 0;
303 
312  virtual void requestMempoolTransactions(Notifications& notifications) = 0;
313 
315  virtual bool hasAssumedValidChain() = 0;
316 
319  virtual node::NodeContext* context() { return nullptr; }
320 };
321 
325 {
326 public:
327  virtual ~ChainClient() {}
328 
330  virtual void registerRpcs() = 0;
331 
333  virtual bool verify() = 0;
334 
336  virtual bool load() = 0;
337 
339  virtual void start(CScheduler& scheduler) = 0;
340 
342  virtual void flush() = 0;
343 
345  virtual void stop() = 0;
346 
348  virtual void setMockTime(int64_t time) = 0;
349 };
350 
352 std::unique_ptr<Chain> MakeChain(node::NodeContext& node);
353 
354 } // namespace interfaces
355 
356 #endif // BITCOIN_INTERFACES_CHAIN_H
interfaces::MakeChain
std::unique_ptr< Chain > MakeChain(node::NodeContext &node)
Return implementation of Chain interface.
Definition: interfaces.cpp:785
interfaces
Definition: dummywallet.cpp:10
interfaces::Chain::findAncestorByHash
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.
interfaces::ChainClient::registerRpcs
virtual void registerRpcs()=0
Register rpcs.
CScheduler
Simple class for background tasks that should be run periodically or once "after a while".
Definition: scheduler.h:38
interfaces::Chain::guessVerificationProgress
virtual double guessVerificationProgress(const uint256 &block_hash)=0
Estimate fraction of total transactions verified if blocks up to the specified block hash are verifie...
interfaces::Chain::Notifications::blockDisconnected
virtual void blockDisconnected(const BlockInfo &block)
Definition: chain.h:266
interfaces::Chain::rpcSerializationFlags
virtual int rpcSerializationFlags()=0
Current RPC serialization flags.
interfaces::FoundBlock::data
FoundBlock & data(CBlock &data)
Read block data from disk.
Definition: chain.h:66
interfaces::Chain::Notifications::~Notifications
virtual ~Notifications()
Definition: chain.h:262
interfaces::FoundBlock::m_data
CBlock * m_data
Definition: chain.h:76
interfaces::Chain::findCoins
virtual void findCoins(std::map< COutPoint, Coin > &coins)=0
Look up unspent output information.
interfaces::Chain::Notifications::transactionRemovedFromMempool
virtual void transactionRemovedFromMempool(const CTransactionRef &tx, MemPoolRemovalReason reason, uint64_t mempool_sequence)
Definition: chain.h:264
interfaces::FoundBlock::mtpTime
FoundBlock & mtpTime(int64_t &mtp_time)
Definition: chain.h:57
transaction.h
interfaces::Chain::hasAssumedValidChain
virtual bool hasAssumedValidChain()=0
Return true if an assumed-valid chain is in use.
interfaces::BlockKey::height
int height
Definition: chain.h:44
RBFTransactionState
RBFTransactionState
The rbf state of unconfirmed transactions.
Definition: rbf.h:27
bilingual_str
Bilingual messages:
Definition: translation.h:18
interfaces::Chain::isInitialBlockDownload
virtual bool isInitialBlockDownload()=0
Check if in IBD.
interfaces::FoundBlock::nextBlock
FoundBlock & nextBlock(const FoundBlock &next_block)
Return next block in the active chain if current block is in the active chain.
Definition: chain.h:63
interfaces::Chain::Notifications::chainStateFlushed
virtual void chainStateFlushed(const CBlockLocator &locator)
Definition: chain.h:268
interfaces::Chain::~Chain
virtual ~Chain()
Definition: chain.h:120
interfaces::FoundBlock::m_in_active_chain
bool * m_in_active_chain
Definition: chain.h:73
node::NodeContext
NodeContext struct containing references to chain state and connection state.
Definition: context.h:43
interfaces::Chain::handleNotifications
virtual std::unique_ptr< Handler > handleNotifications(std::shared_ptr< Notifications > notifications)=0
Register handler for notifications.
interfaces::Chain::getSettingsList
virtual std::vector< util::SettingsValue > getSettingsList(const std::string &arg)=0
Get list of settings values.
interfaces::Chain::hasDescendantsInMempool
virtual bool hasDescendantsInMempool(const uint256 &txid)=0
Check if transaction has descendants in mempool.
interfaces::FoundBlock::found
bool found
Definition: chain.h:77
interfaces::ChainClient::flush
virtual void flush()=0
Save state to disk.
interfaces::FoundBlock::m_next_block
const FoundBlock * m_next_block
Definition: chain.h:75
interfaces::Chain::getHeight
virtual std::optional< int > getHeight()=0
Get current chain height, not including genesis block (returns 0 if chain only contains genesis block...
interfaces::Chain::context
virtual node::NodeContext * context()
Get internal node context.
Definition: chain.h:319
interfaces::Chain::findBlock
virtual bool findBlock(const uint256 &hash, const FoundBlock &block={})=0
Return whether node has the block and optionally return block metadata or contents.
interfaces::BlockInfo::undo_data
const CBlockUndo * undo_data
Definition: chain.h:88
interfaces::ChainClient::start
virtual void start(CScheduler &scheduler)=0
Start client execution and provide a scheduler.
CTransactionRef
std::shared_ptr< const CTransaction > CTransactionRef
Definition: transaction.h:414
interfaces::Chain::findAncestorByHeight
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.
interfaces::Chain::getRwSetting
virtual util::SettingsValue getRwSetting(const std::string &name)=0
Return <datadir>/settings.json setting value.
CFeeRate
Fee rate in satoshis per kilovirtualbyte: CAmount / kvB.
Definition: feerate.h:32
interfaces::FoundBlock::time
FoundBlock & time(int64_t &time)
Definition: chain.h:55
interfaces::Chain::getPackageLimits
virtual void getPackageLimits(unsigned int &limit_ancestor_count, unsigned int &limit_descendant_count)=0
Get the node's package limits.
UniValue
Definition: univalue.h:18
CTransaction
The basic transaction that is broadcasted on the network and contained in blocks.
Definition: transaction.h:287
interfaces::ChainClient::~ChainClient
virtual ~ChainClient()
Definition: chain.h:327
interfaces::Chain::relayIncrementalFee
virtual CFeeRate relayIncrementalFee()=0
Relay incremental fee setting (-incrementalrelayfee), reflecting cost of relay.
interfaces::Chain::getActiveChainLocator
virtual CBlockLocator getActiveChainLocator(const uint256 &block_hash)=0
Return a locator that refers to a block in the active chain.
interfaces::Chain::isReadyToBroadcast
virtual bool isReadyToBroadcast()=0
Check if the node is ready to broadcast transactions.
interfaces::Chain::havePruned
virtual bool havePruned()=0
Check if any block has been pruned.
interfaces::Chain
Interface giving clients (wallet processes, maybe other analysis tools in the future) ability to acce...
Definition: chain.h:117
interfaces::Chain::Notifications::updatedBlockTip
virtual void updatedBlockTip()
Definition: chain.h:267
FeeCalculation
Definition: fees.h:76
settings.h
interfaces::FoundBlock::m_time
int64_t * m_time
Definition: chain.h:70
interfaces::ChainClient::load
virtual bool load()=0
Load saved state.
CRPCCommand
Definition: server.h:89
Coin
A UTXO entry.
Definition: coins.h:30
interfaces::Chain::getBlockHash
virtual uint256 getBlockHash(int height)=0
Get block hash. Height must be valid or this function will abort.
interfaces::Chain::mempoolMinFee
virtual CFeeRate mempoolMinFee()=0
Mempool minimum fee.
interfaces::BlockInfo::hash
const uint256 & hash
Definition: chain.h:82
interfaces::FoundBlock::maxTime
FoundBlock & maxTime(int64_t &max_time)
Definition: chain.h:56
interfaces::Chain::waitForNotificationsIfTipChanged
virtual void waitForNotificationsIfTipChanged(const uint256 &old_tip)=0
Wait for pending notifications to be processed unless block hash points to the current chain tip.
interfaces::BlockKey::hash
uint256 hash
Definition: chain.h:43
interfaces::Chain::findLocatorFork
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...
CAmount
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
interfaces::Chain::relayMinFee
virtual CFeeRate relayMinFee()=0
Relay current minimum fee (from -minrelaytxfee and -incrementalrelayfee settings).
interfaces::Chain::shutdownRequested
virtual bool shutdownRequested()=0
Check if shutdown requested.
interfaces::BlockInfo::prev_hash
const uint256 * prev_hash
Definition: chain.h:83
interfaces::Chain::broadcastTransaction
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...
interfaces::Chain::updateRwSetting
virtual bool updateRwSetting(const std::string &name, const util::SettingsValue &value, bool write=true)=0
Write a setting to <datadir>/settings.json.
interfaces::FoundBlock
Helper for findBlock to selectively return pieces of block data.
Definition: chain.h:50
interfaces::Chain::rpcRunLater
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.
uint256
256-bit opaque blob.
Definition: uint256.h:126
interfaces::BlockInfo::file_number
int file_number
Definition: chain.h:85
interfaces::Chain::isRBFOptIn
virtual RBFTransactionState isRBFOptIn(const CTransaction &tx)=0
Check if transaction is RBF opt in.
interfaces::Chain::findCommonAncestor
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.
interfaces::Chain::rpcEnableDeprecated
virtual bool rpcEnableDeprecated(const std::string &method)=0
Check if deprecated RPC is enabled.
interfaces::Chain::Notifications::transactionAddedToMempool
virtual void transactionAddedToMempool(const CTransactionRef &tx, uint64_t mempool_sequence)
Definition: chain.h:263
name
const char * name
Definition: rest.cpp:46
interfaces::Chain::estimateSmartFee
virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation *calc=nullptr)=0
Estimate smart fee.
interfaces::FoundBlock::height
FoundBlock & height(int &height)
Definition: chain.h:54
interfaces::Chain::initWarning
virtual void initWarning(const bilingual_str &message)=0
Send init warning.
CBlock
Definition: block.h:62
interfaces::FoundBlock::m_hash
uint256 * m_hash
Definition: chain.h:68
command
const auto command
Definition: bitcoin-wallet.cpp:118
interfaces::BlockKey
Hash/height pair to help track and identify blocks.
Definition: chain.h:42
interfaces::ChainClient
Interface to let node manage chain clients (wallets, or maybe tools for monitoring and analysis in th...
Definition: chain.h:324
LIFETIMEBOUND
#define LIFETIMEBOUND
Definition: attributes.h:16
interfaces::BlockInfo::height
int height
Definition: chain.h:84
ArgsManager
Definition: system.h:172
interfaces::Chain::isInMempool
virtual bool isInMempool(const uint256 &txid)=0
Check if transaction is in mempool.
MemPoolRemovalReason
MemPoolRemovalReason
Reason why a transaction was removed from the mempool, this is passed to the notification signal.
Definition: txmempool.h:349
interfaces::Chain::Notifications
Chain notifications.
Definition: chain.h:259
interfaces::FoundBlock::m_max_time
int64_t * m_max_time
Definition: chain.h:71
interfaces::Chain::relayDustFee
virtual CFeeRate relayDustFee()=0
Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend.
interfaces::FoundBlock::m_mtp_time
int64_t * m_mtp_time
Definition: chain.h:72
interfaces::Chain::initMessage
virtual void initMessage(const std::string &message)=0
Send init message.
interfaces::Chain::getSetting
virtual util::SettingsValue getSetting(const std::string &arg)=0
Get settings value.
interfaces::ChainClient::stop
virtual void stop()=0
Shut down client.
interfaces::Chain::getTransactionAncestry
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.
interfaces::Chain::checkChainLimits
virtual bool checkChainLimits(const CTransactionRef &tx)=0
Check if transaction will pass the mempool's chain limits.
interfaces::ChainClient::verify
virtual bool verify()=0
Check for errors before loading.
interfaces::BlockInfo::data
const CBlock * data
Definition: chain.h:87
interfaces::Chain::Notifications::blockConnected
virtual void blockConnected(const BlockInfo &block)
Definition: chain.h:265
node
Definition: init.h:25
interfaces::FoundBlock::hash
FoundBlock & hash(uint256 &hash)
Definition: chain.h:53
interfaces::FoundBlock::locator
FoundBlock & locator(CBlockLocator &locator)
Return locator if block is in the active chain.
Definition: chain.h:61
interfaces::Chain::haveBlockOnDisk
virtual bool haveBlockOnDisk(int height)=0
Check that the block is available on disk (i.e.
interfaces::BlockInfo::data_pos
unsigned data_pos
Definition: chain.h:86
interfaces::FoundBlock::m_locator
CBlockLocator * m_locator
Definition: chain.h:74
interfaces::Chain::initError
virtual void initError(const bilingual_str &message)=0
Send init error.
interfaces::BlockInfo
Block data sent with blockConnected, blockDisconnected notifications.
Definition: chain.h:81
interfaces::BlockInfo::BlockInfo
BlockInfo(const uint256 &hash LIFETIMEBOUND)
Definition: chain.h:90
interfaces::Chain::getTipLocator
virtual CBlockLocator getTipLocator()=0
Get locator for the current chain tip.
interfaces::Chain::requestMempoolTransactions
virtual void requestMempoolTransactions(Notifications &notifications)=0
Synchronously send transactionAddedToMempool notifications about all current mempool transactions to ...
CBlockLocator
Describes a place in the block chain to another node such that if the other node doesn't have the sam...
Definition: block.h:114
interfaces::Chain::showProgress
virtual void showProgress(const std::string &title, int progress, bool resume_possible)=0
Send progress indicator.
interfaces::FoundBlock::inActiveChain
FoundBlock & inActiveChain(bool &in_active_chain)
Return whether block is in the active (most-work) chain.
Definition: chain.h:59
interfaces::Chain::estimateMaxBlocks
virtual unsigned int estimateMaxBlocks()=0
Fee estimator max target.
interfaces::Chain::handleRpc
virtual std::unique_ptr< Handler > handleRpc(const CRPCCommand &command)=0
Register handler for RPC.
interfaces::ChainClient::setMockTime
virtual void setMockTime(int64_t time)=0
Set mock time.
CBlockUndo
Undo information for a CBlock.
Definition: undo.h:63
interfaces::Chain::findFirstBlockWithTimeAndHeight
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,...
interfaces::FoundBlock::m_height
int * m_height
Definition: chain.h:69
interfaces::Chain::hasBlocks
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.