Branch data Line data Source code
1 : : // Copyright (c) 2009-2010 Satoshi Nakamoto 2 : : // Copyright (c) 2009-2022 The Bitcoin Core developers 3 : : // Distributed under the MIT software license, see the accompanying 4 : : // file COPYING or http://www.opensource.org/licenses/mit-license.php. 5 : : 6 : : #ifndef BITCOIN_VALIDATIONINTERFACE_H 7 : : #define BITCOIN_VALIDATIONINTERFACE_H 8 : : 9 : : #include <kernel/chain.h> 10 : : #include <kernel/cs_main.h> 11 : : #include <primitives/transaction.h> // CTransaction(Ref) 12 : : #include <sync.h> 13 : : 14 : : #include <cstddef> 15 : : #include <cstdint> 16 : : #include <functional> 17 : : #include <memory> 18 : : #include <vector> 19 : : 20 : : namespace util { 21 : : class TaskRunnerInterface; 22 : : } // namespace util 23 : : 24 : : class BlockValidationState; 25 : : class CBlock; 26 : : class CBlockIndex; 27 : : struct CBlockLocator; 28 : : enum class MemPoolRemovalReason; 29 : : struct RemovedMempoolTransactionInfo; 30 : : struct NewMempoolTransactionInfo; 31 : : 32 : : /** 33 : : * Implement this to subscribe to events generated in validation and mempool 34 : : * 35 : : * Each CValidationInterface() subscriber will receive event callbacks 36 : : * in the order in which the events were generated by validation and mempool. 37 : : * Furthermore, each ValidationInterface() subscriber may assume that 38 : : * callbacks effectively run in a single thread with single-threaded 39 : : * memory consistency. That is, for a given ValidationInterface() 40 : : * instantiation, each callback will complete before the next one is 41 : : * invoked. This means, for example when a block is connected that the 42 : : * UpdatedBlockTip() callback may depend on an operation performed in 43 : : * the BlockConnected() callback without worrying about explicit 44 : : * synchronization. No ordering should be assumed across 45 : : * ValidationInterface() subscribers. 46 : : */ 47 : : class CValidationInterface { 48 : : protected: 49 : : /** 50 : : * Protected destructor so that instances can only be deleted by derived classes. 51 : : * If that restriction is no longer desired, this should be made public and virtual. 52 : : */ 53 : : ~CValidationInterface() = default; 54 : : /** 55 : : * Notifies listeners when the block chain tip advances. 56 : : * 57 : : * When multiple blocks are connected at once, UpdatedBlockTip will be called on the final tip 58 : : * but may not be called on every intermediate tip. If the latter behavior is desired, 59 : : * subscribe to BlockConnected() instead. 60 : : * 61 : : * Called on a background thread. Only called for the active chainstate. 62 : : */ 63 : 44838 : virtual void UpdatedBlockTip(const CBlockIndex *pindexNew, const CBlockIndex *pindexFork, bool fInitialDownload) {} 64 : : /** 65 : : * Notifies listeners of a transaction having been added to mempool. 66 : : * 67 : : * Called on a background thread. 68 : : */ 69 : 0 : virtual void TransactionAddedToMempool(const NewMempoolTransactionInfo& tx, uint64_t mempool_sequence) {} 70 : : 71 : : /** 72 : : * Notifies listeners of a transaction leaving mempool. 73 : : * 74 : : * This notification fires for transactions that are removed from the 75 : : * mempool for the following reasons: 76 : : * 77 : : * - EXPIRY (expired from mempool after -mempoolexpiry hours) 78 : : * - SIZELIMIT (removed in size limiting if the mempool exceeds -maxmempool megabytes) 79 : : * - REORG (removed during a reorg) 80 : : * - CONFLICT (removed because it conflicts with in-block transaction) 81 : : * - REPLACED (removed due to RBF replacement) 82 : : * 83 : : * This does not fire for transactions that are removed from the mempool 84 : : * because they have been included in a block. Any client that is interested 85 : : * in transactions removed from the mempool for inclusion in a block can learn 86 : : * about those transactions from the MempoolTransactionsRemovedForBlock notification. 87 : : * 88 : : * Transactions that are removed from the mempool because they conflict 89 : : * with a transaction in the new block will have 90 : : * TransactionRemovedFromMempool events fired *before* the BlockConnected 91 : : * event is fired. If multiple blocks are connected in one step, then the 92 : : * ordering could be: 93 : : * 94 : : * - TransactionRemovedFromMempool(tx1 from block A) 95 : : * - TransactionRemovedFromMempool(tx2 from block A) 96 : : * - TransactionRemovedFromMempool(tx1 from block B) 97 : : * - TransactionRemovedFromMempool(tx2 from block B) 98 : : * - BlockConnected(A) 99 : : * - BlockConnected(B) 100 : : * 101 : : * Called on a background thread. 102 : : */ 103 : 0 : virtual void TransactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason, uint64_t mempool_sequence) {} 104 : : /* 105 : : * Notifies listeners of transactions removed from the mempool as 106 : : * as a result of new block being connected. 107 : : * MempoolTransactionsRemovedForBlock will be fired before BlockConnected. 108 : : * 109 : : * Called on a background thread. 110 : : */ 111 : 79760 : virtual void MempoolTransactionsRemovedForBlock(const std::vector<RemovedMempoolTransactionInfo>& txs_removed_for_block, unsigned int nBlockHeight) {} 112 : : /** 113 : : * Notifies listeners of a block being connected. 114 : : * Provides a vector of transactions evicted from the mempool as a result. 115 : : * 116 : : * Called on a background thread. 117 : : */ 118 : 61734 : virtual void BlockConnected(ChainstateRole role, const std::shared_ptr<const CBlock> &block, const CBlockIndex *pindex) {} 119 : : /** 120 : : * Notifies listeners of a block being disconnected 121 : : * Provides the block that was disconnected. 122 : : * 123 : : * Called on a background thread. Only called for the active chainstate, since 124 : : * background chainstates should never disconnect blocks. 125 : : */ 126 : 0 : virtual void BlockDisconnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex* pindex) {} 127 : : /** 128 : : * Notifies listeners of the new active block chain on-disk. 129 : : * 130 : : * Prior to this callback, any updates are not guaranteed to persist on disk 131 : : * (ie clients need to handle shutdown/restart safety by being able to 132 : : * understand when some updates were lost due to unclean shutdown). 133 : : * 134 : : * When this callback is invoked, the validation changes done by any prior 135 : : * callback are guaranteed to exist on disk and survive a restart, including 136 : : * an unclean shutdown. 137 : : * 138 : : * Provides a locator describing the best chain, which is likely useful for 139 : : * storing current state on disk in client DBs. 140 : : * 141 : : * Called on a background thread. 142 : : */ 143 : 207 : virtual void ChainStateFlushed(ChainstateRole role, const CBlockLocator &locator) {} 144 : : /** 145 : : * Notifies listeners of a block validation result. 146 : : * If the provided BlockValidationState IsValid, the provided block 147 : : * is guaranteed to be the current best block at the time the 148 : : * callback was generated (not necessarily now). 149 : : */ 150 : 0 : virtual void BlockChecked(const CBlock&, const BlockValidationState&) {} 151 : : /** 152 : : * Notifies listeners that a block which builds directly on our current tip 153 : : * has been received and connected to the headers tree, though not validated yet. 154 : : */ 155 : 0 : virtual void NewPoWValidBlock(const CBlockIndex *pindex, const std::shared_ptr<const CBlock>& block) {}; 156 : : friend class ValidationSignals; 157 : : friend class ValidationInterfaceTest; 158 : : }; 159 : : 160 : : class ValidationSignalsImpl; 161 : : class ValidationSignals { 162 : : private: 163 : : std::unique_ptr<ValidationSignalsImpl> m_internals; 164 : : 165 : : public: 166 : : // The task runner will block validation if it calls its insert method's 167 : : // func argument synchronously. In this class func contains a loop that 168 : : // dispatches a single validation event to all subscribers sequentially. 169 : : explicit ValidationSignals(std::unique_ptr<util::TaskRunnerInterface> task_runner); 170 : : 171 : : ~ValidationSignals(); 172 : : 173 : : /** Call any remaining callbacks on the calling thread */ 174 : : void FlushBackgroundCallbacks(); 175 : : 176 : : size_t CallbacksPending(); 177 : : 178 : : /** Register subscriber */ 179 : : void RegisterValidationInterface(CValidationInterface* callbacks); 180 : : /** Unregister subscriber. DEPRECATED. This is not safe to use when the RPC server or main message handler thread is running. */ 181 : : void UnregisterValidationInterface(CValidationInterface* callbacks); 182 : : /** Unregister all subscribers */ 183 : : void UnregisterAllValidationInterfaces(); 184 : : 185 : : // Alternate registration functions that release a shared_ptr after the last 186 : : // notification is sent. These are useful for race-free cleanup, since 187 : : // unregistration is nonblocking and can return before the last notification is 188 : : // processed. 189 : : /** Register subscriber */ 190 : : void RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks); 191 : : /** Unregister subscriber */ 192 : : void UnregisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks); 193 : : 194 : : /** 195 : : * Pushes a function to callback onto the notification queue, guaranteeing any 196 : : * callbacks generated prior to now are finished when the function is called. 197 : : * 198 : : * Be very careful blocking on func to be called if any locks are held - 199 : : * validation interface clients may not be able to make progress as they often 200 : : * wait for things like cs_main, so blocking until func is called with cs_main 201 : : * will result in a deadlock (that DEBUG_LOCKORDER will miss). 202 : : */ 203 : : void CallFunctionInValidationInterfaceQueue(std::function<void ()> func); 204 : : 205 : : /** 206 : : * This is a synonym for the following, which asserts certain locks are not 207 : : * held: 208 : : * std::promise<void> promise; 209 : : * CallFunctionInValidationInterfaceQueue([&promise] { 210 : : * promise.set_value(); 211 : : * }); 212 : : * promise.get_future().wait(); 213 : : */ 214 : : void SyncWithValidationInterfaceQueue() LOCKS_EXCLUDED(cs_main); 215 : : 216 : : void UpdatedBlockTip(const CBlockIndex *, const CBlockIndex *, bool fInitialDownload); 217 : : void TransactionAddedToMempool(const NewMempoolTransactionInfo&, uint64_t mempool_sequence); 218 : : void TransactionRemovedFromMempool(const CTransactionRef&, MemPoolRemovalReason, uint64_t mempool_sequence); 219 : : void MempoolTransactionsRemovedForBlock(const std::vector<RemovedMempoolTransactionInfo>&, unsigned int nBlockHeight); 220 : : void BlockConnected(ChainstateRole, const std::shared_ptr<const CBlock> &, const CBlockIndex *pindex); 221 : : void BlockDisconnected(const std::shared_ptr<const CBlock> &, const CBlockIndex* pindex); 222 : : void ChainStateFlushed(ChainstateRole, const CBlockLocator &); 223 : : void BlockChecked(const CBlock&, const BlockValidationState&); 224 : : void NewPoWValidBlock(const CBlockIndex *, const std::shared_ptr<const CBlock>&); 225 : : }; 226 : : 227 : : #endif // BITCOIN_VALIDATIONINTERFACE_H