Writeable view to a ledger, for applying a transaction. More...

#include <ApplyView.h>

Inheritance diagram for xrpl::ApplyView:

[legend]

Collaboration diagram for xrpl::ApplyView:

[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 = SLE::const_pointer

Public Member Functions
	ApplyView ()=default
virtual ApplyFlags	flags () const =0
	Returns the tx apply flags.
virtual SLE::pointer	peek (Keylet const &k)=0
	Prepare to modify the SLE associated with key.
virtual void	erase (SLE::ref sle)=0
	Remove a peeked SLE.
virtual void	insert (SLE::ref sle)=0
	Insert a new state SLE.
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.
virtual LedgerHeader const &	header () const =0
	Returns information about the ledger.
virtual bool	open () const =0
	Returns true if this reflects an open ledger.
NetClock::time_point	parentCloseTime () const
	Returns the close time of the previous ledger.
LedgerIndex	seq () const
	Returns the sequence number of the base ledger.
virtual Fees const &	fees () const =0
	Returns the fees for the base ledger.
virtual Rules const &	rules () const =0
	Returns the tx processing rules.
virtual bool	exists (Keylet const &k) const =0
	Determine if a state item exists.
virtual std::optional< key_type >	succ (key_type const &key, std::optional< key_type > const &last=std::nullopt) const =0
	Return the key of the next state item.
virtual SLE::const_pointer	read (Keylet const &k) const =0
	Return the state item associated with a key.
virtual STAmount	balanceHookIOU (AccountID const &account, AccountID const &issuer, STAmount const &amount) const
virtual STAmount	balanceHookMPT (AccountID const &account, MPTIssue const &issue, std::int64_t amount) const
virtual STAmount	balanceHookSelfIssueMPT (MPTIssue const &issue, std::int64_t amount) const
virtual std::uint32_t	ownerCountHook (AccountID const &account, std::uint32_t count) const
virtual std::unique_ptr< SlesType::iter_base >	slesBegin () const =0
virtual std::unique_ptr< SlesType::iter_base >	slesEnd () const =0
virtual std::unique_ptr< SlesType::iter_base >	slesUpperBound (key_type const &key) const =0
virtual std::unique_ptr< TxsType::iter_base >	txsBegin () const =0
virtual std::unique_ptr< TxsType::iter_base >	txsEnd () const =0
virtual bool	txExists (key_type const &key) const =0
	Returns true if a tx exists in the tx map.
virtual tx_type	txRead (key_type const &key) const =0
	Read a transaction from the tx map.

virtual void	update (SLE::ref sle)=0
	Indicate changes to a peeked SLE.
virtual void	creditHookIOU (AccountID const &from, AccountID const &to, STAmount const &amount, STAmount const &preCreditBalance)
virtual void	creditHookMPT (AccountID const &from, AccountID const &to, STAmount const &amount, std::uint64_t preCreditBalanceHolder, std::int64_t preCreditBalanceIssuer)
virtual void	issuerSelfDebitHookMPT (MPTIssue const &issue, std::uint64_t amount, std::int64_t origBalance)
	Facilitate tracking of MPT sold by an issuer owning MPT sell offer.
virtual void	adjustOwnerCountHook (AccountID const &account, std::uint32_t cur, std::uint32_t next)
std::optional< std::uint64_t >	dirAppend (Keylet const &directory, Keylet const &key, std::function< void(SLE::ref)> const &describe)
	Append an entry to a directory.

std::optional< std::uint64_t >	dirInsert (Keylet const &directory, uint256 const &key, std::function< void(SLE::ref)> const &describe)
	Insert an entry to a directory.
std::optional< std::uint64_t >	dirInsert (Keylet const &directory, Keylet const &key, std::function< void(SLE::ref)> 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
SlesType	sles
	Iterable range of ledger state items.
TxsType	txs

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

Detailed Description

Writeable view to a ledger, for applying a transaction.

This refinement of ReadView provides an interface where the SLE can be "checked out" for modifications and put back in an updated or removed state. Also added is an interface to provide contextual information necessary to calculate the results of transaction processing, including the metadata if the view is later applied to the parent (using an interface in the derived class). The context info also includes values from the base ledger such as sequence number and the network time.

This allows implementations to journal changes made to the state items in a ledger, with the option to apply those changes to the base or discard the changes without affecting the base.

Typical usage is to call read() for non-mutating operations.

For mutating operations the sequence is as follows:

Add a new value v.insert(sle);

Check out a value for modification sle = v.peek(k);

Indicate that changes were made v.update(sle)

Or, erase the value v.erase(sle)

The invariant is that insert, update, and erase may not be called with any SLE which belongs to different view.

Definition at line 117 of file ApplyView.h.

Member Typedef Documentation

◆ tx_type

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

inherited

Definition at line 33 of file ReadView.h.

◆ key_type

using xrpl::ReadView::key_type = uint256

inherited

Definition at line 35 of file ReadView.h.

◆ mapped_type

using xrpl::ReadView::mapped_type = SLE::const_pointer

inherited

Definition at line 37 of file ReadView.h.

Constructor & Destructor Documentation

◆ ApplyView()

xrpl::ApplyView::ApplyView ( )

default

Member Function Documentation

◆ dirAdd()

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

private

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

Definition at line 165 of file ApplyView.cpp.

◆ flags()

virtual ApplyFlags xrpl::ApplyView::flags ( ) const

nodiscardpure virtual

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).

Implemented in xrpl::detail::ApplyViewBase.

◆ peek()

virtual SLE::pointer xrpl::ApplyView::peek ( Keylet const & k )

pure virtual

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

Implemented in xrpl::detail::ApplyViewBase.

◆ erase()

virtual void xrpl::ApplyView::erase ( SLE::ref sle )

pure virtual

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.

Implemented in xrpl::detail::ApplyViewBase.

◆ insert()

virtual void xrpl::ApplyView::insert ( SLE::ref sle )

pure virtual

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

Implemented in xrpl::detail::ApplyViewBase.

◆ update()

virtual void xrpl::ApplyView::update ( SLE::ref sle )

pure virtual

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

Implemented in xrpl::detail::ApplyViewBase.

◆ creditHookIOU()

virtual void xrpl::ApplyView::creditHookIOU	(	AccountID const &	from,
		AccountID const &	to,
		STAmount const &	amount,
		STAmount const &	preCreditBalance )

virtual

Reimplemented in xrpl::PaymentSandbox.

Definition at line 218 of file ApplyView.h.

◆ creditHookMPT()

virtual void xrpl::ApplyView::creditHookMPT	(	AccountID const &	from,
		AccountID const &	to,
		STAmount const &	amount,
		std::uint64_t	preCreditBalanceHolder,
		std::int64_t	preCreditBalanceIssuer )

virtual

Reimplemented in xrpl::PaymentSandbox.

Definition at line 228 of file ApplyView.h.

◆ issuerSelfDebitHookMPT()

virtual void xrpl::ApplyView::issuerSelfDebitHookMPT	(	MPTIssue const &	issue,
		std::uint64_t	amount,
		std::int64_t	origBalance )

virtual

Facilitate tracking of MPT sold by an issuer owning MPT sell offer.

Unlike IOU, MPT doesn't have bi-directional relationship with an issuer, where a trustline limits an amount that can be issued to a holder. Consequently, the credit step (last MPTEndpointStep or BookStep buying MPT) might temporarily overflow OutstandingAmount. Limiting of a step's output amount in this case is delegated to the next step (in rev order). The next step always redeems when a holder account sells MPT (first MPTEndpointStep or BookStep selling MPT). In this case the holder account is only limited by the step's output and it's available funds since it's transferring the funds from one account to another account and doesn't change OutstandingAmount. This doesn't apply to an offer owned by an issuer. In this case the issuer sells or self debits and is increasing OutstandingAmount. Ability to issue is limited by the issuer originally available funds less already self sold MPT amounts (MPT sell offer). Consider an example:

GW creates MPT(USD) with 1,000USD MaximumAmount.
GW pays 950USD to A1.
A1 creates an offer 100XRP(buy)/100USD(sell).
GW creates an offer 100XRP(buy)/100USD(sell).
A2 pays 200USD to A3 with sendMax of 200XRP. Since the payment engine executes payments in reverse, OutstandingAmount overflows in MPTEndpointStep: 950 + 200 = 1,150USD. BookStep first consumes A1 offer. This reduces OutstandingAmount by 100USD: 1,150 - 100 = 1,050USD. GW offer can only be partially consumed because the initial available amount is 50USD = 1,000 - 950. BookStep limits it's output to 150USD. This in turn limits A3's send amount to 150XRP: A1 buys 100XRP and sells 100USD to A3. This doesn't change OutstandingAmount. GW buys 50XRP and sells 50USD to A3. This changes OutstandingAmount to 1,000USD.

Reimplemented in xrpl::PaymentSandbox.

Definition at line 271 of file ApplyView.h.

◆ adjustOwnerCountHook()

virtual void xrpl::ApplyView::adjustOwnerCountHook	(	AccountID const &	account,
		std::uint32_t	cur,
		std::uint32_t	next )

virtual

Reimplemented in xrpl::PaymentSandbox.

Definition at line 278 of file ApplyView.h.

◆ dirAppend()

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

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 301 of file ApplyView.h.

◆ dirInsert() [1/2]

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

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 340 of file ApplyView.h.

◆ dirInsert() [2/2]

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

Definition at line 349 of file ApplyView.h.

◆ dirRemove() [1/2]

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

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 256 of file ApplyView.cpp.

◆ dirRemove() [2/2]

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

Definition at line 378 of file ApplyView.h.

◆ dirDelete()

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

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

Definition at line 396 of file ApplyView.cpp.

◆ emptyDirDelete()

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

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 191 of file ApplyView.cpp.

◆ header()

virtual LedgerHeader const & xrpl::ReadView::header ( ) const

nodiscardpure virtualinherited

Returns information about the ledger.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ open()

virtual bool xrpl::ReadView::open ( ) const

nodiscardpure virtualinherited

Returns true if this reflects an open ledger.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ parentCloseTime()

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

nodiscardinherited

Returns the close time of the previous ledger.

Definition at line 90 of file ReadView.h.

◆ seq()

LedgerIndex xrpl::ReadView::seq ( ) const

nodiscardinherited

Returns the sequence number of the base ledger.

Definition at line 97 of file ReadView.h.

◆ fees()

virtual Fees const & xrpl::ReadView::fees ( ) const

nodiscardpure virtualinherited

Returns the fees for the base ledger.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ rules()

virtual Rules const & xrpl::ReadView::rules ( ) const

nodiscardpure virtualinherited

Returns the tx processing rules.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ exists()

virtual bool xrpl::ReadView::exists ( Keylet const & k ) const

nodiscardpure virtualinherited

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.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ succ()

virtual std::optional< key_type > xrpl::ReadView::succ	(	key_type const &	key,
		std::optional< key_type > const &	last = std::nullopt ) const

nodiscardpure virtualinherited

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).

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, and xrpl::OpenView.

