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. More...

#include <chain.h>

Classes
class	Notifications
	Chain notifications. More...

Public Member Functions
virtual	~Chain ()

virtual std::optional< int >	getHeight ()=0
	Get current chain height, not including genesis block (returns 0 if chain only contains genesis block, std::nullopt if chain does not contain any blocks)

virtual BlockHash	getBlockHash (int height)=0
	Get block hash. Height must be valid or this function will abort.

virtual bool	haveBlockOnDisk (int height)=0
	Check that the block is available on disk (i.e.

virtual CBlockLocator	getTipLocator ()=0
	Get locator for the current chain tip.

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 original block used to create the locator, or one of its ancestors.

virtual bool	findBlock (const BlockHash &hash, const FoundBlock &block={})=0
	Return whether node has the block and optionally return block metadata or contents.

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, return false if there is no block with a high enough timestamp and height.

virtual bool	findAncestorByHeight (const BlockHash &block_hash, int ancestor_height, const FoundBlock &ancestor_out={})=0
	Find ancestor of block at specified height and optionally return ancestor information.

virtual bool	findAncestorByHash (const BlockHash &block_hash, const BlockHash &ancestor_hash, const FoundBlock &ancestor_out={})=0
	Return whether block descends from a specified ancestor, and optionally return ancestor information.

virtual bool	findCommonAncestor (const BlockHash &block_hash1, const BlockHash &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 void	findCoins (std::map< COutPoint, Coin > &coins)=0
	Look up unspent output information.

virtual double	guessVerificationProgress (const BlockHash &block_hash)=0
	Estimate fraction of total transactions verified if blocks up to the specified block hash are verified.

virtual bool	hasBlocks (const BlockHash &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 bool	broadcastTransaction (const Config &config, const CTransactionRef &tx, const Amount &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_fee, and broadcast to all peers if relay is set to true.

virtual CFeeRate	estimateFee () const =0
	Estimate fee.

virtual CFeeRate	relayMinFee ()=0
	Relay current minimum fee (from -minrelaytxfee settings).

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 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
	Register handler for notifications.

virtual void	waitForNotificationsIfTipChanged (const BlockHash &old_tip)=0
	Wait for pending notifications to be processed unless block hash points to the current chain tip.

virtual std::unique_ptr< Handler >	handleRpc (const CRPCCommand &command)=0
	Register handler for RPC.

virtual bool	rpcEnableDeprecated (const std::string &method)=0
	Check if deprecated RPC is enabled.

virtual void	rpcRunLater (const std::string &name, std::function< void()> fn, int64_t seconds)=0
	Run function after given number of seconds.

virtual int	rpcSerializationFlags ()=0
	Current RPC serialization flags.

virtual util::SettingsValue	getSetting (const std::string &arg)=0
	Get settings value.

virtual std::vector< util::SettingsValue >	getSettingsList (const std::string &arg)=0
	Get list of settings values.

virtual util::SettingsValue	getRwSetting (const std::string &name)=0
	Return <datadir>/settings.json setting value.

virtual bool	updateRwSetting (const std::string &name, const util::SettingsValue &value, bool write=true)=0
	Write a setting to <datadir>/settings.json.

virtual void	requestMempoolTransactions (Notifications &notifications)=0
	Synchronously send transactionAddedToMempool notifications about all current mempool transactions to the specified handler and return after the last one is sent.

virtual const CChainParams &	params () const =0
	This Chain's parameters.

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 123 of file chain.h.

Constructor & Destructor Documentation

◆ ~Chain()

virtual interfaces::Chain::~Chain ( )

inlinevirtual

Definition at line 125 of file chain.h.

Member Function Documentation

◆ broadcastTransaction()

virtual bool interfaces::Chain::broadcastTransaction	(	const Config &	config,
		const CTransactionRef &	tx,
		const Amount &	max_tx_fee,
		bool	relay,
		std::string &	err_string
	)

pure virtual

Transaction is added to memory pool, if the transaction fee is below the amount specified by max_tx_fee, and broadcast to all peers if relay is set to true.

Return false if the transaction could not be added due to the fee or for another reason.

Here is the caller graph for this function:

◆ estimateFee()

virtual CFeeRate interfaces::Chain::estimateFee ( ) const

pure virtual

Estimate fee.

◆ findAncestorByHash()

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

pure virtual

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

Here is the caller graph for this function:

◆ findAncestorByHeight()

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

pure virtual

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

Here is the caller graph for this function:

◆ findBlock()

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

pure virtual

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

Here is the caller graph for this function:

◆ 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.

Here is the caller graph for this function:

◆ findCommonAncestor()

virtual bool interfaces::Chain::findCommonAncestor	(	const BlockHash &	block_hash1,
		const BlockHash &	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.

Here is the caller graph for this function:

◆ 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.

Here is the caller graph for this function:

◆ getBlockHash()

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

pure virtual

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

Here is the caller graph for this function:

◆ 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, std::nullopt if chain does not contain any blocks)

Here is the caller graph for this function:

◆ getRwSetting()

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

pure virtual

Return <datadir>/settings.json setting value.

Here is the caller graph for this function:

◆ getSetting()

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

pure virtual

Get settings value.

◆ getSettingsList()

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

pure virtual

Get list of settings values.

Here is the caller graph for this function:

◆ getTipLocator()

virtual CBlockLocator interfaces::Chain::getTipLocator ( )

pure virtual

Get locator for the current chain tip.

Here is the caller graph for this function:

◆ guessVerificationProgress()

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

pure virtual

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

Here is the caller graph for this function:

◆ handleNotifications()

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

pure virtual

Register handler for notifications.

Here is the caller graph for this function:

◆ 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.

◆ hasBlocks()

virtual bool interfaces::Chain::hasBlocks	(	const BlockHash &	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.

Here is the caller graph for this function:

◆ 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.

Here is the caller graph for this function:

◆ havePruned()

virtual bool interfaces::Chain::havePruned ( )

pure virtual

Check if any block has been pruned.

Here is the caller graph for this function:

◆ initError()

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

pure virtual

Send init error.

Here is the caller graph for this function:

◆ initMessage()

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

pure virtual

Send init message.

Here is the caller graph for this function:

◆ initWarning()

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

pure virtual

Send init warning.

Here is the caller graph for this function:

◆ isInitialBlockDownload()

virtual bool interfaces::Chain::isInitialBlockDownload ( )

pure virtual

Check if in IBD.

◆ isReadyToBroadcast()

virtual bool interfaces::Chain::isReadyToBroadcast ( )

pure virtual

Check if the node is ready to broadcast transactions.

◆ params()

virtual const CChainParams & interfaces::Chain::params ( ) const

pure virtual

This Chain's parameters.

Here is the caller graph for this function:

◆ relayDustFee()

virtual CFeeRate interfaces::Chain::relayDustFee ( )

pure virtual

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

◆ relayMinFee()

virtual CFeeRate interfaces::Chain::relayMinFee ( )

pure virtual

Relay current minimum fee (from -minrelaytxfee settings).

Here is the caller graph for this function:

◆ 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.

Here is the caller graph for this function:

◆ rpcEnableDeprecated()

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

pure virtual

Check if deprecated RPC is enabled.

◆ rpcRunLater()

virtual void interfaces::Chain::rpcRunLater	(	const std::string &	name,
		std::function< void()>	fn,
		int64_t	seconds
	)

pure virtual

Run function after given number of seconds.

Cancel any previous calls with same name.

Here is the caller graph for this function:

◆ rpcSerializationFlags()

virtual int interfaces::Chain::rpcSerializationFlags ( )

pure virtual

Current RPC serialization flags.

Here is the caller graph for this function:

◆ showProgress()

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

pure virtual

Send progress indicator.

Here is the caller graph for this function:

◆ shutdownRequested()

virtual bool interfaces::Chain::shutdownRequested ( )

pure virtual

Check if shutdown requested.

◆ updateRwSetting()

virtual bool interfaces::Chain::updateRwSetting	(	const std::string &	name,
		const util::SettingsValue &	value,
		bool	write = `true`
	)

pure virtual

Write a setting to <datadir>/settings.json.

Optionally just update the setting in memory and do not write the file.

Here is the caller graph for this function:

◆ waitForNotificationsIfTipChanged()

virtual void interfaces::Chain::waitForNotificationsIfTipChanged ( const BlockHash & 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

◆ broadcastTransaction()

◆ estimateFee()

◆ findAncestorByHash()

◆ findAncestorByHeight()

◆ findBlock()

◆ findCoins()

◆ findCommonAncestor()

◆ findFirstBlockWithTimeAndHeight()

◆ findLocatorFork()

◆ getBlockHash()

◆ getHeight()

◆ getRwSetting()

◆ getSetting()

◆ getSettingsList()

◆ getTipLocator()

◆ guessVerificationProgress()

◆ handleNotifications()

◆ handleRpc()

◆ hasBlocks()

◆ haveBlockOnDisk()

◆ havePruned()

◆ initError()

◆ initMessage()

◆ initWarning()

◆ isInitialBlockDownload()

◆ isReadyToBroadcast()

◆ params()

◆ relayDustFee()

◆ relayMinFee()

◆ requestMempoolTransactions()

◆ rpcEnableDeprecated()

◆ rpcRunLater()

◆ rpcSerializationFlags()

◆ showProgress()

◆ shutdownRequested()

◆ updateRwSetting()

◆ waitForNotificationsIfTipChanged()