ApplyView.h

#pragma once
 
#include <xrpl/basics/base_uint.h>
#include <xrpl/basics/safe_cast.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/ledger/OwnerCounts.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/Issue.h>  // IWYU pragma: keep
#include <xrpl/protocol/Keylet.h>
#include <xrpl/protocol/LedgerFormats.h>
#include <xrpl/protocol/MPTIssue.h>
#include <xrpl/protocol/STAmount.h>
#include <xrpl/protocol/STLedgerEntry.h>
#include <xrpl/protocol/STTx.h>
#include <xrpl/protocol/STVector256.h>
 
#include <cstdint>
#include <functional>
#include <optional>
#include <type_traits>
 
namespace xrpl {
 
// Bitwise flag enum with existing operator overloads
// NOLINTNEXTLINE(cppcoreguidelines-use-enum-class)
enum ApplyFlags : std::uint32_t {
    TapNone = 0x00,
 
    // This is a local transaction with the
    // fail_hard flag set.
    TapFailHard = 0x10,
 
    // This is not the transaction's last pass
    // Transaction can be retried, soft failures allowed
    TapRetry = 0x20,
 
    // Transaction came from a privileged source
    TapUnlimited = 0x400,
 
    // Transaction is executing as part of a batch
    TapBatch = 0x800,
 
    // Transaction shouldn't be applied
    // Signatures shouldn't be checked
    TapDryRun = 0x1000,
 
    // Transaction is being preflighted as the payload of a
    // TransactionProposalCreate. Its signatures are collected on-ledger
    // afterward, so signature-presence checks (e.g. Batch signer matching)
    // are skipped at proposal-creation time (On-Chain Cosigner spec
    // §5.3.1.2).
    TapProposal = 0x2000
};
 
constexpr ApplyFlags
operator|(ApplyFlags const& lhs, ApplyFlags const& rhs)
{
    return safeCast<ApplyFlags>(
        safeCast<std::underlying_type_t<ApplyFlags>>(lhs) |
        safeCast<std::underlying_type_t<ApplyFlags>>(rhs));
}
 
static_assert((TapFailHard | TapRetry) == safeCast<ApplyFlags>(0x30u), "ApplyFlags operator |");
static_assert((TapRetry | TapFailHard) == safeCast<ApplyFlags>(0x30u), "ApplyFlags operator |");
 
constexpr ApplyFlags
operator&(ApplyFlags const& lhs, ApplyFlags const& rhs)
{
    return safeCast<ApplyFlags>(
        safeCast<std::underlying_type_t<ApplyFlags>>(lhs) &
        safeCast<std::underlying_type_t<ApplyFlags>>(rhs));
}
 
static_assert((TapFailHard & TapRetry) == TapNone, "ApplyFlags operator &");
static_assert((TapRetry & TapFailHard) == TapNone, "ApplyFlags operator &");
 
constexpr ApplyFlags
operator~(ApplyFlags const& flags)
{
    return safeCast<ApplyFlags>(~safeCast<std::underlying_type_t<ApplyFlags>>(flags));
}
 
static_assert(~TapRetry == safeCast<ApplyFlags>(0xFFFFFFDFu), "ApplyFlags operator ~");
 
inline ApplyFlags
operator|=(ApplyFlags& lhs, ApplyFlags const& rhs)
{
    lhs = lhs | rhs;
    return lhs;
}
 
inline ApplyFlags
operator&=(ApplyFlags& lhs, ApplyFlags const& rhs)
{
    lhs = lhs & rhs;
    return lhs;
}
 
//------------------------------------------------------------------------------

class ApplyView : public ReadView
{
private:
    std::optional<std::uint64_t>
    dirAdd(
        bool preserveOrder,
        Keylet const& directory,
        UInt256 const& key,
        std::function<void(SLE::Ref)> const& describe);
 
public:
    ApplyView() = default;

    [[nodiscard]] virtual ApplyFlags
    flags() const = 0;

