READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server340 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

10,670 bytes · SHA-256 e8551862eaf5e91f… · View upstream ↗

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
20namespace kernel {
21struct ChainstateRole;
22} // namespace kernel
23namespace util {
24class TaskRunnerInterface;
25} // namespace util
26
27class BlockValidationState;
28class CBlock;
29class CBlockIndex;
30struct CBlockLocator;
31enum class MemPoolRemovalReason;
32struct RemovedMempoolTransactionInfo;
33struct 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 */
50class CValidationInterface {
51protected:
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    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    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    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    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    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    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    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    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    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    virtual void NewPoWValidBlock(const CBlockIndex *pindex, const std::shared_ptr<const CBlock>& block) {};
164    friend class ValidationSignals;
165    friend class ValidationInterfaceTest;
166};
167
168class ValidationSignalsImpl;
169class ValidationSignals {
170private:
171    std::unique_ptr<ValidationSignalsImpl> m_internals;
172
173public:
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
237

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.