Bitcoin Core 29.99.0
P2P Digital Currency
util.cpp
Go to the documentation of this file.
1// Copyright (c) 2017-present 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#include <bitcoin-build-config.h> // IWYU pragma: keep
6
7#include <chain.h>
8#include <clientversion.h>
9#include <common/args.h>
10#include <common/messages.h>
11#include <common/types.h>
12#include <consensus/amount.h>
13#include <core_io.h>
14#include <key_io.h>
15#include <node/types.h>
16#include <outputtype.h>
17#include <pow.h>
18#include <rpc/util.h>
19#include <script/descriptor.h>
20#include <script/interpreter.h>
22#include <script/solver.h>
23#include <tinyformat.h>
24#include <uint256.h>
25#include <univalue.h>
26#include <util/check.h>
27#include <util/result.h>
28#include <util/strencodings.h>
29#include <util/string.h>
30#include <util/translation.h>
31
32#include <algorithm>
33#include <iterator>
34#include <string_view>
35#include <tuple>
36#include <utility>
37
42using util::Join;
45
46const std::string UNIX_EPOCH_TIME = "UNIX epoch time";
47const std::string EXAMPLE_ADDRESS[2] = {"bc1q09vm5lfy0j5reeulh4x5752q25uqqvz34hufdl", "bc1q02ad21edsxd23d32dfgqqsz4vv4nmtfzuklhy3"};
48
49std::string GetAllOutputTypes()
50{
51 std::vector<std::string> ret;
52 using U = std::underlying_type_t<TxoutType>;
53 for (U i = (U)TxoutType::NONSTANDARD; i <= (U)TxoutType::WITNESS_UNKNOWN; ++i) {
54 ret.emplace_back(GetTxnOutputType(static_cast<TxoutType>(i)));
55 }
56 return Join(ret, ", ");
57}
58
60 const std::map<std::string, UniValueType>& typesExpected,
61 bool fAllowNull,
62 bool fStrict)
63{
64 for (const auto& t : typesExpected) {
65 const UniValue& v = o.find_value(t.first);
66 if (!fAllowNull && v.isNull())
67 throw JSONRPCError(RPC_TYPE_ERROR, strprintf("Missing %s", t.first));
68
69 if (!(t.second.typeAny || v.type() == t.second.type || (fAllowNull && v.isNull())))
70 throw JSONRPCError(RPC_TYPE_ERROR, strprintf("JSON value of type %s for field %s is not of expected type %s", uvTypeName(v.type()), t.first, uvTypeName(t.second.type)));
71 }
72
73 if (fStrict)
74 {
75 for (const std::string& k : o.getKeys())
76 {
77 if (typesExpected.count(k) == 0)
78 {
79 std::string err = strprintf("Unexpected key %s", k);
80 throw JSONRPCError(RPC_TYPE_ERROR, err);
81 }
82 }
83 }
84}
85
86int ParseVerbosity(const UniValue& arg, int default_verbosity, bool allow_bool)
87{
88 if (!arg.isNull()) {
89 if (arg.isBool()) {
90 if (!allow_bool) {
91 throw JSONRPCError(RPC_TYPE_ERROR, "Verbosity was boolean but only integer allowed");
92 }
93 return arg.get_bool(); // true = 1
94 } else {
95 return arg.getInt<int>();
96 }
97 }
98 return default_verbosity;
99}
100
101CAmount AmountFromValue(const UniValue& value, int decimals)
102{
103 if (!value.isNum() && !value.isStr())
104 throw JSONRPCError(RPC_TYPE_ERROR, "Amount is not a number or string");
105 CAmount amount;
106 if (!ParseFixedPoint(value.getValStr(), decimals, &amount))
107 throw JSONRPCError(RPC_TYPE_ERROR, "Invalid amount");
108 if (!MoneyRange(amount))
109 throw JSONRPCError(RPC_TYPE_ERROR, "Amount out of range");
110 return amount;
111}
112
114{
116 if (val >= COIN) throw JSONRPCError(RPC_INVALID_PARAMETER, "Fee rates larger than or equal to 1BTC/kvB are not accepted");
117 return CFeeRate{val};
118}
119
120uint256 ParseHashV(const UniValue& v, std::string_view name)
121{
122 const std::string& strHex(v.get_str());
123 if (auto rv{uint256::FromHex(strHex)}) return *rv;
124 if (auto expected_len{uint256::size() * 2}; strHex.length() != expected_len) {
125 throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("%s must be of length %d (not %d, for '%s')", name, expected_len, strHex.length(), strHex));
126 }
127 throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("%s must be hexadecimal string (not '%s')", name, strHex));
128}
129uint256 ParseHashO(const UniValue& o, std::string_view strKey)
130{
131 return ParseHashV(o.find_value(strKey), strKey);
132}
133std::vector<unsigned char> ParseHexV(const UniValue& v, std::string_view name)
134{
135 std::string strHex;
136 if (v.isStr())
137 strHex = v.get_str();
138 if (!IsHex(strHex))
139 throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("%s must be hexadecimal string (not '%s')", name, strHex));
140 return ParseHex(strHex);
141}
142std::vector<unsigned char> ParseHexO(const UniValue& o, std::string_view strKey)
143{
144 return ParseHexV(o.find_value(strKey), strKey);
145}
146
147namespace {
148
154std::string ShellQuote(const std::string& s)
155{
156 std::string result;
157 result.reserve(s.size() * 2);
158 for (const char ch: s) {
159 if (ch == '\'') {
160 result += "'\''";
161 } else {
162 result += ch;
163 }
164 }
165 return "'" + result + "'";
166}
167
173std::string ShellQuoteIfNeeded(const std::string& s)
174{
175 for (const char ch: s) {
176 if (ch == ' ' || ch == '\'' || ch == '"') {
177 return ShellQuote(s);
178 }
179 }
180
181 return s;
182}
183
184}
185
186std::string HelpExampleCli(const std::string& methodname, const std::string& args)
187{
188 return "> bitcoin-cli " + methodname + " " + args + "\n";
189}
190
191std::string HelpExampleCliNamed(const std::string& methodname, const RPCArgList& args)
192{
193 std::string result = "> bitcoin-cli -named " + methodname;
194 for (const auto& argpair: args) {
195 const auto& value = argpair.second.isStr()
196 ? argpair.second.get_str()
197 : argpair.second.write();
198 result += " " + argpair.first + "=" + ShellQuoteIfNeeded(value);
199 }
200 result += "\n";
201 return result;
202}
203
204std::string HelpExampleRpc(const std::string& methodname, const std::string& args)
205{
206 return "> curl --user myusername --data-binary '{\"jsonrpc\": \"2.0\", \"id\": \"curltest\", "
207 "\"method\": \"" + methodname + "\", \"params\": [" + args + "]}' -H 'content-type: application/json' http://127.0.0.1:8332/\n";
208}
209
210std::string HelpExampleRpcNamed(const std::string& methodname, const RPCArgList& args)
211{
212 UniValue params(UniValue::VOBJ);
213 for (const auto& param: args) {
214 params.pushKV(param.first, param.second);
215 }
216
217 return "> curl --user myusername --data-binary '{\"jsonrpc\": \"2.0\", \"id\": \"curltest\", "
218 "\"method\": \"" + methodname + "\", \"params\": " + params.write() + "}' -H 'content-type: application/json' http://127.0.0.1:8332/\n";
219}
220
221// Converts a hex string to a public key if possible
222CPubKey HexToPubKey(const std::string& hex_in)
223{
224 if (!IsHex(hex_in)) {
225 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Pubkey \"" + hex_in + "\" must be a hex string");
226 }
227 if (hex_in.length() != 66 && hex_in.length() != 130) {
228 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Pubkey \"" + hex_in + "\" must have a length of either 33 or 65 bytes");
229 }
230 CPubKey vchPubKey(ParseHex(hex_in));
231 if (!vchPubKey.IsFullyValid()) {
232 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Pubkey \"" + hex_in + "\" must be cryptographically valid.");
233 }
234 return vchPubKey;
235}
236
237// Creates a multisig address from a given list of public keys, number of signatures required, and the address type
238CTxDestination AddAndGetMultisigDestination(const int required, const std::vector<CPubKey>& pubkeys, OutputType type, FlatSigningProvider& keystore, CScript& script_out)
239{
240 // Gather public keys
241 if (required < 1) {
242 throw JSONRPCError(RPC_INVALID_PARAMETER, "a multisignature address must require at least one key to redeem");
243 }
244 if ((int)pubkeys.size() < required) {
245 throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("not enough keys supplied (got %u keys, but need at least %d to redeem)", pubkeys.size(), required));
246 }
247 if (pubkeys.size() > MAX_PUBKEYS_PER_MULTISIG) {
248 throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("Number of keys involved in the multisignature address creation > %d\nReduce the number", MAX_PUBKEYS_PER_MULTISIG));
249 }
250
251 script_out = GetScriptForMultisig(required, pubkeys);
252
253 // Check if any keys are uncompressed. If so, the type is legacy
254 for (const CPubKey& pk : pubkeys) {
255 if (!pk.IsCompressed()) {
256 type = OutputType::LEGACY;
257 break;
258 }
259 }
260
261 if (type == OutputType::LEGACY && script_out.size() > MAX_SCRIPT_ELEMENT_SIZE) {
262 throw JSONRPCError(RPC_INVALID_PARAMETER, (strprintf("redeemScript exceeds size limit: %d > %d", script_out.size(), MAX_SCRIPT_ELEMENT_SIZE)));
263 }
264
265 // Make the address
266 CTxDestination dest = AddAndGetDestinationForScript(keystore, script_out, type);
267
268 return dest;
269}
270
272{
273public:
274 explicit DescribeAddressVisitor() = default;
275
277 {
278 return UniValue(UniValue::VOBJ);
279 }
280
282 {
283 return UniValue(UniValue::VOBJ);
284 }
285
286 UniValue operator()(const PKHash& keyID) const
287 {
289 obj.pushKV("isscript", false);
290 obj.pushKV("iswitness", false);
291 return obj;
292 }
293
294 UniValue operator()(const ScriptHash& scriptID) const
295 {
297 obj.pushKV("isscript", true);
298 obj.pushKV("iswitness", false);
299 return obj;
300 }
301
303 {
305 obj.pushKV("isscript", false);
306 obj.pushKV("iswitness", true);
307 obj.pushKV("witness_version", 0);
308 obj.pushKV("witness_program", HexStr(id));
309 return obj;
310 }
311
313 {
315 obj.pushKV("isscript", true);
316 obj.pushKV("iswitness", true);
317 obj.pushKV("witness_version", 0);
318 obj.pushKV("witness_program", HexStr(id));
319 return obj;
320 }
321
323 {
325 obj.pushKV("isscript", true);
326 obj.pushKV("iswitness", true);
327 obj.pushKV("witness_version", 1);
328 obj.pushKV("witness_program", HexStr(tap));
329 return obj;
330 }
331
332 UniValue operator()(const PayToAnchor& anchor) const
333 {
335 obj.pushKV("isscript", true);
336 obj.pushKV("iswitness", true);
337 return obj;
338 }
339
341 {
343 obj.pushKV("iswitness", true);
344 obj.pushKV("witness_version", id.GetWitnessVersion());
345 obj.pushKV("witness_program", HexStr(id.GetWitnessProgram()));
346 return obj;
347 }
348};
349
351{
352 return std::visit(DescribeAddressVisitor(), dest);
353}
354
360std::optional<int> ParseSighashString(const UniValue& sighash)
361{
362 if (sighash.isNull()) {
363 return std::nullopt;
364 }
365 const auto result{SighashFromStr(sighash.get_str())};
366 if (!result) {
368 }
369 return result.value();
370}
371
372unsigned int ParseConfirmTarget(const UniValue& value, unsigned int max_target)
373{
374 const int target{value.getInt<int>()};
375 const unsigned int unsigned_target{static_cast<unsigned int>(target)};
376 if (target < 1 || unsigned_target > max_target) {
377 throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("Invalid conf_target, must be between %u and %u", 1, max_target));
378 }
379 return unsigned_target;
380}
381
383{
384 switch (err) {
385 case PSBTError::UNSUPPORTED:
387 case PSBTError::SIGHASH_MISMATCH:
389 default: break;
390 }
392}
393
395{
396 switch (terr) {
397 case TransactionError::MEMPOOL_REJECTED:
399 case TransactionError::ALREADY_IN_UTXO_SET:
401 default: break;
402 }
404}
405
407{
408 return JSONRPCError(RPCErrorFromPSBTError(err), PSBTErrorString(err).original);
409}
410
411UniValue JSONRPCTransactionError(TransactionError terr, const std::string& err_string)
412{
413 if (err_string.length() > 0) {
414 return JSONRPCError(RPCErrorFromTransactionError(terr), err_string);
415 } else {
417 }
418}
419
424struct Section {
425 Section(const std::string& left, const std::string& right)
426 : m_left{left}, m_right{right} {}
427 std::string m_left;
428 const std::string m_right;
429};
430
435struct Sections {
436 std::vector<Section> m_sections;
437 size_t m_max_pad{0};
438
439 void PushSection(const Section& s)
440 {
441 m_max_pad = std::max(m_max_pad, s.m_left.size());
442 m_sections.push_back(s);
443 }
444
448 // NOLINTNEXTLINE(misc-no-recursion)
449 void Push(const RPCArg& arg, const size_t current_indent = 5, const OuterType outer_type = OuterType::NONE)
450 {
451 const auto indent = std::string(current_indent, ' ');
452 const auto indent_next = std::string(current_indent + 2, ' ');
453 const bool push_name{outer_type == OuterType::OBJ}; // Dictionary keys must have a name
454 const bool is_top_level_arg{outer_type == OuterType::NONE}; // True on the first recursion
455
456 switch (arg.m_type) {
464 if (is_top_level_arg) return; // Nothing more to do for non-recursive types on first recursion
465 auto left = indent;
466 if (arg.m_opts.type_str.size() != 0 && push_name) {
467 left += "\"" + arg.GetName() + "\": " + arg.m_opts.type_str.at(0);
468 } else {
469 left += push_name ? arg.ToStringObj(/*oneline=*/false) : arg.ToString(/*oneline=*/false);
470 }
471 left += ",";
472 PushSection({left, arg.ToDescriptionString(/*is_named_arg=*/push_name)});
473 break;
474 }
477 const auto right = is_top_level_arg ? "" : arg.ToDescriptionString(/*is_named_arg=*/push_name);
478 PushSection({indent + (push_name ? "\"" + arg.GetName() + "\": " : "") + "{", right});
479 for (const auto& arg_inner : arg.m_inner) {
480 Push(arg_inner, current_indent + 2, OuterType::OBJ);
481 }
482 if (arg.m_type != RPCArg::Type::OBJ) {
483 PushSection({indent_next + "...", ""});
484 }
485 PushSection({indent + "}" + (is_top_level_arg ? "" : ","), ""});
486 break;
487 }
488 case RPCArg::Type::ARR: {
489 auto left = indent;
490 left += push_name ? "\"" + arg.GetName() + "\": " : "";
491 left += "[";
492 const auto right = is_top_level_arg ? "" : arg.ToDescriptionString(/*is_named_arg=*/push_name);
493 PushSection({left, right});
494 for (const auto& arg_inner : arg.m_inner) {
495 Push(arg_inner, current_indent + 2, OuterType::ARR);
496 }
497 PushSection({indent_next + "...", ""});
498 PushSection({indent + "]" + (is_top_level_arg ? "" : ","), ""});
499 break;
500 }
501 } // no default case, so the compiler can warn about missing cases
502 }
503
507 std::string ToString() const
508 {
509 std::string ret;
510 const size_t pad = m_max_pad + 4;
511 for (const auto& s : m_sections) {
512 // The left part of a section is assumed to be a single line, usually it is the name of the JSON struct or a
513 // brace like {, }, [, or ]
514 CHECK_NONFATAL(s.m_left.find('\n') == std::string::npos);
515 if (s.m_right.empty()) {
516 ret += s.m_left;
517 ret += "\n";
518 continue;
519 }
520
521 std::string left = s.m_left;
522 left.resize(pad, ' ');
523 ret += left;
524
525 // Properly pad after newlines
526 std::string right;
527 size_t begin = 0;
528 size_t new_line_pos = s.m_right.find_first_of('\n');
529 while (true) {
530 right += s.m_right.substr(begin, new_line_pos - begin);
531 if (new_line_pos == std::string::npos) {
532 break; //No new line
533 }
534 right += "\n" + std::string(pad, ' ');
535 begin = s.m_right.find_first_not_of(' ', new_line_pos + 1);
536 if (begin == std::string::npos) {
537 break; // Empty line
538 }
539 new_line_pos = s.m_right.find_first_of('\n', begin + 1);
540 }
541 ret += right;
542 ret += "\n";
543 }
544 return ret;
545 }
546};
547
548RPCHelpMan::RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples)
549 : RPCHelpMan{std::move(name), std::move(description), std::move(args), std::move(results), std::move(examples), nullptr} {}
550
551RPCHelpMan::RPCHelpMan(std::string name, std::string description, std::vector<RPCArg> args, RPCResults results, RPCExamples examples, RPCMethodImpl fun)
552 : m_name{std::move(name)},
553 m_fun{std::move(fun)},
554 m_description{std::move(description)},
555 m_args{std::move(args)},
556 m_results{std::move(results)},
557 m_examples{std::move(examples)}
558{
559 // Map of parameter names and types just used to check whether the names are
560 // unique. Parameter names always need to be unique, with the exception that
561 // there can be pairs of POSITIONAL and NAMED parameters with the same name.
562 enum ParamType { POSITIONAL = 1, NAMED = 2, NAMED_ONLY = 4 };
563 std::map<std::string, int> param_names;
564
565 for (const auto& arg : m_args) {
566 std::vector<std::string> names = SplitString(arg.m_names, '|');
567 // Should have unique named arguments
568 for (const std::string& name : names) {
569 auto& param_type = param_names[name];
570 CHECK_NONFATAL(!(param_type & POSITIONAL));
571 CHECK_NONFATAL(!(param_type & NAMED_ONLY));
572 param_type |= POSITIONAL;
573 }
574 if (arg.m_type == RPCArg::Type::OBJ_NAMED_PARAMS) {
575 for (const auto& inner : arg.m_inner) {
576 std::vector<std::string> inner_names = SplitString(inner.m_names, '|');
577 for (const std::string& inner_name : inner_names) {
578 auto& param_type = param_names[inner_name];
579 CHECK_NONFATAL(!(param_type & POSITIONAL) || inner.m_opts.also_positional);
580 CHECK_NONFATAL(!(param_type & NAMED));
581 CHECK_NONFATAL(!(param_type & NAMED_ONLY));
582 param_type |= inner.m_opts.also_positional ? NAMED : NAMED_ONLY;
583 }
584 }
585 }
586 // Default value type should match argument type only when defined
587 if (arg.m_fallback.index() == 2) {
588 const RPCArg::Type type = arg.m_type;
589 switch (std::get<RPCArg::Default>(arg.m_fallback).getType()) {
590 case UniValue::VOBJ:
592 break;
593 case UniValue::VARR:
595 break;
596 case UniValue::VSTR:
598 break;
599 case UniValue::VNUM:
601 break;
602 case UniValue::VBOOL:
604 break;
605 case UniValue::VNULL:
606 // Null values are accepted in all arguments
607 break;
608 default:
610 break;
611 }
612 }
613 }
614}
615
617{
618 std::string result;
619 for (const auto& r : m_results) {
620 if (r.m_type == RPCResult::Type::ANY) continue; // for testing only
621 if (r.m_cond.empty()) {
622 result += "\nResult:\n";
623 } else {
624 result += "\nResult (" + r.m_cond + "):\n";
625 }
626 Sections sections;
627 r.ToSections(sections);
628 result += sections.ToString();
629 }
630 return result;
631}
632
634{
635 return m_examples.empty() ? m_examples : "\nExamples:\n" + m_examples;
636}
637
639{
640 if (request.mode == JSONRPCRequest::GET_ARGS) {
641 return GetArgMap();
642 }
643 /*
644 * Check if the given request is valid according to this command or if
645 * the user is asking for help information, and throw help when appropriate.
646 */
647 if (request.mode == JSONRPCRequest::GET_HELP || !IsValidNumArgs(request.params.size())) {
648 throw HelpResult{ToString()};
649 }
650 UniValue arg_mismatch{UniValue::VOBJ};
651 for (size_t i{0}; i < m_args.size(); ++i) {
652 const auto& arg{m_args.at(i)};
653 UniValue match{arg.MatchesType(request.params[i])};
654 if (!match.isTrue()) {
655 arg_mismatch.pushKV(strprintf("Position %s (%s)", i + 1, arg.m_names), std::move(match));
656 }
657 }
658 if (!arg_mismatch.empty()) {
659 throw JSONRPCError(RPC_TYPE_ERROR, strprintf("Wrong type passed:\n%s", arg_mismatch.write(4)));
660 }
661 CHECK_NONFATAL(m_req == nullptr);
662 m_req = &request;
663 UniValue ret = m_fun(*this, request);
664 m_req = nullptr;
665 if (gArgs.GetBoolArg("-rpcdoccheck", DEFAULT_RPC_DOC_CHECK)) {
666 UniValue mismatch{UniValue::VARR};
667 for (const auto& res : m_results.m_results) {
668 UniValue match{res.MatchesType(ret)};
669 if (match.isTrue()) {
670 mismatch.setNull();
671 break;
672 }
673 mismatch.push_back(std::move(match));
674 }
675 if (!mismatch.isNull()) {
676 std::string explain{
677 mismatch.empty() ? "no possible results defined" :
678 mismatch.size() == 1 ? mismatch[0].write(4) :
679 mismatch.write(4)};
680 throw std::runtime_error{
681 strprintf("Internal bug detected: RPC call \"%s\" returned incorrect type:\n%s\n%s %s\nPlease report this issue here: %s\n",
682 m_name, explain,
683 CLIENT_NAME, FormatFullVersion(),
684 CLIENT_BUGREPORT)};
685 }
686 }
687 return ret;
688}
689
690using CheckFn = void(const RPCArg&);
691static const UniValue* DetailMaybeArg(CheckFn* check, const std::vector<RPCArg>& params, const JSONRPCRequest* req, size_t i)
692{
693 CHECK_NONFATAL(i < params.size());
694 const UniValue& arg{CHECK_NONFATAL(req)->params[i]};
695 const RPCArg& param{params.at(i)};
696 if (check) check(param);
697
698 if (!arg.isNull()) return &arg;
699 if (!std::holds_alternative<RPCArg::Default>(param.m_fallback)) return nullptr;
700 return &std::get<RPCArg::Default>(param.m_fallback);
701}
702
703static void CheckRequiredOrDefault(const RPCArg& param)
704{
705 // Must use `Arg<Type>(key)` to get the argument or its default value.
706 const bool required{
707 std::holds_alternative<RPCArg::Optional>(param.m_fallback) && RPCArg::Optional::NO == std::get<RPCArg::Optional>(param.m_fallback),
708 };
709 CHECK_NONFATAL(required || std::holds_alternative<RPCArg::Default>(param.m_fallback));
710}
711
712#define TMPL_INST(check_param, ret_type, return_code) \
713 template <> \
714 ret_type RPCHelpMan::ArgValue<ret_type>(size_t i) const \
715 { \
716 const UniValue* maybe_arg{ \
717 DetailMaybeArg(check_param, m_args, m_req, i), \
718 }; \
719 return return_code \
720 } \
721 void force_semicolon(ret_type)
722
723// Optional arg (without default). Can also be called on required args, if needed.
724TMPL_INST(nullptr, const UniValue*, maybe_arg;);
725TMPL_INST(nullptr, std::optional<double>, maybe_arg ? std::optional{maybe_arg->get_real()} : std::nullopt;);
726TMPL_INST(nullptr, std::optional<bool>, maybe_arg ? std::optional{maybe_arg->get_bool()} : std::nullopt;);
727TMPL_INST(nullptr, const std::string*, maybe_arg ? &maybe_arg->get_str() : nullptr;);
728
729// Required arg or optional arg with default value.
731TMPL_INST(CheckRequiredOrDefault, bool, CHECK_NONFATAL(maybe_arg)->get_bool(););
732TMPL_INST(CheckRequiredOrDefault, int, CHECK_NONFATAL(maybe_arg)->getInt<int>(););
733TMPL_INST(CheckRequiredOrDefault, uint64_t, CHECK_NONFATAL(maybe_arg)->getInt<uint64_t>(););
734TMPL_INST(CheckRequiredOrDefault, uint32_t, CHECK_NONFATAL(maybe_arg)->getInt<uint32_t>(););
735TMPL_INST(CheckRequiredOrDefault, const std::string&, CHECK_NONFATAL(maybe_arg)->get_str(););
736
737bool RPCHelpMan::IsValidNumArgs(size_t num_args) const
738{
739 size_t num_required_args = 0;
740 for (size_t n = m_args.size(); n > 0; --n) {
741 if (!m_args.at(n - 1).IsOptional()) {
742 num_required_args = n;
743 break;
744 }
745 }
746 return num_required_args <= num_args && num_args <= m_args.size();
747}
748
749std::vector<std::pair<std::string, bool>> RPCHelpMan::GetArgNames() const
750{
751 std::vector<std::pair<std::string, bool>> ret;
752 ret.reserve(m_args.size());
753 for (const auto& arg : m_args) {
754 if (arg.m_type == RPCArg::Type::OBJ_NAMED_PARAMS) {
755 for (const auto& inner : arg.m_inner) {
756 ret.emplace_back(inner.m_names, /*named_only=*/true);
757 }
758 }
759 ret.emplace_back(arg.m_names, /*named_only=*/false);
760 }
761 return ret;
762}
763
764size_t RPCHelpMan::GetParamIndex(std::string_view key) const
765{
766 auto it{std::find_if(
767 m_args.begin(), m_args.end(), [&key](const auto& arg) { return arg.GetName() == key;}
768 )};
769
770 CHECK_NONFATAL(it != m_args.end()); // TODO: ideally this is checked at compile time
771 return std::distance(m_args.begin(), it);
772}
773
774std::string RPCHelpMan::ToString() const
775{
776 std::string ret;
777
778 // Oneline summary
779 ret += m_name;
780 bool was_optional{false};
781 for (const auto& arg : m_args) {
782 if (arg.m_opts.hidden) break; // Any arg that follows is also hidden
783 const bool optional = arg.IsOptional();
784 ret += " ";
785 if (optional) {
786 if (!was_optional) ret += "( ";
787 was_optional = true;
788 } else {
789 if (was_optional) ret += ") ";
790 was_optional = false;
791 }
792 ret += arg.ToString(/*oneline=*/true);
793 }
794 if (was_optional) ret += " )";
795
796 // Description
797 CHECK_NONFATAL(!m_description.starts_with('\n')); // Historically \n was required, but reject it for new code.
798 ret += "\n\n" + TrimString(m_description) + "\n";
799
800 // Arguments
801 Sections sections;
802 Sections named_only_sections;
803 for (size_t i{0}; i < m_args.size(); ++i) {
804 const auto& arg = m_args.at(i);
805 if (arg.m_opts.hidden) break; // Any arg that follows is also hidden
806
807 // Push named argument name and description
808 sections.m_sections.emplace_back(util::ToString(i + 1) + ". " + arg.GetFirstName(), arg.ToDescriptionString(/*is_named_arg=*/true));
809 sections.m_max_pad = std::max(sections.m_max_pad, sections.m_sections.back().m_left.size());
810
811 // Recursively push nested args
812 sections.Push(arg);
813
814 // Push named-only argument sections
815 if (arg.m_type == RPCArg::Type::OBJ_NAMED_PARAMS) {
816 for (const auto& arg_inner : arg.m_inner) {
817 named_only_sections.PushSection({arg_inner.GetFirstName(), arg_inner.ToDescriptionString(/*is_named_arg=*/true)});
818 named_only_sections.Push(arg_inner);
819 }
820 }
821 }
822
823 if (!sections.m_sections.empty()) ret += "\nArguments:\n";
824 ret += sections.ToString();
825 if (!named_only_sections.m_sections.empty()) ret += "\nNamed Arguments:\n";
826 ret += named_only_sections.ToString();
827
828 // Result
830
831 // Examples
833
834 return ret;
835}
836
838{
840
841 auto push_back_arg_info = [&arr](const std::string& rpc_name, int pos, const std::string& arg_name, const RPCArg::Type& type) {
843 map.push_back(rpc_name);
844 map.push_back(pos);
845 map.push_back(arg_name);
846 map.push_back(type == RPCArg::Type::STR ||
847 type == RPCArg::Type::STR_HEX);
848 arr.push_back(std::move(map));
849 };
850
851 for (int i{0}; i < int(m_args.size()); ++i) {
852 const auto& arg = m_args.at(i);
853 std::vector<std::string> arg_names = SplitString(arg.m_names, '|');
854 for (const auto& arg_name : arg_names) {
855 push_back_arg_info(m_name, i, arg_name, arg.m_type);
856 if (arg.m_type == RPCArg::Type::OBJ_NAMED_PARAMS) {
857 for (const auto& inner : arg.m_inner) {
858 std::vector<std::string> inner_names = SplitString(inner.m_names, '|');
859 for (const std::string& inner_name : inner_names) {
860 push_back_arg_info(m_name, i, inner_name, inner.m_type);
861 }
862 }
863 }
864 }
865 }
866 return arr;
867}
868
869static std::optional<UniValue::VType> ExpectedType(RPCArg::Type type)
870{
871 using Type = RPCArg::Type;
872 switch (type) {
873 case Type::STR_HEX:
874 case Type::STR: {
875 return UniValue::VSTR;
876 }
877 case Type::NUM: {
878 return UniValue::VNUM;
879 }
880 case Type::AMOUNT: {
881 // VNUM or VSTR, checked inside AmountFromValue()
882 return std::nullopt;
883 }
884 case Type::RANGE: {
885 // VNUM or VARR, checked inside ParseRange()
886 return std::nullopt;
887 }
888 case Type::BOOL: {
889 return UniValue::VBOOL;
890 }
891 case Type::OBJ:
892 case Type::OBJ_NAMED_PARAMS:
893 case Type::OBJ_USER_KEYS: {
894 return UniValue::VOBJ;
895 }
896 case Type::ARR: {
897 return UniValue::VARR;
898 }
899 } // no default case, so the compiler can warn about missing cases
901}
902
904{
905 if (m_opts.skip_type_check) return true;
906 if (IsOptional() && request.isNull()) return true;
907 const auto exp_type{ExpectedType(m_type)};
908 if (!exp_type) return true; // nothing to check
909
910 if (*exp_type != request.getType()) {
911 return strprintf("JSON value of type %s is not of expected type %s", uvTypeName(request.getType()), uvTypeName(*exp_type));
912 }
913 return true;
914}
915
916std::string RPCArg::GetFirstName() const
917{
918 return m_names.substr(0, m_names.find('|'));
919}
920
921std::string RPCArg::GetName() const
922{
923 CHECK_NONFATAL(std::string::npos == m_names.find('|'));
924 return m_names;
925}
926
928{
929 if (m_fallback.index() != 0) {
930 return true;
931 } else {
932 return RPCArg::Optional::NO != std::get<RPCArg::Optional>(m_fallback);
933 }
934}
935
936std::string RPCArg::ToDescriptionString(bool is_named_arg) const
937{
938 std::string ret;
939 ret += "(";
940 if (m_opts.type_str.size() != 0) {
941 ret += m_opts.type_str.at(1);
942 } else {
943 switch (m_type) {
944 case Type::STR_HEX:
945 case Type::STR: {
946 ret += "string";
947 break;
948 }
949 case Type::NUM: {
950 ret += "numeric";
951 break;
952 }
953 case Type::AMOUNT: {
954 ret += "numeric or string";
955 break;
956 }
957 case Type::RANGE: {
958 ret += "numeric or array";
959 break;
960 }
961 case Type::BOOL: {
962 ret += "boolean";
963 break;
964 }
965 case Type::OBJ:
967 case Type::OBJ_USER_KEYS: {
968 ret += "json object";
969 break;
970 }
971 case Type::ARR: {
972 ret += "json array";
973 break;
974 }
975 } // no default case, so the compiler can warn about missing cases
976 }
977 if (m_fallback.index() == 1) {
978 ret += ", optional, default=" + std::get<RPCArg::DefaultHint>(m_fallback);
979 } else if (m_fallback.index() == 2) {
980 ret += ", optional, default=" + std::get<RPCArg::Default>(m_fallback).write();
981 } else {
982 switch (std::get<RPCArg::Optional>(m_fallback)) {
984 if (is_named_arg) ret += ", optional"; // Default value is "null" in dicts. Otherwise,
985 // nothing to do. Element is treated as if not present and has no default value
986 break;
987 }
989 ret += ", required";
990 break;
991 }
992 } // no default case, so the compiler can warn about missing cases
993 }
994 ret += ")";
995 if (m_type == Type::OBJ_NAMED_PARAMS) ret += " Options object that can be used to pass named arguments, listed below.";
996 ret += m_description.empty() ? "" : " " + m_description;
997 return ret;
998}
999
1000// NOLINTNEXTLINE(misc-no-recursion)
1001void RPCResult::ToSections(Sections& sections, const OuterType outer_type, const int current_indent) const
1002{
1003 // Indentation
1004 const std::string indent(current_indent, ' ');
1005 const std::string indent_next(current_indent + 2, ' ');
1006
1007 // Elements in a JSON structure (dictionary or array) are separated by a comma
1008 const std::string maybe_separator{outer_type != OuterType::NONE ? "," : ""};
1009
1010 // The key name if recursed into a dictionary
1011 const std::string maybe_key{
1012 outer_type == OuterType::OBJ ?
1013 "\"" + this->m_key_name + "\" : " :
1014 ""};
1015
1016 // Format description with type
1017 const auto Description = [&](const std::string& type) {
1018 return "(" + type + (this->m_optional ? ", optional" : "") + ")" +
1019 (this->m_description.empty() ? "" : " " + this->m_description);
1020 };
1021
1022 switch (m_type) {
1023 case Type::ELISION: {
1024 // If the inner result is empty, use three dots for elision
1025 sections.PushSection({indent + "..." + maybe_separator, m_description});
1026 return;
1027 }
1028 case Type::ANY: {
1029 NONFATAL_UNREACHABLE(); // Only for testing
1030 }
1031 case Type::NONE: {
1032 sections.PushSection({indent + "null" + maybe_separator, Description("json null")});
1033 return;
1034 }
1035 case Type::STR: {
1036 sections.PushSection({indent + maybe_key + "\"str\"" + maybe_separator, Description("string")});
1037 return;
1038 }
1039 case Type::STR_AMOUNT: {
1040 sections.PushSection({indent + maybe_key + "n" + maybe_separator, Description("numeric")});
1041 return;
1042 }
1043 case Type::STR_HEX: {
1044 sections.PushSection({indent + maybe_key + "\"hex\"" + maybe_separator, Description("string")});
1045 return;
1046 }
1047 case Type::NUM: {
1048 sections.PushSection({indent + maybe_key + "n" + maybe_separator, Description("numeric")});
1049 return;
1050 }
1051 case Type::NUM_TIME: {
1052 sections.PushSection({indent + maybe_key + "xxx" + maybe_separator, Description("numeric")});
1053 return;
1054 }
1055 case Type::BOOL: {
1056 sections.PushSection({indent + maybe_key + "true|false" + maybe_separator, Description("boolean")});
1057 return;
1058 }
1059 case Type::ARR_FIXED:
1060 case Type::ARR: {
1061 sections.PushSection({indent + maybe_key + "[", Description("json array")});
1062 for (const auto& i : m_inner) {
1063 i.ToSections(sections, OuterType::ARR, current_indent + 2);
1064 }
1065 CHECK_NONFATAL(!m_inner.empty());
1066 if (m_type == Type::ARR && m_inner.back().m_type != Type::ELISION) {
1067 sections.PushSection({indent_next + "...", ""});
1068 } else {
1069 // Remove final comma, which would be invalid JSON
1070 sections.m_sections.back().m_left.pop_back();
1071 }
1072 sections.PushSection({indent + "]" + maybe_separator, ""});
1073 return;
1074 }
1075 case Type::OBJ_DYN:
1076 case Type::OBJ: {
1077 if (m_inner.empty()) {
1078 sections.PushSection({indent + maybe_key + "{}", Description("empty JSON object")});
1079 return;
1080 }
1081 sections.PushSection({indent + maybe_key + "{", Description("json object")});
1082 for (const auto& i : m_inner) {
1083 i.ToSections(sections, OuterType::OBJ, current_indent + 2);
1084 }
1085 if (m_type == Type::OBJ_DYN && m_inner.back().m_type != Type::ELISION) {
1086 // If the dictionary keys are dynamic, use three dots for continuation
1087 sections.PushSection({indent_next + "...", ""});
1088 } else {
1089 // Remove final comma, which would be invalid JSON
1090 sections.m_sections.back().m_left.pop_back();
1091 }
1092 sections.PushSection({indent + "}" + maybe_separator, ""});
1093 return;
1094 }
1095 } // no default case, so the compiler can warn about missing cases
1097}
1098
1099static std::optional<UniValue::VType> ExpectedType(RPCResult::Type type)
1100{
1101 using Type = RPCResult::Type;
1102 switch (type) {
1103 case Type::ELISION:
1104 case Type::ANY: {
1105 return std::nullopt;
1106 }
1107 case Type::NONE: {
1108 return UniValue::VNULL;
1109 }
1110 case Type::STR:
1111 case Type::STR_HEX: {
1112 return UniValue::VSTR;
1113 }
1114 case Type::NUM:
1115 case Type::STR_AMOUNT:
1116 case Type::NUM_TIME: {
1117 return UniValue::VNUM;
1118 }
1119 case Type::BOOL: {
1120 return UniValue::VBOOL;
1121 }
1122 case Type::ARR_FIXED:
1123 case Type::ARR: {
1124 return UniValue::VARR;
1125 }
1126 case Type::OBJ_DYN:
1127 case Type::OBJ: {
1128 return UniValue::VOBJ;
1129 }
1130 } // no default case, so the compiler can warn about missing cases
1132}
1133
1134// NOLINTNEXTLINE(misc-no-recursion)
1136{
1137 if (m_skip_type_check) {
1138 return true;
1139 }
1140
1141 const auto exp_type = ExpectedType(m_type);
1142 if (!exp_type) return true; // can be any type, so nothing to check
1143
1144 if (*exp_type != result.getType()) {
1145 return strprintf("returned type is %s, but declared as %s in doc", uvTypeName(result.getType()), uvTypeName(*exp_type));
1146 }
1147
1148 if (UniValue::VARR == result.getType()) {
1149 UniValue errors(UniValue::VOBJ);
1150 for (size_t i{0}; i < result.get_array().size(); ++i) {
1151 // If there are more results than documented, reuse the last doc_inner.
1152 const RPCResult& doc_inner{m_inner.at(std::min(m_inner.size() - 1, i))};
1153 UniValue match{doc_inner.MatchesType(result.get_array()[i])};
1154 if (!match.isTrue()) errors.pushKV(strprintf("%d", i), std::move(match));
1155 }
1156 if (errors.empty()) return true; // empty result array is valid
1157 return errors;
1158 }
1159
1160 if (UniValue::VOBJ == result.getType()) {
1161 if (!m_inner.empty() && m_inner.at(0).m_type == Type::ELISION) return true;
1162 UniValue errors(UniValue::VOBJ);
1163 if (m_type == Type::OBJ_DYN) {
1164 const RPCResult& doc_inner{m_inner.at(0)}; // Assume all types are the same, randomly pick the first
1165 for (size_t i{0}; i < result.get_obj().size(); ++i) {
1166 UniValue match{doc_inner.MatchesType(result.get_obj()[i])};
1167 if (!match.isTrue()) errors.pushKV(result.getKeys()[i], std::move(match));
1168 }
1169 if (errors.empty()) return true; // empty result obj is valid
1170 return errors;
1171 }
1172 std::set<std::string> doc_keys;
1173 for (const auto& doc_entry : m_inner) {
1174 doc_keys.insert(doc_entry.m_key_name);
1175 }
1176 std::map<std::string, UniValue> result_obj;
1177 result.getObjMap(result_obj);
1178 for (const auto& result_entry : result_obj) {
1179 if (doc_keys.find(result_entry.first) == doc_keys.end()) {
1180 errors.pushKV(result_entry.first, "key returned that was not in doc");
1181 }
1182 }
1183
1184 for (const auto& doc_entry : m_inner) {
1185 const auto result_it{result_obj.find(doc_entry.m_key_name)};
1186 if (result_it == result_obj.end()) {
1187 if (!doc_entry.m_optional) {
1188 errors.pushKV(doc_entry.m_key_name, "key missing, despite not being optional in doc");
1189 }
1190 continue;
1191 }
1192 UniValue match{doc_entry.MatchesType(result_it->second)};
1193 if (!match.isTrue()) errors.pushKV(doc_entry.m_key_name, std::move(match));
1194 }
1195 if (errors.empty()) return true;
1196 return errors;
1197 }
1198
1199 return true;
1200}
1201
1203{
1204 if (m_type == Type::OBJ) {
1205 // May or may not be empty
1206 return;
1207 }
1208 // Everything else must either be empty or not
1209 const bool inner_needed{m_type == Type::ARR || m_type == Type::ARR_FIXED || m_type == Type::OBJ_DYN};
1210 CHECK_NONFATAL(inner_needed != m_inner.empty());
1211}
1212
1213// NOLINTNEXTLINE(misc-no-recursion)
1214std::string RPCArg::ToStringObj(const bool oneline) const
1215{
1216 std::string res;
1217 res += "\"";
1218 res += GetFirstName();
1219 if (oneline) {
1220 res += "\":";
1221 } else {
1222 res += "\": ";
1223 }
1224 switch (m_type) {
1225 case Type::STR:
1226 return res + "\"str\"";
1227 case Type::STR_HEX:
1228 return res + "\"hex\"";
1229 case Type::NUM:
1230 return res + "n";
1231 case Type::RANGE:
1232 return res + "n or [n,n]";
1233 case Type::AMOUNT:
1234 return res + "amount";
1235 case Type::BOOL:
1236 return res + "bool";
1237 case Type::ARR:
1238 res += "[";
1239 for (const auto& i : m_inner) {
1240 res += i.ToString(oneline) + ",";
1241 }
1242 return res + "...]";
1243 case Type::OBJ:
1246 // Currently unused, so avoid writing dead code
1248 } // no default case, so the compiler can warn about missing cases
1250}
1251
1252// NOLINTNEXTLINE(misc-no-recursion)
1253std::string RPCArg::ToString(const bool oneline) const
1254{
1255 if (oneline && !m_opts.oneline_description.empty()) {
1256 if (m_opts.oneline_description[0] == '\"' && m_type != Type::STR_HEX && m_type != Type::STR && gArgs.GetBoolArg("-rpcdoccheck", DEFAULT_RPC_DOC_CHECK)) {
1257 throw std::runtime_error{
1258 STR_INTERNAL_BUG(strprintf("non-string RPC arg \"%s\" quotes oneline_description:\n%s",
1260 )};
1261 }
1263 }
1264
1265 switch (m_type) {
1266 case Type::STR_HEX:
1267 case Type::STR: {
1268 return "\"" + GetFirstName() + "\"";
1269 }
1270 case Type::NUM:
1271 case Type::RANGE:
1272 case Type::AMOUNT:
1273 case Type::BOOL: {
1274 return GetFirstName();
1275 }
1276 case Type::OBJ:
1278 case Type::OBJ_USER_KEYS: {
1279 // NOLINTNEXTLINE(misc-no-recursion)
1280 const std::string res = Join(m_inner, ",", [&](const RPCArg& i) { return i.ToStringObj(oneline); });
1281 if (m_type == Type::OBJ) {
1282 return "{" + res + "}";
1283 } else {
1284 return "{" + res + ",...}";
1285 }
1286 }
1287 case Type::ARR: {
1288 std::string res;
1289 for (const auto& i : m_inner) {
1290 res += i.ToString(oneline) + ",";
1291 }
1292 return "[" + res + "...]";
1293 }
1294 } // no default case, so the compiler can warn about missing cases
1296}
1297
1298static std::pair<int64_t, int64_t> ParseRange(const UniValue& value)
1299{
1300 if (value.isNum()) {
1301 return {0, value.getInt<int64_t>()};
1302 }
1303 if (value.isArray() && value.size() == 2 && value[0].isNum() && value[1].isNum()) {
1304 int64_t low = value[0].getInt<int64_t>();
1305 int64_t high = value[1].getInt<int64_t>();
1306 if (low > high) throw JSONRPCError(RPC_INVALID_PARAMETER, "Range specified as [begin,end] must not have begin after end");
1307 return {low, high};
1308 }
1309 throw JSONRPCError(RPC_INVALID_PARAMETER, "Range must be specified as end or as [begin,end]");
1310}
1311
1312std::pair<int64_t, int64_t> ParseDescriptorRange(const UniValue& value)
1313{
1314 int64_t low, high;
1315 std::tie(low, high) = ParseRange(value);
1316 if (low < 0) {
1317 throw JSONRPCError(RPC_INVALID_PARAMETER, "Range should be greater or equal than 0");
1318 }
1319 if ((high >> 31) != 0) {
1320 throw JSONRPCError(RPC_INVALID_PARAMETER, "End of range is too high");
1321 }
1322 if (high >= low + 1000000) {
1323 throw JSONRPCError(RPC_INVALID_PARAMETER, "Range is too large");
1324 }
1325 return {low, high};
1326}
1327
1328std::vector<CScript> EvalDescriptorStringOrObject(const UniValue& scanobject, FlatSigningProvider& provider, const bool expand_priv)
1329{
1330 std::string desc_str;
1331 std::pair<int64_t, int64_t> range = {0, 1000};
1332 if (scanobject.isStr()) {
1333 desc_str = scanobject.get_str();
1334 } else if (scanobject.isObject()) {
1335 const UniValue& desc_uni{scanobject.find_value("desc")};
1336 if (desc_uni.isNull()) throw JSONRPCError(RPC_INVALID_PARAMETER, "Descriptor needs to be provided in scan object");
1337 desc_str = desc_uni.get_str();
1338 const UniValue& range_uni{scanobject.find_value("range")};
1339 if (!range_uni.isNull()) {
1340 range = ParseDescriptorRange(range_uni);
1341 }
1342 } else {
1343 throw JSONRPCError(RPC_INVALID_PARAMETER, "Scan object needs to be either a string or an object");
1344 }
1345
1346 std::string error;
1347 auto descs = Parse(desc_str, provider, error);
1348 if (descs.empty()) {
1350 }
1351 if (!descs.at(0)->IsRange()) {
1352 range.first = 0;
1353 range.second = 0;
1354 }
1355 std::vector<CScript> ret;
1356 for (int i = range.first; i <= range.second; ++i) {
1357 for (const auto& desc : descs) {
1358 std::vector<CScript> scripts;
1359 if (!desc->Expand(i, provider, scripts, provider)) {
1360 throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, strprintf("Cannot derive script without private keys: '%s'", desc_str));
1361 }
1362 if (expand_priv) {
1363 desc->ExpandPrivate(/*pos=*/i, provider, /*out=*/provider);
1364 }
1365 std::move(scripts.begin(), scripts.end(), std::back_inserter(ret));
1366 }
1367 }
1368 return ret;
1369}
1370
1372[[nodiscard]] static UniValue BilingualStringsToUniValue(const std::vector<bilingual_str>& bilingual_strings)
1373{
1374 CHECK_NONFATAL(!bilingual_strings.empty());
1375 UniValue result{UniValue::VARR};
1376 for (const auto& s : bilingual_strings) {
1377 result.push_back(s.original);
1378 }
1379 return result;
1380}
1381
1382void PushWarnings(const UniValue& warnings, UniValue& obj)
1383{
1384 if (warnings.empty()) return;
1385 obj.pushKV("warnings", warnings);
1386}
1387
1388void PushWarnings(const std::vector<bilingual_str>& warnings, UniValue& obj)
1389{
1390 if (warnings.empty()) return;
1391 obj.pushKV("warnings", BilingualStringsToUniValue(warnings));
1392}
1393
1394std::vector<RPCResult> ScriptPubKeyDoc() {
1395 return
1396 {
1397 {RPCResult::Type::STR, "asm", "Disassembly of the output script"},
1398 {RPCResult::Type::STR, "desc", "Inferred descriptor for the output"},
1399 {RPCResult::Type::STR_HEX, "hex", "The raw output script bytes, hex-encoded"},
1400 {RPCResult::Type::STR, "address", /*optional=*/true, "The Bitcoin address (only if a well-defined address exists)"},
1401 {RPCResult::Type::STR, "type", "The type (one of: " + GetAllOutputTypes() + ")"},
1402 };
1403}
1404
1405uint256 GetTarget(const CBlockIndex& blockindex, const uint256 pow_limit)
1406{
1407 arith_uint256 target{*CHECK_NONFATAL(DeriveTarget(blockindex.nBits, pow_limit))};
1408 return ArithToUint256(target);
1409}
std::variant< CNoDestination, PubKeyDestination, PKHash, ScriptHash, WitnessV0ScriptHash, WitnessV0KeyHash, WitnessV1Taproot, PayToAnchor, WitnessUnknown > CTxDestination
A txout script categorized into standard templates.
Definition: addresstype.h:143
bool MoneyRange(const CAmount &nValue)
Definition: amount.h:27
int64_t CAmount
Amount in satoshis (Can be negative)
Definition: amount.h:12
static constexpr CAmount COIN
The amount of satoshis in one BTC.
Definition: amount.h:15
ArgsManager gArgs
Definition: args.cpp:42
uint256 ArithToUint256(const arith_uint256 &a)
int ret
ArgsManager & args
Definition: bitcoind.cpp:277
#define CHECK_NONFATAL(condition)
Identity function.
Definition: check.h:102
#define NONFATAL_UNREACHABLE()
NONFATAL_UNREACHABLE() is a macro that is used to mark unreachable code.
Definition: check.h:123
#define STR_INTERNAL_BUG(msg)
Definition: check.h:89
bool GetBoolArg(const std::string &strArg, bool fDefault) const
Return boolean argument or default value.
Definition: args.cpp:507
The block chain is a tree shaped structure starting with the genesis block at the root,...
Definition: chain.h:141
uint32_t nBits
Definition: chain.h:190
Fee rate in satoshis per virtualbyte: CAmount / vB the feerate is represented internally as FeeFrac.
Definition: feerate.h:35
An encapsulated public key.
Definition: pubkey.h:34
bool IsFullyValid() const
fully validate whether this is a valid public key (more expensive than IsValid())
Definition: pubkey.cpp:320
Serialized script, used inside transaction inputs and outputs.
Definition: script.h:413
UniValue operator()(const WitnessUnknown &id) const
Definition: util.cpp:340
UniValue operator()(const WitnessV0KeyHash &id) const
Definition: util.cpp:302
UniValue operator()(const WitnessV0ScriptHash &id) const
Definition: util.cpp:312
DescribeAddressVisitor()=default
UniValue operator()(const CNoDestination &dest) const
Definition: util.cpp:276
UniValue operator()(const PubKeyDestination &dest) const
Definition: util.cpp:281
UniValue operator()(const WitnessV1Taproot &tap) const
Definition: util.cpp:322
UniValue operator()(const ScriptHash &scriptID) const
Definition: util.cpp:294
UniValue operator()(const PKHash &keyID) const
Definition: util.cpp:286
UniValue operator()(const PayToAnchor &anchor) const
Definition: util.cpp:332
UniValue params
Definition: request.h:57
enum JSONRPCRequest::Mode mode
std::function< UniValue(const RPCHelpMan &, const JSONRPCRequest &)> RPCMethodImpl
Definition: util.h:422
const RPCExamples m_examples
Definition: util.h:503
size_t GetParamIndex(std::string_view key) const
Return positional index of a parameter using its name as key.
Definition: util.cpp:764
RPCHelpMan(std::string name, std::string description, std::vector< RPCArg > args, RPCResults results, RPCExamples examples)
Definition: util.cpp:548
const std::string m_description
Definition: util.h:500
bool IsValidNumArgs(size_t num_args) const
If the supplied number of args is neither too small nor too high.
Definition: util.cpp:737
const RPCMethodImpl m_fun
Definition: util.h:499
const std::string m_name
Definition: util.h:496
const RPCResults m_results
Definition: util.h:502
const std::vector< RPCArg > m_args
Definition: util.h:501
std::string ToString() const
Definition: util.cpp:774
UniValue GetArgMap() const
Return the named args that need to be converted from string to another JSON type.
Definition: util.cpp:837
std::vector< std::pair< std::string, bool > > GetArgNames() const
Return list of arguments and whether they are named-only.
Definition: util.cpp:749
const JSONRPCRequest * m_req
Definition: util.h:504
UniValue HandleRequest(const JSONRPCRequest &request) const
Definition: util.cpp:638
const std::string & get_str() const
bool isArray() const
Definition: univalue.h:87
const UniValue & find_value(std::string_view key) const
Definition: univalue.cpp:233
enum VType getType() const
Definition: univalue.h:67
@ VNULL
Definition: univalue.h:24
@ VOBJ
Definition: univalue.h:24
@ VSTR
Definition: univalue.h:24
@ VARR
Definition: univalue.h:24
@ VNUM
Definition: univalue.h:24
@ VBOOL
Definition: univalue.h:24
std::string write(unsigned int prettyIndent=0, unsigned int indentLevel=0) const
bool isNull() const
Definition: univalue.h:81
const std::string & getValStr() const
Definition: univalue.h:68
const UniValue & get_obj() const
void setNull()
Definition: univalue.cpp:26
size_t size() const
Definition: univalue.h:71
enum VType type() const
Definition: univalue.h:128
const std::vector< std::string > & getKeys() const
bool empty() const
Definition: univalue.h:69
bool isStr() const
Definition: univalue.h:85
bool isBool() const
Definition: univalue.h:84
Int getInt() const
Definition: univalue.h:140
const UniValue & get_array() const
bool isNum() const
Definition: univalue.h:86
void pushKV(std::string key, UniValue val)
Definition: univalue.cpp:126
void getObjMap(std::map< std::string, UniValue > &kv) const
Definition: univalue.cpp:146
bool get_bool() const
bool isObject() const
Definition: univalue.h:88
256-bit unsigned big integer.
static constexpr unsigned int size()
Definition: uint256.h:107
size_type size() const
Definition: prevector.h:255
256-bit opaque blob.
Definition: uint256.h:196
static std::optional< uint256 > FromHex(std::string_view str)
Definition: uint256.h:198
static UniValue Parse(std::string_view raw)
Parse string to UniValue or throw runtime_error if string contains invalid JSON.
Definition: client.cpp:321
std::string FormatFullVersion()
is a home for simple enum and struct type definitions that can be used internally by functions in the...
util::Result< int > SighashFromStr(const std::string &sighash)
Definition: core_read.cpp:237
std::string HexStr(const std::span< const uint8_t > s)
Convert a span of bytes to a lower-case hexadecimal string.
Definition: hex_base.cpp:29
is a home for simple string functions returning descriptive messages that are used in RPC and GUI int...
@ NONE
Definition: logging.h:65
char const * json() noexcept
Template to generate JSON data.
PSBTError
Definition: types.h:17
bilingual_str PSBTErrorString(PSBTError err)
Definition: messages.cpp:106
bilingual_str TransactionErrorString(const TransactionError err)
Definition: messages.cpp:128
TransactionError
Definition: types.h:24
std::vector< std::string > SplitString(std::string_view str, char sep)
Definition: string.h:148
bilingual_str ErrorString(const Result< T > &result)
Definition: result.h:93
std::string ToString(const T &t)
Locale-independent version of std::to_string.
Definition: string.h:245
std::string TrimString(std::string_view str, std::string_view pattern=" \f\n\r\t\v")
Definition: string.h:168
auto Join(const C &container, const S &separator, UnaryOp unary_op)
Join all container items.
Definition: string.h:204
is a home for public enum and struct type definitions that are used internally by node code,...
CTxDestination AddAndGetDestinationForScript(FlatSigningProvider &keystore, const CScript &script, OutputType type)
Get a destination of the requested type (if possible) to the specified script.
Definition: outputtype.cpp:54
OutputType
Definition: outputtype.h:17
std::optional< arith_uint256 > DeriveTarget(unsigned int nBits, const uint256 pow_limit)
Convert nBits value to target.
Definition: pow.cpp:146
UniValue JSONRPCError(int code, const std::string &message)
Definition: request.cpp:70
const char * name
Definition: rest.cpp:50
RPCErrorCode
Bitcoin RPC error codes.
Definition: protocol.h:25
@ RPC_VERIFY_ALREADY_IN_UTXO_SET
Transaction already in utxo set.
Definition: protocol.h:49
@ RPC_TYPE_ERROR
Unexpected type was passed as parameter.
Definition: protocol.h:41
@ RPC_TRANSACTION_REJECTED
Definition: protocol.h:55
@ RPC_TRANSACTION_ERROR
Aliases for backward compatibility.
Definition: protocol.h:54
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
Definition: protocol.h:44
@ RPC_DESERIALIZATION_ERROR
Error parsing or validating structure in raw format.
Definition: protocol.h:46
@ RPC_INVALID_ADDRESS_OR_KEY
Invalid address or key.
Definition: protocol.h:42
static const UniValue * DetailMaybeArg(CheckFn *check, const std::vector< RPCArg > &params, const JSONRPCRequest *req, size_t i)
Definition: util.cpp:691
std::vector< CScript > EvalDescriptorStringOrObject(const UniValue &scanobject, FlatSigningProvider &provider, const bool expand_priv)
Evaluate a descriptor given as a string, or as a {"desc":...,"range":...} object, with default range ...
Definition: util.cpp:1328
void(const RPCArg &) CheckFn
Definition: util.cpp:690
std::pair< int64_t, int64_t > ParseDescriptorRange(const UniValue &value)
Parse a JSON range specified as int64, or [int64, int64].
Definition: util.cpp:1312
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
Definition: util.cpp:186
std::string HelpExampleRpcNamed(const std::string &methodname, const RPCArgList &args)
Definition: util.cpp:210
CAmount AmountFromValue(const UniValue &value, int decimals)
Validate and return a CAmount from a UniValue number or string.
Definition: util.cpp:101
RPCErrorCode RPCErrorFromPSBTError(PSBTError err)
Definition: util.cpp:382
std::vector< unsigned char > ParseHexV(const UniValue &v, std::string_view name)
Definition: util.cpp:133
static UniValue BilingualStringsToUniValue(const std::vector< bilingual_str > &bilingual_strings)
Convert a vector of bilingual strings to a UniValue::VARR containing their original untranslated valu...
Definition: util.cpp:1372
void PushWarnings(const UniValue &warnings, UniValue &obj)
Push warning messages to an RPC "warnings" field as a JSON array of strings.
Definition: util.cpp:1382
UniValue JSONRPCTransactionError(TransactionError terr, const std::string &err_string)
Definition: util.cpp:411
#define TMPL_INST(check_param, ret_type, return_code)
Definition: util.cpp:712
std::vector< unsigned char > ParseHexO(const UniValue &o, std::string_view strKey)
Definition: util.cpp:142
uint256 GetTarget(const CBlockIndex &blockindex, const uint256 pow_limit)
Definition: util.cpp:1405
UniValue JSONRPCPSBTError(PSBTError err)
Definition: util.cpp:406
RPCErrorCode RPCErrorFromTransactionError(TransactionError terr)
Definition: util.cpp:394
CFeeRate ParseFeeRate(const UniValue &json)
Parse a json number or string, denoting BTC/kvB, into a CFeeRate (sat/kvB).
Definition: util.cpp:113
static std::optional< UniValue::VType > ExpectedType(RPCArg::Type type)
Definition: util.cpp:869
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
Definition: util.cpp:204
const std::string UNIX_EPOCH_TIME
String used to describe UNIX epoch time in documentation, factored out to a constant for consistency.
Definition: util.cpp:46
std::string GetAllOutputTypes()
Gets all existing output types formatted for RPC help sections.
Definition: util.cpp:49
int ParseVerbosity(const UniValue &arg, int default_verbosity, bool allow_bool)
Parses verbosity from provided UniValue.
Definition: util.cpp:86
CPubKey HexToPubKey(const std::string &hex_in)
Definition: util.cpp:222
std::optional< int > ParseSighashString(const UniValue &sighash)
Returns a sighash value corresponding to the passed in argument.
Definition: util.cpp:360
const std::string EXAMPLE_ADDRESS[2]
Example bech32 addresses for the RPCExamples help documentation.
Definition: util.cpp:47
CTxDestination AddAndGetMultisigDestination(const int required, const std::vector< CPubKey > &pubkeys, OutputType type, FlatSigningProvider &keystore, CScript &script_out)
Definition: util.cpp:238
static std::pair< int64_t, int64_t > ParseRange(const UniValue &value)
Definition: util.cpp:1298
uint256 ParseHashO(const UniValue &o, std::string_view strKey)
Definition: util.cpp:129
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:372
void RPCTypeCheckObj(const UniValue &o, const std::map< std::string, UniValueType > &typesExpected, bool fAllowNull, bool fStrict)
Definition: util.cpp:59
std::string HelpExampleCliNamed(const std::string &methodname, const RPCArgList &args)
Definition: util.cpp:191
uint256 ParseHashV(const UniValue &v, std::string_view name)
Utilities: convert hex-encoded Values (throws error if not hex).
Definition: util.cpp:120
static void CheckRequiredOrDefault(const RPCArg &param)
Definition: util.cpp:703
UniValue DescribeAddress(const CTxDestination &dest)
Definition: util.cpp:350
std::vector< RPCResult > ScriptPubKeyDoc()
Definition: util.cpp:1394
std::vector< std::pair< std::string, UniValue > > RPCArgList
Definition: util.h:132
static constexpr bool DEFAULT_RPC_DOC_CHECK
Definition: util.h:46
OuterType
Serializing JSON objects depends on the outer type.
Definition: util.h:163
static const unsigned int MAX_SCRIPT_ELEMENT_SIZE
Definition: script.h:28
static const int MAX_PUBKEYS_PER_MULTISIG
Definition: script.h:34
#define STR(x)
Definition: util.h:24
CScript GetScriptForMultisig(int nRequired, const std::vector< CPubKey > &keys)
Generate a multisig script.
Definition: solver.cpp:218
std::string GetTxnOutputType(TxoutType t)
Get the name of a TxoutType as a string.
Definition: solver.cpp:18
TxoutType
Definition: solver.h:22
@ WITNESS_UNKNOWN
Only for Witness versions not already defined above.
std::vector< Byte > ParseHex(std::string_view hex_str)
Like TryParseHex, but returns an empty vector on invalid input.
Definition: strencodings.h:68
Definition: util.h:186
Type
Definition: util.h:187
@ RANGE
Special type that is a NUM or [NUM,NUM].
@ OBJ_USER_KEYS
Special type where the user must set the keys e.g. to define multiple addresses; as opposed to e....
@ STR_HEX
Special type that is a STR with only hex chars.
@ AMOUNT
Special type representing a floating point amount (can be either NUM or STR)
@ OBJ_NAMED_PARAMS
Special type that behaves almost exactly like OBJ, defining an options object with a list of pre-defi...
const std::vector< RPCArg > m_inner
Only used for arrays or dicts.
Definition: util.h:227
const RPCArgOptions m_opts
Definition: util.h:230
const std::string m_names
The name of the arg (can be empty for inner args, can contain multiple aliases separated by | for nam...
Definition: util.h:225
const Fallback m_fallback
Definition: util.h:228
std::string ToString(bool oneline) const
Return the type string of the argument.
Definition: util.cpp:1253
UniValue MatchesType(const UniValue &request) const
Check whether the request JSON type matches.
Definition: util.cpp:903
const std::string m_description
Definition: util.h:229
bool IsOptional() const
Definition: util.cpp:927
std::string ToDescriptionString(bool is_named_arg) const
Return the description string, including the argument type and whether the argument is required.
Definition: util.cpp:936
const Type m_type
Definition: util.h:226
std::string GetName() const
Return the name, throws when there are aliases.
Definition: util.cpp:921
std::string GetFirstName() const
Return the first of all aliases.
Definition: util.cpp:916
std::string ToStringObj(bool oneline) const
Return the type string of the argument when it is in an object (dict).
Definition: util.cpp:1214
@ OMITTED
Optional argument for which the default value is omitted from help text for one of two reasons:
@ NO
Required arg.
std::vector< std::string > type_str
Should be empty unless it is supposed to override the auto-generated type strings....
Definition: util.h:172
std::string oneline_description
Should be empty unless it is supposed to override the auto-generated summary line.
Definition: util.h:171
bool skip_type_check
Definition: util.h:170
std::string ToDescriptionString() const
Definition: util.cpp:633
const std::string m_examples
Definition: util.h:409
const std::string m_description
Definition: util.h:318
void ToSections(Sections &sections, OuterType outer_type=OuterType::NONE, const int current_indent=0) const
Append the sections of the result.
Definition: util.cpp:1001
@ ELISION
Special type to denote elision (...)
@ NUM_TIME
Special numeric to denote unix epoch time.
@ ANY
Special type to disable type checks (for testing only)
@ ARR_FIXED
Special array that has a fixed number of entries.
@ OBJ_DYN
Special dictionary with keys that are not literals.
@ STR_HEX
Special string with only hex chars.
@ STR_AMOUNT
Special string to represent a floating point amount.
const std::vector< RPCResult > m_inner
Only used for arrays or dicts.
Definition: util.h:315
UniValue MatchesType(const UniValue &result) const
Check whether the result JSON type matches.
Definition: util.cpp:1135
void CheckInnerDoc() const
Definition: util.cpp:1202
const bool m_optional
Definition: util.h:316
const std::string m_key_name
Only used for dicts.
Definition: util.h:314
const Type m_type
Definition: util.h:313
const bool m_skip_type_check
Definition: util.h:317
std::string ToDescriptionString() const
Return the description string.
Definition: util.cpp:616
const std::vector< RPCResult > m_results
Definition: util.h:390
A pair of strings that can be aligned (through padding) with other Sections later on.
Definition: util.cpp:424
std::string m_left
Definition: util.cpp:427
Section(const std::string &left, const std::string &right)
Definition: util.cpp:425
const std::string m_right
Definition: util.cpp:428
Keeps track of RPCArgs by transforming them into sections for the purpose of serializing everything t...
Definition: util.cpp:435
void PushSection(const Section &s)
Definition: util.cpp:439
std::vector< Section > m_sections
Definition: util.cpp:436
void Push(const RPCArg &arg, const size_t current_indent=5, const OuterType outer_type=OuterType::NONE)
Recursive helper to translate an RPCArg into sections.
Definition: util.cpp:449
size_t m_max_pad
Definition: util.cpp:437
std::string ToString() const
Concatenate all sections with proper padding.
Definition: util.cpp:507
CTxDestination subtype to encode any future Witness version.
Definition: addresstype.h:96
#define NUM
Definition: tests.c:3588
#define strprintf
Format arguments and return the string or write to given std::ostream (see tinyformat::format doc for...
Definition: tinyformat.h:1172
const char * uvTypeName(UniValue::VType t)
Definition: univalue.cpp:218
bool ParseFixedPoint(std::string_view val, int decimals, int64_t *amount_out)
Parse number as fixed point according to JSON number syntax.
bool IsHex(std::string_view str)