Store a list of transactions to be broadcast privately. More...

#include <private_broadcast.h>

Collaboration diagram for PrivateBroadcast:

Classes
struct	CTransactionRefComp

struct	CTransactionRefHash

struct	PeerSendInfo

struct	Priority
	Cumulative stats from all the send attempts for a transaction. Used to prioritize transactions. More...

struct	SendStatus
	Status of a transaction sent to a given node. More...

struct	TxAndSendStatusForNode
	A pair of a transaction and a sent status for a given node. Convenience return type of GetSendStatusByNode(). More...

struct	TxBroadcastInfo

struct	TxSendStatus

Public Types
enum class	AddResult { Added , AlreadyPresent , QueueFull }
	Outcome of Add(). More...

Public Member Functions
	PrivateBroadcast (size_t max_transactions=MAX_TRANSACTIONS, size_t max_send_attempts=MAX_SEND_ATTEMPTS)

AddResult	Add (const CTransactionRef &tx) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Add a transaction to the storage, or reset an exhausted transaction so it can be broadcast again.

std::optional< size_t >	Remove (const CTransactionRef &tx) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Forget a transaction.

bool	MarkResolved (const CTransactionRef &tx) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Mark a transaction as resolved because it was received back from the network or is no longer acceptable to the mempool.

void	NodeDisconnected (NodeId nodeid) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Mark a connection finished.

bool	TryGrantRetry (const CTransactionRef &tx) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Grant one additional send attempt if the transaction is unresolved, all planned sends have been picked, and the attempt limit has not been reached.

std::optional< CTransactionRef >	PickTxForSend (const NodeId &will_send_to_nodeid, const CService &will_send_to_address) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Pick the transaction with the fewest send attempts, and confirmations, and oldest send/confirm times.

std::optional< CTransactionRef >	GetTxForNode (const NodeId &nodeid) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Get the transaction that was picked for sending to a given node by PickTxForSend().

void	NodeConfirmedReception (const NodeId &nodeid) EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Mark that the node has confirmed reception of the transaction we sent it by responding with `PONG` to our `PING` message.

bool	HavePendingTransactions () EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Check if there are transactions with send attempts remaining.

std::vector< CTransactionRef >	GetStale () const EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Get the transactions that have not been broadcast recently and have send attempts remaining.

std::vector< TxBroadcastInfo >	GetBroadcastInfo () const EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)
	Get stats about all transactions currently being privately broadcast.

Static Public Attributes
static constexpr size_t	INITIAL_CONNECTION_COUNT {3}
	Number of connections to make for initial broadcast.

static constexpr auto	INITIAL_STALE_DURATION {5min}
	If a transaction is not sent to any peer for this duration, then we consider it stale / for rebroadcasting.

static constexpr auto	STALE_DURATION {1min}
	If a transaction is not received back from the network for this duration after it is broadcast, then we consider it stale / for rebroadcasting.