    virtual SLE::pointer
    peek(Keylet const& k) = 0;

    virtual void
    erase(SLE::Ref sle) = 0;

    virtual void
    insert(SLE::Ref sle) = 0;

    virtual void
    update(SLE::Ref sle) = 0;
 
    //--------------------------------------------------------------------------
 
    // Called when a credit is made to an account
    // This is required to support PaymentSandbox
    virtual void
    creditHookIOU(
        AccountID const& from,
        AccountID const& to,
        STAmount const& amount,
        STAmount const& preCreditBalance)
    {
        XRPL_ASSERT(amount.holds<Issue>(), "creditHookIOU: amount is for Issue");
    }
 
    virtual void
    creditHookMPT(
        AccountID const& from,
        AccountID const& to,
        STAmount const& amount,
        std::uint64_t preCreditBalanceHolder,
        std::int64_t preCreditBalanceIssuer)
    {
        XRPL_ASSERT(amount.holds<MPTIssue>(), "creditHookMPT: amount is for MPTIssue");
    }

    virtual void
    issuerSelfDebitHookMPT(MPTIssue const& issue, std::uint64_t amount, std::int64_t origBalance)
    {
    }
 
    // Called when the owner count changes
    // This is required to support PaymentSandbox
    virtual void
    adjustOwnerCountHook(AccountID const& account, OwnerCounts const& cur, OwnerCounts const& next)
    {
    }

    std::optional<std::uint64_t>
    dirAppend(
        Keylet const& directory,
        Keylet const& key,
        std::function<void(SLE::Ref)> const& describe)
    {
        if (key.type != ltOFFER)
        {
            // LCOV_EXCL_START
            UNREACHABLE(
                "xrpl::ApplyView::dirAppend : only Offers are appended to "
                "book directories");
            // Only Offers are appended to book directories. Call dirInsert()
            // instead
            return std::nullopt;
            // LCOV_EXCL_STOP
        }
        return dirAdd(true, directory, key.key, describe);
    }


    std::optional<std::uint64_t>
    dirInsert(
        Keylet const& directory,
        UInt256 const& key,
        std::function<void(SLE::Ref)> const& describe)
    {
        return dirAdd(false, directory, key, describe);
    }
 
    std::optional<std::uint64_t>
    dirInsert(
        Keylet const& directory,
        Keylet const& key,
        std::function<void(SLE::Ref)> const& describe)
    {
        return dirAdd(false, directory, key.key, describe);
    }


    bool
    dirRemove(Keylet const& directory, std::uint64_t page, UInt256 const& key, bool keepRoot);
 
    bool
    dirRemove(Keylet const& directory, std::uint64_t page, Keylet const& key, bool keepRoot)
    {
        return dirRemove(directory, page, key.key, keepRoot);
    }


    bool
    dirDelete(Keylet const& directory, std::function<void(UInt256 const&)> const&);

    bool
    emptyDirDelete(Keylet const& directory);
};

struct ApplyViewContext
{
    ApplyView& view;
    STTx const& tx;
};
 
namespace directory {
 
std::uint64_t
createRoot(
    ApplyView& view,
    Keylet const& directory,
    UInt256 const& key,
    std::function<void(SLE::Ref)> const& describe);
 
auto
findPreviousPage(ApplyView& view, Keylet const& directory, SLE::Ref start);
 
std::uint64_t
insertKey(
    ApplyView& view,
    SLE::Ref node,
    std::uint64_t page,
    bool preserveOrder,
    STVector256& indexes,
    UInt256 const& key);
 
std::optional<std::uint64_t>
insertPage(
    ApplyView& view,
    std::uint64_t page,
    SLE::pointer node,
    std::uint64_t nextPage,
    SLE::Ref next,
    UInt256 const& key,
    Keylet const& directory,
    std::function<void(SLE::Ref)> const& describe);
 
}  // namespace directory
}  // namespace xrpl