Branch data     Line data    Source code

       1                 :             : // Copyright (c) The Bitcoin Core developers
       2                 :             : // Distributed under the MIT software license, see the accompanying
       3                 :             : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
       4                 :             : 
       5                 :             : #ifndef BITCOIN_UTIL_FEES_H
       6                 :             : #define BITCOIN_UTIL_FEES_H
       7                 :             : 
       8                 :             : #include <attributes.h>
       9                 :             : #include <util/expected.h>
      10                 :             : #include <util/feefrac.h>
      11                 :             : 
      12                 :             : #include <optional>
      13                 :             : #include <string>
      14                 :             : #include <string_view>
      15                 :             : #include <utility>
      16                 :             : 
      17                 :             : /* Used to determine type of fee estimation requested */
      18                 :             : enum class FeeEstimateMode {
      19                 :             :     UNSET,        //!< Use default settings based on other criteria
      20                 :             :     ECONOMICAL,   //!< Force Fee rate estimator to return non-conservative estimates
      21                 :             :     CONSERVATIVE, //!< Force Fee rate estimator to return conservative estimates
      22                 :             : };
      23                 :             : 
      24                 :             : /* Used to determine the reason a wallet selected a transaction fee rate */
      25                 :             : enum class FeeReason {
      26                 :             :     FEE_RATE_ESTIMATOR,
      27                 :             :     MEMPOOL_MIN,
      28                 :             :     USER_SPECIFIED,
      29                 :             :     FALLBACK,
      30                 :             :     REQUIRED,
      31                 :             : };
      32                 :             : 
      33                 :             : /**
      34                 :             :  * @enum FeeRateEstimatorType
      35                 :             :  * Identifier for fee rate estimator.
      36                 :             :  */
      37                 :             : enum class FeeRateEstimatorType {
      38                 :             :     AUTO,
      39                 :             :     BLOCK_POLICY,
      40                 :             :     MEMPOOL_POLICY,
      41                 :             : };
      42                 :             : 
      43                 :             : /**
      44                 :             :  * @struct FeeRateEstimation
      45                 :             :  * A successful fee rate estimate returned by a fee rate estimator.
      46                 :             :  */
      47                 :             : struct FeeRateEstimation {
      48                 :             :     //! This identifies which fee rate estimator is providing this feerate estimate
      49                 :             :     FeeRateEstimatorType feerate_estimator;
      50                 :             :     //! Fee rate sufficient for confirmation within target.
      51                 :             :     FeePerVSize feerate;
      52                 :             :     //! The returned confirmation target for the estimate.
      53                 :             :     int returned_target;
      54                 :             :     /**
      55                 :             :      * Compare two FeeRateEstimation objects based on fee rate
      56                 :             :      * @param other The other FeeRateEstimation object to compare with
      57                 :             :      * @return strong ordering of either less, greater or equal; based on feerate ratio comparison.
      58                 :             :      */
      59                 :           0 :     auto operator<=>(const FeeRateEstimation& other) const
      60                 :             :     {
      61         [ #  # ]:           0 :         return ByRatio{feerate} <=> ByRatio{other.feerate};
      62                 :             :     }
      63                 :             : };
      64                 :             : 
      65                 :             : /**
      66                 :             :  * @struct FeeRateEstimationError
      67                 :             :  * A failed fee rate estimation, carrying the zero-value estimation that
      68                 :             :  * identifies the estimator and target alongside the error reason.
      69                 :             :  */
      70                 :          72 : struct FeeRateEstimationError {
      71                 :             :     FeeRateEstimation estimation;
      72                 :             :     std::string reason;
      73                 :             : };
      74                 :             : 
      75                 :             : /**
      76                 :             :  * Build a fee rate estimation error result: a zero-value estimation
      77                 :             :  * identifying the estimator and target, alongside the error message.
      78                 :             :  */
      79                 :          24 : inline util::Unexpected<FeeRateEstimationError> EstimationError(FeeRateEstimatorType estimator, int returned_target, std::string error)
      80                 :             : {
      81                 :          24 :     return util::Unexpected{FeeRateEstimationError{{estimator, FeePerVSize{0, 0}, returned_target}, std::move(error)}};
      82                 :             : }
      83                 :             : 
      84                 :             : /**
      85                 :             :  * Return the estimation carried by a fee rate estimate result: the
      86                 :             :  * successful estimation, or the error's zero-value estimation.
      87                 :             :  */
      88                 :           7 : inline const FeeRateEstimation& FeeRateEstimationRef(const util::Expected<FeeRateEstimation, FeeRateEstimationError>& result LIFETIMEBOUND)
      89                 :             : {
      90         [ -  + ]:           7 :     return result ? *result : result.error().estimation;
      91                 :             : }
      92                 :             : 
      93                 :             : std::string_view FeeRateEstimatorTypeToString(FeeRateEstimatorType feerate_estimator_type);
      94                 :             : std::optional<FeeRateEstimatorType> FeeRateEstimatorTypeFromString(std::string_view feerate_estimator_type);
      95                 :             : 
      96                 :             : #endif // BITCOIN_UTIL_FEES_H