Maintains current and recent ledger validations. More...

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

Adaptor const &	adaptor () const
	Return the adaptor instance. More...

ValidationParms const &	parms () const
	Return the validation timing parameters. More...

bool	canValidateSeq (Seq const s)
	Return whether the local node can issue a validation for the given sequence number. More...

ValStatus	add (NodeID const &nodeID, Validation const &val)
	Add a new validation. More...

void	setSeqToKeep (Seq const &low, Seq const &high)
	Set the range [low, high) of validations to keep from expire. More...

void	expire (beast::Journal &j)
	Expire old validation sets. More...

void	trustChanged (hash_set< NodeID > const &added, hash_set< NodeID > const &removed)
	Update trust status of validations. More...

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

ID	getPreferred (Ledger const &curr, Seq minValidSeq)
	Get the ID of the preferred working ledger that exceeds a minimum valid ledger sequence number. More...

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

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

std::vector< WrappedValidationType >	currentTrusted ()
	Get the currently trusted full validations. More...

auto	getCurrentNodeIDs () -> hash_set< NodeID >
	Get the set of node ids associated with current validations. More...

std::size_t	numTrustedForLedger (ID const &ledgerID)
	Count the number of trusted full validations for the given ledger. More...

std::vector< WrappedValidationType >	getTrustedForLedger (ID const &ledgerID, Seq const &seq)
	Get trusted full validations for a specific ledger. More...

std::vector< std::uint32_t >	fees (ID const &ledgerID, std::uint32_t baseFee)
	Returns fees reported by trusted full validators in the given ledger. More...

void	flush ()
	Flush all current validations. More...

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

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

template<class F >
auto	withTrie (std::lock_guard< Mutex > const &lock, F &&f)
	Use the trie for a calculation. More...

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

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

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

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_

const ValidationParms	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 111 of file Application.h.

Member Typedef Documentation

◆ Mutex

template<class Adaptor >

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

private

Definition at line 290 of file Validations.h.

◆ Validation

template<class Adaptor >

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

private

Definition at line 291 of file Validations.h.

◆ Ledger

template<class Adaptor >

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

private

Definition at line 292 of file Validations.h.

◆ ID

template<class Adaptor >

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

private

Definition at line 293 of file Validations.h.

◆ Seq

template<class Adaptor >

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

private

Definition at line 294 of file Validations.h.

◆ NodeID

template<class Adaptor >

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

private

Definition at line 295 of file Validations.h.

◆ NodeKey

template<class Adaptor >

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

private

Definition at line 296 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 572 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 357 of file Validations.h.

◆ checkAcquired()

template<class Adaptor >

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

private

Definition at line 384 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 403 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 431 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 482 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 509 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 547 of file Validations.h.

◆ adaptor()

template<class Adaptor >

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

Return the adaptor instance.

Definition at line 586 of file Validations.h.

◆ parms()

template<class Adaptor >

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

Return the validation timing parameters.

Definition at line 594 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 607 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 622 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 714 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 727 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 792 of file Validations.h.

◆ getJsonTrie()

template<class Adaptor >

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

Definition at line 828 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 847 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 908 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 933 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 971 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 997 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 1016 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 1034 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 1056 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 1079 of file Validations.h.

◆ flush()

template<class Adaptor >

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

Flush all current validations.

Definition at line 1103 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 1125 of file Validations.h.

Member Data Documentation

◆ mutex_

template<class Adaptor >

Mutex ripple::Validations< Adaptor >::mutex_

mutableprivate

Definition at line 302 of file Validations.h.

◆ current_

template<class Adaptor >

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

private

Definition at line 305 of file Validations.h.

◆ localSeqEnforcer_

template<class Adaptor >

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

private

Definition at line 308 of file Validations.h.

◆ seqEnforcers_

template<class Adaptor >

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

private

Definition at line 311 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 319 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 327 of file Validations.h.

◆ toKeep_

template<class Adaptor >

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

private

Definition at line 335 of file Validations.h.

◆ trie_

template<class Adaptor >

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

private

Definition at line 338 of file Validations.h.

◆ lastLedger_

template<class Adaptor >

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

private

Definition at line 342 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 345 of file Validations.h.

◆ parms_

template<class Adaptor >

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

private

Definition at line 348 of file Validations.h.

◆ adaptor_

template<class Adaptor >

Adaptor ripple::Validations< Adaptor >::adaptor_

private

Definition at line 352 of file Validations.h.

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

template<class Adaptor> class ripple::Validations< Adaptor >

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

Member Data Documentation

◆ mutex_

◆ current_

◆ localSeqEnforcer_

◆ seqEnforcers_

◆ byLedger_

◆ bySequence_

◆ toKeep_

◆ trie_

◆ lastLedger_

◆ acquiring_

◆ parms_

◆ adaptor_

template<class Adaptor>
class ripple::Validations< Adaptor >