A wrapper which makes credits unavailable to balances. More...

#include <PaymentSandbox.h>

Inheritance diagram for ripple::PaymentSandbox:

[legend]

Collaboration diagram for ripple::PaymentSandbox:

[legend]

Public Types
using	tx_type = std::pair< std::shared_ptr< STTx const >, std::shared_ptr< STObject const > >

using	key_type = uint256

using	mapped_type = std::shared_ptr< SLE const >

Public Member Functions
	PaymentSandbox ()=delete

	PaymentSandbox (PaymentSandbox const &)=delete

PaymentSandbox &	operator= (PaymentSandbox &&)=delete

PaymentSandbox &	operator= (PaymentSandbox const &)=delete

	PaymentSandbox (PaymentSandbox &&)=default

	PaymentSandbox (ReadView const *base, ApplyFlags flags)

	PaymentSandbox (ApplyView const *base)

STAmount	balanceHook (AccountID const &account, AccountID const &issuer, STAmount const &amount) const override

void	creditHook (AccountID const &from, AccountID const &to, STAmount const &amount, STAmount const &preCreditBalance) override

void	adjustOwnerCountHook (AccountID const &account, std::uint32_t cur, std::uint32_t next) override

std::uint32_t	ownerCountHook (AccountID const &account, std::uint32_t count) const override

std::map< std::tuple< AccountID, AccountID, Currency >, STAmount >	balanceChanges (ReadView const &view) const

XRPAmount	xrpDestroyed () const

bool	open () const override
	Returns true if this reflects an open ledger.

LedgerInfo const &	info () const override
	Returns information about the ledger.

Fees const &	fees () const override
	Returns the fees for the base ledger.

Rules const &	rules () const override
	Returns the tx processing rules.

bool	exists (Keylet const &k) const override
	Determine if a state item exists.

std::optional< key_type >	succ (key_type const &key, std::optional< key_type > const &last=std::nullopt) const override
	Return the key of the next state item.

std::shared_ptr< SLE const >	read (Keylet const &k) const override
	Return the state item associated with a key.

std::unique_ptr< sles_type::iter_base >	slesBegin () const override

std::unique_ptr< sles_type::iter_base >	slesEnd () const override

std::unique_ptr< sles_type::iter_base >	slesUpperBound (uint256 const &key) const override

virtual std::unique_ptr< sles_type::iter_base >	slesUpperBound (key_type const &key) const =0

std::unique_ptr< txs_type::iter_base >	txsBegin () const override

std::unique_ptr< txs_type::iter_base >	txsEnd () const override

bool	txExists (key_type const &key) const override
	Returns `true` if a tx exists in the tx map.

tx_type	txRead (key_type const &key) const override
	Read a transaction from the tx map.

ApplyFlags	flags () const override
	Returns the tx apply flags.

std::shared_ptr< SLE >	peek (Keylet const &k) override
	Prepare to modify the SLE associated with key.

void	erase (std::shared_ptr< SLE > const &sle) override
	Remove a peeked SLE.

void	insert (std::shared_ptr< SLE > const &sle) override
	Insert a new state SLE.

void	update (std::shared_ptr< SLE > const &sle) override
	Indicate changes to a peeked SLE.

void	rawErase (std::shared_ptr< SLE > const &sle) override
	Delete an existing state item.

void	rawInsert (std::shared_ptr< SLE > const &sle) override
	Unconditionally insert a state item.

void	rawReplace (std::shared_ptr< SLE > const &sle) override
	Unconditionally replace a state item.

void	rawDestroyXRP (XRPAmount const &feeDrops) override
	Destroy XRP.

bool	dirDelete (Keylet const &directory, std::function< void(uint256 const &)> const &)
	Remove the specified directory, invoking the callback for every node.

bool	emptyDirDelete (Keylet const &directory)
	Remove the specified directory, if it is empty.

NetClock::time_point	parentCloseTime () const
	Returns the close time of the previous ledger.

LedgerIndex	seq () const
	Returns the sequence number of the base ledger.


	PaymentSandbox (PaymentSandbox const *base)
	Construct on top of existing PaymentSandbox.

	PaymentSandbox (PaymentSandbox *base)


void	apply (RawView &to)
	Apply changes to base view.

