|
Bitcoin Core
22.99.0
P2P Digital Currency
|
Go to the documentation of this file.
32 #ifdef HAVE_MALLOC_INFO
44 "\nReturn information about the given bitcoin address.\n",
59 {
RPCResult::Type::ARR,
"error_locations",
true,
"Indices of likely error locations in address, if known (e.g. Bech32 errors)",
71 std::string error_msg;
72 std::vector<int> error_locations;
78 ret.
pushKV(
"isvalid", isValid);
81 ret.
pushKV(
"address", currentAddress);
90 for (
int i : error_locations) error_indices.
push_back(i);
91 ret.
pushKV(
"error_locations", error_indices);
92 ret.
pushKV(
"error", error_msg);
103 "\nCreates a multi-signature address with n signature of m keys required.\n"
104 "It returns a json object with the address and redeemScript.\n",
119 {
RPCResult::Type::ARR,
"warnings",
true,
"Any warnings resulting from the creation of this multisig",
126 "\nCreate a multisig address from 2 public keys\n"
127 +
HelpExampleCli(
"createmultisig",
"2 \"[\\\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\\\",\\\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\\\"]\"") +
128 "\nAs a JSON-RPC call\n"
129 +
HelpExampleRpc(
"createmultisig",
"2, [\"03789ed0bb717d88f7d321a368d905e7430207ebbd82bd342cf11ae157a7ace5fd\",\"03dbc6764b8884a92e871274b87583e6d5c2a58819473e17e107ef3f6aa5a61626\"]")
133 int required = request.params[0].
get_int();
137 std::vector<CPubKey> pubkeys;
138 for (
unsigned int i = 0; i < keys.
size(); ++i) {
139 if (
IsHex(keys[i].get_str()) && (keys[i].
get_str().length() == 66 || keys[i].
get_str().length() == 130)) {
148 if (!request.params[2].isNull()) {
149 std::optional<OutputType> parsed =
ParseOutputType(request.params[2].get_str());
155 output_type = parsed.value();
169 result.
pushKV(
"descriptor", descriptor->ToString());
174 warnings.
push_back(
"Unable to make chosen address type, please ensure no uncompressed public keys are present.");
176 if (warnings.
size()) result.
pushKV(
"warnings", warnings);
185 const std::string EXAMPLE_DESCRIPTOR =
"wpkh([d34db33f/84h/0h/0h]0279be667ef9dcbbac55a06295Ce870b07029Bfcdb2dce28d959f2815b16f81798)";
188 {
"\nAnalyses a descriptor.\n"},
199 {
RPCResult::Type::BOOL,
"hasprivatekeys",
"Whether the input descriptor contained at least one private key"},
203 "Analyse a descriptor\n" +
204 HelpExampleCli(
"getdescriptorinfo",
"\"" + EXAMPLE_DESCRIPTOR +
"\"") +
205 HelpExampleRpc(
"getdescriptorinfo",
"\"" + EXAMPLE_DESCRIPTOR +
"\"")
213 auto desc =
Parse(request.params[0].get_str(), provider,
error);
219 result.
pushKV(
"descriptor", desc->ToString());
221 result.
pushKV(
"isrange", desc->IsRange());
222 result.
pushKV(
"issolvable", desc->IsSolvable());
223 result.
pushKV(
"hasprivatekeys", provider.
keys.size() > 0);
231 const std::string EXAMPLE_DESCRIPTOR =
"wpkh([d34db33f/84h/0h/0h]xpub6DJ2dNUysrn5Vt36jH2KLBT2i1auw1tTSSomg8PhqNiUtx8QX2SvC9nrHu81fT41fvDUnhMjEzQgXnQjKEu3oaqMSzhSrHMxyyoEAmUHQbY/0/*)#cjjspncu";
234 {
"\nDerives one or more addresses corresponding to an output descriptor.\n"
235 "Examples of output descriptors are:\n"
236 " pkh(<pubkey>) P2PKH outputs for the given pubkey\n"
237 " wpkh(<pubkey>) Native segwit P2PKH outputs for the given pubkey\n"
238 " sh(multi(<n>,<pubkey>,<pubkey>,...)) P2SH-multisig outputs for the given threshold and pubkeys\n"
239 " raw(<hex script>) Outputs whose scriptPubKey equals the specified hex scripts\n"
240 "\nIn the above, <pubkey> either refers to a fixed public key in hexadecimal notation, or to an xpub/xprv optionally followed by one\n"
241 "or more path elements separated by \"/\", where \"h\" represents a hardened child key.\n"
242 "For more information on output descriptors, see the documentation in the doc/descriptors.md file.\n"},
254 "First three native segwit receive addresses\n" +
255 HelpExampleCli(
"deriveaddresses",
"\"" + EXAMPLE_DESCRIPTOR +
"\" \"[0,2]\"") +
256 HelpExampleRpc(
"deriveaddresses",
"\"" + EXAMPLE_DESCRIPTOR +
"\", \"[0,2]\"")
260 RPCTypeCheck(request.params, {UniValue::VSTR, UniValueType()});
261 const std::string desc_str = request.params[0].get_str();
263 int64_t range_begin = 0;
264 int64_t range_end = 0;
266 if (request.params.size() >= 2 && !request.params[1].isNull()) {
272 auto desc =
Parse(desc_str, key_provider,
error,
true);
277 if (!desc->IsRange() && request.params.size() > 1) {
281 if (desc->IsRange() && request.params.size() == 1) {
287 for (
int i = range_begin; i <= range_end; ++i) {
289 std::vector<CScript> scripts;
290 if (!desc->Expand(i, key_provider, scripts, provider)) {
294 for (
const CScript &script : scripts) {
305 if (addresses.
empty()) {
317 "Verify a signed message.",
327 "\nUnlock the wallet for 30 seconds\n"
329 "\nCreate the signature\n"
330 +
HelpExampleCli(
"signmessage",
"\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\" \"my message\"") +
331 "\nVerify the signature\n"
332 +
HelpExampleCli(
"verifymessage",
"\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\" \"signature\" \"my message\"") +
333 "\nAs a JSON-RPC call\n"
334 +
HelpExampleRpc(
"verifymessage",
"\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\", \"signature\", \"my message\"")
340 std::string strAddress = request.params[0].get_str();
341 std::string strSign = request.params[1].get_str();
342 std::string strMessage = request.params[2].get_str();
366 "\nSign a message with the private key of an address\n",
375 "\nCreate the signature\n"
376 +
HelpExampleCli(
"signmessagewithprivkey",
"\"privkey\" \"my message\"") +
377 "\nVerify the signature\n"
378 +
HelpExampleCli(
"verifymessage",
"\"1D1ZrZNe3JUo7ZycKEYQQiQAWd9y54F4XX\" \"signature\" \"my message\"") +
379 "\nAs a JSON-RPC call\n"
380 +
HelpExampleRpc(
"signmessagewithprivkey",
"\"privkey\", \"my message\"")
384 std::string strPrivkey = request.params[0].
get_str();
385 std::string strMessage = request.params[1].get_str();
392 std::string signature;
406 "\nSet the local time to given timestamp (-regtest only)\n",
409 "Pass 0 to go back to using the system time."},
416 throw std::runtime_error(
"setmocktime is for regression testing (-regtest mode) only");
427 const int64_t time{request.params[0].get_int64()};
432 auto node_context = util::AnyPtr<NodeContext>(request.context);
434 for (
const auto& chain_client : node_context->chain_clients) {
435 chain_client->setMockTime(time);
444 #if defined(USE_SYSCALL_SANDBOX)
448 "invokedisallowedsyscall",
449 "\nInvoke a disallowed syscall to trigger a syscall sandbox violation. Used for testing purposes.\n",
456 throw std::runtime_error(
"invokedisallowedsyscall is used for testing only.");
458 TestDisallowedSandboxCall();
463 #endif // USE_SYSCALL_SANDBOX
468 "\nBump the scheduler into the future (-regtest only)\n",
477 throw std::runtime_error(
"mockscheduler is for regression testing (-regtest mode) only");
482 int64_t delta_seconds = request.params[0].get_int64();
483 if (delta_seconds <= 0 || delta_seconds > 3600) {
484 throw std::runtime_error(
"delta_time must be between 1 and 3600 seconds (1 hr)");
487 auto node_context = util::AnyPtr<NodeContext>(request.context);
491 node_context->scheduler->MockForward(std::chrono::seconds(delta_seconds));
511 #ifdef HAVE_MALLOC_INFO
512 static std::string RPCMallocInfo()
516 FILE *f = open_memstream(&ptr, &size);
521 std::string rv(ptr, size);
536 "Returns an object containing information about memory usage.\n",
539 " - \"stats\" returns general statistics about memory usage in the daemon.\n"
540 " - \"mallocinfo\" returns an XML string describing low-level heap state (only available if compiled with glibc 2.10+)."},
551 {
RPCResult::Type::NUM,
"locked",
"Amount of bytes that succeeded locking. If this number is smaller than total, locking pages failed at some point and key data could be swapped to disk."},
567 std::string mode = request.params[0].
isNull() ?
"stats" : request.params[0].get_str();
568 if (mode ==
"stats") {
572 }
else if (mode ==
"mallocinfo") {
573 #ifdef HAVE_MALLOC_INFO
574 return RPCMallocInfo();
587 for (
unsigned int i = 0; i < cats.
size(); ++i) {
588 std::string cat = cats[i].
get_str();
606 "Gets and sets the logging configuration.\n"
607 "When called without an argument, returns the list of categories with status that are currently being debug logged or not.\n"
608 "When called with arguments, adds or removes categories from debug logging and return the lists above.\n"
609 "The arguments are evaluated in order \"include\", \"exclude\".\n"
610 "If an item is both included and excluded, it will thus end up being excluded.\n"
612 "In addition, the following are available as category names with special meanings:\n"
613 " - \"all\", \"1\" : represent all logging categories.\n"
614 " - \"none\", \"0\" : even if other logging categories are specified, ignore all of them.\n"
639 if (request.params[0].isArray()) {
642 if (request.params[1].isArray()) {
646 uint32_t changed_log_categories = original_log_categories ^ updated_log_categories;
663 for (
const auto& logCatActive :
LogInstance().LogCategoriesList()) {
664 result.
pushKV(logCatActive.category, logCatActive.active);
675 "\nSimply echo back the input arguments. This command is for testing.\n"
676 "\nIt will return an internal bug report when arg9='trigger_internal_bug' is passed.\n"
677 "\nThe difference between echo and echojson is that echojson has argument conversion enabled in the client-side table in "
678 "bitcoin-cli and the GUI. There is no server-side difference.",
695 if (request.params[9].isStr()) {
696 CHECK_NONFATAL(request.params[9].get_str() !=
"trigger_internal_bug");
699 return request.params;
711 "\nEcho back the input argument, passing it through a spawned process in a multiprocess build.\n"
712 "This command is for testing.\n",
719 std::unique_ptr<interfaces::Echo>
echo;
729 auto init =
ipc->spawnProcess(
"bitcoin-node");
740 return echo->echo(request.params[0].get_str());
748 if (!index_name.empty() && index_name != summary.name)
return ret_summary;
751 entry.
pushKV(
"synced", summary.synced);
752 entry.
pushKV(
"best_block_height", summary.best_block_height);
753 ret_summary.
pushKV(summary.name, entry);
760 "\nReturns the status of one or all available indices currently running in the node.\n",
784 const std::string index_name = request.params[0].isNull() ?
"" : request.params[0].get_str();
822 {
"hidden", &
echo, },
825 #if defined(USE_SYSCALL_SANDBOX)
826 {
"hidden", &invokedisallowedsyscall, },
827 #endif // USE_SYSCALL_SANDBOX
830 for (
const auto& c : commands) {
831 t.appendCommand(c.name, &c);
@ RPC_MISC_ERROR
General application defined errors.
bool MessageSign(const CKey &privkey, const std::string &message, std::string &signature)
Sign a message.
std::unique_ptr< Descriptor > Parse(const std::string &descriptor, FlatSigningProvider &out, std::string &error, bool require_checksum)
Parse a descriptor string.
bool IsMockableChain() const
If this chain allows time to be mocked.
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
@ ERR_MALFORMED_SIGNATURE
The provided signature couldn't be parsed (maybe invalid base64).
static RPCHelpMan getdescriptorinfo()
static RPCHelpMan echo(const std::string &name)
std::unique_ptr< TxIndex > g_txindex
The global transaction index, used in GetTransaction. May be null.
#define CHECK_NONFATAL(condition)
Throw a NonFatalCheckError when the condition evaluates to false.
static RPCHelpMan createmultisig()
virtual std::unique_ptr< Echo > makeEcho()
static RPCHelpMan signmessagewithprivkey()
Fillable signing provider that keeps keys in an address->secret map.
const UniValue NullUniValue
CScript GetScriptForDestination(const CTxDestination &dest)
Generate a Bitcoin scriptPubKey for the given CTxDestination.
bool IsTestChain() const
If this chain is exclusively used for testing.
IndexSummary GetSummary() const
Get a summary of the index and its state.
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
bool IsHex(const std::string &str)
static RPCHelpMan deriveaddresses()
NodeContext struct containing references to chain state and connection state.
Initial interface created when a process is first started, and used to give and get access to other i...
std::map< CKeyID, CKey > keys
BlockFilterIndex is used to store and retrieve block filters, hashes, and headers for a range of bloc...
MessageVerificationResult MessageVerify(const std::string &address, const std::string &signature, const std::string &message)
Verify a signed message.
@ ERR_NOT_SIGNED
The message was not signed with the private key of the provided address.
uint32_t GetCategoryMask() const
static LockedPoolManager & Instance()
Return the current instance, or create it once.
CPubKey HexToPubKey(const std::string &hex_in)
static UniValue SummaryToJSON(const IndexSummary &&summary, std::string index_name)
bool pushKV(const std::string &key, const UniValue &val)
static RPCHelpMan validateaddress()
std::unique_ptr< CoinStatsIndex > g_coin_stats_index
The global UTXO set hash object.
std::string GetDescriptorChecksum(const std::string &descriptor)
Get the checksum for a descriptor.
NodeContext & EnsureAnyNodeContext(const std::any &context)
const std::string & get_str() const
bool pushKVs(const UniValue &obj)
std::variant< CNoDestination, PKHash, ScriptHash, WitnessV0ScriptHash, WitnessV0KeyHash, WitnessV1Taproot, WitnessUnknown > CTxDestination
A txout script template with a specific destination.
static RPCHelpMan echoipc()
bool IsValidDestination(const CTxDestination &dest)
Check whether a CTxDestination is a CNoDestination.
@ OMITTED_NAMED_ARG
Optional arg that is a named argument and has a default value of null.
@ STR_HEX
Special type that is a STR with only hex chars.
std::optional< OutputType > OutputTypeFromDestination(const CTxDestination &dest)
Get the OutputType for a CTxDestination.
bool UpdateHTTPServerLogging(bool enable)
Change logging level for libevent.
void SetMockTime(int64_t nMockTimeIn)
DEPRECATED Use SetMockTime with chrono type.
std::string LogCategoriesString() const
Returns a string with the log categories in alphabetical order.
static UniValue RPCLockedMemoryInfo()
@ STR_HEX
Special string with only hex chars.
CTxDestination AddAndGetMultisigDestination(const int required, const std::vector< CPubKey > &pubkeys, OutputType type, FillableSigningProvider &keystore, CScript &script_out)
bool IsValid() const
Check whether this private key is valid.
UniValue DescribeAddress(const CTxDestination &dest)
@ ERR_INVALID_ADDRESS
The provided address is invalid.
static RPCHelpMan setmocktime()
void EnableCategory(LogFlags flag)
static RPCHelpMan getindexinfo()
static RPCHelpMan echojson()
CKey DecodeSecret(const std::string &str)
static RPCHelpMan logging()
interfaces::Init * init
Init interface for initializing current process and connecting to other processes.
@ ERR_PUBKEY_NOT_RECOVERED
A public key could not be recovered from the provided signature and message.
@ ANY
Special type to disable type checks (for testing only)
static void EnableOrDisableLogCategories(UniValue cats, bool enable)
Serialized script, used inside transaction inputs and outputs.
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
bool ExtractDestination(const CScript &scriptPubKey, CTxDestination &addressRet)
Parse a standard scriptPubKey for the destination address.
@ RANGE
Special type that is a NUM or [NUM,NUM].
@ ERR_ADDRESS_NO_KEY
The provided address is valid but does not refer to a public key.
@ RPC_INVALID_ADDRESS_OR_KEY
Invalid address or key.
std::pair< int64_t, int64_t > ParseDescriptorRange(const UniValue &value)
Parse a JSON range specified as int64, or [int64, int64].
void RegisterMiscRPCCommands(CRPCTable &t)
Register miscellaneous RPC commands.
static RPCHelpMan verifymessage()
static RPCHelpMan getmemoryinfo()
An encapsulated private key.
void RPCTypeCheck(const UniValue ¶ms, const std::list< UniValueType > &typesExpected, bool fAllowNull)
Type-check arguments; throws JSONRPCError if wrong type given.
UniValue JSONRPCError(int code, const std::string &message)
void ForEachBlockFilterIndex(std::function< void(BlockFilterIndex &)> fn)
Iterate over all running block filter indexes, invoking fn on each.
@ OMITTED
Optional argument with default value omitted because they are implicitly clear.
CTxDestination DecodeDestination(const std::string &str, std::string &error_msg, std::vector< int > *error_locations)
bool push_back(const UniValue &val)
BCLog::Logger & LogInstance()
const CChainParams & Params()
Return the currently selected parameters.
@ OK
The message verification was successful.
const std::string EXAMPLE_ADDRESS[2]
Example bech32 addresses for the RPCExamples help documentation.
@ OBJ_DYN
Special dictionary with keys that are not literals.
@ RPC_TYPE_ERROR
Unexpected type was passed as parameter.
bool error(const char *fmt, const Args &... args)
void DisableCategory(LogFlags flag)
const UniValue & get_array() const
std::unique_ptr< Descriptor > InferDescriptor(const CScript &script, const SigningProvider &provider)
Find a descriptor for the specified script, using information from provider where possible.
RecursiveMutex cs_main
Mutex to guard access to validation specific variables, such as reading or changing the chainstate.
std::string HexStr(const Span< const uint8_t > s)
Convert a span of bytes to a lower-case hexadecimal string.
Stats stats() const
Get pool usage statistics.
static RPCHelpMan mockscheduler()
std::optional< OutputType > ParseOutputType(const std::string &type)
std::string EncodeDestination(const CTxDestination &dest)
const std::string UNIX_EPOCH_TIME
String used to describe UNIX epoch time in documentation, factored out to a constant for consistency.
Interface providing access to interprocess-communication (IPC) functionality.