/root/bitcoin/src/validationinterface.h

Source
// Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-present The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.

#ifndef BITCOIN_VALIDATIONINTERFACE_H
#define BITCOIN_VALIDATIONINTERFACE_H

#include <kernel/cs_main.h>
#include <primitives/transaction.h>
#include <sync.h>
#include <uint256.h>

#include <cstddef>
#include <cstdint>
#include <functional>
#include <memory>
#include <vector>

namespace kernel {
struct ChainstateRole;
} // namespace kernel
namespace util {
class TaskRunnerInterface;
} // namespace util

class BlockValidationState;
class CBlock;
class CBlockIndex;
struct CBlockLocator;
enum class MemPoolRemovalReason;
struct RemovedMempoolTransactionInfo;
struct NewMempoolTransactionInfo;

/**
 * Implement this to subscribe to events generated in validation and mempool
 *
 * Each CValidationInterface() subscriber will receive event callbacks
 * in the order in which the events were generated by validation and mempool.
 * Furthermore, each ValidationInterface() subscriber may assume that
 * callbacks effectively run in a single thread with single-threaded
 * memory consistency. That is, for a given ValidationInterface()
 * instantiation, each callback will complete before the next one is
 * invoked. This means, for example when a block is connected that the
 * UpdatedBlockTip() callback may depend on an operation performed in
 * the BlockConnected() callback without worrying about explicit
 * synchronization. No ordering should be assumed across
 * ValidationInterface() subscribers.
 */
class CValidationInterface {
protected:
    /**
     * Protected destructor so that instances can only be deleted by derived classes.
     * If that restriction is no longer desired, this should be made public and virtual.
     */
    ~CValidationInterface() = default;
    /**
     * Notifies listeners when the block chain tip advances.
     *
     * When multiple blocks are connected at once, UpdatedBlockTip will be called on the final tip
     * but may not be called on every intermediate tip. If the latter behavior is desired,
     * subscribe to BlockConnected() instead.
     *
     * Called on a background thread. Only called for the active chainstate.
     */
    virtual void UpdatedBlockTip(const CBlockIndex *pindexNew, const CBlockIndex *pindexFork, bool fInitialDownload) {}
    /**
     * Notifies listeners any time the block chain tip changes, synchronously.
     */
    virtual void ActiveTipChange(const CBlockIndex& new_tip, bool is_ibd) {};
    /**
     * Notifies listeners of a transaction having been added to mempool.
     *
     * Called on a background thread.
     */
    virtual void TransactionAddedToMempool(const NewMempoolTransactionInfo& tx, uint64_t mempool_sequence) {}

    /**
     * Notifies listeners of a transaction leaving mempool.
     *
     * This notification fires for transactions that are removed from the
     * mempool for the following reasons:
     *
     * - EXPIRY (expired from mempool after -mempoolexpiry hours)
     * - SIZELIMIT (removed in size limiting if the mempool exceeds -maxmempool megabytes)
     * - REORG (removed during a reorg)
     * - CONFLICT (removed because it conflicts with in-block transaction)
     * - REPLACED (removed due to RBF replacement)
     *
     * This does not fire for transactions that are removed from the mempool
     * because they have been included in a block. Any client that is interested
     * in transactions removed from the mempool for inclusion in a block can learn
     * about those transactions from the MempoolTransactionsRemovedForBlock notification.
     *
     * Transactions that are removed from the mempool because they conflict
     * with a transaction in the new block will have
     * TransactionRemovedFromMempool events fired *before* the BlockConnected
     * event is fired. If multiple blocks are connected in one step, then the
     * ordering could be:
     *
     * - TransactionRemovedFromMempool(tx1 from block A)
     * - TransactionRemovedFromMempool(tx2 from block A)
     * - TransactionRemovedFromMempool(tx1 from block B)
     * - TransactionRemovedFromMempool(tx2 from block B)
     * - BlockConnected(A)
     * - BlockConnected(B)
     *
     * Called on a background thread.
     */
    virtual void TransactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason reason, uint64_t mempool_sequence) {}
    /*
     * Notifies listeners of transactions removed from the mempool as
     * as a result of new block being connected.
     * MempoolTransactionsRemovedForBlock will be fired before BlockConnected.
     *
     * Not fired while initial block download is active.
     *
     * Called on a background thread.
     */
    virtual void MempoolTransactionsRemovedForBlock(const std::shared_ptr<const CBlock>& block, const std::vector<RemovedMempoolTransactionInfo>& txs_removed_for_block, unsigned int block_height) {}
    /**
     * Notifies listeners of a block being connected.
     *
     * Called on a background thread.
     */
    virtual void BlockConnected(const kernel::ChainstateRole& role, const std::shared_ptr<const CBlock>& block, const CBlockIndex* pindex) {}
    /**
     * Notifies listeners of a block being disconnected
     * Provides the block that was disconnected.
     *
     * Called on a background thread. Only called for the active chainstate, since
     * background chainstates should never disconnect blocks.
     */
    virtual void BlockDisconnected(const std::shared_ptr<const CBlock> &block, const CBlockIndex* pindex) {}
    /**
     * Notifies listeners of the new active block chain on-disk.
     *
     * Prior to this callback, any updates are not guaranteed to persist on disk
     * (ie clients need to handle shutdown/restart safety by being able to
     * understand when some updates were lost due to unclean shutdown).
     *
     * When this callback is invoked, the validation changes done by any prior
     * callback are guaranteed to exist on disk and survive a restart, including
     * an unclean shutdown.
     *
     * Provides a locator describing the best chain, which is likely useful for
     * storing current state on disk in client DBs.
     *
     * Called on a background thread.
     */
    virtual void ChainStateFlushed(const kernel::ChainstateRole& role, const CBlockLocator& locator) {}
    /**
     * Notifies listeners of a block validation result.
     * If the provided BlockValidationState IsValid, the provided block
     * is guaranteed to be the current best block at the time the
     * callback was generated (not necessarily now).
     */
    virtual void BlockChecked(const std::shared_ptr<const CBlock>&, const BlockValidationState&) {}
    /**
     * Notifies listeners that a block which builds directly on our current tip
     * has been received and connected to the headers tree, though not validated yet.
     */
    virtual void NewPoWValidBlock(const CBlockIndex *pindex, const std::shared_ptr<const CBlock>& block) {};
    friend class ValidationSignals;
    friend class ValidationInterfaceTest;
};