void	apply (PaymentSandbox &to)


std::optional< std::uint64_t >	dirAppend (Keylet const &directory, Keylet const &key, std::function< void(std::shared_ptr< SLE > const &)> const &describe)
	Append an entry to a directory.


std::optional< std::uint64_t >	dirInsert (Keylet const &directory, uint256 const &key, std::function< void(std::shared_ptr< SLE > const &)> const &describe)
	Insert an entry to a directory.

std::optional< std::uint64_t >	dirInsert (Keylet const &directory, Keylet const &key, std::function< void(std::shared_ptr< SLE > const &)> const &describe)


bool	dirRemove (Keylet const &directory, std::uint64_t page, uint256 const &key, bool keepRoot)
	Remove an entry from a directory.

bool	dirRemove (Keylet const &directory, std::uint64_t page, Keylet const &key, bool keepRoot)

Public Attributes
sles_type	sles
	Iterable range of ledger state items.

txs_type	txs

Protected Attributes
ApplyFlags	flags_

ReadView const *	base_

detail::ApplyStateTable	items_

Private Member Functions
std::optional< std::uint64_t >	dirAdd (bool preserveOrder, Keylet const &directory, uint256 const &key, std::function< void(std::shared_ptr< SLE > const &)> const &describe)
	Add an entry to a directory using the specified insert strategy.

Private Attributes
detail::DeferredCredits	tab_

PaymentSandbox const *	ps_ = nullptr

Detailed Description

A wrapper which makes credits unavailable to balances.

This is used for payments and pathfinding, so that consuming liquidity from a path never causes portions of that path or other paths to gain liquidity.

The behavior of certain free functions in the ApplyView API will change via the balanceHook and creditHook overrides of PaymentSandbox.

Note: Presented as ApplyView to clients

Definition at line 112 of file PaymentSandbox.h.

Member Typedef Documentation

◆ tx_type

using ripple::ReadView::tx_type = std::pair<std::shared_ptr<STTx const>, std::shared_ptr<STObject const> >

inherited

Definition at line 53 of file ReadView.h.

◆ key_type

using ripple::ReadView::key_type = uint256

inherited

Definition at line 56 of file ReadView.h.

◆ mapped_type

using ripple::ReadView::mapped_type = std::shared_ptr<SLE const>

inherited

Definition at line 58 of file ReadView.h.

Constructor & Destructor Documentation

◆ PaymentSandbox() [1/7]

ripple::PaymentSandbox::PaymentSandbox ( )

delete

◆ PaymentSandbox() [2/7]

ripple::PaymentSandbox::PaymentSandbox ( PaymentSandbox const & )

delete

◆ PaymentSandbox() [3/7]

ripple::PaymentSandbox::PaymentSandbox ( PaymentSandbox && )

default

◆ PaymentSandbox() [4/7]

ripple::PaymentSandbox::PaymentSandbox	(	ReadView const *	base,
		ApplyFlags	flags
	)

Definition at line 124 of file PaymentSandbox.h.

◆ PaymentSandbox() [5/7]

ripple::PaymentSandbox::PaymentSandbox ( ApplyView const * base )

Definition at line 129 of file PaymentSandbox.h.

◆ PaymentSandbox() [6/7]

ripple::PaymentSandbox::PaymentSandbox ( PaymentSandbox const * base )

explicit

Construct on top of existing PaymentSandbox.

The changes are pushed to the parent when apply() is called.

Parameters

parent A non-null pointer to the parent.

Note: A pointer is used to prevent confusion with copy construction.

Definition at line 147 of file PaymentSandbox.h.

◆ PaymentSandbox() [7/7]

ripple::PaymentSandbox::PaymentSandbox ( PaymentSandbox * base )

explicit

Definition at line 152 of file PaymentSandbox.h.

Member Function Documentation

◆ operator=() [1/2]

PaymentSandbox & ripple::PaymentSandbox::operator= ( PaymentSandbox && )

delete

◆ operator=() [2/2]

PaymentSandbox & ripple::PaymentSandbox::operator= ( PaymentSandbox const & )

delete

◆ balanceHook()

STAmount ripple::PaymentSandbox::balanceHook	(	AccountID const &	account,
		AccountID const &	issuer,
		STAmount const &	amount
	)		const

