#include <chain.h>

Classes
class	Notifications
	Chain notifications. More...
struct	NotifyOptions
	Options specifying which chain notifications are required. More...

Public Member Functions
virtual	~Chain ()=default
virtual std::optional< int >	getHeight ()=0
virtual uint256	getBlockHash (int height)=0
	Get block hash. Height must be valid or this function will abort.
virtual bool	haveBlockOnDisk (int height)=0
virtual std::optional< int >	findLocatorFork (const CBlockLocator &locator)=0
virtual bool	hasBlockFilterIndex (BlockFilterType filter_type)=0
	Returns whether a block filter index is available.
virtual std::optional< bool >	blockFilterMatchesAny (BlockFilterType filter_type, const uint256 &block_hash, const GCSFilter::ElementSet &filter_set)=0
virtual bool	findBlock (const uint256 &hash, const FoundBlock &block={})=0
virtual bool	findFirstBlockWithTimeAndHeight (int64_t min_time, int min_height, const FoundBlock &block={})=0
virtual bool	findAncestorByHeight (const uint256 &block_hash, int ancestor_height, const FoundBlock &ancestor_out={})=0
virtual bool	findAncestorByHash (const uint256 &block_hash, const uint256 &ancestor_hash, const FoundBlock &ancestor_out={})=0
virtual bool	findCommonAncestor (const uint256 &block_hash1, const uint256 &block_hash2, const FoundBlock &ancestor_out={}, const FoundBlock &block1_out={}, const FoundBlock &block2_out={})=0
virtual void	findCoins (std::map< COutPoint, Coin > &coins)=0
virtual double	guessVerificationProgress (const uint256 &block_hash)=0
virtual bool	hasBlocks (const uint256 &block_hash, int min_height=0, std::optional< int > max_height={})=0
virtual RBFTransactionState	isRBFOptIn (const CTransaction &tx)=0
	Check if transaction is RBF opt in.
virtual bool	isInMempool (const Txid &txid)=0
	Check if transaction is in mempool.
virtual bool	hasDescendantsInMempool (const Txid &txid)=0
	Check if transaction has descendants in mempool.
virtual bool	broadcastTransaction (const CTransactionRef &tx, const CAmount &max_tx_fee, node::TxBroadcast broadcast_method, std::string &err_string)=0
virtual void	getTransactionAncestry (const Txid &txid, size_t &ancestors, size_t &cluster_count, size_t ancestorsize=nullptr, CAmount ancestorfees=nullptr)=0
	Calculate mempool ancestor and cluster counts for the given transaction.
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 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 void	getPackageLimits (unsigned int &limit_ancestor_count, unsigned int &limit_descendant_count)=0
virtual util::Result< void >	checkChainLimits (const CTransactionRef &tx)=0
	Check if transaction will pass the mempool's chain limits.
virtual CFeeRate	estimateSmartFee (int num_blocks, bool conservative, FeeCalculation *calc=nullptr)=0
	Estimate smart fee.
virtual unsigned int	estimateMaxBlocks ()=0
	Fee estimator max target.
virtual CFeeRate	mempoolMinFee ()=0
	Mempool minimum 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 CFeeRate	relayDustFee ()=0
	Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend.
virtual bool	havePruned ()=0
	Check if any block has been pruned.
virtual std::optional< int >	getPruneHeight ()=0
	Get the current prune height.
virtual bool	isReadyToBroadcast ()=0
	Check if the node is ready to broadcast transactions.
virtual bool	isInitialBlockDownload ()=0
	Check if in IBD.
virtual bool	shutdownRequested ()=0
	Check if shutdown requested.
virtual void	initMessage (const std::string &message)=0
	Send init message.
virtual void	initWarning (const bilingual_str &message)=0
	Send init warning.
virtual void	initError (const bilingual_str &message)=0
	Send init error.
virtual void	showProgress (const std::string &title, int progress, bool resume_possible)=0
	Send progress indicator.
virtual std::unique_ptr< Handler >	handleNotifications (std::shared_ptr< Notifications > notifications)=0
virtual void	waitForNotificationsIfTipChanged (const uint256 &old_tip)=0
virtual void	waitForNotifications ()=0
	Wait for all pending notifications up to this point to be processed.
