6#include <bitcoin-build-config.h>
28 "You need to rescan the blockchain in order to correctly mark used "
29 "destinations in the past. Until this is done, some destinations may "
30 "be considered unused, even if the opposite is the case."},
36 "Returns an object containing various wallet state info.\n",
43 {
RPCResult::Type::NUM,
"walletversion",
"(DEPRECATED) only related to unsupported legacy wallet, returns the latest version 169900 for backwards compatibility"},
46 {
RPCResult::Type::NUM,
"keypoolsize",
"how many new keys are pre-generated (only counts external keys)"},
47 {
RPCResult::Type::NUM,
"keypoolsize_hd_internal",
true,
"how many new keys are pre-generated for internal use (used for change outputs, only appears if the wallet is using this feature, otherwise external keys are used)"},
48 {
RPCResult::Type::NUM_TIME,
"unlocked_until",
true,
"the " +
UNIX_EPOCH_TIME +
" until which the wallet is unlocked for transfers, or 0 if the wallet is locked (only present for passphrase-encrypted wallets)"},
50 {
RPCResult::Type::BOOL,
"private_keys_enabled",
"false if privatekeys are disabled for this wallet (enforced watch-only wallet)"},
51 {
RPCResult::Type::BOOL,
"avoid_reuse",
"whether this wallet tracks clean/dirty coins in terms of reuse"},
52 {
RPCResult::Type::OBJ,
"scanning",
"current scanning details, or false if no scan is in progress",
57 {
RPCResult::Type::BOOL,
"descriptors",
"whether this wallet uses descriptors for output script management"},
58 {
RPCResult::Type::BOOL,
"external_signer",
"whether this wallet is configured to use an external signer such as a hardware wallet"},
59 {
RPCResult::Type::BOOL,
"blank",
"Whether this wallet intentionally does not contain any keys, scripts, or descriptors"},
60 {
RPCResult::Type::NUM_TIME,
"birthtime",
true,
"The start time for blocks scanning. It could be modified by (re)importing any descriptor with an earlier timestamp."},
79 pwallet->BlockUntilSyncedToCurrentChain();
81 LOCK(pwallet->cs_wallet);
85 const int latest_legacy_wallet_minversion{169900};
87 size_t kpExternalSize = pwallet->KeypoolCountExternalKeys();
88 obj.
pushKV(
"walletname", pwallet->GetName());
89 obj.
pushKV(
"walletversion", latest_legacy_wallet_minversion);
90 obj.
pushKV(
"format", pwallet->GetDatabase().Format());
91 obj.
pushKV(
"txcount", (
int)pwallet->mapWallet.size());
92 obj.
pushKV(
"keypoolsize", (int64_t)kpExternalSize);
93 obj.
pushKV(
"keypoolsize_hd_internal", pwallet->GetKeyPoolSize() - kpExternalSize);
95 if (pwallet->IsCrypted()) {
96 obj.
pushKV(
"unlocked_until", pwallet->nRelockTime);
101 if (pwallet->IsScanning()) {
103 scanning.
pushKV(
"duration", Ticks<std::chrono::seconds>(pwallet->ScanningDuration()));
104 scanning.
pushKV(
"progress", pwallet->ScanningProgress());
105 obj.
pushKV(
"scanning", std::move(scanning));
107 obj.
pushKV(
"scanning",
false);
112 if (int64_t birthtime = pwallet->GetBirthTime(); birthtime !=
UNKNOWN_TIME) {
113 obj.
pushKV(
"birthtime", birthtime);
118 uint64_t wallet_flags = pwallet->GetWalletFlags();
119 for (uint64_t i = 0; i < 64; ++i) {
120 uint64_t flag = uint64_t{1} << i;
121 if (flag & wallet_flags) {
140 "Returns a list of wallets in the wallet directory.\n",
150 {
RPCResult::Type::ARR,
"warnings",
true,
"Warning messages, if any, related to loading the wallet.",
167 wallet.pushKV(
"name", path.utf8string());
169 if (db_type ==
"bdb") {
170 warnings.
push_back(
"This wallet is a legacy wallet and will need to be migrated with migratewallet before it can be loaded");
172 wallet.pushKV(
"warnings", warnings);
177 result.
pushKV(
"wallets", std::move(wallets));
186 "Returns a list of currently loaded wallets.\n"
187 "For full information on the wallet, use \"getwalletinfo\"\n",
218 "Loads a wallet from a wallet file or directory."
219 "\nNote that all wallet command-line options used when starting bitcoind will be"
220 "\napplied to the new wallet.\n",
222 {
"filename",
RPCArg::Type::STR,
RPCArg::Optional::NO,
"The path to the directory of the wallet to be loaded, either absolute or relative to the \"wallets\" directory. The \"wallets\" directory is set by the -walletdir option and defaults to the \"wallets\" folder within the data directory."},
229 {
RPCResult::Type::ARR,
"warnings",
true,
"Warning messages, if any, related to loading the wallet.",
236 "\nLoad wallet from the wallet dir:\n"
239 +
"\nLoad wallet using absolute path (Unix):\n"
242 +
"\nLoad wallet using absolute path (Windows):\n"
243 +
HelpExampleCli(
"loadwallet",
"\"DriveLetter:\\path\\to\\walletname\\\"")
244 +
HelpExampleRpc(
"loadwallet",
"\"DriveLetter:\\path\\to\\walletname\\\"")
249 const std::string
name(request.params[0].get_str());
256 std::vector<bilingual_str> warnings;
257 std::optional<bool> load_on_start = request.params[1].isNull() ? std::nullopt : std::optional<bool>(request.params[1].get_bool());
261 if (std::any_of(context.wallets.begin(), context.wallets.end(), [&
name](
const auto&
wallet) { return wallet->GetName() == name; })) {
266 std::shared_ptr<CWallet>
const wallet =
LoadWallet(context,
name, load_on_start, options, status, error, warnings);
284 flags += (
flags ==
"" ?
"" :
", ") + it.first;
288 "Change the state of the given wallet flag for a wallet.\n",
310 std::string flag_str = request.params[0].get_str();
311 bool value = request.params[1].isNull() || request.params[1].get_bool();
325 if (pwallet->IsWalletFlagSet(flag) == value) {
329 res.pushKV(
"flag_name", flag_str);
330 res.pushKV(
"flag_state", value);
333 pwallet->SetWalletFlag(flag);
335 pwallet->UnsetWalletFlag(flag);
351 "Creates and loads a new wallet.\n",
357 {
"avoid_reuse",
RPCArg::Type::BOOL,
RPCArg::Default{
false},
"Keep track of coin reuse, and treat dirty and clean coins differently with privacy considerations in mind."},
360 {
"external_signer",
RPCArg::Type::BOOL,
RPCArg::Default{
false},
"Use an external signer such as a hardware wallet. Requires -signer to be configured. Wallet creation will fail if keys cannot be fetched. Requires disable_private_keys and descriptors set to true."},
365 {
RPCResult::Type::STR,
"name",
"The wallet name if created successfully. If the wallet was created using a full path, the wallet_name will be the full path."},
366 {
RPCResult::Type::ARR,
"warnings",
true,
"Warning messages, if any, related to creating and loading the wallet.",
375 +
HelpExampleCliNamed(
"createwallet", {{
"wallet_name",
"descriptors"}, {
"avoid_reuse",
true}, {
"load_on_startup",
true}})
376 +
HelpExampleRpcNamed(
"createwallet", {{
"wallet_name",
"descriptors"}, {
"avoid_reuse",
true}, {
"load_on_startup",
true}})
382 if (!request.params[1].isNull() && request.params[1].get_bool()) {
386 if (!request.params[2].isNull() && request.params[2].get_bool()) {
390 passphrase.reserve(100);
391 std::vector<bilingual_str> warnings;
392 if (!request.params[3].isNull()) {
393 passphrase = std::string_view{request.params[3].get_str()};
394 if (passphrase.empty()) {
396 warnings.emplace_back(
Untranslated(
"Empty string given as passphrase, wallet will not be encrypted."));
400 if (!request.params[4].isNull() && request.params[4].get_bool()) {
404 if (!self.
Arg<
bool>(
"descriptors")) {
405 throw JSONRPCError(
RPC_WALLET_ERROR,
"descriptors argument must be set to \"true\"; it is no longer possible to create a legacy wallet.");
407 if (!request.params[7].isNull() && request.params[7].get_bool()) {
408#ifdef ENABLE_EXTERNAL_SIGNER
422 std::optional<bool> load_on_start = request.params[6].isNull() ? std::nullopt : std::optional<bool>(request.params[6].get_bool());
423 const std::shared_ptr<CWallet>
wallet =
CreateWallet(context, request.params[0].get_str(), load_on_start, options, status, error, warnings);
441 "Unloads the wallet referenced by the request endpoint or the wallet_name argument.\n"
442 "If both are specified, they must be identical.",
444 {
"wallet_name",
RPCArg::Type::STR,
RPCArg::DefaultHint{
"the wallet name from the RPC endpoint"},
"The name of the wallet to unload. If provided both here and in the RPC endpoint, the two must be identical."},
448 {
RPCResult::Type::ARR,
"warnings",
true,
"Warning messages, if any, related to unloading the wallet.",
467 std::vector<bilingual_str> warnings;
477 std::optional<bool> load_on_start{self.
MaybeArg<
bool>(
"load_on_startup")};
496 "simulaterawtransaction",
497 "Calculate the balance change resulting in the signing and broadcasting of the given transaction(s).\n",
528 const auto& txs = request.params[0].get_array();
530 std::map<COutPoint, CAmount> new_utxos;
531 std::set<COutPoint> spent;
533 for (
size_t i = 0; i < txs.size(); ++i) {
535 if (!
DecodeHexTx(mtx, txs[i].get_str(),
true,
true)) {
540 std::map<COutPoint, Coin> coins;
544 wallet.chain().findCoins(coins);
548 for (
const auto& txin : mtx.
vin) {
549 const auto& outpoint = txin.
prevout;
550 if (spent.count(outpoint)) {
553 if (new_utxos.count(outpoint)) {
554 changes -= new_utxos.at(outpoint);
555 new_utxos.erase(outpoint);
557 if (coins.at(outpoint).IsSpent()) {
560 changes -=
wallet.GetDebit(txin);
562 spent.insert(outpoint);
570 const auto& hash = mtx.
GetHash();
571 for (
size_t i = 0; i < mtx.
vout.size(); ++i) {
572 const auto& txout = mtx.
vout[i];
573 bool is_mine =
wallet.IsMine(txout);
574 changes += new_utxos[
COutPoint(hash, i)] = is_mine ? txout.nValue : 0;
590 "Migrate the wallet to a descriptor wallet.\n"
591 "A new wallet backup will need to be made.\n"
592 "\nThe migration process will create a backup of the wallet before migrating. This backup\n"
593 "file will be named <wallet name>-<timestamp>.legacy.bak and can be found in the directory\n"
594 "for this wallet. In the event of an incorrect migration, the backup can be restored using restorewallet."
595 "\nEncrypted wallets must have the passphrase provided as an argument to this call.\n"
596 "\nThis RPC may take a long time to complete. Increasing the RPC client timeout is recommended.",
598 {
"wallet_name",
RPCArg::Type::STR,
RPCArg::DefaultHint{
"the wallet name from the RPC endpoint"},
"The name of the wallet to migrate. If provided both here and in the RPC endpoint, the two must be identical."},
605 {
RPCResult::Type::STR,
"watchonly_name",
true,
"The name of the migrated wallet containing the watchonly scripts"},
606 {
RPCResult::Type::STR,
"solvables_name",
true,
"The name of the migrated wallet containing solvable but not watched scripts"},
619 wallet_pass.reserve(100);
620 if (!request.params[1].isNull()) {
621 wallet_pass = std::string_view{request.params[1].get_str()};
631 r.pushKV(
"wallet_name", res->wallet_name);
632 if (res->watchonly_wallet) {
633 r.pushKV(
"watchonly_name", res->watchonly_wallet->GetName());
635 if (res->solvables_wallet) {
636 r.pushKV(
"solvables_name", res->solvables_wallet->GetName());
638 r.pushKV(
"backup_path", res->backup_path.utf8string());
649 "List all BIP 32 HD keys in the wallet and which descriptors use them.\n",
666 {
RPCResult::Type::BOOL,
"active",
"Whether this descriptor is currently used to generate new addresses"},
684 const bool active_only{options.exists(
"active_only") ? options[
"active_only"].get_bool() :
false};
685 const bool priv{options.exists(
"private") ? options[
"private"].get_bool() :
false};
691 std::set<ScriptPubKeyMan*> spkms;
693 spkms =
wallet->GetActiveScriptPubKeyMans();
695 spkms =
wallet->GetAllScriptPubKeyMans();
698 std::map<CExtPubKey, std::set<std::tuple<std::string, bool, bool>>> wallet_xpubs;
699 std::map<CExtPubKey, CExtKey> wallet_xprvs;
700 for (
auto* spkm : spkms) {
703 LOCK(desc_spkm->cs_desc_man);
707 std::set<CPubKey> desc_pubkeys;
708 std::set<CExtPubKey> desc_xpubs;
709 w_desc.
descriptor->GetPubKeys(desc_pubkeys, desc_xpubs);
711 std::string desc_str;
712 bool ok = desc_spkm->GetDescriptorString(desc_str,
false);
714 wallet_xpubs[xpub].emplace(desc_str,
wallet->IsActiveScriptPubKeyMan(*spkm), desc_spkm->HasPrivKey(xpub.pubkey.GetID()));
715 if (std::optional<CKey> key = priv ? desc_spkm->GetKey(xpub.pubkey.GetID()) : std::nullopt) {
716 wallet_xprvs[xpub] =
CExtKey(xpub, *key);
722 for (
const auto& [xpub, descs] : wallet_xpubs) {
723 bool has_xprv =
false;
725 for (
const auto& [desc, active, has_priv] : descs) {
728 d.
pushKV(
"active", active);
729 has_xprv |= has_priv;
735 xpub_info.
pushKV(
"has_private", has_xprv);
739 xpub_info.
pushKV(
"descriptors", std::move(descriptors));
741 response.
push_back(std::move(xpub_info));
752 "Creates the wallet's descriptor for the given address type. "
753 "The address type must be one that the wallet does not already have a descriptor for."
758 {
"internal",
RPCArg::Type::BOOL,
RPCArg::DefaultHint{
"Both external and internal will be generated unless this parameter is specified"},
"Whether to only make one descriptor that is internal (if parameter is true) or external (if parameter is false)"},
759 {
"hdkey",
RPCArg::Type::STR,
RPCArg::DefaultHint{
"The HD key used by all other active descriptors"},
"The HD key that the wallet knows the private key of, listed using 'gethdkeys', to use for this descriptor's key"},
779 std::optional<OutputType> output_type =
ParseOutputType(request.params[0].get_str());
785 UniValue internal_only{options[
"internal"]};
788 std::vector<bool> internals;
789 if (internal_only.isNull()) {
791 internals.push_back(
true);
793 internals.push_back(internal_only.get_bool());
796 LOCK(pwallet->cs_wallet);
800 if (hdkey.isNull()) {
801 std::set<CExtPubKey> active_xpubs = pwallet->GetActiveHDPubKeys();
802 if (active_xpubs.size() != 1) {
805 xpub = *active_xpubs.begin();
813 std::optional<CKey> key = pwallet->GetKey(xpub.
pubkey.
GetID());
817 CExtKey active_hdkey(xpub, *key);
819 std::vector<std::reference_wrapper<DescriptorScriptPubKeyMan>> spkms;
821 for (
bool internal : internals) {
824 if (!pwallet->GetScriptPubKeyMan(w_id)) {
825 spkms.emplace_back(pwallet->SetupDescriptorScriptPubKeyMan(batch, active_hdkey, *output_type, internal));
834 for (
const auto& spkm : spkms) {
835 std::string desc_str;
836 bool ok = spkm.get().GetDescriptorString(desc_str,
false);
838 descs.push_back(desc_str);
841 out.pushKV(
"descs", std::move(descs));
856#ifdef ENABLE_EXTERNAL_SIGNER
964#ifdef ENABLE_EXTERNAL_SIGNER
int64_t CAmount
Amount in satoshis (Can be negative)
#define CHECK_NONFATAL(condition)
Identity function.
An outpoint - a combination of a transaction hash and an index n into its vout.
CKeyID GetID() const
Get the KeyID of this public key (hash of its serialization)
An input of a transaction.
auto Arg(std::string_view key) const
Helper to get a required or default-valued request argument.
auto MaybeArg(std::string_view key) const
Helper to get an optional request argument.
void push_back(UniValue val)
void pushKV(std::string key, UniValue val)
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
Access to the wallet database.
Descriptor with some wallet metadata.
std::shared_ptr< Descriptor > descriptor
RAII object to check and reserve a wallet rescan.
bool reserve(bool with_passphrase=false)
UniValue ValueFromAmount(const CAmount amount)
bool DecodeHexTx(CMutableTransaction &tx, const std::string &hex_tx, bool try_no_witness=false, bool try_witness=true)
const std::string CURRENCY_UNIT
std::string EncodeExtKey(const CExtKey &key)
CExtPubKey DecodeExtPubKey(const std::string &str)
std::string EncodeExtPubKey(const CExtPubKey &key)
void ReadDatabaseArgs(const ArgsManager &args, DBOptions &options)
bilingual_str ErrorString(const Result< T > &result)
void ReadDatabaseArgs(const ArgsManager &args, DatabaseOptions &options)
std::shared_ptr< CWallet > LoadWallet(WalletContext &context, const std::string &name, std::optional< bool > load_on_start, const DatabaseOptions &options, DatabaseStatus &status, bilingual_str &error, std::vector< bilingual_str > &warnings)
static RPCHelpMan loadwallet()
std::shared_ptr< CWallet > GetWalletForJSONRPCRequest(const JSONRPCRequest &request)
Figures out what wallet, if any, to use for a JSONRPCRequest.
RPCHelpMan listreceivedbyaddress()
std::vector< std::shared_ptr< CWallet > > GetWallets(WalletContext &context)
RPCHelpMan keypoolrefill()
RPCHelpMan removeprunedfunds()
RPCHelpMan listlockunspent()
static const RPCResult RESULT_LAST_PROCESSED_BLOCK
RPCHelpMan walletprocesspsbt()
void HandleWalletError(const std::shared_ptr< CWallet > wallet, DatabaseStatus &status, bilingual_str &error)
void EnsureWalletIsUnlocked(const CWallet &wallet)
static RPCHelpMan getwalletinfo()
RPCHelpMan backupwallet()
static RPCHelpMan listwalletdir()
RPCHelpMan walletpassphrase()
const std::string HELP_REQUIRING_PASSPHRASE
util::Result< MigrationResult > MigrateLegacyToDescriptor(std::shared_ptr< CWallet > local_wallet, const SecureString &passphrase, WalletContext &context)
Requirement: The wallet provided to this function must be isolated, with no attachment to the node's ...
RPCHelpMan getreceivedbyaddress()
RPCHelpMan walletdisplayaddress()
RPCHelpMan importprunedfunds()
RPCHelpMan simulaterawtransaction()
static RPCHelpMan setwalletflag()
RPCHelpMan walletcreatefundedpsbt()
bool RemoveWallet(WalletContext &context, const std::shared_ptr< CWallet > &wallet, std::optional< bool > load_on_start)
WalletContext & EnsureWalletContext(const std::any &context)
RPCHelpMan listaddressgroupings()
RPCHelpMan walletpassphrasechange()
fs::path GetWalletDir()
Get the path of the wallet directory.
RPCHelpMan abandontransaction()
RPCHelpMan listdescriptors()
RPCHelpMan listtransactions()
RPCHelpMan signrawtransactionwithwallet()
std::string EnsureUniqueWalletName(const JSONRPCRequest &request, const std::string *wallet_name)
Ensures that a wallet name is specified across the endpoint and wallet_name.
static RPCHelpMan listwallets()
static constexpr int64_t UNKNOWN_TIME
Constant representing an unknown spkm creation time.
static RPCHelpMan unloadwallet()
RPCHelpMan listsinceblock()
RPCHelpMan restorewallet()
void AppendLastProcessedBlock(UniValue &entry, const CWallet &wallet)
RPCHelpMan getreceivedbylabel()
RPCHelpMan importdescriptors()
RPCHelpMan getrawchangeaddress()
static RPCHelpMan createwallet()
RPCHelpMan getaddressinfo()
static constexpr uint64_t KNOWN_WALLET_FLAGS
RPCHelpMan encryptwallet()
RPCHelpMan gettransaction()
RPCHelpMan getaddressesbylabel()
RPCHelpMan fundrawtransaction()
static const std::map< uint64_t, std::string > WALLET_FLAG_CAVEATS
std::shared_ptr< CWallet > CreateWallet(WalletContext &context, const std::string &name, std::optional< bool > load_on_start, DatabaseOptions &options, DatabaseStatus &status, bilingual_str &error, std::vector< bilingual_str > &warnings)
static RPCHelpMan migratewallet()
RPCHelpMan rescanblockchain()
@ WALLET_FLAG_EXTERNAL_SIGNER
Indicates that the wallet needs an external signer.
@ WALLET_FLAG_AVOID_REUSE
@ WALLET_FLAG_DESCRIPTORS
Indicate that this wallet supports DescriptorScriptPubKeyMan.
@ WALLET_FLAG_DISABLE_PRIVATE_KEYS
@ WALLET_FLAG_BLANK_WALLET
Flag set when a wallet contains no HD seed and no private keys, scripts, addresses,...
void WaitForDeleteWallet(std::shared_ptr< CWallet > &&wallet)
Explicitly delete the wallet.
static const std::map< std::string, WalletFlags > STRING_TO_WALLET_FLAG
static constexpr uint64_t MUTABLE_WALLET_FLAGS
RPCHelpMan getnewaddress()
RPCHelpMan listreceivedbylabel()
std::shared_ptr< CWallet > GetWallet(WalletContext &context, const std::string &name)
std::span< const CRPCCommand > GetWalletRPCCommands()
static const std::map< WalletFlags, std::string > WALLET_FLAG_TO_STRING
RPCHelpMan sendtoaddress()
std::vector< std::pair< fs::path, std::string > > ListDatabases(const fs::path &wallet_dir)
Recursively list database paths in directory.
static RPCHelpMan createwalletdescriptor()
WalletDescriptor GenerateWalletDescriptor(const CExtPubKey &master_key, const OutputType &addr_type, bool internal)
std::string FormatAllOutputTypes()
std::optional< OutputType > ParseOutputType(const std::string &type)
UniValue JSONRPCError(int code, const std::string &message)
RPCErrorCode
Bitcoin RPC error codes.
@ RPC_MISC_ERROR
General application defined errors.
@ RPC_WALLET_ENCRYPTION_FAILED
Failed to encrypt the wallet.
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
@ RPC_WALLET_ERROR
Wallet errors.
@ RPC_WALLET_ALREADY_LOADED
This same wallet is already loaded.
@ RPC_WALLET_NOT_FOUND
Invalid wallet specified.
@ RPC_DESERIALIZATION_ERROR
Error parsing or validating structure in raw format.
@ RPC_INVALID_ADDRESS_OR_KEY
Invalid address or key.
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
std::string HelpExampleRpcNamed(const std::string &methodname, const RPCArgList &args)
void PushWarnings(const UniValue &warnings, UniValue &obj)
Push warning messages to an RPC "warnings" field as a JSON array of strings.
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
const std::string UNIX_EPOCH_TIME
String used to describe UNIX epoch time in documentation, factored out to a constant for consistency.
std::string HelpExampleCliNamed(const std::string &methodname, const RPCArgList &args)
uint256 DescriptorID(const Descriptor &desc)
Unique identifier that may not change over time, unless explicitly marked as not backwards compatible...
std::basic_string< char, std::char_traits< char >, secure_allocator< char > > SecureString
A mutable version of CTransaction.
std::vector< CTxOut > vout
Txid GetHash() const
Compute the hash of this CMutableTransaction.
@ STR_HEX
Special type that is a STR with only hex chars.
@ OBJ_NAMED_PARAMS
Special type that behaves almost exactly like OBJ, defining an options object with a list of pre-defi...
std::string DefaultHint
Hint for default value.
@ OMITTED
Optional argument for which the default value is omitted from help text for one of two reasons:
@ NUM_TIME
Special numeric to denote unix epoch time.
@ STR_AMOUNT
Special string to represent a floating point amount.
SecureString create_passphrase
WalletContext struct containing references to state shared between CWallet instances,...
bilingual_str Untranslated(std::string original)
Mark a bilingual_str as untranslated.