overridevirtual

Reimplemented from ripple::ReadView.

Definition at line 172 of file PaymentSandbox.cpp.

◆ creditHook()

void ripple::PaymentSandbox::creditHook	(	AccountID const &	from,
		AccountID const &	to,
		STAmount const &	amount,
		STAmount const &	preCreditBalance
	)

overridevirtual

Reimplemented from ripple::ApplyView.

Definition at line 235 of file PaymentSandbox.cpp.

◆ adjustOwnerCountHook()

void ripple::PaymentSandbox::adjustOwnerCountHook	(	AccountID const &	account,
		std::uint32_t	cur,
		std::uint32_t	next
	)

overridevirtual

Reimplemented from ripple::ApplyView.

Definition at line 245 of file PaymentSandbox.cpp.

◆ ownerCountHook()

std::uint32_t ripple::PaymentSandbox::ownerCountHook	(	AccountID const &	account,
		std::uint32_t	count
	)		const

overridevirtual

Reimplemented from ripple::ReadView.

Definition at line 222 of file PaymentSandbox.cpp.

◆ apply() [1/2]

void ripple::PaymentSandbox::apply ( RawView & to )

Apply changes to base view.

to must contain contents identical to the parent view passed upon construction, else undefined behavior will result.

Definition at line 254 of file PaymentSandbox.cpp.

◆ apply() [2/2]

void ripple::PaymentSandbox::apply ( PaymentSandbox & to )

Definition at line 261 of file PaymentSandbox.cpp.

◆ balanceChanges()

std::map< std::tuple< AccountID, AccountID, Currency >, STAmount > ripple::PaymentSandbox::balanceChanges ( ReadView const & view ) const

Definition at line 269 of file PaymentSandbox.cpp.

◆ xrpDestroyed()

XRPAmount ripple::PaymentSandbox::xrpDestroyed ( ) const

Definition at line 394 of file PaymentSandbox.cpp.

◆ open()

bool ripple::detail::ApplyViewBase::open ( ) const

overridevirtualinherited

Returns true if this reflects an open ledger.

Implements ripple::ReadView.

Definition at line 33 of file ApplyViewBase.cpp.

◆ info()

LedgerInfo const & ripple::detail::ApplyViewBase::info ( ) const

overridevirtualinherited

Returns information about the ledger.

Implements ripple::ReadView.

Definition at line 39 of file ApplyViewBase.cpp.

◆ fees()

Fees const & ripple::detail::ApplyViewBase::fees ( ) const

overridevirtualinherited

Returns the fees for the base ledger.

Implements ripple::ReadView.

Definition at line 45 of file ApplyViewBase.cpp.

◆ rules()

Rules const & ripple::detail::ApplyViewBase::rules ( ) const

overridevirtualinherited

Returns the tx processing rules.

Implements ripple::ReadView.

Definition at line 51 of file ApplyViewBase.cpp.

◆ exists()

bool ripple::detail::ApplyViewBase::exists ( Keylet const & k ) const

overridevirtualinherited

Determine if a state item exists.

Note: This can be more efficient than calling read.

Returns: true if a SLE is associated with the specified key.

Implements ripple::ReadView.

Definition at line 57 of file ApplyViewBase.cpp.

◆ succ()

auto ripple::detail::ApplyViewBase::succ	(	key_type const &	key,
		std::optional< key_type > const &	last = `std::nullopt`
	)		const

overridevirtualinherited

Return the key of the next state item.

This returns the key of the first state item whose key is greater than the specified key. If no such key is present, std::nullopt is returned.

If last is engaged, returns std::nullopt when the key returned would be outside the open interval (key, last).

Implements ripple::ReadView.

Definition at line 63 of file ApplyViewBase.cpp.

◆ read()

std::shared_ptr< SLE const > ripple::detail::ApplyViewBase::read ( Keylet const & k ) const

overridevirtualinherited

Return the state item associated with a key.

Effects: If the key exists, gives the caller ownership of the non-modifiable corresponding SLE.

Note: While the returned SLE is const from the perspective of the caller, it can be changed by other callers through raw operations.

Returns: nullptr if the key is not present or if the type does not match.

Implements ripple::ReadView.

Definition at line 70 of file ApplyViewBase.cpp.

◆ slesBegin()

