#include <TxQ.h>

Collaboration diagram for xrpl::TxQ:

[legend]

Classes
struct	FeeAndSeq

class	FeeMetrics
	Track and use the fee escalation metrics of the current open ledger. More...

class	MaybeTx
	Represents a transaction in the queue which may be applied later to the open ledger. More...

struct	Metrics
	Structure returned by TxQ::getMetrics, expressed in reference fee level units. More...

class	OrderCandidates
	Used for sorting MaybeTx. More...

struct	Setup
	Structure used to customize TxQ behavior. More...

struct	TxDetails
	Structure that describes a transaction in the queue waiting to be applied to the current open ledger. More...

class	TxQAccount
	Used to represent an account to the queue, and stores the transactions queued for that account by SeqProxy. More...

Public Member Functions
	TxQ (Setup const &setup, beast::Journal j)
	Constructor.

virtual	~TxQ ()
	Destructor.

ApplyResult	apply (Application &app, OpenView &view, std::shared_ptr< STTx const > const &tx, ApplyFlags flags, beast::Journal j)
	Add a new transaction to the open ledger, hold it in the queue, or reject it.

bool	accept (Application &app, OpenView &view)
	Fill the new open ledger with transactions from the queue.

void	processClosedLedger (Application &app, ReadView const &view, bool timeLeap)
	Update fee metrics and clean up the queue in preparation for the next ledger.

SeqProxy	nextQueuableSeq (std::shared_ptr< SLE const > const &sleAccount) const
	Return the next sequence that would go in the TxQ for an account.

Metrics	getMetrics (OpenView const &view) const
	Returns fee metrics in reference fee level units.

FeeAndSeq	getTxRequiredFeeAndSeq (OpenView const &view, std::shared_ptr< STTx const > const &tx) const
	Returns minimum required fee for tx and two sequences: first valid sequence for this account in current ledger and first available sequence for transaction.

std::vector< TxDetails >	getAccountTxs (AccountID const &account) const
	Returns information about the transactions currently in the queue for the account.

std::vector< TxDetails >	getTxs () const
	Returns information about all transactions currently in the queue.

Json::Value	doRPC (Application &app) const
	Summarize current fee metrics for the `fee` RPC command.

Static Public Attributes
static constexpr FeeLevel64	baseLevel {256}
	Fee level for single-signed reference transaction.

Private Types
using	FeeHook = boost::intrusive::member_hook< MaybeTx, boost::intrusive::set_member_hook<>, &MaybeTx::byFeeListHook >

using	FeeMultiSet = boost::intrusive::multiset< MaybeTx, FeeHook, boost::intrusive::compare< OrderCandidates > >

using	AccountMap = std::map< AccountID, TxQAccount >

Private Member Functions
SeqProxy	nextQueuableSeqImpl (std::shared_ptr< SLE const > const &sleAccount, std::lock_guard< std::mutex > const &) const

std::optional< ApplyResult >	tryDirectApply (Application &app, OpenView &view, std::shared_ptr< STTx const > const &tx, ApplyFlags flags, beast::Journal j)

std::optional< TxQAccount::TxMap::iterator >	removeFromByFee (std::optional< TxQAccount::TxMap::iterator > const &replacedTxIter, std::shared_ptr< STTx const > const &tx)

template<size_t fillPercentage = 100>
bool	isFull () const
	Is the queue at least `fillPercentage` full?

TER	canBeHeld (STTx const &, ApplyFlags const, OpenView const &, std::shared_ptr< SLE const > const &sleAccount, AccountMap::iterator const &, std::optional< TxQAccount::TxMap::iterator > const &, std::lock_guard< std::mutex > const &lock)
	Checks if the indicated transaction fits the conditions for being stored in the queue.

FeeMultiSet::iterator_type	erase (FeeMultiSet::const_iterator_type)
	Erase and return the next entry in byFee_ (lower fee level)

FeeMultiSet::iterator_type	eraseAndAdvance (FeeMultiSet::const_iterator_type)
	Erase and return the next entry for the account (if fee level is higher), or next entry in byFee_ (lower fee level).

TxQAccount::TxMap::iterator	erase (TxQAccount &txQAccount, TxQAccount::TxMap::const_iterator begin, TxQAccount::TxMap::const_iterator end)
	Erase a range of items, based on TxQAccount::TxMap iterators.

