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