auto ripple::detail::ApplyViewBase::slesBegin ( ) const

overridevirtualinherited

Implements ripple::ReadView.

Definition at line 76 of file ApplyViewBase.cpp.

◆ slesEnd()

auto ripple::detail::ApplyViewBase::slesEnd ( ) const

overridevirtualinherited

Implements ripple::ReadView.

Definition at line 82 of file ApplyViewBase.cpp.

◆ slesUpperBound() [1/2]

auto ripple::detail::ApplyViewBase::slesUpperBound ( uint256 const & key ) const

overrideinherited

Definition at line 88 of file ApplyViewBase.cpp.

◆ slesUpperBound() [2/2]

virtual std::unique_ptr< sles_type::iter_base > ripple::ReadView::slesUpperBound ( key_type const & key ) const

pure virtualinherited

◆ txsBegin()

auto ripple::detail::ApplyViewBase::txsBegin ( ) const

overridevirtualinherited

Implements ripple::ReadView.

Definition at line 95 of file ApplyViewBase.cpp.

◆ txsEnd()

auto ripple::detail::ApplyViewBase::txsEnd ( ) const

overridevirtualinherited

Implements ripple::ReadView.

Definition at line 101 of file ApplyViewBase.cpp.

◆ txExists()

bool ripple::detail::ApplyViewBase::txExists ( key_type const & key ) const

overridevirtualinherited

Returns true if a tx exists in the tx map.

A tx exists in the map if it is part of the base ledger, or if it is a newly inserted tx.

Implements ripple::ReadView.

Definition at line 107 of file ApplyViewBase.cpp.

◆ txRead()

auto ripple::detail::ApplyViewBase::txRead ( key_type const & key ) const

overridevirtualinherited

Read a transaction from the tx map.

If the view represents an open ledger, the metadata object will be empty.

Returns: A pair of nullptr if the key is not found in the tx map.

Implements ripple::ReadView.

Definition at line 113 of file ApplyViewBase.cpp.

◆ flags()

ApplyFlags ripple::detail::ApplyViewBase::flags ( ) const

overridevirtualinherited

Returns the tx apply flags.

Flags can affect the outcome of transaction processing. For example, transactions applied to an open ledger generate "local" failures, while transactions applied to the consensus ledger produce hard failures (and claim a fee).

Implements ripple::ApplyView.

Definition at line 121 of file ApplyViewBase.cpp.

◆ peek()

std::shared_ptr< SLE > ripple::detail::ApplyViewBase::peek ( Keylet const & k )

overridevirtualinherited

Prepare to modify the SLE associated with key.

Effects:

Gives the caller ownership of a modifiable
SLE associated with the specified key.

The returned SLE may be used in a subsequent call to erase or update.

The SLE must not be passed to any other ApplyView.

Returns: nullptr if the key is not present

Implements ripple::ApplyView.

Definition at line 127 of file ApplyViewBase.cpp.

◆ erase()

void ripple::detail::ApplyViewBase::erase ( std::shared_ptr< SLE > const & sle )

overridevirtualinherited

Remove a peeked SLE.

Requirements:

`sle` was obtained from prior call to peek()
on this instance of the RawView.

Effects:

The key is no longer associated with the SLE.

Implements ripple::ApplyView.

Definition at line 133 of file ApplyViewBase.cpp.

◆ insert()

void ripple::detail::ApplyViewBase::insert ( std::shared_ptr< SLE > const & sle )

overridevirtualinherited

Insert a new state SLE.

Requirements:

`sle` was not obtained from any calls to
peek() on any instances of RawView.

The SLE's key must not already exist.

Effects:

The key in the state map is associated
with the SLE.

The RawView acquires ownership of the shared_ptr.

Note: The key is taken from the SLE

Implements ripple::ApplyView.

Definition at line 139 of file ApplyViewBase.cpp.

◆ update()

void ripple::detail::ApplyViewBase::update ( std::shared_ptr< SLE > const & sle )

overridevirtualinherited

Indicate changes to a peeked SLE.

Requirements:

The SLE's key must exist.

`sle` was obtained from prior call to peek()
on this instance of the RawView.

Effects:

The SLE is updated

Note: The key is taken from the SLE

Implements ripple::ApplyView.

