Steps.h

#pragma once
 
#include <xrpl/basics/base_uint.h>
#include <xrpl/beast/utility/Journal.h>
#include <xrpl/beast/utility/Zero.h>
#include <xrpl/protocol/AccountID.h>
#include <xrpl/protocol/Book.h>
#include <xrpl/protocol/Concepts.h>
#include <xrpl/protocol/Quality.h>
#include <xrpl/protocol/QualityFunction.h>
#include <xrpl/protocol/STPathSet.h>
#include <xrpl/protocol/TER.h>
#include <xrpl/protocol/UintTypes.h>
#include <xrpl/tx/paths/detail/EitherAmount.h>
 
#include <boost/container/flat_set.hpp>
 
#include <array>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <ostream>
#include <stdexcept>
#include <string>
#include <utility>
#include <vector>
 
namespace xrpl {
class PaymentSandbox;
class ReadView;
class ApplyView;
class AMMContext;
 
enum class DebtDirection { Issues, Redeems };
enum class QualityDirection { In, Out };
enum class StrandDirection { Forward, Reverse };
enum class OfferCrossing { No = 0, Yes = 1, Sell = 2 };
 
inline bool
redeems(DebtDirection dir)
{
    return dir == DebtDirection::Redeems;
}
 
inline bool
issues(DebtDirection dir)
{
    return dir == DebtDirection::Issues;
}

class Step
{
public:
    virtual ~Step() = default;

    virtual std::pair<EitherAmount, EitherAmount>
    rev(PaymentSandbox& sb,
        ApplyView& afView,
        boost::container::flat_set<uint256>& ofrsToRm,
        EitherAmount const& out) = 0;

    virtual std::pair<EitherAmount, EitherAmount>
    fwd(PaymentSandbox& sb,
        ApplyView& afView,
        boost::container::flat_set<uint256>& ofrsToRm,
        EitherAmount const& in) = 0;

    [[nodiscard]] virtual std::optional<EitherAmount>
    cachedIn() const = 0;

    [[nodiscard]] virtual std::optional<EitherAmount>
    cachedOut() const = 0;

    [[nodiscard]] virtual std::optional<AccountID>
    directStepSrcAcct() const
    {
        return std::nullopt;
    }
 
    // for debugging. Return the src and dst accounts for a direct step
    // For XRP endpoints, one of src or dst will be the root account
    [[nodiscard]] virtual std::optional<std::pair<AccountID, AccountID>>
    directStepAccts() const
    {
        return std::nullopt;
    }

    [[nodiscard]] virtual DebtDirection
    debtDirection(ReadView const& sb, StrandDirection dir) const = 0;

    [[nodiscard]] virtual std::uint32_t
    lineQualityIn(ReadView const&) const
    {
        return QUALITY_ONE;
    }

    [[nodiscard]] virtual std::pair<std::optional<Quality>, DebtDirection>
    qualityUpperBound(ReadView const& v, DebtDirection prevStepDir) const = 0;

    [[nodiscard]] virtual std::pair<std::optional<QualityFunction>, DebtDirection>
    getQualityFunc(ReadView const& v, DebtDirection prevStepDir) const;

    [[nodiscard]] virtual std::uint32_t
    offersUsed() const
    {
        return 0;
    }

    [[nodiscard]] virtual std::optional<Book>
    bookStepBook() const
    {
        return std::nullopt;
    }

    [[nodiscard]] virtual bool
    isZero(EitherAmount const& out) const = 0;

    [[nodiscard]] virtual bool
    inactive() const
    {
        return false;
    }

    [[nodiscard]] virtual bool
    equalOut(EitherAmount const& lhs, EitherAmount const& rhs) const = 0;

    [[nodiscard]] virtual bool
    equalIn(EitherAmount const& lhs, EitherAmount const& rhs) const = 0;

    virtual std::pair<bool, EitherAmount>
    validFwd(PaymentSandbox& sb, ApplyView& afView, EitherAmount const& in) = 0;

    friend bool
    operator==(Step const& lhs, Step const& rhs)
    {
        return lhs.equal(rhs);
    }