class ValidationSignalsImpl;
class ValidationSignals {
private:
    std::unique_ptr<ValidationSignalsImpl> m_internals;

public:
    // The task runner will block validation if it calls its insert method's
    // func argument synchronously. In this class func contains a loop that
    // dispatches a single validation event to all subscribers sequentially.
    explicit ValidationSignals(std::unique_ptr<util::TaskRunnerInterface> task_runner);

    ~ValidationSignals();

    /** Call any remaining callbacks on the calling thread */
    void FlushBackgroundCallbacks();

    size_t CallbacksPending();

    /** Register subscriber */
    void RegisterValidationInterface(CValidationInterface* callbacks);
    /** Unregister subscriber. DEPRECATED. This is not safe to use when the RPC server or main message handler thread is running. */
    void UnregisterValidationInterface(CValidationInterface* callbacks);
    /** Unregister all subscribers */
    void UnregisterAllValidationInterfaces();

    // Alternate registration functions that release a shared_ptr after the last
    // notification is sent. These are useful for race-free cleanup, since
    // unregistration is nonblocking and can return before the last notification is
    // processed.
    /** Register subscriber */
    void RegisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks);
    /** Unregister subscriber */
    void UnregisterSharedValidationInterface(std::shared_ptr<CValidationInterface> callbacks);

    /**
     * Pushes a function to callback onto the notification queue, guaranteeing any
     * callbacks generated prior to now are finished when the function is called.
     *
     * Be very careful blocking on func to be called if any locks are held -
     * validation interface clients may not be able to make progress as they often
     * wait for things like cs_main, so blocking until func is called with cs_main
     * will result in a deadlock (that DEBUG_LOCKORDER will miss).
     */
    void CallFunctionInValidationInterfaceQueue(std::function<void ()> func);

    /**
     * This is a synonym for the following, which asserts certain locks are not
     * held:
     *     std::promise<void> promise;
     *     CallFunctionInValidationInterfaceQueue([&promise] {
     *         promise.set_value();
     *     });
     *     promise.get_future().wait();
     */
    void SyncWithValidationInterfaceQueue() LOCKS_EXCLUDED(cs_main);

    void UpdatedBlockTip(const CBlockIndex *, const CBlockIndex *, bool fInitialDownload);
    void ActiveTipChange(const CBlockIndex&, bool);
    void TransactionAddedToMempool(const NewMempoolTransactionInfo&, uint64_t mempool_sequence);
    void TransactionRemovedFromMempool(const CTransactionRef&, MemPoolRemovalReason, uint64_t mempool_sequence);
    void MempoolTransactionsRemovedForBlock(std::shared_ptr<const CBlock>, std::vector<RemovedMempoolTransactionInfo>, unsigned int block_height);
    void BlockConnected(const kernel::ChainstateRole&, std::shared_ptr<const CBlock>, const CBlockIndex* pindex);
    void BlockDisconnected(std::shared_ptr<const CBlock>, const CBlockIndex* pindex);
    void ChainStateFlushed(const kernel::ChainstateRole&, const CBlockLocator&);
    void BlockChecked(const std::shared_ptr<const CBlock>&, const BlockValidationState&);
    void NewPoWValidBlock(const CBlockIndex *, const std::shared_ptr<const CBlock>&);
};

#endif // BITCOIN_VALIDATIONINTERFACE_H

Coverage Report

Created: 2026-09-01 13:35

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