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 server440 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.

15,624 bytes · SHA-256 53efb460c887345e… · 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#ifndef BITCOIN_POLICY_FEES_BLOCK_POLICY_ESTIMATOR_H
6#define BITCOIN_POLICY_FEES_BLOCK_POLICY_ESTIMATOR_H
7
8#include <consensus/amount.h>
9#include <policy/feerate.h>
10#include <primitives/transaction_identifier.h>
11#include <random.h>
12#include <sync.h>
13#include <uint256.h>
14#include <util/expected.h>
15#include <util/fees.h>
16#include <util/fs.h>
17
18#include <array>
19#include <chrono>
20#include <map>
21#include <memory>
22#include <set>
23#include <string>
24#include <vector>
25
26
27/** Block policy estimate files that are more than 60 hours (2.5 days) old will not be read,
28 * as fee estimates are based on historical data and may be inaccurate if
29 * network activity has changed.
30 */
31inline constexpr std::chrono::hours MAX_FILE_AGE{60};
32
33// Whether we allow importing a fee_estimates file older than MAX_FILE_AGE.
34inline constexpr bool DEFAULT_ACCEPT_STALE_FEE_ESTIMATES{false};
35
36class AutoFile;
37class TxConfirmStats;
38struct RemovedMempoolTransactionInfo;
39struct NewMempoolTransactionInfo;
40
41/* Identifier for each of the 3 different TxConfirmStats which will track
42 * history over different time horizons. */
43enum class FeeEstimateHorizon {
44    SHORT_HALFLIFE,
45    MED_HALFLIFE,
46    LONG_HALFLIFE,
47};
48
49inline constexpr auto ALL_FEE_ESTIMATE_HORIZONS = std::array{
50    FeeEstimateHorizon::SHORT_HALFLIFE,
51    FeeEstimateHorizon::MED_HALFLIFE,
52    FeeEstimateHorizon::LONG_HALFLIFE,
53};
54
55std::string StringForFeeEstimateHorizon(FeeEstimateHorizon horizon);
56
57/* Enumeration of reason for returned fee estimate */
58enum class BlockPolicyEstimateReason {
59    NONE,
60    HALF_ESTIMATE,
61    FULL_ESTIMATE,
62    DOUBLE_ESTIMATE,
63    CONSERVATIVE,
64};
65
66std::string StringForBlockPolicyEstimateReason(BlockPolicyEstimateReason reason);
67
68/* Used to return detailed information about a feerate bucket */
69struct EstimatorBucket
70{
71    double start = -1;
72    double end = -1;
73    double withinTarget = 0;
74    double totalConfirmed = 0;
75    double inMempool = 0;
76    double leftMempool = 0;
77};
78
79/* Used to return detailed information about a fee estimate calculation */
80struct EstimationResult
81{
82    EstimatorBucket pass;
83    EstimatorBucket fail;
84    double decay = 0;
85    unsigned int scale = 0;
86};
87
88struct FeeCalculation
89{
90    EstimationResult est;
91    BlockPolicyEstimateReason reason = BlockPolicyEstimateReason::NONE;
92    int desiredTarget = 0;
93    int returnedTarget = 0;
94    unsigned int best_height{0};
95};
96
97/** \class CBlockPolicyEstimator
98 * The BlockPolicyEstimator is used for estimating the feerate needed
99 * for a transaction to be included in a block within a certain number of
100 * blocks.
101 *
102 * At a high level the algorithm works by grouping transactions into buckets
103 * based on having similar feerates and then tracking how long it
104 * takes transactions in the various buckets to be mined.  It operates under
105 * the assumption that in general transactions of higher feerate will be
106 * included in blocks before transactions of lower feerate.   So for
107 * example if you wanted to know what feerate you should put on a transaction to
108 * be included in a block within the next 5 blocks, you would start by looking
109 * at the bucket with the highest feerate transactions and verifying that a
110 * sufficiently high percentage of them were confirmed within 5 blocks and
111 * then you would look at the next highest feerate bucket, and so on, stopping at
112 * the last bucket to pass the test.   The average feerate of transactions in this
113 * bucket will give you an indication of the lowest feerate you can put on a
114 * transaction and still have a sufficiently high chance of being confirmed
115 * within your desired 5 blocks.
116 *
117 * Here is a brief description of the implementation:
118 * When a transaction enters the mempool, we track the height of the block chain
119 * at entry.  All further calculations are conducted only on this set of "seen"
120 * transactions. Whenever a block comes in, we count the number of transactions
121 * in each bucket and the total amount of feerate paid in each bucket. Then we
122 * calculate how many blocks Y it took each transaction to be mined.  We convert
123 * from a number of blocks to a number of periods Y' each encompassing "scale"
124 * blocks.  This is tracked in 3 different data sets each up to a maximum
125 * number of periods. Within each data set we have an array of counters in each
126 * feerate bucket and we increment all the counters from Y' up to max periods
127 * representing that a tx was successfully confirmed in less than or equal to
128 * that many periods. We want to save a history of this information, so at any
129 * time we have a counter of the total number of transactions that happened in a
130 * given feerate bucket and the total number that were confirmed in each of the
131 * periods or less for any bucket.  We save this history by keeping an
132 * exponentially decaying moving average of each one of these stats.  This is
133 * done for a different decay in each of the 3 data sets to keep relevant data
134 * from different time horizons.  Furthermore we also keep track of the number
135 * unmined (in mempool or left mempool without being included in a block)
136 * transactions in each bucket and for how many blocks they have been
137 * outstanding and use both of these numbers to increase the number of transactions
138 * we've seen in that feerate bucket when calculating an estimate for any number
139 * of confirmations below the number of blocks they've been outstanding.
140 *
141 *  We want to be able to estimate feerates that are needed on tx's to be included in
142 * a certain number of blocks.  Every time a block is added to the best chain, this class records
143 * stats on the transactions included in that block
144 */
145class CBlockPolicyEstimator
146{
147private:
148    /** Track confirm delays up to 12 blocks for short horizon */
149    static constexpr unsigned int SHORT_BLOCK_PERIODS = 12;
150    static constexpr unsigned int SHORT_SCALE = 1;
151    /** Track confirm delays up to 48 blocks for medium horizon */
152    static constexpr unsigned int MED_BLOCK_PERIODS = 24;
153    static constexpr unsigned int MED_SCALE = 2;
154    /** Track confirm delays up to 1008 blocks for long horizon */
155    static constexpr unsigned int LONG_BLOCK_PERIODS = 42;
156    static constexpr unsigned int LONG_SCALE = 24;
157    /** Historical estimates that are older than this aren't valid */
158    static constexpr unsigned int OLDEST_ESTIMATE_HISTORY{6 * 1008};
159
160    /** Decay of .962 is a half-life of 18 blocks or about 3 hours */
161    static constexpr double SHORT_DECAY = .962;
162    /** Decay of .9952 is a half-life of 144 blocks or about 1 day */
163    static constexpr double MED_DECAY = .9952;
164    /** Decay of .99931 is a half-life of 1008 blocks or about 1 week */
165    static constexpr double LONG_DECAY = .99931;
166
167    /** Require greater than 60% of X feerate transactions to be confirmed within Y/2 blocks*/
168    static constexpr double HALF_SUCCESS_PCT = .6;
169    /** Require greater than 85% of X feerate transactions to be confirmed within Y blocks*/
170    static constexpr double SUCCESS_PCT = .85;
171    /** Require greater than 95% of X feerate transactions to be confirmed within 2 * Y blocks*/
172    static constexpr double DOUBLE_SUCCESS_PCT = .95;
173
174    /** Require an avg of 0.1 tx in the combined feerate bucket per block to have stat significance */
175    static constexpr double SUFFICIENT_FEETXS = 0.1;
176    /** Require an avg of 0.5 tx when using short decay since there are fewer blocks considered*/
177    static constexpr double SUFFICIENT_TXS_SHORT = 0.5;
178
179    /** Minimum and Maximum values for tracking feerates
180     * The MIN_BUCKET_FEERATE should just be set to the lowest reasonable feerate.
181     * MIN_BUCKET_FEERATE has historically inherited DEFAULT_MIN_RELAY_TX_FEE.
182     * It is hardcoded because changing it is disruptive, as it invalidates existing fee
183     * estimate files.
184     *
185     * Whenever DEFAULT_MIN_RELAY_TX_FEE changes, this value should be updated
186     * accordingly. At the same time CURRENT_FEES_FILE_VERSION should be bumped.
187     */
188    static constexpr double MIN_BUCKET_FEERATE = 100;
189    static constexpr double MAX_BUCKET_FEERATE = 1e7;
190
191    /** Spacing of FeeRate buckets
192     * We have to lump transactions into buckets based on feerate, but we want to be able
193     * to give accurate estimates over a large range of potential feerates
194     * Therefore it makes sense to exponentially space the buckets
195     */
196    static constexpr double FEE_SPACING = 1.05;
197
198    const fs::path m_estimation_filepath;
199public:
200    /** Create new BlockPolicyEstimator and initialize stats tracking classes with default values */
201    CBlockPolicyEstimator(const fs::path& estimation_filepath, bool read_stale_estimates);
202    virtual ~CBlockPolicyEstimator();
203
204    /** Process all the transactions that have been included in a block */
205    void processBlock(const std::vector<RemovedMempoolTransactionInfo>& txs_removed_for_block,
206                      unsigned int nBlockHeight)
207        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
208
209    /** Process a transaction accepted to the mempool*/
210    void processTransaction(const NewMempoolTransactionInfo& tx)
211        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
212
213    /** Remove a transaction from the mempool tracking stats for non BLOCK removal reasons*/
214    bool removeTx(Txid hash)
215        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
216
217    /** DEPRECATED. Return a feerate estimate */
218    CFeeRate estimateFee(int confTarget) const
219        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
220
221    /** Estimate feerate needed to get be included in a block within confTarget
222     *  blocks. If no answer can be given at confTarget, return an estimate at
223     *  the closest target where one can be given.  'conservative' estimates are
224     *  valid over longer time horizons also.
225     */
226    virtual CFeeRate estimateSmartFee(int confTarget, FeeCalculation *feeCalc, bool conservative) const
227        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
228
229    /** Return a specific fee estimate calculation with a given success
230     * threshold and time horizon, and optionally return detailed data about
231     * calculation
232     */
233    CFeeRate estimateRawFee(int confTarget, double successThreshold, FeeEstimateHorizon horizon,
234                            EstimationResult* result = nullptr) const
235        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
236
237    /** Write estimation data to a file */
238    bool Write(AutoFile& fileout) const
239        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
240
241    /** Read estimation data from a file */
242    bool Read(AutoFile& filein)
243        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
244
245    /** Empty mempool transactions on shutdown to record failure to confirm for txs still in mempool */
246    void FlushUnconfirmed()
247        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
248
249    /** Calculation of highest target that estimates are tracked for */
250    virtual unsigned int HighestTargetTracked(FeeEstimateHorizon horizon) const

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

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.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.