Creating, loading and inspecting wallets

751                {"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"},
752            }},
753        },
754        RPCResult{
755            RPCResult::Type::OBJ, "", "",
756            {
757                {RPCResult::Type::ARR, "descs", "The public descriptors that were added to the wallet",
758                    {{RPCResult::Type::STR, "", ""}}
759                }
760            },
761        },
762        RPCExamples{
763            HelpExampleCli("createwalletdescriptor", "bech32m")
764            + HelpExampleRpc("createwalletdescriptor", R"("bech32m")")
765        },
766        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
767        {
768            std::shared_ptr<CWallet> const pwallet = GetWalletForJSONRPCRequest(request);
769            if (!pwallet) return UniValue::VNULL;
770
771            std::optional<OutputType> output_type = ParseOutputType(request.params[0].get_str());
772            if (!output_type) {
773                throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, strprintf("Unknown address type '%s'", request.params[0].get_str()));
774            }
775
776            UniValue options{request.params[1].isNull() ? UniValue::VOBJ : request.params[1]};
777            UniValue internal_only{options["internal"]};
778            UniValue hdkey{options["hdkey"]};
779
780            std::vector<bool> internals;
781            if (internal_only.isNull()) {
782                internals.push_back(false);
783                internals.push_back(true);
784            } else {
785                internals.push_back(internal_only.get_bool());
786            }
787
788            LOCK(pwallet->cs_wallet);
789            EnsureWalletIsUnlocked(*pwallet);
790
791            CExtPubKey xpub;
792            if (hdkey.isNull()) {
793                HDPubKeyMap active_xpubs = pwallet->GetHDPubKeys(HDKeyFilter::Active);
794                if (active_xpubs.size() != 1) {
795                    throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Unable to determine which HD key to use from active descriptors. Please specify with 'hdkey'");
796                }
797                xpub = active_xpubs.begin()->first;
798            } else {
799                xpub = DecodeExtPubKey(hdkey.get_str());
800                if (!xpub.pubkey.IsValid()) {
801                    throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Unable to parse HD key. Please provide a valid xpub");
802                }
803            }
804
805            std::optional<CKey> key = pwallet->GetKey(xpub.pubkey.GetID());
806            if (!key) {
807                throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, strprintf("Private key for %s is not known", EncodeExtPubKey(xpub)));
808            }
809            CExtKey active_hdkey(xpub, *key);
810
811            std::vector<std::reference_wrapper<DescriptorScriptPubKeyMan>> spkms;
812            WalletBatch batch{pwallet->GetDatabase()};
813            for (bool internal : internals) {
814                WalletDescriptor w_desc = GenerateWalletDescriptor(xpub, *output_type, internal);
815                if (!pwallet->GetDescriptorScriptPubKeyMan(w_desc)) {
816                    spkms.emplace_back(pwallet->SetupDescriptorScriptPubKeyMan(batch, active_hdkey, *output_type, internal));
817                }
818            }
819            if (spkms.empty()) {
820                throw JSONRPCError(RPC_WALLET_ERROR, "Descriptor already exists");
821            }
822
823            // Fetch each descspkm from the wallet in order to get the descriptor strings
824            UniValue descs{UniValue::VARR};
825            for (const auto& spkm : spkms) {
826                std::string desc_str;
827                bool ok = spkm.get().GetDescriptorString(desc_str, false);
828                CHECK_NONFATAL(ok);
829                descs.push_back(desc_str);
830            }
831            UniValue out{UniValue::VOBJ};
832            out.pushKV("descs", std::move(descs));
833            return out;
834        }
835    };
836}
837
838RPCMethod addhdkey()
839{
840    return RPCMethod{
841        "addhdkey",
842        "Add a BIP 32 HD key to the wallet that can be used with 'createwalletdescriptor'\n",
843        {
844            {"hdkey", RPCArg::Type::STR, RPCArg::DefaultHint{"Automatically generated new key"}, "The BIP 32 extended private key to add. If none is provided, a randomly generated one will be added."},
845        },
846        RPCResult{
847            RPCResult::Type::OBJ, "", "",
848            {
849                {RPCResult::Type::STR, "xpub", "The xpub of the HD key that was added to the wallet"}
850            },
851        },
852        RPCExamples{
853            HelpExampleCli("addhdkey", "xprv") + HelpExampleRpc("addhdkey", R"("xprv")")
854        },
855        [&](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
856        {
857            std::shared_ptr<CWallet> const wallet = GetWalletForJSONRPCRequest(request);
858            if (!wallet) return UniValue::VNULL;
859
860            if (wallet->IsWalletFlagSet(WALLET_FLAG_DISABLE_PRIVATE_KEYS)) {
861                throw JSONRPCError(RPC_WALLET_ERROR, "addhdkey is not available for wallets without private keys");
862            }
863
864            EnsureWalletIsUnlocked(*wallet);
865
866            CExtKey hdkey;
867            if (request.params[0].isNull()) {
868                CKey seed_key = GenerateRandomKey();
869                hdkey.SetSeed(seed_key);
870            } else {
871                hdkey = DecodeExtKey(request.params[0].get_str());
872                if (!hdkey.key.IsValid()) {
873                    // Check if the user gave us an xpub and give a more descriptive error if so
874                    CExtPubKey xpub = DecodeExtPubKey(request.params[0].get_str());
875                    if (xpub.pubkey.IsValid()) {
876                        throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Extended public key (xpub) provided, but extended private key (xprv) is required");
877                    } else {
878                        throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Could not parse HD key");
879                    }
880                }
881            }
882
883            LOCK(wallet->cs_wallet);
884            std::string desc_str = "unused(" + EncodeExtKey(hdkey) + ")";
885            FlatSigningProvider keys;
886            std::string error;
887            std::vector<std::unique_ptr<Descriptor>> descs = Parse(desc_str, keys, error, false);
888            CHECK_NONFATAL(!descs.empty());
889            WalletDescriptor w_desc(std::move(descs.at(0)), GetTime(), 0, 0, 0);
890            if (wallet->GetDescriptorScriptPubKeyMan(w_desc) != nullptr) {
891                throw JSONRPCError(RPC_WALLET_ERROR, "HD key already exists");
892            }
893
894            auto spkm = wallet->AddWalletDescriptor(w_desc, keys, /*label=*/"", /*internal=*/false);
895            if (!spkm) {
896                throw JSONRPCError(RPC_WALLET_ERROR, util::ErrorString(spkm).original);
897            }
898
899            UniValue response(UniValue::VOBJ);
900            const DescriptorScriptPubKeyMan& desc_spkm = spkm->get();
901            LOCK(desc_spkm.cs_desc_man);
902            std::set<CPubKey> pubkeys;
903            std::set<CExtPubKey> extpubs;
904            desc_spkm.GetWalletDescriptor().descriptor->GetPubKeys(pubkeys, extpubs);
905            CHECK_NONFATAL(pubkeys.size() == 0);
906            CHECK_NONFATAL(extpubs.size() == 1);
907            response.pushKV("xpub", EncodeExtPubKey(*extpubs.begin()));
908
909            return response;
910        },
911    };
912}
913
914static RPCMethod exportwatchonlywallet()
915{
916    return RPCMethod{"exportwatchonlywallet",
917        "Creates a wallet file at the specified destination containing a watchonly version "
918        "of the current wallet. This watchonly wallet contains the wallet's public descriptors, "
919        "its transactions, and address book data. Descriptors that use hardened derivation will "
920        "only have a limited number of derived keys included in the export due to hardened "
921        "derivation requiring private keys. Descriptors with unhardened derivation do not have "
922        "this limitation. The watchonly wallet can be imported into another node using 'restorewallet'.",
923        {
924            {"destination", RPCArg::Type::STR, RPCArg::Optional::NO, "The path to the filename the exported watchonly wallet will be saved to"},
925        },
926        RPCResult{
927            RPCResult::Type::OBJ, "", "",
928            {
929                {RPCResult::Type::STR, "exported_file", "The full path that the file has been exported to"},
930            },
931        },
932        RPCExamples{
933            HelpExampleCli("exportwatchonlywallet", "\"/path/to/export.dat\"")
934            + HelpExampleRpc("exportwatchonlywallet", "\"/path/to/export.dat\"")
935        },
936        [&](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
937        {
938            std::shared_ptr<CWallet> const pwallet = GetWalletForJSONRPCRequest(request);
939            if (!pwallet) return UniValue::VNULL;
940            WalletContext& context = EnsureWalletContext(request.context);
941
942            std::string dest = request.params[0].get_str();
943
944            LOCK(pwallet->cs_wallet);
945            pwallet->TopUpKeyPool();
946            util::Result<std::string> exported = ExportWatchOnlyWallet(*pwallet, fs::PathFromString(dest), context);
947            if (!exported) {
948                throw JSONRPCError(RPC_WALLET_ERROR, util::ErrorString(exported).original);
949            }
950            UniValue out{UniValue::VOBJ};
951            out.pushKV("exported_file", *exported);
952            return out;
953        }
954    };
955}
956
957RPCMethod derivehdkey()
958{
959    return RPCMethod{
960        "derivehdkey",
961        "Derive extended public or private key from HD key in the wallet at a given path.\n"
962        "Derivation uses wallet private key material.\n"
963        + HELP_REQUIRING_PASSPHRASE,
964        {
965            {"path", RPCArg::Type::STR, RPCArg::Optional::NO, "BIP 32 derivation path with at least one hardened step."},
966            {"options", RPCArg::Type::OBJ_NAMED_PARAMS, RPCArg::Optional::OMITTED, "", {
967                {"private", RPCArg::Type::BOOL, RPCArg::Default{false}, "Show private key"},
968                {"hdkey", RPCArg::Type::STR, RPCArg::DefaultHint{"Either the HD key of an unused(KEY) descriptor, or any other active descriptor."}, "The HD key that the wallet knows the private key of, listed using 'gethdkeys', to use for derivation"},
969            }},
970        },
971        RPCResult{
972            RPCResult::Type::OBJ, "", "", {
973                {RPCResult::Type::STR, "origin", "Fingerprint and path for use in descriptors"},
974                {RPCResult::Type::STR, "xpub", "The extended public key"},
975                {RPCResult::Type::STR, "xprv", /*optional=*/true, "The extended private key if \"private\" is true"},
976            },
977        },
978        RPCExamples{
979            HelpExampleCli("derivehdkey", "m/87h/0h/0h") + HelpExampleRpc("derivehdkey", "\"m/87h/0h/0h\"")
980            + HelpExampleCliNamed("derivehdkey", {{"path", "m/87h/0h/0h"}, {"private", "true"}})
981            + HelpExampleRpcNamed("derivehdkey", {{"path", "m/87h/0h/0h"}, {"private", "true"}})
982        },
983        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
984        {
985            const std::shared_ptr<const CWallet> wallet = GetWalletForJSONRPCRequest(request);
986            if (!wallet) return UniValue::VNULL;
987
988            if (wallet->IsWalletFlagSet(WALLET_FLAG_DISABLE_PRIVATE_KEYS)) {
989                // Watch-only wallets can't contain unused(KEY) descriptors
990                throw JSONRPCError(RPC_WALLET_ERROR, "derivehdkey is not available for watch-only wallets");
991            }
992
993            std::vector<uint32_t> path = ParsePathBIP32(request.params[0].get_str());
994            UniValue options{request.params[1].isNull() ? UniValue::VOBJ : request.params[1]};
995            const bool priv{options.exists("private") ? options["private"].get_bool() : false};
996            UniValue hdkey{options["hdkey"]};
997            if (!HasHardenedDerivation(path)) {
998                throw JSONRPCError(RPC_INVALID_PARAMETER, "Derivation path requires at least one hardened step");
999            }
1000