27 "You need to rescan the blockchain in order to correctly mark used "
28 "destinations in the past. Until this is done, some destinations may "
29 "be considered unused, even if the opposite is the case."},
43 "Returns an object containing various wallet state info.\n",
57 {
RPCResult::Type::NUM,
"keypoolsize",
"how many new keys are pre-generated (only counts external keys)"},
58 {
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)"},
59 {
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)"},
62 {
RPCResult::Type::BOOL,
"private_keys_enabled",
"false if privatekeys are disabled for this wallet (enforced watch-only wallet)"},
63 {
RPCResult::Type::BOOL,
"avoid_reuse",
"whether this wallet tracks clean/dirty coins in terms of reuse"},
64 {
RPCResult::Type::OBJ,
"scanning",
"current scanning details, or false if no scan is in progress",
69 {
RPCResult::Type::BOOL,
"descriptors",
"whether this wallet uses descriptors for scriptPubKey management"},
70 {
RPCResult::Type::BOOL,
"external_signer",
"whether this wallet is configured to use an external signer such as a hardware wallet"},
71 {
RPCResult::Type::BOOL,
"blank",
"Whether this wallet intentionally does not contain any keys, scripts, or descriptors"},
86 pwallet->BlockUntilSyncedToCurrentChain();
88 LOCK(pwallet->cs_wallet);
92 size_t kpExternalSize = pwallet->KeypoolCountExternalKeys();
94 obj.
pushKV(
"walletname", pwallet->GetName());
95 obj.
pushKV(
"walletversion", pwallet->GetVersion());
96 obj.
pushKV(
"format", pwallet->GetDatabase().Format());
100 obj.
pushKV(
"txcount", (
int)pwallet->mapWallet.size());
101 const auto kp_oldest = pwallet->GetOldestKeyPoolTime();
102 if (kp_oldest.has_value()) {
103 obj.
pushKV(
"keypoololdest", kp_oldest.value());
105 obj.
pushKV(
"keypoolsize", (int64_t)kpExternalSize);
116 obj.
pushKV(
"keypoolsize_hd_internal", (int64_t)(pwallet->GetKeyPoolSize() - kpExternalSize));
118 if (pwallet->IsCrypted()) {
119 obj.
pushKV(
"unlocked_until", pwallet->nRelockTime);
124 if (pwallet->IsScanning()) {
126 scanning.
pushKV(
"duration", Ticks<std::chrono::seconds>(pwallet->ScanningDuration()));
127 scanning.
pushKV(
"progress", pwallet->ScanningProgress());
128 obj.
pushKV(
"scanning", scanning);
130 obj.
pushKV(
"scanning",
false);
145 "Returns a list of wallets in the wallet directory.\n",
168 wallet.pushKV(
"name", path.u8string());
173 result.
pushKV(
"wallets", wallets);
182 "Returns a list of currently loaded wallets.\n"
183 "For full information on the wallet, use \"getwalletinfo\"\n",
213 "\nLoads a wallet from a wallet file or directory."
214 "\nNote that all wallet command-line options used when starting bitcoind will be"
215 "\napplied to the new wallet.\n",
224 {
RPCResult::Type::ARR,
"warnings",
true,
"Warning messages, if any, related to loading the wallet.",
237 const std::string
name(request.params[0].get_str());
244 std::vector<bilingual_str> warnings;
245 std::optional<bool> load_on_start = request.params[1].isNull() ? std::nullopt : std::optional<bool>(request.params[1].get_bool());
249 if (std::any_of(
context.wallets.begin(),
context.wallets.end(), [&
name](
const auto&
wallet) { return wallet->GetName() == name; })) {
272 flags += (
flags ==
"" ?
"" :
", ") + it.first;
275 "\nChange the state of the given wallet flag for a wallet.\n",
297 std::string flag_str = request.params[0].get_str();
298 bool value = request.params[1].isNull() || request.params[1].get_bool();
312 if (pwallet->IsWalletFlagSet(flag) == value) {
316 res.pushKV(
"flag_name", flag_str);
317 res.pushKV(
"flag_state", value);
320 pwallet->SetWalletFlag(flag);
322 pwallet->UnsetWalletFlag(flag);
338 "\nCreates and loads a new wallet.\n",
344 {
"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."},
345 {
"descriptors",
RPCArg::Type::BOOL,
RPCArg::Default{
true},
"Create a native descriptor wallet. The wallet will use descriptors internally to handle address creation."
346 " Setting to \"false\" will create a legacy wallet; however, the legacy wallet type is being deprecated and"
347 " support for creating and opening legacy wallets will be removed in the future."},
349 {
"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."},
354 {
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."},
355 {
RPCResult::Type::ARR,
"warnings",
true,
"Warning messages, if any, related to creating and loading the wallet.",
364 +
HelpExampleCliNamed(
"createwallet", {{
"wallet_name",
"descriptors"}, {
"avoid_reuse",
true}, {
"descriptors",
true}, {
"load_on_startup",
true}})
365 +
HelpExampleRpcNamed(
"createwallet", {{
"wallet_name",
"descriptors"}, {
"avoid_reuse",
true}, {
"descriptors",
true}, {
"load_on_startup",
true}})
371 if (!request.params[1].isNull() && request.params[1].get_bool()) {
375 if (!request.params[2].isNull() && request.params[2].get_bool()) {
379 passphrase.reserve(100);
380 std::vector<bilingual_str> warnings;
381 if (!request.params[3].isNull()) {
382 passphrase = std::string_view{request.params[3].get_str()};
383 if (passphrase.empty()) {
385 warnings.emplace_back(
Untranslated(
"Empty string given as passphrase, wallet will not be encrypted."));
389 if (!request.params[4].isNull() && request.params[4].get_bool()) {
392 if (request.params[5].isNull() || request.params[5].get_bool()) {
398 if (!request.params[7].isNull() && request.params[7].get_bool()) {
399 #ifdef ENABLE_EXTERNAL_SIGNER
419 std::optional<bool> load_on_start = request.params[6].isNull() ? std::nullopt : std::optional<bool>(request.params[6].get_bool());
438 "Unloads the wallet referenced by the request endpoint, otherwise unloads the wallet specified in the argument.\n"
439 "Specifying the wallet name on a wallet endpoint is invalid.",
441 {
"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."},
445 {
RPCResult::Type::ARR,
"warnings",
true,
"Warning messages, if any, related to unloading the wallet.",
456 std::string wallet_name;
458 if (!(request.params[0].isNull() || request.params[0].get_str() == wallet_name)) {
462 wallet_name = request.params[0].get_str();
471 std::vector<bilingual_str> warnings;
481 std::optional<bool> load_on_start{
self.MaybeArg<
bool>(1)};
500 "\nSet or generate a new HD wallet seed. Non-HD wallets will not be upgraded to being a HD wallet. Wallets that are already\n"
501 "HD will have a new HD seed set so that new keys added to the keypool will be derived from this new seed.\n"
502 "\nNote that you will need to MAKE A NEW BACKUP of your wallet after setting the HD wallet seed." +
HELP_REQUIRING_PASSPHRASE +
503 "Note: This command is only compatible with legacy wallets.\n",
505 {
"newkeypool",
RPCArg::Type::BOOL,
RPCArg::Default{
true},
"Whether to flush old unused addresses, including change addresses, from the keypool and regenerate it.\n"
506 "If true, the next address from getnewaddress and change address from getrawchangeaddress will be from this new seed.\n"
507 "If false, addresses (including change addresses if the wallet already had HD Chain Split enabled) from the existing\n"
508 "keypool will be used until it has been depleted."},
510 "The seed value can be retrieved using the dumpwallet command. It is the private key marked hdseed=1"},
533 if (!pwallet->CanSupportFeature(
FEATURE_HD)) {
534 throw JSONRPCError(
RPC_WALLET_ERROR,
"Cannot set an HD seed on a non-HD wallet. Use the upgradewallet RPC in order to upgrade a non-HD wallet to HD");
539 bool flush_key_pool =
true;
540 if (!request.params[0].isNull()) {
541 flush_key_pool = request.params[0].get_bool();
545 if (request.params[1].isNull()) {
571 "\nUpgrade the wallet. Upgrades to the latest version if no version number is specified.\n"
572 "New keys may be generated and a new wallet backup will need to be made.",
598 if (!request.params[0].isNull()) {
599 version = request.params[0].getInt<
int>();
602 const int previous_version{pwallet->GetVersion()};
603 const bool wallet_upgraded{pwallet->UpgradeWallet(version,
error)};
604 const int current_version{pwallet->GetVersion()};
607 if (wallet_upgraded) {
608 if (previous_version == current_version) {
609 result =
"Already at latest version. Wallet version unchanged.";
611 result =
strprintf(
"Wallet upgraded successfully from version %i to version %i.", previous_version, current_version);
616 obj.
pushKV(
"wallet_name", pwallet->GetName());
617 obj.
pushKV(
"previous_version", previous_version);
618 obj.
pushKV(
"current_version", current_version);
619 if (!result.empty()) {
620 obj.
pushKV(
"result", result);
633 "\nCalculate the balance change resulting in the signing and broadcasting of the given transaction(s).\n",
665 if (request.params[1].isObject()) {
666 UniValue options = request.params[1];
673 include_watchonly = options[
"include_watchonly"];
681 const auto& txs = request.params[0].get_array();
683 std::map<COutPoint, CAmount> new_utxos;
684 std::set<COutPoint> spent;
686 for (
size_t i = 0; i < txs.size(); ++i) {
688 if (!
DecodeHexTx(mtx, txs[i].get_str(),
true,
true)) {
693 std::map<COutPoint, Coin> coins;
697 wallet.chain().findCoins(coins);
701 for (
const auto& txin : mtx.
vin) {
702 const auto& outpoint = txin.
prevout;
703 if (spent.count(outpoint)) {
706 if (new_utxos.count(outpoint)) {
707 changes -= new_utxos.at(outpoint);
708 new_utxos.erase(outpoint);
710 if (coins.at(outpoint).IsSpent()) {
713 changes -=
wallet.GetDebit(txin, filter);
715 spent.insert(outpoint);
723 const auto& hash = mtx.
GetHash();
724 for (
size_t i = 0; i < mtx.
vout.size(); ++i) {
725 const auto& txout = mtx.
vout[i];
726 bool is_mine = 0 < (
wallet.IsMine(txout) & filter);
727 changes += new_utxos[
COutPoint(hash, i)] = is_mine ? txout.nValue : 0;
742 "EXPERIMENTAL warning: This call may not work as expected and may be changed in future releases\n"
743 "\nMigrate the wallet to a descriptor wallet.\n"
744 "A new wallet backup will need to be made.\n"
745 "\nThe migration process will create a backup of the wallet before migrating. This backup\n"
746 "file will be named <wallet name>-<timestamp>.legacy.bak and can be found in the directory\n"
747 "for this wallet. In the event of an incorrect migration, the backup can be restored using restorewallet."
748 "\nEncrypted wallets must have the passphrase provided as an argument to this call.",
750 {
"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."},
757 {
RPCResult::Type::STR,
"watchonly_name",
true,
"The name of the migrated wallet containing the watchonly scripts"},
758 {
RPCResult::Type::STR,
"solvables_name",
true,
"The name of the migrated wallet containing solvable but not watched scripts"},
768 std::string wallet_name;
770 if (!(request.params[0].isNull() || request.params[0].get_str() == wallet_name)) {
774 if (request.params[0].isNull()) {
777 wallet_name = request.params[0].get_str();
781 wallet_pass.reserve(100);
782 if (!request.params[1].isNull()) {
783 wallet_pass = std::string_view{request.params[1].get_str()};
793 r.pushKV(
"wallet_name", res->wallet_name);
794 if (res->watchonly_wallet) {
795 r.pushKV(
"watchonly_name", res->watchonly_wallet->GetName());
797 if (res->solvables_wallet) {
798 r.pushKV(
"solvables_name", res->solvables_wallet->GetName());
800 r.pushKV(
"backup_path", res->backup_path.u8string());
818 #ifdef ENABLE_EXTERNAL_SIGNER
944 #ifdef ENABLE_EXTERNAL_SIGNER
int64_t CAmount
Amount in satoshis (Can be negative)
#define CHECK_NONFATAL(condition)
Identity function.
An encapsulated private key.
const unsigned char * end() const
bool IsValid() const
Check whether this private key is valid.
bool IsCompressed() const
Check whether the public key corresponding to this private key is (to be) compressed.
CPubKey GetPubKey() const
Compute the public key from a private key.
void Set(const T pbegin, const T pend, bool fCompressedIn)
Initialize using begin and end iterators to byte data.
const unsigned char * begin() const
A reference to a CKey: the Hash160 of its serialized public key.
An outpoint - a combination of a transaction hash and an index n into its vout.
An encapsulated public key.
CKeyID GetID() const
Get the KeyID of this public key (hash of its serialization)
An input of a transaction.
RecursiveMutex cs_KeyStore
An interface to be implemented by keystores that support signing.
A Span is an object that can refer to a contiguous sequence of objects.
void push_back(UniValue val)
void pushKV(std::string key, UniValue val)
constexpr bool IsNull() const
std::string GetHex() const
CKeyID seed_id
seed hash160
A CWallet maintains a set of transactions and balances, and provides the ability to create new transa...
const CHDChain & GetHDChain() const
bool NewKeyPool()
Mark old keypool keys as used, and generate all new keys.
CPubKey GenerateNewSeed()
CPubKey DeriveNewSeed(const CKey &key)
void SetHDSeed(const CPubKey &key)
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
CKey DecodeSecret(const std::string &str)
bool error(const char *fmt, const Args &... args)
void ReadDatabaseArgs(const ArgsManager &args, DBOptions &options)
bilingual_str ErrorString(const Result< T > &result)
static RPCHelpMan sethdseed()
void UnloadWallet(std::shared_ptr< CWallet > &&wallet)
Explicitly unload and delete the wallet.
void AppendLastProcessedBlock(UniValue &entry, const CWallet &wallet) EXCLUSIVE_LOCKS_REQUIRED(wallet.cs_wallet)
void ReadDatabaseArgs(const ArgsManager &args, DatabaseOptions &options)
Balance GetBalance(const CWallet &wallet, const int min_depth, bool avoid_reuse)
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 importwallet()
bool GetWalletNameFromJSONRPCRequest(const JSONRPCRequest &request, std::string &wallet_name)
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
std::vector< fs::path > ListDatabases(const fs::path &wallet_dir)
Recursively list database paths in directory.
RPCHelpMan getreceivedbyaddress()
RPCHelpMan walletdisplayaddress()
RPCHelpMan importaddress()
RPCHelpMan importprunedfunds()
LegacyScriptPubKeyMan & EnsureLegacyScriptPubKeyMan(CWallet &wallet, bool also_create)
RPCHelpMan simulaterawtransaction()
static RPCHelpMan setwalletflag()
RPCHelpMan importprivkey()
RPCHelpMan walletcreatefundedpsbt()
bool RemoveWallet(WalletContext &context, const std::shared_ptr< CWallet > &wallet, std::optional< bool > load_on_start)
RPCHelpMan addmultisigaddress()
WalletContext & EnsureWalletContext(const std::any &context)
RPCHelpMan listaddressgroupings()
RPCHelpMan walletpassphrasechange()
std::underlying_type< isminetype >::type isminefilter
used for bitflags of isminetype
fs::path GetWalletDir()
Get the path of the wallet directory.
RPCHelpMan abandontransaction()
bool HaveKey(const SigningProvider &wallet, const CKey &key)
Checks if a CKey is in the given CWallet compressed or otherwise.
RPCHelpMan listdescriptors()
RPCHelpMan listtransactions()
RPCHelpMan signrawtransactionwithwallet()
util::Result< MigrationResult > MigrateLegacyToDescriptor(const std::string &wallet_name, const SecureString &passphrase, WalletContext &context)
Do all steps to migrate a legacy wallet to a descriptor wallet.
RPCHelpMan importpubkey()
static RPCHelpMan listwallets()
static RPCHelpMan upgradewallet()
static const std::map< std::string, WalletFlags > WALLET_FLAG_MAP
static RPCHelpMan unloadwallet()
RPCHelpMan listsinceblock()
RPCHelpMan restorewallet()
bool ParseIncludeWatchonly(const UniValue &include_watchonly, const CWallet &wallet)
Used by RPC commands that have an include_watchonly parameter.
RPCHelpMan getreceivedbylabel()
RPCHelpMan importdescriptors()
RPCHelpMan getrawchangeaddress()
static RPCHelpMan createwallet()
RPCHelpMan getaddressinfo()
RPCHelpMan encryptwallet()
RPCHelpMan gettransaction()
RPCHelpMan getaddressesbylabel()
RPCHelpMan fundrawtransaction()
static const std::map< uint64_t, std::string > WALLET_FLAG_CAVEATS
Span< const CRPCCommand > GetWalletRPCCommands()
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,...
static constexpr uint64_t MUTABLE_WALLET_FLAGS
RPCHelpMan getnewaddress()
RPCHelpMan listreceivedbylabel()
std::shared_ptr< CWallet > GetWallet(WalletContext &context, const std::string &name)
RPCHelpMan getunconfirmedbalance()
RPCHelpMan sendtoaddress()
std::shared_ptr< CWallet > wallet
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.
void RPCTypeCheckObj(const UniValue &o, const std::map< std::string, UniValueType > &typesExpected, bool fAllowNull, bool fStrict)
std::string HelpExampleCliNamed(const std::string &methodname, const RPCArgList &args)
std::basic_string< char, std::char_traits< char >, secure_allocator< char > > SecureString
A mutable version of CTransaction.
uint256 GetHash() const
Compute the hash of this CMutableTransaction.
std::vector< CTxOut > vout
@ 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_HEX
Special string with only hex chars.
@ STR_AMOUNT
Special string to represent a floating point amount.
Wrapper for UniValue::VType, which includes typeAny: Used to denote don't care type.
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.