Steps.h

//------------------------------------------------------------------------------
/*
    This file is part of rippled: https://github.com/ripple/rippled
    Copyright (c) 2012, 2013 Ripple Labs Inc.
 
    Permission to use, copy, modify, and/or distribute this software for any
    purpose  with  or without fee is hereby granted, provided that the above
    copyright notice and this permission notice appear in all copies.
 
    THE  SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    WITH  REGARD  TO  THIS  SOFTWARE  INCLUDING  ALL  IMPLIED  WARRANTIES  OF
    MERCHANTABILITY  AND  FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    ANY  SPECIAL ,  DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    WHATSOEVER  RESULTING  FROM  LOSS  OF USE, DATA OR PROFITS, WHETHER IN AN
    ACTION  OF  CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/
//==============================================================================
 
#ifndef RIPPLE_APP_PATHS_IMPL_PAYSTEPS_H_INCLUDED
#define RIPPLE_APP_PATHS_IMPL_PAYSTEPS_H_INCLUDED
 
#include <ripple/app/paths/impl/AmountSpec.h>
#include <ripple/basics/Log.h>
#include <ripple/protocol/Quality.h>
#include <ripple/protocol/STLedgerEntry.h>
#include <ripple/protocol/TER.h>
 
#include <boost/container/flat_set.hpp>
#include <optional>
 
namespace ripple {
class PaymentSandbox;
class ReadView;
class ApplyView;
 
enum class DebtDirection { issues, redeems };
enum class QualityDirection { in, out };
enum class StrandDirection { forward, reverse };
 
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::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;
};
 
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,
    bool offerCrossing,
    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,
    bool offerCrossing,
    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;  
    bool 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;
    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_,
        bool offerCrossing_,
        bool isDefaultPath_,
        std::array<boost::container::flat_set<Issue>, 2>&
            seenDirectIssues_,  
        boost::container::flat_set<Issue>&
            seenBookOuts_,   
        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, ripple::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 ripple
 
#endif