Wallet balances, unspent outputs and local coin locks

251            + HelpExampleCli("listlockunspent", "") +
252            "\nUnlock the transaction again\n"
253            + HelpExampleCli("lockunspent", "true \"[{\\\"txid\\\":\\\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\\\",\\\"vout\\\":1}]\"") +
254            "\nLock the transaction persistently in the wallet database\n"
255            + HelpExampleCli("lockunspent", "false \"[{\\\"txid\\\":\\\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\\\",\\\"vout\\\":1}]\" true") +
256            "\nAs a JSON-RPC call\n"
257            + HelpExampleRpc("lockunspent", "false, \"[{\\\"txid\\\":\\\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\\\",\\\"vout\\\":1}]\"")
258                },
259        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
260{
261    std::shared_ptr<CWallet> const pwallet = GetWalletForJSONRPCRequest(request);
262    if (!pwallet) return UniValue::VNULL;
263
264    // Make sure the results are valid at least up to the most recent block
265    // the user could have gotten from another RPC command prior to now
266    pwallet->BlockUntilSyncedToCurrentChain();
267
268    LOCK(pwallet->cs_wallet);
269
270    bool fUnlock = request.params[0].get_bool();
271
272    const bool persistent{request.params[2].isNull() ? false : request.params[2].get_bool()};
273
274    if (request.params[1].isNull()) {
275        if (fUnlock) {
276            if (!pwallet->UnlockAllCoins())
277                throw JSONRPCError(RPC_WALLET_ERROR, "Unlocking coins failed");
278        }
279        return true;
280    }
281
282    const UniValue& output_params = request.params[1].get_array();
283
284    // Create and validate the COutPoints first.
285
286    std::vector<COutPoint> outputs;
287    outputs.reserve(output_params.size());
288
289    for (unsigned int idx = 0; idx < output_params.size(); idx++) {
290        const UniValue& o = output_params[idx].get_obj();
291
292        RPCTypeCheckObj(o,
293            {
294                {"txid", UniValueType(UniValue::VSTR)},
295                {"vout", UniValueType(UniValue::VNUM)},
296            });
297
298        const Txid txid = Txid::FromUint256(ParseHashO(o, "txid"));
299        const int nOutput = o.find_value("vout").getInt<int>();
300        if (nOutput < 0) {
301            throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid parameter, vout cannot be negative");
302        }
303
304        const COutPoint outpt(txid, nOutput);
305
306        const auto it = pwallet->mapWallet.find(outpt.hash);
307        if (it == pwallet->mapWallet.end()) {
308            throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid parameter, unknown transaction");
309        }
310
311        const CWalletTx& trans = it->second;
312
313        if (outpt.n >= trans.GetTx()->vout.size()) {
314            throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid parameter, vout index out of bounds");
315        }
316
317        if (pwallet->IsSpent(outpt)) {
318            throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid parameter, expected unspent output");
319        }
320
321        const bool is_locked = pwallet->IsLockedCoin(outpt);
322
323        if (fUnlock && !is_locked) {
324            throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid parameter, expected locked output");
325        }
326
327        if (!fUnlock && is_locked && !persistent) {
328            throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid parameter, output already locked");
329        }
330
331        outputs.push_back(outpt);
332    }
333
334    // Atomically set (un)locked status for the outputs.
335    for (const COutPoint& outpt : outputs) {
336        if (fUnlock) {
337            if (!pwallet->UnlockCoin(outpt)) throw JSONRPCError(RPC_WALLET_ERROR, "Unlocking coin failed");
338        } else {
339            if (!pwallet->LockCoin(outpt, persistent)) throw JSONRPCError(RPC_WALLET_ERROR, "Locking coin failed");
340        }
341    }
342
343    return true;
344},
345    };
346}
347
348RPCMethod listlockunspent()
349{
350    return RPCMethod{
351        "listlockunspent",
352        "Returns list of temporarily unspendable outputs.\n"
353                "See the lockunspent call to lock and unlock transactions for spending.\n",
354                {},
355                RPCResult{
356                    RPCResult::Type::ARR, "", "",
357                    {
358                        {RPCResult::Type::OBJ, "", "",
359                        {
360                            {RPCResult::Type::STR_HEX, "txid", "The transaction id locked"},
361                            {RPCResult::Type::NUM, "vout", "The vout value"},
362                        }},
363                    }
364                },
365                RPCExamples{
366            "\nList the unspent transactions\n"
367            + HelpExampleCli("listunspent", "") +
368            "\nLock an unspent transaction\n"
369            + HelpExampleCli("lockunspent", "false \"[{\\\"txid\\\":\\\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\\\",\\\"vout\\\":1}]\"") +
370            "\nList the locked transactions\n"
371            + HelpExampleCli("listlockunspent", "") +
372            "\nUnlock the transaction again\n"
373            + HelpExampleCli("lockunspent", "true \"[{\\\"txid\\\":\\\"a08e6907dbbd3d809776dbfc5d82e371b764ed838b5655e72f463568df1aadf0\\\",\\\"vout\\\":1}]\"") +
374            "\nAs a JSON-RPC call\n"
375            + HelpExampleRpc("listlockunspent", "")
376                },
377        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
378{
379    const std::shared_ptr<const CWallet> pwallet = GetWalletForJSONRPCRequest(request);
380    if (!pwallet) return UniValue::VNULL;
381
382    LOCK(pwallet->cs_wallet);
383
384    std::vector<COutPoint> vOutpts;
385    pwallet->ListLockedCoins(vOutpts);
386
387    UniValue ret(UniValue::VARR);
388
389    for (const COutPoint& outpt : vOutpts) {
390        UniValue o(UniValue::VOBJ);
391
392        o.pushKV("txid", outpt.hash.GetHex());
393        o.pushKV("vout", outpt.n);
394        ret.push_back(std::move(o));
395    }
396
397    return ret;
398},
399    };
400}
401
402RPCMethod getbalances()
403{
404    return RPCMethod{
405        "getbalances",
406        "Returns an object with all balances in " + CURRENCY_UNIT + ".\n",
407        {},
408        RPCResult{
409            RPCResult::Type::OBJ, "", "",
410            {
411                {RPCResult::Type::OBJ, "mine", "balances from outputs that the wallet can sign",
412                {
413                    {RPCResult::Type::STR_AMOUNT, "trusted", "trusted balance (outputs created by the wallet or confirmed outputs)"},
414                    {RPCResult::Type::STR_AMOUNT, "untrusted_pending", "untrusted pending balance (outputs created by others that are in the mempool)"},
415                    {RPCResult::Type::STR_AMOUNT, "immature", "balance from immature coinbase outputs"},
416                    {RPCResult::Type::STR_AMOUNT, "nonmempool", "sum of coins that are spent by transactions not in the mempool (usually an over-estimate due to not accounting for change or spends that conflict with each other)"},
417                    {RPCResult::Type::STR_AMOUNT, "used", /*optional=*/true, "(only present if avoid_reuse is set) balance from coins sent to addresses that were previously spent from (potentially privacy violating)"},
418                }},
419                RESULT_LAST_PROCESSED_BLOCK,
420            }
421            },
422        RPCExamples{
423            HelpExampleCli("getbalances", "") +
424            HelpExampleRpc("getbalances", "")},
425        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
426{
427    const std::shared_ptr<const CWallet> rpc_wallet = GetWalletForJSONRPCRequest(request);
428    if (!rpc_wallet) return UniValue::VNULL;
429    const CWallet& wallet = *rpc_wallet;
430
431    // Make sure the results are valid at least up to the most recent block
432    // the user could have gotten from another RPC command prior to now
433    wallet.BlockUntilSyncedToCurrentChain();
434
435    LOCK(wallet.cs_wallet);
436
437    const auto bal = GetBalance(wallet, /*min_depth=*/0, /*avoid_reuse=*/true, /*include_nonmempool=*/true);
438
439    UniValue balances{UniValue::VOBJ};
440    {
441        UniValue balances_mine{UniValue::VOBJ};
442        balances_mine.pushKV("trusted", ValueFromAmount(bal.m_mine_trusted));
443        balances_mine.pushKV("untrusted_pending", ValueFromAmount(bal.m_mine_untrusted_pending));
444        balances_mine.pushKV("immature", ValueFromAmount(bal.m_mine_immature));
445        balances_mine.pushKV("nonmempool", ValueFromAmount(bal.m_mine_nonmempool));
446        if (wallet.IsWalletFlagSet(WALLET_FLAG_AVOID_REUSE)) {
447            balances_mine.pushKV("used", ValueFromAmount(bal.m_mine_used));
448        }
449        balances.pushKV("mine", std::move(balances_mine));
450    }
451    AppendLastProcessedBlock(balances, wallet);
452    return balances;
453},
454    };
455}
456
457RPCMethod listunspent()
458{
459    return RPCMethod{
460        "listunspent",
461        "Returns array of unspent transaction outputs\n"
462                "with between minconf and maxconf (inclusive) confirmations.\n"
463                "Optionally filter to only include txouts paid to specified addresses.\n",
464                {
465                    {"minconf", RPCArg::Type::NUM, RPCArg::Default{1}, "The minimum confirmations to filter"},
466                    {"maxconf", RPCArg::Type::NUM, RPCArg::Default{9999999}, "The maximum confirmations to filter"},
467                    {"addresses", RPCArg::Type::ARR, RPCArg::Default{UniValue::VARR}, "The bitcoin addresses to filter",
468                        {
469                            {"address", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "bitcoin address"},
470                        },
471                    },
472                    {"include_unsafe", RPCArg::Type::BOOL, RPCArg::Default{true}, "Include outputs that are not safe to spend\n"
473                              "See description of \"safe\" attribute below."},
474                    {"query_options", RPCArg::Type::OBJ_NAMED_PARAMS, RPCArg::Optional::OMITTED, "",
475                        {
476                            {"minimumAmount", RPCArg::Type::AMOUNT, RPCArg::Default{FormatMoney(0)}, "Minimum value of each UTXO in " + CURRENCY_UNIT + ""},
477                            {"maximumAmount", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"unlimited"}, "Maximum value of each UTXO in " + CURRENCY_UNIT + ""},
478                            {"maximumCount", RPCArg::Type::NUM, RPCArg::DefaultHint{"unlimited"}, "Maximum number of UTXOs"},
479                            {"minimumSumAmount", RPCArg::Type::AMOUNT, RPCArg::DefaultHint{"unlimited"}, "Minimum sum value of all UTXOs in " + CURRENCY_UNIT + ""},
480                            {"include_immature_coinbase", RPCArg::Type::BOOL, RPCArg::Default{false}, "Include immature coinbase UTXOs"}
481                        },
482                        RPCArgOptions{.oneline_description="query_options"}},
483                },
484                RPCResult{
485                    RPCResult::Type::ARR, "", "",
486                    {
487                        {RPCResult::Type::OBJ, "", "",
488                        {
489                            {RPCResult::Type::STR_HEX, "txid", "the transaction id"},
490                            {RPCResult::Type::NUM, "vout", "the vout value"},
491                            {RPCResult::Type::STR, "address", /*optional=*/true, "the bitcoin address"},
492                            {RPCResult::Type::STR, "label", /*optional=*/true, "The associated label, or \"\" for the default label"},
493                            {RPCResult::Type::STR_HEX, "scriptPubKey", "the output script"},
494                            {RPCResult::Type::STR_AMOUNT, "amount", "the transaction output amount in " + CURRENCY_UNIT},
495                            {RPCResult::Type::NUM, "confirmations", "The number of confirmations"},
496                            {RPCResult::Type::NUM, "ancestorcount", /*optional=*/true, "The number of in-mempool ancestor transactions, including this one (if transaction is in the mempool)"},
497                            {RPCResult::Type::NUM, "ancestorsize", /*optional=*/true, "The virtual transaction size of in-mempool ancestors, including this one (if transaction is in the mempool)"},
498                            {RPCResult::Type::NUM, "ancestorfees", /*optional=*/true, "The total fees of in-mempool ancestors (including this one) with fee deltas used for mining priority in " + CURRENCY_ATOM + " (if transaction is in the mempool)"},
499                            {RPCResult::Type::STR_HEX, "redeemScript", /*optional=*/true, "The redeem script if the output script is P2SH"},
500                            {RPCResult::Type::STR, "witnessScript", /*optional=*/true, "witness script if the output script is P2WSH or P2SH-P2WSH"},