A step in a payment path. More...

#include <Steps.h>

Public Member Functions
virtual	~Step ()=default
virtual std::pair< EitherAmount, EitherAmount >	rev (PaymentSandbox &sb, ApplyView &afView, boost::container::flat_set< uint256 > &ofrsToRm, EitherAmount const &out)=0
	Find the amount we need to put into the step to get the requested out subject to liquidity limits.
virtual std::pair< EitherAmount, EitherAmount >	fwd (PaymentSandbox &sb, ApplyView &afView, boost::container::flat_set< uint256 > &ofrsToRm, EitherAmount const &in)=0
	Find the amount we get out of the step given the input subject to liquidity limits.
virtual std::optional< EitherAmount >	cachedIn () const =0
	Amount of currency computed coming into the Step the last time the step ran in reverse.
virtual std::optional< EitherAmount >	cachedOut () const =0
	Amount of currency computed coming out of the Step the last time the step ran in reverse.
virtual std::optional< AccountID >	directStepSrcAcct () const
	If this step is DirectStepI (IOU->IOU direct step), return the src account.
virtual std::optional< std::pair< AccountID, AccountID > >	directStepAccts () const
virtual DebtDirection	debtDirection (ReadView const &sb, StrandDirection dir) const =0
	If this step is a DirectStepI and the src redeems to the dst, return true, otherwise return false.
virtual std::uint32_t	lineQualityIn (ReadView const &) const
	If this step is a DirectStepI, return the quality in of the dst account.
virtual std::pair< std::optional< Quality >, DebtDirection >	qualityUpperBound (ReadView const &v, DebtDirection prevStepDir) const =0
	Find an upper bound of quality for the step.
virtual std::pair< std::optional< QualityFunction >, DebtDirection >	getQualityFunc (ReadView const &v, DebtDirection prevStepDir) const
	Get QualityFunction.
virtual std::uint32_t	offersUsed () const
	Return the number of offers consumed or partially consumed the last time the step ran, including expired and unfunded offers.
virtual std::optional< Book >	bookStepBook () const
	If this step is a BookStep, return the book.
virtual bool	isZero (EitherAmount const &out) const =0
	Check if amount is zero.
virtual bool	inactive () const
	Return true if the step should be considered inactive.
virtual bool	equalOut (EitherAmount const &lhs, EitherAmount const &rhs) const =0
	Return true if Out of lhs == Out of rhs.
virtual bool	equalIn (EitherAmount const &lhs, EitherAmount const &rhs) const =0
	Return true if In of lhs == In of rhs.
virtual std::pair< bool, EitherAmount >	validFwd (PaymentSandbox &sb, ApplyView &afView, EitherAmount const &in)=0
	Check that the step can correctly execute in the forward direction.

Private Member Functions
virtual std::string	logString () const =0
virtual bool	equal (Step const &rhs) const =0

Friends
bool	operator== (Step const &lhs, Step const &rhs)
	Return true if lhs == rhs.
bool	operator!= (Step const &lhs, Step const &rhs)
	Return true if lhs != rhs.
std::ostream &	operator<< (std::ostream &stream, Step const &step)
	Streaming operator for a Step.

Detailed Description

A step in a payment path.

There are five concrete step classes: DirectStepI is an IOU step between accounts BookStepII is an IOU/IOU offer book BookStepIX is an IOU/XRP offer book BookStepXI is an XRP/IOU offer book XRPEndpointStep is the source or destination account for XRP MPTEndpointStep is the source or destination account for MPT

Amounts may be transformed through a step in either the forward or the reverse direction. In the forward direction, the function fwd is used to find the amount the step would output given an input amount. In the reverse direction, the function rev is used to find the amount of input needed to produce the desired output.

Amounts are always transformed using liquidity with the same quality (quality is the amount out/amount in). For example, a BookStep may use multiple offers when executing fwd or rev, but all those offers will be from the same quality directory.

A step may not have enough liquidity to transform the entire requested amount. Both fwd and rev return a pair of amounts (one for input amount, one for output amount) that show how much of the requested amount the step was actually able to use.

Definition at line 65 of file Steps.h.

Constructor & Destructor Documentation

◆ ~Step()

virtual xrpl::Step::~Step ( )

virtualdefault

Member Function Documentation

◆ rev()

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

pure virtual

Find the amount we need to put into the step to get the requested out subject to liquidity limits.

Parameters

sb	view with the strand's state of balances and offers
afView	view the state of balances before the strand runs this determines if an offer becomes unfunded or is found unfunded
ofrsToRm	offers found unfunded or in an error state are added to this collection
out	requested step output

Returns: actual step input and output

◆ fwd()

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

pure virtual

Find the amount we get out of the step given the input subject to liquidity limits.

Parameters

sb	view with the strand's state of balances and offers
afView	view the state of balances before the strand runs this determines if an offer becomes unfunded or is found unfunded
ofrsToRm	offers found unfunded or in an error state are added to this collection
in	requested step input

Returns: actual step input and output

◆ cachedIn()

virtual std::optional< EitherAmount > xrpl::Step::cachedIn ( ) const

nodiscardpure virtual

Amount of currency computed coming into the Step the last time the step ran in reverse.

◆ cachedOut()

virtual std::optional< EitherAmount > xrpl::Step::cachedOut ( ) const

nodiscardpure virtual

Amount of currency computed coming out of the Step the last time the step ran in reverse.

◆ directStepSrcAcct()

virtual std::optional< AccountID > xrpl::Step::directStepSrcAcct ( ) const

nodiscardvirtual

If this step is DirectStepI (IOU->IOU direct step), return the src account.

This is needed for checkNoRipple.

Definition at line 125 of file Steps.h.

◆ directStepAccts()