ApplyResult	tryClearAccountQueueUpThruTx (Application &app, OpenView &view, STTx const &tx, AccountMap::iterator const &accountIter, TxQAccount::TxMap::iterator, FeeLevel64 feeLevelPaid, PreflightResult const &pfResult, std::size_t const txExtraCount, ApplyFlags flags, FeeMetrics::Snapshot const &metricsSnapshot, beast::Journal j)
	All-or-nothing attempt to try to apply the queued txs for `accountIter` up to and including `tx`.

Static Private Member Functions
static FeeLevel64	getRequiredFeeLevel (OpenView &view, ApplyFlags flags, FeeMetrics::Snapshot const &metricsSnapshot, std::lock_guard< std::mutex > const &lock)

Private Attributes
Setup const	setup_
	Setup parameters used to control the behavior of the queue.

beast::Journal const	j_
	Journal.

FeeMetrics	feeMetrics_
	Tracks the current state of the queue.

FeeMultiSet	byFee_
	The queue itself: the collection of transactions ordered by fee level.

AccountMap	byAccount_
	All of the accounts which currently have any transactions in the queue.

std::optional< size_t >	maxSize_
	Maximum number of transactions allowed in the queue based on the current metrics.

LedgerHash	parentHash_ {beast::zero}
	parentHash_ used for logging only

std::mutex	mutex_
	Most queue operations are done under the master lock, but use this mutex for the RPC "fee" command, which isn't.

Detailed Description

Transaction Queue.

Used to manage transactions in conjunction with fee escalation.

Once enough transactions are added to the open ledger, the required fee will jump dramatically. If additional transactions are added, the fee will grow exponentially from there.

Transactions that don't have a high enough fee to be applied to the ledger are added to the queue in order from highest fee level to lowest. Whenever a new ledger is accepted as validated, transactions are first applied from the queue to the open ledger in fee level order until either all transactions are applied or the fee again jumps too high for the remaining transactions.

For further information and a high-level overview of how transactions are processed with the TxQ, see FeeEscalation.md

Definition at line 39 of file TxQ.h.

Member Typedef Documentation

◆ FeeHook

using xrpl::TxQ::FeeHook = boost::intrusive:: member_hook<MaybeTx, boost::intrusive::set_member_hook<>, &MaybeTx::byFeeListHook>

private

Definition at line 719 of file TxQ.h.

◆ FeeMultiSet

using xrpl::TxQ::FeeMultiSet = boost::intrusive::multiset<MaybeTx, FeeHook, boost::intrusive::compare<OrderCandidates> >

private

Definition at line 722 of file TxQ.h.

◆ AccountMap

using xrpl::TxQ::AccountMap = std::map<AccountID, TxQAccount>

private

Definition at line 725 of file TxQ.h.

Constructor & Destructor Documentation

◆ TxQ()

xrpl::TxQ::TxQ	(	Setup const &	setup,
		beast::Journal	j
	)

Constructor.

Definition at line 327 of file TxQ.cpp.

◆ ~TxQ()

xrpl::TxQ::~TxQ ( )

virtual

Destructor.

Definition at line 332 of file TxQ.cpp.

Member Function Documentation

◆ apply()

ApplyResult xrpl::TxQ::apply	(	Application &	app,
		OpenView &	view,
		std::shared_ptr< STTx const > const &	tx,
		ApplyFlags	flags,
		beast::Journal	j
	)

Add a new transaction to the open ledger, hold it in the queue, or reject it.

Returns: A pair with the TER and a bool indicating whether or not the transaction was applied to the open ledger. If the transaction is queued, will return { terQUEUED, false }.

Definition at line 686 of file TxQ.cpp.

◆ accept()

bool xrpl::TxQ::accept	(	Application &	app,
		OpenView &	view
	)

Fill the new open ledger with transactions from the queue.

Note: As more transactions are applied to the ledger, the required fee may increase. The required fee may rise above the fee level of the queued items before the queue is emptied, which will end the process, leaving those in the queue for the next open ledger.

Returns: Whether any transactions were added to the view.

Definition at line 1358 of file TxQ.cpp.

◆ processClosedLedger()

void xrpl::TxQ::processClosedLedger	(	Application &	app,
		ReadView const &	view,
		bool	timeLeap
	)

Update fee metrics and clean up the queue in preparation for the next ledger.

