SLEBase.h

#pragma once
 
#include <xrpl/basics/base_uint.h>
#include <xrpl/basics/contract.h>
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/ledger/ApplyView.h>
#include <xrpl/ledger/ReadView.h>
#include <xrpl/protocol/Keylet.h>
#include <xrpl/protocol/LedgerFormats.h>
#include <xrpl/protocol/STLedgerEntry.h>
 
#include <concepts>
#include <memory>
#include <stdexcept>
#include <type_traits>
#include <utility>
 
namespace xrpl {
 
// Concept to distinguish read-only vs writable view types
template <typename V>
concept IsWritableView = std::derived_from<V, ApplyView>;
 
namespace detail {

inline SLE::const_pointer
resolveEntry(ReadView const& view, Keylet const& key)
{
    // Safe only for a view that is not itself a const object -- see the
    // note above. The entry holds a const reference because it does not
    // modify the view, not because the view is const.
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-const-cast)
    if (auto const applyView = dynamic_cast<ApplyView*>(const_cast<ReadView*>(&view)))
        return applyView->peek(key);
    return view.read(key);
}
 
}  // namespace detail

template <typename ViewT, LedgerEntryType EntryType = ltANY>
class SLEBase
{
public:
    static constexpr bool kIsWritable = IsWritableView<ViewT>;
 
    // The ledger entry type this entry is bound to, and whether that binding
    // is meaningful (ltANY means "any type", i.e. no static check).
    static constexpr LedgerEntryType kEntryType = EntryType;
    static constexpr bool kIsTyped = (EntryType != ltANY);
 
    // SLE pointer type: mutable for writable views, const for read-only
    using SlePtrType = std::conditional_t<kIsWritable, SLE::pointer, SLE::const_pointer>;
 
    // View reference type: ApplyView& for writable, ReadView const& for
    // read-only
    using ViewRefType = std::conditional_t<kIsWritable, ApplyView&, ReadView const&>;
 
    // Non-virtual by design: these entries are parameterized on the view and
    // entry type, never used polymorphically through a base pointer. A vptr
    // would be 8 bytes of pure overhead on a type meant to be as cheap as the
    // shared_ptr it wraps. See the static_assert below the class.
    //
    // The destructor is public because the ReadOnlySLE / WritableSLE aliases
    // name this class directly and are used as value types. Since it is not
    // virtual, never delete a derived entry through an SLEBase*.
    ~SLEBase() = default;
 
    SLEBase(SLEBase const&)
        requires(!kIsWritable)
    = default;
    SLEBase(SLEBase&&) = default;
    SLEBase&
    operator=(SLEBase const&) = delete;
    SLEBase&
    operator=(SLEBase&&) = delete;
    SLEBase() = delete;
 
    // --- Constructors that adopt/resolve an SLE (public so the ReadOnlySLE /
    //     WritableSLE aliases and the per-type entries can be built directly
    //     from a keylet, or -- read-only only -- from an already-fetched
    //     SLE). ---

