Maintains current and recent ledger validations. More...

#include <Validations.h>

Collaboration diagram for ripple::Validations< Adaptor >:

[legend]

Classes
struct	KeepRange

Public Member Functions
template<class... Ts>
	Validations (ValidationParms const &p, beast::abstract_clock< 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 &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 = typename Adaptor::Mutex

using	Validation = typename Adaptor::Validation

using	Ledger = typename Adaptor::Ledger

using	ID = typename Ledger::ID

using	Seq = typename Ledger::Seq

using	NodeID = typename Validation::NodeID

using	NodeKey = typename Validation::NodeKey

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

Private Member Functions
void	removeTrie (std::lock_guard< Mutex > const &, NodeID const &nodeID, Validation const &val)

void	checkAcquired (std::lock_guard< Mutex > const &lock)

void	updateTrie (std::lock_guard< Mutex > const &, NodeID const &nodeID, Ledger ledger)

void	updateTrie (std::lock_guard< 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::lock_guard< Mutex > const &lock, F &&f)
	Use the trie for a calculation.

template<class Pre , class F >
void	current (std::lock_guard< Mutex > const &lock, Pre &&pre, F &&f)
	Iterate current validations.

template<class Pre , class F >
void	byLedger (std::lock_guard< Mutex > const &, ID const &ledgerID, Pre &&pre, F &&f)
	Iterate the set of validations associated with a given ledger id.

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 ripple::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 289 of file Validations.h.

Member Typedef Documentation

◆ Mutex

template<class Adaptor >

using ripple::Validations< Adaptor >::Mutex = typename Adaptor::Mutex

private

Definition at line 291 of file Validations.h.

◆ Validation

template<class Adaptor >

using ripple::Validations< Adaptor >::Validation = typename Adaptor::Validation

private

Definition at line 292 of file Validations.h.

◆ Ledger

template<class Adaptor >

using ripple::Validations< Adaptor >::Ledger = typename Adaptor::Ledger

private

Definition at line 293 of file Validations.h.

◆ ID

template<class Adaptor >

using ripple::Validations< Adaptor >::ID = typename Ledger::ID

private

Definition at line 294 of file Validations.h.

◆ Seq

template<class Adaptor >

using ripple::Validations< Adaptor >::Seq = typename Ledger::Seq

private

Definition at line 295 of file Validations.h.

◆ NodeID

template<class Adaptor >

using ripple::Validations< Adaptor >::NodeID = typename Validation::NodeID

private

Definition at line 296 of file Validations.h.

◆ NodeKey

template<class Adaptor >

using ripple::Validations< Adaptor >::NodeKey = typename Validation::NodeKey

private

Definition at line 297 of file Validations.h.

◆ WrappedValidationType

template<class Adaptor >

using ripple::Validations< Adaptor >::WrappedValidationType = std::decay_t< std::invoke_result_t<decltype(&Validation::unwrap), Validation> >

private

Definition at line 299 of file Validations.h.

Constructor & Destructor Documentation

◆ Validations()

template<class Adaptor >

template<class... Ts>

ripple::Validations< Adaptor >::Validations	(	ValidationParms const &	p,
		beast::abstract_clock< 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 574 of file Validations.h.

Member Function Documentation

◆ removeTrie()

template<class Adaptor >

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

private

Definition at line 358 of file Validations.h.

◆ checkAcquired()

template<class Adaptor >

void ripple::Validations< Adaptor >::checkAcquired ( std::lock_guard< Mutex > const & lock )

private

Definition at line 385 of file Validations.h.

◆ updateTrie() [1/2]

template<class Adaptor >

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

private

Definition at line 404 of file Validations.h.

◆ updateTrie() [2/2]

template<class Adaptor >

void ripple::Validations< Adaptor >::updateTrie	(	std::lock_guard< 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 432 of file Validations.h.

◆ withTrie()

template<class Adaptor >

template<class F >

auto ripple::Validations< Adaptor >::withTrie	(	std::lock_guard< 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	Invokable with signature (LedgerTrie<Ledger> &)

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

Definition at line 485 of file Validations.h.

◆ current()

template<class Adaptor >

template<class Pre , class F >

void ripple::Validations< Adaptor >::current	(	std::lock_guard< Mutex > const &	lock,
		Pre &&	pre,
		F &&	f
	)

private

Iterate current validations.

Iterate current validations, flushing any which are stale.

Parameters

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

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

Definition at line 511 of file Validations.h.

◆ byLedger()

template<class Adaptor >

template<class Pre , class F >

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

private

Iterate the set of validations associated with a given ledger id.

Parameters

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

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

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

Definition at line 549 of file Validations.h.

◆ adaptor()

template<class Adaptor >

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

Return the adaptor instance.

Definition at line 588 of file Validations.h.

◆ parms()

template<class Adaptor >

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

Return the validation timing parameters.

Definition at line 596 of file Validations.h.

◆ canValidateSeq()

template<class Adaptor >

bool ripple::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 609 of file Validations.h.

◆ add()

template<class Adaptor >

ValStatus ripple::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 624 of file Validations.h.

◆ setSeqToKeep()

template<class Adaptor >

void ripple::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 716 of file Validations.h.

◆ expire()

template<class Adaptor >

void ripple::Validations< Adaptor >::expire ( beast::Journal & 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 730 of file Validations.h.

◆ trustChanged()

template<class Adaptor >

void ripple::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 795 of file Validations.h.

◆ getJsonTrie()

template<class Adaptor >

Json::Value ripple::Validations< Adaptor >::getJsonTrie ( ) const

Definition at line 831 of file Validations.h.

◆ getPreferred() [1/2]

template<class Adaptor >

std::optional< std::pair< Seq, ID > > ripple::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 850 of file Validations.h.

◆ getPreferred() [2/2]

template<class Adaptor >

ID ripple::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 911 of file Validations.h.

◆ getPreferredLCL()

template<class Adaptor >

ID ripple::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 936 of file Validations.h.

◆ getNodesAfter()

template<class Adaptor >

std::size_t ripple::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 974 of file Validations.h.

◆ currentTrusted()

template<class Adaptor >

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

Get the currently trusted full validations.

Returns: Vector of validations from currently trusted validators

Definition at line 1000 of file Validations.h.

◆ getCurrentNodeIDs()

template<class Adaptor >

auto ripple::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 1019 of file Validations.h.

◆ numTrustedForLedger()

template<class Adaptor >

std::size_t ripple::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 1037 of file Validations.h.

◆ getTrustedForLedger()

template<class Adaptor >

std::vector< WrappedValidationType > ripple::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 1059 of file Validations.h.

◆ fees()

template<class Adaptor >

std::vector< std::uint32_t > ripple::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 1082 of file Validations.h.

◆ flush()

template<class Adaptor >

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

Flush all current validations.

Definition at line 1106 of file Validations.h.

◆ laggards()

template<class Adaptor >

std::size_t ripple::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 1128 of file Validations.h.

◆ sizeOfCurrentCache()

template<class Adaptor >

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

Definition at line 1150 of file Validations.h.

◆ sizeOfSeqEnforcersCache()

template<class Adaptor >

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

Definition at line 1157 of file Validations.h.

◆ sizeOfByLedgerCache()

template<class Adaptor >

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

Definition at line 1164 of file Validations.h.

◆ sizeOfBySequenceCache()

template<class Adaptor >

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

Definition at line 1171 of file Validations.h.

Member Data Documentation

◆ mutex_

template<class Adaptor >

Mutex ripple::Validations< Adaptor >::mutex_

mutableprivate

Definition at line 303 of file Validations.h.

◆ current_

template<class Adaptor >

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

private

Definition at line 306 of file Validations.h.

◆ localSeqEnforcer_

template<class Adaptor >

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

private

Definition at line 309 of file Validations.h.

◆ seqEnforcers_

template<class Adaptor >

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

private

Definition at line 312 of file Validations.h.

◆ byLedger_

template<class Adaptor >

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

private

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

Definition at line 320 of file Validations.h.

◆ bySequence_

template<class Adaptor >

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

private

Definition at line 328 of file Validations.h.

◆ toKeep_

template<class Adaptor >

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

private

Definition at line 336 of file Validations.h.

◆ trie_

template<class Adaptor >

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

private

Definition at line 339 of file Validations.h.

◆ lastLedger_

template<class Adaptor >

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

private

Definition at line 343 of file Validations.h.

◆ acquiring_

template<class Adaptor >

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

private

Definition at line 346 of file Validations.h.

◆ parms_

template<class Adaptor >

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

private

Definition at line 349 of file Validations.h.

◆ adaptor_

template<class Adaptor >

Adaptor ripple::Validations< Adaptor >::adaptor_

private

Definition at line 353 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()

◆ current()

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