Blockchain information through RPC

2251}
2252
2253namespace {
2254//! Search for a given set of pubkey scripts
2255bool FindScriptPubKey(std::atomic<int>& scan_progress, const std::atomic<bool>& should_abort, int64_t& count, CCoinsViewCursor* cursor, const std::set<CScript>& needles, std::map<COutPoint, Coin>& out_results, std::function<void()>& interruption_point)
2256{
2257    scan_progress = 0;
2258    count = 0;
2259    while (cursor->Valid()) {
2260        COutPoint key;
2261        Coin coin;
2262        if (!cursor->GetKey(key) || !cursor->GetValue(coin)) return false;
2263        if (++count % 8192 == 0) {
2264            interruption_point();
2265            if (should_abort) {
2266                // allow to abort the scan via the abort reference
2267                return false;
2268            }
2269        }
2270        if (count % 256 == 0) {
2271            // update progress reference every 256 item
2272            uint32_t high = 0x100 * *UCharCast(key.hash.begin()) + *(UCharCast(key.hash.begin()) + 1);
2273            scan_progress = (int)(high * 100.0 / 65536.0 + 0.5);
2274        }
2275        if (needles.contains(coin.out.scriptPubKey)) {
2276            out_results.emplace(key, coin);
2277        }
2278        cursor->Next();
2279    }
2280    scan_progress = 100;
2281    return true;
2282}
2283} // namespace
2284
2285/** RAII object to prevent concurrency issue when scanning the txout set */
2286static std::atomic<int> g_scan_progress;
2287static std::atomic<bool> g_scan_in_progress;
2288static std::atomic<bool> g_should_abort_scan;
2289class CoinsViewScanReserver
2290{
2291private:
2292    bool m_could_reserve{false};
2293public:
2294    explicit CoinsViewScanReserver() = default;
2295
2296    bool reserve() {
2297        CHECK_NONFATAL(!m_could_reserve);
2298        if (g_scan_in_progress.exchange(true)) {
2299            return false;
2300        }
2301        CHECK_NONFATAL(g_scan_progress == 0);
2302        m_could_reserve = true;
2303        return true;
2304    }
2305
2306    ~CoinsViewScanReserver() {
2307        if (m_could_reserve) {
2308            g_scan_in_progress = false;
2309            g_scan_progress = 0;
2310        }
2311    }
2312};
2313
2314static const auto scan_action_arg_desc = RPCArg{
2315    "action", RPCArg::Type::STR, RPCArg::Optional::NO, "The action to execute\n"
2316        "\"start\" for starting a scan\n"
2317        "\"abort\" for aborting the current scan (returns true when abort was successful)\n"
2318        "\"status\" for progress report (in %) of the current scan"
2319};
2320
2321static const auto output_descriptor_obj = RPCArg{
2322    "", RPCArg::Type::OBJ, RPCArg::Optional::OMITTED, "An object with output descriptor and metadata",
2323    {
2324        {"desc", RPCArg::Type::STR, RPCArg::Optional::NO, "An output descriptor"},
2325        {"range", RPCArg::Type::RANGE, RPCArg::Default{1000}, "The range of HD chain indexes to explore (either end or [begin,end])"},
2326    }
2327};
2328
2329static const auto scan_objects_arg_desc = RPCArg{
2330    "scanobjects", RPCArg::Type::ARR, RPCArg::Optional::OMITTED, "Array of scan objects. Required for \"start\" action\n"
2331        "Every scan object is either a string descriptor or an object:",
2332    {
2333        {"descriptor", RPCArg::Type::STR, RPCArg::Optional::OMITTED, "An output descriptor"},
2334        output_descriptor_obj,
2335    },
2336    RPCArgOptions{.oneline_description="[scanobjects,...]"},
2337};
2338
2339static const auto scan_result_abort = RPCResult{
2340    "when action=='abort'", RPCResult::Type::BOOL, "success",
2341    "True if scan will be aborted (not necessarily before this RPC returns), or false if there is no scan to abort"
2342};
2343static const auto scan_result_status_none = RPCResult{
2344    "when action=='status' and no scan is in progress - possibly already completed", RPCResult::Type::NONE, "", ""
2345};
2346static const auto scan_result_status_some = RPCResult{
2347    "when action=='status' and a scan is currently in progress", RPCResult::Type::OBJ, "", "",
2348    {{RPCResult::Type::NUM, "progress", "Approximate percent complete"},}
2349};
2350
2351
2352static RPCMethod scantxoutset()
2353{
2354    // raw() descriptor corresponding to mainnet address 12cbQLTFMXRnSzktFkuoG3eHoMeFtpTu3S
2355    const std::string EXAMPLE_DESCRIPTOR_RAW = "raw(76a91411b366edfc0a8b66feebae5c2e25a7b6a5d1cf3188ac)#fm24fxxy";
2356
2357    return RPCMethod{
2358        "scantxoutset",
2359        "Scans the unspent transaction output set for entries that match certain output descriptors.\n"
2360        "Examples of output descriptors are:\n"
2361        "    addr(<address>)                      Outputs whose output script corresponds to the specified address (does not include P2PK)\n"
2362        "    raw(<hex script>)                    Outputs whose output script equals the specified hex-encoded bytes\n"
2363        "    combo(<pubkey>)                      P2PK, P2PKH, P2WPKH, and P2SH-P2WPKH outputs for the given pubkey\n"
2364        "    pkh(<pubkey>)                        P2PKH outputs for the given pubkey\n"
2365        "    sh(multi(<n>,<pubkey>,<pubkey>,...)) P2SH-multisig outputs for the given threshold and pubkeys\n"
2366        "    tr(<pubkey>)                         P2TR\n"
2367        "    tr(<pubkey>,{pk(<pubkey>)})          P2TR with single fallback pubkey in tapscript\n"
2368        "    rawtr(<pubkey>)                      P2TR with the specified key as output key rather than inner\n"
2369        "    wsh(and_v(v:pk(<pubkey>),after(2)))  P2WSH miniscript with mandatory pubkey and a timelock\n"
2370        "\nIn the above, <pubkey> either refers to a fixed public key in hexadecimal notation, or to an xpub/xprv optionally followed by one\n"
2371        "or more path elements separated by \"/\", and optionally ending in \"/*\" (unhardened), or \"/*'\" or \"/*h\" (hardened) to specify all\n"
2372        "unhardened or hardened child keys.\n"
2373        "In the latter case, a range needs to be specified by below if different from 1000.\n"
2374        "For more information on output descriptors, see the documentation in the doc/descriptors.md file.\n",
2375        {
2376            scan_action_arg_desc,
2377            scan_objects_arg_desc,
2378        },
2379        {
2380            RPCResult{"when action=='start'; only returns after scan completes", RPCResult::Type::OBJ, "", "", {
2381                {RPCResult::Type::BOOL, "success", "Whether the scan was completed"},
2382                {RPCResult::Type::NUM, "txouts", "The number of unspent transaction outputs scanned"},
2383                {RPCResult::Type::NUM, "height", "The block height at which the scan was done"},
2384                {RPCResult::Type::STR_HEX, "bestblock", "The hash of the block at the tip of the chain"},
2385                {RPCResult::Type::ARR, "unspents", "",
2386                {
2387                    {RPCResult::Type::OBJ, "", "",
2388                    {
2389                        {RPCResult::Type::STR_HEX, "txid", "The transaction id"},
2390                        {RPCResult::Type::NUM, "vout", "The vout value"},
2391                        {RPCResult::Type::STR_HEX, "scriptPubKey", "The output script"},
2392                        {RPCResult::Type::STR, "desc", "A specialized descriptor for the matched output script"},
2393                        {RPCResult::Type::STR_AMOUNT, "amount", "The total amount in " + CURRENCY_UNIT + " of the unspent output"},
2394                        {RPCResult::Type::BOOL, "coinbase", "Whether this is a coinbase output"},
2395                        {RPCResult::Type::NUM, "height", "Height of the unspent transaction output"},
2396                        {RPCResult::Type::STR_HEX, "blockhash", "Blockhash of the unspent transaction output"},
2397                        {RPCResult::Type::NUM, "confirmations", "Number of confirmations of the unspent transaction output when the scan was done"},
2398                    }},
2399                }},
2400                {RPCResult::Type::STR_AMOUNT, "total_amount", "The total amount of all found unspent outputs in " + CURRENCY_UNIT},
2401            }},
2402            scan_result_abort,
2403            scan_result_status_some,
2404            scan_result_status_none,
2405        },
2406        RPCExamples{
2407            HelpExampleCli("scantxoutset", "start \'[\"" + EXAMPLE_DESCRIPTOR_RAW + "\"]\'") +
2408            HelpExampleCli("scantxoutset", "status") +
2409            HelpExampleCli("scantxoutset", "abort") +
2410            HelpExampleRpc("scantxoutset", "\"start\", [\"" + EXAMPLE_DESCRIPTOR_RAW + "\"]") +
2411            HelpExampleRpc("scantxoutset", "\"status\"") +
2412            HelpExampleRpc("scantxoutset", "\"abort\"")
2413        },
2414        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
2415{
2416    UniValue result(UniValue::VOBJ);
2417    const auto action{self.Arg<std::string_view>("action")};
2418    if (action == "status") {
2419        CoinsViewScanReserver reserver;
2420        if (reserver.reserve()) {
2421            // no scan in progress
2422            return UniValue::VNULL;
2423        }
2424        result.pushKV("progress", g_scan_progress.load());
2425        return result;
2426    } else if (action == "abort") {
2427        CoinsViewScanReserver reserver;
2428        if (reserver.reserve()) {
2429            // reserve was possible which means no scan was running
2430            return false;
2431        }
2432        // set the abort flag
2433        g_should_abort_scan = true;
2434        return true;
2435    } else if (action == "start") {
2436        CoinsViewScanReserver reserver;
2437        if (!reserver.reserve()) {
2438            throw JSONRPCError(RPC_INVALID_PARAMETER, "Scan already in progress, use action \"abort\" or \"status\"");
2439        }
2440
2441        const UniValue* scanobjects = self.MaybeArg<UniValue>("scanobjects");
2442        if (!scanobjects) {
2443            throw JSONRPCError(RPC_MISC_ERROR, "scanobjects argument is required for the start action");
2444        }
2445
2446        std::set<CScript> needles;
2447        std::map<CScript, std::string> descriptors;
2448        CAmount total_in = 0;
2449
2450        // loop through the scan objects
2451        for (const UniValue& scanobject : scanobjects->get_array().getValues()) {
2452            FlatSigningProvider provider;
2453            auto scripts = EvalDescriptorStringOrObject(scanobject, provider);
2454            for (CScript& script : scripts) {
2455                std::string inferred = InferDescriptor(script, provider)->ToString();
2456                needles.emplace(script);
2457                descriptors.emplace(std::move(script), std::move(inferred));
2458            }
2459        }
2460
2461        // Scan the unspent transaction output set for inputs
2462        UniValue unspents(UniValue::VARR);
2463        std::vector<CTxOut> input_txos;
2464        std::map<COutPoint, Coin> coins;
2465        g_should_abort_scan = false;
2466        int64_t count = 0;
2467        std::unique_ptr<CCoinsViewCursor> pcursor;
2468        const CBlockIndex* tip;
2469        NodeContext& node = EnsureAnyNodeContext(request.context);
2470        {
2471            ChainstateManager& chainman = EnsureChainman(node);
2472            LOCK(cs_main);
2473            Chainstate& active_chainstate = chainman.ActiveChainstate();
2474            active_chainstate.ForceFlushStateToDisk(/*wipe_cache=*/false);
2475            pcursor = active_chainstate.CoinsDB().Cursor();
2476            tip = CHECK_NONFATAL(active_chainstate.m_chain.Tip());
2477        }
2478        bool res = FindScriptPubKey(g_scan_progress, g_should_abort_scan, count, pcursor.get(), needles, coins, node.rpc_interruption_point);
2479        result.pushKV("success", res);
2480        result.pushKV("txouts", count);
2481        result.pushKV("height", tip->nHeight);
2482        result.pushKV("bestblock", tip->GetBlockHash().GetHex());
2483
2484        for (const auto& it : coins) {
2485            const COutPoint& outpoint = it.first;
2486            const Coin& coin = it.second;
2487            const CTxOut& txo = coin.out;
2488            const CBlockIndex& coinb_block{*CHECK_NONFATAL(tip->GetAncestor(coin.nHeight))};
2489            input_txos.push_back(txo);
2490            total_in += txo.nValue;
2491
2492            UniValue unspent(UniValue::VOBJ);
2493            unspent.pushKV("txid", outpoint.hash.GetHex());
2494            unspent.pushKV("vout", outpoint.n);
2495            unspent.pushKV("scriptPubKey", HexStr(txo.scriptPubKey));
2496            unspent.pushKV("desc", descriptors[txo.scriptPubKey]);
2497            unspent.pushKV("amount", ValueFromAmount(txo.nValue));
2498            unspent.pushKV("coinbase", coin.IsCoinBase());
2499            unspent.pushKV("height", coin.nHeight);
2500            unspent.pushKV("blockhash", coinb_block.GetBlockHash().GetHex());