◆ read()

virtual SLE::const_pointer xrpl::ReadView::read ( Keylet const & k ) const

nodiscardpure virtualinherited

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.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ balanceHookIOU()

virtual STAmount xrpl::ReadView::balanceHookIOU	(	AccountID const &	account,
		AccountID const &	issuer,
		STAmount const &	amount ) const

nodiscardvirtualinherited

Reimplemented in xrpl::PaymentSandbox.

Definition at line 155 of file ReadView.h.

◆ balanceHookMPT()

virtual STAmount xrpl::ReadView::balanceHookMPT	(	AccountID const &	account,
		MPTIssue const &	issue,
		std::int64_t	amount ) const

nodiscardvirtualinherited

Reimplemented in xrpl::PaymentSandbox.

Definition at line 165 of file ReadView.h.

◆ balanceHookSelfIssueMPT()

virtual STAmount xrpl::ReadView::balanceHookSelfIssueMPT	(	MPTIssue const &	issue,
		std::int64_t	amount ) const

nodiscardvirtualinherited

Reimplemented in xrpl::PaymentSandbox.

Definition at line 175 of file ReadView.h.

◆ ownerCountHook()

virtual std::uint32_t xrpl::ReadView::ownerCountHook	(	AccountID const &	account,
		std::uint32_t	count ) const