static constexpr size_t	MAX_TRANSACTIONS {10'000}
	Maximum number of transactions tracked simultaneously.

static constexpr size_t	MAX_SEND_ATTEMPTS {1'000}
	Maximum number of send attempts for a transaction. Once this limit is reached, the transaction remains tracked but is not sent again unless explicitly re-added.

Private Member Functions
std::optional< TxAndSendStatusForNode >	GetSendStatusByNode (const NodeId &nodeid) EXCLUSIVE_LOCKS_REQUIRED(m_mutex)
	Find which transaction we sent to a given node (marked by PickTxForSend()).

bool	IsPending (const TxSendStatus &status) const

std::unordered_map< CTransactionRef, TxSendStatus, CTransactionRefHash, CTransactionRefComp > m_transactions	GUARDED_BY (m_mutex)

Static Private Member Functions
static Priority	DerivePriority (const std::vector< SendStatus > &sent_to)
	Derive the sending priority of a transaction.

Private Attributes
const size_t	m_max_transactions
	Cap on the number of simultaneously tracked transactions (see Add()).

const size_t	m_max_send_attempts
	Cap on the number of send attempts per transaction (see PickTxForSend()).

Mutex	m_mutex

Detailed Description

Store a list of transactions to be broadcast privately.

Supports the following operations:

Add a new transaction
Remove a transaction
Mark a transaction as resolved, so no more retry send attempts are granted
Mark a connection finished
Grant an additional send attempt for an unresolved transaction
Pick a transaction for sending to one recipient
Query which transaction has been picked for sending to a given recipient node
Mark that a given recipient node has confirmed receipt of a transaction
Query whether any transactions that need sending are currently on the list

Definition at line 31 of file private_broadcast.h.

Member Enumeration Documentation

◆ AddResult

enum class PrivateBroadcast::AddResult

strong

Outcome of Add().

Enumerator
Added	The transaction was newly added or reset after exhausting its send attempts.
AlreadyPresent	The transaction was already present with send attempts remaining; no change.
QueueFull	Rejected: the queue is already at MAX_TRANSACTIONS.

Definition at line 78 of file private_broadcast.h.

Constructor & Destructor Documentation

◆ PrivateBroadcast()

PrivateBroadcast::PrivateBroadcast	(	size_t	max_transactions = `MAX_TRANSACTIONS`,
		size_t	max_send_attempts = `MAX_SEND_ATTEMPTS`
	)

inlineexplicit

Parameters

[in]	max_transactions	Cap on the number of simultaneously tracked transactions. Defaults to MAX_TRANSACTIONS.
[in]	max_send_attempts	Cap on the number of send attempts per transaction. Defaults to MAX_SEND_ATTEMPTS.

Definition at line 59 of file private_broadcast.h.

Member Function Documentation

◆ Add()

PrivateBroadcast::AddResult PrivateBroadcast::Add ( const CTransactionRef & tx )

Add a transaction to the storage, or reset an exhausted transaction so it can be broadcast again.

Parameters

[in] tx The transaction to add.

Returns: Whether the transaction was newly added or reset, was already present with send attempts remaining, or was rejected because the queue is full (see AddResult).

Definition at line 13 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ DerivePriority()

PrivateBroadcast::Priority PrivateBroadcast::DerivePriority ( const std::vector< SendStatus > & sent_to )

staticprivate

Derive the sending priority of a transaction.

Parameters

[in] sent_to List of nodes that the transaction has been sent to.

Definition at line 183 of file private_broadcast.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetBroadcastInfo()

std::vector< PrivateBroadcast::TxBroadcastInfo > PrivateBroadcast::GetBroadcastInfo ( ) const

Get stats about all transactions currently being privately broadcast.

Definition at line 155 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ GetSendStatusByNode()

std::optional< PrivateBroadcast::TxAndSendStatusForNode > PrivateBroadcast::GetSendStatusByNode ( const NodeId & nodeid )

private

Find which transaction we sent to a given node (marked by PickTxForSend()).

Returns: That transaction together with the send status or nullopt if we did not send any transaction to the given node.

Definition at line 197 of file private_broadcast.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ GetStale()

std::vector< CTransactionRef > PrivateBroadcast::GetStale ( ) const

Get the transactions that have not been broadcast recently and have send attempts remaining.

Definition at line 137 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ GetTxForNode()

std::optional< CTransactionRef > PrivateBroadcast::GetTxForNode ( const NodeId & nodeid )

Get the transaction that was picked for sending to a given node by PickTxForSend().

Parameters

[in] nodeid Node to which a transaction is being (or was) sent.

Returns: Transaction or nullopt if the nodeid is unknown.

Definition at line 109 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ GUARDED_BY()

std::unordered_map< CTransactionRef, TxSendStatus, CTransactionRefHash, CTransactionRefComp > m_transactions PrivateBroadcast::GUARDED_BY ( m_mutex )

private

◆ HavePendingTransactions()

bool PrivateBroadcast::HavePendingTransactions ( )

Check if there are transactions with send attempts remaining.

Definition at line 130 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ IsPending()

bool PrivateBroadcast::IsPending ( const TxSendStatus & status ) const

private

Definition at line 176 of file private_broadcast.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ MarkResolved()

bool PrivateBroadcast::MarkResolved ( const CTransactionRef & tx )

Mark a transaction as resolved because it was received back from the network or is no longer acceptable to the mempool.

Parameters

[in] tx Transaction to resolve.

Returns: Whether the transaction was found in the storage.

Definition at line 55 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ NodeConfirmedReception()

void PrivateBroadcast::NodeConfirmedReception ( const NodeId & nodeid )

Mark that the node has confirmed reception of the transaction we sent it by responding with PONG to our PING message.

Parameters

[in] nodeid Node that we sent a transaction to.

Definition at line 120 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ NodeDisconnected()

void PrivateBroadcast::NodeDisconnected ( NodeId nodeid )

Mark a connection finished.

Parameters

[in] nodeid Node whose connection has ended.

Definition at line 64 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ PickTxForSend()

std::optional< CTransactionRef > PrivateBroadcast::PickTxForSend	(	const NodeId &	will_send_to_nodeid,
		const CService &	will_send_to_address
	)

Pick the transaction with the fewest send attempts, and confirmations, and oldest send/confirm times.

Parameters

[in]	will_send_to_nodeid	Will remember that the returned transaction was picked for sending to this node. Calling this method more than once with the same `will_send_to_nodeid` is not allowed because sending more than one transaction to one node would be a privacy leak.
[in]	will_send_to_address	Address of the peer to which this transaction will be sent.

Returns: Most urgent transaction or nullopt if there are no transactions with send attempts remaining.

Definition at line 84 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ Remove()

std::optional< size_t > PrivateBroadcast::Remove ( const CTransactionRef & tx )

Forget a transaction.

Parameters

[in] tx Transaction to forget.

Return values

!nullopt	The number of planned send attempts not yet picked (if the transaction existed and was removed).
nullopt	The transaction was not in the storage.

Definition at line 41 of file private_broadcast.cpp.

Here is the call graph for this function:

◆ TryGrantRetry()

bool PrivateBroadcast::TryGrantRetry ( const CTransactionRef & tx )

Grant one additional send attempt if the transaction is unresolved, all planned sends have been picked, and the attempt limit has not been reached.

The caller schedules the connection separately.

Parameters

[in] tx Transaction to retry.

Returns: Whether an additional send attempt was granted.

Definition at line 72 of file private_broadcast.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ INITIAL_CONNECTION_COUNT

constexpr size_t PrivateBroadcast::INITIAL_CONNECTION_COUNT {3}

staticconstexpr

Number of connections to make for initial broadcast.

Definition at line 36 of file private_broadcast.h.

◆ INITIAL_STALE_DURATION

constexpr auto PrivateBroadcast::INITIAL_STALE_DURATION {5min}

staticconstexpr

If a transaction is not sent to any peer for this duration, then we consider it stale / for rebroadcasting.

Definition at line 40 of file private_broadcast.h.

◆ m_max_send_attempts

const size_t PrivateBroadcast::m_max_send_attempts

private

Cap on the number of send attempts per transaction (see PickTxForSend()).

Definition at line 265 of file private_broadcast.h.

◆ m_max_transactions

const size_t PrivateBroadcast::m_max_transactions

private

Cap on the number of simultaneously tracked transactions (see Add()).

Definition at line 263 of file private_broadcast.h.

◆ m_mutex

Mutex PrivateBroadcast::m_mutex

mutableprivate

Definition at line 266 of file private_broadcast.h.

◆ MAX_SEND_ATTEMPTS

constexpr size_t PrivateBroadcast::MAX_SEND_ATTEMPTS {1'000}

staticconstexpr

Maximum number of send attempts for a transaction. Once this limit is reached, the transaction remains tracked but is not sent again unless explicitly re-added.

Definition at line 53 of file private_broadcast.h.

◆ MAX_TRANSACTIONS

constexpr size_t PrivateBroadcast::MAX_TRANSACTIONS {10'000}

staticconstexpr

Maximum number of transactions tracked simultaneously.

Additions that would exceed this are rejected (see Add()).

Definition at line 48 of file private_broadcast.h.

◆ STALE_DURATION

constexpr auto PrivateBroadcast::STALE_DURATION {1min}

staticconstexpr

If a transaction is not received back from the network for this duration after it is broadcast, then we consider it stale / for rebroadcasting.

Definition at line 44 of file private_broadcast.h.

The documentation for this class was generated from the following files:

src/private_broadcast.h
src/private_broadcast.cpp

Classes

Public Types

Public Member Functions

Static Public Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ AddResult

Constructor & Destructor Documentation

◆ PrivateBroadcast()

Member Function Documentation

◆ Add()

◆ DerivePriority()

◆ GetBroadcastInfo()

◆ GetSendStatusByNode()

◆ GetStale()

◆ GetTxForNode()

◆ GUARDED_BY()

◆ HavePendingTransactions()

◆ IsPending()

◆ MarkResolved()

◆ NodeConfirmedReception()

◆ NodeDisconnected()

◆ PickTxForSend()

◆ Remove()

◆ TryGrantRetry()

Member Data Documentation

◆ INITIAL_CONNECTION_COUNT

◆ INITIAL_STALE_DURATION

◆ m_max_send_attempts

◆ m_max_transactions

◆ m_mutex

◆ MAX_SEND_ATTEMPTS

◆ MAX_TRANSACTIONS

◆ STALE_DURATION