virtual std::unique_ptr< Handler >	handleRpc (const CRPCCommand &command)=0
virtual bool	rpcEnableDeprecated (const std::string &method)=0
	Check if deprecated RPC is enabled.
virtual common::SettingsValue	getSetting (const std::string &arg)=0
	Get settings value.
virtual std::vector< common::SettingsValue >	getSettingsList (const std::string &arg)=0
	Get list of settings values.
virtual common::SettingsValue	getRwSetting (const std::string &name)=0
	Return <datadir>/settings.json setting value.
virtual bool	updateRwSetting (const std::string &name, const SettingsUpdate &update_function)=0
virtual bool	overwriteRwSetting (const std::string &name, common::SettingsValue value, SettingsAction action=SettingsAction::WRITE)=0
virtual bool	deleteRwSettings (const std::string &name, SettingsAction action=SettingsAction::WRITE)=0
virtual void	requestMempoolTransactions (Notifications &notifications)=0
virtual bool	hasAssumedValidChain ()=0
virtual node::NodeContext *	context ()

Detailed Description

Interface giving clients (wallet processes, maybe other analysis tools in the future) ability to access to the chain state, receive notifications, estimate fees, and submit transactions.

TODO: Current chain methods are too low level, exposing too much of the internal workings of the bitcoin node, and not being very convenient to use. Chain methods should be cleaned up and simplified over time. Examples:

