You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

fees.h 13KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  1. // Copyright (c) 2009-2010 Satoshi Nakamoto
  2. // Copyright (c) 2009-2015 The Bitcoin 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_POLICYESTIMATOR_H
  6. #define BITCOIN_POLICYESTIMATOR_H
  7. #include "amount.h"
  8. #include "uint256.h"
  9. #include <map>
  10. #include <string>
  11. #include <vector>
  12. class CAutoFile;
  13. class CFeeRate;
  14. class CTxMemPoolEntry;
  15. class CTxMemPool;
  16. /** \class CBlockPolicyEstimator
  17. * The BlockPolicyEstimator is used for estimating the fee or priority needed
  18. * for a transaction to be included in a block within a certain number of
  19. * blocks.
  20. *
  21. * At a high level the algorithm works by grouping transactions into buckets
  22. * based on having similar priorities or fees and then tracking how long it
  23. * takes transactions in the various buckets to be mined. It operates under
  24. * the assumption that in general transactions of higher fee/priority will be
  25. * included in blocks before transactions of lower fee/priority. So for
  26. * example if you wanted to know what fee you should put on a transaction to
  27. * be included in a block within the next 5 blocks, you would start by looking
  28. * at the bucket with the highest fee transactions and verifying that a
  29. * sufficiently high percentage of them were confirmed within 5 blocks and
  30. * then you would look at the next highest fee bucket, and so on, stopping at
  31. * the last bucket to pass the test. The average fee of transactions in this
  32. * bucket will give you an indication of the lowest fee you can put on a
  33. * transaction and still have a sufficiently high chance of being confirmed
  34. * within your desired 5 blocks.
  35. *
  36. * When a transaction enters the mempool or is included within a block we
  37. * decide whether it can be used as a data point for fee estimation, priority
  38. * estimation or neither. If the value of exactly one of those properties was
  39. * below the required minimum it can be used to estimate the other. In
  40. * addition, if a priori our estimation code would indicate that the
  41. * transaction would be much more quickly included in a block because of one
  42. * of the properties compared to the other, we can also decide to use it as
  43. * an estimate for that property.
  44. *
  45. * Here is a brief description of the implementation for fee estimation.
  46. * When a transaction that counts for fee estimation enters the mempool, we
  47. * track the height of the block chain at entry. Whenever a block comes in,
  48. * we count the number of transactions in each bucket and the total amount of fee
  49. * paid in each bucket. Then we calculate how many blocks Y it took each
  50. * transaction to be mined and we track an array of counters in each bucket
  51. * for how long it to took transactions to get confirmed from 1 to a max of 25
  52. * and we increment all the counters from Y up to 25. This is because for any
  53. * number Z>=Y the transaction was successfully mined within Z blocks. We
  54. * want to save a history of this information, so at any time we have a
  55. * counter of the total number of transactions that happened in a given fee
  56. * bucket and the total number that were confirmed in each number 1-25 blocks
  57. * or less for any bucket. We save this history by keeping an exponentially
  58. * decaying moving average of each one of these stats. Furthermore we also
  59. * keep track of the number unmined (in mempool) transactions in each bucket
  60. * and for how many blocks they have been outstanding and use that to increase
  61. * the number of transactions we've seen in that fee bucket when calculating
  62. * an estimate for any number of confirmations below the number of blocks
  63. * they've been outstanding.
  64. */
  65. /**
  66. * We will instantiate two instances of this class, one to track transactions
  67. * that were included in a block due to fee, and one for tx's included due to
  68. * priority. We will lump transactions into a bucket according to their approximate
  69. * fee or priority and then track how long it took for those txs to be included in a block
  70. *
  71. * The tracking of unconfirmed (mempool) transactions is completely independent of the
  72. * historical tracking of transactions that have been confirmed in a block.
  73. */
  74. class TxConfirmStats
  75. {
  76. private:
  77. //Define the buckets we will group transactions into (both fee buckets and priority buckets)
  78. std::vector<double> buckets; // The upper-bound of the range for the bucket (inclusive)
  79. std::map<double, unsigned int> bucketMap; // Map of bucket upper-bound to index into all vectors by bucket
  80. // For each bucket X:
  81. // Count the total # of txs in each bucket
  82. // Track the historical moving average of this total over blocks
  83. std::vector<double> txCtAvg;
  84. // and calculate the total for the current block to update the moving average
  85. std::vector<int> curBlockTxCt;
  86. // Count the total # of txs confirmed within Y blocks in each bucket
  87. // Track the historical moving average of theses totals over blocks
  88. std::vector<std::vector<double> > confAvg; // confAvg[Y][X]
  89. // and calculate the totals for the current block to update the moving averages
  90. std::vector<std::vector<int> > curBlockConf; // curBlockConf[Y][X]
  91. // Sum the total priority/fee of all tx's in each bucket
  92. // Track the historical moving average of this total over blocks
  93. std::vector<double> avg;
  94. // and calculate the total for the current block to update the moving average
  95. std::vector<double> curBlockVal;
  96. // Combine the conf counts with tx counts to calculate the confirmation % for each Y,X
  97. // Combine the total value with the tx counts to calculate the avg fee/priority per bucket
  98. std::string dataTypeString;
  99. double decay;
  100. // Mempool counts of outstanding transactions
  101. // For each bucket X, track the number of transactions in the mempool
  102. // that are unconfirmed for each possible confirmation value Y
  103. std::vector<std::vector<int> > unconfTxs; //unconfTxs[Y][X]
  104. // transactions still unconfirmed after MAX_CONFIRMS for each bucket
  105. std::vector<int> oldUnconfTxs;
  106. public:
  107. /**
  108. * Initialize the data structures. This is called by BlockPolicyEstimator's
  109. * constructor with default values.
  110. * @param defaultBuckets contains the upper limits for the bucket boundaries
  111. * @param maxConfirms max number of confirms to track
  112. * @param decay how much to decay the historical moving average per block
  113. * @param dataTypeString for logging purposes
  114. */
  115. void Initialize(std::vector<double>& defaultBuckets, unsigned int maxConfirms, double decay, std::string dataTypeString);
  116. /** Clear the state of the curBlock variables to start counting for the new block */
  117. void ClearCurrent(unsigned int nBlockHeight);
  118. /**
  119. * Record a new transaction data point in the current block stats
  120. * @param blocksToConfirm the number of blocks it took this transaction to confirm
  121. * @param val either the fee or the priority when entered of the transaction
  122. * @warning blocksToConfirm is 1-based and has to be >= 1
  123. */
  124. void Record(int blocksToConfirm, double val);
  125. /** Record a new transaction entering the mempool*/
  126. unsigned int NewTx(unsigned int nBlockHeight, double val);
  127. /** Remove a transaction from mempool tracking stats*/
  128. void removeTx(unsigned int entryHeight, unsigned int nBestSeenHeight,
  129. unsigned int bucketIndex);
  130. /** Update our estimates by decaying our historical moving average and updating
  131. with the data gathered from the current block */
  132. void UpdateMovingAverages();
  133. /**
  134. * Calculate a fee or priority estimate. Find the lowest value bucket (or range of buckets
  135. * to make sure we have enough data points) whose transactions still have sufficient likelihood
  136. * of being confirmed within the target number of confirmations
  137. * @param confTarget target number of confirmations
  138. * @param sufficientTxVal required average number of transactions per block in a bucket range
  139. * @param minSuccess the success probability we require
  140. * @param requireGreater return the lowest fee/pri such that all higher values pass minSuccess OR
  141. * return the highest fee/pri such that all lower values fail minSuccess
  142. * @param nBlockHeight the current block height
  143. */
  144. double EstimateMedianVal(int confTarget, double sufficientTxVal,
  145. double minSuccess, bool requireGreater, unsigned int nBlockHeight);
  146. /** Return the max number of confirms we're tracking */
  147. unsigned int GetMaxConfirms() { return confAvg.size(); }
  148. /** Write state of estimation data to a file*/
  149. void Write(CAutoFile& fileout);
  150. /**
  151. * Read saved state of estimation data from a file and replace all internal data structures and
  152. * variables with this state.
  153. */
  154. void Read(CAutoFile& filein);
  155. };
  156. /** Track confirm delays up to 25 blocks, can't estimate beyond that */
  157. static const unsigned int MAX_BLOCK_CONFIRMS = 25;
  158. /** Decay of .998 is a half-life of 346 blocks or about 2.4 days */
  159. static const double DEFAULT_DECAY = .998;
  160. /** Require greater than 95% of X fee transactions to be confirmed within Y blocks for X to be big enough */
  161. static const double MIN_SUCCESS_PCT = .95;
  162. static const double UNLIKELY_PCT = .5;
  163. /** Require an avg of 1 tx in the combined fee bucket per block to have stat significance */
  164. static const double SUFFICIENT_FEETXS = 1;
  165. /** Require only an avg of 1 tx every 5 blocks in the combined pri bucket (way less pri txs) */
  166. static const double SUFFICIENT_PRITXS = .2;
  167. // Minimum and Maximum values for tracking fees and priorities
  168. static const double MIN_FEERATE = 10;
  169. static const double MAX_FEERATE = 1e7;
  170. static const double INF_FEERATE = MAX_MONEY;
  171. static const double MIN_PRIORITY = 10;
  172. static const double MAX_PRIORITY = 1e16;
  173. static const double INF_PRIORITY = 1e9 * MAX_MONEY;
  174. // We have to lump transactions into buckets based on fee or priority, but we want to be able
  175. // to give accurate estimates over a large range of potential fees and priorities
  176. // Therefore it makes sense to exponentially space the buckets
  177. /** Spacing of FeeRate buckets */
  178. static const double FEE_SPACING = 1.1;
  179. /** Spacing of Priority buckets */
  180. static const double PRI_SPACING = 2;
  181. /**
  182. * We want to be able to estimate fees or priorities that are needed on tx's to be included in
  183. * a certain number of blocks. Every time a block is added to the best chain, this class records
  184. * stats on the transactions included in that block
  185. */
  186. class CBlockPolicyEstimator
  187. {
  188. public:
  189. /** Create new BlockPolicyEstimator and initialize stats tracking classes with default values */
  190. CBlockPolicyEstimator(const CFeeRate& minRelayFee);
  191. /** Process all the transactions that have been included in a block */
  192. void processBlock(unsigned int nBlockHeight,
  193. std::vector<CTxMemPoolEntry>& entries, bool fCurrentEstimate);
  194. /** Process a transaction confirmed in a block*/
  195. void processBlockTx(unsigned int nBlockHeight, const CTxMemPoolEntry& entry);
  196. /** Process a transaction accepted to the mempool*/
  197. void processTransaction(const CTxMemPoolEntry& entry, bool fCurrentEstimate);
  198. /** Remove a transaction from the mempool tracking stats*/
  199. void removeTx(uint256 hash);
  200. /** Is this transaction likely included in a block because of its fee?*/
  201. bool isFeeDataPoint(const CFeeRate &fee, double pri);
  202. /** Is this transaction likely included in a block because of its priority?*/
  203. bool isPriDataPoint(const CFeeRate &fee, double pri);
  204. /** Return a fee estimate */
  205. CFeeRate estimateFee(int confTarget);
  206. /** Estimate fee rate needed to get be included in a block within
  207. * confTarget blocks. If no answer can be given at confTarget, return an
  208. * estimate at the lowest target where one can be given.
  209. */
  210. CFeeRate estimateSmartFee(int confTarget, int *answerFoundAtTarget, const CTxMemPool& pool);
  211. /** Return a priority estimate */
  212. double estimatePriority(int confTarget);
  213. /** Estimate priority needed to get be included in a block within
  214. * confTarget blocks. If no answer can be given at confTarget, return an
  215. * estimate at the lowest target where one can be given.
  216. */
  217. double estimateSmartPriority(int confTarget, int *answerFoundAtTarget, const CTxMemPool& pool);
  218. /** Write estimation data to a file */
  219. void Write(CAutoFile& fileout);
  220. /** Read estimation data from a file */
  221. void Read(CAutoFile& filein);
  222. private:
  223. CFeeRate minTrackedFee; //!< Passed to constructor to avoid dependency on main
  224. double minTrackedPriority; //!< Set to AllowFreeThreshold
  225. unsigned int nBestSeenHeight;
  226. struct TxStatsInfo
  227. {
  228. TxConfirmStats *stats;
  229. unsigned int blockHeight;
  230. unsigned int bucketIndex;
  231. TxStatsInfo() : stats(NULL), blockHeight(0), bucketIndex(0) {}
  232. };
  233. // map of txids to information about that transaction
  234. std::map<uint256, TxStatsInfo> mapMemPoolTxs;
  235. /** Classes to track historical data on transaction confirmations */
  236. TxConfirmStats feeStats, priStats;
  237. /** Breakpoints to help determine whether a transaction was confirmed by priority or Fee */
  238. CFeeRate feeLikely, feeUnlikely;
  239. double priLikely, priUnlikely;
  240. };
  241. class FeeFilterRounder
  242. {
  243. public:
  244. /** Create new FeeFilterRounder */
  245. FeeFilterRounder(const CFeeRate& minIncrementalFee);
  246. /** Quantize a minimum fee for privacy purpose before broadcast **/
  247. CAmount round(CAmount currentMinFee);
  248. private:
  249. std::set<double> feeset;
  250. };
  251. #endif /*BITCOIN_POLICYESTIMATOR_H */