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