|
Bitcoin Core
22.99.0
P2P Digital Currency
|
Go to the documentation of this file.
33 "Returns an object containing various wallet state info.\n",
47 {
RPCResult::Type::NUM,
"keypoolsize",
"how many new keys are pre-generated (only counts external keys)"},
48 {
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)"},
49 {
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)"},
52 {
RPCResult::Type::BOOL,
"private_keys_enabled",
"false if privatekeys are disabled for this wallet (enforced watch-only wallet)"},
53 {
RPCResult::Type::BOOL,
"avoid_reuse",
"whether this wallet tracks clean/dirty coins in terms of reuse"},
54 {
RPCResult::Type::OBJ,
"scanning",
"current scanning details, or false if no scan is in progress",
59 {
RPCResult::Type::BOOL,
"descriptors",
"whether this wallet uses descriptors for scriptPubKey management"},
60 {
RPCResult::Type::BOOL,
"external_signer",
"whether this wallet is configured to use an external signer such as a hardware wallet"},
74 pwallet->BlockUntilSyncedToCurrentChain();
76 LOCK(pwallet->cs_wallet);
80 size_t kpExternalSize = pwallet->KeypoolCountExternalKeys();
82 obj.
pushKV(
"walletname", pwallet->GetName());
83 obj.
pushKV(
"walletversion", pwallet->GetVersion());
84 obj.
pushKV(
"format", pwallet->GetDatabase().Format());
88 obj.
pushKV(
"txcount", (
int)pwallet->mapWallet.size());
89 const auto kp_oldest = pwallet->GetOldestKeyPoolTime();
90 if (kp_oldest.has_value()) {
91 obj.
pushKV(
"keypoololdest", kp_oldest.value());
93 obj.
pushKV(
"keypoolsize", (int64_t)kpExternalSize);
104 obj.
pushKV(
"keypoolsize_hd_internal", (int64_t)(pwallet->GetKeyPoolSize() - kpExternalSize));
106 if (pwallet->IsCrypted()) {
107 obj.
pushKV(
"unlocked_until", pwallet->nRelockTime);
112 if (pwallet->IsScanning()) {
114 scanning.
pushKV(
"duration", pwallet->ScanningDuration() / 1000);
115 scanning.
pushKV(
"progress", pwallet->ScanningProgress());
116 obj.
pushKV(
"scanning", scanning);
118 obj.
pushKV(
"scanning",
false);
130 "Returns a list of wallets in the wallet directory.\n",
153 wallet.pushKV(
"name", path.u8string());
158 result.
pushKV(
"wallets", wallets);
167 "Returns a list of currently loaded wallets.\n"
168 "For full information on the wallet, use \"getwalletinfo\"\n",
198 "\nLoads a wallet from a wallet file or directory."
199 "\nNote that all wallet command-line options used when starting bitcoind will be"
200 "\napplied to the new wallet.\n",
219 const std::string
name(request.params[0].get_str());
225 std::vector<bilingual_str> warnings;
226 std::optional<bool> load_on_start = request.params[1].isNull() ? std::nullopt : std::optional<bool>(request.params[1].get_bool());
242 std::string
flags =
"";
245 flags += (
flags ==
"" ?
"" :
", ") + it.first;
248 "\nChange the state of the given wallet flag for a wallet.\n",
270 std::string flag_str = request.params[0].
get_str();
271 bool value = request.params[1].isNull() || request.params[1].get_bool();
285 if (pwallet->IsWalletFlagSet(flag) == value) {
289 res.pushKV(
"flag_name", flag_str);
290 res.pushKV(
"flag_state", value);
293 pwallet->SetWalletFlag(flag);
295 pwallet->UnsetWalletFlag(flag);
311 "\nCreates and loads a new wallet.\n",
317 {
"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."},
318 {
"descriptors",
RPCArg::Type::BOOL,
RPCArg::Default{
true},
"Create a native descriptor wallet. The wallet will use descriptors internally to handle address creation"},
320 {
"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."},
325 {
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."},
332 +
HelpExampleCliNamed(
"createwallet", {{
"wallet_name",
"descriptors"}, {
"avoid_reuse",
true}, {
"descriptors",
true}, {
"load_on_startup",
true}})
333 +
HelpExampleRpcNamed(
"createwallet", {{
"wallet_name",
"descriptors"}, {
"avoid_reuse",
true}, {
"descriptors",
true}, {
"load_on_startup",
true}})
339 if (!request.params[1].isNull() && request.params[1].get_bool()) {
343 if (!request.params[2].isNull() && request.params[2].get_bool()) {
347 passphrase.reserve(100);
348 std::vector<bilingual_str> warnings;
349 if (!request.params[3].isNull()) {
350 passphrase = request.params[3].get_str().c_str();
351 if (passphrase.empty()) {
353 warnings.emplace_back(
Untranslated(
"Empty string given as passphrase, wallet will not be encrypted."));
357 if (!request.params[4].isNull() && request.params[4].get_bool()) {
360 if (request.params[5].isNull() || request.params[5].get_bool()) {
366 if (!request.params[7].isNull() && request.params[7].get_bool()) {
367 #ifdef ENABLE_EXTERNAL_SIGNER
386 std::optional<bool> load_on_start = request.params[6].isNull() ? std::nullopt : std::optional<bool>(request.params[6].get_bool());
405 "Unloads the wallet referenced by the request endpoint otherwise unloads the wallet specified in the argument.\n"
406 "Specifying the wallet name on a wallet endpoint is invalid.",
408 {
"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."},
420 std::string wallet_name;
422 if (!(request.params[0].isNull() || request.params[0].get_str() == wallet_name)) {
426 wallet_name = request.params[0].get_str();
438 std::vector<bilingual_str> warnings;
439 std::optional<bool> load_on_start = request.params[1].isNull() ? std::nullopt : std::optional<bool>(request.params[1].get_bool());
456 "\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"
457 "HD will have a new HD seed set so that new keys added to the keypool will be derived from this new seed.\n"
458 "\nNote that you will need to MAKE A NEW BACKUP of your wallet after setting the HD wallet seed." +
461 {
"newkeypool",
RPCArg::Type::BOOL,
RPCArg::Default{
true},
"Whether to flush old unused addresses, including change addresses, from the keypool and regenerate it.\n"
462 "If true, the next address from getnewaddress and change address from getrawchangeaddress will be from this new seed.\n"
463 "If false, addresses (including change addresses if the wallet already had HD Chain Split enabled) from the existing\n"
464 "keypool will be used until it has been depleted."},
466 "The seed value can be retrieved using the dumpwallet command. It is the private key marked hdseed=1"},
489 if (!pwallet->CanSupportFeature(
FEATURE_HD)) {
490 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");
495 bool flush_key_pool =
true;
496 if (!request.params[0].isNull()) {
497 flush_key_pool = request.params[0].get_bool();
501 if (request.params[1].isNull()) {
527 "\nUpgrade the wallet. Upgrades to the latest version if no version number is specified.\n"
528 "New keys may be generated and a new wallet backup will need to be made.",
556 if (!request.params[0].isNull()) {
557 version = request.params[0].get_int();
560 const int previous_version{pwallet->GetVersion()};
561 const bool wallet_upgraded{pwallet->UpgradeWallet(version,
error)};
562 const int current_version{pwallet->GetVersion()};
565 if (wallet_upgraded) {
566 if (previous_version == current_version) {
567 result =
"Already at latest version. Wallet version unchanged.";
569 result =
strprintf(
"Wallet upgraded successfully from version %i to version %i.", previous_version, current_version);
574 obj.
pushKV(
"wallet_name", pwallet->GetName());
575 obj.
pushKV(
"previous_version", previous_version);
576 obj.
pushKV(
"current_version", current_version);
577 if (!result.empty()) {
578 obj.
pushKV(
"result", result);
599 #ifdef ENABLE_EXTERNAL_SIGNER
601 #endif // ENABLE_EXTERNAL_SIGNER
712 {
"wallet", &
send, },
724 #ifdef ENABLE_EXTERNAL_SIGNER
726 #endif // ENABLE_EXTERNAL_SIGNER
bool IsCompressed() const
Check whether the public key corresponding to this private key is (to be) compressed.
@ RPC_MISC_ERROR
General application defined errors.
RPCHelpMan listtransactions()
RPCHelpMan walletcreatefundedpsbt()
RPCHelpMan backupwallet()
static RPCHelpMan sethdseed()
std::string HelpExampleCli(const std::string &methodname, const std::string &args)
RPCHelpMan keypoolrefill()
#define CHECK_NONFATAL(condition)
Throw a NonFatalCheckError when the condition evaluates to false.
std::vector< fs::path > ListDatabases(const fs::path &wallet_dir)
Recursively list database paths in directory.
RPCHelpMan encryptwallet()
RPCHelpMan getaddressesbylabel()
const UniValue NullUniValue
RPCHelpMan fundrawtransaction()
@ RPC_INVALID_PARAMETER
Invalid, missing or duplicate parameter.
void Set(const T pbegin, const T pend, bool fCompressedIn)
Initialize using begin and end iterators to byte data.
RPCHelpMan listsinceblock()
RPCHelpMan getreceivedbyaddress()
RPCHelpMan rescanblockchain()
RPCHelpMan walletdisplayaddress()
CPubKey DeriveNewSeed(const CKey &key)
@ WALLET_FLAG_DESCRIPTORS
Indicate that this wallet supports DescriptorScriptPubKeyMan.
An interface to be implemented by keystores that support signing.
static RPCHelpMan createwallet()
std::shared_ptr< CWallet > GetWalletForJSONRPCRequest(const JSONRPCRequest &request)
Figures out what wallet, if any, to use for a JSONRPCRequest.
CPubKey GenerateNewSeed()
RPCHelpMan walletpassphrasechange()
bool HaveKey(const SigningProvider &wallet, const CKey &key)
Checks if a CKey is in the given CWallet compressed or otherwise.
A reference to a CKey: the Hash160 of its serialized public key.
std::shared_ptr< CWallet > wallet
bool pushKV(const std::string &key, const UniValue &val)
RPCHelpMan walletpassphrase()
UniValue ValueFromAmount(const CAmount amount)
RPCHelpMan importpubkey()
const unsigned char * end() const
static const std::map< std::string, WalletFlags > WALLET_FLAG_MAP
bool NewKeyPool()
Mark old keypool keys as used, and generate all new keys.
std::vector< std::shared_ptr< CWallet > > GetWallets(WalletContext &context)
RPCHelpMan abandontransaction()
const std::string HELP_REQUIRING_PASSPHRASE
@ WALLET_FLAG_EXTERNAL_SIGNER
Indicates that the wallet needs an external signer.
A Span is an object that can refer to a contiguous sequence of objects.
const std::string & get_str() const
RPCHelpMan listreceivedbyaddress()
const unsigned char * begin() const
RPCHelpMan importdescriptors()
std::basic_string< char, std::char_traits< char >, secure_allocator< char > > SecureString
std::string getnewaddress(wallet::CWallet &w)
Returns a new address from the wallet.
const std::string CURRENCY_UNIT
RPCHelpMan listaddressgroupings()
bilingual_str Untranslated(std::string original)
Mark a bilingual_str as untranslated.
@ OMITTED_NAMED_ARG
Optional arg that is a named argument and has a default value of null.
@ RPC_WALLET_NOT_FOUND
Invalid wallet specified.
@ WALLET_FLAG_BLANK_WALLET
Flag set when a wallet contains no HD seed and no private keys, scripts, addresses,...
@ WALLET_FLAG_DISABLE_PRIVATE_KEYS
@ STR_HEX
Special string with only hex chars.
bool IsValid() const
Check whether this private key is valid.
std::shared_ptr< CWallet > GetWallet(WalletContext &context, const std::string &name)
Span< const CRPCCommand > GetWalletRPCCommands()
static RPCHelpMan listwalletdir()
@ RPC_WALLET_ENCRYPTION_FAILED
Failed to encrypt the wallet.
std::string GetHex() const
RPCHelpMan getaddressinfo()
@ WALLET_FLAG_AVOID_REUSE
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)
void HandleWalletError(const std::shared_ptr< CWallet > wallet, DatabaseStatus &status, bilingual_str &error)
@ RPC_WALLET_ERROR
Wallet errors.
CKey DecodeSecret(const std::string &str)
RPCHelpMan importprunedfunds()
@ NUM_TIME
Special numeric to denote unix epoch time.
RPCHelpMan restorewallet()
CKeyID seed_id
seed hash160
CPubKey GetPubKey() const
Compute the public key from a private key.
RPCHelpMan gettransaction()
std::string HelpExampleRpc(const std::string &methodname, const std::string &args)
RPCHelpMan listlockunspent()
std::string HelpExampleRpcNamed(const std::string &methodname, const RPCArgList &args)
RPCHelpMan signrawtransactionwithwallet()
RPCHelpMan sendtoaddress()
RPCHelpMan getreceivedbylabel()
void importaddress(wallet::CWallet &wallet, const std::string &address)
Import the address to the wallet.
RPCHelpMan walletprocesspsbt()
@ RPC_INVALID_ADDRESS_OR_KEY
Invalid address or key.
const CHDChain & GetHDChain() const
auto Join(const std::vector< T > &list, const BaseType &separator, UnaryOp unary_op) -> decltype(unary_op(list.at(0)))
Join a list of items.
static RPCHelpMan loadwallet()
An encapsulated public key.
RPCHelpMan removeprunedfunds()
static RPCHelpMan upgradewallet()
static RPCHelpMan unloadwallet()
static constexpr uint64_t MUTABLE_WALLET_FLAGS
An encapsulated private key.
static RPCHelpMan setwalletflag()
void RPCTypeCheck(const UniValue ¶ms, const std::list< UniValueType > &typesExpected, bool fAllowNull)
Type-check arguments; throws JSONRPCError if wrong type given.
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)
UniValue JSONRPCError(int code, const std::string &message)
RPCErrorCode
Bitcoin RPC error codes.
static RPCHelpMan listwallets()
fs::path GetWalletDir()
Get the path of the wallet directory.
RPCHelpMan importwallet()
bool push_back(const UniValue &val)
RPCHelpMan getrawchangeaddress()
bool GetWalletNameFromJSONRPCRequest(const JSONRPCRequest &request, std::string &wallet_name)
Balance GetBalance(const CWallet &wallet, const int min_depth, bool avoid_reuse)
RPCHelpMan addmultisigaddress()
void SetHDSeed(const CPubKey &key)
std::string HelpExampleCliNamed(const std::string &methodname, const RPCArgList &args)
RPCHelpMan listreceivedbylabel()
WalletContext struct containing references to state shared between CWallet instances,...
RPCHelpMan getunconfirmedbalance()
RecursiveMutex cs_KeyStore
const std::map< uint64_t, std::string > WALLET_FLAG_CAVEATS
void UnloadWallet(std::shared_ptr< CWallet > &&wallet)
Explicitly unload and delete the wallet.
bool error(const char *fmt, const Args &... args)
@ STR_AMOUNT
Special string to represent a floating point amount.
RPCHelpMan listdescriptors()
SecureString create_passphrase
static RPCHelpMan getwalletinfo()
LegacyScriptPubKeyMan & EnsureLegacyScriptPubKeyMan(CWallet &wallet, bool also_create)
RPCHelpMan importprivkey()
const std::string UNIX_EPOCH_TIME
String used to describe UNIX epoch time in documentation, factored out to a constant for consistency.
CKeyID GetID() const
Get the KeyID of this public key (hash of its serialization)
void EnsureWalletIsUnlocked(const CWallet &wallet)
WalletContext & EnsureWalletContext(const std::any &context)
bool RemoveWallet(WalletContext &context, const std::shared_ptr< CWallet > &wallet, std::optional< bool > load_on_start)