RelationalDatabase.h

#pragma once
 
#include <xrpl/basics/Blob.h>
#include <xrpl/basics/Log.h>
#include <xrpl/basics/RangeSet.h>
#include <xrpl/basics/base_uint.h>
#include <xrpl/beast/utility/instrumentation.h>
#include <xrpl/core/ServiceRegistry.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/ErrorCodes.h>
#include <xrpl/protocol/LedgerHeader.h>
#include <xrpl/protocol/LedgerShortcut.h>
#include <xrpl/protocol/Protocol.h>
#include <xrpl/protocol/TxMeta.h>
#include <xrpl/protocol/TxSearched.h>
 
#include <boost/variant.hpp>
 
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <map>
#include <memory>
#include <optional>
#include <tuple>
#include <utility>
#include <variant>
#include <vector>
 
namespace xrpl {
 
class Transaction;
class Ledger;
 
struct LedgerHashPair
{
    uint256 ledgerHash;
    uint256 parentHash;
};
 
struct LedgerRange
{
    uint32_t min;
    uint32_t max;
};

enum class DelegateType {
    Actor,  
    Authorizer  
};
 
struct DelegateFilter
{
    DelegateType type = DelegateType::Actor;
    std::optional<AccountID> counterparty;
};
 
class RelationalDatabase
{
public:
    struct CountMinMax
    {
        std::size_t numberOfRows;
        LedgerIndex minLedgerSequence;
        LedgerIndex maxLedgerSequence;
    };
 
    struct AccountTxMarker
    {
        std::uint32_t ledgerSeq = 0;
        std::uint32_t txnSeq = 0;
    };
 
    struct AccountTxOptions
    {
        AccountID const& account;
        LedgerRange ledgerRange{};
        std::uint32_t offset = 0;
        std::uint32_t limit = 0;
        bool bUnlimited{};
    };
 
    struct AccountTxPageOptions
    {
        AccountID const& account;
        LedgerRange ledgerRange{};
        std::optional<AccountTxMarker> marker;
        std::uint32_t limit = 0;
        bool bAdmin = false;
        std::optional<DelegateFilter> delegate;
    };
 
    using AccountTx = std::pair<std::shared_ptr<Transaction>, std::shared_ptr<TxMeta>>;
    using AccountTxs = std::vector<AccountTx>;
    using txnMetaLedgerType = std::tuple<Blob, Blob, std::uint32_t>;
    using MetaTxsList = std::vector<txnMetaLedgerType>;
 
    using LedgerSequence = uint32_t;
    using LedgerHash = uint256;
    using LedgerSpecifier = std::variant<LedgerRange, LedgerShortcut, LedgerSequence, LedgerHash>;
 
    struct AccountTxArgs
    {
        AccountID account;
        std::optional<LedgerSpecifier> ledger;
        bool binary = false;
        bool forward = false;
        uint32_t limit = 0;
        std::optional<AccountTxMarker> marker;
        std::optional<DelegateFilter> delegate;
    };
 
    struct AccountTxResult
    {
        std::variant<AccountTxs, MetaTxsList> transactions;
        LedgerRange ledgerRange{};
        uint32_t limit = 0;
        std::optional<AccountTxMarker> marker;
        std::optional<DelegateFilter> delegate;
    };
 
    virtual ~RelationalDatabase() = default;

    virtual std::optional<LedgerIndex>
    getMinLedgerSeq() = 0;

    virtual std::optional<LedgerIndex>
    getMaxLedgerSeq() = 0;

    virtual std::optional<LedgerHeader>
    getLedgerInfoByIndex(LedgerIndex ledgerSeq) = 0;

    virtual std::optional<LedgerHeader>
    getNewestLedgerInfo() = 0;

    virtual std::optional<LedgerHeader>
    getLedgerInfoByHash(uint256 const& ledgerHash) = 0;

    virtual uint256
    getHashByIndex(LedgerIndex ledgerIndex) = 0;

    virtual std::optional<LedgerHashPair>
    getHashesByIndex(LedgerIndex ledgerIndex) = 0;

