Bitcoin Core  23.99.0
P2P Digital Currency
fees.h
Go to the documentation of this file.
1 // Copyright (c) 2009-2010 Satoshi Nakamoto
2 // Copyright (c) 2009-2021 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_H
6 #define BITCOIN_POLICY_FEES_H
7 
8 #include <consensus/amount.h>
9 #include <fs.h>
10 #include <policy/feerate.h>
11 #include <random.h>
12 #include <sync.h>
13 #include <threadsafety.h>
14 #include <uint256.h>
15 
16 #include <array>
17 #include <map>
18 #include <memory>
19 #include <set>
20 #include <string>
21 #include <vector>
22 
23 class AutoFile;
24 class CTxMemPoolEntry;
25 class TxConfirmStats;
26 
27 /* Identifier for each of the 3 different TxConfirmStats which will track
28  * history over different time horizons. */
29 enum class FeeEstimateHorizon {
33 };
34 
35 static constexpr auto ALL_FEE_ESTIMATE_HORIZONS = std::array{
39 };
40 
42 
43 /* Enumeration of reason for returned fee estimate */
44 enum class FeeReason {
45  NONE,
51  PAYTXFEE,
52  FALLBACK,
53  REQUIRED,
54 };
55 
56 /* Used to return detailed information about a feerate bucket */
58 {
59  double start = -1;
60  double end = -1;
61  double withinTarget = 0;
62  double totalConfirmed = 0;
63  double inMempool = 0;
64  double leftMempool = 0;
65 };
66 
67 /* Used to return detailed information about a fee estimate calculation */
69 {
72  double decay = 0;
73  unsigned int scale = 0;
74 };
75 
77 {
80  int desiredTarget = 0;
81  int returnedTarget = 0;
82 };
83 
133 {
134 private:
136  static constexpr unsigned int SHORT_BLOCK_PERIODS = 12;
137  static constexpr unsigned int SHORT_SCALE = 1;
139  static constexpr unsigned int MED_BLOCK_PERIODS = 24;
140  static constexpr unsigned int MED_SCALE = 2;
142  static constexpr unsigned int LONG_BLOCK_PERIODS = 42;
143  static constexpr unsigned int LONG_SCALE = 24;
145  static const unsigned int OLDEST_ESTIMATE_HISTORY = 6 * 1008;
146 
148  static constexpr double SHORT_DECAY = .962;
150  static constexpr double MED_DECAY = .9952;
152  static constexpr double LONG_DECAY = .99931;
153 
155  static constexpr double HALF_SUCCESS_PCT = .6;
157  static constexpr double SUCCESS_PCT = .85;
159  static constexpr double DOUBLE_SUCCESS_PCT = .95;
160 
162  static constexpr double SUFFICIENT_FEETXS = 0.1;
164  static constexpr double SUFFICIENT_TXS_SHORT = 0.5;
165 
173  static constexpr double MIN_BUCKET_FEERATE = 1000;
174  static constexpr double MAX_BUCKET_FEERATE = 1e7;
175 
181  static constexpr double FEE_SPACING = 1.05;
182 
184 public:
186  CBlockPolicyEstimator(const fs::path& estimation_filepath);
188 
190  void processBlock(unsigned int nBlockHeight,
191  std::vector<const CTxMemPoolEntry*>& entries)
193 
195  void processTransaction(const CTxMemPoolEntry& entry, bool validFeeEstimate)
197 
199  bool removeTx(uint256 hash, bool inBlock)
201 
203  CFeeRate estimateFee(int confTarget) const
205 
211  CFeeRate estimateSmartFee(int confTarget, FeeCalculation *feeCalc, bool conservative) const
213 
218  CFeeRate estimateRawFee(int confTarget, double successThreshold, FeeEstimateHorizon horizon,
219  EstimationResult* result = nullptr) const
221 
223  bool Write(AutoFile& fileout) const
225 
227  bool Read(AutoFile& filein)
229 
231  void FlushUnconfirmed()
233 
235  unsigned int HighestTargetTracked(FeeEstimateHorizon horizon) const
237 
239  void Flush()
241 
242 private:
244 
245  unsigned int nBestSeenHeight GUARDED_BY(m_cs_fee_estimator);
246  unsigned int firstRecordedHeight GUARDED_BY(m_cs_fee_estimator);
247  unsigned int historicalFirst GUARDED_BY(m_cs_fee_estimator);
248  unsigned int historicalBest GUARDED_BY(m_cs_fee_estimator);
249 
250  struct TxStatsInfo
251  {
252  unsigned int blockHeight;
253  unsigned int bucketIndex;
254  TxStatsInfo() : blockHeight(0), bucketIndex(0) {}
255  };
256 
257  // map of txids to information about that transaction
258  std::map<uint256, TxStatsInfo> mapMemPoolTxs GUARDED_BY(m_cs_fee_estimator);
259 
261  std::unique_ptr<TxConfirmStats> feeStats PT_GUARDED_BY(m_cs_fee_estimator);
262  std::unique_ptr<TxConfirmStats> shortStats PT_GUARDED_BY(m_cs_fee_estimator);
263  std::unique_ptr<TxConfirmStats> longStats PT_GUARDED_BY(m_cs_fee_estimator);
264 
265  unsigned int trackedTxs GUARDED_BY(m_cs_fee_estimator);
266  unsigned int untrackedTxs GUARDED_BY(m_cs_fee_estimator);
267 
268  std::vector<double> buckets GUARDED_BY(m_cs_fee_estimator); // The upper-bound of the range for the bucket (inclusive)
269  std::map<double, unsigned int> bucketMap GUARDED_BY(m_cs_fee_estimator); // Map of bucket upper-bound to index into all vectors by bucket
270 
272  bool processBlockTx(unsigned int nBlockHeight, const CTxMemPoolEntry* entry) EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
273 
275  double estimateCombinedFee(unsigned int confTarget, double successThreshold, bool checkShorterHorizon, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
277  double estimateConservativeFee(unsigned int doubleTarget, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
284 
286  bool _removeTx(const uint256& hash, bool inBlock)
288 };
289 
291 {
292 private:
293  static constexpr double MAX_FILTER_FEERATE = 1e7;
298  static constexpr double FEE_FILTER_SPACING = 1.1;
299 
300 public:
302  explicit FeeFilterRounder(const CFeeRate& minIncrementalFee);
303 
305  CAmount round(CAmount currentMinFee);
306 
307 private:
308  std::set<double> feeset;
310 };
311 
312 #endif // BITCOIN_POLICY_FEES_H
CBlockPolicyEstimator::~CBlockPolicyEstimator
~CBlockPolicyEstimator()
CBlockPolicyEstimator::MED_SCALE
static constexpr unsigned int MED_SCALE
Definition: fees.h:140
FeeFilterRounder::feeset
std::set< double > feeset
Definition: fees.h:308
EstimatorBucket::inMempool
double inMempool
Definition: fees.h:63
FeeReason
FeeReason
Definition: fees.h:44
feerate.h
EstimatorBucket::start
double start
Definition: fees.h:59
EstimatorBucket::leftMempool
double leftMempool
Definition: fees.h:64
CBlockPolicyEstimator::FEE_SPACING
static constexpr double FEE_SPACING
Spacing of FeeRate buckets We have to lump transactions into buckets based on feerate,...
Definition: fees.h:181
fs.h
AutoFile
Non-refcounted RAII wrapper for FILE*.
Definition: streams.h:474
FeeCalculation::est
EstimationResult est
Definition: fees.h:78
FeeFilterRounder::insecure_rand
FastRandomContext insecure_rand
Definition: fees.h:309
FeeEstimateHorizon
FeeEstimateHorizon
Definition: fees.h:29
sync.h
FeeCalculation::returnedTarget
int returnedTarget
Definition: fees.h:81
uint256.h
CBlockPolicyEstimator::estimateFee
CFeeRate estimateFee(int confTarget) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
DEPRECATED.
Definition: fees.cpp:673
CBlockPolicyEstimator::SUFFICIENT_FEETXS
static constexpr double SUFFICIENT_FEETXS
Require an avg of 0.1 tx in the combined feerate bucket per block to have stat significance.
Definition: fees.h:162
CBlockPolicyEstimator::processBlockTx
bool processBlockTx(unsigned int nBlockHeight, const CTxMemPoolEntry *entry) EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
Process a transaction confirmed in a block.
Definition: fees.cpp:596
CBlockPolicyEstimator::processBlock
void processBlock(unsigned int nBlockHeight, std::vector< const CTxMemPoolEntry * > &entries) EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Process all the transactions that have been included in a block.
Definition: fees.cpp:624
CBlockPolicyEstimator::estimateSmartFee
CFeeRate estimateSmartFee(int confTarget, FeeCalculation *feeCalc, bool conservative) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Estimate feerate needed to get be included in a block within confTarget blocks.
Definition: fees.cpp:826
CBlockPolicyEstimator::MaxUsableEstimate
unsigned int MaxUsableEstimate() const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
Calculation of highest target that reasonable estimate can be provided for.
Definition: fees.cpp:753
CBlockPolicyEstimator::removeTx
bool removeTx(uint256 hash, bool inBlock) EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Remove a transaction from the mempool tracking stats.
Definition: fees.cpp:509
AnnotatedMixin< std::mutex >
CBlockPolicyEstimator::HistoricalBlockSpan
unsigned int HistoricalBlockSpan() const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
Number of blocks of recorded fee estimate data represented in saved data file.
Definition: fees.cpp:743
CBlockPolicyEstimator::SUCCESS_PCT
static constexpr double SUCCESS_PCT
Require greater than 85% of X feerate transactions to be confirmed within Y blocks.
Definition: fees.h:157
CBlockPolicyEstimator::m_estimation_filepath
const fs::path m_estimation_filepath
Definition: fees.h:183
FeeReason::FULL_ESTIMATE
@ FULL_ESTIMATE
FeeReason::PAYTXFEE
@ PAYTXFEE
CBlockPolicyEstimator::MED_BLOCK_PERIODS
static constexpr unsigned int MED_BLOCK_PERIODS
Track confirm delays up to 48 blocks for medium horizon.
Definition: fees.h:139
FeeReason::NONE
@ NONE
CFeeRate
Fee rate in satoshis per kilovirtualbyte: CAmount / kvB.
Definition: feerate.h:32
CBlockPolicyEstimator::estimateConservativeFee
double estimateConservativeFee(unsigned int doubleTarget, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
Helper for estimateSmartFee.
Definition: fees.cpp:802
CBlockPolicyEstimator::SUFFICIENT_TXS_SHORT
static constexpr double SUFFICIENT_TXS_SHORT
Require an avg of 0.5 tx when using short decay since there are fewer blocks considered.
Definition: fees.h:164
EstimatorBucket::end
double end
Definition: fees.h:60
FeeCalculation::desiredTarget
int desiredTarget
Definition: fees.h:80
CBlockPolicyEstimator::LONG_SCALE
static constexpr unsigned int LONG_SCALE
Definition: fees.h:143
CBlockPolicyEstimator::MED_DECAY
static constexpr double MED_DECAY
Decay of .9952 is a half-life of 144 blocks or about 1 day.
Definition: fees.h:150
CBlockPolicyEstimator::MIN_BUCKET_FEERATE
static constexpr double MIN_BUCKET_FEERATE
Minimum and Maximum values for tracking feerates The MIN_BUCKET_FEERATE should just be set to the low...
Definition: fees.h:173
CBlockPolicyEstimator::SHORT_SCALE
static constexpr unsigned int SHORT_SCALE
Definition: fees.h:137
FeeCalculation::reason
FeeReason reason
Definition: fees.h:79
FeeEstimateHorizon::LONG_HALFLIFE
@ LONG_HALFLIFE
FeeCalculation
Definition: fees.h:76
EstimationResult::decay
double decay
Definition: fees.h:72
EstimationResult
Definition: fees.h:68
threadsafety.h
FeeReason::FALLBACK
@ FALLBACK
CBlockPolicyEstimator::estimateCombinedFee
double estimateCombinedFee(unsigned int confTarget, double successThreshold, bool checkShorterHorizon, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
Helper for estimateSmartFee.
Definition: fees.cpp:763
CBlockPolicyEstimator::TxStatsInfo
Definition: fees.h:250
CBlockPolicyEstimator::MAX_BUCKET_FEERATE
static constexpr double MAX_BUCKET_FEERATE
Definition: fees.h:174
fs::path
Path class wrapper to block calls to the fs::path(std::string) implicit constructor and the fs::path:...
Definition: fs.h:30
FeeReason::MEMPOOL_MIN
@ MEMPOOL_MIN
CBlockPolicyEstimator::PT_GUARDED_BY
std::unique_ptr< TxConfirmStats > feeStats PT_GUARDED_BY(m_cs_fee_estimator)
Classes to track historical data on transaction confirmations.
EstimationResult::scale
unsigned int scale
Definition: fees.h:73
CBlockPolicyEstimator::m_cs_fee_estimator
Mutex m_cs_fee_estimator
Definition: fees.h:243
CBlockPolicyEstimator::TxStatsInfo::blockHeight
unsigned int blockHeight
Definition: fees.h:252
TxConfirmStats
We will instantiate an instance of this class to track transactions that were included in a block.
Definition: fees.cpp:73
CBlockPolicyEstimator
Definition: fees.h:132
CAmount
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
FeeFilterRounder
Definition: fees.h:290
EstimatorBucket
Definition: fees.h:57
CBlockPolicyEstimator::SHORT_DECAY
static constexpr double SHORT_DECAY
Decay of .962 is a half-life of 18 blocks or about 3 hours.
Definition: fees.h:148
CBlockPolicyEstimator::LONG_DECAY
static constexpr double LONG_DECAY
Decay of .99931 is a half-life of 1008 blocks or about 1 week.
Definition: fees.h:152
CBlockPolicyEstimator::GUARDED_BY
unsigned int nBestSeenHeight GUARDED_BY(m_cs_fee_estimator)
uint256
256-bit opaque blob.
Definition: uint256.h:126
FeeReason::REQUIRED
@ REQUIRED
CBlockPolicyEstimator::CBlockPolicyEstimator
CBlockPolicyEstimator(const fs::path &estimation_filepath)
Create new BlockPolicyEstimator and initialize stats tracking classes with default values.
Definition: fees.cpp:530
FeeEstimateMode::CONSERVATIVE
@ CONSERVATIVE
Force estimateSmartFee to use conservative estimates.
CBlockPolicyEstimator::estimateRawFee
CFeeRate estimateRawFee(int confTarget, double successThreshold, FeeEstimateHorizon horizon, EstimationResult *result=nullptr) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Return a specific fee estimate calculation with a given success threshold and time horizon,...
Definition: fees.cpp:682
CBlockPolicyEstimator::Read
bool Read(AutoFile &filein) EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Read estimation data from a file.
Definition: fees.cpp:938
CBlockPolicyEstimator::LONG_BLOCK_PERIODS
static constexpr unsigned int LONG_BLOCK_PERIODS
Track confirm delays up to 1008 blocks for long horizon.
Definition: fees.h:142
CBlockPolicyEstimator::SHORT_BLOCK_PERIODS
static constexpr unsigned int SHORT_BLOCK_PERIODS
Track confirm delays up to 12 blocks for short horizon.
Definition: fees.h:136
EstimationResult::fail
EstimatorBucket fail
Definition: fees.h:71
EXCLUSIVE_LOCKS_REQUIRED
#define EXCLUSIVE_LOCKS_REQUIRED(...)
Definition: threadsafety.h:49
CTxMemPoolEntry
Definition: txmempool.h:88
StringForFeeEstimateHorizon
std::string StringForFeeEstimateHorizon(FeeEstimateHorizon horizon)
Definition: fees.cpp:36
FeeReason::DOUBLE_ESTIMATE
@ DOUBLE_ESTIMATE
CBlockPolicyEstimator::OLDEST_ESTIMATE_HISTORY
static const unsigned int OLDEST_ESTIMATE_HISTORY
Historical estimates that are older than this aren't valid.
Definition: fees.h:145
CBlockPolicyEstimator::TxStatsInfo::bucketIndex
unsigned int bucketIndex
Definition: fees.h:253
EstimatorBucket::withinTarget
double withinTarget
Definition: fees.h:61
CBlockPolicyEstimator::Write
bool Write(AutoFile &fileout) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Write estimation data to a file.
Definition: fees.cpp:913
CBlockPolicyEstimator::HALF_SUCCESS_PCT
static constexpr double HALF_SUCCESS_PCT
Require greater than 60% of X feerate transactions to be confirmed within Y/2 blocks.
Definition: fees.h:155
EstimationResult::pass
EstimatorBucket pass
Definition: fees.h:70
CBlockPolicyEstimator::HighestTargetTracked
unsigned int HighestTargetTracked(FeeEstimateHorizon horizon) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Calculation of highest target that estimates are tracked for.
Definition: fees.cpp:718
FeeEstimateHorizon::SHORT_HALFLIFE
@ SHORT_HALFLIFE
FeeReason::HALF_ESTIMATE
@ HALF_ESTIMATE
CBlockPolicyEstimator::BlockSpan
unsigned int BlockSpan() const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
Number of blocks of data recorded while fee estimates have been running.
Definition: fees.cpp:735
CBlockPolicyEstimator::TxStatsInfo::TxStatsInfo
TxStatsInfo()
Definition: fees.h:254
CBlockPolicyEstimator::Flush
void Flush() EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Drop still unconfirmed transactions and record current estimations, if the fee estimation file is pre...
Definition: fees.cpp:904
CBlockPolicyEstimator::FlushUnconfirmed
void FlushUnconfirmed() EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Empty mempool transactions on shutdown to record failure to confirm for txs still in mempool.
Definition: fees.cpp:1000
FeeEstimateHorizon::MED_HALFLIFE
@ MED_HALFLIFE
CBlockPolicyEstimator::_removeTx
bool _removeTx(const uint256 &hash, bool inBlock) EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
A non-thread-safe helper for the removeTx function.
Definition: fees.cpp:515
amount.h
CBlockPolicyEstimator::DOUBLE_SUCCESS_PCT
static constexpr double DOUBLE_SUCCESS_PCT
Require greater than 95% of X feerate transactions to be confirmed within 2 * Y blocks.
Definition: fees.h:159
ALL_FEE_ESTIMATE_HORIZONS
static constexpr auto ALL_FEE_ESTIMATE_HORIZONS
Definition: fees.h:35
CBlockPolicyEstimator::processTransaction
void processTransaction(const CTxMemPoolEntry &entry, bool validFeeEstimate) EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Process a transaction accepted to the mempool.
Definition: fees.cpp:557
FastRandomContext
Fast randomness source.
Definition: random.h:142
EstimatorBucket::totalConfirmed
double totalConfirmed
Definition: fees.h:62