Note: Fee metrics are updated based on the fee levels of the txs in the validated ledger and whether consensus is slow. Maximum queue size is adjusted to be enough to hold ledgersInQueue ledgers or queueSizeMin transactions. Any transactions for which the LastLedgerSequence has passed are removed from the queue, and any account objects that have no candidates under them are removed.

Definition at line 1287 of file TxQ.cpp.

◆ nextQueuableSeq()

SeqProxy xrpl::TxQ::nextQueuableSeq ( std::shared_ptr< SLE const > const & sleAccount ) const

Return the next sequence that would go in the TxQ for an account.

Definition at line 1530 of file TxQ.cpp.

◆ getMetrics()

TxQ::Metrics xrpl::TxQ::getMetrics ( OpenView const & view ) const

Returns fee metrics in reference fee level units.

Definition at line 1692 of file TxQ.cpp.

◆ getTxRequiredFeeAndSeq()

TxQ::FeeAndSeq xrpl::TxQ::getTxRequiredFeeAndSeq	(	OpenView const &	view,
		std::shared_ptr< STTx const > const &	tx
	)		const

Returns minimum required fee for tx and two sequences: first valid sequence for this account in current ledger and first available sequence for transaction.

Parameters

view	current open ledger
tx	the transaction

Returns: minimum required fee, first sequence in the ledger and first available sequence

Definition at line 1713 of file TxQ.cpp.

◆ getAccountTxs()

std::vector< TxQ::TxDetails > xrpl::TxQ::getAccountTxs ( AccountID const & account ) const

Returns information about the transactions currently in the queue for the account.

Returns: Empty vector if the account has no transactions in the queue.

Definition at line 1735 of file TxQ.cpp.

◆ getTxs()

std::vector< TxQ::TxDetails > xrpl::TxQ::getTxs ( ) const

Returns information about all transactions currently in the queue.

Returns: Empty vector if there are no transactions in the queue.

Definition at line 1755 of file TxQ.cpp.

◆ doRPC()

Json::Value xrpl::TxQ::doRPC ( Application & app ) const

Summarize current fee metrics for the fee RPC command.

Returns: a Json objectvalue

Definition at line 1770 of file TxQ.cpp.

◆ nextQueuableSeqImpl()

SeqProxy xrpl::TxQ::nextQueuableSeqImpl	(	std::shared_ptr< SLE const > const &	sleAccount,
		std::lock_guard< std::mutex > const &
	)		const

private

Definition at line 1543 of file TxQ.cpp.

◆ getRequiredFeeLevel()

FeeLevel64 xrpl::TxQ::getRequiredFeeLevel	(	OpenView &	view,
		ApplyFlags	flags,
		FeeMetrics::Snapshot const &	metricsSnapshot,
		std::lock_guard< std::mutex > const &	lock
	)

staticprivate

Definition at line 1590 of file TxQ.cpp.

◆ tryDirectApply()

std::optional< ApplyResult > xrpl::TxQ::tryDirectApply	(	Application &	app,
		OpenView &	view,
		std::shared_ptr< STTx const > const &	tx,
		ApplyFlags	flags,
		beast::Journal	j
	)

private

Definition at line 1600 of file TxQ.cpp.

◆ removeFromByFee()

std::optional< TxQ::TxQAccount::TxMap::iterator > xrpl::TxQ::removeFromByFee	(	std::optional< TxQAccount::TxMap::iterator > const &	replacedTxIter,
		std::shared_ptr< STTx const > const &	tx
	)

private

Definition at line 1666 of file TxQ.cpp.

◆ isFull()

template<size_t fillPercentage>

bool xrpl::TxQ::isFull ( ) const

private

Is the queue at least fillPercentage full?

Definition at line 339 of file TxQ.cpp.

◆ canBeHeld()

TER xrpl::TxQ::canBeHeld	(	STTx const &	tx,
		ApplyFlags const	flags,
		OpenView const &	view,
		std::shared_ptr< SLE const > const &	sleAccount,
		AccountMap::iterator const &	accountIter,
		std::optional< TxQAccount::TxMap::iterator > const &	replacementIter,
		std::lock_guard< std::mutex > const &	lock
	)

private

Checks if the indicated transaction fits the conditions for being stored in the queue.

Definition at line 346 of file TxQ.cpp.

◆ erase() [1/2]

FeeMultiSet::iterator_type xrpl::TxQ::erase ( FeeMultiSet::const_iterator_type )

private

Erase and return the next entry in byFee_ (lower fee level)

◆ eraseAndAdvance()

auto xrpl::TxQ::eraseAndAdvance ( FeeMultiSet::const_iterator_type )

private

Erase and return the next entry for the account (if fee level is higher), or next entry in byFee_ (lower fee level).

Used to get the next "applicable" MaybeTx for accept().

Definition at line 432 of file TxQ.cpp.

◆ erase() [2/2]

TxQAccount::TxMap::iterator xrpl::TxQ::erase	(	TxQAccount &	txQAccount,
		TxQAccount::TxMap::const_iterator	begin,
		TxQAccount::TxMap::const_iterator	end
	)

private

Erase a range of items, based on TxQAccount::TxMap iterators.

◆ tryClearAccountQueueUpThruTx()

ApplyResult xrpl::TxQ::tryClearAccountQueueUpThruTx	(	Application &	app,
		OpenView &	view,
		STTx const &	tx,
		AccountMap::iterator const &	accountIter,
		TxQAccount::TxMap::iterator	,
		FeeLevel64	feeLevelPaid,
		PreflightResult const &	pfResult,
		std::size_t const	txExtraCount,
		ApplyFlags	flags,
		FeeMetrics::Snapshot const &	metricsSnapshot,
		beast::Journal	j
	)

private

All-or-nothing attempt to try to apply the queued txs for accountIter up to and including tx.

Transactions following tx are not cleared.

Definition at line 478 of file TxQ.cpp.

Member Data Documentation

◆ baseLevel

constexpr FeeLevel64 xrpl::TxQ::baseLevel {256}

staticconstexpr

Fee level for single-signed reference transaction.

Definition at line 43 of file TxQ.h.

◆ setup_

Setup const xrpl::TxQ::setup_

private

Setup parameters used to control the behavior of the queue.

Definition at line 728 of file TxQ.h.

◆ j_

beast::Journal const xrpl::TxQ::j_

private

Journal.

Definition at line 730 of file TxQ.h.

◆ feeMetrics_

FeeMetrics xrpl::TxQ::feeMetrics_

private

Tracks the current state of the queue.

Note: This member must always and only be accessed under locked mutex_

Definition at line 736 of file TxQ.h.

◆ byFee_

FeeMultiSet xrpl::TxQ::byFee_

private

The queue itself: the collection of transactions ordered by fee level.

Note: This member must always and only be accessed under locked mutex_

Definition at line 742 of file TxQ.h.

◆ byAccount_

AccountMap xrpl::TxQ::byAccount_

private

All of the accounts which currently have any transactions in the queue.

Entries are created and destroyed dynamically as transactions are added and removed.

Note: This member must always and only be accessed under locked mutex_

Definition at line 749 of file TxQ.h.

◆ maxSize_

std::optional<size_t> xrpl::TxQ::maxSize_

private

Maximum number of transactions allowed in the queue based on the current metrics.

If uninitialized, there is no limit, but that condition cannot last for long in practice.

Note: This member must always and only be accessed under locked mutex_

Definition at line 756 of file TxQ.h.

◆ parentHash_

LedgerHash xrpl::TxQ::parentHash_ {beast::zero}

private

parentHash_ used for logging only

Definition at line 761 of file TxQ.h.

◆ mutex_

std::mutex xrpl::TxQ::mutex_

mutableprivate

Most queue operations are done under the master lock, but use this mutex for the RPC "fee" command, which isn't.

Definition at line 766 of file TxQ.h.

Classes

Public Member Functions

Static Public Attributes

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ FeeHook

◆ FeeMultiSet

◆ AccountMap

Constructor & Destructor Documentation

◆ TxQ()

◆ ~TxQ()

Member Function Documentation

◆ apply()

◆ accept()

◆ processClosedLedger()

◆ nextQueuableSeq()

◆ getMetrics()

◆ getTxRequiredFeeAndSeq()

◆ getAccountTxs()

◆ getTxs()

◆ doRPC()

◆ nextQueuableSeqImpl()

◆ getRequiredFeeLevel()

◆ tryDirectApply()

◆ removeFromByFee()

◆ isFull()

◆ canBeHeld()

◆ erase() [1/2]

◆ eraseAndAdvance()

◆ erase() [2/2]

◆ tryClearAccountQueueUpThruTx()

Member Data Documentation

◆ baseLevel

◆ setup_

◆ j_

◆ feeMetrics_

◆ byFee_

◆ byAccount_

◆ maxSize_

◆ parentHash_

◆ mutex_