Bitcoin Core  21.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-2020 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 <amount.h>
9 #include <policy/feerate.h>
10 #include <uint256.h>
11 #include <random.h>
12 #include <sync.h>
13 
14 #include <array>
15 #include <map>
16 #include <memory>
17 #include <string>
18 #include <vector>
19 
20 class CAutoFile;
21 class CFeeRate;
22 class CTxMemPoolEntry;
23 class CTxMemPool;
24 class TxConfirmStats;
25 
26 /* Identifier for each of the 3 different TxConfirmStats which will track
27  * history over different time horizons. */
28 enum class FeeEstimateHorizon {
32 };
33 
34 static constexpr auto ALL_FEE_ESTIMATE_HORIZONS = std::array{
38 };
39 
41 
42 /* Enumeration of reason for returned fee estimate */
43 enum class FeeReason {
44  NONE,
50  PAYTXFEE,
51  FALLBACK,
52  REQUIRED,
53 };
54 
55 /* Used to return detailed information about a feerate bucket */
57 {
58  double start = -1;
59  double end = -1;
60  double withinTarget = 0;
61  double totalConfirmed = 0;
62  double inMempool = 0;
63  double leftMempool = 0;
64 };
65 
66 /* Used to return detailed information about a fee estimate calculation */
68 {
71  double decay = 0;
72  unsigned int scale = 0;
73 };
74 
76 {
79  int desiredTarget = 0;
80  int returnedTarget = 0;
81 };
82 
132 {
133 private:
135  static constexpr unsigned int SHORT_BLOCK_PERIODS = 12;
136  static constexpr unsigned int SHORT_SCALE = 1;
138  static constexpr unsigned int MED_BLOCK_PERIODS = 24;
139  static constexpr unsigned int MED_SCALE = 2;
141  static constexpr unsigned int LONG_BLOCK_PERIODS = 42;
142  static constexpr unsigned int LONG_SCALE = 24;
144  static const unsigned int OLDEST_ESTIMATE_HISTORY = 6 * 1008;
145 
147  static constexpr double SHORT_DECAY = .962;
149  static constexpr double MED_DECAY = .9952;
151  static constexpr double LONG_DECAY = .99931;
152 
154  static constexpr double HALF_SUCCESS_PCT = .6;
156  static constexpr double SUCCESS_PCT = .85;
158  static constexpr double DOUBLE_SUCCESS_PCT = .95;
159 
161  static constexpr double SUFFICIENT_FEETXS = 0.1;
163  static constexpr double SUFFICIENT_TXS_SHORT = 0.5;
164 
172  static constexpr double MIN_BUCKET_FEERATE = 1000;
173  static constexpr double MAX_BUCKET_FEERATE = 1e7;
174 
180  static constexpr double FEE_SPACING = 1.05;
181 
182 public:
186 
188  void processBlock(unsigned int nBlockHeight,
189  std::vector<const CTxMemPoolEntry*>& entries);
190 
192  void processTransaction(const CTxMemPoolEntry& entry, bool validFeeEstimate);
193 
195  bool removeTx(uint256 hash, bool inBlock);
196 
198  CFeeRate estimateFee(int confTarget) const;
199 
205  CFeeRate estimateSmartFee(int confTarget, FeeCalculation *feeCalc, bool conservative) const;
206 
211  CFeeRate estimateRawFee(int confTarget, double successThreshold, FeeEstimateHorizon horizon, EstimationResult *result = nullptr) const;
212 
214  bool Write(CAutoFile& fileout) const;
215 
217  bool Read(CAutoFile& filein);
218 
220  void FlushUnconfirmed();
221 
223  unsigned int HighestTargetTracked(FeeEstimateHorizon horizon) const;
224 
226  void Flush();
227 
228 private:
230 
231  unsigned int nBestSeenHeight GUARDED_BY(m_cs_fee_estimator);
232  unsigned int firstRecordedHeight GUARDED_BY(m_cs_fee_estimator);
233  unsigned int historicalFirst GUARDED_BY(m_cs_fee_estimator);
234  unsigned int historicalBest GUARDED_BY(m_cs_fee_estimator);
235 
236  struct TxStatsInfo
237  {
238  unsigned int blockHeight;
239  unsigned int bucketIndex;
241  };
242 
243  // map of txids to information about that transaction
244  std::map<uint256, TxStatsInfo> mapMemPoolTxs GUARDED_BY(m_cs_fee_estimator);
245 
247  std::unique_ptr<TxConfirmStats> feeStats PT_GUARDED_BY(m_cs_fee_estimator);
248  std::unique_ptr<TxConfirmStats> shortStats PT_GUARDED_BY(m_cs_fee_estimator);
249  std::unique_ptr<TxConfirmStats> longStats PT_GUARDED_BY(m_cs_fee_estimator);
250 
251  unsigned int trackedTxs GUARDED_BY(m_cs_fee_estimator);
252  unsigned int untrackedTxs GUARDED_BY(m_cs_fee_estimator);
253 
254  std::vector<double> buckets GUARDED_BY(m_cs_fee_estimator); // The upper-bound of the range for the bucket (inclusive)
255  std::map<double, unsigned int> bucketMap GUARDED_BY(m_cs_fee_estimator); // Map of bucket upper-bound to index into all vectors by bucket
256 
258  bool processBlockTx(unsigned int nBlockHeight, const CTxMemPoolEntry* entry) EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
259 
261  double estimateCombinedFee(unsigned int confTarget, double successThreshold, bool checkShorterHorizon, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
263  double estimateConservativeFee(unsigned int doubleTarget, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
270 };
271 
273 {
274 private:
275  static constexpr double MAX_FILTER_FEERATE = 1e7;
280  static constexpr double FEE_FILTER_SPACING = 1.1;
281 
282 public:
284  explicit FeeFilterRounder(const CFeeRate& minIncrementalFee);
285 
287  CAmount round(CAmount currentMinFee);
288 
289 private:
290  std::set<double> feeset;
292 };
293 
294 #endif // BITCOIN_POLICY_FEES_H
CBlockPolicyEstimator::~CBlockPolicyEstimator
~CBlockPolicyEstimator()
Definition: fees.cpp:514
CBlockPolicyEstimator::MED_SCALE
static constexpr unsigned int MED_SCALE
Definition: fees.h:139
FeeFilterRounder::feeset
std::set< double > feeset
Definition: fees.h:290
EstimatorBucket::inMempool
double inMempool
Definition: fees.h:62
CBlockPolicyEstimator::CBlockPolicyEstimator
CBlockPolicyEstimator()
Create new BlockPolicyEstimator and initialize stats tracking classes with default values.
Definition: fees.cpp:488
FeeReason
FeeReason
Definition: fees.h:43
feerate.h
CBlockPolicyEstimator::processTransaction
void processTransaction(const CTxMemPoolEntry &entry, bool validFeeEstimate)
Process a transaction accepted to the mempool.
Definition: fees.cpp:518
EstimatorBucket::start
double start
Definition: fees.h:58
EstimatorBucket::leftMempool
double leftMempool
Definition: fees.h:63
CBlockPolicyEstimator::Flush
void Flush()
Drop still unconfirmed transactions and record current estimations, if the fee estimation file is pre...
Definition: fees.cpp:864
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:180
FeeCalculation::est
EstimationResult est
Definition: fees.h:77
FeeFilterRounder::insecure_rand
FastRandomContext insecure_rand
Definition: fees.h:291
FeeEstimateHorizon
FeeEstimateHorizon
Definition: fees.h:28
sync.h
FeeCalculation::returnedTarget
int returnedTarget
Definition: fees.h:80
CTxMemPool
CTxMemPool stores valid-according-to-the-current-best-chain transactions that may be included in the ...
Definition: txmempool.h:477
uint256.h
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:161
CBlockPolicyEstimator::removeTx
bool removeTx(uint256 hash, bool inBlock)
Remove a transaction from the mempool tracking stats.
Definition: fees.cpp:473
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:557
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:713
CBlockPolicyEstimator::Write
bool Write(CAutoFile &fileout) const
Write estimation data to a file.
Definition: fees.cpp:874
AnnotatedMixin< std::recursive_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:703
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:156
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:138
FeeReason::NONE
@ NONE
CFeeRate
Fee rate in satoshis per kilobyte: CAmount / kB.
Definition: feerate.h:29
CBlockPolicyEstimator::estimateConservativeFee
double estimateConservativeFee(unsigned int doubleTarget, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator)
Helper for estimateSmartFee.
Definition: fees.cpp:762
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:163
EstimatorBucket::end
double end
Definition: fees.h:59
FeeCalculation::desiredTarget
int desiredTarget
Definition: fees.h:79
CBlockPolicyEstimator::FlushUnconfirmed
void FlushUnconfirmed()
Empty mempool transactions on shutdown to record failure to confirm for txs still in mempool.
Definition: fees.cpp:961
CBlockPolicyEstimator::LONG_SCALE
static constexpr unsigned int LONG_SCALE
Definition: fees.h:142
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:149
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:172
CBlockPolicyEstimator::SHORT_SCALE
static constexpr unsigned int SHORT_SCALE
Definition: fees.h:136
CAutoFile
Non-refcounted RAII wrapper for FILE*.
Definition: streams.h:564
FeeCalculation::reason
FeeReason reason
Definition: fees.h:78
CBlockPolicyEstimator::estimateSmartFee
CFeeRate estimateSmartFee(int confTarget, FeeCalculation *feeCalc, bool conservative) const
Estimate feerate needed to get be included in a block within confTarget blocks.
Definition: fees.cpp:786
FeeEstimateHorizon::LONG_HALFLIFE
@ LONG_HALFLIFE
FeeCalculation
Definition: fees.h:75
random.h
EstimationResult::decay
double decay
Definition: fees.h:71
EstimationResult
Definition: fees.h:67
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:723
CBlockPolicyEstimator::estimateRawFee
CFeeRate estimateRawFee(int confTarget, double successThreshold, FeeEstimateHorizon horizon, EstimationResult *result=nullptr) const
Return a specific fee estimate calculation with a given success threshold and time horizon,...
Definition: fees.cpp:642
CBlockPolicyEstimator::TxStatsInfo
Definition: fees.h:236
CBlockPolicyEstimator::MAX_BUCKET_FEERATE
static constexpr double MAX_BUCKET_FEERATE
Definition: fees.h:173
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:72
CBlockPolicyEstimator::m_cs_fee_estimator
RecursiveMutex m_cs_fee_estimator
Definition: fees.h:229
CBlockPolicyEstimator::TxStatsInfo::blockHeight
unsigned int blockHeight
Definition: fees.h:238
TxConfirmStats
We will instantiate an instance of this class to track transactions that were included in a block.
Definition: fees.cpp:37
CBlockPolicyEstimator
Definition: fees.h:131
CAmount
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
FeeFilterRounder
Definition: fees.h:272
CBlockPolicyEstimator::HighestTargetTracked
unsigned int HighestTargetTracked(FeeEstimateHorizon horizon) const
Calculation of highest target that estimates are tracked for.
Definition: fees.cpp:678
EstimatorBucket
Definition: fees.h:56
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:147
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:151
CBlockPolicyEstimator::GUARDED_BY
unsigned int nBestSeenHeight GUARDED_BY(m_cs_fee_estimator)
uint256
256-bit opaque blob.
Definition: uint256.h:124
FeeReason::REQUIRED
@ REQUIRED
FeeEstimateMode::CONSERVATIVE
@ CONSERVATIVE
Force estimateSmartFee to use conservative estimates.
CBlockPolicyEstimator::LONG_BLOCK_PERIODS
static constexpr unsigned int LONG_BLOCK_PERIODS
Track confirm delays up to 1008 blocks for long horizon.
Definition: fees.h:141
CBlockPolicyEstimator::SHORT_BLOCK_PERIODS
static constexpr unsigned int SHORT_BLOCK_PERIODS
Track confirm delays up to 12 blocks for short horizon.
Definition: fees.h:135
EstimationResult::fail
EstimatorBucket fail
Definition: fees.h:70
EXCLUSIVE_LOCKS_REQUIRED
#define EXCLUSIVE_LOCKS_REQUIRED(...)
Definition: threadsafety.h:49
CTxMemPoolEntry
Definition: txmempool.h:81
StringForFeeEstimateHorizon
std::string StringForFeeEstimateHorizon(FeeEstimateHorizon horizon)
Definition: fees.cpp:19
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:144
CBlockPolicyEstimator::TxStatsInfo::bucketIndex
unsigned int bucketIndex
Definition: fees.h:239
EstimatorBucket::withinTarget
double withinTarget
Definition: fees.h:60
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:154
CBlockPolicyEstimator::estimateFee
CFeeRate estimateFee(int confTarget) const
DEPRECATED.
Definition: fees.cpp:633
EstimationResult::pass
EstimatorBucket pass
Definition: fees.h:69
FeeEstimateHorizon::SHORT_HALFLIFE
@ SHORT_HALFLIFE
FeeReason::HALF_ESTIMATE
@ HALF_ESTIMATE
CBlockPolicyEstimator::processBlock
void processBlock(unsigned int nBlockHeight, std::vector< const CTxMemPoolEntry * > &entries)
Process all the transactions that have been included in a block.
Definition: fees.cpp:584
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:695
CBlockPolicyEstimator::TxStatsInfo::TxStatsInfo
TxStatsInfo()
Definition: fees.h:240
CBlockPolicyEstimator::Read
bool Read(CAutoFile &filein)
Read estimation data from a file.
Definition: fees.cpp:899
FeeEstimateHorizon::MED_HALFLIFE
@ MED_HALFLIFE
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:158
ALL_FEE_ESTIMATE_HORIZONS
static constexpr auto ALL_FEE_ESTIMATE_HORIZONS
Definition: fees.h:34
FastRandomContext
Fast randomness source.
Definition: random.h:119
EstimatorBucket::totalConfirmed
double totalConfirmed
Definition: fees.h:61