// Copyright (c) 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_MEMPOOL_ESTIMATOR_H

#define BITCOIN_POLICY_FEES_MEMPOOL_ESTIMATOR_H

#include <primitives/transaction.h>

#include <sync.h>

#include <threadsafety.h>

#include <uint256.h>

#include <util/expected.h>

#include <util/feefrac.h>

#include <util/fees.h>

#include <util/fs.h>

#include <util/time.h>

#include <chrono>

#include <memory>

#include <optional>

#include <span>

#include <vector>

class CBlock;

class AutoFile;

class ChainstateManager;

class CTxMemPool;

struct RemovedMempoolTransactionInfo;

// Fee rate estimate for confirmation target above this is not reliable,

// as mempool conditions are likely to change.

constexpr int MEMPOOL_FEE_ESTIMATOR_MAX_TARGET{2};

constexpr std::chrono::seconds CACHE_LIFE{7};

// Constants for mempool sanity checks.

constexpr size_t MEMPOOL_HEALTH_WINDOW_BLOCKS = 6;

constexpr double MEMPOOL_REPRESENTATION_THRESHOLD = 0.75;

//! Weight statistics for a recently mined block, used to assess mempool coverage.

struct MinedBlockStats {

    //! Block height.

    uint64_t m_height{0};

    //! Weight of mempool transactions removed for this block (excluding coinbase).

    uint64_t m_removed_block_txs_weight{0};

    //! Total non-coinbase transaction weight in the block.

    uint64_t m_block_weight{0};

};

/**

 * MemPoolFeeRateEstimatorCache holds a cache of recent fee rate estimates.

 * A cached fee rate is only provided while it is not older than CACHE_LIFE

 * and the chain tip has not changed.

 */

class MemPoolFeeRateEstimatorCache

{

public:

    MemPoolFeeRateEstimatorCache() = default;

    MemPoolFeeRateEstimatorCache(const MemPoolFeeRateEstimatorCache&) = delete;

    MemPoolFeeRateEstimatorCache& operator=(const MemPoolFeeRateEstimatorCache&) = delete;

    /** Returns true if the cache is empty or older than CACHE_LIFE. */

    bool IsStale() const;

    struct FeeRateEstimate {

        FeePerVSize m_conservative;

        FeePerVSize m_economical;

    };

    /** Returns cached estimates if not stale and computed on tip_hash, nullopt otherwise. */

    std::optional<FeeRateEstimate> GetCachedEstimate(const uint256& tip_hash) const;

    /** Update the cache with new estimates computed on tip_hash. */

    void Update(FeePerVSize conservative, FeePerVSize economical, const uint256& tip_hash);

    /** Clear cached fee rate estimates. */

    void Clear();

private:

    std::optional<FeeRateEstimate> m_fee_rate_estimation;

    uint256 m_tip_hash;

    NodeClock::time_point m_last_updated{};

};

/**

 * Estimate the fee rate required for a transaction to be included in the next block.

 *

 * Uses Bitcoin Core's block-building algorithm to generate a block template from the mempool,

 * then calculates percentile fee rates from the selected chunks: the 75th percentile is returned

 * as the economical estimate and the 50th percentile as the conservative estimate.

 */

class MemPoolFeeRateEstimator

{

public:

    // Block percentiles fee rate (in sat/vB).

    struct Percentiles {

        FeePerVSize p50;

        FeePerVSize p75;

    };

    MemPoolFeeRateEstimator(fs::path mempool_estimator_file_path,

                            const CTxMemPool& mempool,

                            ChainstateManager& chainman);

    ~MemPoolFeeRateEstimator() = default;

    /**

     * Calculate the 50th and 75th percentile fee rates from block template chunks,

     * sorted in descending mining-score order. A percentile is left empty when the

     * chunks cannot cover the corresponding fraction of a block.

     *

     * @param[in] chunk_feerates Block template chunk fee rates sorted by descending mining score.

     */

    static Percentiles CalculateMaxWeightPercentiles(std::span<const FeePerVSize> chunk_feerates);

    util::Expected<FeeRateEstimation, FeeRateEstimationError> EstimateFeeRate(bool conservative) const

        EXCLUSIVE_LOCKS_REQUIRED(!cs);

    unsigned int MaximumTarget() const

    {

        return MEMPOOL_FEE_ESTIMATOR_MAX_TARGET;

    }

    std::vector<MinedBlockStats> GetPrevBlockData() const EXCLUSIVE_LOCKS_REQUIRED(!cs)

    {

        LOCK(cs);

        return m_prev_mined_blocks;

    }

    void MempoolTxsRemovedForBlock(const std::shared_ptr<const CBlock>& block,

                                   const std::vector<RemovedMempoolTransactionInfo>& txs_removed_for_block,

                                   unsigned int block_height)

        EXCLUSIVE_LOCKS_REQUIRED(!cs);

    //! Health of the recent mined-block window for fee rate estimation.

    enum class MempoolHealth {

        //! Recent blocks represent the mempool well enough to estimate a fee rate.

        HEALTHY,

        //! Too few recent mined blocks to estimate a fee rate.

        INSUFFICIENT_DATA,

        //! Recent blocks include too few mempool transactions to estimate a fee rate.

        LOW_COVERAGE,

    };

    MempoolHealth GetMempoolHealth() const EXCLUSIVE_LOCKS_REQUIRED(!cs);

    //! Checks if recent mined blocks indicate a healthy mempool state.

    bool IsMempoolHealthy() const EXCLUSIVE_LOCKS_REQUIRED(!cs) { return GetMempoolHealth() == MempoolHealth::HEALTHY; }

    void FlushMinedBlockStats() EXCLUSIVE_LOCKS_REQUIRED(!cs);

    //! Deserialize mined-block stats without taking ownership of file.

    bool Read(AutoFile& file) EXCLUSIVE_LOCKS_REQUIRED(!cs);

    //! Serialize mined-block stats without taking ownership of file.

    //! Callers must explicitly close file and check for errors after writing.

    bool Write(AutoFile& file) const EXCLUSIVE_LOCKS_REQUIRED(!cs);

private:

    void ReadFromDisk() EXCLUSIVE_LOCKS_REQUIRED(!cs);

    //! Tracks weight statistics for the last MEMPOOL_HEALTH_WINDOW_BLOCKS mined blocks.

    std::vector<MinedBlockStats> m_prev_mined_blocks GUARDED_BY(cs);

    uint256 m_mined_blocks_tip_hash GUARDED_BY(cs);

    const CTxMemPool& m_mempool;

    ChainstateManager& m_chainman;

    mutable Mutex cs;

    mutable MemPoolFeeRateEstimatorCache m_cache GUARDED_BY(cs);

    const fs::path m_mempool_estimator_file_path;

};

#endif // BITCOIN_POLICY_FEES_MEMPOOL_ESTIMATOR_H