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