AccountTx.cpp

#include <xrpld/app/ledger/LedgerMaster.h>
#include <xrpld/app/main/Application.h>
#include <xrpld/app/misc/DeliverMax.h>
#include <xrpld/app/misc/Transaction.h>
#include <xrpld/app/rdb/backend/SQLiteDatabase.h>
#include <xrpld/rpc/Context.h>
#include <xrpld/rpc/Role.h>
#include <xrpld/rpc/Status.h>
#include <xrpld/rpc/detail/RPCHelpers.h>
#include <xrpld/rpc/detail/RPCLedgerHelpers.h>
#include <xrpld/rpc/detail/SyntheticFields.h>
#include <xrpld/rpc/detail/Tuning.h>
 
#include <xrpl/basics/Log.h>
#include <xrpl/basics/base_uint.h>
#include <xrpl/basics/chrono.h>
#include <xrpl/basics/strHex.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/json/json_value.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/ErrorCodes.h>
#include <xrpl/protocol/RPCErr.h>
#include <xrpl/protocol/RippleLedgerHash.h>
#include <xrpl/protocol/jss.h>
#include <xrpl/rdb/RelationalDatabase.h>
#include <xrpl/resource/Fees.h>
 
#include <rpcspec/Ledger.hpp>
 
#include <cstdint>
#include <expected>
#include <memory>
#include <optional>
#include <type_traits>
#include <utility>
#include <variant>
 
