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 */
18enum 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 */
25enum 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 */
37enum 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 */
47struct 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    auto operator<=>(const FeeRateEstimation& other) const
60    {
61        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 */
70struct 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 */
79inline util::Unexpected<FeeRateEstimationError> EstimationError(FeeRateEstimatorType estimator, int returned_target, std::string error)
80{
81    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 */
88inline const FeeRateEstimation& FeeRateEstimationRef(const util::Expected<FeeRateEstimation, FeeRateEstimationError>& result LIFETIMEBOUND)
89{
90    return result ? *result : result.error().estimation;
91}
92
93std::string_view FeeRateEstimatorTypeToString(FeeRateEstimatorType feerate_estimator_type);
94std::optional<FeeRateEstimatorType> FeeRateEstimatorTypeFromString(std::string_view feerate_estimator_type);
95
96#endif // BITCOIN_UTIL_FEES_H
97