LCOV - code coverage report
Current view: top level - src/interfaces - chain.h (source / functions) Hit Total Coverage
Test: fuzz_coverage.info Lines: 1 38 2.6 %
Date: 2023-10-05 12:38:51 Functions: 2 27 7.4 %
Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : // Copyright (c) 2018-2022 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>
      10                 :            : #include <primitives/transaction.h> // For CTransactionRef
      11                 :            : 
      12                 :            : #include <functional>
      13                 :            : #include <memory>
      14                 :            : #include <optional>
      15                 :            : #include <stddef.h>
      16                 :            : #include <stdint.h>
      17                 :            : #include <string>
      18                 :            : #include <vector>
      19                 :            : 
      20                 :            : class ArgsManager;
      21                 :            : class CBlock;
      22                 :            : class CBlockUndo;
      23                 :            : class CFeeRate;
      24                 :            : class CRPCCommand;
      25                 :            : class CScheduler;
      26                 :            : class Coin;
      27                 :            : class uint256;
      28                 :            : enum class MemPoolRemovalReason;
      29                 :            : enum class RBFTransactionState;
      30                 :            : enum class ChainstateRole;
      31                 :            : struct bilingual_str;
      32                 :            : struct CBlockLocator;
      33                 :            : struct FeeCalculation;
      34                 :            : namespace node {
      35                 :            : struct NodeContext;
      36                 :            : } // namespace node
      37                 :            : 
      38                 :            : namespace interfaces {
      39                 :            : 
      40                 :            : class Handler;
      41                 :            : class Wallet;
      42                 :            : 
      43                 :            : //! Hash/height pair to help track and identify blocks.
      44                 :            : struct BlockKey {
      45                 :            :     uint256 hash;
      46                 :            :     int height = -1;
      47                 :            : };
      48                 :            : 
      49                 :            : //! Helper for findBlock to selectively return pieces of block data. If block is
      50                 :            : //! found, data will be returned by setting specified output variables. If block
      51                 :            : //! is not found, output variables will keep their previous values.
      52                 :          0 : class FoundBlock
      53                 :            : {
      54                 :            : public:
      55                 :          0 :     FoundBlock& hash(uint256& hash) { m_hash = &hash; return *this; }
      56                 :          0 :     FoundBlock& height(int& height) { m_height = &height; return *this; }
      57                 :          0 :     FoundBlock& time(int64_t& time) { m_time = &time; return *this; }
      58                 :          0 :     FoundBlock& maxTime(int64_t& max_time) { m_max_time = &max_time; return *this; }
      59                 :          0 :     FoundBlock& mtpTime(int64_t& mtp_time) { m_mtp_time = &mtp_time; return *this; }
      60                 :            :     //! Return whether block is in the active (most-work) chain.
      61                 :          0 :     FoundBlock& inActiveChain(bool& in_active_chain) { m_in_active_chain = &in_active_chain; return *this; }
      62                 :            :     //! Return locator if block is in the active chain.
      63                 :          0 :     FoundBlock& locator(CBlockLocator& locator) { m_locator = &locator; return *this; }
      64                 :            :     //! Return next block in the active chain if current block is in the active chain.
      65                 :          0 :     FoundBlock& nextBlock(const FoundBlock& next_block) { m_next_block = &next_block; return *this; }
      66                 :            :     //! Read block data from disk. If the block exists but doesn't have data
      67                 :            :     //! (for example due to pruning), the CBlock variable will be set to null.
      68                 :          0 :     FoundBlock& data(CBlock& data) { m_data = &data; return *this; }
      69                 :            : 
      70                 :          0 :     uint256* m_hash = nullptr;
      71                 :          0 :     int* m_height = nullptr;
      72                 :          0 :     int64_t* m_time = nullptr;
      73                 :          0 :     int64_t* m_max_time = nullptr;
      74                 :          0 :     int64_t* m_mtp_time = nullptr;
      75                 :          0 :     bool* m_in_active_chain = nullptr;
      76                 :          0 :     CBlockLocator* m_locator = nullptr;
      77                 :          0 :     const FoundBlock* m_next_block = nullptr;
      78                 :          0 :     CBlock* m_data = nullptr;
      79                 :          0 :     mutable bool found = false;
      80                 :            : };
      81                 :            : 
      82                 :            : //! Block data sent with blockConnected, blockDisconnected notifications.
      83                 :            : struct BlockInfo {
      84                 :            :     const uint256& hash;
      85                 :          0 :     const uint256* prev_hash = nullptr;
      86                 :          0 :     int height = -1;
      87                 :          0 :     int file_number = -1;
      88                 :          0 :     unsigned data_pos = 0;
      89                 :          0 :     const CBlock* data = nullptr;
      90                 :          0 :     const CBlockUndo* undo_data = nullptr;
      91                 :            :     // The maximum time in the chain up to and including this block.
      92                 :            :     // A timestamp that can only move forward.
      93                 :          0 :     unsigned int chain_time_max{0};
      94                 :            : 
      95                 :          0 :     BlockInfo(const uint256& hash LIFETIMEBOUND) : hash(hash) {}
      96                 :            : };
      97                 :            : 
      98                 :            : //! Interface giving clients (wallet processes, maybe other analysis tools in
      99                 :            : //! the future) ability to access to the chain state, receive notifications,
     100                 :            : //! estimate fees, and submit transactions.
     101                 :            : //!
     102                 :            : //! TODO: Current chain methods are too low level, exposing too much of the
     103                 :            : //! internal workings of the bitcoin node, and not being very convenient to use.
     104                 :            : //! Chain methods should be cleaned up and simplified over time. Examples:
     105                 :            : //!
     106                 :            : //! * The initMessages() and showProgress() methods which the wallet uses to send
     107                 :            : //!   notifications to the GUI should go away when GUI and wallet can directly
     108                 :            : //!   communicate with each other without going through the node
     109                 :            : //!   (https://github.com/bitcoin/bitcoin/pull/15288#discussion_r253321096).
     110                 :            : //!
     111                 :            : //! * The handleRpc, registerRpcs, rpcEnableDeprecated methods and other RPC
     112                 :            : //!   methods can go away if wallets listen for HTTP requests on their own
     113                 :            : //!   ports instead of registering to handle requests on the node HTTP port.
     114                 :            : //!
     115                 :            : //! * Move fee estimation queries to an asynchronous interface and let the
     116                 :            : //!   wallet cache it, fee estimation being driven by node mempool, wallet
     117                 :            : //!   should be the consumer.
     118                 :            : //!
     119                 :            : //! * `guessVerificationProgress` and similar methods can go away if rescan
     120                 :            : //!   logic moves out of the wallet, and the wallet just requests scans from the
     121                 :            : //!   node (https://github.com/bitcoin/bitcoin/issues/11756)
     122                 :            : class Chain
     123                 :            : {
     124                 :            : public:
     125                 :          1 :     virtual ~Chain() {}
     126                 :            : 
     127                 :            :     //! Get current chain height, not including genesis block (returns 0 if
     128                 :            :     //! chain only contains genesis block, nullopt if chain does not contain
     129                 :            :     //! any blocks)
     130                 :            :     virtual std::optional<int> getHeight() = 0;
     131                 :            : 
     132                 :            :     //! Get block hash. Height must be valid or this function will abort.
     133                 :            :     virtual uint256 getBlockHash(int height) = 0;
     134                 :            : 
     135                 :            :     //! Check that the block is available on disk (i.e. has not been
     136                 :            :     //! pruned), and contains transactions.
     137                 :            :     virtual bool haveBlockOnDisk(int height) = 0;
     138                 :            : 
     139                 :            :     //! Get locator for the current chain tip.
     140                 :            :     virtual CBlockLocator getTipLocator() = 0;
     141                 :            : 
     142                 :            :     //! Return a locator that refers to a block in the active chain.
     143                 :            :     //! If specified block is not in the active chain, return locator for the latest ancestor that is in the chain.
     144                 :            :     virtual CBlockLocator getActiveChainLocator(const uint256& block_hash) = 0;
     145                 :            : 
     146                 :            :     //! Return height of the highest block on chain in common with the locator,
     147                 :            :     //! which will either be the original block used to create the locator,
     148                 :            :     //! or one of its ancestors.
     149                 :            :     virtual std::optional<int> findLocatorFork(const CBlockLocator& locator) = 0;
     150                 :            : 
     151                 :            :     //! Returns whether a block filter index is available.
     152                 :            :     virtual bool hasBlockFilterIndex(BlockFilterType filter_type) = 0;
     153                 :            : 
     154                 :            :     //! Returns whether any of the elements match the block via a BIP 157 block filter
     155                 :            :     //! or std::nullopt if the block filter for this block couldn't be found.
     156                 :            :     virtual std::optional<bool> blockFilterMatchesAny(BlockFilterType filter_type, const uint256& block_hash, const GCSFilter::ElementSet& filter_set) = 0;
     157                 :            : 
     158                 :            :     //! Return whether node has the block and optionally return block metadata
     159                 :            :     //! or contents.
     160                 :            :     virtual bool findBlock(const uint256& hash, const FoundBlock& block={}) = 0;
     161                 :            : 
     162                 :            :     //! Find first block in the chain with timestamp >= the given time
     163                 :            :     //! and height >= than the given height, return false if there is no block
     164                 :            :     //! with a high enough timestamp and height. Optionally return block
     165                 :            :     //! information.
     166                 :            :     virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock& block={}) = 0;
     167                 :            : 
     168                 :            :     //! Find ancestor of block at specified height and optionally return
     169                 :            :     //! ancestor information.
     170                 :            :     virtual bool findAncestorByHeight(const uint256& block_hash, int ancestor_height, const FoundBlock& ancestor_out={}) = 0;
     171                 :            : 
     172                 :            :     //! Return whether block descends from a specified ancestor, and
     173                 :            :     //! optionally return ancestor information.
     174                 :            :     virtual bool findAncestorByHash(const uint256& block_hash,
     175                 :            :         const uint256& ancestor_hash,
     176                 :            :         const FoundBlock& ancestor_out={}) = 0;
     177                 :            : 
     178                 :            :     //! Find most recent common ancestor between two blocks and optionally
     179                 :            :     //! return block information.
     180                 :            :     virtual bool findCommonAncestor(const uint256& block_hash1,
     181                 :            :         const uint256& block_hash2,
     182                 :            :         const FoundBlock& ancestor_out={},
     183                 :            :         const FoundBlock& block1_out={},
     184                 :            :         const FoundBlock& block2_out={}) = 0;
     185                 :            : 
     186                 :            :     //! Look up unspent output information. Returns coins in the mempool and in
     187                 :            :     //! the current chain UTXO set. Iterates through all the keys in the map and
     188                 :            :     //! populates the values.
     189                 :            :     virtual void findCoins(std::map<COutPoint, Coin>& coins) = 0;
     190                 :            : 
     191                 :            :     //! Estimate fraction of total transactions verified if blocks up to
     192                 :            :     //! the specified block hash are verified.
     193                 :            :     virtual double guessVerificationProgress(const uint256& block_hash) = 0;
     194                 :            : 
     195                 :            :     //! Return true if data is available for all blocks in the specified range
     196                 :            :     //! of blocks. This checks all blocks that are ancestors of block_hash in
     197                 :            :     //! the height range from min_height to max_height, inclusive.
     198                 :            :     virtual bool hasBlocks(const uint256& block_hash, int min_height = 0, std::optional<int> max_height = {}) = 0;
     199                 :            : 
     200                 :            :     //! Check if transaction is RBF opt in.
     201                 :            :     virtual RBFTransactionState isRBFOptIn(const CTransaction& tx) = 0;
     202                 :            : 
     203                 :            :     //! Check if transaction is in mempool.
     204                 :            :     virtual bool isInMempool(const uint256& txid) = 0;
     205                 :            : 
     206                 :            :     //! Check if transaction has descendants in mempool.
     207                 :            :     virtual bool hasDescendantsInMempool(const uint256& txid) = 0;
     208                 :            : 
     209                 :            :     //! Transaction is added to memory pool, if the transaction fee is below the
     210                 :            :     //! amount specified by max_tx_fee, and broadcast to all peers if relay is set to true.
     211                 :            :     //! Return false if the transaction could not be added due to the fee or for another reason.
     212                 :            :     virtual bool broadcastTransaction(const CTransactionRef& tx,
     213                 :            :         const CAmount& max_tx_fee,
     214                 :            :         bool relay,
     215                 :            :         std::string& err_string) = 0;
     216                 :            : 
     217                 :            :     //! Calculate mempool ancestor and descendant counts for the given transaction.
     218                 :            :     virtual void getTransactionAncestry(const uint256& txid, size_t& ancestors, size_t& descendants, size_t* ancestorsize = nullptr, CAmount* ancestorfees = nullptr) = 0;
     219                 :            : 
     220                 :            :     //! For each outpoint, calculate the fee-bumping cost to spend this outpoint at the specified
     221                 :            :     //  feerate, including bumping its ancestors. For example, if the target feerate is 10sat/vbyte
     222                 :            :     //  and this outpoint refers to a mempool transaction at 3sat/vbyte, the bump fee includes the
     223                 :            :     //  cost to bump the mempool transaction to 10sat/vbyte (i.e. 7 * mempooltx.vsize). If that
     224                 :            :     //  transaction also has, say, an unconfirmed parent with a feerate of 1sat/vbyte, the bump fee
     225                 :            :     //  includes the cost to bump the parent (i.e. 9 * parentmempooltx.vsize).
     226                 :            :     //
     227                 :            :     //  If the outpoint comes from an unconfirmed transaction that is already above the target
     228                 :            :     //  feerate or bumped by its descendant(s) already, it does not need to be bumped. Its bump fee
     229                 :            :     //  is 0. Likewise, if any of the transaction's ancestors are already bumped by a transaction
     230                 :            :     //  in our mempool, they are not included in the transaction's bump fee.
     231                 :            :     //
     232                 :            :     //  Also supported is bump-fee calculation in the case of replacements. If an outpoint
     233                 :            :     //  conflicts with another transaction in the mempool, it is assumed that the goal is to replace
     234                 :            :     //  that transaction. As such, the calculation will exclude the to-be-replaced transaction, but
     235                 :            :     //  will include the fee-bumping cost. If bump fees of descendants of the to-be-replaced
     236                 :            :     //  transaction are requested, the value will be 0. Fee-related RBF rules are not included as
     237                 :            :     //  they are logically distinct.
     238                 :            :     //
     239                 :            :     //  Any outpoints that are otherwise unavailable from the mempool (e.g. UTXOs from confirmed
     240                 :            :     //  transactions or transactions not yet broadcast by the wallet) are given a bump fee of 0.
     241                 :            :     //
     242                 :            :     //  If multiple outpoints come from the same transaction (which would be very rare because
     243                 :            :     //  it means that one transaction has multiple change outputs or paid the same wallet using multiple
     244                 :            :     //  outputs in the same transaction) or have shared ancestry, the bump fees are calculated
     245                 :            :     //  independently, i.e. as if only one of them is spent. This may result in double-fee-bumping. This
     246                 :            :     //  caveat can be rectified per use of the sister-function CalculateCombinedBumpFee(…).
     247                 :            :     virtual std::map<COutPoint, CAmount> CalculateIndividualBumpFees(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
     248                 :            : 
     249                 :            :     //! Calculate the combined bump fee for an input set per the same strategy
     250                 :            :     //  as in CalculateIndividualBumpFees(…).
     251                 :            :     //  Unlike CalculateIndividualBumpFees(…), this does not return individual
     252                 :            :     //  bump fees per outpoint, but a single bump fee for the shared ancestry.
     253                 :            :     //  The combined bump fee may be used to correct overestimation due to
     254                 :            :     //  shared ancestry by multiple UTXOs after coin selection.
     255                 :            :     virtual std::optional<CAmount> CalculateCombinedBumpFee(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
     256                 :            : 
     257                 :            :     //! Get the node's package limits.
     258                 :            :     //! Currently only returns the ancestor and descendant count limits, but could be enhanced to
     259                 :            :     //! return more policy settings.
     260                 :            :     virtual void getPackageLimits(unsigned int& limit_ancestor_count, unsigned int& limit_descendant_count) = 0;
     261                 :            : 
     262                 :            :     //! Check if transaction will pass the mempool's chain limits.
     263                 :            :     virtual bool checkChainLimits(const CTransactionRef& tx) = 0;
     264                 :            : 
     265                 :            :     //! Estimate smart fee.
     266                 :            :     virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation* calc = nullptr) = 0;
     267                 :            : 
     268                 :            :     //! Fee estimator max target.
     269                 :            :     virtual unsigned int estimateMaxBlocks() = 0;
     270                 :            : 
     271                 :            :     //! Mempool minimum fee.
     272                 :            :     virtual CFeeRate mempoolMinFee() = 0;
     273                 :            : 
     274                 :            :     //! Relay current minimum fee (from -minrelaytxfee and -incrementalrelayfee settings).
     275                 :            :     virtual CFeeRate relayMinFee() = 0;
     276                 :            : 
     277                 :            :     //! Relay incremental fee setting (-incrementalrelayfee), reflecting cost of relay.
     278                 :            :     virtual CFeeRate relayIncrementalFee() = 0;
     279                 :            : 
     280                 :            :     //! Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend.
     281                 :            :     virtual CFeeRate relayDustFee() = 0;
     282                 :            : 
     283                 :            :     //! Check if any block has been pruned.
     284                 :            :     virtual bool havePruned() = 0;
     285                 :            : 
     286                 :            :     //! Check if the node is ready to broadcast transactions.
     287                 :            :     virtual bool isReadyToBroadcast() = 0;
     288                 :            : 
     289                 :            :     //! Check if in IBD.
     290                 :            :     virtual bool isInitialBlockDownload() = 0;
     291                 :            : 
     292                 :            :     //! Check if shutdown requested.
     293                 :            :     virtual bool shutdownRequested() = 0;
     294                 :            : 
     295                 :            :     //! Send init message.
     296                 :            :     virtual void initMessage(const std::string& message) = 0;
     297                 :            : 
     298                 :            :     //! Send init warning.
     299                 :            :     virtual void initWarning(const bilingual_str& message) = 0;
     300                 :            : 
     301                 :            :     //! Send init error.
     302                 :            :     virtual void initError(const bilingual_str& message) = 0;
     303                 :            : 
     304                 :            :     //! Send progress indicator.
     305                 :            :     virtual void showProgress(const std::string& title, int progress, bool resume_possible) = 0;
     306                 :            : 
     307                 :            :     //! Chain notifications.
     308                 :            :     class Notifications
     309                 :            :     {
     310                 :            :     public:
     311                 :          0 :         virtual ~Notifications() {}
     312                 :          0 :         virtual void transactionAddedToMempool(const CTransactionRef& tx) {}
     313                 :          0 :         virtual void transactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason) {}
     314                 :          0 :         virtual void blockConnected(ChainstateRole role, const BlockInfo& block) {}
     315                 :          0 :         virtual void blockDisconnected(const BlockInfo& block) {}
     316                 :          0 :         virtual void updatedBlockTip() {}
     317                 :          0 :         virtual void chainStateFlushed(ChainstateRole role, const CBlockLocator& locator) {}
     318                 :            :     };
     319                 :            : 
     320                 :            :     //! Register handler for notifications.
     321                 :            :     virtual std::unique_ptr<Handler> handleNotifications(std::shared_ptr<Notifications> notifications) = 0;
     322                 :            : 
     323                 :            :     //! Wait for pending notifications to be processed unless block hash points to the current
     324                 :            :     //! chain tip.
     325                 :            :     virtual void waitForNotificationsIfTipChanged(const uint256& old_tip) = 0;
     326                 :            : 
     327                 :            :     //! Register handler for RPC. Command is not copied, so reference
     328                 :            :     //! needs to remain valid until Handler is disconnected.
     329                 :            :     virtual std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) = 0;
     330                 :            : 
     331                 :            :     //! Check if deprecated RPC is enabled.
     332                 :            :     virtual bool rpcEnableDeprecated(const std::string& method) = 0;
     333                 :            : 
     334                 :            :     //! Run function after given number of seconds. Cancel any previous calls with same name.
     335                 :            :     virtual void rpcRunLater(const std::string& name, std::function<void()> fn, int64_t seconds) = 0;
     336                 :            : 
     337                 :            :     //! Current RPC serialization flags.
     338                 :            :     virtual int rpcSerializationFlags() = 0;
     339                 :            : 
     340                 :            :     //! Get settings value.
     341                 :            :     virtual common::SettingsValue getSetting(const std::string& arg) = 0;
     342                 :            : 
     343                 :            :     //! Get list of settings values.
     344                 :            :     virtual std::vector<common::SettingsValue> getSettingsList(const std::string& arg) = 0;
     345                 :            : 
     346                 :            :     //! Return <datadir>/settings.json setting value.
     347                 :            :     virtual common::SettingsValue getRwSetting(const std::string& name) = 0;
     348                 :            : 
     349                 :            :     //! Write a setting to <datadir>/settings.json. Optionally just update the
     350                 :            :     //! setting in memory and do not write the file.
     351                 :            :     virtual bool updateRwSetting(const std::string& name, const common::SettingsValue& value, bool write=true) = 0;
     352                 :            : 
     353                 :            :     //! Synchronously send transactionAddedToMempool notifications about all
     354                 :            :     //! current mempool transactions to the specified handler and return after
     355                 :            :     //! the last one is sent. These notifications aren't coordinated with async
     356                 :            :     //! notifications sent by handleNotifications, so out of date async
     357                 :            :     //! notifications from handleNotifications can arrive during and after
     358                 :            :     //! synchronous notifications from requestMempoolTransactions. Clients need
     359                 :            :     //! to be prepared to handle this by ignoring notifications about unknown
     360                 :            :     //! removed transactions and already added new transactions.
     361                 :            :     virtual void requestMempoolTransactions(Notifications& notifications) = 0;
     362                 :            : 
     363                 :            :     //! Return true if an assumed-valid chain is in use.
     364                 :            :     virtual bool hasAssumedValidChain() = 0;
     365                 :            : 
     366                 :            :     //! Get internal node context. Useful for testing, but not
     367                 :            :     //! accessible across processes.
     368                 :          0 :     virtual node::NodeContext* context() { return nullptr; }
     369                 :            : };
     370                 :            : 
     371                 :            : //! Interface to let node manage chain clients (wallets, or maybe tools for
     372                 :            : //! monitoring and analysis in the future).
     373                 :            : class ChainClient
     374                 :            : {
     375                 :            : public:
     376                 :          0 :     virtual ~ChainClient() {}
     377                 :            : 
     378                 :            :     //! Register rpcs.
     379                 :            :     virtual void registerRpcs() = 0;
     380                 :            : 
     381                 :            :     //! Check for errors before loading.
     382                 :            :     virtual bool verify() = 0;
     383                 :            : 
     384                 :            :     //! Load saved state.
     385                 :            :     virtual bool load() = 0;
     386                 :            : 
     387                 :            :     //! Start client execution and provide a scheduler.
     388                 :            :     virtual void start(CScheduler& scheduler) = 0;
     389                 :            : 
     390                 :            :     //! Save state to disk.
     391                 :            :     virtual void flush() = 0;
     392                 :            : 
     393                 :            :     //! Shut down client.
     394                 :            :     virtual void stop() = 0;
     395                 :            : 
     396                 :            :     //! Set mock time.
     397                 :            :     virtual void setMockTime(int64_t time) = 0;
     398                 :            : };
     399                 :            : 
     400                 :            : //! Return implementation of Chain interface.
     401                 :            : std::unique_ptr<Chain> MakeChain(node::NodeContext& node);
     402                 :            : 
     403                 :            : } // namespace interfaces
     404                 :            : 
     405                 :            : #endif // BITCOIN_INTERFACES_CHAIN_H

Generated by: LCOV version 1.14