Steps.h

#pragma once
 
#include <xrpld/app/paths/detail/AmountSpec.h>
 
#include <xrpl/basics/Log.h>
#include <xrpl/basics/base_uint.h>
#include <xrpl/protocol/Quality.h>
#include <xrpl/protocol/QualityFunction.h>
#include <xrpl/protocol/STLedgerEntry.h>
#include <xrpl/protocol/TER.h>
 
#include <boost/container/flat_set.hpp>
 
#include <optional>
 
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 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;
 
    virtual std::optional<EitherAmount>
    cachedIn() const = 0;
 
    virtual std::optional<EitherAmount>
    cachedOut() const = 0;
 
    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
    virtual std::optional<std::pair<AccountID, AccountID>>
    directStepAccts() const
    {
        return std::nullopt;
    }
 
    virtual DebtDirection
    debtDirection(ReadView const& sb, StrandDirection dir) const = 0;
 
    virtual std::uint32_t
    lineQualityIn(ReadView const&) const
    {
        return QUALITY_ONE;
    }
 
    // clang-format off
    // clang-format on
    virtual std::pair<std::optional<Quality>, DebtDirection>
    qualityUpperBound(ReadView const& v, DebtDirection prevStepDir) const = 0;
 
    virtual std::pair<std::optional<QualityFunction>, DebtDirection>
    getQualityFunc(ReadView const& v, DebtDirection prevStepDir) const;
 
    virtual std::uint32_t
    offersUsed() const
    {
        return 0;
    }
 
    virtual std::optional<Book>
    bookStepBook() const
    {
        return std::nullopt;
    }
 
    virtual bool
    isZero(EitherAmount const& out) const = 0;
 
    virtual bool
    inactive() const
    {
        return false;
    }
 
    virtual bool
    equalOut(EitherAmount const& lhs, EitherAmount const& rhs) const = 0;
 
    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 bool
    operator!=(Step const& lhs, Step const& rhs)
    {
        return !(lhs == rhs);
    }
 
    friend std::ostream&
    operator<<(std::ostream& stream, Step const& step)
    {
        stream << step.logString();
        return stream;
    }
 
private:
    virtual std::string
    logString() const = 0;
 
    virtual bool
    equal(Step const& rhs) const = 0;
};
 
inline std::pair<std::optional<QualityFunction>, DebtDirection>
Step::getQualityFunc(ReadView const& v, DebtDirection prevStepDir) const
{
    if (auto const res = qualityUpperBound(v, prevStepDir); res.first)
        return {QualityFunction{*res.first, QualityFunction::CLOBLikeTag{}}, res.second};
    else
        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;
}
 
/*
   Normalize a path by inserting implied accounts and offers
 
   @param src Account that is sending assets
   @param dst Account that is receiving assets
   @param deliver Asset the dst account will receive
   (if issuer of deliver == dst, then accept any issuer)
   @param sendMax Optional asset to send.
   @param path Liquidity sources to use for this strand of the payment. The path
               contains an ordered collection of the offer books to use and
               accounts to ripple through.
   @return error code and normalized path
*/
std::pair<TER, STPath>
normalizePath(
    AccountID const& src,
    AccountID const& dst,
    Issue const& deliver,
    std::optional<Issue> const& sendMaxIssue,
    STPath const& path);
 
std::pair<TER, Strand>
toStrand(
    ReadView const& sb,
    AccountID const& src,
    AccountID const& dst,
    Issue const& deliver,
    std::optional<Quality> const& limitQuality,
    std::optional<Issue> const& sendMaxIssue,
    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,
    Issue const& deliver,
    std::optional<Quality> const& limitQuality,
    std::optional<Issue> const& sendMax,
    STPathSet const& paths,
    bool addDefaultPath,
    bool ownerPaysTransferFee,
    OfferCrossing offerCrossing,
    AMMContext& ammContext,
    std::optional<uint256> const& domainID,
    beast::Journal j);
 
template <class TIn, class TOut, class TDerived>
struct StepImp : public Step
{
    explicit StepImp() = default;
 
    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)};
    }
 
    bool
    isZero(EitherAmount const& out) const override
    {
        return get<TOut>(out) == beast::zero;
    }
 
    bool
    equalOut(EitherAmount const& lhs, EitherAmount const& rhs) const override
    {
        return get<TOut>(lhs) == get<TOut>(rhs);
    }
 
    bool
    equalIn(EitherAmount const& lhs, EitherAmount const& rhs) const override
    {
        return get<TIn>(lhs) == get<TIn>(rhs);
    }
};
 
// 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);
bool
checkNear(XRPAmount const& expected, XRPAmount const& actual);
 
struct StrandContext
{
    ReadView const& view;                       
    AccountID const strandSrc;                  
    AccountID const strandDst;                  
    Issue 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<Issue>, 2>& seenDirectIssues;
    boost::container::flat_set<Issue>& 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_,
        Issue const& strandDeliver_,
        std::optional<Quality> const& limitQuality_,
        bool isLast_,
        bool ownerPaysTransferFee_,
        OfferCrossing offerCrossing_,
        bool isDefaultPath_,
        std::array<boost::container::flat_set<Issue>, 2>& seenDirectIssues_,  
        boost::container::flat_set<Issue>& 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
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>>
make_DirectStepI(StrandContext const& ctx, AccountID const& src, AccountID const& dst, Currency const& c);
 
std::pair<TER, std::unique_ptr<Step>>
make_BookStepII(StrandContext const& ctx, Issue const& in, Issue const& out);
 
std::pair<TER, std::unique_ptr<Step>>
make_BookStepIX(StrandContext const& ctx, Issue const& in);
 
std::pair<TER, std::unique_ptr<Step>>
make_BookStepXI(StrandContext const& ctx, Issue const& out);
 
std::pair<TER, std::unique_ptr<Step>>
make_XRPEndpointStep(StrandContext const& ctx, AccountID const& acc);
 
template <class InAmt, class OutAmt>
bool
isDirectXrpToXrp(Strand const& strand);
 
}  // namespace xrpl