[#CBlockPolicyEstimator]
= CBlockPolicyEstimator
:mrdocs:

The BlockPolicyEstimator is used for estimating the feerate needed for a transaction to be included in a block within a certain number of blocks&period;

== Synopsis

Declared in `&lt;policy&sol;fees&sol;block&lowbar;policy&lowbar;estimator&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class CBlockPolicyEstimator;
----

== Description

At a high level the algorithm works by grouping transactions into buckets based on having similar feerates and then tracking how long it takes transactions in the various buckets to be mined&period; It operates under the assumption that in general transactions of higher feerate will be included in blocks before transactions of lower feerate&period; So for example if you wanted to know what feerate you should put on a transaction to be included in a block within the next 5 blocks, you would start by looking at the bucket with the highest feerate transactions and verifying that a sufficiently high percentage of them were confirmed within 5 blocks and then you would look at the next highest feerate bucket, and so on, stopping at the last bucket to pass the test&period; The average feerate of transactions in this bucket will give you an indication of the lowest feerate you can put on a transaction and still have a sufficiently high chance of being confirmed within your desired 5 blocks&period;

Here is a brief description of the implementation&colon; When a transaction enters the mempool, we track the height of the block chain at entry&period; All further calculations are conducted only on this set of &quot;seen&quot; transactions&period; Whenever a block comes in, we count the number of transactions in each bucket and the total amount of feerate paid in each bucket&period; Then we calculate how many blocks Y it took each transaction to be mined&period; We convert from a number of blocks to a number of periods Y&apos; each encompassing &quot;scale&quot; blocks&period; This is tracked in 3 different data sets each up to a maximum number of periods&period; Within each data set we have an array of counters in each feerate bucket and we increment all the counters from Y&apos; up to max periods representing that a tx was successfully confirmed in less than or equal to that many periods&period; We want to save a history of this information, so at any time we have a counter of the total number of transactions that happened in a given feerate bucket and the total number that were confirmed in each of the periods or less for any bucket&period; We save this history by keeping an exponentially decaying moving average of each one of these stats&period; This is done for a different decay in each of the 3 data sets to keep relevant data from different time horizons&period; Furthermore we also keep track of the number unmined (in mempool or left mempool without being included in a block) transactions in each bucket and for how many blocks they have been outstanding and use both of these numbers to increase the number of transactions we&apos;ve seen in that feerate bucket when calculating an estimate for any number of confirmations below the number of blocks they&apos;ve been outstanding&period;

We want to be able to estimate feerates that are needed on tx&apos;s to be included in a certain number of blocks&period; Every time a block is added to the best chain, this class records stats on the transactions included in that block

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:CBlockPolicyEstimator/2constructor.adoc[`CBlockPolicyEstimator`]         [.small]#[constructor]#
| Create new BlockPolicyEstimator and initialize stats tracking classes with default values&period;
| xref:CBlockPolicyEstimator/2destructor.adoc[`&#126;CBlockPolicyEstimator`] [.small]#[destructor]# [.small]#[virtual]#
| Destroy the estimator and release its tracking stats&period;
| xref:CBlockPolicyEstimator/EstimateFeeRate.adoc[`EstimateFeeRate`] 
| Estimate the feerate needed to confirm within `target` blocks&semi; wraps estimateSmartFee into a FeeRateEstimation&period;
| xref:CBlockPolicyEstimator/Flush.adoc[`Flush`] 
| Drop still unconfirmed transactions and record current estimations, if the fee estimation file is present&period;
| xref:CBlockPolicyEstimator/FlushFeeEstimates.adoc[`FlushFeeEstimates`] 
| Record current fee estimations&period;
| xref:CBlockPolicyEstimator/FlushUnconfirmed.adoc[`FlushUnconfirmed`] 
| Empty mempool transactions on shutdown to record failure to confirm for txs still in mempool
| xref:CBlockPolicyEstimator/GetFeeEstimatorFileAge.adoc[`GetFeeEstimatorFileAge`] 
| Calculates the age of the file, since last modified&period;
| xref:CBlockPolicyEstimator/HighestTargetTracked.adoc[`HighestTargetTracked`]  [.small]#[virtual]#
| Calculation of highest target that estimates are tracked for&period;
| xref:CBlockPolicyEstimator/MaximumTarget.adoc[`MaximumTarget`] 
| Return the highest confirmation target for which an estimate can be provided&period;
| xref:CBlockPolicyEstimator/Read.adoc[`Read`] 
| Read estimation data from a file&period;
| xref:CBlockPolicyEstimator/Write.adoc[`Write`] 
| Write estimation data to a file&period;
| xref:CBlockPolicyEstimator/estimateFee.adoc[`estimateFee`] 
| DEPRECATED&period; Return a feerate estimate&period;
| xref:CBlockPolicyEstimator/estimateRawFee.adoc[`estimateRawFee`] 
| Return a specific fee estimate calculation with a given success threshold and time horizon, and optionally return detailed data about calculation&period;
| xref:CBlockPolicyEstimator/estimateSmartFee.adoc[`estimateSmartFee`]  [.small]#[virtual]#
| Estimate feerate needed to get be included in a block within confTarget blocks&period; If no answer can be given at confTarget, return an estimate at the closest target where one can be given&period; &apos;conservative&apos; estimates are valid over longer time horizons also&period;
| xref:CBlockPolicyEstimator/processBlock.adoc[`processBlock`] 
| Process all the transactions that have been included in a block&period;
| xref:CBlockPolicyEstimator/processTransaction.adoc[`processTransaction`] 
| Process a transaction accepted to the mempool&period;
| xref:CBlockPolicyEstimator/removeTx.adoc[`removeTx`] 
| Remove a transaction from the mempool tracking stats for non BLOCK removal reasons&period;
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#