    explicit SLEBase(
        SLE::const_pointer sle,
        ViewRefType view,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        requires(!kIsWritable)
        : view_(view), sle_(std::move(sle)), j_(j)
    {
        XRPL_ASSERT(
            !kIsTyped || !sle_ || sle_->getType() == kEntryType,
            "xrpl::SLEBase::SLEBase : adopted SLE matches bound entry type");
    }

    explicit SLEBase(
        Keylet const& key,
        ViewRefType view,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        requires(!kIsWritable)
        : view_(view), sle_(detail::resolveEntry(view, key)), j_(j)
    {
        XRPL_ASSERT(
            !kIsTyped || key.type == kEntryType,
            "xrpl::SLEBase::SLEBase : keylet matches bound entry type");
    }

    template <typename OtherViewT, LedgerEntryType OtherType>
    SLEBase(SLEBase<OtherViewT, OtherType> const& other)
        requires(!kIsWritable && IsWritableView<OtherViewT> &&
                 (OtherType == EntryType || EntryType == ltANY))
        : view_(other.readView()), sle_(other.rawSle()), j_(other.journal())
    {
    }

    explicit SLEBase(
        Keylet const& key,
        ApplyView& view,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        requires kIsWritable
        : view_(view), key_(key), sle_(view_.peek(key)), j_(j)
    {
        XRPL_ASSERT(
            !kIsTyped || key.type == kEntryType,
            "xrpl::SLEBase::SLEBase : keylet matches bound entry type");
    }

    explicit SLEBase(
        Keylet const& key,
        ApplyViewContext const& ctx,
        beast::Journal j = beast::Journal{beast::Journal::getNullSink()})
        requires kIsWritable
        : SLEBase(key, ctx.view, j)
    {
    }
 
    // --- Common interface (always available) ---

    [[nodiscard]] bool
    exists() const
    {
        return sle_ != nullptr;
    }

    explicit
    operator bool() const
    {
        return exists();
    }

    [[nodiscard]] SLE::const_pointer
    rawSle() const
    {
        return sle_;
    }

    [[nodiscard]] LedgerEntryType
    type() const
    {
        if constexpr (kIsTyped)
        {
            return kEntryType;
        }
        else
        {
            if (!exists())
                Throw<std::logic_error>("xrpl::SLEBase::type : entry does not exist");
            return sle_->getType();
        }
    }

    [[nodiscard]] Keylet
    keylet() const
    {
        if constexpr (kIsWritable)
        {
            return key_;
        }
        else
        {
            if (!exists())
                Throw<std::logic_error>("xrpl::SLEBase::keylet : entry does not exist");
            // Take the type from the SLE, not from kEntryType: the adopt-SLE
            // constructor's type check is assert-only, so a Release build can
            // be holding an SLE whose type disagrees with the binding, and the
            // SLE is the one telling the truth.
            return Keylet(sle_->getType(), sle_->key());
        }
    }

    [[nodiscard]] UInt256
    key() const
    {
        return keylet().key;
    }

    [[nodiscard]] ReadView const&
    readView() const
    {
        return view_;
    }

    STLedgerEntry const*
    operator->() const
    {
        if (!exists())
            Throw<std::logic_error>("xrpl::SLEBase::operator-> : entry does not exist");
        return sle_.get();
    }
 
    STLedgerEntry const&
    operator*() const
    {
        if (!exists())
            Throw<std::logic_error>("xrpl::SLEBase::operator* : entry does not exist");
        return *sle_;
    }
 
    // --- Writable interface (compile-time gated) ---
    //
    // Everything that hands out mutable access (or mutates) is non-const, so
    // that a `FooEntryW const&` is as inert as a `FooEntryR`. Use readView()
    // when a const entry only needs to inspect the view.

    [[nodiscard]] SlePtrType const&
    mutableRawSle()
        requires kIsWritable
    {
        return sle_;
    }

    [[nodiscard]] ApplyView&
    applyView()
        requires kIsWritable
    {
        return view_;
    }

    STLedgerEntry*
    operator->()
        requires kIsWritable
    {
        if (!exists())
            Throw<std::logic_error>("xrpl::SLEBase::operator-> : entry does not exist");
        return sle_.get();
    }
 
    STLedgerEntry&
    operator*()
        requires kIsWritable
    {
        if (!exists())
            Throw<std::logic_error>("xrpl::SLEBase::operator* : entry does not exist");
        return *sle_;
    }

    void
    insert()
        requires kIsWritable
    {
        if (!exists())
            Throw<std::logic_error>("xrpl::SLEBase::insert : entry does not exist");
        view_.insert(sle_);
    }

    void
    erase()
        requires kIsWritable
    {
        if (!exists())
            Throw<std::logic_error>("xrpl::SLEBase::erase : entry does not exist");
        view_.erase(sle_);
        sle_ = nullptr;
    }

    void
    update()
        requires kIsWritable
    {
        if (!exists())
            Throw<std::logic_error>("xrpl::SLEBase::update : entry does not exist");
        view_.update(sle_);
    }

    void
    newSLE()
        requires kIsWritable
    {
        if (exists())
            Throw<std::logic_error>("xrpl::SLEBase::newSLE : entry already exists");
        sle_ = std::make_shared<SLE>(key_);
    }
 
    [[nodiscard]] beast::Journal
    journal() const
    {
        return j_;
    }
 
protected:
    ViewRefType view_;
 
    // Keylet is only meaningful for writable views, which need it to build an
    // SLE that does not exist yet; read-only entries derive it from the SLE.
    struct Empty
    {
    };
 
    // No default member initializer: Keylet is not default-constructible, so
    // every writable constructor must initialize key_ explicitly.
    [[no_unique_address]]
    std::conditional_t<kIsWritable, Keylet, Empty> key_;
 
    SlePtrType sle_{};
    beast::Journal j_;
};

using ReadOnlySLE = SLEBase<ReadView>;
using WritableSLE = SLEBase<ApplyView>;
 
static_assert(
    !std::is_polymorphic_v<ReadOnlySLE> && !std::is_polymorphic_v<WritableSLE>,
    "SLEBase must stay a thin value type; it must not acquire a vtable");
 
}  // namespace xrpl