    virtual std::map<LedgerIndex, LedgerHashPair>
    getHashesByIndex(LedgerIndex minSeq, LedgerIndex maxSeq) = 0;

    virtual std::vector<std::shared_ptr<Transaction>>
    getTxHistory(LedgerIndex startIndex) = 0;

    virtual std::optional<LedgerIndex>
    getTransactionsMinLedgerSeq() = 0;

    virtual std::optional<LedgerIndex>
    getAccountTransactionsMinLedgerSeq() = 0;

    virtual void
    deleteTransactionByLedgerSeq(LedgerIndex ledgerSeq) = 0;

    virtual void
    deleteBeforeLedgerSeq(LedgerIndex ledgerSeq) = 0;

    virtual void
    deleteTransactionsBeforeLedgerSeq(LedgerIndex ledgerSeq) = 0;

    virtual void
    deleteAccountTransactionsBeforeLedgerSeq(LedgerIndex ledgerSeq) = 0;

    virtual std::size_t
    getTransactionCount() = 0;

    virtual std::size_t
    getAccountTransactionCount() = 0;

    virtual CountMinMax
    getLedgerCountMinMax() = 0;

    virtual bool
    saveValidatedLedger(std::shared_ptr<Ledger const> const& ledger, bool current) = 0;

    virtual std::optional<LedgerHeader>
    getLimitedOldestLedgerInfo(LedgerIndex ledgerFirstIndex) = 0;

    virtual std::optional<LedgerHeader>
    getLimitedNewestLedgerInfo(LedgerIndex ledgerFirstIndex) = 0;

    virtual AccountTxs
    getOldestAccountTxs(AccountTxOptions const& options) = 0;

    virtual AccountTxs
    getNewestAccountTxs(AccountTxOptions const& options) = 0;

    virtual MetaTxsList
    getOldestAccountTxsB(AccountTxOptions const& options) = 0;

    virtual MetaTxsList
    getNewestAccountTxsB(AccountTxOptions const& options) = 0;

    virtual std::pair<AccountTxs, std::optional<AccountTxMarker>>
    oldestAccountTxPage(AccountTxPageOptions const& options) = 0;

    virtual std::pair<AccountTxs, std::optional<AccountTxMarker>>
    newestAccountTxPage(AccountTxPageOptions const& options) = 0;

    virtual std::pair<MetaTxsList, std::optional<AccountTxMarker>>
    oldestAccountTxPageB(AccountTxPageOptions const& options) = 0;

    virtual std::pair<MetaTxsList, std::optional<AccountTxMarker>>
    newestAccountTxPageB(AccountTxPageOptions const& options) = 0;

    virtual std::variant<AccountTx, TxSearched>
    getTransaction(
        uint256 const& id,
        std::optional<ClosedInterval<uint32_t>> const& range,
        ErrorCodeI& ec) = 0;

    virtual uint32_t
    getKBUsedAll() = 0;

    virtual uint32_t
    getKBUsedLedger() = 0;

    virtual uint32_t
    getKBUsedTransaction() = 0;

    virtual void
    closeLedgerDB() = 0;

    virtual void
    closeTransactionDB() = 0;
};
 
template <typename T, typename C>
T
rangeCheckedCast(C c)
    requires(std::is_arithmetic_v<T> && std::is_arithmetic_v<C> && std::convertible_to<C, T>)
{
    if ((c > std::numeric_limits<T>::max()) || (!std::numeric_limits<T>::is_signed && c < 0) ||
        (std::numeric_limits<T>::is_signed && std::numeric_limits<C>::is_signed &&
         c < std::numeric_limits<T>::lowest()))
    {
        // This should never happen
        // LCOV_EXCL_START
        UNREACHABLE("xrpl::rangeCheckedCast : domain error");
        JLOG(debugLog().error()) << "rangeCheckedCast domain error:"
                                 << " value = " << c
                                 << " min = " << std::numeric_limits<T>::lowest()
                                 << " max: " << std::numeric_limits<T>::max();
        // LCOV_EXCL_STOP
    }
 
    return static_cast<T>(c);
}
 
}  // namespace xrpl