block_policy_estimator.h

Go to the documentation of this file.

// Copyright (c) 2009-2010 Satoshi Nakamoto
// Copyright (c) 2009-2022 The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.
#ifndef BITCOIN_POLICY_FEES_BLOCK_POLICY_ESTIMATOR_H
#define BITCOIN_POLICY_FEES_BLOCK_POLICY_ESTIMATOR_H
 
#include <consensus/amount.h>
#include <policy/feerate.h>
#include <random.h>
#include <sync.h>
#include <threadsafety.h>
#include <uint256.h>
#include <util/fs.h>
#include <validationinterface.h>
 
#include <array>
#include <chrono>
#include <map>
#include <memory>
#include <set>
#include <string>
#include <vector>
 
 
// How often to flush fee estimates to fee_estimates.dat.
static constexpr std::chrono::hours FEE_FLUSH_INTERVAL{1};
 
static constexpr std::chrono::hours MAX_FILE_AGE{60};
 
// Whether we allow importing a fee_estimates file older than MAX_FILE_AGE.
static constexpr bool DEFAULT_ACCEPT_STALE_FEE_ESTIMATES{false};
 
class AutoFile;
class TxConfirmStats;
struct RemovedMempoolTransactionInfo;
struct NewMempoolTransactionInfo;
 
/* Identifier for each of the 3 different TxConfirmStats which will track
 * history over different time horizons. */
enum class FeeEstimateHorizon {
    SHORT_HALFLIFE,
    MED_HALFLIFE,
    LONG_HALFLIFE,
};
 
static constexpr auto ALL_FEE_ESTIMATE_HORIZONS = std::array{
    FeeEstimateHorizon::SHORT_HALFLIFE,
    FeeEstimateHorizon::MED_HALFLIFE,
    FeeEstimateHorizon::LONG_HALFLIFE,
};
 
std::string StringForFeeEstimateHorizon(FeeEstimateHorizon horizon);
 
/* Enumeration of reason for returned fee estimate */
enum class FeeReason {
    NONE,
    HALF_ESTIMATE,
    FULL_ESTIMATE,
    DOUBLE_ESTIMATE,
    CONSERVATIVE,
    MEMPOOL_MIN,
    PAYTXFEE,
    FALLBACK,
    REQUIRED,
};
 
/* Used to return detailed information about a feerate bucket */
struct EstimatorBucket
{
    double start = -1;
    double end = -1;
    double withinTarget = 0;
    double totalConfirmed = 0;
    double inMempool = 0;
    double leftMempool = 0;
};
 
/* Used to return detailed information about a fee estimate calculation */
struct EstimationResult
{
    EstimatorBucket pass;
    EstimatorBucket fail;
    double decay = 0;
    unsigned int scale = 0;
};
 
struct FeeCalculation
{
    EstimationResult est;
    FeeReason reason = FeeReason::NONE;
    int desiredTarget = 0;
    int returnedTarget = 0;
    unsigned int best_height{0};
};
 
class CBlockPolicyEstimator : public CValidationInterface
{
private:
    static constexpr unsigned int SHORT_BLOCK_PERIODS = 12;
    static constexpr unsigned int SHORT_SCALE = 1;
    static constexpr unsigned int MED_BLOCK_PERIODS = 24;
    static constexpr unsigned int MED_SCALE = 2;
    static constexpr unsigned int LONG_BLOCK_PERIODS = 42;
    static constexpr unsigned int LONG_SCALE = 24;
    static const unsigned int OLDEST_ESTIMATE_HISTORY = 6 * 1008;
 
    static constexpr double SHORT_DECAY = .962;
    static constexpr double MED_DECAY = .9952;
    static constexpr double LONG_DECAY = .99931;
 
    static constexpr double HALF_SUCCESS_PCT = .6;
    static constexpr double SUCCESS_PCT = .85;
    static constexpr double DOUBLE_SUCCESS_PCT = .95;
 
    static constexpr double SUFFICIENT_FEETXS = 0.1;
    static constexpr double SUFFICIENT_TXS_SHORT = 0.5;
 
    static constexpr double MIN_BUCKET_FEERATE = 1000;
    static constexpr double MAX_BUCKET_FEERATE = 1e7;
 
    static constexpr double FEE_SPACING = 1.05;
 
    const fs::path m_estimation_filepath;
public:
    CBlockPolicyEstimator(const fs::path& estimation_filepath, const bool read_stale_estimates);
    virtual ~CBlockPolicyEstimator();
 
