Transactor.h

#pragma once
 
#include <xrpl/basics/Slice.h>
#include <xrpl/basics/base_uint.h>
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/beast/utility/WrappedSink.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/core/ServiceRegistry.h>
#include <xrpl/ledger/ApplyView.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/Fees.h>
#include <xrpl/protocol/Keylet.h>
#include <xrpl/protocol/Permissions.h>
#include <xrpl/protocol/Rules.h>
#include <xrpl/protocol/SField.h>
#include <xrpl/protocol/STObject.h>
#include <xrpl/protocol/TER.h>
#include <xrpl/protocol/Units.h>
#include <xrpl/protocol/XRPAmount.h>
#include <xrpl/tx/ApplyContext.h>
#include <xrpl/tx/applySteps.h>
#include <xrpl/tx/invariants/InvariantRunner.h>
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <tuple>
#include <unordered_set>
#include <utility>
 
namespace xrpl {

struct PreflightContext
{
public:
    std::reference_wrapper<ServiceRegistry> registry;
    STTx const& tx;
    Rules const rules;
    ApplyFlags flags;
    std::optional<UInt256 const> parentBatchId;
    beast::Journal const j;
 
    PreflightContext(
        ServiceRegistry& registry,
        STTx const& tx,
        UInt256 parentBatchId,
        Rules rules,
        ApplyFlags flags,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        : registry(registry)
        , tx(tx)
        , rules(std::move(rules))
        , flags(flags)
        , parentBatchId(parentBatchId)
        , j(j)
    {
        XRPL_ASSERT((flags & TapBatch) == TapBatch, "Batch apply flag should be set");
        XRPL_ASSERT_IF(
            (flags & TapProposal) != TapNone,
            (flags & TapDryRun) != TapNone,
            "xrpl::PreflightContext : proposal preflight implies dry run");
    }
 
    PreflightContext(
        ServiceRegistry& registry,
        STTx const& tx,
        Rules rules,
        ApplyFlags flags,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        : registry(registry), tx(tx), rules(std::move(rules)), flags(flags), j(j)
    {
        XRPL_ASSERT((flags & TapBatch) == 0, "Batch apply flag should not be set");
        XRPL_ASSERT_IF(
            (flags & TapProposal) != TapNone,
            (flags & TapDryRun) != TapNone,
            "xrpl::PreflightContext : proposal preflight implies dry run");
    }
 
    PreflightContext&
    operator=(PreflightContext const&) = delete;
};

struct PreclaimContext
{
public:
    std::reference_wrapper<ServiceRegistry> registry;
    ReadView const& view;
    TER preflightResult;
    ApplyFlags flags;
    STTx const& tx;
    std::optional<UInt256 const> const parentBatchId;
    beast::Journal const j;
 
    PreclaimContext(
        ServiceRegistry& registry,
        ReadView const& view,
        TER preflightResult,
        STTx const& tx,
        ApplyFlags flags,
        std::optional<UInt256> parentBatchId,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        : registry(registry)
        , view(view)
        , preflightResult(preflightResult)
        , flags(flags)
        , tx(tx)
        , parentBatchId(parentBatchId)
        , j(j)
    {
        XRPL_ASSERT(
            parentBatchId.has_value() == ((flags & TapBatch) == TapBatch),
            "Parent Batch ID should be set if batch apply flag is set");
    }
 
    PreclaimContext(
        ServiceRegistry& registry,
        ReadView const& view,
        TER preflightResult,
        STTx const& tx,
        ApplyFlags flags,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        : PreclaimContext(registry, view, preflightResult, tx, flags, std::nullopt, j)
    {
        XRPL_ASSERT((flags & TapBatch) == 0, "Batch apply flag should not be set");
    }
 
    PreclaimContext&
    operator=(PreclaimContext const&) = delete;
};
 
class TxConsequences;
struct PreflightResult;
// Needed for preflight specialization
class Change;
 
enum class FeePayerType {
    Account,
    Delegate,
    SponsorCoSigned,
    SponsorPreFunded,
};
 
struct FeePayer
{
    AccountID id;
    Keylet keylet;
    SF_AMOUNT const& balanceField;
    FeePayerType type{FeePayerType::Account};
};
 
class Transactor : public TxInvariantCheck
{
protected:
    ApplyContext& ctx_;
    beast::WrappedSink sink_;
    beast::Journal const j_;
 
    AccountID const accountID_;
    XRPAmount preFeeBalance_{};  // Balance before fees.
 
public:
    ~Transactor() override = default;
    Transactor(Transactor const&) = delete;
    Transactor&
    operator=(Transactor const&) = delete;
 
    enum class ConsequencesFactoryType { Normal, Blocker, Custom };

    ApplyResult
    operator()();
 
    ApplyView&
    view()
    {
        return ctx_.view();
    }
 
    [[nodiscard]] ApplyView const&
    view() const
    {
        return ctx_.view();
    }

    enum class InvariantScope { Full, ProtocolOnly };

    [[nodiscard]] TER
    checkInvariants(TER result, XRPAmount fee, InvariantScope scope);

    /*
    These static functions are called from invoke_preclaim<Tx>
    using name hiding to accomplish compile-time polymorphism,
    so derived classes can override for different or extra
    functionality. Use with care, as these are not really
    virtual and so don't have the compiler-time protection that
    comes with it.
    */
 
    static NotTEC
    checkSeqProxy(ReadView const& view, STTx const& tx, beast::Journal j);
 
    static NotTEC
    checkPriorTxAndLastLedger(PreclaimContext const& ctx);
 
    static TER
    checkFee(PreclaimContext const& ctx, XRPAmount baseFee);
 
    static NotTEC
    checkSign(PreclaimContext const& ctx);
 
    // Returns the fee in fee units, not scaled for load.
    static XRPAmount
    calculateBaseFee(ReadView const& view, STTx const& tx);
 
    // Returns the base fee plus extra base fee units, not scaled for load.
    static XRPAmount
    calculateBaseFee(ReadView const& view, STTx const& tx, std::uint32_t extraBaseFeeMultiplier);
 
    // Exposed for invariant checks (e.g. ValidVault) that need to know which
    // ledger entry actually pays a transaction's fee, distinguishing an
    // ordinary sender, a delegate, and pre-funded vs. co-signed fee
    // sponsorship.
    static FeePayer
    getFeePayer(ReadView const& view, STTx const& tx);
 
    /* Do NOT define an invokePreflight function in a derived class.
       Instead, define:
 
        // Optional if the transaction is gated on an amendment that
        // isn't specified in transactions.macro
        static bool
        checkExtraFeatures(PreflightContext const& ctx);
 
        // Optional if the transaction uses any flags other than tfUniversal
        static std::uint32_t
        getFlagsMask(PreflightContext const& ctx);
 
        // Required, even if it just returns tesSUCCESS.
        static NotTEC
        preflight(PreflightContext const& ctx);
 
        // Optional, rarely needed, if the transaction does any expensive
        // checks after the signature is verified.
        static NotTEC preflightSigValidated(PreflightContext const& ctx);
 
       * Do not try to call preflight1 or preflight2 directly.
       * Do not check whether relevant amendments are enabled in preflight.
         Instead, define checkExtraFeatures.
       * Do not check flags in preflight. Instead, define getFlagsMask.
    */
    template <class T>
    static NotTEC
    invokePreflight(PreflightContext const& ctx);
 
    static TER
    preclaim(PreclaimContext const& ctx)
    {
        // Most transactors do nothing
        // after checkSeq/Fee/Sign.
        return tesSUCCESS;
    }

    static NotTEC
    checkGranularSemantics(
        ReadView const& view,
        STTx const& tx,
        std::unordered_set<GranularPermissionType> const& heldGranularPermissions)
    {
        return tesSUCCESS;
    }

    template <class T>
    static NotTEC
    invokeCheckPermission(ReadView const& view, STTx const& tx)
    {
        // heldGranularPermissions is passed by reference into checkPermission.
        // It is populated with the sender’s granular permissions only when the sender
        // lacks tx-level permission but has granular permissions that satisfy the
        // granular permission template.
        //
        // - result is terNO_DELEGATE_PERMISSION: return immediately.
        // - result is tesSUCCESS and heldGranularPermissions is empty: tx-level permission was
        // granted, so we returned success before populating it.
        // - result is tesSUCCESS and heldGranularPermissions is not empty: tx-level permission was
        // not granted, but the held granular permissions passed checkGranularSandbox, so we proceed
        // to checkGranularSemantics.
        //
        // WARNING: Do not simplify checkPermission to return only
        // heldGranularPermissions or the ter code. Both the result and the
        // populated set are required to enforce the strict permission hierarchy
        // described above.
        std::unordered_set<GranularPermissionType> heldGranularPermissions;
        if (NotTEC const result = checkPermission(view, tx, heldGranularPermissions);
            !isTesSuccess(result) || heldGranularPermissions.empty())
        {
            return result;
        }
 
        return T::checkGranularSemantics(view, tx, heldGranularPermissions);
    }
 
    static NotTEC
    checkSponsor(ReadView const& view, STTx const& tx);

 
    // Interface used by AccountDelete
    static TER
    ticketDelete(
        ApplyView& view,
        AccountID const& account,
        UInt256 const& ticketIndex,
        beast::Journal j);
 
protected:
    TER
    apply();
 
    explicit Transactor(ApplyContext& ctx);
 
    virtual void
    preCompute();
 
    virtual TER
    doApply() = 0;

    virtual void
    visitInvariantEntry(bool isDelete, SLE::ConstRef before, SLE::ConstRef after) = 0;

    [[nodiscard]] virtual bool
    finalizeInvariants(
        STTx const& tx,
        TER result,
        XRPAmount fee,
        ReadView const& view,
        beast::Journal const& j) = 0;

    static XRPAmount
    minimumFee(ServiceRegistry& registry, XRPAmount baseFee, Fees const& fees, ApplyFlags flags);
 
    // Returns the fee in fee units, not scaled for load.
    static XRPAmount
    calculateOwnerReserveFee(ReadView const& view, STTx const& tx);
 
    static NotTEC
    checkSign(
        ReadView const& view,
        ApplyFlags flags,
        std::optional<UInt256 const> const& parentBatchId,
        AccountID const& idAccount,
        STObject const& sigObject,
        beast::Journal const j,
        // A batch may carry an inner from an account that an earlier inner
        // creates, so the signer account need not exist yet; when it does not,
        // only its own master key may authorize it. Normal transactions require
        // the account to already exist.
        bool permitUncreatedAccount = false);
 
    // Base class always returns true
    static bool
    checkExtraFeatures(PreflightContext const& ctx);
 
    // Base class always returns tfUniversalMask
    static std::uint32_t
    getFlagsMask(PreflightContext const& ctx);
 
    // Base class always returns tesSUCCESS
    static NotTEC
    preflightSigValidated(PreflightContext const& ctx);
 
    static bool
    validDataLength(std::optional<Slice> const& slice, std::size_t maxLength);
 
    template <class T>
    static bool
    validNumericRange(std::optional<T> value, T max, T min = T{});
 
    template <class T, class Unit>
    static bool
    validNumericRange(
        std::optional<T> value,
        unit::ValueUnit<Unit, T> max,
        unit::ValueUnit<Unit, T> min = unit::ValueUnit<Unit, T>{});

    template <class T>
    static bool
    validNumericMinimum(std::optional<T> value, T min = T{});

    template <class T, class Unit>
    static bool
    validNumericMinimum(
        std::optional<T> value,
        unit::ValueUnit<Unit, T> min = unit::ValueUnit<Unit, T>{});
 
    // Signature-authorization helpers. protected so the Batch transactor can
    // reuse them when validating each BatchSigner in Batch::checkBatchSign.
    static NotTEC
    checkSingleSign(
        ReadView const& view,
        AccountID const& idSigner,
        AccountID const& idAccount,
        SLE::const_pointer sleAccount,
        beast::Journal const j);
 
    static NotTEC
    checkMultiSign(
        ReadView const& view,
        ApplyFlags flags,
        AccountID const& id,
        STObject const& sigObject,
        beast::Journal const j);
 
private:
    static NotTEC
    checkPermission(
        ReadView const& view,
        STTx const& tx,
        std::unordered_set<GranularPermissionType>& heldGranularPermissions);
 
    std::pair<TER, XRPAmount>
    reset(XRPAmount fee);
 
    TER
    consumeSeqProxy(SLE::pointer const& sleAccount);
    TER
    payFee();
 
    std::tuple<TER, XRPAmount, bool>
    processPersistentChanges(TER result, XRPAmount fee);
 
    void trapTransaction(UInt256) const;

    static NotTEC
    preflight1(PreflightContext const& ctx, std::uint32_t flagMask);

    static NotTEC
    preflight2(PreflightContext const& ctx);

    static NotTEC
    preflightUniversal(PreflightContext const& ctx);

    void
    visitEntry(bool isDelete, SLE::ConstRef before, SLE::ConstRef after) final
    {
        visitInvariantEntry(isDelete, before, after);
    }
 
    [[nodiscard]] bool
    finalize(
        STTx const& tx,
        TER result,
        XRPAmount fee,
        ReadView const& view,
        beast::Journal const& j) final
    {
        return finalizeInvariants(tx, result, fee, view, j);
    }
};
 
inline bool
Transactor::checkExtraFeatures(PreflightContext const& ctx)
{
    return true;
}

NotTEC
preflight0(PreflightContext const& ctx, std::uint32_t flagMask);
 
namespace detail {

NotTEC
preflightCheckSigningKey(STObject const& sigObject, beast::Journal j);

std::optional<NotTEC>
preflightCheckSimulateKeys(ApplyFlags flags, STObject const& sigObject, beast::Journal j);
}  // namespace detail
 
// Defined in Change.cpp
template <>
NotTEC
Transactor::invokePreflight<Change>(PreflightContext const& ctx);
 
template <class T>
NotTEC
Transactor::invokePreflight(PreflightContext const& ctx)
{
    // Using this lookup does NOT require checking the fixDelegateV1_1. The data
    // exists regardless of whether it is enabled.
    auto const feature = Permission::getInstance().getTxFeature(ctx.tx.getTxnType());
 
    if (feature && !ctx.rules.enabled(*feature))
        return temDISABLED;
 
    if (!T::checkExtraFeatures(ctx))
        return temDISABLED;
 
    if (auto const ret = preflight1(ctx, T::getFlagsMask(ctx)))
        return ret;
 
    if (auto const ret = preflightUniversal(ctx))
        return ret;
 
    if (auto const ret = T::preflight(ctx))
        return ret;
 
    if (auto const ret = preflight2(ctx))
        return ret;
 
    return T::preflightSigValidated(ctx);
}
 
template <class T>
bool
Transactor::validNumericRange(std::optional<T> value, T max, T min)
{
    if (!value)
        return true;
    return value >= min && value <= max;
}
 
template <class T, class Unit>
bool
Transactor::validNumericRange(
    std::optional<T> value,
    unit::ValueUnit<Unit, T> max,
    unit::ValueUnit<Unit, T> min)
{
    return validNumericRange(value, max.value(), min.value());
}
 
template <class T>
bool
Transactor::validNumericMinimum(std::optional<T> value, T min)
{
    if (!value)
        return true;
    return value >= min;
}
 
template <class T, class Unit>
bool
Transactor::validNumericMinimum(std::optional<T> value, unit::ValueUnit<Unit, T> min)
{
    return validNumericMinimum(value, min.value());
}
 
}  // namespace xrpl