Definition at line 145 of file ApplyViewBase.cpp.

◆ rawErase()

void ripple::detail::ApplyViewBase::rawErase ( std::shared_ptr< SLE > const & sle )

overridevirtualinherited

Delete an existing state item.

The SLE is provided so the implementation can calculate metadata.

Implements ripple::RawView.

Definition at line 153 of file ApplyViewBase.cpp.

◆ rawInsert()

void ripple::detail::ApplyViewBase::rawInsert ( std::shared_ptr< SLE > const & sle )

overridevirtualinherited

Unconditionally insert a state item.

Requirements: The key must not already exist.

Effects:

The key is associated with the SLE.

Note: The key is taken from the SLE

Implements ripple::RawView.

Definition at line 159 of file ApplyViewBase.cpp.

◆ rawReplace()

void ripple::detail::ApplyViewBase::rawReplace ( std::shared_ptr< SLE > const & sle )

overridevirtualinherited

Unconditionally replace a state item.

Requirements:

The key must exist.

Effects:

The key is associated with the SLE.

Note: The key is taken from the SLE

Implements ripple::RawView.

Definition at line 165 of file ApplyViewBase.cpp.

◆ rawDestroyXRP()

void ripple::detail::ApplyViewBase::rawDestroyXRP ( XRPAmount const & fee )

overridevirtualinherited

Destroy XRP.

This is used to pay for transaction fees.

Implements ripple::RawView.

Definition at line 171 of file ApplyViewBase.cpp.

◆ dirAdd()

std::optional< std::uint64_t > ripple::ApplyView::dirAdd	(	bool	preserveOrder,
		Keylet const &	directory,
		uint256 const &	key,
		std::function< void(std::shared_ptr< SLE > const &)> const &	describe
	)

privateinherited

Add an entry to a directory using the specified insert strategy.

Definition at line 31 of file ApplyView.cpp.

◆ dirAppend()

std::optional< std::uint64_t > ripple::ApplyView::dirAppend	(	Keylet const &	directory,
		Keylet const &	key,
		std::function< void(std::shared_ptr< SLE > const &)> const &	describe
	)

inherited

Append an entry to a directory.

Entries in the directory will be stored in order of insertion, i.e. new entries will always be added at the tail end of the last page.

Parameters

directory	the base of the directory
key	the entry to insert
describe	callback to add required entries to a new page

Returns: a std::optional which, if insertion was successful, will contain the page number in which the item was stored.

Note: this function may create a page (including a root page), if no page with space is available. This function will only fail if the page counter exceeds the protocol-defined maximum number of allowable pages.

Definition at line 280 of file ApplyView.h.

◆ dirInsert() [1/2]

std::optional< std::uint64_t > ripple::ApplyView::dirInsert	(	Keylet const &	directory,
		uint256 const &	key,
		std::function< void(std::shared_ptr< SLE > const &)> const &	describe
	)

inherited

Insert an entry to a directory.

Entries in the directory will be stored in a semi-random order, but each page will be maintained in sorted order.

Parameters

directory	the base of the directory
key	the entry to insert
describe	callback to add required entries to a new page

Returns: a std::optional which, if insertion was successful, will contain the page number in which the item was stored.

Note: this function may create a page (including a root page), if no page with space is available.this function will only fail if the page counter exceeds the protocol-defined maximum number of allowable pages.

Definition at line 319 of file ApplyView.h.

◆ dirInsert() [2/2]

std::optional< std::uint64_t > ripple::ApplyView::dirInsert	(	Keylet const &	directory,
		Keylet const &	key,
		std::function< void(std::shared_ptr< SLE > const &)> const &	describe
	)

inherited

Definition at line 328 of file ApplyView.h.

◆ dirRemove() [1/2]

bool ripple::ApplyView::dirRemove	(	Keylet const &	directory,
		std::uint64_t	page,
		uint256 const &	key,
		bool	keepRoot
	)

inherited

Remove an entry from a directory.

Parameters

directory	the base of the directory
page	the page number for this page
key	the entry to remove
keepRoot	if deleting the last entry, don't delete the root page (i.e. the directory itself).

Returns: true if the entry was found and deleted and false otherwise.

Note: This function will remove zero or more pages from the directory; the root page will not be deleted even if it is empty, unless keepRoot is not set and the directory is empty.

