1 // Copyright (c) 2010 Satoshi Nakamoto
2 // Copyright (c) 2009-2020 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 <amount.h>
7 #include <chain.h>
8 #include <chainparams.h>
9 #include <consensus/consensus.h>
10 #include <consensus/params.h>
11 #include <consensus/validation.h>
12 #include <core_io.h>
13 #include <deploymentinfo.h>
14 #include <deploymentstatus.h>
15 #include <key_io.h>
16 #include <miner.h>
enumeratesigners()17 #include <net.h>
18 #include <node/context.h>
19 #include <policy/fees.h>
20 #include <pow.h>
21 #include <rpc/blockchain.h>
22 #include <rpc/mining.h>
23 #include <rpc/net.h>
24 #include <rpc/server.h>
25 #include <rpc/util.h>
26 #include <script/descriptor.h>
27 #include <script/script.h>
28 #include <script/signingprovider.h>
29 #include <shutdown.h>
30 #include <txmempool.h>
31 #include <univalue.h>
32 #include <util/fees.h>
33 #include <util/strencodings.h>
34 #include <util/string.h>
35 #include <util/system.h>
36 #include <util/translation.h>
37 #include <validation.h>
38 #include <validationinterface.h>
39 #include <warnings.h>
40
41 #include <memory>
42 #include <stdint.h>
43
44 /**
45 * Return average network hashes per second based on the last 'lookup' blocks,
46 * or from the last difficulty change if 'lookup' is nonpositive.
47 * If 'height' is nonnegative, compute the estimate at the time when a given block was found.
48 */
49 static UniValue GetNetworkHashPS(int lookup, int height, const CChain& active_chain) {
50 const CBlockIndex* pb = active_chain.Tip();
51
52 if (height >= 0 && height < active_chain.Height()) {
53 pb = active_chain[height];
54 }
55
56 if (pb == nullptr || !pb->nHeight)
57 return 0;
58
59 // If lookup is -1, then use blocks since last difficulty change.
60 if (lookup <= 0)
61 lookup = pb->nHeight % Params().GetConsensus().DifficultyAdjustmentInterval() + 1;
62
63 // If lookup is larger than chain, then set it to chain length.
64 if (lookup > pb->nHeight)
65 lookup = pb->nHeight;
66
67 const CBlockIndex* pb0 = pb;
68 int64_t minTime = pb0->GetBlockTime();
69 int64_t maxTime = minTime;
70 for (int i = 0; i < lookup; i++) {
71 pb0 = pb0->pprev;
72 int64_t time = pb0->GetBlockTime();
73 minTime = std::min(time, minTime);
74 maxTime = std::max(time, maxTime);
75 }
76
77 // In case there's a situation where minTime == maxTime, we don't want a divide by zero exception.
78 if (minTime == maxTime)
79 return 0;
80
81 arith_uint256 workDiff = pb->nChainWork - pb0->nChainWork;
82 int64_t timeDiff = maxTime - minTime;
83
84 return workDiff.getdouble() / timeDiff;
85 }
86
87 static RPCHelpMan getnetworkhashps()
88 {
89 return RPCHelpMan{"getnetworkhashps",
90 "\nReturns the estimated network hashes per second based on the last n blocks.\n"
91 "Pass in [blocks] to override # of blocks, -1 specifies since last difficulty change.\n"
92 "Pass in [height] to estimate the network speed at the time when a certain block was found.\n",
93 {
94 {"nblocks", RPCArg::Type::NUM, RPCArg::Default{120}, "The number of blocks, or -1 for blocks since last difficulty change."},
95 {"height", RPCArg::Type::NUM, RPCArg::Default{-1}, "To estimate at the time of the given height."},
96 },
97 RPCResult{
98 RPCResult::Type::NUM, "", "Hashes per second estimated"},
99 RPCExamples{
100 HelpExampleCli("getnetworkhashps", "")
101 + HelpExampleRpc("getnetworkhashps", "")
102 },
103 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
104 {
105 ChainstateManager& chainman = EnsureAnyChainman(request.context);
106 LOCK(cs_main);
107 return GetNetworkHashPS(!request.params[0].isNull() ? request.params[0].get_int() : 120, !request.params[1].isNull() ? request.params[1].get_int() : -1, chainman.ActiveChain());
108 },
109 };
110 }
111
112 static bool GenerateBlock(ChainstateManager& chainman, CBlock& block, uint64_t& max_tries, unsigned int& extra_nonce, uint256& block_hash)
113 {
114 block_hash.SetNull();
115
116 {
117 LOCK(cs_main);
118 IncrementExtraNonce(&block, chainman.ActiveChain().Tip(), extra_nonce);
119 }
120
121 CChainParams chainparams(Params());
122
123 while (max_tries > 0 && block.nNonce < std::numeric_limits<uint32_t>::max() && !CheckProofOfWork(block.GetHash(), block.nBits, chainparams.GetConsensus()) && !ShutdownRequested()) {
124 ++block.nNonce;
125 --max_tries;
126 }
127 if (max_tries == 0 || ShutdownRequested()) {
128 return false;
129 }
130 if (block.nNonce == std::numeric_limits<uint32_t>::max()) {
131 return true;
132 }
133
134 std::shared_ptr<const CBlock> shared_pblock = std::make_shared<const CBlock>(block);
135 if (!chainman.ProcessNewBlock(chainparams, shared_pblock, true, nullptr)) {
136 throw JSONRPCError(RPC_INTERNAL_ERROR, "ProcessNewBlock, block not accepted");
137 }
138
139 block_hash = block.GetHash();
140 return true;
141 }
142
143 static UniValue generateBlocks(ChainstateManager& chainman, const CTxMemPool& mempool, const CScript& coinbase_script, int nGenerate, uint64_t nMaxTries)
144 {
145 int nHeightEnd = 0;
146 int nHeight = 0;
147
148 { // Don't keep cs_main locked
149 LOCK(cs_main);
150 nHeight = chainman.ActiveChain().Height();
151 nHeightEnd = nHeight+nGenerate;
152 }
153 unsigned int nExtraNonce = 0;
154 UniValue blockHashes(UniValue::VARR);
155 while (nHeight < nHeightEnd && !ShutdownRequested())
156 {
157 std::unique_ptr<CBlockTemplate> pblocktemplate(BlockAssembler(chainman.ActiveChainstate(), mempool, Params()).CreateNewBlock(coinbase_script));
158 if (!pblocktemplate.get())
159 throw JSONRPCError(RPC_INTERNAL_ERROR, "Couldn't create new block");
160 CBlock *pblock = &pblocktemplate->block;
161
162 uint256 block_hash;
163 if (!GenerateBlock(chainman, *pblock, nMaxTries, nExtraNonce, block_hash)) {
164 break;
165 }
166
167 if (!block_hash.IsNull()) {
168 ++nHeight;
169 blockHashes.push_back(block_hash.GetHex());
170 }
171 }
172 return blockHashes;
173 }
174
175 static bool getScriptFromDescriptor(const std::string& descriptor, CScript& script, std::string& error)
176 {
177 FlatSigningProvider key_provider;
178 const auto desc = Parse(descriptor, key_provider, error, /* require_checksum = */ false);
179 if (desc) {
180 if (desc->IsRange()) {
181 throw JSONRPCError(RPC_INVALID_PARAMETER, "Ranged descriptor not accepted. Maybe pass through deriveaddresses first?");
182 }
183
184 FlatSigningProvider provider;
185 std::vector<CScript> scripts;
186 if (!desc->Expand(0, key_provider, scripts, provider)) {
187 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, strprintf("Cannot derive script without private keys"));
188 }
189
190 // Combo descriptors can have 2 or 4 scripts, so we can't just check scripts.size() == 1
191 CHECK_NONFATAL(scripts.size() > 0 && scripts.size() <= 4);
192
193 if (scripts.size() == 1) {
194 script = scripts.at(0);
195 } else if (scripts.size() == 4) {
196 // For uncompressed keys, take the 3rd script, since it is p2wpkh
197 script = scripts.at(2);
198 } else {
199 // Else take the 2nd script, since it is p2pkh
200 script = scripts.at(1);
201 }
202
203 return true;
204 } else {
205 return false;
206 }
207 }
208
209 static RPCHelpMan generatetodescriptor()
210 {
211 return RPCHelpMan{
212 "generatetodescriptor",
213 "\nMine blocks immediately to a specified descriptor (before the RPC call returns)\n",
214 {
215 {"num_blocks", RPCArg::Type::NUM, RPCArg::Optional::NO, "How many blocks are generated immediately."},
216 {"descriptor", RPCArg::Type::STR, RPCArg::Optional::NO, "The descriptor to send the newly generated bitcoin to."},
217 {"maxtries", RPCArg::Type::NUM, RPCArg::Default{DEFAULT_MAX_TRIES}, "How many iterations to try."},
218 },
219 RPCResult{
220 RPCResult::Type::ARR, "", "hashes of blocks generated",
221 {
222 {RPCResult::Type::STR_HEX, "", "blockhash"},
223 }
224 },
225 RPCExamples{
226 "\nGenerate 11 blocks to mydesc\n" + HelpExampleCli("generatetodescriptor", "11 \"mydesc\"")},
227 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
228 {
229 const int num_blocks{request.params[0].get_int()};
230 const uint64_t max_tries{request.params[2].isNull() ? DEFAULT_MAX_TRIES : request.params[2].get_int()};
231
232 CScript coinbase_script;
233 std::string error;
234 if (!getScriptFromDescriptor(request.params[1].get_str(), coinbase_script, error)) {
235 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, error);
236 }
237
238 NodeContext& node = EnsureAnyNodeContext(request.context);
239 const CTxMemPool& mempool = EnsureMemPool(node);
240 ChainstateManager& chainman = EnsureChainman(node);
241
242 return generateBlocks(chainman, mempool, coinbase_script, num_blocks, max_tries);
243 },
244 };
245 }
246
247 static RPCHelpMan generate()
248 {
249 return RPCHelpMan{"generate", "has been replaced by the -generate cli option. Refer to -help for more information.", {}, {}, RPCExamples{""}, [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue {
250 throw JSONRPCError(RPC_METHOD_NOT_FOUND, self.ToString());
251 }};
252 }
253
254 static RPCHelpMan generatetoaddress()
255 {
256 return RPCHelpMan{"generatetoaddress",
257 "\nMine blocks immediately to a specified address (before the RPC call returns)\n",
258 {
259 {"nblocks", RPCArg::Type::NUM, RPCArg::Optional::NO, "How many blocks are generated immediately."},
260 {"address", RPCArg::Type::STR, RPCArg::Optional::NO, "The address to send the newly generated bitcoin to."},
261 {"maxtries", RPCArg::Type::NUM, RPCArg::Default{DEFAULT_MAX_TRIES}, "How many iterations to try."},
262 },
263 RPCResult{
264 RPCResult::Type::ARR, "", "hashes of blocks generated",
265 {
266 {RPCResult::Type::STR_HEX, "", "blockhash"},
267 }},
268 RPCExamples{
269 "\nGenerate 11 blocks to myaddress\n"
270 + HelpExampleCli("generatetoaddress", "11 \"myaddress\"")
271 + "If you are using the " PACKAGE_NAME " wallet, you can get a new address to send the newly generated bitcoin to with:\n"
272 + HelpExampleCli("getnewaddress", "")
273 },
274 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
275 {
276 const int num_blocks{request.params[0].get_int()};
277 const uint64_t max_tries{request.params[2].isNull() ? DEFAULT_MAX_TRIES : request.params[2].get_int()};
278
279 CTxDestination destination = DecodeDestination(request.params[1].get_str());
280 if (!IsValidDestination(destination)) {
281 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Error: Invalid address");
282 }
283
284 NodeContext& node = EnsureAnyNodeContext(request.context);
285 const CTxMemPool& mempool = EnsureMemPool(node);
286 ChainstateManager& chainman = EnsureChainman(node);
287
288 CScript coinbase_script = GetScriptForDestination(destination);
289
290 return generateBlocks(chainman, mempool, coinbase_script, num_blocks, max_tries);
291 },
292 };
293 }
294
295 static RPCHelpMan generateblock()
296 {
297 return RPCHelpMan{"generateblock",
298 "\nMine a block with a set of ordered transactions immediately to a specified address or descriptor (before the RPC call returns)\n",
299 {
300 {"output", RPCArg::Type::STR, RPCArg::Optional::NO, "The address or descriptor to send the newly generated bitcoin to."},
301 {"transactions", RPCArg::Type::ARR, RPCArg::Optional::NO, "An array of hex strings which are either txids or raw transactions.\n"
302 "Txids must reference transactions currently in the mempool.\n"
303 "All transactions must be valid and in valid order, otherwise the block will be rejected.",
304 {
305 {"rawtx/txid", RPCArg::Type::STR_HEX, RPCArg::Optional::OMITTED, ""},
306 },
307 },
308 },
309 RPCResult{
310 RPCResult::Type::OBJ, "", "",
311 {
312 {RPCResult::Type::STR_HEX, "hash", "hash of generated block"},
313 }
314 },
315 RPCExamples{
316 "\nGenerate a block to myaddress, with txs rawtx and mempool_txid\n"
317 + HelpExampleCli("generateblock", R"("myaddress" '["rawtx", "mempool_txid"]')")
318 },
319 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
320 {
321 const auto address_or_descriptor = request.params[0].get_str();
322 CScript coinbase_script;
323 std::string error;
324
325 if (!getScriptFromDescriptor(address_or_descriptor, coinbase_script, error)) {
326 const auto destination = DecodeDestination(address_or_descriptor);
327 if (!IsValidDestination(destination)) {
328 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Error: Invalid address or descriptor");
329 }
330
331 coinbase_script = GetScriptForDestination(destination);
332 }
333
334 NodeContext& node = EnsureAnyNodeContext(request.context);
335 const CTxMemPool& mempool = EnsureMemPool(node);
336
337 std::vector<CTransactionRef> txs;
338 const auto raw_txs_or_txids = request.params[1].get_array();
339 for (size_t i = 0; i < raw_txs_or_txids.size(); i++) {
340 const auto str(raw_txs_or_txids[i].get_str());
341
342 uint256 hash;
343 CMutableTransaction mtx;
344 if (ParseHashStr(str, hash)) {
345
346 const auto tx = mempool.get(hash);
347 if (!tx) {
348 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, strprintf("Transaction %s not in mempool.", str));
349 }
350
351 txs.emplace_back(tx);
352
353 } else if (DecodeHexTx(mtx, str)) {
354 txs.push_back(MakeTransactionRef(std::move(mtx)));
355
356 } else {
357 throw JSONRPCError(RPC_DESERIALIZATION_ERROR, strprintf("Transaction decode failed for %s. Make sure the tx has at least one input.", str));
358 }
359 }
360
361 CChainParams chainparams(Params());
362 CBlock block;
363
364 ChainstateManager& chainman = EnsureChainman(node);
365 {
366 LOCK(cs_main);
367
368 CTxMemPool empty_mempool;
369 std::unique_ptr<CBlockTemplate> blocktemplate(BlockAssembler(chainman.ActiveChainstate(), empty_mempool, chainparams).CreateNewBlock(coinbase_script));
370 if (!blocktemplate) {
371 throw JSONRPCError(RPC_INTERNAL_ERROR, "Couldn't create new block");
372 }
373 block = blocktemplate->block;
374 }
375
376 CHECK_NONFATAL(block.vtx.size() == 1);
377
378 // Add transactions
379 block.vtx.insert(block.vtx.end(), txs.begin(), txs.end());
380 RegenerateCommitments(block, chainman);
381
382 {
383 LOCK(cs_main);
384
385 BlockValidationState state;
386 if (!TestBlockValidity(state, chainparams, chainman.ActiveChainstate(), block, chainman.m_blockman.LookupBlockIndex(block.hashPrevBlock), false, false)) {
387 throw JSONRPCError(RPC_VERIFY_ERROR, strprintf("TestBlockValidity failed: %s", state.ToString()));
388 }
389 }
390
391 uint256 block_hash;
392 uint64_t max_tries{DEFAULT_MAX_TRIES};
393 unsigned int extra_nonce{0};
394
395 if (!GenerateBlock(chainman, block, max_tries, extra_nonce, block_hash) || block_hash.IsNull()) {
396 throw JSONRPCError(RPC_MISC_ERROR, "Failed to make block.");
397 }
398
399 UniValue obj(UniValue::VOBJ);
400 obj.pushKV("hash", block_hash.GetHex());
401 return obj;
402 },
403 };
404 }
405
406 static RPCHelpMan getmininginfo()
407 {
408 return RPCHelpMan{"getmininginfo",
409 "\nReturns a json object containing mining-related information.",
410 {},
411 RPCResult{
412 RPCResult::Type::OBJ, "", "",
413 {
414 {RPCResult::Type::NUM, "blocks", "The current block"},
415 {RPCResult::Type::NUM, "currentblockweight", /* optional */ true, "The block weight of the last assembled block (only present if a block was ever assembled)"},
416 {RPCResult::Type::NUM, "currentblocktx", /* optional */ true, "The number of block transactions of the last assembled block (only present if a block was ever assembled)"},
417 {RPCResult::Type::NUM, "difficulty", "The current difficulty"},
418 {RPCResult::Type::NUM, "networkhashps", "The network hashes per second"},
419 {RPCResult::Type::NUM, "pooledtx", "The size of the mempool"},
420 {RPCResult::Type::STR, "chain", "current network name (main, test, signet, regtest)"},
421 {RPCResult::Type::STR, "warnings", "any network and blockchain warnings"},
422 }},
423 RPCExamples{
424 HelpExampleCli("getmininginfo", "")
425 + HelpExampleRpc("getmininginfo", "")
426 },
427 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
428 {
429 NodeContext& node = EnsureAnyNodeContext(request.context);
430 const CTxMemPool& mempool = EnsureMemPool(node);
431 ChainstateManager& chainman = EnsureChainman(node);
432 LOCK(cs_main);
433 const CChain& active_chain = chainman.ActiveChain();
434
435 UniValue obj(UniValue::VOBJ);
436 obj.pushKV("blocks", active_chain.Height());
437 if (BlockAssembler::m_last_block_weight) obj.pushKV("currentblockweight", *BlockAssembler::m_last_block_weight);
438 if (BlockAssembler::m_last_block_num_txs) obj.pushKV("currentblocktx", *BlockAssembler::m_last_block_num_txs);
439 obj.pushKV("difficulty", (double)GetDifficulty(active_chain.Tip()));
440 obj.pushKV("networkhashps", getnetworkhashps().HandleRequest(request));
441 obj.pushKV("pooledtx", (uint64_t)mempool.size());
442 obj.pushKV("chain", Params().NetworkIDString());
443 obj.pushKV("warnings", GetWarnings(false).original);
444 return obj;
445 },
446 };
447 }
448
449
450 // NOTE: Unlike wallet RPC (which use BTC values), mining RPCs follow GBT (BIP 22) in using satoshi amounts
451 static RPCHelpMan prioritisetransaction()
452 {
453 return RPCHelpMan{"prioritisetransaction",
454 "Accepts the transaction into mined blocks at a higher (or lower) priority\n",
455 {
456 {"txid", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The transaction id."},
457 {"dummy", RPCArg::Type::NUM, RPCArg::Optional::OMITTED_NAMED_ARG, "API-Compatibility for previous API. Must be zero or null.\n"
458 " DEPRECATED. For forward compatibility use named arguments and omit this parameter."},
459 {"fee_delta", RPCArg::Type::NUM, RPCArg::Optional::NO, "The fee value (in satoshis) to add (or subtract, if negative).\n"
460 " Note, that this value is not a fee rate. It is a value to modify absolute fee of the TX.\n"
461 " The fee is not actually paid, only the algorithm for selecting transactions into a block\n"
462 " considers the transaction as it would have paid a higher (or lower) fee."},
463 },
464 RPCResult{
465 RPCResult::Type::BOOL, "", "Returns true"},
466 RPCExamples{
467 HelpExampleCli("prioritisetransaction", "\"txid\" 0.0 10000")
468 + HelpExampleRpc("prioritisetransaction", "\"txid\", 0.0, 10000")
469 },
470 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
471 {
472 LOCK(cs_main);
473
474 uint256 hash(ParseHashV(request.params[0], "txid"));
475 CAmount nAmount = request.params[2].get_int64();
476
477 if (!(request.params[1].isNull() || request.params[1].get_real() == 0)) {
478 throw JSONRPCError(RPC_INVALID_PARAMETER, "Priority is no longer supported, dummy argument to prioritisetransaction must be 0.");
479 }
480
481 EnsureAnyMemPool(request.context).PrioritiseTransaction(hash, nAmount);
482 return true;
483 },
484 };
485 }
486
487
488 // NOTE: Assumes a conclusive result; if result is inconclusive, it must be handled by caller
489 static UniValue BIP22ValidationResult(const BlockValidationState& state)
490 {
491 if (state.IsValid())
492 return NullUniValue;
493
494 if (state.IsError())
495 throw JSONRPCError(RPC_VERIFY_ERROR, state.ToString());
496 if (state.IsInvalid())
497 {
498 std::string strRejectReason = state.GetRejectReason();
499 if (strRejectReason.empty())
500 return "rejected";
501 return strRejectReason;
502 }
503 // Should be impossible
504 return "valid?";
505 }
506
507 static std::string gbt_vb_name(const Consensus::DeploymentPos pos) {
508 const struct VBDeploymentInfo& vbinfo = VersionBitsDeploymentInfo[pos];
509 std::string s = vbinfo.name;
510 if (!vbinfo.gbt_force) {
511 s.insert(s.begin(), '!');
512 }
513 return s;
514 }
515
516 static RPCHelpMan getblocktemplate()
517 {
518 return RPCHelpMan{"getblocktemplate",
519 "\nIf the request parameters include a 'mode' key, that is used to explicitly select between the default 'template' request or a 'proposal'.\n"
520 "It returns data needed to construct a block to work on.\n"
521 "For full specification, see BIPs 22, 23, 9, and 145:\n"
522 " https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki\n"
523 " https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki\n"
524 " https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki#getblocktemplate_changes\n"
525 " https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki\n",
526 {
527 {"template_request", RPCArg::Type::OBJ, RPCArg::Default{UniValue::VOBJ}, "Format of the template",
528 {
529 {"mode", RPCArg::Type::STR, /* treat as named arg */ RPCArg::Optional::OMITTED_NAMED_ARG, "This must be set to \"template\", \"proposal\" (see BIP 23), or omitted"},
530 {"capabilities", RPCArg::Type::ARR, /* treat as named arg */ RPCArg::Optional::OMITTED_NAMED_ARG, "A list of strings",
531 {
532 {"str", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "client side supported feature, 'longpoll', 'coinbasevalue', 'proposal', 'serverlist', 'workid'"},
533 }},
534 {"rules", RPCArg::Type::ARR, RPCArg::Optional::NO, "A list of strings",
535 {
536 {"segwit", RPCArg::Type::STR, RPCArg::Optional::NO, "(literal) indicates client side segwit support"},
537 {"str", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "other client side supported softfork deployment"},
538 }},
539 },
540 "\"template_request\""},
541 },
542 {
543 RPCResult{"If the proposal was accepted with mode=='proposal'", RPCResult::Type::NONE, "", ""},
544 RPCResult{"If the proposal was not accepted with mode=='proposal'", RPCResult::Type::STR, "", "According to BIP22"},
545 RPCResult{"Otherwise", RPCResult::Type::OBJ, "", "",
546 {
547 {RPCResult::Type::NUM, "version", "The preferred block version"},
548 {RPCResult::Type::ARR, "rules", "specific block rules that are to be enforced",
549 {
550 {RPCResult::Type::STR, "", "name of a rule the client must understand to some extent; see BIP 9 for format"},
551 }},
552 {RPCResult::Type::OBJ_DYN, "vbavailable", "set of pending, supported versionbit (BIP 9) softfork deployments",
553 {
554 {RPCResult::Type::NUM, "rulename", "identifies the bit number as indicating acceptance and readiness for the named softfork rule"},
555 }},
556 {RPCResult::Type::NUM, "vbrequired", "bit mask of versionbits the server requires set in submissions"},
557 {RPCResult::Type::STR, "previousblockhash", "The hash of current highest block"},
558 {RPCResult::Type::ARR, "transactions", "contents of non-coinbase transactions that should be included in the next block",
559 {
560 {RPCResult::Type::OBJ, "", "",
561 {
562 {RPCResult::Type::STR_HEX, "data", "transaction data encoded in hexadecimal (byte-for-byte)"},
563 {RPCResult::Type::STR_HEX, "txid", "transaction id encoded in little-endian hexadecimal"},
564 {RPCResult::Type::STR_HEX, "hash", "hash encoded in little-endian hexadecimal (including witness data)"},
565 {RPCResult::Type::ARR, "depends", "array of numbers",
566 {
567 {RPCResult::Type::NUM, "", "transactions before this one (by 1-based index in 'transactions' list) that must be present in the final block if this one is"},
568 }},
569 {RPCResult::Type::NUM, "fee", "difference in value between transaction inputs and outputs (in satoshis); for coinbase transactions, this is a negative Number of the total collected block fees (ie, not including the block subsidy); if key is not present, fee is unknown and clients MUST NOT assume there isn't one"},
570 {RPCResult::Type::NUM, "sigops", "total SigOps cost, as counted for purposes of block limits; if key is not present, sigop cost is unknown and clients MUST NOT assume it is zero"},
571 {RPCResult::Type::NUM, "weight", "total transaction weight, as counted for purposes of block limits"},
572 }},
573 }},
574 {RPCResult::Type::OBJ_DYN, "coinbaseaux", "data that should be included in the coinbase's scriptSig content",
575 {
576 {RPCResult::Type::STR_HEX, "key", "values must be in the coinbase (keys may be ignored)"},
577 }},
578 {RPCResult::Type::NUM, "coinbasevalue", "maximum allowable input to coinbase transaction, including the generation award and transaction fees (in satoshis)"},
579 {RPCResult::Type::STR, "longpollid", "an id to include with a request to longpoll on an update to this template"},
580 {RPCResult::Type::STR, "target", "The hash target"},
581 {RPCResult::Type::NUM_TIME, "mintime", "The minimum timestamp appropriate for the next block time, expressed in " + UNIX_EPOCH_TIME},
582 {RPCResult::Type::ARR, "mutable", "list of ways the block template may be changed",
583 {
584 {RPCResult::Type::STR, "value", "A way the block template may be changed, e.g. 'time', 'transactions', 'prevblock'"},
585 }},
586 {RPCResult::Type::STR_HEX, "noncerange", "A range of valid nonces"},
587 {RPCResult::Type::NUM, "sigoplimit", "limit of sigops in blocks"},
588 {RPCResult::Type::NUM, "sizelimit", "limit of block size"},
589 {RPCResult::Type::NUM, "weightlimit", "limit of block weight"},
590 {RPCResult::Type::NUM_TIME, "curtime", "current timestamp in " + UNIX_EPOCH_TIME},
591 {RPCResult::Type::STR, "bits", "compressed target of next block"},
592 {RPCResult::Type::NUM, "height", "The height of the next block"},
593 {RPCResult::Type::STR, "default_witness_commitment", /* optional */ true, "a valid witness commitment for the unmodified block template"},
594 }},
595 },
596 RPCExamples{
597 HelpExampleCli("getblocktemplate", "'{\"rules\": [\"segwit\"]}'")
598 + HelpExampleRpc("getblocktemplate", "{\"rules\": [\"segwit\"]}")
599 },
600 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
601 {
602 NodeContext& node = EnsureAnyNodeContext(request.context);
603 ChainstateManager& chainman = EnsureChainman(node);
604 LOCK(cs_main);
605
606 std::string strMode = "template";
607 UniValue lpval = NullUniValue;
608 std::set<std::string> setClientRules;
609 int64_t nMaxVersionPreVB = -1;
610 CChainState& active_chainstate = chainman.ActiveChainstate();
611 CChain& active_chain = active_chainstate.m_chain;
612 if (!request.params[0].isNull())
613 {
614 const UniValue& oparam = request.params[0].get_obj();
615 const UniValue& modeval = find_value(oparam, "mode");
616 if (modeval.isStr())
617 strMode = modeval.get_str();
618 else if (modeval.isNull())
619 {
620 /* Do nothing */
621 }
622 else
623 throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid mode");
624 lpval = find_value(oparam, "longpollid");
625
626 if (strMode == "proposal")
627 {
628 const UniValue& dataval = find_value(oparam, "data");
629 if (!dataval.isStr())
630 throw JSONRPCError(RPC_TYPE_ERROR, "Missing data String key for proposal");
631
632 CBlock block;
633 if (!DecodeHexBlk(block, dataval.get_str()))
634 throw JSONRPCError(RPC_DESERIALIZATION_ERROR, "Block decode failed");
635
636 uint256 hash = block.GetHash();
637 const CBlockIndex* pindex = chainman.m_blockman.LookupBlockIndex(hash);
638 if (pindex) {
639 if (pindex->IsValid(BLOCK_VALID_SCRIPTS))
640 return "duplicate";
641 if (pindex->nStatus & BLOCK_FAILED_MASK)
642 return "duplicate-invalid";
643 return "duplicate-inconclusive";
644 }
645
646 CBlockIndex* const pindexPrev = active_chain.Tip();
647 // TestBlockValidity only supports blocks built on the current Tip
648 if (block.hashPrevBlock != pindexPrev->GetBlockHash())
649 return "inconclusive-not-best-prevblk";
650 BlockValidationState state;
651 TestBlockValidity(state, Params(), active_chainstate, block, pindexPrev, false, true);
652 return BIP22ValidationResult(state);
653 }
654
655 const UniValue& aClientRules = find_value(oparam, "rules");
656 if (aClientRules.isArray()) {
657 for (unsigned int i = 0; i < aClientRules.size(); ++i) {
658 const UniValue& v = aClientRules[i];
659 setClientRules.insert(v.get_str());
660 }
661 } else {
662 // NOTE: It is important that this NOT be read if versionbits is supported
663 const UniValue& uvMaxVersion = find_value(oparam, "maxversion");
664 if (uvMaxVersion.isNum()) {
665 nMaxVersionPreVB = uvMaxVersion.get_int64();
666 }
667 }
668 }
669
670 if (strMode != "template")
671 throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid mode");
672
673 if (!Params().IsTestChain()) {
674 const CConnman& connman = EnsureConnman(node);
675 if (connman.GetNodeCount(ConnectionDirection::Both) == 0) {
676 throw JSONRPCError(RPC_CLIENT_NOT_CONNECTED, PACKAGE_NAME " is not connected!");
677 }
678
679 if (active_chainstate.IsInitialBlockDownload()) {
680 throw JSONRPCError(RPC_CLIENT_IN_INITIAL_DOWNLOAD, PACKAGE_NAME " is in initial sync and waiting for blocks...");
681 }
682 }
683
684 static unsigned int nTransactionsUpdatedLast;
685 const CTxMemPool& mempool = EnsureMemPool(node);
686
687 if (!lpval.isNull())
688 {
689 // Wait to respond until either the best block changes, OR a minute has passed and there are more transactions
690 uint256 hashWatchedChain;
691 std::chrono::steady_clock::time_point checktxtime;
692 unsigned int nTransactionsUpdatedLastLP;
693
694 if (lpval.isStr())
695 {
696 // Format: <hashBestChain><nTransactionsUpdatedLast>
697 std::string lpstr = lpval.get_str();
698
699 hashWatchedChain = ParseHashV(lpstr.substr(0, 64), "longpollid");
700 nTransactionsUpdatedLastLP = atoi64(lpstr.substr(64));
701 }
702 else
703 {
704 // NOTE: Spec does not specify behaviour for non-string longpollid, but this makes testing easier
705 hashWatchedChain = active_chain.Tip()->GetBlockHash();
706 nTransactionsUpdatedLastLP = nTransactionsUpdatedLast;
707 }
708
709 // Release lock while waiting
710 LEAVE_CRITICAL_SECTION(cs_main);
711 {
712 checktxtime = std::chrono::steady_clock::now() + std::chrono::minutes(1);
713
714 WAIT_LOCK(g_best_block_mutex, lock);
715 while (g_best_block == hashWatchedChain && IsRPCRunning())
716 {
717 if (g_best_block_cv.wait_until(lock, checktxtime) == std::cv_status::timeout)
718 {
719 // Timeout: Check transactions for update
720 // without holding the mempool lock to avoid deadlocks
721 if (mempool.GetTransactionsUpdated() != nTransactionsUpdatedLastLP)
722 break;
723 checktxtime += std::chrono::seconds(10);
724 }
725 }
726 }
727 ENTER_CRITICAL_SECTION(cs_main);
728
729 if (!IsRPCRunning())
730 throw JSONRPCError(RPC_CLIENT_NOT_CONNECTED, "Shutting down");
731 // TODO: Maybe recheck connections/IBD and (if something wrong) send an expires-immediately template to stop miners?
732 }
733
734 const Consensus::Params& consensusParams = Params().GetConsensus();
735
736 // GBT must be called with 'signet' set in the rules for signet chains
737 if (consensusParams.signet_blocks && setClientRules.count("signet") != 1) {
738 throw JSONRPCError(RPC_INVALID_PARAMETER, "getblocktemplate must be called with the signet rule set (call with {\"rules\": [\"segwit\", \"signet\"]})");
739 }
740
741 // GBT must be called with 'segwit' set in the rules
742 if (setClientRules.count("segwit") != 1) {
743 throw JSONRPCError(RPC_INVALID_PARAMETER, "getblocktemplate must be called with the segwit rule set (call with {\"rules\": [\"segwit\"]})");
744 }
745
746 // Update block
747 static CBlockIndex* pindexPrev;
748 static int64_t nStart;
749 static std::unique_ptr<CBlockTemplate> pblocktemplate;
750 if (pindexPrev != active_chain.Tip() ||
751 (mempool.GetTransactionsUpdated() != nTransactionsUpdatedLast && GetTime() - nStart > 5))
752 {
753 // Clear pindexPrev so future calls make a new block, despite any failures from here on
754 pindexPrev = nullptr;
755
756 // Store the pindexBest used before CreateNewBlock, to avoid races
757 nTransactionsUpdatedLast = mempool.GetTransactionsUpdated();
758 CBlockIndex* pindexPrevNew = active_chain.Tip();
759 nStart = GetTime();
760
761 // Create new block
762 CScript scriptDummy = CScript() << OP_TRUE;
763 pblocktemplate = BlockAssembler(active_chainstate, mempool, Params()).CreateNewBlock(scriptDummy);
764 if (!pblocktemplate)
765 throw JSONRPCError(RPC_OUT_OF_MEMORY, "Out of memory");
766
767 // Need to update only after we know CreateNewBlock succeeded
768 pindexPrev = pindexPrevNew;
769 }
770 CHECK_NONFATAL(pindexPrev);
771 CBlock* pblock = &pblocktemplate->block; // pointer for convenience
772
773 // Update nTime
774 UpdateTime(pblock, consensusParams, pindexPrev);
775 pblock->nNonce = 0;
776
777 // NOTE: If at some point we support pre-segwit miners post-segwit-activation, this needs to take segwit support into consideration
778 const bool fPreSegWit = !DeploymentActiveAfter(pindexPrev, consensusParams, Consensus::DEPLOYMENT_SEGWIT);
779
780 UniValue aCaps(UniValue::VARR); aCaps.push_back("proposal");
781
782 UniValue transactions(UniValue::VARR);
783 std::map<uint256, int64_t> setTxIndex;
784 int i = 0;
785 for (const auto& it : pblock->vtx) {
786 const CTransaction& tx = *it;
787 uint256 txHash = tx.GetHash();
788 setTxIndex[txHash] = i++;
789
790 if (tx.IsCoinBase())
791 continue;
792
793 UniValue entry(UniValue::VOBJ);
794
795 entry.pushKV("data", EncodeHexTx(tx));
796 entry.pushKV("txid", txHash.GetHex());
797 entry.pushKV("hash", tx.GetWitnessHash().GetHex());
798
799 UniValue deps(UniValue::VARR);
800 for (const CTxIn &in : tx.vin)
801 {
802 if (setTxIndex.count(in.prevout.hash))
803 deps.push_back(setTxIndex[in.prevout.hash]);
804 }
805 entry.pushKV("depends", deps);
806
807 int index_in_template = i - 1;
808 entry.pushKV("fee", pblocktemplate->vTxFees[index_in_template]);
809 int64_t nTxSigOps = pblocktemplate->vTxSigOpsCost[index_in_template];
810 if (fPreSegWit) {
811 CHECK_NONFATAL(nTxSigOps % WITNESS_SCALE_FACTOR == 0);
812 nTxSigOps /= WITNESS_SCALE_FACTOR;
813 }
814 entry.pushKV("sigops", nTxSigOps);
815 entry.pushKV("weight", GetTransactionWeight(tx));
816
817 transactions.push_back(entry);
818 }
819
820 UniValue aux(UniValue::VOBJ);
821
822 arith_uint256 hashTarget = arith_uint256().SetCompact(pblock->nBits);
823
824 UniValue aMutable(UniValue::VARR);
825 aMutable.push_back("time");
826 aMutable.push_back("transactions");
827 aMutable.push_back("prevblock");
828
829 UniValue result(UniValue::VOBJ);
830 result.pushKV("capabilities", aCaps);
831
832 UniValue aRules(UniValue::VARR);
833 aRules.push_back("csv");
834 if (!fPreSegWit) aRules.push_back("!segwit");
835 if (consensusParams.signet_blocks) {
836 // indicate to miner that they must understand signet rules
837 // when attempting to mine with this template
838 aRules.push_back("!signet");
839 }
840
841 UniValue vbavailable(UniValue::VOBJ);
842 for (int j = 0; j < (int)Consensus::MAX_VERSION_BITS_DEPLOYMENTS; ++j) {
843 Consensus::DeploymentPos pos = Consensus::DeploymentPos(j);
844 ThresholdState state = g_versionbitscache.State(pindexPrev, consensusParams, pos);
845 switch (state) {
846 case ThresholdState::DEFINED:
847 case ThresholdState::FAILED:
848 // Not exposed to GBT at all
849 break;
850 case ThresholdState::LOCKED_IN:
851 // Ensure bit is set in block version
852 pblock->nVersion |= g_versionbitscache.Mask(consensusParams, pos);
853 [[fallthrough]];
854 case ThresholdState::STARTED:
855 {
856 const struct VBDeploymentInfo& vbinfo = VersionBitsDeploymentInfo[pos];
857 vbavailable.pushKV(gbt_vb_name(pos), consensusParams.vDeployments[pos].bit);
858 if (setClientRules.find(vbinfo.name) == setClientRules.end()) {
859 if (!vbinfo.gbt_force) {
860 // If the client doesn't support this, don't indicate it in the [default] version
861 pblock->nVersion &= ~g_versionbitscache.Mask(consensusParams, pos);
862 }
863 }
864 break;
865 }
866 case ThresholdState::ACTIVE:
867 {
868 // Add to rules only
869 const struct VBDeploymentInfo& vbinfo = VersionBitsDeploymentInfo[pos];
870 aRules.push_back(gbt_vb_name(pos));
871 if (setClientRules.find(vbinfo.name) == setClientRules.end()) {
872 // Not supported by the client; make sure it's safe to proceed
873 if (!vbinfo.gbt_force) {
874 // If we do anything other than throw an exception here, be sure version/force isn't sent to old clients
875 throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("Support for '%s' rule requires explicit client support", vbinfo.name));
876 }
877 }
878 break;
879 }
880 }
881 }
882 result.pushKV("version", pblock->nVersion);
883 result.pushKV("rules", aRules);
884 result.pushKV("vbavailable", vbavailable);
885 result.pushKV("vbrequired", int(0));
886
887 if (nMaxVersionPreVB >= 2) {
888 // If VB is supported by the client, nMaxVersionPreVB is -1, so we won't get here
889 // Because BIP 34 changed how the generation transaction is serialized, we can only use version/force back to v2 blocks
890 // This is safe to do [otherwise-]unconditionally only because we are throwing an exception above if a non-force deployment gets activated
891 // Note that this can probably also be removed entirely after the first BIP9 non-force deployment (ie, probably segwit) gets activated
892 aMutable.push_back("version/force");
893 }
894
895 result.pushKV("previousblockhash", pblock->hashPrevBlock.GetHex());
896 result.pushKV("transactions", transactions);
897 result.pushKV("coinbaseaux", aux);
898 result.pushKV("coinbasevalue", (int64_t)pblock->vtx[0]->vout[0].nValue);
899 result.pushKV("longpollid", active_chain.Tip()->GetBlockHash().GetHex() + ToString(nTransactionsUpdatedLast));
900 result.pushKV("target", hashTarget.GetHex());
901 result.pushKV("mintime", (int64_t)pindexPrev->GetMedianTimePast()+1);
902 result.pushKV("mutable", aMutable);
903 result.pushKV("noncerange", "00000000ffffffff");
904 int64_t nSigOpLimit = MAX_BLOCK_SIGOPS_COST;
905 int64_t nSizeLimit = MAX_BLOCK_SERIALIZED_SIZE;
906 if (fPreSegWit) {
907 CHECK_NONFATAL(nSigOpLimit % WITNESS_SCALE_FACTOR == 0);
908 nSigOpLimit /= WITNESS_SCALE_FACTOR;
909 CHECK_NONFATAL(nSizeLimit % WITNESS_SCALE_FACTOR == 0);
910 nSizeLimit /= WITNESS_SCALE_FACTOR;
911 }
912 result.pushKV("sigoplimit", nSigOpLimit);
913 result.pushKV("sizelimit", nSizeLimit);
914 if (!fPreSegWit) {
915 result.pushKV("weightlimit", (int64_t)MAX_BLOCK_WEIGHT);
916 }
917 result.pushKV("curtime", pblock->GetBlockTime());
918 result.pushKV("bits", strprintf("%08x", pblock->nBits));
919 result.pushKV("height", (int64_t)(pindexPrev->nHeight+1));
920
921 if (consensusParams.signet_blocks) {
922 result.pushKV("signet_challenge", HexStr(consensusParams.signet_challenge));
923 }
924
925 if (!pblocktemplate->vchCoinbaseCommitment.empty()) {
926 result.pushKV("default_witness_commitment", HexStr(pblocktemplate->vchCoinbaseCommitment));
927 }
928
929 return result;
930 },
931 };
932 }
933
934 class submitblock_StateCatcher final : public CValidationInterface
935 {
936 public:
937 uint256 hash;
938 bool found;
939 BlockValidationState state;
940
941 explicit submitblock_StateCatcher(const uint256 &hashIn) : hash(hashIn), found(false), state() {}
942
943 protected:
944 void BlockChecked(const CBlock& block, const BlockValidationState& stateIn) override {
945 if (block.GetHash() != hash)
946 return;
947 found = true;
948 state = stateIn;
949 }
950 };
951
952 static RPCHelpMan submitblock()
953 {
954 // We allow 2 arguments for compliance with BIP22. Argument 2 is ignored.
955 return RPCHelpMan{"submitblock",
956 "\nAttempts to submit new block to network.\n"
957 "See https://en.bitcoin.it/wiki/BIP_0022 for full specification.\n",
958 {
959 {"hexdata", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hex-encoded block data to submit"},
960 {"dummy", RPCArg::Type::STR, RPCArg::DefaultHint{"ignored"}, "dummy value, for compatibility with BIP22. This value is ignored."},
961 },
962 {
963 RPCResult{"If the block was accepted", RPCResult::Type::NONE, "", ""},
964 RPCResult{"Otherwise", RPCResult::Type::STR, "", "According to BIP22"},
965 },
966 RPCExamples{
967 HelpExampleCli("submitblock", "\"mydata\"")
968 + HelpExampleRpc("submitblock", "\"mydata\"")
969 },
970 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
971 {
972 std::shared_ptr<CBlock> blockptr = std::make_shared<CBlock>();
973 CBlock& block = *blockptr;
974 if (!DecodeHexBlk(block, request.params[0].get_str())) {
975 throw JSONRPCError(RPC_DESERIALIZATION_ERROR, "Block decode failed");
976 }
977
978 if (block.vtx.empty() || !block.vtx[0]->IsCoinBase()) {
979 throw JSONRPCError(RPC_DESERIALIZATION_ERROR, "Block does not start with a coinbase");
980 }
981
982 ChainstateManager& chainman = EnsureAnyChainman(request.context);
983 uint256 hash = block.GetHash();
984 {
985 LOCK(cs_main);
986 const CBlockIndex* pindex = chainman.m_blockman.LookupBlockIndex(hash);
987 if (pindex) {
988 if (pindex->IsValid(BLOCK_VALID_SCRIPTS)) {
989 return "duplicate";
990 }
991 if (pindex->nStatus & BLOCK_FAILED_MASK) {
992 return "duplicate-invalid";
993 }
994 }
995 }
996
997 {
998 LOCK(cs_main);
999 const CBlockIndex* pindex = chainman.m_blockman.LookupBlockIndex(block.hashPrevBlock);
1000 if (pindex) {
1001 UpdateUncommittedBlockStructures(block, pindex, Params().GetConsensus());
1002 }
1003 }
1004
1005 bool new_block;
1006 auto sc = std::make_shared<submitblock_StateCatcher>(block.GetHash());
1007 RegisterSharedValidationInterface(sc);
1008 bool accepted = chainman.ProcessNewBlock(Params(), blockptr, /* fForceProcessing */ true, /* fNewBlock */ &new_block);
1009 UnregisterSharedValidationInterface(sc);
1010 if (!new_block && accepted) {
1011 return "duplicate";
1012 }
1013 if (!sc->found) {
1014 return "inconclusive";
1015 }
1016 return BIP22ValidationResult(sc->state);
1017 },
1018 };
1019 }
1020
1021 static RPCHelpMan submitheader()
1022 {
1023 return RPCHelpMan{"submitheader",
1024 "\nDecode the given hexdata as a header and submit it as a candidate chain tip if valid."
1025 "\nThrows when the header is invalid.\n",
1026 {
1027 {"hexdata", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "the hex-encoded block header data"},
1028 },
1029 RPCResult{
1030 RPCResult::Type::NONE, "", "None"},
1031 RPCExamples{
1032 HelpExampleCli("submitheader", "\"aabbcc\"") +
1033 HelpExampleRpc("submitheader", "\"aabbcc\"")
1034 },
1035 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
1036 {
1037 CBlockHeader h;
1038 if (!DecodeHexBlockHeader(h, request.params[0].get_str())) {
1039 throw JSONRPCError(RPC_DESERIALIZATION_ERROR, "Block header decode failed");
1040 }
1041 ChainstateManager& chainman = EnsureAnyChainman(request.context);
1042 {
1043 LOCK(cs_main);
1044 if (!chainman.m_blockman.LookupBlockIndex(h.hashPrevBlock)) {
1045 throw JSONRPCError(RPC_VERIFY_ERROR, "Must submit previous header (" + h.hashPrevBlock.GetHex() + ") first");
1046 }
1047 }
1048
1049 BlockValidationState state;
1050 chainman.ProcessNewBlockHeaders({h}, state, Params());
1051 if (state.IsValid()) return NullUniValue;
1052 if (state.IsError()) {
1053 throw JSONRPCError(RPC_VERIFY_ERROR, state.ToString());
1054 }
1055 throw JSONRPCError(RPC_VERIFY_ERROR, state.GetRejectReason());
1056 },
1057 };
1058 }
1059
1060 static RPCHelpMan estimatesmartfee()
1061 {
1062 return RPCHelpMan{"estimatesmartfee",
1063 "\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
1064 "confirmation within conf_target blocks if possible and return the number of blocks\n"
1065 "for which the estimate is valid. Uses virtual transaction size as defined\n"
1066 "in BIP 141 (witness data is discounted).\n",
1067 {
1068 {"conf_target", RPCArg::Type::NUM, RPCArg::Optional::NO, "Confirmation target in blocks (1 - 1008)"},
1069 {"estimate_mode", RPCArg::Type::STR, RPCArg::Default{"conservative"}, "The fee estimate mode.\n"
1070 " Whether to return a more conservative estimate which also satisfies\n"
1071 " a longer history. A conservative estimate potentially returns a\n"
1072 " higher feerate and is more likely to be sufficient for the desired\n"
1073 " target, but is not as responsive to short term drops in the\n"
1074 " prevailing fee market. Must be one of (case insensitive):\n"
1075 "\"" + FeeModes("\"\n\"") + "\""},
1076 },
1077 RPCResult{
1078 RPCResult::Type::OBJ, "", "",
1079 {
1080 {RPCResult::Type::NUM, "feerate", /* optional */ true, "estimate fee rate in " + CURRENCY_UNIT + "/kvB (only present if no errors were encountered)"},
1081 {RPCResult::Type::ARR, "errors", /* optional */ true, "Errors encountered during processing (if there are any)",
1082 {
1083 {RPCResult::Type::STR, "", "error"},
1084 }},
1085 {RPCResult::Type::NUM, "blocks", "block number where estimate was found\n"
1086 "The request target will be clamped between 2 and the highest target\n"
1087 "fee estimation is able to return based on how long it has been running.\n"
1088 "An error is returned if not enough transactions and blocks\n"
1089 "have been observed to make an estimate for any number of blocks."},
1090 }},
1091 RPCExamples{
1092 HelpExampleCli("estimatesmartfee", "6")
1093 },
1094 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
1095 {
1096 RPCTypeCheck(request.params, {UniValue::VNUM, UniValue::VSTR});
1097 RPCTypeCheckArgument(request.params[0], UniValue::VNUM);
1098
1099 CBlockPolicyEstimator& fee_estimator = EnsureAnyFeeEstimator(request.context);
1100
1101 unsigned int max_target = fee_estimator.HighestTargetTracked(FeeEstimateHorizon::LONG_HALFLIFE);
1102 unsigned int conf_target = ParseConfirmTarget(request.params[0], max_target);
1103 bool conservative = true;
1104 if (!request.params[1].isNull()) {
1105 FeeEstimateMode fee_mode;
1106 if (!FeeModeFromString(request.params[1].get_str(), fee_mode)) {
1107 throw JSONRPCError(RPC_INVALID_PARAMETER, InvalidEstimateModeErrorMessage());
1108 }
1109 if (fee_mode == FeeEstimateMode::ECONOMICAL) conservative = false;
1110 }
1111
1112 UniValue result(UniValue::VOBJ);
1113 UniValue errors(UniValue::VARR);
1114 FeeCalculation feeCalc;
1115 CFeeRate feeRate = fee_estimator.estimateSmartFee(conf_target, &feeCalc, conservative);
1116 if (feeRate != CFeeRate(0)) {
1117 result.pushKV("feerate", ValueFromAmount(feeRate.GetFeePerK()));
1118 } else {
1119 errors.push_back("Insufficient data or no feerate found");
1120 result.pushKV("errors", errors);
1121 }
1122 result.pushKV("blocks", feeCalc.returnedTarget);
1123 return result;
1124 },
1125 };
1126 }
1127
1128 static RPCHelpMan estimaterawfee()
1129 {
1130 return RPCHelpMan{"estimaterawfee",
1131 "\nWARNING: This interface is unstable and may disappear or change!\n"
1132 "\nWARNING: This is an advanced API call that is tightly coupled to the specific\n"
1133 " implementation of fee estimation. The parameters it can be called with\n"
1134 " and the results it returns will change if the internal implementation changes.\n"
1135 "\nEstimates the approximate fee per kilobyte needed for a transaction to begin\n"
1136 "confirmation within conf_target blocks if possible. Uses virtual transaction size as\n"
1137 "defined in BIP 141 (witness data is discounted).\n",
1138 {
1139 {"conf_target", RPCArg::Type::NUM, RPCArg::Optional::NO, "Confirmation target in blocks (1 - 1008)"},
1140 {"threshold", RPCArg::Type::NUM, RPCArg::Default{0.95}, "The proportion of transactions in a given feerate range that must have been\n"
1141 " confirmed within conf_target in order to consider those feerates as high enough and proceed to check\n"
1142 " lower buckets."},
1143 },
1144 RPCResult{
1145 RPCResult::Type::OBJ, "", "Results are returned for any horizon which tracks blocks up to the confirmation target",
1146 {
1147 {RPCResult::Type::OBJ, "short", /* optional */ true, "estimate for short time horizon",
1148 {
1149 {RPCResult::Type::NUM, "feerate", /* optional */ true, "estimate fee rate in " + CURRENCY_UNIT + "/kvB"},
1150 {RPCResult::Type::NUM, "decay", "exponential decay (per block) for historical moving average of confirmation data"},
1151 {RPCResult::Type::NUM, "scale", "The resolution of confirmation targets at this time horizon"},
1152 {RPCResult::Type::OBJ, "pass", /* optional */ true, "information about the lowest range of feerates to succeed in meeting the threshold",
1153 {
1154 {RPCResult::Type::NUM, "startrange", "start of feerate range"},
1155 {RPCResult::Type::NUM, "endrange", "end of feerate range"},
1156 {RPCResult::Type::NUM, "withintarget", "number of txs over history horizon in the feerate range that were confirmed within target"},
1157 {RPCResult::Type::NUM, "totalconfirmed", "number of txs over history horizon in the feerate range that were confirmed at any point"},
1158 {RPCResult::Type::NUM, "inmempool", "current number of txs in mempool in the feerate range unconfirmed for at least target blocks"},
1159 {RPCResult::Type::NUM, "leftmempool", "number of txs over history horizon in the feerate range that left mempool unconfirmed after target"},
1160 }},
1161 {RPCResult::Type::OBJ, "fail", /* optional */ true, "information about the highest range of feerates to fail to meet the threshold",
1162 {
1163 {RPCResult::Type::ELISION, "", ""},
1164 }},
1165 {RPCResult::Type::ARR, "errors", /* optional */ true, "Errors encountered during processing (if there are any)",
1166 {
1167 {RPCResult::Type::STR, "error", ""},
1168 }},
1169 }},
1170 {RPCResult::Type::OBJ, "medium", /* optional */ true, "estimate for medium time horizon",
1171 {
1172 {RPCResult::Type::ELISION, "", ""},
1173 }},
1174 {RPCResult::Type::OBJ, "long", /* optional */ true, "estimate for long time horizon",
1175 {
1176 {RPCResult::Type::ELISION, "", ""},
1177 }},
1178 }},
1179 RPCExamples{
1180 HelpExampleCli("estimaterawfee", "6 0.9")
1181 },
1182 [&](const RPCHelpMan& self, const JSONRPCRequest& request) -> UniValue
1183 {
1184 RPCTypeCheck(request.params, {UniValue::VNUM, UniValue::VNUM}, true);
1185 RPCTypeCheckArgument(request.params[0], UniValue::VNUM);
1186
1187 CBlockPolicyEstimator& fee_estimator = EnsureAnyFeeEstimator(request.context);
1188
1189 unsigned int max_target = fee_estimator.HighestTargetTracked(FeeEstimateHorizon::LONG_HALFLIFE);
1190 unsigned int conf_target = ParseConfirmTarget(request.params[0], max_target);
1191 double threshold = 0.95;
1192 if (!request.params[1].isNull()) {
1193 threshold = request.params[1].get_real();
1194 }
1195 if (threshold < 0 || threshold > 1) {
1196 throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid threshold");
1197 }
1198
1199 UniValue result(UniValue::VOBJ);
1200
1201 for (const FeeEstimateHorizon horizon : ALL_FEE_ESTIMATE_HORIZONS) {
1202 CFeeRate feeRate;
1203 EstimationResult buckets;
1204
1205 // Only output results for horizons which track the target
1206 if (conf_target > fee_estimator.HighestTargetTracked(horizon)) continue;
1207
1208 feeRate = fee_estimator.estimateRawFee(conf_target, threshold, horizon, &buckets);
1209 UniValue horizon_result(UniValue::VOBJ);
1210 UniValue errors(UniValue::VARR);
1211 UniValue passbucket(UniValue::VOBJ);
1212 passbucket.pushKV("startrange", round(buckets.pass.start));
1213 passbucket.pushKV("endrange", round(buckets.pass.end));
1214 passbucket.pushKV("withintarget", round(buckets.pass.withinTarget * 100.0) / 100.0);
1215 passbucket.pushKV("totalconfirmed", round(buckets.pass.totalConfirmed * 100.0) / 100.0);
1216 passbucket.pushKV("inmempool", round(buckets.pass.inMempool * 100.0) / 100.0);
1217 passbucket.pushKV("leftmempool", round(buckets.pass.leftMempool * 100.0) / 100.0);
1218 UniValue failbucket(UniValue::VOBJ);
1219 failbucket.pushKV("startrange", round(buckets.fail.start));
1220 failbucket.pushKV("endrange", round(buckets.fail.end));
1221 failbucket.pushKV("withintarget", round(buckets.fail.withinTarget * 100.0) / 100.0);
1222 failbucket.pushKV("totalconfirmed", round(buckets.fail.totalConfirmed * 100.0) / 100.0);
1223 failbucket.pushKV("inmempool", round(buckets.fail.inMempool * 100.0) / 100.0);
1224 failbucket.pushKV("leftmempool", round(buckets.fail.leftMempool * 100.0) / 100.0);
1225
1226 // CFeeRate(0) is used to indicate error as a return value from estimateRawFee
1227 if (feeRate != CFeeRate(0)) {
1228 horizon_result.pushKV("feerate", ValueFromAmount(feeRate.GetFeePerK()));
1229 horizon_result.pushKV("decay", buckets.decay);
1230 horizon_result.pushKV("scale", (int)buckets.scale);
1231 horizon_result.pushKV("pass", passbucket);
1232 // buckets.fail.start == -1 indicates that all buckets passed, there is no fail bucket to output
1233 if (buckets.fail.start != -1) horizon_result.pushKV("fail", failbucket);
1234 } else {
1235 // Output only information that is still meaningful in the event of error
1236 horizon_result.pushKV("decay", buckets.decay);
1237 horizon_result.pushKV("scale", (int)buckets.scale);
1238 horizon_result.pushKV("fail", failbucket);
1239 errors.push_back("Insufficient data or no feerate found which meets threshold");
1240 horizon_result.pushKV("errors",errors);
1241 }
1242 result.pushKV(StringForFeeEstimateHorizon(horizon), horizon_result);
1243 }
1244 return result;
1245 },
1246 };
1247 }
1248
1249 void RegisterMiningRPCCommands(CRPCTable &t)
1250 {
1251 // clang-format off
1252 static const CRPCCommand commands[] =
1253 { // category actor (function)
1254 // --------------------- -----------------------
1255 { "mining", &getnetworkhashps, },
1256 { "mining", &getmininginfo, },
1257 { "mining", &prioritisetransaction, },
1258 { "mining", &getblocktemplate, },
1259 { "mining", &submitblock, },
1260 { "mining", &submitheader, },
1261
1262
1263 { "generating", &generatetoaddress, },
1264 { "generating", &generatetodescriptor, },
1265 { "generating", &generateblock, },
1266
1267 { "util", &estimatesmartfee, },
1268
1269 { "hidden", &estimaterawfee, },
1270 { "hidden", &generate, },
1271 };
1272 // clang-format on
1273 for (const auto& c : commands) {
1274 t.appendCommand(c.name, &c);
1275 }
1276 }
1277