Querying and submitting pending transactions

1251        },
1252        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
1253{
1254    const ArgsManager& args{EnsureAnyArgsman(request.context)};
1255    const CTxMemPool& mempool = EnsureAnyMemPool(request.context);
1256
1257    if (!mempool.GetLoadTried()) {
1258        throw JSONRPCError(RPC_MISC_ERROR, "The mempool was not loaded yet");
1259    }
1260
1261    const fs::path& dump_path = MempoolPath(args);
1262
1263    if (!DumpMempool(mempool, dump_path)) {
1264        throw JSONRPCError(RPC_MISC_ERROR, "Unable to dump mempool to disk");
1265    }
1266
1267    UniValue ret(UniValue::VOBJ);
1268    ret.pushKV("filename", dump_path.utf8string());
1269
1270    return ret;
1271},
1272    };
1273}
1274
1275static std::vector<RPCResult> OrphanDescription()
1276{
1277    return {
1278        RPCResult{RPCResult::Type::STR_HEX, "txid", "The transaction hash in hex"},
1279        RPCResult{RPCResult::Type::STR_HEX, "wtxid", "The transaction witness hash in hex"},
1280        RPCResult{RPCResult::Type::NUM, "bytes", "The serialized transaction size in bytes"},
1281        RPCResult{RPCResult::Type::NUM, "vsize", "(DEPRECATED) use vsize_bip141 instead. The virtual transaction size as defined in BIP 141. This is different from actual serialized size for witness transactions as witness data is discounted."},
1282        RPCResult{RPCResult::Type::NUM, "vsize_bip141", "The virtual transaction size as defined in BIP 141. This is different from actual serialized size for witness transactions as witness data is discounted."},
1283        RPCResult{RPCResult::Type::NUM, "weight", "The transaction weight as defined in BIP 141."},
1284        RPCResult{RPCResult::Type::ARR, "from", "",
1285        {
1286            RPCResult{RPCResult::Type::NUM, "peer_id", "Peer ID"},
1287        }},
1288    };
1289}
1290
1291static UniValue OrphanToJSON(const node::TxOrphanage::OrphanInfo& orphan)
1292{
1293    UniValue o(UniValue::VOBJ);
1294    o.pushKV("txid", orphan.tx->GetHash().ToString());
1295    o.pushKV("wtxid", orphan.tx->GetWitnessHash().ToString());
1296    o.pushKV("bytes", orphan.tx->ComputeTotalSize());
1297    o.pushKV("vsize", GetVirtualTransactionSize(*orphan.tx));
1298    o.pushKV("vsize_bip141", GetVirtualTransactionSize(*orphan.tx));
1299    o.pushKV("weight", GetTransactionWeight(*orphan.tx));
1300    UniValue from(UniValue::VARR);
1301    for (const auto fromPeer: orphan.announcers) {
1302        from.push_back(fromPeer);
1303    }
1304    o.pushKV("from", from);
1305    return o;
1306}
1307
1308static RPCMethod getorphantxs()
1309{
1310    return RPCMethod{
1311        "getorphantxs",
1312        "Shows transactions in the tx orphanage.\n"
1313        "\nEXPERIMENTAL warning: this call may be changed in future releases.\n",
1314        {
1315            {"verbosity", RPCArg::Type::NUM, RPCArg::Default{0}, "0 for an array of txids (may contain duplicates), 1 for an array of objects with tx details, and 2 for details from (1) and tx hex",
1316             RPCArgOptions{.skip_type_check = true}},
1317        },
1318        {
1319            RPCResult{"for verbose = 0",
1320                RPCResult::Type::ARR, "", "",
1321                {
1322                    {RPCResult::Type::STR_HEX, "txid", "The transaction hash in hex"},
1323                }},
1324            RPCResult{"for verbose = 1",
1325                RPCResult::Type::ARR, "", "",
1326                {
1327                    {RPCResult::Type::OBJ, "", "", OrphanDescription()},
1328                }},
1329            RPCResult{"for verbose = 2",
1330                RPCResult::Type::ARR, "", "",
1331                {
1332                    {RPCResult::Type::OBJ, "", "",
1333                        Cat<std::vector<RPCResult>>(
1334                            OrphanDescription(),
1335                            {{RPCResult::Type::STR_HEX, "hex", "The serialized, hex-encoded transaction data"}}
1336                        )
1337                    },
1338                }},
1339        },
1340        RPCExamples{
1341            HelpExampleCli("getorphantxs", "2")
1342            + HelpExampleRpc("getorphantxs", "2")
1343        },
1344        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
1345        {
1346            const NodeContext& node = EnsureAnyNodeContext(request.context);
1347            PeerManager& peerman = EnsurePeerman(node);
1348            std::vector<node::TxOrphanage::OrphanInfo> orphanage = peerman.GetOrphanTransactions();
1349
1350            int verbosity{ParseVerbosity(request.params[0], /*default_verbosity=*/0, /*allow_bool=*/false)};
1351
1352            UniValue ret(UniValue::VARR);
1353
1354            if (verbosity == 0) {
1355                for (auto const& orphan : orphanage) {
1356                    ret.push_back(orphan.tx->GetHash().ToString());
1357                }
1358            } else if (verbosity == 1) {
1359                for (auto const& orphan : orphanage) {
1360                    ret.push_back(OrphanToJSON(orphan));
1361                }
1362            } else if (verbosity == 2) {
1363                for (auto const& orphan : orphanage) {
1364                    UniValue o{OrphanToJSON(orphan)};
1365                    o.pushKV("hex", EncodeHexTx(*orphan.tx));
1366                    ret.push_back(o);
1367                }
1368            } else {
1369                throw JSONRPCError(RPC_INVALID_PARAMETER, "Invalid verbosity value " + ToString(verbosity));
1370            }
1371
1372            return ret;
1373        },
1374    };
1375}
1376
1377static RPCMethod submitpackage()
1378{
1379    return RPCMethod{"submitpackage",
1380        "Submit a package of raw transactions (serialized, hex-encoded) to local node.\n"
1381        "The package will be validated according to consensus and mempool policy rules. If any transaction passes, it will be accepted to mempool.\n"
1382        "This RPC is experimental and the interface may be unstable. Refer to doc/policy/packages.md for documentation on package policies.\n"
1383        "Warning: successful submission does not mean the transactions will propagate throughout the network.\n"
1384        ,
1385        {
1386            {"package", RPCArg::Type::ARR, RPCArg::Optional::NO, "An array of raw transactions.\n"
1387                "The package must consist of a transaction with (some, all, or none of) its unconfirmed parents. A single transaction is permitted.\n"
1388                "None of the parents may depend on each other. Parents that are already in mempool do not need to be present in the package.\n"
1389                "The package must be topologically sorted, with the child being the last element in the array if there are multiple elements.",
1390                {
1391                    {"rawtx", RPCArg::Type::STR_HEX, RPCArg::Optional::OMITTED, ""},
1392                },
1393            },
1394            {"maxfeerate", RPCArg::Type::AMOUNT, RPCArg::Default{FormatMoney(DEFAULT_MAX_RAW_TX_FEE_RATE.GetFeePerK())},
1395             "Reject transactions whose fee rate is higher than the specified value, expressed in " + CURRENCY_UNIT +
1396                 "/kvB.\nFee rates larger than 1BTC/kvB are rejected.\nSet to 0 to accept any fee rate."},
1397            {"maxburnamount", RPCArg::Type::AMOUNT, RPCArg::Default{FormatMoney(DEFAULT_MAX_BURN_AMOUNT)},
1398             "Reject transactions with provably unspendable outputs (e.g. 'datacarrier' outputs that use the OP_RETURN opcode) greater than the specified value, expressed in " + CURRENCY_UNIT + ".\n"
1399             "If burning funds through unspendable outputs is desired, increase this value.\n"
1400             "This check is based on heuristics and does not guarantee spendability of outputs.\n"
1401            },
1402        },
1403        RPCResult{
1404            RPCResult::Type::OBJ, "", "",
1405            {
1406                {RPCResult::Type::STR, "package_msg", "The transaction package result message. \"success\" indicates all transactions were accepted into or are already in the mempool."},
1407                {RPCResult::Type::OBJ_DYN, "tx-results", "The transaction results keyed by wtxid. An entry is returned for every submitted wtxid.",
1408                {
1409                    {RPCResult::Type::OBJ, "wtxid", "transaction wtxid", {
1410                        {RPCResult::Type::STR_HEX, "txid", "The transaction hash in hex"},
1411                        {RPCResult::Type::STR_HEX, "other-wtxid", /*optional=*/true, "The wtxid of a different transaction with the same txid but different witness found in the mempool. This means the submitted transaction was ignored."},
1412                        {RPCResult::Type::NUM, "vsize_adjusted", /*optional=*/true, "Maximum of sigop-adjusted size (-bytespersigop) and virtual transaction size as defined in BIP 141."},
1413                        {RPCResult::Type::NUM, "vsize", /*optional=*/true, "(DEPRECATED) Was previously erroneously described as the BIP 141 vsize, but is actually sigops-adjusted vsize.\n"
1414                                                                    "Use vsize_bip141 to actually get that behavior or switch to the explicit vsize_adjusted for retained behavior."},
1415                        {RPCResult::Type::NUM, "vsize_bip141", /*optional=*/true, "Virtual transaction size as defined in BIP 141."},
1416                        {RPCResult::Type::OBJ, "fees", /*optional=*/true, "Transaction fees", {
1417                            {RPCResult::Type::STR_AMOUNT, "base", "transaction fee in " + CURRENCY_UNIT},
1418                            {RPCResult::Type::STR_AMOUNT, "effective-feerate", /*optional=*/true, "if the transaction was not already in the mempool, the effective feerate in " + CURRENCY_UNIT + " per KvB. For example, the package feerate and/or feerate with modified fees from prioritisetransaction."},
1419                            {RPCResult::Type::ARR, "effective-includes", /*optional=*/true, "if effective-feerate is provided, the wtxids of the transactions whose fees and vsizes are included in effective-feerate.",
1420                                {{RPCResult::Type::STR_HEX, "", "transaction wtxid in hex"},
1421                            }},
1422                        }},
1423                        {RPCResult::Type::STR, "error", /*optional=*/true, "Error string if rejected from mempool, or \"package-not-validated\" when the package aborts before any per-tx processing."},
1424                    }}
1425                }},
1426                {RPCResult::Type::ARR, "replaced-transactions", /*optional=*/true, "List of txids of replaced transactions",
1427                {
1428                    {RPCResult::Type::STR_HEX, "", "The transaction id"},
1429                }},
1430            },
1431        },
1432        RPCExamples{
1433            HelpExampleRpc("submitpackage", R"(["raw-parent-tx-1", "raw-parent-tx-2", "raw-child-tx"])") +
1434            HelpExampleCli("submitpackage", R"('["raw-tx-without-unconfirmed-parents"]')")
1435        },
1436        [](const RPCMethod& self, const JSONRPCRequest& request) -> UniValue
1437        {
1438            const UniValue raw_transactions = request.params[0].get_array();
1439            if (raw_transactions.empty() || raw_transactions.size() > MAX_PACKAGE_COUNT) {
1440                throw JSONRPCError(RPC_INVALID_PARAMETER,
1441                                   "Array must contain between 1 and " + ToString(MAX_PACKAGE_COUNT) + " transactions.");
1442            }
1443
1444            // Fee check needs to be run with chainstate and package context
1445            const CFeeRate max_raw_tx_fee_rate{ParseFeeRate(self.Arg<UniValue>("maxfeerate"))};
1446            std::optional<CFeeRate> client_maxfeerate{max_raw_tx_fee_rate};
1447            // 0-value is special; it's mapped to no sanity check
1448            if (max_raw_tx_fee_rate == CFeeRate(0)) {
1449                client_maxfeerate = std::nullopt;
1450            }
1451
1452            // Burn sanity check is run with no context
1453            const CAmount max_burn_amount = request.params[2].isNull() ? 0 : AmountFromValue(request.params[2]);
1454
1455            std::vector<CTransactionRef> txns;
1456            txns.reserve(raw_transactions.size());
1457            for (const auto& rawtx : raw_transactions.getValues()) {
1458                CMutableTransaction mtx;
1459                if (!DecodeHexTx(mtx, rawtx.get_str())) {
1460                    throw JSONRPCError(RPC_DESERIALIZATION_ERROR,
1461                                       "TX decode failed: " + rawtx.get_str() + " Make sure the tx has at least one input.");
1462                }
1463
1464                for (const auto& out : mtx.vout) {
1465                    if((out.scriptPubKey.IsUnspendable() || !out.scriptPubKey.HasValidOps()) && out.nValue > max_burn_amount) {
1466                        throw JSONRPCTransactionError(TransactionError::MAX_BURN_EXCEEDED);
1467                    }
1468                }
1469
1470                txns.emplace_back(MakeTransactionRef(std::move(mtx)));
1471            }
1472            CHECK_NONFATAL(!txns.empty());
1473            if (txns.size() > 1 && !IsChildWithParentsTree(txns)) {
1474                throw JSONRPCTransactionError(TransactionError::INVALID_PACKAGE, "package topology disallowed. not child-with-parents or parents depend on each other.");
1475            }
1476
1477            NodeContext& node = EnsureAnyNodeContext(request.context);
1478            CTxMemPool& mempool = EnsureMemPool(node);
1479            Chainstate& chainstate = EnsureChainman(node).ActiveChainstate();
1480            const auto package_result = WITH_LOCK(::cs_main, return ProcessNewPackage(chainstate, mempool, txns, /*test_accept=*/ false, client_maxfeerate));
1481
1482            std::string package_msg = "success";
1483
1484            // First catch package-wide errors, continue if we can
1485            switch(package_result.m_state.GetResult()) {
1486                case PackageValidationResult::PCKG_RESULT_UNSET:
1487                {
1488                    // Belt-and-suspenders check; everything should be successful here
1489                    CHECK_NONFATAL(package_result.m_tx_results.size() == txns.size());
1490                    for (const auto& tx : txns) {
1491                        CHECK_NONFATAL(mempool.exists(tx->GetHash()));
1492                    }
1493                    break;
1494                }
1495                case PackageValidationResult::PCKG_MEMPOOL_ERROR:
1496                {
1497                    // This only happens with internal bug; user should stop and report
1498                    throw JSONRPCTransactionError(TransactionError::MEMPOOL_ERROR,
1499                        package_result.m_state.GetRejectReason());
1500                }