The initMessages() and showProgress() methods which the wallet uses to send notifications to the GUI should go away when GUI and wallet can directly communicate with each other without going through the node (https://github.com/bitcoin/bitcoin/pull/15288#discussion_r253321096).
The handleRpc, registerRpcs, rpcEnableDeprecated methods and other RPC methods can go away if wallets listen for HTTP requests on their own ports instead of registering to handle requests on the node HTTP port.
Move fee estimation queries to an asynchronous interface and let the wallet cache it, fee estimation being driven by node mempool, wallet should be the consumer.
guessVerificationProgress and similar methods can go away if rescan logic moves out of the wallet, and the wallet just requests scans from the node (https://github.com/bitcoin/bitcoin/issues/11756)

Definition at line 117 of file chain.h.

Constructor & Destructor Documentation

◆ ~Chain()

virtual interfaces::Chain::~Chain ( )

virtualdefault

Member Function Documentation

◆ blockFilterMatchesAny()

virtual std::optional< bool > interfaces::Chain::blockFilterMatchesAny	(	BlockFilterType	filter_type,
		const uint256 &	block_hash,
		const GCSFilter::ElementSet &	filter_set )

pure virtual

Returns whether any of the elements match the block via a BIP 157 block filter or std::nullopt if the block filter for this block couldn't be found.

◆ broadcastTransaction()

virtual bool interfaces::Chain::broadcastTransaction	(	const CTransactionRef &	tx,
		const CAmount &	max_tx_fee,
		node::TxBroadcast	broadcast_method,
		std::string &	err_string )

pure virtual

Process a local transaction, optionally adding it to the mempool and optionally broadcasting it to the network.

Parameters

[in]	tx	Transaction to process.
[in]	max_tx_fee	Don't add the transaction to the mempool or broadcast it if its fee is higher than this.
[in]	broadcast_method	Whether to add the transaction to the mempool and how/whether to broadcast it.
[out]	err_string	Set if an error occurs.

Returns: False if the transaction could not be added due to the fee or for another reason.

◆ calculateCombinedBumpFee()

virtual std::optional< CAmount > interfaces::Chain::calculateCombinedBumpFee	(	const std::vector< COutPoint > &	outpoints,
		const CFeeRate &	target_feerate )

pure virtual

Calculate the combined bump fee for an input set per the same strategy.

◆ calculateIndividualBumpFees()

virtual std::map< COutPoint, CAmount > interfaces::Chain::calculateIndividualBumpFees	(	const std::vector< COutPoint > &	outpoints,
		const CFeeRate &	target_feerate )

pure virtual

For each outpoint, calculate the fee-bumping cost to spend this outpoint at the specified.

◆ checkChainLimits()

virtual util::Result< void > interfaces::Chain::checkChainLimits ( const CTransactionRef & tx )

pure virtual

Check if transaction will pass the mempool's chain limits.

◆ context()

virtual node::NodeContext * interfaces::Chain::context ( )

inlinevirtual

Get internal node context. Useful for testing, but not accessible across processes.

Definition at line 392 of file chain.h.

◆ deleteRwSettings()

virtual bool interfaces::Chain::deleteRwSettings	(	const std::string &	name,
		SettingsAction	action = SettingsAction::WRITE )

pure virtual

Delete a given setting in <datadir>/settings.json. This method provides a simpler alternative to overwriteRwSetting when erasing a setting, for ease of use and readability.

◆ estimateMaxBlocks()

virtual unsigned int interfaces::Chain::estimateMaxBlocks ( )

pure virtual

Fee estimator max target.

◆ estimateSmartFee()

virtual CFeeRate interfaces::Chain::estimateSmartFee	(	int	num_blocks,
		bool	conservative,
		FeeCalculation *	calc = nullptr )

pure virtual

Estimate smart fee.

◆ findAncestorByHash()

virtual bool interfaces::Chain::findAncestorByHash	(	const uint256 &	block_hash,
		const uint256 &	ancestor_hash,
		const FoundBlock &	ancestor_out = {} )

pure virtual

Return whether block descends from a specified ancestor, and optionally return ancestor information.

◆ findAncestorByHeight()

virtual bool interfaces::Chain::findAncestorByHeight	(	const uint256 &	block_hash,
		int	ancestor_height,
		const FoundBlock &	ancestor_out = {} )

pure virtual

Find ancestor of block at specified height and optionally return ancestor information.

◆ findBlock()

virtual bool interfaces::Chain::findBlock	(	const uint256 &	hash,
		const FoundBlock &	block = {} )

pure virtual

Return whether node has the block and optionally return block metadata or contents.

◆ findCoins()

virtual void interfaces::Chain::findCoins ( std::map< COutPoint, Coin > & coins )

pure virtual

Look up unspent output information. Returns coins in the mempool and in the current chain UTXO set. Iterates through all the keys in the map and populates the values.

◆ findCommonAncestor()

virtual bool interfaces::Chain::findCommonAncestor	(	const uint256 &	block_hash1,
		const uint256 &	block_hash2,
		const FoundBlock &	ancestor_out = {},
		const FoundBlock &	block1_out = {},
		const FoundBlock &	block2_out = {} )

pure virtual

Find most recent common ancestor between two blocks and optionally return block information.

◆ findFirstBlockWithTimeAndHeight()

virtual bool interfaces::Chain::findFirstBlockWithTimeAndHeight	(	int64_t	min_time,
		int	min_height,
		const FoundBlock &	block = {} )

pure virtual

Find first block in the chain with timestamp >= the given time and height >= than the given height, return false if there is no block with a high enough timestamp and height. Optionally return block information.

◆ findLocatorFork()

virtual std::optional< int > interfaces::Chain::findLocatorFork ( const CBlockLocator & locator )

pure virtual

Return height of the highest block on chain in common with the locator, which will either be the original block used to create the locator, or one of its ancestors.

◆ getBlockHash()

virtual uint256 interfaces::Chain::getBlockHash ( int height )

pure virtual

Get block hash. Height must be valid or this function will abort.

◆ getHeight()

virtual std::optional< int > interfaces::Chain::getHeight ( )

pure virtual

Get current chain height, not including genesis block (returns 0 if chain only contains genesis block, nullopt if chain does not contain any blocks)

◆ getPackageLimits()

virtual void interfaces::Chain::getPackageLimits	(	unsigned int &	limit_ancestor_count,
		unsigned int &	limit_descendant_count )

pure virtual

Get the node's package limits. Currently only returns the ancestor and descendant count limits, but could be enhanced to return more policy settings.

◆ getPruneHeight()

virtual std::optional< int > interfaces::Chain::getPruneHeight ( )

pure virtual

Get the current prune height.

◆ getRwSetting()

virtual common::SettingsValue interfaces::Chain::getRwSetting ( const std::string & name )

pure virtual

Return <datadir>/settings.json setting value.

◆ getSetting()

virtual common::SettingsValue interfaces::Chain::getSetting ( const std::string & arg )

pure virtual

Get settings value.

◆ getSettingsList()

virtual std::vector< common::SettingsValue > interfaces::Chain::getSettingsList ( const std::string & arg )

pure virtual

Get list of settings values.

◆ getTransactionAncestry()

virtual void interfaces::Chain::getTransactionAncestry	(	const Txid &	txid,
		size_t &	ancestors,
		size_t &	cluster_count,
		size_t *	ancestorsize = nullptr,
		CAmount *	ancestorfees = nullptr )

pure virtual

Calculate mempool ancestor and cluster counts for the given transaction.

◆ guessVerificationProgress()

virtual double interfaces::Chain::guessVerificationProgress ( const uint256 & block_hash )

pure virtual

Estimate fraction of total transactions verified if blocks up to the specified block hash are verified.

◆ handleNotifications()

virtual std::unique_ptr< Handler > interfaces::Chain::handleNotifications ( std::shared_ptr< Notifications > notifications )

pure virtual

Register handler for notifications. Some notifications are asynchronous and may still execute after the handler is disconnected. Use waitForNotifications() after the handler is disconnected to ensure all pending notifications have been processed.

◆ handleRpc()

virtual std::unique_ptr< Handler > interfaces::Chain::handleRpc ( const CRPCCommand & command )

pure virtual

Register handler for RPC. Command is not copied, so reference needs to remain valid until Handler is disconnected.

◆ hasAssumedValidChain()

virtual bool interfaces::Chain::hasAssumedValidChain ( )

pure virtual

Return true if an assumed-valid snapshot is in use. Note that this returns true even after the snapshot is validated, until the next node restart.

◆ hasBlockFilterIndex()

virtual bool interfaces::Chain::hasBlockFilterIndex ( BlockFilterType filter_type )

pure virtual

Returns whether a block filter index is available.

◆ hasBlocks()

virtual bool interfaces::Chain::hasBlocks	(	const uint256 &	block_hash,
		int	min_height = 0,
		std::optional< int >	max_height = {} )

pure virtual

Return true if data is available for all blocks in the specified range of blocks. This checks all blocks that are ancestors of block_hash in the height range from min_height to max_height, inclusive.

◆ hasDescendantsInMempool()

virtual bool interfaces::Chain::hasDescendantsInMempool ( const Txid & txid )

pure virtual

Check if transaction has descendants in mempool.

◆ haveBlockOnDisk()

virtual bool interfaces::Chain::haveBlockOnDisk ( int height )

pure virtual

Check that the block is available on disk (i.e. has not been pruned), and contains transactions.

◆ havePruned()

virtual bool interfaces::Chain::havePruned ( )

pure virtual

Check if any block has been pruned.

◆ initError()

virtual void interfaces::Chain::initError ( const bilingual_str & message )

pure virtual

Send init error.

◆ initMessage()

virtual void interfaces::Chain::initMessage ( const std::string & message )

pure virtual

Send init message.

◆ initWarning()

virtual void interfaces::Chain::initWarning ( const bilingual_str & message )

pure virtual

Send init warning.

◆ isInitialBlockDownload()

virtual bool interfaces::Chain::isInitialBlockDownload ( )

pure virtual

Check if in IBD.

◆ isInMempool()

virtual bool interfaces::Chain::isInMempool ( const Txid & txid )

pure virtual

Check if transaction is in mempool.

◆ isRBFOptIn()

virtual RBFTransactionState interfaces::Chain::isRBFOptIn ( const CTransaction & tx )

pure virtual

Check if transaction is RBF opt in.

◆ isReadyToBroadcast()

virtual bool interfaces::Chain::isReadyToBroadcast ( )

pure virtual

Check if the node is ready to broadcast transactions.

◆ mempoolMinFee()

virtual CFeeRate interfaces::Chain::mempoolMinFee ( )

pure virtual

Mempool minimum fee.

◆ overwriteRwSetting()

virtual bool interfaces::Chain::overwriteRwSetting	(	const std::string &	name,
		common::SettingsValue	value,
		SettingsAction	action = SettingsAction::WRITE )

pure virtual

Replace a setting in <datadir>/settings.json with a new value. Null can be passed to erase the setting. This method provides a simpler alternative to updateRwSetting when atomically reading and updating the setting is not required.

◆ relayDustFee()

virtual CFeeRate interfaces::Chain::relayDustFee ( )

pure virtual

Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend.

◆ relayIncrementalFee()

virtual CFeeRate interfaces::Chain::relayIncrementalFee ( )

pure virtual

Relay incremental fee setting (-incrementalrelayfee), reflecting cost of relay.

◆ relayMinFee()

virtual CFeeRate interfaces::Chain::relayMinFee ( )

pure virtual

Relay current minimum fee (from -minrelaytxfee and -incrementalrelayfee settings).

◆ requestMempoolTransactions()

virtual void interfaces::Chain::requestMempoolTransactions ( Notifications & notifications )

pure virtual

Synchronously send transactionAddedToMempool notifications about all current mempool transactions to the specified handler and return after the last one is sent. These notifications aren't coordinated with async notifications sent by handleNotifications, so out of date async notifications from handleNotifications can arrive during and after synchronous notifications from requestMempoolTransactions. Clients need to be prepared to handle this by ignoring notifications about unknown removed transactions and already added new transactions.

◆ rpcEnableDeprecated()

virtual bool interfaces::Chain::rpcEnableDeprecated ( const std::string & method )

pure virtual

Check if deprecated RPC is enabled.

◆ showProgress()

virtual void interfaces::Chain::showProgress	(	const std::string &	title,
		int	progress,
		bool	resume_possible )

pure virtual

Send progress indicator.

◆ shutdownRequested()

virtual bool interfaces::Chain::shutdownRequested ( )

pure virtual

Check if shutdown requested.

◆ updateRwSetting()

virtual bool interfaces::Chain::updateRwSetting	(	const std::string &	name,
		const SettingsUpdate &	update_function )

pure virtual

Updates a setting in <datadir>/settings.json. Null can be passed to erase the setting. There is intentionally no support for writing null values to settings.json. Depending on the action returned by the update function, this will either update the setting in memory or write the updated settings to disk.

◆ waitForNotifications()

virtual void interfaces::Chain::waitForNotifications ( )

pure virtual

Wait for all pending notifications up to this point to be processed.

◆ waitForNotificationsIfTipChanged()

virtual void interfaces::Chain::waitForNotificationsIfTipChanged ( const uint256 & old_tip )

pure virtual

Wait for pending notifications to be processed unless block hash points to the current chain tip.

The documentation for this class was generated from the following file:

src/interfaces/chain.h

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Chain()

Member Function Documentation

◆ blockFilterMatchesAny()

◆ broadcastTransaction()

◆ calculateCombinedBumpFee()

◆ calculateIndividualBumpFees()

◆ checkChainLimits()

◆ context()

◆ deleteRwSettings()

◆ estimateMaxBlocks()

◆ estimateSmartFee()

◆ findAncestorByHash()

◆ findAncestorByHeight()

◆ findBlock()

◆ findCoins()

◆ findCommonAncestor()

◆ findFirstBlockWithTimeAndHeight()

◆ findLocatorFork()

◆ getBlockHash()

◆ getHeight()

◆ getPackageLimits()

◆ getPruneHeight()

◆ getRwSetting()

◆ getSetting()

◆ getSettingsList()

◆ getTransactionAncestry()

◆ guessVerificationProgress()

◆ handleNotifications()

◆ handleRpc()

◆ hasAssumedValidChain()

◆ hasBlockFilterIndex()

◆ hasBlocks()

◆ hasDescendantsInMempool()

◆ haveBlockOnDisk()

◆ havePruned()

◆ initError()

◆ initMessage()

◆ initWarning()

◆ isInitialBlockDownload()

◆ isInMempool()

◆ isRBFOptIn()

◆ isReadyToBroadcast()

◆ mempoolMinFee()

◆ overwriteRwSetting()

◆ relayDustFee()

◆ relayIncrementalFee()

◆ relayMinFee()

◆ requestMempoolTransactions()

◆ rpcEnableDeprecated()

◆ showProgress()

◆ shutdownRequested()

◆ updateRwSetting()

◆ waitForNotifications()

◆ waitForNotificationsIfTipChanged()