virtual std::optional< std::pair< AccountID, AccountID > > xrpl::Step::directStepAccts ( ) const

nodiscardvirtual

Definition at line 133 of file Steps.h.

◆ debtDirection()

virtual DebtDirection xrpl::Step::debtDirection	(	ReadView const &	sb,
		StrandDirection	dir ) const

nodiscardpure virtual

If this step is a DirectStepI and the src redeems to the dst, return true, otherwise return false.

If this step is a BookStep, return false if the owner pays the transfer fee, otherwise return true.

Parameters

sb	view with the strand's state of balances and offers
dir	reverse -> called from rev(); forward -> called from fwd().

◆ lineQualityIn()

virtual std::uint32_t xrpl::Step::lineQualityIn ( ReadView const & ) const

nodiscardvirtual

If this step is a DirectStepI, return the quality in of the dst account.

Definition at line 153 of file Steps.h.

◆ qualityUpperBound()

virtual std::pair< std::optional< Quality >, DebtDirection > xrpl::Step::qualityUpperBound	(	ReadView const &	v,
		DebtDirection	prevStepDir ) const

nodiscardpure virtual

Find an upper bound of quality for the step.

Parameters

v	view to query the ledger state from
prevStepDir	Set to DebtDirection::redeems if the previous step redeems.

Returns: A pair. The first element is the upper bound of quality for the step, or std::nullopt if the step is dry. The second element will be set to DebtDirection::redeems if this steps redeems, DebtDirection:issues if this step issues.

Note: It is an upper bound because offers on the books may be unfunded. If there is always a funded offer at the tip of the book, then we could rename this theoreticalQuality rather than qualityUpperBound. It could still differ from the actual quality, but except for "dust" amounts, it should be a good estimate for the actual quality.

◆ getQualityFunc()

std::pair< std::optional< QualityFunction >, DebtDirection > xrpl::Step::getQualityFunc	(	ReadView const &	v,
		DebtDirection	prevStepDir ) const

nodiscardvirtual

Get QualityFunction.

Used in one path optimization where the quality function is non-constant (has AMM) and there is limitQuality. QualityFunction allows calculation of required path output given requested limitQuality. All steps, except for BookStep have the default implementation.

Definition at line 289 of file Steps.h.

◆ offersUsed()

virtual std::uint32_t xrpl::Step::offersUsed ( ) const

nodiscardvirtual

Return the number of offers consumed or partially consumed the last time the step ran, including expired and unfunded offers.

N.B. This this not the total number offers consumed by this step for the entire payment, it is only the number the last time it ran. Offers may be partially consumed multiple times during a payment.

Definition at line 192 of file Steps.h.

◆ bookStepBook()

virtual std::optional< Book > xrpl::Step::bookStepBook ( ) const

nodiscardvirtual

If this step is a BookStep, return the book.

Definition at line 201 of file Steps.h.

◆ isZero()

virtual bool xrpl::Step::isZero ( EitherAmount const & out ) const

nodiscardpure virtual

Check if amount is zero.

◆ inactive()

virtual bool xrpl::Step::inactive ( ) const

nodiscardvirtual

Return true if the step should be considered inactive.

A strand that has additional liquidity may be marked inactive if a step has consumed too many offers.

Definition at line 218 of file Steps.h.

◆ equalOut()

virtual bool xrpl::Step::equalOut	(	EitherAmount const &	lhs,
		EitherAmount const &	rhs ) const

nodiscardpure virtual

Return true if Out of lhs == Out of rhs.

◆ equalIn()

virtual bool xrpl::Step::equalIn	(	EitherAmount const &	lhs,
		EitherAmount const &	rhs ) const

nodiscardpure virtual

Return true if In of lhs == In of rhs.

◆ validFwd()

virtual std::pair< bool, EitherAmount > xrpl::Step::validFwd	(	PaymentSandbox &	sb,
		ApplyView &	afView,
		EitherAmount const &	in )

pure virtual

Check that the step can correctly execute in the forward direction.

Parameters

sb	view with the strands state of balances and offers
afView	view the state of balances before the strand runs this determines if an offer becomes unfunded or is found unfunded
in	requested step input

Returns: first element is true if step is valid, second element is out amount

◆ logString()

virtual std::string xrpl::Step::logString ( ) const

nodiscardprivatepure virtual

◆ equal()

virtual bool xrpl::Step::equal ( Step const & rhs ) const

nodiscardprivatepure virtual

◆ operator==

bool operator==	(	Step const &	lhs,
		Step const &	rhs )

friend

Return true if lhs == rhs.

Parameters

lhs	Step to compare.
rhs	Step to compare.

Returns: true if lhs == rhs.

Definition at line 255 of file Steps.h.

◆ operator!=

bool operator!=	(	Step const &	lhs,
		Step const &	rhs )

friend

Return true if lhs != rhs.

Parameters

lhs	Step to compare.
rhs	Step to compare.

Returns: true if lhs != rhs.

Definition at line 267 of file Steps.h.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	stream,
		Step const &	step )

friend

Streaming operator for a Step.

Definition at line 273 of file Steps.h.

Public Member Functions

Private Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~Step()

Member Function Documentation

◆ rev()

◆ fwd()

◆ cachedIn()

◆ cachedOut()

◆ directStepSrcAcct()

◆ directStepAccts()

◆ debtDirection()

◆ lineQualityIn()

◆ qualityUpperBound()

◆ getQualityFunc()

◆ offersUsed()

◆ bookStepBook()

◆ isZero()

◆ inactive()

◆ equalOut()

◆ equalIn()

◆ validFwd()

◆ logString()

◆ equal()

Friends And Related Symbol Documentation

◆ operator==

◆ operator!=

◆ operator<<