    friend std::ostream&
    operator<<(std::ostream& stream, Step const& step)
    {
        stream << step.logString();
        return stream;
    }
 
private:
    [[nodiscard]] virtual std::string
    logString() const = 0;
 
    [[nodiscard]] virtual bool
    equal(Step const& rhs) const = 0;
};
 
inline std::pair<std::optional<QualityFunction>, DebtDirection>
Step::getQualityFunc(ReadView const& v, DebtDirection prevStepDir) const
{
    auto const res = qualityUpperBound(v, prevStepDir);
    if (res.first)
        return {QualityFunction{*res.first, QualityFunction::CLOBLikeTag{}}, res.second};
    return {std::nullopt, res.second};
}

using Strand = std::vector<std::unique_ptr<Step>>;
 
inline std::uint32_t
offersUsed(Strand const& strand)
{
    std::uint32_t r = 0;
    for (auto const& step : strand)
    {
        if (step)
            r += step->offersUsed();
    }
    return r;
}

inline bool
operator==(Strand const& lhs, Strand const& rhs)
{
    if (lhs.size() != rhs.size())
        return false;
    for (size_t i = 0, e = lhs.size(); i != e; ++i)
    {
        if (*lhs[i] != *rhs[i])
            return false;
    }
    return true;
}

std::pair<TER, STPath>
normalizePath(
    AccountID const& src,
    AccountID const& dst,
    Asset const& deliver,
    std::optional<Asset> const& sendMaxAsset,
    STPath const& path);

std::pair<TER, Strand>
toStrand(
    ReadView const& sb,
    AccountID const& src,
    AccountID const& dst,
    Asset const& deliver,
    std::optional<Quality> const& limitQuality,
    std::optional<Asset> const& sendMaxAsset,
    STPath const& path,
    bool ownerPaysTransferFee,
    OfferCrossing offerCrossing,
    AMMContext& ammContext,
    std::optional<uint256> const& domainID,
    beast::Journal j);

std::pair<TER, std::vector<Strand>>
toStrands(
    ReadView const& sb,
    AccountID const& src,
    AccountID const& dst,
    Asset const& deliver,
    std::optional<Quality> const& limitQuality,
    std::optional<Asset> const& sendMax,
    STPathSet const& paths,
    bool addDefaultPath,
    bool ownerPaysTransferFee,
    OfferCrossing offerCrossing,
    AMMContext& ammContext,
    std::optional<uint256> const& domainID,
    beast::Journal j);

template <StepAmount TIn, StepAmount TOut, class TDerived>
struct StepImp : public Step
{
private:
    explicit StepImp() = default;
 
public:
    std::pair<EitherAmount, EitherAmount>
    rev(PaymentSandbox& sb,
        ApplyView& afView,
        boost::container::flat_set<uint256>& ofrsToRm,
        EitherAmount const& out) override
    {
        auto const r = static_cast<TDerived*>(this)->revImp(sb, afView, ofrsToRm, get<TOut>(out));
        return {EitherAmount(r.first), EitherAmount(r.second)};
    }
 
    // Given the requested amount to consume, compute the amount produced.
    // Return the consumed/produced
    std::pair<EitherAmount, EitherAmount>
    fwd(PaymentSandbox& sb,
        ApplyView& afView,
        boost::container::flat_set<uint256>& ofrsToRm,
        EitherAmount const& in) override
    {
        auto const r = static_cast<TDerived*>(this)->fwdImp(sb, afView, ofrsToRm, get<TIn>(in));
        return {EitherAmount(r.first), EitherAmount(r.second)};
    }
 
    [[nodiscard]] bool
    isZero(EitherAmount const& out) const override
    {
        return get<TOut>(out) == beast::kZero;
    }
 
    [[nodiscard]] bool
    equalOut(EitherAmount const& lhs, EitherAmount const& rhs) const override
    {
        return get<TOut>(lhs) == get<TOut>(rhs);
    }
 
    [[nodiscard]] bool
    equalIn(EitherAmount const& lhs, EitherAmount const& rhs) const override
    {
        return get<TIn>(lhs) == get<TIn>(rhs);
    }
    friend TDerived;
};

// Thrown when unexpected errors occur
class FlowException : public std::runtime_error
{
public:
    TER ter;
 