    void processBlock(const std::vector<RemovedMempoolTransactionInfo>& txs_removed_for_block,
                      unsigned int nBlockHeight)
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    void processTransaction(const NewMempoolTransactionInfo& tx)
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    bool removeTx(Txid hash)
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    CFeeRate estimateFee(int confTarget) const
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    virtual CFeeRate estimateSmartFee(int confTarget, FeeCalculation *feeCalc, bool conservative) const
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    CFeeRate estimateRawFee(int confTarget, double successThreshold, FeeEstimateHorizon horizon,
                            EstimationResult* result = nullptr) const
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    bool Write(AutoFile& fileout) const
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    bool Read(AutoFile& filein)
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    void FlushUnconfirmed()
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    virtual unsigned int HighestTargetTracked(FeeEstimateHorizon horizon) const
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    void Flush()
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    void FlushFeeEstimates()
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
    std::chrono::hours GetFeeEstimatorFileAge();
 
protected:
    void TransactionAddedToMempool(const NewMempoolTransactionInfo& tx, uint64_t /*unused*/) override
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
    void TransactionRemovedFromMempool(const CTransactionRef& tx, MemPoolRemovalReason /*unused*/, uint64_t /*unused*/) override
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
    void MempoolTransactionsRemovedForBlock(const std::vector<RemovedMempoolTransactionInfo>& txs_removed_for_block, unsigned int nBlockHeight) override
        EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator);
 
private:
    mutable Mutex m_cs_fee_estimator;
 
    unsigned int nBestSeenHeight GUARDED_BY(m_cs_fee_estimator){0};
    unsigned int firstRecordedHeight GUARDED_BY(m_cs_fee_estimator){0};
    unsigned int historicalFirst GUARDED_BY(m_cs_fee_estimator){0};
    unsigned int historicalBest GUARDED_BY(m_cs_fee_estimator){0};
 
    struct TxStatsInfo
    {
        unsigned int blockHeight{0};
        unsigned int bucketIndex{0};
        TxStatsInfo() = default;
    };
 
    // map of txids to information about that transaction
    std::map<Txid, TxStatsInfo> mapMemPoolTxs GUARDED_BY(m_cs_fee_estimator);
 
    std::unique_ptr<TxConfirmStats> feeStats PT_GUARDED_BY(m_cs_fee_estimator);
    std::unique_ptr<TxConfirmStats> shortStats PT_GUARDED_BY(m_cs_fee_estimator);
    std::unique_ptr<TxConfirmStats> longStats PT_GUARDED_BY(m_cs_fee_estimator);
 
    unsigned int trackedTxs GUARDED_BY(m_cs_fee_estimator){0};
    unsigned int untrackedTxs GUARDED_BY(m_cs_fee_estimator){0};
 
    std::vector<double> buckets GUARDED_BY(m_cs_fee_estimator); // The upper-bound of the range for the bucket (inclusive)
    std::map<double, unsigned int> bucketMap GUARDED_BY(m_cs_fee_estimator); // Map of bucket upper-bound to index into all vectors by bucket
 
    bool processBlockTx(unsigned int nBlockHeight, const RemovedMempoolTransactionInfo& tx) EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
 
    double estimateCombinedFee(unsigned int confTarget, double successThreshold, bool checkShorterHorizon, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
    double estimateConservativeFee(unsigned int doubleTarget, EstimationResult *result) const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
    unsigned int BlockSpan() const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
    unsigned int HistoricalBlockSpan() const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
    unsigned int MaxUsableEstimate() const EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
 
    bool _removeTx(const Txid& hash, bool inBlock)
        EXCLUSIVE_LOCKS_REQUIRED(m_cs_fee_estimator);
};
 
class FeeFilterRounder
{
private:
    static constexpr double MAX_FILTER_FEERATE = 1e7;
    static constexpr double FEE_FILTER_SPACING = 1.1;
 
public:
    explicit FeeFilterRounder(const CFeeRate& min_incremental_fee, FastRandomContext& rng);
 
    CAmount round(CAmount currentMinFee) EXCLUSIVE_LOCKS_REQUIRED(!m_insecure_rand_mutex);
 
private:
    const std::set<double> m_fee_set;
    Mutex m_insecure_rand_mutex;
    FastRandomContext& insecure_rand GUARDED_BY(m_insecure_rand_mutex);
};
 
#endif // BITCOIN_POLICY_FEES_BLOCK_POLICY_ESTIMATOR_H