xrpld
Loading...
Searching...
No Matches
xrpl::Sandbox Class Referenceabstract

Discardable, editable view to a ledger. More...

#include <Sandbox.h>

Inheritance diagram for xrpl::Sandbox:
Collaboration diagram for xrpl::Sandbox:

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

 Sandbox ()=delete
 Sandbox (Sandbox const &)=delete
Sandboxoperator= (Sandbox &&)=delete
Sandboxoperator= (Sandbox const &)=delete
 Sandbox (Sandbox &&)=default
 Sandbox (ReadView const *base, ApplyFlags flags)
 Sandbox (ApplyView const *base)
void apply (RawView &to)
bool open () const override
 Returns true if this reflects an open ledger.
LedgerHeader const & header () 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_typesucc (key_type const &key, std::optional< key_type > const &last=std::nullopt) const override
 Return the key of the next state item.
SLE::const_pointer read (Keylet const &k) const override
 Return the state item associated with a key.
std::unique_ptr< SlesType::iter_base > slesBegin () const override
std::unique_ptr< SlesType::iter_base > slesEnd () const override
std::unique_ptr< SlesType::iter_base > slesUpperBound (uint256 const &key) const override
virtual std::unique_ptr< SlesType::iter_base > slesUpperBound (key_type const &key) const =0
std::unique_ptr< TxsType::iter_base > txsBegin () const override
std::unique_ptr< TxsType::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.
SLE::pointer peek (Keylet const &k) override
 Prepare to modify the SLE associated with key.
void erase (SLE::ref sle) override
 Remove a peeked SLE.
void insert (SLE::ref sle) override
 Insert a new state SLE.
void update (SLE::ref sle) override
 Indicate changes to a peeked SLE.
void rawErase (SLE::ref sle) override
 Delete an existing state item.
void rawInsert (SLE::ref sle) override
 Unconditionally insert a state item.