Definition at line 207 of file ApplyView.cpp.

◆ dirRemove() [2/2]

bool ripple::ApplyView::dirRemove	(	Keylet const &	directory,
		std::uint64_t	page,
		Keylet const &	key,
		bool	keepRoot
	)

inherited

Definition at line 361 of file ApplyView.h.

◆ dirDelete()

bool ripple::ApplyView::dirDelete	(	Keylet const &	directory,
		std::function< void(uint256 const &)> const &	callback
	)

inherited

Remove the specified directory, invoking the callback for every node.

Definition at line 356 of file ApplyView.cpp.

◆ emptyDirDelete()

bool ripple::ApplyView::emptyDirDelete ( Keylet const & directory )

inherited

Remove the specified directory, if it is empty.

Parameters

directory the identifier of the directory node to be deleted

Returns: true if the directory was found and was successfully deleted false otherwise.

Note: The function should only be called with the root entry (i.e. with the first page) of a directory.

Definition at line 141 of file ApplyView.cpp.

◆ parentCloseTime()

NetClock::time_point ripple::ReadView::parentCloseTime ( ) const

inherited

Returns the close time of the previous ledger.

Definition at line 111 of file ReadView.h.

◆ seq()

LedgerIndex ripple::ReadView::seq ( ) const

inherited

Returns the sequence number of the base ledger.

Definition at line 118 of file ReadView.h.

Member Data Documentation

◆ tab_

detail::DeferredCredits ripple::PaymentSandbox::tab_

private

Definition at line 206 of file PaymentSandbox.h.

◆ ps_

PaymentSandbox const* ripple::PaymentSandbox::ps_ = nullptr

private

Definition at line 207 of file PaymentSandbox.h.

◆ flags_

ApplyFlags ripple::detail::ApplyViewBase::flags_

protectedinherited

Definition at line 122 of file ApplyViewBase.h.

◆ base_

ReadView const* ripple::detail::ApplyViewBase::base_

protectedinherited

Definition at line 123 of file ApplyViewBase.h.

◆ items_

detail::ApplyStateTable ripple::detail::ApplyViewBase::items_

protectedinherited

Definition at line 124 of file ApplyViewBase.h.

◆ sles

sles_type ripple::ReadView::sles

inherited

Iterable range of ledger state items.

Note: Visiting each state entry in the ledger can become quite expensive as the ledger grows.

Definition at line 245 of file ReadView.h.

◆ txs

txs_type ripple::ReadView::txs

inherited

Definition at line 248 of file ReadView.h.

Public Types

Public Member Functions

Public Attributes

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ tx_type

◆ key_type

◆ mapped_type

Constructor & Destructor Documentation

◆ PaymentSandbox() [1/7]

◆ PaymentSandbox() [2/7]

◆ PaymentSandbox() [3/7]

◆ PaymentSandbox() [4/7]

◆ PaymentSandbox() [5/7]

◆ PaymentSandbox() [6/7]

◆ PaymentSandbox() [7/7]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ balanceHook()

◆ creditHook()

◆ adjustOwnerCountHook()

◆ ownerCountHook()

◆ apply() [1/2]

◆ apply() [2/2]

◆ balanceChanges()

◆ xrpDestroyed()

◆ open()

◆ info()

◆ fees()

◆ rules()

◆ exists()

◆ succ()

◆ read()

◆ slesBegin()

◆ slesEnd()

◆ slesUpperBound() [1/2]

◆ slesUpperBound() [2/2]

◆ txsBegin()

◆ txsEnd()

◆ txExists()

◆ txRead()

◆ flags()

◆ peek()

◆ erase()

◆ insert()

◆ update()

◆ rawErase()

◆ rawInsert()

◆ rawReplace()

◆ rawDestroyXRP()

◆ dirAdd()

◆ dirAppend()

◆ dirInsert() [1/2]

◆ dirInsert() [2/2]

◆ dirRemove() [1/2]

◆ dirRemove() [2/2]

◆ dirDelete()

◆ emptyDirDelete()

◆ parentCloseTime()

◆ seq()

Member Data Documentation

◆ tab_

◆ ps_

◆ flags_

◆ base_

◆ items_

◆ sles

◆ txs