namespace xrpl {
 
static std::expected<DelegateFilter, json::Value>
parseDelegateFilter(json::Value const& delegateNode)
{
    if (!delegateNode.isObject())
        return std::unexpected(rpc::invalidFieldError(jss::delegate));
 
    if (!delegateNode.isMember(jss::delegate_filter) ||
        !delegateNode[jss::delegate_filter].isString())
        return std::unexpected(rpc::invalidFieldError(jss::delegate_filter));
 
    auto const& delegateFilterStr = delegateNode[jss::delegate_filter].asString();
 
    auto typeResult = [&] -> std::expected<DelegateType, json::Value> {
        if (delegateFilterStr == "actor")
            return DelegateType::Actor;
 
        if (delegateFilterStr == "authorizer")
            return DelegateType::Authorizer;
 
        return std::unexpected(rpc::invalidFieldError(jss::delegate_filter));
    }();
 
    if (!typeResult)
        return std::unexpected(typeResult.error());
 
    DelegateType const type = *typeResult;
 
    std::optional<AccountID> counterparty;
    if (delegateNode.isMember(jss::counter_party))
    {
        if (!delegateNode[jss::counter_party].isString())
            return std::unexpected(rpc::invalidFieldError(jss::counter_party));
 
        counterparty = parseBase58<AccountID>(delegateNode[jss::counter_party].asString());
 
        if (!counterparty)
            return std::unexpected(rpcError(RpcActMalformed));
    }
 
    return DelegateFilter{.type = type, .counterparty = counterparty};
}
 
using TxnsData = RelationalDatabase::AccountTxs;
using TxnsDataBinary = RelationalDatabase::MetaTxsList;
using TxnDataBinary = RelationalDatabase::TxnMetaLedgerType;
using AccountTxResult = RelationalDatabase::AccountTxResult;
 
// Moved here from RelationalDatabase, where nothing but this handler used them, so that
// libxrpl does not depend on the spec for LedgerShortcut. Temporary: the spec's
// account_tx Input replaces both once account_tx is migrated to the spec.
using LedgerSpecifier =
    std::variant<LedgerRange, ::rpc::spec::LedgerShortcut, std::uint32_t, uint256>;
 
struct AccountTxArgs
{
    AccountID account;
    std::optional<LedgerSpecifier> ledger;
    bool binary = false;
    bool forward = false;
    uint32_t limit = 0;
    std::optional<RelationalDatabase::AccountTxMarker> marker;
    std::optional<DelegateFilter> delegate;
};
 
// parses args into a ledger specifier, or returns a Json object on error
std::variant<std::optional<LedgerSpecifier>, json::Value>
parseLedgerArgs(rpc::Context& context, json::Value const& params)
{
    json::Value response;
    // if ledger_index_min or max is specified, then ledger_hash or ledger_index
    // should not be specified. Error out if it is
    if (context.apiVersion > 1u)
    {
        if ((params.isMember(jss::ledger_index_min) || params.isMember(jss::ledger_index_max)) &&
            (params.isMember(jss::ledger_hash) || params.isMember(jss::ledger_index)))
        {
            rpc::Status const status{RpcInvalidParams, "invalidParams"};
            status.inject(response);
            return response;
        }
    }
    if (params.isMember(jss::ledger_index_min) || params.isMember(jss::ledger_index_max))
    {
        uint32_t const min =
            params.isMember(jss::ledger_index_min) && params[jss::ledger_index_min].asInt() >= 0
            ? params[jss::ledger_index_min].asUInt()
            : 0;
        uint32_t const max =
            params.isMember(jss::ledger_index_max) && params[jss::ledger_index_max].asInt() >= 0
            ? params[jss::ledger_index_max].asUInt()
            : UINT32_MAX;
 
        return LedgerRange{.min = min, .max = max};
    }
    if (params.isMember(jss::ledger_hash))
    {
        auto& hashValue = params[jss::ledger_hash];
        if (!hashValue.isString())
        {
            rpc::Status const status{RpcInvalidParams, "ledgerHashNotString"};
            status.inject(response);
            return response;
        }
 
        LedgerHash hash;
        if (!hash.parseHex(hashValue.asString()))
        {
            rpc::Status const status{RpcInvalidParams, "ledgerHashMalformed"};
            status.inject(response);
            return response;
        }
        return hash;
    }
    if (params.isMember(jss::ledger_index))
    {
        LedgerSpecifier ledger;
        if (params[jss::ledger_index].isNumeric())
        {
            ledger = params[jss::ledger_index].asUInt();
        }
        else
        {
            std::string const ledgerStr = params[jss::ledger_index].asString();
 
            if (ledgerStr == "current" || ledgerStr.empty())
            {
                ledger = ::rpc::spec::LedgerShortcut::Current;
            }
            else if (ledgerStr == "closed")
            {
                ledger = ::rpc::spec::LedgerShortcut::Closed;
            }
            else if (ledgerStr == "validated")
            {
                ledger = ::rpc::spec::LedgerShortcut::Validated;
            }
            else
            {
                rpc::Status const status{RpcInvalidParams, "ledger_index string malformed"};
                status.inject(response);
                return response;
            }
        }
        return ledger;
    }
    return std::optional<LedgerSpecifier>{};
}
 
std::variant<LedgerRange, rpc::Status>
getLedgerRange(rpc::Context& context, std::optional<LedgerSpecifier> const& ledgerSpecifier)
{
    std::uint32_t uValidatedMin = 0;
    std::uint32_t uValidatedMax = 0;
    bool const bValidated = context.ledgerMaster.getValidatedRange(uValidatedMin, uValidatedMax);
 
    if (!bValidated)
    {
        // Don't have a validated ledger range.
        if (context.apiVersion == 1)
            return RpcLgrIdxsInvalid;
        return RpcNotSynced;
    }
 
    std::uint32_t uLedgerMin = uValidatedMin;
    std::uint32_t uLedgerMax = uValidatedMax;
    // Does request specify a ledger or ledger range?
    if (ledgerSpecifier)
    {
        auto status = std::visit(
            [&](auto const& ls) -> rpc::Status {
                using T = std::decay_t<decltype(ls)>;
                if constexpr (std::is_same_v<T, LedgerRange>)
                {
                    // if ledger_index_min or ledger_index_max is out of
                    // valid ledger range, error out. exclude -1 as
                    // it is a valid input
                    if (context.apiVersion > 1u)
                    {
                        if ((ls.max > uValidatedMax && ls.max != -1) ||
                            (ls.min < uValidatedMin && ls.min != 0))
                        {
                            return RpcLgrIdxMalformed;
                        }
                    }
                    if (ls.min > uValidatedMin)
                    {
                        uLedgerMin = ls.min;
                    }
                    if (ls.max < uValidatedMax)
                    {
                        uLedgerMax = ls.max;
                    }
                    if (uLedgerMax < uLedgerMin)
                    {
                        if (context.apiVersion == 1)
                            return RpcLgrIdxsInvalid;
                        return RpcInvalidLgrRange;
                    }
                }
                else
                {
                    std::shared_ptr<ReadView const> ledgerView;
                    auto status = getLedger(ledgerView, ls, context);
                    if (!ledgerView)
                    {
                        return status;
                    }
 
                    bool const validated = context.ledgerMaster.isValidated(*ledgerView);
 
                    if (!validated || ledgerView->header().seq > uValidatedMax ||
                        ledgerView->header().seq < uValidatedMin)
                    {
                        return RpcLgrNotValidated;
                    }
                    uLedgerMin = uLedgerMax = ledgerView->header().seq;
                }
                return rpc::Status::kOK;
            },
            *ledgerSpecifier);
 
        if (status)
            return status;
    }
    return LedgerRange{.min = uLedgerMin, .max = uLedgerMax};
}
 
std::pair<AccountTxResult, rpc::Status>
doAccountTxHelp(rpc::Context& context, AccountTxArgs const& args)
{
    context.loadType = resource::kFeeMediumBurdenRpc;
 
    AccountTxResult result;
 
    auto lgrRange = getLedgerRange(context, args.ledger);
    if (auto stat = std::get_if<rpc::Status>(&lgrRange))
    {
        // An error occurred getting the requested ledger range
        return {result, *stat};
    }
 
    result.ledgerRange = std::get<LedgerRange>(lgrRange);
 
    result.marker = args.marker;
 
    RelationalDatabase::AccountTxPageOptions const options = {
        .account = args.account,
        .ledgerRange = result.ledgerRange,
        .marker = result.marker,
        .limit = args.limit,
        .bAdmin = isUnlimited(context.role),
        .delegate = args.delegate};
 
    auto& db = context.app.getRelationalDatabase();
 
    if (args.binary)
    {
        if (args.forward)
        {
            auto [tx, marker] = db.oldestAccountTxPageB(options);
            result.transactions = tx;
            result.marker = marker;
        }
        else
        {
            auto [tx, marker] = db.newestAccountTxPageB(options);
            result.transactions = tx;
            result.marker = marker;
        }
    }
    else
    {
        if (args.forward)
        {
            auto [tx, marker] = db.oldestAccountTxPage(options);
            result.transactions = tx;
            result.marker = marker;
        }
        else
        {
            auto [tx, marker] = db.newestAccountTxPage(options);
            result.transactions = tx;
            result.marker = marker;
        }
    }
 
    result.limit = args.limit;
    JLOG(context.j.debug()) << __func__ << " : finished";
 
    return {result, RpcSuccess};
}
 
json::Value
populateJsonResponse(
    std::pair<AccountTxResult, rpc::Status> const& res,
    AccountTxArgs const& args,
    rpc::JsonContext const& context)
{
    json::Value response;
    rpc::Status const& error = res.second;
    if (error.toErrorCode() != RpcSuccess)
    {
        error.inject(response);
    }
    else
    {
        AccountTxResult const& result = res.first;
        response[jss::validated] = true;
        response[jss::limit] = result.limit;
        response[jss::account] = context.params[jss::account].asString();
        response[jss::ledger_index_min] = result.ledgerRange.min;
        response[jss::ledger_index_max] = result.ledgerRange.max;
 
        json::Value& jvTxns = (response[jss::transactions] = json::ValueType::Array);
 
        if (auto txnsData = std::get_if<TxnsData>(&result.transactions))
        {
            XRPL_ASSERT(!args.binary, "xrpl::populateJsonResponse : binary is not set");
 
            for (auto const& [txn, txnMeta] : *txnsData)
            {
                if (txn)
                {
                    json::Value& jvObj = jvTxns.append(json::ValueType::Object);
                    jvObj[jss::validated] = true;
 
                    auto const jsonTx = (context.apiVersion > 1 ? jss::tx_json : jss::tx);
                    if (context.apiVersion > 1)
                    {
                        jvObj[jsonTx] = txn->getJson(
                            static_cast<JsonOptions::UnderlyingT>(
                                JsonOptions::Values::IncludeDate) |
                                static_cast<JsonOptions::UnderlyingT>(
                                    JsonOptions::Values::DisableApiPriorV2),
                            false);
                        jvObj[jss::hash] = to_string(txn->getID());
                        jvObj[jss::ledger_index] = txn->getLedger();
                        jvObj[jss::ledger_hash] =
                            to_string(context.ledgerMaster.getHashBySeq(txn->getLedger()));
 
                        if (auto closeTime =
                                context.ledgerMaster.getCloseTimeBySeq(txn->getLedger()))
                            jvObj[jss::close_time_iso] = toStringIso(*closeTime);
                    }
                    else
                    {
                        jvObj[jsonTx] = txn->getJson(JsonOptions::Values::IncludeDate);
                    }
 
                    auto const& sttx = txn->getSTransaction();
                    rpc::insertDeliverMax(jvObj[jsonTx], sttx->getTxnType(), context.apiVersion);
                    if (txnMeta)
                    {
                        jvObj[jss::meta] = txnMeta->getJson(JsonOptions::Values::IncludeDate);
                        rpc::insertAllSyntheticInJson(jvObj[jss::meta], context, sttx, *txnMeta);
                    }
                    else
                    {
                        // LCOV_EXCL_START
                        UNREACHABLE(
                            "xrpl::populateJsonResponse : missing "
                            "transaction metadata");
                        // LCOV_EXCL_STOP
                    }
                }
            }
        }
        else
        {
            XRPL_ASSERT(args.binary, "xrpl::populateJsonResponse : binary is set");
 
            for (auto const& binaryData : std::get<TxnsDataBinary>(result.transactions))
            {
                json::Value& jvObj = jvTxns.append(json::ValueType::Object);
 
                jvObj[jss::tx_blob] = strHex(std::get<0>(binaryData));
                auto const jsonMeta = (context.apiVersion > 1 ? jss::meta_blob : jss::meta);
                jvObj[jsonMeta] = strHex(std::get<1>(binaryData));
                jvObj[jss::ledger_index] = std::get<2>(binaryData);
                jvObj[jss::validated] = true;
            }
        }
 
        if (result.marker)
        {
            response[jss::marker] = json::ValueType::Object;
            response[jss::marker][jss::ledger] = result.marker->ledgerSeq;
            response[jss::marker][jss::seq] = result.marker->txnSeq;
 
            if (args.delegate)
                response[jss::marker][jss::delegate] = true;
        }
    }
 
    JLOG(context.j.debug()) << __func__ << " : finished";
    return response;
}
 
// {
//   account: account,
//   ledger_index_min: ledger_index  // optional, defaults to earliest
//   ledger_index_max: ledger_index, // optional, defaults to latest
//   binary: boolean,                // optional, defaults to false
//   forward: boolean,               // optional, defaults to false
//   limit: integer,                 // optional
//   marker: object {ledger: ledger_index, seq: txn_sequence} // optional,
//   resume previous query
//   delegate: object {              // optional
//     delegate_filter: string,      // required; "actor" or "authorizer"
//     counter_party: account        // optional
//   }
// }
//
// Pagination note for delegate-filtered queries: the `delegate` object (both
// `delegate_filter` and `counter_party`) must be supplied unchanged on every
// paginated request until the query completes. A marker returned by a
// delegate-filtered query is only valid for a follow-up request that repeats
// the same `delegate` object
json::Value
doAccountTx(rpc::JsonContext& context)
{
    if (!context.app.config().useTxTables())
        return rpcError(RpcNotEnabled);
 
    auto& params = context.params;
    AccountTxArgs args;
    json::Value response;
 
    // The document[https://xrpl.org/account_tx.html#account_tx] states that
    // binary and forward params are both boolean values, however, assigning any
    // string value works. Do not allow this. This check is for api Version 2
    // onwards only
    if (context.apiVersion > 1u && params.isMember(jss::binary) && !params[jss::binary].isBool())
    {
        return rpc::invalidFieldError(jss::binary);
    }
    if (context.apiVersion > 1u && params.isMember(jss::forward) && !params[jss::forward].isBool())
    {
        return rpc::invalidFieldError(jss::forward);
    }
 
    if (auto const err = rpc::readLimitField(args.limit, rpc::tuning::kAccountTx, context))
        return *err;
 
    args.binary = params.isMember(jss::binary) && params[jss::binary].asBool();
    args.forward = params.isMember(jss::forward) && params[jss::forward].asBool();
 
    if (!params.isMember(jss::account))
        return rpc::missingFieldError(jss::account);
 
    if (!params[jss::account].isString())
        return rpc::invalidFieldError(jss::account);
 
    auto const account = parseBase58<AccountID>(params[jss::account].asString());
    if (!account)
        return rpcError(RpcActMalformed);
 
    args.account = *account;
 
    auto parseRes = parseLedgerArgs(context, params);
    if (auto jv = std::get_if<json::Value>(&parseRes))
    {
        return *jv;
    }
 
    args.ledger = std::get<std::optional<LedgerSpecifier>>(parseRes);
 
    if (params.isMember(jss::marker))
    {
        auto& token = params[jss::marker];
        if (!token.isMember(jss::ledger) || !token.isMember(jss::seq) ||
            !token[jss::ledger].isConvertibleTo(json::ValueType::UInt) ||
            !token[jss::seq].isConvertibleTo(json::ValueType::UInt))
        {
            rpc::Status const status{
                RpcInvalidParams,
                "invalid marker. Provide ledger index via ledger field, and "
                "transaction sequence number via seq field"};
            status.inject(response);
            return response;
        }
        args.marker = {
            .ledgerSeq = token[jss::ledger].asUInt(), .txnSeq = token[jss::seq].asUInt()};
    }
 
    if (params.isMember(jss::delegate))
    {
        if (auto const filter = parseDelegateFilter(params[jss::delegate]); filter.has_value())
        {
            args.delegate = *filter;
        }
        else
        {
            return filter.error();
        }
    }
 
    // A marker produced by a delegate-filtered query uses a different
    // pagination cursor than a normal query, so it is only valid when the same
    // `delegate` object is supplied again. Reject any mismatch so pagination
    // cannot silently skip or duplicate results.
    if (args.marker)
    {
        bool const markerFromDelegate = params[jss::marker].isMember(jss::delegate) &&
            params[jss::marker][jss::delegate].isBool() &&
            params[jss::marker][jss::delegate].asBool();
        if (markerFromDelegate != args.delegate.has_value())
        {
            rpc::Status const status{
                RpcInvalidParams,
                "Do not mix delegate and non-delegate pagination markers in account_tx; "
                "repeat the same `delegate` object when using a delegate marker."};
            status.inject(response);
            return response;
        }
    }
 
    auto res = doAccountTxHelp(context, args);
    JLOG(context.j.debug()) << __func__ << " populating response";
    return populateJsonResponse(res, args, context);
}
 
}  // namespace xrpl