Branch data Line data Source code
# 1 : : // Copyright (c) 2018-2021 The Bitcoin Core developers
# 2 : : // Distributed under the MIT software license, see the accompanying
# 3 : : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
# 4 : :
# 5 : : #ifndef BITCOIN_INTERFACES_CHAIN_H
# 6 : : #define BITCOIN_INTERFACES_CHAIN_H
# 7 : :
# 8 : : #include <primitives/transaction.h> // For CTransactionRef
# 9 : : #include <util/settings.h> // For util::SettingsValue
# 10 : :
# 11 : : #include <functional>
# 12 : : #include <memory>
# 13 : : #include <optional>
# 14 : : #include <stddef.h>
# 15 : : #include <stdint.h>
# 16 : : #include <string>
# 17 : : #include <vector>
# 18 : :
# 19 : : class ArgsManager;
# 20 : : class CBlock;
# 21 : : class CFeeRate;
# 22 : : class CRPCCommand;
# 23 : : class CScheduler;
# 24 : : class Coin;
# 25 : : class uint256;
# 26 : : enum class MemPoolRemovalReason;
# 27 : : enum class RBFTransactionState;
# 28 : : struct bilingual_str;
# 29 : : struct CBlockLocator;
# 30 : : struct FeeCalculation;
# 31 : : namespace node {
# 32 : : struct NodeContext;
# 33 : : } // namespace node
# 34 : :
# 35 : : namespace interfaces {
# 36 : :
# 37 : : class Handler;
# 38 : : class Wallet;
# 39 : :
# 40 : : //! Helper for findBlock to selectively return pieces of block data. If block is
# 41 : : //! found, data will be returned by setting specified output variables. If block
# 42 : : //! is not found, output variables will keep their previous values.
# 43 : : class FoundBlock
# 44 : : {
# 45 : : public:
# 46 : 99520 : FoundBlock& hash(uint256& hash) { m_hash = &hash; return *this; }
# 47 : 10982 : FoundBlock& height(int& height) { m_height = &height; return *this; }
# 48 : 29257 : FoundBlock& time(int64_t& time) { m_time = &time; return *this; }
# 49 : 20394 : FoundBlock& maxTime(int64_t& max_time) { m_max_time = &max_time; return *this; }
# 50 : 577 : FoundBlock& mtpTime(int64_t& mtp_time) { m_mtp_time = &mtp_time; return *this; }
# 51 : : //! Return whether block is in the active (most-work) chain.
# 52 : 207532 : FoundBlock& inActiveChain(bool& in_active_chain) { m_in_active_chain = &in_active_chain; return *this; }
# 53 : : //! Return next block in the active chain if current block is in the active chain.
# 54 : 98718 : FoundBlock& nextBlock(const FoundBlock& next_block) { m_next_block = &next_block; return *this; }
# 55 : : //! Read block data from disk. If the block exists but doesn't have data
# 56 : : //! (for example due to pruning), the CBlock variable will be set to null.
# 57 : 98740 : FoundBlock& data(CBlock& data) { m_data = &data; return *this; }
# 58 : :
# 59 : : uint256* m_hash = nullptr;
# 60 : : int* m_height = nullptr;
# 61 : : int64_t* m_time = nullptr;
# 62 : : int64_t* m_max_time = nullptr;
# 63 : : int64_t* m_mtp_time = nullptr;
# 64 : : bool* m_in_active_chain = nullptr;
# 65 : : const FoundBlock* m_next_block = nullptr;
# 66 : : CBlock* m_data = nullptr;
# 67 : : mutable bool found = false;
# 68 : : };
# 69 : :
# 70 : : //! Interface giving clients (wallet processes, maybe other analysis tools in
# 71 : : //! the future) ability to access to the chain state, receive notifications,
# 72 : : //! estimate fees, and submit transactions.
# 73 : : //!
# 74 : : //! TODO: Current chain methods are too low level, exposing too much of the
# 75 : : //! internal workings of the bitcoin node, and not being very convenient to use.
# 76 : : //! Chain methods should be cleaned up and simplified over time. Examples:
# 77 : : //!
# 78 : : //! * The initMessages() and showProgress() methods which the wallet uses to send
# 79 : : //! notifications to the GUI should go away when GUI and wallet can directly
# 80 : : //! communicate with each other without going through the node
# 81 : : //! (https://github.com/bitcoin/bitcoin/pull/15288#discussion_r253321096).
# 82 : : //!
# 83 : : //! * The handleRpc, registerRpcs, rpcEnableDeprecated methods and other RPC
# 84 : : //! methods can go away if wallets listen for HTTP requests on their own
# 85 : : //! ports instead of registering to handle requests on the node HTTP port.
# 86 : : //!
# 87 : : //! * Move fee estimation queries to an asynchronous interface and let the
# 88 : : //! wallet cache it, fee estimation being driven by node mempool, wallet
# 89 : : //! should be the consumer.
# 90 : : //!
# 91 : : //! * `guessVerificationProgress` and similar methods can go away if rescan
# 92 : : //! logic moves out of the wallet, and the wallet just requests scans from the
# 93 : : //! node (https://github.com/bitcoin/bitcoin/issues/11756)
# 94 : : class Chain
# 95 : : {
# 96 : : public:
# 97 : 1630 : virtual ~Chain() {}
# 98 : :
# 99 : : //! Get current chain height, not including genesis block (returns 0 if
# 100 : : //! chain only contains genesis block, nullopt if chain does not contain
# 101 : : //! any blocks)
# 102 : : virtual std::optional<int> getHeight() = 0;
# 103 : :
# 104 : : //! Get block hash. Height must be valid or this function will abort.
# 105 : : virtual uint256 getBlockHash(int height) = 0;
# 106 : :
# 107 : : //! Check that the block is available on disk (i.e. has not been
# 108 : : //! pruned), and contains transactions.
# 109 : : virtual bool haveBlockOnDisk(int height) = 0;
# 110 : :
# 111 : : //! Get locator for the current chain tip.
# 112 : : virtual CBlockLocator getTipLocator() = 0;
# 113 : :
# 114 : : //! Return height of the highest block on chain in common with the locator,
# 115 : : //! which will either be the original block used to create the locator,
# 116 : : //! or one of its ancestors.
# 117 : : virtual std::optional<int> findLocatorFork(const CBlockLocator& locator) = 0;
# 118 : :
# 119 : : //! Return whether node has the block and optionally return block metadata
# 120 : : //! or contents.
# 121 : : virtual bool findBlock(const uint256& hash, const FoundBlock& block={}) = 0;
# 122 : :
# 123 : : //! Find first block in the chain with timestamp >= the given time
# 124 : : //! and height >= than the given height, return false if there is no block
# 125 : : //! with a high enough timestamp and height. Optionally return block
# 126 : : //! information.
# 127 : : virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock& block={}) = 0;
# 128 : :
# 129 : : //! Find ancestor of block at specified height and optionally return
# 130 : : //! ancestor information.
# 131 : : virtual bool findAncestorByHeight(const uint256& block_hash, int ancestor_height, const FoundBlock& ancestor_out={}) = 0;
# 132 : :
# 133 : : //! Return whether block descends from a specified ancestor, and
# 134 : : //! optionally return ancestor information.
# 135 : : virtual bool findAncestorByHash(const uint256& block_hash,
# 136 : : const uint256& ancestor_hash,
# 137 : : const FoundBlock& ancestor_out={}) = 0;
# 138 : :
# 139 : : //! Find most recent common ancestor between two blocks and optionally
# 140 : : //! return block information.
# 141 : : virtual bool findCommonAncestor(const uint256& block_hash1,
# 142 : : const uint256& block_hash2,
# 143 : : const FoundBlock& ancestor_out={},
# 144 : : const FoundBlock& block1_out={},
# 145 : : const FoundBlock& block2_out={}) = 0;
# 146 : :
# 147 : : //! Look up unspent output information. Returns coins in the mempool and in
# 148 : : //! the current chain UTXO set. Iterates through all the keys in the map and
# 149 : : //! populates the values.
# 150 : : virtual void findCoins(std::map<COutPoint, Coin>& coins) = 0;
# 151 : :
# 152 : : //! Estimate fraction of total transactions verified if blocks up to
# 153 : : //! the specified block hash are verified.
# 154 : : virtual double guessVerificationProgress(const uint256& block_hash) = 0;
# 155 : :
# 156 : : //! Return true if data is available for all blocks in the specified range
# 157 : : //! of blocks. This checks all blocks that are ancestors of block_hash in
# 158 : : //! the height range from min_height to max_height, inclusive.
# 159 : : virtual bool hasBlocks(const uint256& block_hash, int min_height = 0, std::optional<int> max_height = {}) = 0;
# 160 : :
# 161 : : //! Check if transaction is RBF opt in.
# 162 : : virtual RBFTransactionState isRBFOptIn(const CTransaction& tx) = 0;
# 163 : :
# 164 : : //! Check if transaction is in mempool.
# 165 : : virtual bool isInMempool(const uint256& txid) = 0;
# 166 : :
# 167 : : //! Check if transaction has descendants in mempool.
# 168 : : virtual bool hasDescendantsInMempool(const uint256& txid) = 0;
# 169 : :
# 170 : : //! Transaction is added to memory pool, if the transaction fee is below the
# 171 : : //! amount specified by max_tx_fee, and broadcast to all peers if relay is set to true.
# 172 : : //! Return false if the transaction could not be added due to the fee or for another reason.
# 173 : : virtual bool broadcastTransaction(const CTransactionRef& tx,
# 174 : : const CAmount& max_tx_fee,
# 175 : : bool relay,
# 176 : : std::string& err_string) = 0;
# 177 : :
# 178 : : //! Calculate mempool ancestor and descendant counts for the given transaction.
# 179 : : virtual void getTransactionAncestry(const uint256& txid, size_t& ancestors, size_t& descendants, size_t* ancestorsize = nullptr, CAmount* ancestorfees = nullptr) = 0;
# 180 : :
# 181 : : //! Get the node's package limits.
# 182 : : //! Currently only returns the ancestor and descendant count limits, but could be enhanced to
# 183 : : //! return more policy settings.
# 184 : : virtual void getPackageLimits(unsigned int& limit_ancestor_count, unsigned int& limit_descendant_count) = 0;
# 185 : :
# 186 : : //! Check if transaction will pass the mempool's chain limits.
# 187 : : virtual bool checkChainLimits(const CTransactionRef& tx) = 0;
# 188 : :
# 189 : : //! Estimate smart fee.
# 190 : : virtual CFeeRate estimateSmartFee(int num_blocks, bool conservative, FeeCalculation* calc = nullptr) = 0;
# 191 : :
# 192 : : //! Fee estimator max target.
# 193 : : virtual unsigned int estimateMaxBlocks() = 0;
# 194 : :
# 195 : : //! Mempool minimum fee.
# 196 : : virtual CFeeRate mempoolMinFee() = 0;
# 197 : :
# 198 : : //! Relay current minimum fee (from -minrelaytxfee and -incrementalrelayfee settings).
# 199 : : virtual CFeeRate relayMinFee() = 0;
# 200 : :
# 201 : : //! Relay incremental fee setting (-incrementalrelayfee), reflecting cost of relay.
# 202 : : virtual CFeeRate relayIncrementalFee() = 0;
# 203 : :
# 204 : : //! Relay dust fee setting (-dustrelayfee), reflecting lowest rate it's economical to spend.
# 205 : : virtual CFeeRate relayDustFee() = 0;
# 206 : :
# 207 : : //! Check if any block has been pruned.
# 208 : : virtual bool havePruned() = 0;
# 209 : :
# 210 : : //! Check if the node is ready to broadcast transactions.
# 211 : : virtual bool isReadyToBroadcast() = 0;
# 212 : :
# 213 : : //! Check if in IBD.
# 214 : : virtual bool isInitialBlockDownload() = 0;
# 215 : :
# 216 : : //! Check if shutdown requested.
# 217 : : virtual bool shutdownRequested() = 0;
# 218 : :
# 219 : : //! Send init message.
# 220 : : virtual void initMessage(const std::string& message) = 0;
# 221 : :
# 222 : : //! Send init warning.
# 223 : : virtual void initWarning(const bilingual_str& message) = 0;
# 224 : :
# 225 : : //! Send init error.
# 226 : : virtual void initError(const bilingual_str& message) = 0;
# 227 : :
# 228 : : //! Send progress indicator.
# 229 : : virtual void showProgress(const std::string& title, int progress, bool resume_possible) = 0;
# 230 : :
# 231 : : //! Chain notifications.
# 232 : : class Notifications
# 233 : : {
# 234 : : public:
# 235 : 876 : virtual ~Notifications() {}
# 236 : 0 : virtual void transactionAddedToMempool(const CTransactionRef& tx, uint64_t mempool_sequence) {}
# 237 : 0 : virtual void transactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason, uint64_t mempool_sequence) {}
# 238 : 0 : virtual void blockConnected(const CBlock& block, int height) {}
# 239 : 0 : virtual void blockDisconnected(const CBlock& block, int height) {}
# 240 : 0 : virtual void updatedBlockTip() {}
# 241 : 0 : virtual void chainStateFlushed(const CBlockLocator& locator) {}
# 242 : : };
# 243 : :
# 244 : : //! Register handler for notifications.
# 245 : : virtual std::unique_ptr<Handler> handleNotifications(std::shared_ptr<Notifications> notifications) = 0;
# 246 : :
# 247 : : //! Wait for pending notifications to be processed unless block hash points to the current
# 248 : : //! chain tip.
# 249 : : virtual void waitForNotificationsIfTipChanged(const uint256& old_tip) = 0;
# 250 : :
# 251 : : //! Register handler for RPC. Command is not copied, so reference
# 252 : : //! needs to remain valid until Handler is disconnected.
# 253 : : virtual std::unique_ptr<Handler> handleRpc(const CRPCCommand& command) = 0;
# 254 : :
# 255 : : //! Check if deprecated RPC is enabled.
# 256 : : virtual bool rpcEnableDeprecated(const std::string& method) = 0;
# 257 : :
# 258 : : //! Run function after given number of seconds. Cancel any previous calls with same name.
# 259 : : virtual void rpcRunLater(const std::string& name, std::function<void()> fn, int64_t seconds) = 0;
# 260 : :
# 261 : : //! Current RPC serialization flags.
# 262 : : virtual int rpcSerializationFlags() = 0;
# 263 : :
# 264 : : //! Get settings value.
# 265 : : virtual util::SettingsValue getSetting(const std::string& arg) = 0;
# 266 : :
# 267 : : //! Get list of settings values.
# 268 : : virtual std::vector<util::SettingsValue> getSettingsList(const std::string& arg) = 0;
# 269 : :
# 270 : : //! Return <datadir>/settings.json setting value.
# 271 : : virtual util::SettingsValue getRwSetting(const std::string& name) = 0;
# 272 : :
# 273 : : //! Write a setting to <datadir>/settings.json. Optionally just update the
# 274 : : //! setting in memory and do not write the file.
# 275 : : virtual bool updateRwSetting(const std::string& name, const util::SettingsValue& value, bool write=true) = 0;
# 276 : :
# 277 : : //! Synchronously send transactionAddedToMempool notifications about all
# 278 : : //! current mempool transactions to the specified handler and return after
# 279 : : //! the last one is sent. These notifications aren't coordinated with async
# 280 : : //! notifications sent by handleNotifications, so out of date async
# 281 : : //! notifications from handleNotifications can arrive during and after
# 282 : : //! synchronous notifications from requestMempoolTransactions. Clients need
# 283 : : //! to be prepared to handle this by ignoring notifications about unknown
# 284 : : //! removed transactions and already added new transactions.
# 285 : : virtual void requestMempoolTransactions(Notifications& notifications) = 0;
# 286 : : };
# 287 : :
# 288 : : //! Interface to let node manage chain clients (wallets, or maybe tools for
# 289 : : //! monitoring and analysis in the future).
# 290 : : class ChainClient
# 291 : : {
# 292 : : public:
# 293 : 808 : virtual ~ChainClient() {}
# 294 : :
# 295 : : //! Register rpcs.
# 296 : : virtual void registerRpcs() = 0;
# 297 : :
# 298 : : //! Check for errors before loading.
# 299 : : virtual bool verify() = 0;
# 300 : :
# 301 : : //! Load saved state.
# 302 : : virtual bool load() = 0;
# 303 : :
# 304 : : //! Start client execution and provide a scheduler.
# 305 : : virtual void start(CScheduler& scheduler) = 0;
# 306 : :
# 307 : : //! Save state to disk.
# 308 : : virtual void flush() = 0;
# 309 : :
# 310 : : //! Shut down client.
# 311 : : virtual void stop() = 0;
# 312 : :
# 313 : : //! Set mock time.
# 314 : : virtual void setMockTime(int64_t time) = 0;
# 315 : : };
# 316 : :
# 317 : : //! Return implementation of Chain interface.
# 318 : : std::unique_ptr<Chain> MakeChain(node::NodeContext& node);
# 319 : :
# 320 : : } // namespace interfaces
# 321 : :
# 322 : : #endif // BITCOIN_INTERFACES_CHAIN_H
|
