Bitcoin Core  24.99.0
P2P Digital Currency
fees.cpp
Go to the documentation of this file.
1 // Copyright (c) 2010 Satoshi Nakamoto
2 // Copyright (c) 2009-2021 The Bitcoin Core developers
3 // Distributed under the MIT software license, see the accompanying
4 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
5 
6 #include <core_io.h>
7 #include <policy/feerate.h>
8 #include <policy/fees.h>
9 #include <rpc/protocol.h>
10 #include <rpc/request.h>
11 #include <rpc/server.h>
12 #include <rpc/server_util.h>
13 #include <rpc/util.h>
14 #include <txmempool.h>
15 #include <univalue.h>
16 #include <util/fees.h>
17 
18 #include <algorithm>
19 #include <array>
20 #include <cmath>
21 #include <string>
22 
23 namespace node {
24 struct NodeContext;
25 }
26 
27 using node::NodeContext;
28 
30 {
31  return RPCHelpMan{"estimatesmartfee",
32  "\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
33  "confirmation within conf_target blocks if possible and return the number of blocks\n"
34  "for which the estimate is valid. Uses virtual transaction size as defined\n"
35  "in BIP 141 (witness data is discounted).\n",
36  {
37  {"conf_target", RPCArg::Type::NUM, RPCArg::Optional::NO, "Confirmation target in blocks (1 - 1008)"},
38  {"estimate_mode", RPCArg::Type::STR, RPCArg::Default{"conservative"}, "The fee estimate mode.\n"
39  "Whether to return a more conservative estimate which also satisfies\n"
40  "a longer history. A conservative estimate potentially returns a\n"
41  "higher feerate and is more likely to be sufficient for the desired\n"
42  "target, but is not as responsive to short term drops in the\n"
43  "prevailing fee market. Must be one of (case insensitive):\n"
44  "\"" + FeeModes("\"\n\"") + "\""},
45  },
46  RPCResult{
47  RPCResult::Type::OBJ, "", "",
48  {
49  {RPCResult::Type::NUM, "feerate", /*optional=*/true, "estimate fee rate in " + CURRENCY_UNIT + "/kvB (only present if no errors were encountered)"},
50  {RPCResult::Type::ARR, "errors", /*optional=*/true, "Errors encountered during processing (if there are any)",
51  {
52  {RPCResult::Type::STR, "", "error"},
53  }},
54  {RPCResult::Type::NUM, "blocks", "block number where estimate was found\n"
55  "The request target will be clamped between 2 and the highest target\n"
56  "fee estimation is able to return based on how long it has been running.\n"
57  "An error is returned if not enough transactions and blocks\n"
58  "have been observed to make an estimate for any number of blocks."},
59  }},
61  HelpExampleCli("estimatesmartfee", "6") +
62  HelpExampleRpc("estimatesmartfee", "6")
63  },
64  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
65  {
66  RPCTypeCheck(request.params, {UniValue::VNUM, UniValue::VSTR});
67 
68  CBlockPolicyEstimator& fee_estimator = EnsureAnyFeeEstimator(request.context);
69  const NodeContext& node = EnsureAnyNodeContext(request.context);
70  const CTxMemPool& mempool = EnsureMemPool(node);
71 
72  unsigned int max_target = fee_estimator.HighestTargetTracked(FeeEstimateHorizon::LONG_HALFLIFE);
73  unsigned int conf_target = ParseConfirmTarget(request.params[0], max_target);
74  bool conservative = true;
75  if (!request.params[1].isNull()) {
76  FeeEstimateMode fee_mode;
77  if (!FeeModeFromString(request.params[1].get_str(), fee_mode)) {
79  }
80  if (fee_mode == FeeEstimateMode::ECONOMICAL) conservative = false;
81  }
82 
83  UniValue result(UniValue::VOBJ);
84  UniValue errors(UniValue::VARR);
85  FeeCalculation feeCalc;
86  CFeeRate feeRate{fee_estimator.estimateSmartFee(conf_target, &feeCalc, conservative)};
87  if (feeRate != CFeeRate(0)) {
88  CFeeRate min_mempool_feerate{mempool.GetMinFee()};
89  CFeeRate min_relay_feerate{mempool.m_min_relay_feerate};
90  feeRate = std::max({feeRate, min_mempool_feerate, min_relay_feerate});
91  result.pushKV("feerate", ValueFromAmount(feeRate.GetFeePerK()));
92  } else {
93  errors.push_back("Insufficient data or no feerate found");
94  result.pushKV("errors", errors);
95  }
96  result.pushKV("blocks", feeCalc.returnedTarget);
97  return result;
98  },
99  };
100 }
101 
103 {
104  return RPCHelpMan{"estimaterawfee",
105  "\nWARNING: This interface is unstable and may disappear or change!\n"
106  "\nWARNING: This is an advanced API call that is tightly coupled to the specific\n"
107  "implementation of fee estimation. The parameters it can be called with\n"
108  "and the results it returns will change if the internal implementation changes.\n"
109  "\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
110  "confirmation within conf_target blocks if possible. Uses virtual transaction size as\n"
111  "defined in BIP 141 (witness data is discounted).\n",
112  {
113  {"conf_target", RPCArg::Type::NUM, RPCArg::Optional::NO, "Confirmation target in blocks (1 - 1008)"},
114  {"threshold", RPCArg::Type::NUM, RPCArg::Default{0.95}, "The proportion of transactions in a given feerate range that must have been\n"
115  "confirmed within conf_target in order to consider those feerates as high enough and proceed to check\n"
116  "lower buckets."},
117  },
118  RPCResult{
119  RPCResult::Type::OBJ, "", "Results are returned for any horizon which tracks blocks up to the confirmation target",
120  {
121  {RPCResult::Type::OBJ, "short", /*optional=*/true, "estimate for short time horizon",
122  {
123  {RPCResult::Type::NUM, "feerate", /*optional=*/true, "estimate fee rate in " + CURRENCY_UNIT + "/kvB"},
124  {RPCResult::Type::NUM, "decay", "exponential decay (per block) for historical moving average of confirmation data"},
125  {RPCResult::Type::NUM, "scale", "The resolution of confirmation targets at this time horizon"},
126  {RPCResult::Type::OBJ, "pass", /*optional=*/true, "information about the lowest range of feerates to succeed in meeting the threshold",
127  {
128  {RPCResult::Type::NUM, "startrange", "start of feerate range"},
129  {RPCResult::Type::NUM, "endrange", "end of feerate range"},
130  {RPCResult::Type::NUM, "withintarget", "number of txs over history horizon in the feerate range that were confirmed within target"},
131  {RPCResult::Type::NUM, "totalconfirmed", "number of txs over history horizon in the feerate range that were confirmed at any point"},
132  {RPCResult::Type::NUM, "inmempool", "current number of txs in mempool in the feerate range unconfirmed for at least target blocks"},
133  {RPCResult::Type::NUM, "leftmempool", "number of txs over history horizon in the feerate range that left mempool unconfirmed after target"},
134  }},
135  {RPCResult::Type::OBJ, "fail", /*optional=*/true, "information about the highest range of feerates to fail to meet the threshold",
136  {
137  {RPCResult::Type::ELISION, "", ""},
138  }},
139  {RPCResult::Type::ARR, "errors", /*optional=*/true, "Errors encountered during processing (if there are any)",
140  {
141  {RPCResult::Type::STR, "error", ""},
142  }},
143  }},
144  {RPCResult::Type::OBJ, "medium", /*optional=*/true, "estimate for medium time horizon",
145  {
146  {RPCResult::Type::ELISION, "", ""},
147  }},
148  {RPCResult::Type::OBJ, "long", /*optional=*/true, "estimate for long time horizon",
149  {
150  {RPCResult::Type::ELISION, "", ""},
151  }},
152  }},
153  RPCExamples{
154  HelpExampleCli("estimaterawfee", "6 0.9")
155  },
156  [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
157  {
158  RPCTypeCheck(request.params, {UniValue::VNUM, UniValue::VNUM}, true);
159 
160  CBlockPolicyEstimator& fee_estimator = EnsureAnyFeeEstimator(request.context);
161 
162  unsigned int max_target = fee_estimator.HighestTargetTracked(FeeEstimateHorizon::LONG_HALFLIFE);
163  unsigned int conf_target = ParseConfirmTarget(request.params[0], max_target);
164  double threshold = 0.95;
165  if (!request.params[1].isNull()) {
166  threshold = request.params[1].get_real();
167  }
168  if (threshold < 0 || threshold > 1) {
169  throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid threshold");
170  }
171 
172  UniValue result(UniValue::VOBJ);
173 
174  for (const FeeEstimateHorizon horizon : ALL_FEE_ESTIMATE_HORIZONS) {
175  CFeeRate feeRate;
176  EstimationResult buckets;
177 
178  // Only output results for horizons which track the target
179  if (conf_target > fee_estimator.HighestTargetTracked(horizon)) continue;
180 
181  feeRate = fee_estimator.estimateRawFee(conf_target, threshold, horizon, &buckets);
182  UniValue horizon_result(UniValue::VOBJ);
183  UniValue errors(UniValue::VARR);
184  UniValue passbucket(UniValue::VOBJ);
185  passbucket.pushKV("startrange", round(buckets.pass.start));
186  passbucket.pushKV("endrange", round(buckets.pass.end));
187  passbucket.pushKV("withintarget", round(buckets.pass.withinTarget * 100.0) / 100.0);
188  passbucket.pushKV("totalconfirmed", round(buckets.pass.totalConfirmed * 100.0) / 100.0);
189  passbucket.pushKV("inmempool", round(buckets.pass.inMempool * 100.0) / 100.0);
190  passbucket.pushKV("leftmempool", round(buckets.pass.leftMempool * 100.0) / 100.0);
191  UniValue failbucket(UniValue::VOBJ);
192  failbucket.pushKV("startrange", round(buckets.fail.start));
193  failbucket.pushKV("endrange", round(buckets.fail.end));
194  failbucket.pushKV("withintarget", round(buckets.fail.withinTarget * 100.0) / 100.0);
195  failbucket.pushKV("totalconfirmed", round(buckets.fail.totalConfirmed * 100.0) / 100.0);
196  failbucket.pushKV("inmempool", round(buckets.fail.inMempool * 100.0) / 100.0);
197  failbucket.pushKV("leftmempool", round(buckets.fail.leftMempool * 100.0) / 100.0);
198 
199  // CFeeRate(0) is used to indicate error as a return value from estimateRawFee
200  if (feeRate != CFeeRate(0)) {
201  horizon_result.pushKV("feerate", ValueFromAmount(feeRate.GetFeePerK()));
202  horizon_result.pushKV("decay", buckets.decay);
203  horizon_result.pushKV("scale", (int)buckets.scale);
204  horizon_result.pushKV("pass", passbucket);
205  // buckets.fail.start == -1 indicates that all buckets passed, there is no fail bucket to output
206  if (buckets.fail.start != -1) horizon_result.pushKV("fail", failbucket);
207  } else {
208  // Output only information that is still meaningful in the event of error
209  horizon_result.pushKV("decay", buckets.decay);
210  horizon_result.pushKV("scale", (int)buckets.scale);
211  horizon_result.pushKV("fail", failbucket);
212  errors.push_back("Insufficient data or no feerate found which meets threshold");
213  horizon_result.pushKV("errors", errors);
214  }
215  result.pushKV(StringForFeeEstimateHorizon(horizon), horizon_result);
216  }
217  return result;
218  },
219  };
220 }
221 
223 {
224  static const CRPCCommand commands[]{
225  {"util", &estimatesmartfee},
226  {"hidden", &estimaterawfee},
227  };
228  for (const auto& c : commands) {
229  t.appendCommand(c.name, &c);
230  }
231 }
The BlockPolicyEstimator is used for estimating the feerate needed for a transaction to be included i...
Definition: fees.h:133
CFeeRate estimateSmartFee(int confTarget, FeeCalculation *feeCalc, bool conservative) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Estimate feerate needed to get be included in a block within confTarget blocks.
Definition: fees.cpp:826
unsigned int HighestTargetTracked(FeeEstimateHorizon horizon) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Calculation of highest target that estimates are tracked for.
Definition: fees.cpp:718
CFeeRate estimateRawFee(int confTarget, double successThreshold, FeeEstimateHorizon horizon, EstimationResult *result=nullptr) const EXCLUSIVE_LOCKS_REQUIRED(!m_cs_fee_estimator)
Return a specific fee estimate calculation with a given success threshold and time horizon,...
Definition: fees.cpp:682
Fee rate in satoshis per kilovirtualbyte: CAmount / kvB.
Definition: feerate.h:33
CAmount GetFeePerK() const
Return the fee in satoshis for a vsize of 1000 vbytes.
Definition: feerate.h:65
RPC command dispatcher.
Definition: server.h:126
CTxMemPool stores valid-according-to-the-current-best-chain transactions that may be included in the ...
Definition: txmempool.h:432
CFeeRate GetMinFee(size_t sizelimit) const
Definition: txmempool.cpp:1080
const CFeeRate m_min_relay_feerate
Definition: txmempool.h:572
void push_back(UniValue val)
Definition: univalue.cpp:104
@ VOBJ
Definition: univalue.h:20
@ VARR
Definition: univalue.h:20
void pushKV(std::string key, UniValue val)
Definition: univalue.cpp:126
UniValue ValueFromAmount(const CAmount amount)
Definition: core_write.cpp:26
const std::string CURRENCY_UNIT
Definition: feerate.h:17
FeeEstimateMode
Definition: feerate.h:21
@ ECONOMICAL
Force estimateSmartFee to use non-conservative estimates.
Definition: init.h:25
std::string StringForFeeEstimateHorizon(FeeEstimateHorizon horizon)
Definition: fees.cpp:36
static constexpr auto ALL_FEE_ESTIMATE_HORIZONS
Definition: fees.h:35
FeeEstimateHorizon
Definition: fees.h:29
UniValue JSONRPCError(int code, const std::string &message)
Definition: request.cpp:56
static RPCHelpMan estimatesmartfee()
Definition: fees.cpp:29
void RegisterFeeRPCCommands(CRPCTable &t)
Definition: fees.cpp:222
static RPCHelpMan estimaterawfee()
Definition: fees.cpp:102
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
Definition: protocol.h:43
void RPCTypeCheck(const UniValue &params, const std::list< UniValueType > &typesExpected, bool fAllowNull)
Type-check arguments; throws JSONRPCError if wrong type given.
Definition: util.cpp:33
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
Definition: util.cpp:166
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:184
unsigned int ParseConfirmTarget(const UniValue &value, unsigned int max_target)
Parse a confirm target option and raise an RPC error if it is invalid.
Definition: util.cpp:340
NodeContext & EnsureAnyNodeContext(const std::any &context)
Definition: server_util.cpp:20
CBlockPolicyEstimator & EnsureAnyFeeEstimator(const std::any &context)
Definition: server_util.cpp:76
CTxMemPool & EnsureMemPool(const NodeContext &node)
Definition: server_util.cpp:29
EstimatorBucket fail
Definition: fees.h:71
EstimatorBucket pass
Definition: fees.h:70
double decay
Definition: fees.h:72
unsigned int scale
Definition: fees.h:73
double totalConfirmed
Definition: fees.h:62
double end
Definition: fees.h:60
double leftMempool
Definition: fees.h:64
double start
Definition: fees.h:59
double withinTarget
Definition: fees.h:61
double inMempool
Definition: fees.h:63
int returnedTarget
Definition: fees.h:81
@ NO
Required arg.
@ ELISION
Special type to denote elision (...)
NodeContext struct containing references to chain state and connection state.
Definition: context.h:43
std::string FeeModes(const std::string &delimiter)
Definition: fees.cpp:47
bool FeeModeFromString(const std::string &mode_string, FeeEstimateMode &fee_estimate_mode)
Definition: fees.cpp:57
const std::string InvalidEstimateModeErrorMessage()
Definition: fees.cpp:52