    FlowException(TER t, std::string const& msg) : std::runtime_error(msg), ter(t)
    {
    }
 
    explicit FlowException(TER t) : std::runtime_error(transHuman(t)), ter(t)
    {
    }
};

// Check equal with tolerance
bool
checkNear(IOUAmount const& expected, IOUAmount const& actual);
inline bool
checkNear(MPTAmount const& expected, MPTAmount const& actual)
{
    return expected == actual;
}
inline bool
checkNear(XRPAmount const& expected, XRPAmount const& actual)
{
    return expected == actual;
}

struct StrandContext
{
    ReadView const& view;                       
    AccountID const strandSrc;                  
    AccountID const strandDst;                  
    Asset const strandDeliver;                  
    std::optional<Quality> const limitQuality;  
    bool const isFirst;                         
    bool const isLast = false;                  
    bool const ownerPaysTransferFee;            
    OfferCrossing const offerCrossing;          
    bool const isDefaultPath;                   
    size_t const strandSize;                    
    Step const* const prevStep = nullptr;
    std::array<boost::container::flat_set<Asset>, 2>& seenDirectAssets;
    boost::container::flat_set<Asset>& seenBookOuts;
    AMMContext& ammContext;
    std::optional<uint256> domainID;  // the domain the order book will use
    beast::Journal const j;

    StrandContext(
        ReadView const& view,
        std::vector<std::unique_ptr<Step>> const& strand,
        // A strand may not include an inner node that
        // replicates the source or destination.
        AccountID const& strandSrc,
        AccountID const& strandDst,
        Asset const& strandDeliver,
        std::optional<Quality> const& limitQuality,
        bool isLast,
        bool ownerPaysTransferFee,
        OfferCrossing offerCrossing,
        bool isDefaultPath,
        std::array<boost::container::flat_set<Asset>, 2>&
            seenDirectAssets,                             
        boost::container::flat_set<Asset>& seenBookOuts,  
        AMMContext& ammContext,
        std::optional<uint256> const& domainID,
        beast::Journal j);  
};

namespace test {
// Needed for testing
bool
directStepEqual(
    Step const& step,
    AccountID const& src,
    AccountID const& dst,
    Currency const& currency);
 
bool
mptEndpointStepEqual(
    Step const& step,
    AccountID const& src,
    AccountID const& dst,
    MPTID const& mptid);
 
bool
xrpEndpointStepEqual(Step const& step, AccountID const& acc);
 
bool
bookStepEqual(Step const& step, xrpl::Book const& book);
}  // namespace test
 
std::pair<TER, std::unique_ptr<Step>>
makeDirectStepI(
    StrandContext const& ctx,
    AccountID const& src,
    AccountID const& dst,
    Currency const& c);
 
std::pair<TER, std::unique_ptr<Step>>
makeMptEndpointStep(
    StrandContext const& ctx,
    AccountID const& src,
    AccountID const& dst,
    MPTID const& a);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepIi(StrandContext const& ctx, Issue const& in, Issue const& out);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepIx(StrandContext const& ctx, Issue const& in);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepXi(StrandContext const& ctx, Issue const& out);
 
std::pair<TER, std::unique_ptr<Step>>
makeXrpEndpointStep(StrandContext const& ctx, AccountID const& acc);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepMm(StrandContext const& ctx, MPTIssue const& in, MPTIssue const& out);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepMx(StrandContext const& ctx, MPTIssue const& in);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepXm(StrandContext const& ctx, MPTIssue const& out);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepMi(StrandContext const& ctx, MPTIssue const& in, Issue const& out);
 
std::pair<TER, std::unique_ptr<Step>>
makeBookStepIm(StrandContext const& ctx, Issue const& in, MPTIssue const& out);
 
template <StepAmount InAmt, StepAmount OutAmt>
bool
isDirectXrpToXrp(Strand const& strand)
{
    if constexpr (std::is_same_v<InAmt, XRPAmount> && std::is_same_v<OutAmt, XRPAmount>)
    {
        return strand.size() == 2;
    }
    else
    {
        return false;
    }
}
 
}  // namespace xrpl