nodiscardvirtualinherited

Reimplemented in xrpl::PaymentSandbox.

Definition at line 186 of file ReadView.h.

◆ slesBegin()

virtual std::unique_ptr< SlesType::iter_base > xrpl::ReadView::slesBegin ( ) const

nodiscardpure virtualinherited

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ slesEnd()

virtual std::unique_ptr< SlesType::iter_base > xrpl::ReadView::slesEnd ( ) const

nodiscardpure virtualinherited

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ slesUpperBound()

virtual std::unique_ptr< SlesType::iter_base > xrpl::ReadView::slesUpperBound ( key_type const & key ) const

nodiscardpure virtualinherited

◆ txsBegin()

virtual std::unique_ptr< TxsType::iter_base > xrpl::ReadView::txsBegin ( ) const

nodiscardpure virtualinherited

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ txsEnd()

virtual std::unique_ptr< TxsType::iter_base > xrpl::ReadView::txsEnd ( ) const

nodiscardpure virtualinherited

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

◆ txExists()

virtual bool xrpl::ReadView::txExists ( key_type const & key ) const

nodiscardpure virtualinherited

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.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, and xrpl::OpenView.

◆ txRead()

virtual tx_type xrpl::ReadView::txRead ( key_type const & key ) const

nodiscardpure virtualinherited

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.

Implemented in xrpl::detail::ApplyViewBase, xrpl::detail::CachedViewImpl, xrpl::Ledger, and xrpl::OpenView.

Member Data Documentation

◆ sles

SlesType xrpl::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 239 of file ReadView.h.

◆ txs

TxsType xrpl::ReadView::txs

inherited

Definition at line 242 of file ReadView.h.

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ tx_type

◆ key_type

◆ mapped_type

Constructor & Destructor Documentation

◆ ApplyView()

Member Function Documentation

◆ dirAdd()

◆ flags()

◆ peek()

◆ erase()

◆ insert()

◆ update()

◆ creditHookIOU()

◆ creditHookMPT()

◆ issuerSelfDebitHookMPT()

◆ adjustOwnerCountHook()

◆ dirAppend()

◆ dirInsert() [1/2]

◆ dirInsert() [2/2]

◆ dirRemove() [1/2]

◆ dirRemove() [2/2]

◆ dirDelete()

◆ emptyDirDelete()

◆ header()

◆ open()

◆ parentCloseTime()

◆ seq()

◆ fees()

◆ rules()

◆ exists()

◆ succ()

◆ read()

◆ balanceHookIOU()

◆ balanceHookMPT()

◆ balanceHookSelfIssueMPT()

◆ ownerCountHook()

◆ slesBegin()

◆ slesEnd()

◆ slesUpperBound()

◆ txsBegin()

◆ txsEnd()

◆ txExists()

◆ txRead()

Member Data Documentation

◆ sles

◆ txs