Bitcoin Core  27.99.0
P2P Digital Currency
Classes | Public Member Functions | List of all members
interfaces::Chain Class Referenceabstract

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, nullopt if chain does not contain any blocks) More...
 
virtual uint256 getBlockHash (int height)=0
 Get block hash. Height must be valid or this function will abort. More...
 
virtual bool haveBlockOnDisk (int height)=0
 Check that the block is available on disk (i.e. More...
 
virtual CBlockLocator getTipLocator ()=0
 Get locator for the current chain tip. More...
 
virtual CBlockLocator getActiveChainLocator (const uint256 &block_hash)=0
 Return a locator that refers to a block in the active chain. More...
 
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. More...
 
virtual bool hasBlockFilterIndex (BlockFilterType filter_type)=0
 Returns whether a block filter index is available. More...
 
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 block filter for this block couldn't be found. More...
 
virtual bool findBlock (const uint256 &hash, const FoundBlock &block={})=0
 Return whether node has the block and optionally return block metadata or contents. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
virtual void findCoins (std::map< COutPoint, Coin > &coins)=0
 Look up unspent output information. More...
 
virtual double guessVerificationProgress (const uint256 &block_hash)=0
 Estimate fraction of total transactions verified if blocks up to the specified block hash are verified. More...
 
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. More...
 
virtual RBFTransactionState isRBFOptIn (const CTransaction &tx)=0
 Check if transaction is RBF opt in. More...
 
virtual bool isInMempool (const uint256 &txid)=0
 Check if transaction is in mempool. More...
 
virtual bool hasDescendantsInMempool (const uint256 &txid)=0
 Check if transaction has descendants in mempool. More...
 
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_fee, and broadcast to all peers if relay is set to true. More...
 
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. More...
 
virtual std::map< COutPoint, CAmountcalculateIndividualBumpFees (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. More...
 
virtual std::optional< CAmountcalculateCombinedBumpFee (const std::vector< COutPoint > &outpoints, const CFeeRate &target_feerate)=0
 Calculate the combined bump fee for an input set per the same strategy. More...
 
virtual void getPackageLimits (unsigned int &limit_ancestor_count, unsigned int &limit_descendant_count)=0
 Get the node's package limits. More...
 
virtual util::Result< void > checkChainLimits (const CTransactionRef &tx)=0
 Check if transaction will pass the mempool's chain limits. More...
 
virtual CFeeRate estimateSmartFee (int num_blocks, bool conservative, FeeCalculation *calc=nullptr)=0
 Estimate smart fee. More...
 
virtual unsigned int estimateMaxBlocks ()=0
 Fee estimator max target. More...
 
virtual CFeeRate mempoolMinFee ()=0
 Mempool minimum fee. More...
 
virtual CFeeRate relayMinFee ()=0
 Relay current minimum fee (from -minrelaytxfee and -incrementalrelayfee settings). More...
 
virtual CFeeRate relayIncrementalFee ()=0
 Relay incremental fee setting (-incrementalrelayfee), reflecting cost of relay. More...
 
virtual CFeeRate relayDustFee ()=0
 Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend. More...
 
virtual bool havePruned ()=0
 Check if any block has been pruned. More...
 
virtual bool isReadyToBroadcast ()=0
 Check if the node is ready to broadcast transactions. More...
 
virtual bool isInitialBlockDownload ()=0
 Check if in IBD. More...
 
virtual bool shutdownRequested ()=0
 Check if shutdown requested. More...
 
virtual void initMessage (const std::string &message)=0
 Send init message. More...
 
virtual void initWarning (const bilingual_str &message)=0
 Send init warning. More...
 
virtual void initError (const bilingual_str &message)=0
 Send init error. More...
 
virtual void showProgress (const std::string &title, int progress, bool resume_possible)=0
 Send progress indicator. More...
 
virtual std::unique_ptr< HandlerhandleNotifications (std::shared_ptr< Notifications > notifications)=0
 Register handler for notifications. More...
 
virtual void waitForNotificationsIfTipChanged (const uint256 &old_tip)=0
 Wait for pending notifications to be processed unless block hash points to the current chain tip. More...
 
virtual std::unique_ptr< HandlerhandleRpc (const CRPCCommand &command)=0
 Register handler for RPC. More...
 
virtual bool rpcEnableDeprecated (const std::string &method)=0
 Check if deprecated RPC is enabled. More...
 
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. More...
 
virtual common::SettingsValue getSetting (const std::string &arg)=0
 Get settings value. More...
 
virtual std::vector< common::SettingsValuegetSettingsList (const std::string &arg)=0
 Get list of settings values. More...
 
virtual common::SettingsValue getRwSetting (const std::string &name)=0
 Return <datadir>/settings.json setting value. More...
 
virtual bool updateRwSetting (const std::string &name, const common::SettingsValue &value, bool write=true)=0
 Write a setting to <datadir>/settings.json. More...
 
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. More...
 
virtual bool hasAssumedValidChain ()=0
 Return true if an assumed-valid chain is in use. More...
 
virtual node::NodeContextcontext ()
 Get internal node context. More...
 

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:

Definition at line 123 of file chain.h.

Constructor & Destructor Documentation

◆ ~Chain()

virtual interfaces::Chain::~Chain ( )
inlinevirtual

Definition at line 126 of file chain.h.

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,
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:

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

Here is the caller graph for this function:

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

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

Here is the caller graph for this function:

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

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.

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

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:

◆ getActiveChainLocator()

virtual CBlockLocator interfaces::Chain::getActiveChainLocator ( const uint256 block_hash)
pure virtual

Return a locator that refers to a block in the active chain.

If specified block is not in the active chain, return locator for the latest ancestor that is in the chain.

Here is the caller graph for this function:

◆ getBlockHash()

virtual uint256 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, nullopt if chain does not contain any blocks)

Here is the caller graph for this function:

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

◆ getRwSetting()

virtual common::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 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.

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:

◆ getTransactionAncestry()

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

Calculate mempool ancestor and descendant 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.

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.

◆ 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 chain is in use.

Here is the caller graph for this function:

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

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.

Here is the caller graph for this function:

◆ isInMempool()

virtual bool interfaces::Chain::isInMempool ( const uint256 txid)
pure virtual

Check if transaction is in mempool.

Here is the caller graph for this function:

◆ isRBFOptIn()

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

Check if transaction is RBF opt in.

Here is the caller graph for this function:

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

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

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.

◆ rpcEnableDeprecated()

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

Check if deprecated RPC is enabled.

Here is the caller graph for this function:

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

◆ 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 common::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 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: