Maintains current and recent ledger validations. More...

#include <Validations.h>

Collaboration diagram for xrpl::Validations< Adaptor >:

[legend]

Classes
struct	KeepRange

Public Member Functions
template<class... Ts>
	Validations (ValidationParms const &p, beast::AbstractClock< std::chrono::steady_clock > &c, Ts &&... ts)
	Constructor.
Adaptor const &	adaptor () const
	Return the adaptor instance.
ValidationParms const &	parms () const
	Return the validation timing parameters.
bool	canValidateSeq (Seq const s)
	Return whether the local node can issue a validation for the given sequence number.
ValStatus	add (NodeID const &nodeID, Validation const &val)
	Add a new validation.
void	setSeqToKeep (Seq const &low, Seq const &high)
	Set the range [low, high) of validations to keep from expire.
void	expire (beast::Journal const &j)
	Expire old validation sets.
void	trustChanged (hash_set< NodeID > const &added, hash_set< NodeID > const &removed)
	Update trust status of validations.
json::Value	getJsonTrie () const
std::optional< std::pair< Seq, ID > >	getPreferred (Ledger const &curr)
	Return the sequence number and ID of the preferred working ledger.
ID	getPreferred (Ledger const &curr, Seq minValidSeq)
	Get the ID of the preferred working ledger that exceeds a minimum valid ledger sequence number.
ID	getPreferredLCL (Ledger const &lcl, Seq minSeq, hash_map< ID, std::uint32_t > const &peerCounts)
	Determine the preferred last closed ledger for the next consensus round.
std::size_t	getNodesAfter (Ledger const &ledger, ID const &ledgerID)
	Count the number of current trusted validators working on a ledger after the specified one.
std::vector< WrappedValidationType >	currentTrusted ()
	Get the currently trusted full validations.
auto	getCurrentNodeIDs () -> hash_set< NodeID >
	Get the set of node ids associated with current validations.
std::size_t	numTrustedForLedger (ID const &ledgerID)
	Count the number of trusted full validations for the given ledger.
std::vector< WrappedValidationType >	getTrustedForLedger (ID const &ledgerID, Seq const &seq)
	Get trusted full validations for a specific ledger.
std::vector< std::uint32_t >	fees (ID const &ledgerID, std::uint32_t baseFee)
	Returns fees reported by trusted full validators in the given ledger.
void	flush ()
	Flush all current validations.
std::size_t	laggards (Seq const seq, hash_set< NodeKey > &trustedKeys)
	Return quantity of lagging proposers, and remove online proposers for purposes of evaluating whether to pause.
std::size_t	sizeOfCurrentCache () const
std::size_t	sizeOfSeqEnforcersCache () const
std::size_t	sizeOfByLedgerCache () const
std::size_t	sizeOfBySequenceCache () const

Private Types
using	Mutex = Adaptor::Mutex
using	Validation = Adaptor::Validation
using	Ledger = Adaptor::Ledger
using	ID = Ledger::ID
using	Seq = Ledger::Seq
using	NodeID = Validation::NodeID
using	NodeKey = Validation::NodeKey
using	WrappedValidationType

Private Member Functions
void	removeTrie (std::scoped_lock< Mutex > const &, NodeID const &nodeID, Validation const &val)
void	checkAcquired (std::scoped_lock< Mutex > const &lock)
void	updateTrie (std::scoped_lock< Mutex > const &, NodeID const &nodeID, Ledger ledger)
void	updateTrie (std::scoped_lock< Mutex > const &lock, NodeID const &nodeID, Validation const &val, std::optional< std::pair< Seq, ID > > prior)
	Process a new validation.
template<class F>
auto	withTrie (std::scoped_lock< Mutex > const &lock, F &&f)
	Use the trie for a calculation.
template<class Pre, class F>
void	byLedger (std::scoped_lock< Mutex > const &, ID const &ledgerID, Pre &&pre, F &&f)
	Iterate current validations.

Private Attributes
Mutex	mutex_
hash_map< NodeID, Validation >	current_
SeqEnforcer< Seq >	localSeqEnforcer_
hash_map< NodeID, SeqEnforcer< Seq > >	seqEnforcers_
beast::aged_unordered_map< ID, hash_map< NodeID, Validation >, std::chrono::steady_clock, beast::Uhash<> >	byLedger_
	Validations from listed nodes, indexed by ledger id (partial and full).
beast::aged_unordered_map< Seq, hash_map< NodeID, Validation >, std::chrono::steady_clock, beast::Uhash<> >	bySequence_
std::optional< KeepRange >	toKeep_
LedgerTrie< Ledger >	trie_
hash_map< NodeID, Ledger >	lastLedger_
hash_map< std::pair< Seq, ID >, hash_set< NodeID > >	acquiring_
ValidationParms const	parms_
Adaptor	adaptor_

Detailed Description

template<class Adaptor>
class xrpl::Validations< Adaptor >

Maintains current and recent ledger validations.

Manages storage and queries related to validations received on the network. Stores the most current validation from nodes and sets of recent validations grouped by ledger identifier.

Stored validations are not necessarily from trusted nodes, so clients and implementations should take care to use trusted member functions or check the validation's trusted status.

This class uses a generic interface to allow adapting Validations for specific applications. The Adaptor template implements a set of helper functions and type definitions. The code stubs below outline the interface and type requirements.

Warning: The Adaptor::MutexType is used to manage concurrent access to private members of Validations but does not manage any data in the Adaptor instance itself.

// Conforms to the Ledger type requirements of LedgerTrie
struct Ledger;
 
struct Validation
{
    using NodeID = ...;
    using NodeKey = ...;
 
    // Ledger ID associated with this validation
    Ledger::ID ledgerID() const;
 
    // Sequence number of validation's ledger (0 means no sequence number)
    Ledger::Seq seq() const
 
    // When the validation was signed
    NetClock::time_point signTime() const;
 
    // When the validation was first observed by this node
    NetClock::time_point seenTime() const;
 
    // Signing key of node that published the validation
    NodeKey key() const;
 
    // Whether the publishing node was trusted at the time the validation
    // arrived
    bool trusted() const;
 
    // Set the validation as trusted
    void setTrusted();
 
    // Set the validation as untrusted
    void setUntrusted();
 
    // Whether this is a full or partial validation
    bool full() const;
 
    // Identifier for this node that remains fixed even when rotating
    // signing keys
    NodeID nodeID()  const;
 
    implementation_specific_t
    unwrap() -> return the implementation-specific type being wrapped
 
    // ... implementation specific
};
 
class Adaptor
{
    using Mutex = std::mutex;
    using Validation = Validation;
    using Ledger = Ledger;
 
    // Return the current network time (used to determine staleness)
    NetClock::time_point now() const;
 
    // Attempt to acquire a specific ledger.
    std::optional<Ledger> acquire(Ledger::ID const & ledgerID);
 
    // ... implementation specific
};

Template Parameters

Adaptor Provides type definitions and callbacks

Definition at line 268 of file Validations.h.

Member Typedef Documentation

◆ Mutex

template<class Adaptor>

using xrpl::Validations< Adaptor >::Mutex = Adaptor::Mutex

private

Definition at line 270 of file Validations.h.

◆ Validation

template<class Adaptor>

using xrpl::Validations< Adaptor >::Validation = Adaptor::Validation

private

Definition at line 271 of file Validations.h.

◆ Ledger

template<class Adaptor>

using xrpl::Validations< Adaptor >::Ledger = Adaptor::Ledger

private

Definition at line 272 of file Validations.h.

◆ ID

template<class Adaptor>

using xrpl::Validations< Adaptor >::ID = Ledger::ID

private

Definition at line 273 of file Validations.h.

◆ Seq

template<class Adaptor>

using xrpl::Validations< Adaptor >::Seq = Ledger::Seq

private

Definition at line 274 of file Validations.h.

◆ NodeID

template<class Adaptor>

using xrpl::Validations< Adaptor >::NodeID = Validation::NodeID

private

Definition at line 275 of file Validations.h.

◆ NodeKey

template<class Adaptor>

using xrpl::Validations< Adaptor >::NodeKey = Validation::NodeKey

private

Definition at line 276 of file Validations.h.

◆ WrappedValidationType

template<class Adaptor>

using xrpl::Validations< Adaptor >::WrappedValidationType

private

Initial value:

std::decay_t<std::invoke_result_t<decltype(&Validation::unwrap), Validation>>

std::decay_t

std::invoke_result_t

Definition at line 278 of file Validations.h.

Constructor & Destructor Documentation

◆ Validations()

template<class Adaptor>

template<class... Ts>

xrpl::Validations< Adaptor >::Validations	(	ValidationParms const &	p,
		beast::AbstractClock< std::chrono::steady_clock > &	c,
		Ts &&...	ts )

Constructor.

Parameters

p	ValidationParms to control staleness/expiration of validations
c	Clock to use for expiring validations stored by ledger
ts	Parameters for constructing Adaptor instance

Definition at line 544 of file Validations.h.

Member Function Documentation

◆ removeTrie()

template<class Adaptor>

void xrpl::Validations< Adaptor >::removeTrie	(	std::scoped_lock< Mutex > const &	,
		NodeID const &	nodeID,
		Validation const &	val )

private

Definition at line 337 of file Validations.h.

◆ checkAcquired()

template<class Adaptor>

void xrpl::Validations< Adaptor >::checkAcquired ( std::scoped_lock< Mutex > const & lock )

private

Definition at line 360 of file Validations.h.

◆ updateTrie() [1/2]

template<class Adaptor>

void xrpl::Validations< Adaptor >::updateTrie	(	std::scoped_lock< Mutex > const &	,
		NodeID const &	nodeID,
		Ledger	ledger )

private

Definition at line 380 of file Validations.h.

◆ updateTrie() [2/2]

template<class Adaptor>

void xrpl::Validations< Adaptor >::updateTrie	(	std::scoped_lock< Mutex > const &	lock,
		NodeID const &	nodeID,
		Validation const &	val,
		std::optional< std::pair< Seq, ID > >	prior )

private

Process a new validation.

Process a new trusted validation from a validator. This will be reflected only after the validated ledger is successfully acquired by the local node. In the interim, the prior validated ledger from this node remains.

Parameters

lock	Existing lock of mutex_
nodeID	The node identifier of the validating node
val	The trusted validation issued by the node
prior	If not none, the last current validated ledger Seq,ID of key

Definition at line 405 of file Validations.h.

◆ withTrie()

template<class Adaptor>

template<class F>

auto xrpl::Validations< Adaptor >::withTrie	(	std::scoped_lock< Mutex > const &	lock,
		F &&	f )

private

Use the trie for a calculation.

Accessing the trie through this helper ensures acquiring validations are checked and any stale validations are flushed from the trie.

Parameters

lock	Existing lock of mutex_
f	Invocable with signature (LedgerTrie<Ledger> &)

Warning: The invocable f is expected to be a simple transformation of its arguments and will be called with mutex_ under lock.

Definition at line 460 of file Validations.h.

◆ byLedger()

template<class Adaptor>

template<class Pre, class F>

void xrpl::Validations< Adaptor >::byLedger	(	std::scoped_lock< Mutex > const &	,
		ID const &	ledgerID,
		Pre &&	pre,
		F &&	f )

private

Iterate current validations.

Iterate current validations, flushing any which are stale.

Parameters

lock	Existing lock of mutex_
pre	Invocable with signature (std::size_t) called prior to looping.
f	Invocable with signature (NodeID const &, Validations const &) for each current validation.

Note: The invocable pre is called prior to checking for staleness and reflects an upper-bound on the number of calls to f. @warning The invocable f` is expected to be a simple transformation of its arguments and will be called with mutex_ under lock. */

template <class Pre, class F> void current(std::scoped_lock<Mutex> const& lock, Pre&& pre, F&& f) { NetClock::time_point const t = adaptor_.now(); pre(current_.size()); auto it = current_.begin(); while (it != current_.end()) { Check for staleness if (!isCurrent(parms_, t, it->second.signTime(), it->second.seenTime())) { removeTrie(lock, it->first, it->second); it = current_.erase(it); } else { auto cit = typename decltype(current_)::const_iterator{it}; contains a live record f(cit->first, cit->second); ++it; } } }

/** Iterate the set of validations associated with a given ledger id

Parameters

lock	Existing lock on mutex_
ledgerID	The identifier of the ledger
pre	Invocable with signature(std::size_t)
f	Invocable with signature (NodeID const &, Validation const &)

Note: The invocable pre is called prior to iterating validations. The argument is the number of times f will be called.

Warning: The invocable f is expected to be a simple transformation of its arguments and will be called with mutex_ under lock.

Definition at line 523 of file Validations.h.

◆ adaptor()

template<class Adaptor>

Adaptor const & xrpl::Validations< Adaptor >::adaptor ( ) const

Return the adaptor instance.

Definition at line 555 of file Validations.h.

◆ parms()

template<class Adaptor>

ValidationParms const & xrpl::Validations< Adaptor >::parms ( ) const

Return the validation timing parameters.

Definition at line 563 of file Validations.h.

◆ canValidateSeq()

template<class Adaptor>

bool xrpl::Validations< Adaptor >::canValidateSeq ( Seq const s )

Return whether the local node can issue a validation for the given sequence number.

Parameters

s	The sequence number of the ledger the node wants to validate

Returns: Whether the validation satisfies the invariant, updating the largest sequence number seen accordingly

Definition at line 576 of file Validations.h.

◆ add()

template<class Adaptor>

ValStatus xrpl::Validations< Adaptor >::add	(	NodeID const &	nodeID,
		Validation const &	val )

Add a new validation.

Attempt to add a new validation.

Parameters

nodeID	The identity of the node issuing this validation
val	The validation to store

Returns: The outcome

Definition at line 591 of file Validations.h.

◆ setSeqToKeep()

template<class Adaptor>

void xrpl::Validations< Adaptor >::setSeqToKeep	(	Seq const &	low,
		Seq const &	high )

Set the range [low, high) of validations to keep from expire.

Parameters

low	the lower sequence number
high	the higher sequence number

Note: high must be greater than low

Definition at line 683 of file Validations.h.

◆ expire()

template<class Adaptor>

void xrpl::Validations< Adaptor >::expire ( beast::Journal const & j )

Expire old validation sets.

Remove validation sets that were accessed more than validationSET_EXPIRES ago and were not asked to keep.

Definition at line 696 of file Validations.h.

◆ trustChanged()

template<class Adaptor>

void xrpl::Validations< Adaptor >::trustChanged	(	hash_set< NodeID > const &	added,
		hash_set< NodeID > const &	removed )

Update trust status of validations.

Updates the trusted status of known validations to account for nodes that have been added or removed from the UNL. This also updates the trie to ensure only currently trusted nodes' validations are used.

Parameters

added	Identifiers of nodes that are now trusted
removed	Identifiers of nodes that are no longer trusted

Definition at line 755 of file Validations.h.

◆ getJsonTrie()

template<class Adaptor>

json::Value xrpl::Validations< Adaptor >::getJsonTrie ( ) const

Definition at line 791 of file Validations.h.

◆ getPreferred() [1/2]

template<class Adaptor>

std::optional< std::pair< Seq, ID > > xrpl::Validations< Adaptor >::getPreferred ( Ledger const & curr )

Return the sequence number and ID of the preferred working ledger.

A ledger is preferred if it has more support amongst trusted validators and is not an ancestor of the current working ledger; otherwise it remains the current working ledger.

Parameters

curr	The local node's current working ledger

Returns: The sequence and id of the preferred working ledger, or std::nullopt if no trusted validations are available to determine the preferred ledger.

Definition at line 810 of file Validations.h.

◆ getPreferred() [2/2]

template<class Adaptor>

ID xrpl::Validations< Adaptor >::getPreferred	(	Ledger const &	curr,
		Seq	minValidSeq )

Get the ID of the preferred working ledger that exceeds a minimum valid ledger sequence number.

Parameters

curr	Current working ledger
minValidSeq	Minimum allowed sequence number

Returns: ID Of the preferred ledger, or curr if the preferred ledger is not valid

Definition at line 863 of file Validations.h.

◆ getPreferredLCL()

template<class Adaptor>

ID xrpl::Validations< Adaptor >::getPreferredLCL	(	Ledger const &	lcl,
		Seq	minSeq,
		hash_map< ID, std::uint32_t > const &	peerCounts )

Determine the preferred last closed ledger for the next consensus round.

Called before starting the next round of ledger consensus to determine the preferred working ledger. Uses the dominant peerCount ledger if no trusted validations are available.

Parameters

lcl	Last closed ledger by this node
minSeq	Minimum allowed sequence number of the trusted preferred ledger
peerCounts	Map from ledger ids to count of peers with that as the last closed ledger

Returns: The preferred last closed ledger ID

Note: The minSeq does not apply to the peerCounts, since this function does not know their sequence number

Definition at line 888 of file Validations.h.

◆ getNodesAfter()

template<class Adaptor>

std::size_t xrpl::Validations< Adaptor >::getNodesAfter	(	Ledger const &	ledger,
		ID const &	ledgerID )

Count the number of current trusted validators working on a ledger after the specified one.

Parameters

ledger	The working ledger
ledgerID	The preferred ledger

Returns: The number of current trusted validators working on a descendant of the preferred ledger

Note: If ledger.id() != ledgerID, only counts immediate child ledgers of ledgerID

Definition at line 921 of file Validations.h.

◆ currentTrusted()

template<class Adaptor>

std::vector< WrappedValidationType > xrpl::Validations< Adaptor >::currentTrusted ( )

Get the currently trusted full validations.

Returns: Vector of validations from currently trusted validators

Definition at line 945 of file Validations.h.

◆ getCurrentNodeIDs()

template<class Adaptor>

auto xrpl::Validations< Adaptor >::getCurrentNodeIDs ( ) -> hash_set< NodeID >

Get the set of node ids associated with current validations.

Returns: The set of node ids for active, listed validators

Definition at line 964 of file Validations.h.

◆ numTrustedForLedger()

template<class Adaptor>

std::size_t xrpl::Validations< Adaptor >::numTrustedForLedger ( ID const & ledgerID )

Count the number of trusted full validations for the given ledger.

Parameters

ledgerID The identifier of ledger of interest

Returns: The number of trusted validations

Definition at line 982 of file Validations.h.

◆ getTrustedForLedger()

template<class Adaptor>

std::vector< WrappedValidationType > xrpl::Validations< Adaptor >::getTrustedForLedger	(	ID const &	ledgerID,
		Seq const &	seq )

Get trusted full validations for a specific ledger.

Parameters

ledgerID	The identifier of ledger of interest
seq	The sequence number of ledger of interest

Returns: Trusted validations associated with ledger

Definition at line 1004 of file Validations.h.

◆ fees()

template<class Adaptor>

std::vector< std::uint32_t > xrpl::Validations< Adaptor >::fees	(	ID const &	ledgerID,
		std::uint32_t	baseFee )

Returns fees reported by trusted full validators in the given ledger.

Parameters

ledgerID	The identifier of ledger of interest
baseFee	The fee to report if not present in the validation

Returns: Vector of fees

Definition at line 1027 of file Validations.h.

◆ flush()

template<class Adaptor>

void xrpl::Validations< Adaptor >::flush ( )

Flush all current validations.

Definition at line 1055 of file Validations.h.

◆ laggards()

template<class Adaptor>

std::size_t xrpl::Validations< Adaptor >::laggards	(	Seq const	seq,
		hash_set< NodeKey > &	trustedKeys )

Return quantity of lagging proposers, and remove online proposers for purposes of evaluating whether to pause.

Laggards are the trusted proposers whose sequence number is lower than the sequence number from which our current pending proposal is based. Proposers from whom we have not received a validation for awhile are considered offline.

Note: the trusted flag is not used in this evaluation because it's made redundant by checking the list of proposers.

Parameters

seq	Our current sequence number.
trustedKeys	Public keys of trusted proposers.

Returns: Quantity of laggards.

Definition at line 1077 of file Validations.h.

◆ sizeOfCurrentCache()

template<class Adaptor>

std::size_t xrpl::Validations< Adaptor >::sizeOfCurrentCache ( ) const

Definition at line 1098 of file Validations.h.

◆ sizeOfSeqEnforcersCache()

template<class Adaptor>

std::size_t xrpl::Validations< Adaptor >::sizeOfSeqEnforcersCache ( ) const

Definition at line 1105 of file Validations.h.

◆ sizeOfByLedgerCache()

template<class Adaptor>

std::size_t xrpl::Validations< Adaptor >::sizeOfByLedgerCache ( ) const

Definition at line 1112 of file Validations.h.

◆ sizeOfBySequenceCache()

template<class Adaptor>

std::size_t xrpl::Validations< Adaptor >::sizeOfBySequenceCache ( ) const

Definition at line 1119 of file Validations.h.

Member Data Documentation

◆ mutex_

template<class Adaptor>

Mutex xrpl::Validations< Adaptor >::mutex_

mutableprivate

Definition at line 282 of file Validations.h.

◆ current_

template<class Adaptor>

hash_map<NodeID, Validation> xrpl::Validations< Adaptor >::current_

private

Definition at line 285 of file Validations.h.

◆ localSeqEnforcer_

template<class Adaptor>

SeqEnforcer<Seq> xrpl::Validations< Adaptor >::localSeqEnforcer_

private

Definition at line 288 of file Validations.h.

◆ seqEnforcers_

template<class Adaptor>

hash_map<NodeID, SeqEnforcer<Seq> > xrpl::Validations< Adaptor >::seqEnforcers_

private

Definition at line 291 of file Validations.h.

◆ byLedger_

template<class Adaptor>

beast::aged_unordered_map< ID, hash_map<NodeID, Validation>, std::chrono::steady_clock, beast::Uhash<> > xrpl::Validations< Adaptor >::byLedger_

private

Validations from listed nodes, indexed by ledger id (partial and full).

Definition at line 299 of file Validations.h.

◆ bySequence_

template<class Adaptor>

beast::aged_unordered_map< Seq, hash_map<NodeID, Validation>, std::chrono::steady_clock, beast::Uhash<> > xrpl::Validations< Adaptor >::bySequence_

private

Definition at line 307 of file Validations.h.

◆ toKeep_

template<class Adaptor>

std::optional<KeepRange> xrpl::Validations< Adaptor >::toKeep_

private

Definition at line 315 of file Validations.h.

◆ trie_

template<class Adaptor>

LedgerTrie<Ledger> xrpl::Validations< Adaptor >::trie_

private

Definition at line 318 of file Validations.h.

◆ lastLedger_

template<class Adaptor>

hash_map<NodeID, Ledger> xrpl::Validations< Adaptor >::lastLedger_

private

Definition at line 322 of file Validations.h.

◆ acquiring_

template<class Adaptor>

hash_map<std::pair<Seq, ID>, hash_set<NodeID> > xrpl::Validations< Adaptor >::acquiring_

private

Definition at line 325 of file Validations.h.

◆ parms_

template<class Adaptor>

ValidationParms const xrpl::Validations< Adaptor >::parms_

private

Definition at line 328 of file Validations.h.

◆ adaptor_

template<class Adaptor>

Adaptor xrpl::Validations< Adaptor >::adaptor_

private

Definition at line 332 of file Validations.h.

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Mutex

◆ Validation

◆ Ledger

◆ ID

◆ Seq

◆ NodeID

◆ NodeKey

◆ WrappedValidationType

Constructor & Destructor Documentation

◆ Validations()

Member Function Documentation

◆ removeTrie()

◆ checkAcquired()

◆ updateTrie() [1/2]

◆ updateTrie() [2/2]

◆ withTrie()

◆ byLedger()

◆ adaptor()

◆ parms()

◆ canValidateSeq()

◆ add()

◆ setSeqToKeep()

◆ expire()

◆ trustChanged()

◆ getJsonTrie()

◆ getPreferred() [1/2]

◆ getPreferred() [2/2]

◆ getPreferredLCL()

◆ getNodesAfter()

◆ currentTrusted()

◆ getCurrentNodeIDs()

◆ numTrustedForLedger()

◆ getTrustedForLedger()

◆ fees()

◆ flush()

◆ laggards()

◆ sizeOfCurrentCache()

◆ sizeOfSeqEnforcersCache()

◆ sizeOfByLedgerCache()

◆ sizeOfBySequenceCache()

Member Data Documentation

◆ mutex_

◆ current_

◆ localSeqEnforcer_

◆ seqEnforcers_

◆ byLedger_

◆ bySequence_

◆ toKeep_

◆ trie_

◆ lastLedger_

◆ acquiring_

◆ parms_

◆ adaptor_