Blockchain information through RPC

3001        "Retrieve a BIP 157 content filter for a particular block.\n",
3002                {
3003                    {"blockhash", RPCArg::Type::STR_HEX, RPCArg::Optional::NO, "The hash of the block"},
3004                    {"filtertype", RPCArg::Type::STR, RPCArg::Default{BlockFilterTypeName(BlockFilterType::BASIC)}, "The type name of the filter"},
3005                },
3006                RPCResult{
3007                    RPCResult::Type::OBJ, "", "",
3008                    {
3009                        {RPCResult::Type::STR_HEX, "filter", "the hex-encoded filter data"},
3010                        {RPCResult::Type::STR_HEX, "header", "the hex-encoded filter header"},
3011                    }},
3012                RPCExamples{
3013                    HelpExampleCli("getblockfilter", "\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\" \"basic\"") +
3014                    HelpExampleRpc("getblockfilter", "\"00000000c937983704a73af28acdec37b049d214adbda81d7e2a3dd146f6ed09\", \"basic\"")
3015                },
3016        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
3017{
3018    uint256 block_hash = ParseHashV(request.params[0], "blockhash");
3019    auto filtertype_name{self.Arg<std::string_view>("filtertype")};
3020
3021    BlockFilterType filtertype;
3022    if (!BlockFilterTypeByName(filtertype_name, filtertype)) {
3023        throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Unknown filtertype");
3024    }
3025
3026    BlockFilterIndex* index = GetBlockFilterIndex(filtertype);
3027    if (!index) {
3028        throw JSONRPCError(RPC_MISC_ERROR, tfm::format("Index is not enabled for filtertype %s", filtertype_name));
3029    }
3030
3031    const CBlockIndex* block_index;
3032    bool block_was_connected;
3033    {
3034        ChainstateManager& chainman = EnsureAnyChainman(request.context);
3035        LOCK(cs_main);
3036        block_index = chainman.m_blockman.LookupBlockIndex(block_hash);
3037        if (!block_index) {
3038            throw JSONRPCError(RPC_INVALID_ADDRESS_OR_KEY, "Block not found");
3039        }
3040        block_was_connected = block_index->IsValid(BLOCK_VALID_SCRIPTS);
3041    }
3042
3043    bool index_ready = index->BlockUntilSyncedToCurrentChain();
3044
3045    BlockFilter filter;
3046    uint256 filter_header;
3047    if (!index->LookupFilter(block_index, filter) ||
3048        !index->LookupFilterHeader(block_index, filter_header)) {
3049        int err_code;
3050        std::string errmsg = "Filter not found.";
3051
3052        if (!block_was_connected) {
3053            err_code = RPC_INVALID_ADDRESS_OR_KEY;
3054            errmsg += " Block was not connected to active chain.";
3055        } else if (!index_ready) {
3056            err_code = RPC_MISC_ERROR;
3057            errmsg += " Block filters are still in the process of being indexed.";
3058        } else {
3059            err_code = RPC_INTERNAL_ERROR;
3060            errmsg += " This error is unexpected and indicates index corruption.";
3061        }
3062
3063        throw JSONRPCError(err_code, errmsg);
3064    }
3065
3066    UniValue ret(UniValue::VOBJ);
3067    ret.pushKV("filter", HexStr(filter.GetEncodedFilter()));
3068    ret.pushKV("header", filter_header.GetHex());
3069    return ret;
3070},
3071    };
3072}
3073
3074/**
3075 * RAII class that registers a prune lock in its constructor to prevent
3076 * block data from being pruned, and removes it in its destructor.
3077 */
3078class TemporaryPruneLock
3079{
3080    static constexpr const char* LOCK_NAME{"dumptxoutset-rollback"};
3081    BlockManager& m_blockman;
3082public:
3083    TemporaryPruneLock(BlockManager& blockman, int height) : m_blockman(blockman)
3084    {
3085        LOCK(::cs_main);
3086        m_blockman.UpdatePruneLock(LOCK_NAME, {height});
3087        LogDebug(BCLog::PRUNE, "dumptxoutset: registered prune lock at height %d", height);
3088    }
3089    ~TemporaryPruneLock()
3090    {
3091        LOCK(::cs_main);
3092        m_blockman.DeletePruneLock(LOCK_NAME);
3093        LogDebug(BCLog::PRUNE, "dumptxoutset: released prune lock");
3094    }
3095};
3096
3097/**
3098 * Serialize the UTXO set to a file for loading elsewhere.
3099 *
3100 * @see SnapshotMetadata
3101 */
3102static RPCMethod dumptxoutset()
3103{
3104    return RPCMethod{
3105        "dumptxoutset",
3106        "Write the serialized UTXO set to a file. This can be used in loadtxoutset afterwards if this snapshot height is supported in the chainparams as well.\n"
3107        "This creates a temporary UTXO database when rolling back, keeping the main chain intact. Should the node experience an unclean shutdown the temporary database may need to be removed from the datadir manually.\n"
3108        "For deep rollbacks, make sure to use no RPC timeout (bitcoin-cli -rpcclienttimeout=0) as it may take several minutes.",
3109        {
3110            {"path", RPCArg::Type::STR, RPCArg::Optional::NO, "Path to the output file. If relative, will be prefixed by datadir."},
3111            {"type", RPCArg::Type::STR, RPCArg::Default(""), "The type of snapshot to create. Can be \"latest\" to create a snapshot of the current UTXO set or \"rollback\" to temporarily roll back the state of the node to a historical block before creating the snapshot of a historical UTXO set. This parameter can be omitted if a separate \"rollback\" named parameter is specified indicating the height or hash of a specific historical block. If \"rollback\" is specified and separate \"rollback\" named parameter is not specified, this will roll back to the latest valid snapshot block that can currently be loaded with loadtxoutset."},
3112            {"options", RPCArg::Type::OBJ_NAMED_PARAMS, RPCArg::Optional::OMITTED, "",
3113                {
3114                    {"rollback", RPCArg::Type::NUM, RPCArg::Optional::OMITTED,
3115                        "Height or hash of the block to roll back to before creating the snapshot. Note: The further this number is from the tip, the longer this process will take. Consider setting a higher -rpcclienttimeout value in this case.",
3116                    RPCArgOptions{.skip_type_check = true, .type_str = {"", "string or numeric"}}},
3117                    {"in_memory", RPCArg::Type::BOOL, RPCArg::Default{false}, "If true, the temporary UTXO-set database used during rollback is kept entirely in memory. This can significantly speed up the process but requires sufficient free RAM (over 10 GB on mainnet)."},
3118                },
3119            },
3120        },
3121        RPCResult{
3122            RPCResult::Type::OBJ, "", "",
3123                {
3124                    {RPCResult::Type::NUM, "coins_written", "the number of coins written in the snapshot"},
3125                    {RPCResult::Type::STR_HEX, "base_hash", "the hash of the base of the snapshot"},
3126                    {RPCResult::Type::NUM, "base_height", "the height of the base of the snapshot"},
3127                    {RPCResult::Type::STR, "path", "the absolute path that the snapshot was written to"},
3128                    {RPCResult::Type::STR_HEX, "txoutset_hash", "the hash of the UTXO set contents"},
3129                    {RPCResult::Type::NUM, "nchaintx", "the number of transactions in the chain up to and including the base block"},
3130                }
3131        },
3132        RPCExamples{
3133            HelpExampleCli("-rpcclienttimeout=0 dumptxoutset", "utxo.dat latest") +
3134            HelpExampleCli("-rpcclienttimeout=0 dumptxoutset", "utxo.dat rollback") +
3135            HelpExampleCli("-rpcclienttimeout=0 -named dumptxoutset", R"(utxo.dat rollback=853456)") +
3136            HelpExampleCli("-rpcclienttimeout=0 -named dumptxoutset", R"(utxo.dat rollback=853456 in_memory=true)")
3137        },
3138        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
3139{
3140    NodeContext& node = EnsureAnyNodeContext(request.context);
3141    const CBlockIndex* tip{WITH_LOCK(::cs_main, return node.chainman->ActiveChain().Tip())};
3142    const CBlockIndex* target_index{nullptr};
3143    const auto snapshot_type{self.Arg<std::string_view>("type")};
3144    const UniValue options{request.params[2].isNull() ? UniValue::VOBJ : request.params[2]};
3145    if (options.exists("rollback")) {
3146        if (!snapshot_type.empty() && snapshot_type != "rollback") {
3147            throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("Invalid snapshot type \"%s\" specified with rollback option", snapshot_type));
3148        }
3149        target_index = ParseHashOrHeight(options["rollback"], *node.chainman);
3150    } else if (snapshot_type == "rollback") {
3151        auto snapshot_heights = node.chainman->GetParams().GetAvailableSnapshotHeights();
3152        CHECK_NONFATAL(snapshot_heights.size() > 0);
3153        auto max_height = std::max_element(snapshot_heights.begin(), snapshot_heights.end());
3154        target_index = ParseHashOrHeight(*max_height, *node.chainman);
3155    } else if (snapshot_type == "latest") {
3156        target_index = tip;
3157    } else {
3158        throw JSONRPCError(RPC_INVALID_PARAMETER, strprintf("Invalid snapshot type \"%s\" specified. Please specify \"rollback\" or \"latest\"", snapshot_type));
3159    }
3160
3161    const ArgsManager& args{EnsureAnyArgsman(request.context)};
3162    const fs::path path = fsbridge::AbsPathJoin(args.GetDataDirNet(), fs::u8path(self.Arg<std::string_view>("path")));
3163    const auto path_info{fs::status(path)};
3164    // Write to a temporary path and then move into `path` on completion
3165    // to avoid confusion due to an interruption. If a named pipe passed, write directly to it.
3166    const fs::path temppath = fs::is_fifo(path_info) ? path : path + ".incomplete";
3167
3168    if (fs::exists(path_info) && !fs::is_fifo(path_info)) {
3169        throw JSONRPCError(
3170            RPC_INVALID_PARAMETER,
3171            path.utf8string() + " already exists. If you are sure this is what you want, "
3172            "move it out of the way first");
3173    }
3174
3175    FILE* file{fsbridge::fopen(temppath, "wb")};
3176    AutoFile afile{file};
3177    if (afile.IsNull()) {
3178        throw JSONRPCError(
3179            RPC_INVALID_PARAMETER,
3180            "Couldn't open file " + temppath.utf8string() + " for writing.");
3181    }
3182
3183    UniValue result;
3184    Chainstate& chainstate{node.chainman->ActiveChainstate()};
3185    if (target_index == tip) {
3186        // Dump the txoutset of the current tip
3187        result = CreateUTXOSnapshot(node, chainstate, std::move(afile), path, temppath);
3188    } else {
3189        // Check pruning constraints before attempting rollback and prevent
3190        // pruning of the necessary blocks with a temporary prune lock
3191        std::optional<TemporaryPruneLock> temp_prune_lock;
3192        if (node.chainman->m_blockman.IsPruneMode()) {
3193            LOCK(node.chainman->GetMutex());
3194            const CBlockIndex* current_tip{node.chainman->ActiveChain().Tip()};
3195            const CBlockIndex& first_block{node.chainman->m_blockman.GetFirstBlock(*current_tip, /*status_mask=*/BLOCK_HAVE_MASK)};
3196            if (first_block.nHeight > target_index->nHeight) {
3197                throw JSONRPCError(RPC_MISC_ERROR, "Could not roll back to requested height since necessary block data is already pruned.");
3198            }
3199            temp_prune_lock.emplace(node.chainman->m_blockman, target_index->nHeight);
3200        }
3201
3202        const bool in_memory{options.exists("in_memory") ? options["in_memory"].get_bool() : false};
3203        result = CreateRolledBackUTXOSnapshot(node,
3204                                              chainstate,
3205                                              target_index,
3206                                              std::move(afile),
3207                                              path,
3208                                              temppath,
3209                                              in_memory);
3210    }
3211
3212    if (!fs::is_fifo(path_info)) {
3213        fs::rename(temppath, path);
3214    }
3215
3216    return result;
3217},
3218    };
3219}
3220
3221/**
3222 * RAII class that creates a temporary database directory in its constructor
3223 * and removes it in its destructor.
3224 */
3225class TemporaryUTXODatabase
3226{
3227    fs::path m_path;
3228public:
3229    TemporaryUTXODatabase(const fs::path& path) : m_path(path) {
3230        fs::create_directories(m_path);
3231    }
3232    ~TemporaryUTXODatabase() {
3233        if (!DestroyDB(fs::PathToString(m_path))) {
3234            LogInfo("Failed to clean up temporary UTXO database at %s, please remove it manually.",
3235                    fs::PathToString(m_path));
3236        }
3237    }
3238};
3239
3240UniValue CreateRolledBackUTXOSnapshot(
3241    NodeContext& node,
3242    Chainstate& chainstate,
3243    const CBlockIndex* target,
3244    AutoFile&& afile,
3245    const fs::path& path,
3246    const fs::path& tmppath,
3247    const bool in_memory)
3248{
3249    // Create a temporary leveldb to store the UTXO set that is being rolled back
3250    std::string temp_db_name{strprintf("temp_utxo_%d", target->nHeight)};