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.

20,227 bytes · SHA-256 e04b34e2f2974bb5… · View upstream ↗

1// Copyright (c) 2018-present 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 <consensus/amount.h>
11#include <kernel/chain.h> // IWYU pragma: export
12#include <primitives/transaction.h>
13#include <util/expected.h>
14#include <util/fees.h>
15#include <util/result.h>
16#include <util/time.h>
17
18#include <cstddef>
19#include <cstdint>
20#include <functional>
21#include <map>
22#include <memory>
23#include <optional>
24#include <string>
25#include <vector>
26
27class CBlock;
28class CFeeRate;
29class CRPCCommand;
30class CScheduler;
31class Coin;
32class uint256;
33enum class MemPoolRemovalReason;
34enum class RBFTransactionState;
35struct bilingual_str;
36struct CBlockLocator;
37namespace kernel {
38struct ChainstateRole;
39} // namespace kernel
40namespace node {
41struct NodeContext;
42enum class TxBroadcast : uint8_t;
43} // namespace node
44
45namespace interfaces {
46class Handler;
47
48//! Helper for findBlock to selectively return pieces of block data. If block is
49//! found, data will be returned by setting specified output variables. If block
50//! is not found, output variables will keep their previous values.
51class FoundBlock
52{
53public:
54    FoundBlock& hash(uint256& hash) { m_hash = &hash; return *this; }
55    FoundBlock& height(int& height) { m_height = &height; return *this; }
56    FoundBlock& time(int64_t& time) { m_time = &time; return *this; }
57    FoundBlock& maxTime(int64_t& max_time) { m_max_time = &max_time; return *this; }
58    FoundBlock& mtpTime(int64_t& mtp_time) { m_mtp_time = &mtp_time; return *this; }
59    //! Return whether block is in the active (most-work) chain.
60    FoundBlock& inActiveChain(bool& in_active_chain) { m_in_active_chain = &in_active_chain; return *this; }
61    //! Return locator if block is in the active chain.
62    FoundBlock& locator(CBlockLocator& locator) { m_locator = &locator; return *this; }
63    //! Return next block in the active chain if current block is in the active chain.
64    FoundBlock& nextBlock(const FoundBlock& next_block) { m_next_block = &next_block; return *this; }
65    //! Read block data from disk. If the block exists but doesn't have data
66    //! (for example due to pruning), the CBlock variable will be set to null.
67    FoundBlock& data(CBlock& data) { m_data = &data; return *this; }
68
69    uint256* m_hash = nullptr;
70    int* m_height = nullptr;
71    int64_t* m_time = nullptr;
72    int64_t* m_max_time = nullptr;
73    int64_t* m_mtp_time = nullptr;
74    bool* m_in_active_chain = nullptr;
75    CBlockLocator* m_locator = nullptr;
76    const FoundBlock* m_next_block = nullptr;
77    CBlock* m_data = nullptr;
78    mutable bool found = false;
79};
80
81//! The action to be taken after updating a settings value.
82//! WRITE indicates that the updated value must be written to disk,
83//! while SKIP_WRITE indicates that the change will be kept in memory-only
84//! without persisting it.
85enum class SettingsAction {
86    WRITE,
87    SKIP_WRITE
88};
89
90using SettingsUpdate = std::function<std::optional<interfaces::SettingsAction>(common::SettingsValue&)>;
91
92//! Interface giving clients (wallet processes, maybe other analysis tools in
93//! the future) ability to access to the chain state, receive notifications,
94//! estimate fees, and submit transactions.
95//!
96//! TODO: Current chain methods are too low level, exposing too much of the
97//! internal workings of the bitcoin node, and not being very convenient to use.
98//! Chain methods should be cleaned up and simplified over time. Examples:
99//!
100//! * The initMessages() and showProgress() methods which the wallet uses to send
101//!   notifications to the GUI should go away when GUI and wallet can directly
102//!   communicate with each other without going through the node
103//!   (https://github.com/bitcoin/bitcoin/pull/15288#discussion_r253321096).
104//!
105//! * The handleRpc, registerRpcs, rpcEnableDeprecated methods and other RPC
106//!   methods can go away if wallets listen for HTTP requests on their own
107//!   ports instead of registering to handle requests on the node HTTP port.
108//!
109//! * Move fee estimation queries to an asynchronous interface and let the
110//!   wallet cache it, fee estimation being driven by node mempool, wallet
111//!   should be the consumer.
112//!
113//! * `guessVerificationProgress` and similar methods can go away if rescan
114//!   logic moves out of the wallet, and the wallet just requests scans from the
115//!   node (https://github.com/bitcoin/bitcoin/issues/11756)
116class Chain
117{
118public:
119    virtual ~Chain() = default;
120
121    //! Get current chain height, not including genesis block (returns 0 if
122    //! chain only contains genesis block, nullopt if chain does not contain
123    //! any blocks)
124    virtual std::optional<int> getHeight() = 0;
125
126    //! Get block hash. Height must be valid or this function will abort.
127    virtual uint256 getBlockHash(int height) = 0;
128
129    //! Check that the block is available on disk (i.e. has not been
130    //! pruned), and contains transactions.
131    virtual bool haveBlockOnDisk(int height) = 0;
132
133    //! Return height of the highest block on chain in common with the locator,
134    //! which will either be the original block used to create the locator,
135    //! or one of its ancestors.
136    virtual std::optional<int> findLocatorFork(const CBlockLocator& locator) = 0;
137
138    //! Returns whether a block filter index is available.
139    virtual bool hasBlockFilterIndex(BlockFilterType filter_type) = 0;
140
141    //! Returns whether any of the elements match the block via a BIP 157 block filter
142    //! or std::nullopt if the block filter for this block couldn't be found.
143    virtual std::optional<bool> blockFilterMatchesAny(BlockFilterType filter_type, const uint256& block_hash, const GCSFilter::ElementSet& filter_set) = 0;
144
145    //! Return whether node has the block and optionally return block metadata
146    //! or contents.
147    virtual bool findBlock(const uint256& hash, const FoundBlock& block={}) = 0;
148
149    //! Find first block in the chain with timestamp >= the given time
150    //! and height >= than the given height, return false if there is no block
151    //! with a high enough timestamp and height. Optionally return block
152    //! information.
153    virtual bool findFirstBlockWithTimeAndHeight(int64_t min_time, int min_height, const FoundBlock& block={}) = 0;
154
155    //! Find ancestor of block at specified height and optionally return
156    //! ancestor information.
157    virtual bool findAncestorByHeight(const uint256& block_hash, int ancestor_height, const FoundBlock& ancestor_out={}) = 0;
158
159    //! Return whether block descends from a specified ancestor, and
160    //! optionally return ancestor information.
161    virtual bool findAncestorByHash(const uint256& block_hash,
162        const uint256& ancestor_hash,
163        const FoundBlock& ancestor_out={}) = 0;
164
165    //! Find most recent common ancestor between two blocks and optionally
166    //! return block information.
167    virtual bool findCommonAncestor(const uint256& block_hash1,
168        const uint256& block_hash2,
169        const FoundBlock& ancestor_out={},
170        const FoundBlock& block1_out={},
171        const FoundBlock& block2_out={}) = 0;
172
173    //! Look up unspent output information. Returns coins in the mempool and in
174    //! the current chain UTXO set. Iterates through all the keys in the map and
175    //! populates the values.
176    virtual void findCoins(std::map<COutPoint, Coin>& coins) = 0;
177
178    //! Estimate fraction of total transactions verified if blocks up to
179    //! the specified block hash are verified.
180    virtual double guessVerificationProgress(const uint256& block_hash) = 0;
181
182    //! Return true if data is available for all blocks in the specified range
183    //! of blocks. This checks all blocks that are ancestors of block_hash in
184    //! the height range from min_height to max_height, inclusive.
185    virtual bool hasBlocks(const uint256& block_hash, int min_height = 0, std::optional<int> max_height = {}) = 0;
186
187    //! Check if transaction is RBF opt in.
188    virtual RBFTransactionState isRBFOptIn(const CTransaction& tx) = 0;
189
190    //! Check if transaction is in mempool.
191    virtual bool isInMempool(const Txid& txid) = 0;
192
193    //! Check if transaction has descendants in mempool.
194    virtual bool hasDescendantsInMempool(const Txid& txid) = 0;
195
196    //! Process a local transaction, optionally adding it to the mempool and
197    //! optionally broadcasting it to the network.
198    //! @param[in] tx Transaction to process.
199    //! @param[in] max_tx_fee Don't add the transaction to the mempool or
200    //! broadcast it if its fee is higher than this.
201    //! @param[in] broadcast_method Whether to add the transaction to the
202    //! mempool and how/whether to broadcast it.
203    //! @param[out] err_string Set if an error occurs.
204    //! @return False if the transaction could not be added due to the fee or for another reason.
205    virtual bool broadcastTransaction(const CTransactionRef& tx,
206                                      const CAmount& max_tx_fee,
207                                      node::TxBroadcast broadcast_method,
208                                      std::string& err_string) = 0;
209
210    //! Calculate mempool ancestor and cluster counts for the given transaction.
211    virtual void getTransactionAncestry(const Txid& txid, size_t& ancestors, size_t& cluster_count, size_t* ancestorsize = nullptr, CAmount* ancestorfees = nullptr) = 0;
212
213    //! For each outpoint, calculate the fee-bumping cost to spend this outpoint at the specified
214    //  feerate, including bumping its ancestors. For example, if the target feerate is 10sat/vbyte
215    //  and this outpoint refers to a mempool transaction at 3sat/vbyte, the bump fee includes the
216    //  cost to bump the mempool transaction to 10sat/vbyte (i.e. 7 * mempooltx.vsize). If that
217    //  transaction also has, say, an unconfirmed parent with a feerate of 1sat/vbyte, the bump fee
218    //  includes the cost to bump the parent (i.e. 9 * parentmempooltx.vsize).
219    //
220    //  If the outpoint comes from an unconfirmed transaction that is already above the target
221    //  feerate or bumped by its descendant(s) already, it does not need to be bumped. Its bump fee
222    //  is 0. Likewise, if any of the transaction's ancestors are already bumped by a transaction
223    //  in our mempool, they are not included in the transaction's bump fee.
224    //
225    //  Also supported is bump-fee calculation in the case of replacements. If an outpoint
226    //  conflicts with another transaction in the mempool, it is assumed that the goal is to replace
227    //  that transaction. As such, the calculation will exclude the to-be-replaced transaction, but
228    //  will include the fee-bumping cost. If bump fees of descendants of the to-be-replaced
229    //  transaction are requested, the value will be 0. Fee-related RBF rules are not included as
230    //  they are logically distinct.
231    //
232    //  Any outpoints that are otherwise unavailable from the mempool (e.g. UTXOs from confirmed
233    //  transactions or transactions not yet broadcast by the wallet) are given a bump fee of 0.
234    //
235    //  If multiple outpoints come from the same transaction (which would be very rare because
236    //  it means that one transaction has multiple change outputs or paid the same wallet using multiple
237    //  outputs in the same transaction) or have shared ancestry, the bump fees are calculated
238    //  independently, i.e. as if only one of them is spent. This may result in double-fee-bumping. This
239    //  caveat can be rectified per use of the sister-function CalculateCombinedBumpFee(…).
240    virtual std::map<COutPoint, CAmount> calculateIndividualBumpFees(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
241
242    //! Calculate the combined bump fee for an input set per the same strategy
243    //  as in CalculateIndividualBumpFees(…).
244    //  Unlike CalculateIndividualBumpFees(…), this does not return individual
245    //  bump fees per outpoint, but a single bump fee for the shared ancestry.
246    //  The combined bump fee may be used to correct overestimation due to
247    //  shared ancestry by multiple UTXOs after coin selection.
248    virtual std::optional<CAmount> calculateCombinedBumpFee(const std::vector<COutPoint>& outpoints, const CFeeRate& target_feerate) = 0;
249
250    //! Get the node's package limits.

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.