void rawReplace (SLE::ref 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.
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 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_tdirAppend (Keylet const &directory, Keylet const &key, std::function< void(SLE::ref)> const &describe)
 Append an entry to a directory.
std::optional< std::uint64_tdirInsert (Keylet const &directory, uint256 const &key, std::function< void(SLE::ref)> const &describe)
 Insert an entry to a directory.
std::optional< std::uint64_tdirInsert (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

Protected Attributes

ApplyFlags flags_
ReadView const * base_
detail::ApplyStateTable items_

Private Member Functions

std::optional< std::uint64_tdirAdd (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

Discardable, editable view to a ledger.

The sandbox inherits the flags of the base.

Note
Presented as ApplyView to clients.

Definition at line 14 of file Sandbox.h.

Member Typedef Documentation

◆ tx_type

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

Definition at line 37 of file ReadView.h.

Constructor & Destructor Documentation

◆ Sandbox() [1/5]

xrpl::Sandbox::Sandbox ( )
delete

◆ Sandbox() [2/5]

xrpl::Sandbox::Sandbox ( Sandbox const & )
delete

◆ Sandbox() [3/5]

xrpl::Sandbox::Sandbox ( Sandbox && )
default

◆ Sandbox() [4/5]

xrpl::Sandbox::Sandbox ( ReadView const * base,
ApplyFlags flags )

Definition at line 26 of file Sandbox.h.

◆ Sandbox() [5/5]

xrpl::Sandbox::Sandbox ( ApplyView const * base)

Definition at line 30 of file Sandbox.h.

Member Function Documentation

◆ operator=() [1/2]

Sandbox & xrpl::Sandbox::operator= ( Sandbox && )
delete

◆ operator=() [2/2]

Sandbox & xrpl::Sandbox::operator= ( Sandbox const & )
delete

◆ apply()

void xrpl::Sandbox::apply ( RawView & to)

Definition at line 35 of file Sandbox.h.

◆ open()

bool xrpl::detail::ApplyViewBase::open ( ) const
nodiscardoverridevirtualinherited

Returns true if this reflects an open ledger.

Implements xrpl::ReadView.

Definition at line 25 of file ApplyViewBase.cpp.

◆ header()

LedgerHeader const & xrpl::detail::ApplyViewBase::header ( ) const
nodiscardoverridevirtualinherited

Returns information about the ledger.

Implements xrpl::ReadView.

Definition at line 31 of file ApplyViewBase.cpp.

◆ fees()

Fees const & xrpl::detail::ApplyViewBase::fees ( ) const
nodiscardoverridevirtualinherited

Returns the fees for the base ledger.

Implements xrpl::ReadView.

Definition at line 37 of file ApplyViewBase.cpp.

◆ rules()

Rules const & xrpl::detail::ApplyViewBase::rules ( ) const
nodiscardoverridevirtualinherited

Returns the tx processing rules.

Implements xrpl::ReadView.

Definition at line 43 of file ApplyViewBase.cpp.

◆ exists()

bool xrpl::detail::ApplyViewBase::exists ( Keylet const & k) const
nodiscardoverridevirtualinherited

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 xrpl::ReadView.

Definition at line 49 of file ApplyViewBase.cpp.

◆ succ()

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

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 xrpl::ReadView.

Definition at line 55 of file ApplyViewBase.cpp.

◆ read()

SLE::const_pointer xrpl::detail::ApplyViewBase::read ( Keylet const & k) const
nodiscardoverridevirtualinherited

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 xrpl::ReadView.

Definition at line 62 of file ApplyViewBase.cpp.

◆ slesBegin()

auto xrpl::detail::ApplyViewBase::slesBegin ( ) const
nodiscardoverridevirtualinherited

Implements xrpl::ReadView.

Definition at line 68 of file ApplyViewBase.cpp.

◆ slesEnd()

auto xrpl::detail::ApplyViewBase::slesEnd ( ) const
nodiscardoverridevirtualinherited

Implements xrpl::ReadView.

Definition at line 74 of file ApplyViewBase.cpp.

◆ slesUpperBound() [1/2]

auto xrpl::detail::ApplyViewBase::slesUpperBound ( uint256 const & key) const
nodiscardoverrideinherited

Definition at line 80 of file ApplyViewBase.cpp.

◆ slesUpperBound() [2/2]

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

◆ txsBegin()

auto xrpl::detail::ApplyViewBase::txsBegin ( ) const
nodiscardoverridevirtualinherited

Implements xrpl::ReadView.

Definition at line 86 of file ApplyViewBase.cpp.

◆ txsEnd()

auto xrpl::detail::ApplyViewBase::txsEnd ( ) const
nodiscardoverridevirtualinherited

Implements xrpl::ReadView.

Definition at line 92 of file ApplyViewBase.cpp.

◆ txExists()

bool xrpl::detail::ApplyViewBase::txExists ( key_type const & key) const
nodiscardoverridevirtualinherited

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 xrpl::ReadView.

Definition at line 98 of file ApplyViewBase.cpp.

◆ txRead()

auto xrpl::detail::ApplyViewBase::txRead ( key_type const & key) const
nodiscardoverridevirtualinherited

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 xrpl::ReadView.

Definition at line 104 of file ApplyViewBase.cpp.

◆ flags()

ApplyFlags xrpl::detail::ApplyViewBase::flags ( ) const
nodiscardoverridevirtualinherited

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 xrpl::ApplyView.

Definition at line 112 of file ApplyViewBase.cpp.

◆ peek()

SLE::pointer xrpl::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 xrpl::ApplyView.

Definition at line 118 of file ApplyViewBase.cpp.

◆ erase()

void xrpl::detail::ApplyViewBase::erase ( SLE::ref 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 xrpl::ApplyView.

Definition at line 124 of file ApplyViewBase.cpp.

◆ insert()

void xrpl::detail::ApplyViewBase::insert ( SLE::ref 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 xrpl::ApplyView.

Definition at line 130 of file ApplyViewBase.cpp.

◆ update()

void xrpl::detail::ApplyViewBase::update ( SLE::ref 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 xrpl::ApplyView.

Definition at line 136 of file ApplyViewBase.cpp.

◆ rawErase()

void xrpl::detail::ApplyViewBase::rawErase ( SLE::ref sle)
overridevirtualinherited

Delete an existing state item.

The SLE is provided so the implementation can calculate metadata.

Implements xrpl::RawView.

Definition at line 144 of file ApplyViewBase.cpp.

◆ rawInsert()

void xrpl::detail::ApplyViewBase::rawInsert ( SLE::ref 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 xrpl::RawView.

Definition at line 150 of file ApplyViewBase.cpp.

◆ rawReplace()

void xrpl::detail::ApplyViewBase::rawReplace ( SLE::ref 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 xrpl::RawView.

Definition at line 156 of file ApplyViewBase.cpp.

◆ rawDestroyXRP()

void xrpl::detail::ApplyViewBase::rawDestroyXRP ( XRPAmount const & fee)
overridevirtualinherited

Destroy XRP.

This is used to pay for transaction fees.

Implements xrpl::RawView.

Definition at line 162 of file ApplyViewBase.cpp.

◆ dirAdd()

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

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

Definition at line 165 of file ApplyView.cpp.

◆ creditHookIOU()

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

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

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

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

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 )
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
directorythe base of the directory
keythe entry to insert
describecallback 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 )
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
directorythe base of the directory
keythe entry to insert
describecallback 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 )
inherited

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

Remove an entry from a directory.

Parameters
directorythe base of the directory
pagethe page number for this page
keythe entry to remove
keepRootif 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 )
inherited

Definition at line 378 of file ApplyView.h.

◆ dirDelete()

bool xrpl::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 396 of file ApplyView.cpp.

◆ emptyDirDelete()

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

Remove the specified directory, if it is empty.

Parameters
directorythe 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.

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

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

Member Data Documentation

◆ flags_

ApplyFlags xrpl::detail::ApplyViewBase::flags_
protectedinherited

Definition at line 99 of file ApplyViewBase.h.

◆ base_

ReadView const* xrpl::detail::ApplyViewBase::base_
protectedinherited

Definition at line 100 of file ApplyViewBase.h.

◆ items_

detail::ApplyStateTable xrpl::detail::ApplyViewBase::items_
protectedinherited

Definition at line 101 of file ApplyViewBase.h.

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