 |
Bitcoin Core
22.99.0
P2P Digital Currency
|
Go to the documentation of this file.
20 "\nReturns a new Bitcoin address for receiving payments.\n"
21 "If 'label' is specified, it is added to the address book \n"
22 "so payments received with the address will be associated with 'label'.\n",
24 {
"label",
RPCArg::Type::STR,
RPCArg::Default{
""},
"The label name for the address to be linked to. It can also be set to the empty string \"\" to represent the default label. The label does not need to exist, it will be created if there is no label by the given name."},
25 {
"address_type",
RPCArg::Type::STR,
RPCArg::DefaultHint{
"set by -addresstype"},
"The address type to use. Options are \"legacy\", \"p2sh-segwit\", \"bech32\", and \"bech32m\"."},
39 LOCK(pwallet->cs_wallet);
41 if (!pwallet->CanGetAddresses()) {
47 if (!request.params[0].isNull())
50 OutputType output_type = pwallet->m_default_address_type;
51 if (!request.params[1].isNull()) {
52 std::optional<OutputType> parsed =
ParseOutputType(request.params[1].get_str());
58 output_type = parsed.value();
63 if (!pwallet->GetNewDestination(output_type, label, dest,
error)) {
75 "\nReturns a new Bitcoin address, for receiving change.\n"
76 "This is for use with raw transactions, NOT normal use.\n",
78 {
"address_type",
RPCArg::Type::STR,
RPCArg::DefaultHint{
"set by -changetype"},
"The address type to use. Options are \"legacy\", \"p2sh-segwit\", \"bech32\", and \"bech32m\"."},
92 LOCK(pwallet->cs_wallet);
94 if (!pwallet->CanGetAddresses(
true)) {
98 OutputType output_type = pwallet->m_default_change_type.value_or(pwallet->m_default_address_type);
99 if (!request.params[0].isNull()) {
100 std::optional<OutputType> parsed =
ParseOutputType(request.params[0].get_str());
106 output_type = parsed.value();
111 if (!pwallet->GetNewChangeDestination(output_type, dest,
error)) {
123 "\nSets the label associated with the given address.\n",
138 LOCK(pwallet->cs_wallet);
147 if (pwallet->IsMine(dest)) {
148 pwallet->SetAddressBook(dest, label,
"receive");
150 pwallet->SetAddressBook(dest, label,
"send");
161 "\nLists groups of addresses which have had their common ownership\n"
162 "made public by common use as inputs or as the resulting change\n"
163 "in past transactions\n",
190 pwallet->BlockUntilSyncedToCurrentChain();
192 LOCK(pwallet->cs_wallet);
204 const auto* address_book_entry = pwallet->FindAddressBookEntry(address);
205 if (address_book_entry) {
206 addressInfo.
push_back(address_book_entry->GetLabel());
213 return jsonGroupings;
221 "\nAdd an nrequired-to-sign multisignature address to the wallet. Requires a new wallet backup.\n"
222 "Each key is a Bitcoin address or hex-encoded public key.\n"
223 "This functionality is only intended for use with non-watchonly addresses.\n"
224 "See `importaddress` for watchonly p2sh address support.\n"
225 "If 'label' is specified, assign address to that label.\n",
242 {
RPCResult::Type::ARR,
"warnings",
true,
"Any warnings resulting from the creation of this multisig",
249 "\nAdd a multisig address from 2 addresses\n"
251 "\nAs a JSON-RPC call\n"
264 if (!request.params[2].isNull())
267 int required = request.params[0].get_int();
271 std::vector<CPubKey> pubkeys;
272 for (
unsigned int i = 0; i < keys_or_addrs.
size(); ++i) {
273 if (
IsHex(keys_or_addrs[i].get_str()) && (keys_or_addrs[i].get_str().length() == 66 || keys_or_addrs[i].get_str().length() == 130)) {
276 pubkeys.push_back(
AddrToPubKey(spk_man, keys_or_addrs[i].get_str()));
280 OutputType output_type = pwallet->m_default_address_type;
281 if (!request.params[3].isNull()) {
282 std::optional<OutputType> parsed =
ParseOutputType(request.params[3].get_str());
288 output_type = parsed.value();
294 pwallet->SetAddressBook(dest, label,
"send");
302 result.
pushKV(
"descriptor", descriptor->ToString());
307 warnings.
push_back(
"Unable to make chosen address type, please ensure no uncompressed public keys are present.");
309 if (warnings.
size()) result.
pushKV(
"warnings", warnings);
319 "\nFills the keypool."+
338 LOCK(pwallet->cs_wallet);
341 unsigned int kpSize = 0;
342 if (!request.params[0].isNull()) {
343 if (request.params[0].get_int() < 0)
345 kpSize = (
unsigned int)request.params[0].get_int();
349 pwallet->TopUpKeyPool(kpSize);
351 if (pwallet->GetKeyPoolSize() < kpSize) {
363 "\nEntirely clears and refills the keypool.\n"
364 "WARNING: On non-HD wallets, this will require a new backup immediately, to include the new keys.\n"
365 "When restoring a backup of an HD wallet created before the newkeypool command is run, funds received to\n"
366 "new addresses may not appear automatically. They have not been lost, but the wallet may not find them.\n"
367 "This can be fixed by running the newkeypool command on the backup and then rescanning, so the wallet\n"
368 "re-generates the required keys." +
381 LOCK(pwallet->cs_wallet);
400 std::vector<std::vector<unsigned char>> solutions_data;
411 UniValue wallet_detail = std::visit(*
this, embedded);
416 if (subobj.
exists(
"pubkey")) obj.
pushKV(
"pubkey", subobj[
"pubkey"]);
417 obj.
pushKV(
"embedded", std::move(subobj));
420 obj.
pushKV(
"sigsrequired", solutions_data[0][0]);
422 for (
size_t i = 1; i < solutions_data.size() - 1; ++i) {
423 CPubKey key(solutions_data[i].begin(), solutions_data[i].end());
426 obj.
pushKV(
"pubkeys", std::move(pubkeys));
489 std::unique_ptr<SigningProvider> provider =
nullptr;
490 provider =
wallet.GetSolvingProvider(script);
499 "\nReturn information about the given bitcoin address.\n"
500 "Some of the information will only be present if the address is in the active wallet.\n",
511 {
RPCResult::Type::BOOL,
"solvable",
"If we know how to spend coins sent to this address, ignoring the possible lack of private keys."},
512 {
RPCResult::Type::STR,
"desc",
true,
"A descriptor for spending coins sent to this address (only when solvable)."},
513 {
RPCResult::Type::STR,
"parent_desc",
true,
"The descriptor used to derive this address if this is a descriptor wallet"},
519 {
RPCResult::Type::STR,
"script",
true,
"The output script type. Only if isscript is true and the redeemscript is known. Possible\n"
520 "types: nonstandard, pubkey, pubkeyhash, scripthash, multisig, nulldata, witness_v0_keyhash,\n"
521 "witness_v0_scripthash, witness_unknown."},
523 {
RPCResult::Type::ARR,
"pubkeys",
true,
"Array of pubkeys associated with the known redeemscript (only if script is multisig).",
527 {
RPCResult::Type::NUM,
"sigsrequired",
true,
"The number of signatures required to spend multisig output (only if script is multisig)."},
528 {
RPCResult::Type::STR_HEX,
"pubkey",
true,
"The hex value of the raw public key for single-key addresses (possibly embedded in P2SH or P2WSH)."},
529 {
RPCResult::Type::OBJ,
"embedded",
true,
"Information about the address embedded in P2SH or P2WSH, if relevant and known.",
531 {
RPCResult::Type::ELISION,
"",
"Includes all getaddressinfo output fields for the embedded address, excluding metadata (timestamp, hdkeypath, hdseedid)\n"
532 "and relation to the wallet (ismine, iswatchonly)."},
539 {
RPCResult::Type::ARR,
"labels",
"Array of labels associated with the address. Currently limited to one label but returned\n"
540 "as an array to keep the API stable if multiple labels are enabled in the future.",
555 LOCK(pwallet->cs_wallet);
557 std::string error_msg;
563 if (error_msg.empty()) error_msg =
"Invalid address";
571 ret.
pushKV(
"address", currentAddress);
576 std::unique_ptr<SigningProvider> provider = pwallet->GetSolvingProvider(scriptPubKey);
583 bool solvable = inferred->IsSolvable() ||
IsSolvable(*provider, scriptPubKey);
584 ret.
pushKV(
"solvable", solvable);
586 ret.
pushKV(
"desc", inferred->ToString());
589 ret.
pushKV(
"solvable",
false);
592 const auto& spk_mans = pwallet->GetScriptPubKeyMans(scriptPubKey);
595 if (spk_mans.size()) spk_man = *spk_mans.begin();
599 std::string desc_str;
601 ret.
pushKV(
"parent_desc", desc_str);
613 if (
const std::unique_ptr<CKeyMetadata> meta = spk_man->GetMetadata(dest)) {
614 ret.
pushKV(
"timestamp", meta->nCreateTime);
615 if (meta->has_key_origin) {
617 ret.
pushKV(
"hdseedid", meta->hd_seed_id.GetHex());
618 ret.
pushKV(
"hdmasterfingerprint",
HexStr(meta->key_origin.fingerprint));
629 const auto* address_book_entry = pwallet->FindAddressBookEntry(dest);
630 if (address_book_entry) {
631 labels.
push_back(address_book_entry->GetLabel());
633 ret.
pushKV(
"labels", std::move(labels));
654 "\nReturns the list of addresses assigned the specified label.\n",
663 {
RPCResult::Type::STR,
"purpose",
"Purpose of address (\"send\" for sending address, \"receive\" for receiving address)"},
676 LOCK(pwallet->cs_wallet);
682 std::set<std::string> addresses;
683 for (
const std::pair<const CTxDestination, CAddressBookData>& item : pwallet->m_address_book) {
684 if (item.second.IsChange())
continue;
685 if (item.second.GetLabel() == label) {
690 bool unique = addresses.emplace(address).second;
712 "\nReturns the list of all labels, or labels that are assigned to addresses with a specific purpose.\n",
723 "\nList all labels\n"
725 "\nList labels that have receiving addresses\n"
727 "\nList labels that have sending addresses\n"
729 "\nAs a JSON-RPC call\n"
737 LOCK(pwallet->cs_wallet);
740 if (!request.params[0].isNull()) {
741 purpose = request.params[0].get_str();
745 std::set<std::string> label_set;
746 for (
const std::pair<const CTxDestination, CAddressBookData>& entry : pwallet->m_address_book) {
747 if (entry.second.IsChange())
continue;
748 if (purpose.empty() || entry.second.purpose == purpose) {
749 label_set.insert(entry.second.GetLabel());
754 for (
const std::string&
name : label_set) {
764 #ifdef ENABLE_EXTERNAL_SIGNER
768 "walletdisplayaddress",
769 "Display address on an external signer for verification.",
800 result.
pushKV(
"address", request.params[0].get_str());
805 #endif // ENABLE_EXTERNAL_SIGNER
std::string WriteHDKeypath(const std::vector< uint32_t > &keypath)
Write HD keypaths as strings.
@ RPC_MISC_ERROR
General application defined errors.
@ ELISION
Special type to denote elision (...)
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
isminetype
IsMine() return codes, which depend on ScriptPubKeyMan implementation.
CTxDestination subtype to encode any future Witness version.
TxoutType Solver(const CScript &scriptPubKey, std::vector< std::vector< unsigned char >> &vSolutionsRet)
Parse a scriptPubKey and identify script type for standard scripts.
RPCHelpMan keypoolrefill()
A hasher class for RIPEMD-160.
#define CHECK_NONFATAL(condition)
Throw a NonFatalCheckError when the condition evaluates to false.
bool ScriptIsChange(const CWallet &wallet, const CScript &script)
bool GetDescriptorString(std::string &out, const bool priv) const
RPCHelpMan getaddressesbylabel()
void Finalize(unsigned char hash[OUTPUT_SIZE])
const UniValue NullUniValue
CScript GetScriptForDestination(const CTxDestination &dest)
Generate a Bitcoin scriptPubKey for the given CTxDestination.
std::set< std::set< CTxDestination > > GetAddressGroupings(const CWallet &wallet)
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
bool IsHex(const std::string &str)
RPCHelpMan walletdisplayaddress()
An interface to be implemented by keystores that support signing.
std::shared_ptr< CWallet > GetWalletForJSONRPCRequest(const JSONRPCRequest &request)
Figures out what wallet, if any, to use for a JSONRPCRequest.
UniValue operator()(const WitnessV0KeyHash &id) const
@ RPC_WALLET_KEYPOOL_RAN_OUT
Keypool ran out, call keypoolrefill first.
CPubKey HexToPubKey(const std::string &hex_in)
A reference to a CKey: the Hash160 of its serialized public key.
virtual bool GetPubKey(const CKeyID &address, CPubKey &pubkey) const
bool pushKV(const std::string &key, const UniValue &val)
UniValue ValueFromAmount(const CAmount amount)
UniValue operator()(const WitnessV1Taproot &id) const
bool DisplayAddress(const CTxDestination &dest) EXCLUSIVE_LOCKS_REQUIRED(cs_wallet)
Display address on an external signer.
bool NewKeyPool()
Mark old keypool keys as used, and generate all new keys.
@ ARR_FIXED
Special array that has a fixed number of entries.
const std::string HELP_REQUIRING_PASSPHRASE
UniValue operator()(const WitnessV0ScriptHash &id) const
DescribeWalletAddressVisitor(const SigningProvider *_provider)
std::map< CTxDestination, CAmount > GetAddressBalances(const CWallet &wallet)
const std::string CURRENCY_UNIT
UniValue operator()(const WitnessUnknown &id) const
bool pushKVs(const UniValue &obj)
std::variant< CNoDestination, PKHash, ScriptHash, WitnessV0ScriptHash, WitnessV0KeyHash, WitnessV1Taproot, WitnessUnknown > CTxDestination
A txout script template with a specific destination.
RPCHelpMan listaddressgroupings()
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.
std::optional< OutputType > OutputTypeFromDestination(const CTxDestination &dest)
Get the OutputType for a CTxDestination.
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
@ RPC_WALLET_INVALID_LABEL_NAME
Invalid label name.
bool exists(const std::string &key) const
@ WALLET_FLAG_DISABLE_PRIVATE_KEYS
static const unsigned int DEFAULT_KEYPOOL_SIZE
Default for -keypool.
CRIPEMD160 & Write(const unsigned char *data, size_t len)
@ 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)
UniValue DescribeAddress(const CTxDestination &dest)
RPCHelpMan getaddressinfo()
void __pushKV(const std::string &key, const UniValue &val)
@ RPC_WALLET_ERROR
Wallet errors.
@ NUM_TIME
Special numeric to denote unix epoch time.
virtual bool GetCScript(const CScriptID &scriptid, CScript &script) const
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.
RecursiveMutex cs_wallet
Main wallet lock.
@ RPC_INVALID_ADDRESS_OR_KEY
Invalid address or key.
RPCHelpMan getnewaddress()
bool IsCompressed() const
Check whether this is a compressed public key.
CKeyID ToKeyID(const PKHash &key_hash)
std::string GetTxnOutputType(TxoutType t)
Get the name of a TxoutType as a string.
An encapsulated public key.
UniValue operator()(const ScriptHash &scripthash) const
UniValue operator()(const PKHash &pkhash) const
bool IsSolvable(const SigningProvider &provider, const CScript &script)
UniValue operator()(const CNoDestination &dest) const
UniValue JSONRPCError(int code, const std::string &message)
@ 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)
void ProcessSubScript(const CScript &subscript, UniValue &obj) const
bool push_back(const UniValue &val)
RPCHelpMan getrawchangeaddress()
static UniValue AddressBookDataToJSON(const CAddressBookData &data, const bool verbose)
Convert CAddressBookData to JSON record.
static UniValue DescribeWalletAddress(const CWallet &wallet, const CTxDestination &dest)
const std::string EXAMPLE_ADDRESS[2]
Example bech32 addresses for the RPCExamples help documentation.
const SigningProvider *const provider
RPCHelpMan addmultisigaddress()
@ OBJ_DYN
Special dictionary with keys that are not literals.
RecursiveMutex cs_KeyStore
bool error(const char *fmt, const Args &... args)
@ STR_AMOUNT
Special string to represent a floating point amount.
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.
LegacyScriptPubKeyMan & EnsureLegacyScriptPubKeyMan(CWallet &wallet, bool also_create)
A reference to a CScript: the Hash160 of its serialization (see script.h)
std::string HexStr(const Span< const uint8_t > s)
Convert a span of bytes to a lower-case hexadecimal string.
CPubKey AddrToPubKey(const FillableSigningProvider &keystore, const std::string &addr_in)
const std::string & GetLabel() const
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.
void EnsureWalletIsUnlocked(const CWallet &wallet)
std::string LabelFromValue(const UniValue &value)