node::TxOrphanage

A class to track orphan transactions (failed on TX_MISSING_INPUTS) Since we cannot distinguish orphans from bad transactions with non-existent inputs, we heavily limit the amount of announcements (unique (NodeId, wtxid) pairs), the number of inputs, and size of the orphans stored (both individual and summed). We also try to prevent adversaries from churning this data structure: once global limits are reached, we continuously evict the oldest announcement (sorting non-reconsiderable orphans before reconsiderable ones) from the most resource-intensive peer until we are back within limits. - Peers can exceed their individual limits (e.g. because they are very useful transaction relay peers) as long as the global limits are not exceeded. - As long as the orphan has 1 announcer, it remains in the orphanage. - No peer can trigger the eviction of another peer's orphans. - Peers' orphans are effectively protected from eviction as long as they don't exceed their limits. Not thread-safe. Requires external synchronization.

Synopsis

Declared in <node/txorphanage.h>

class TxOrphanage;

Types

Name	Description
`OrphanInfo`	Allows providing orphan information externally

Type Aliases

Name	Description
`Count`	Count of announcements or orphans.
`Usage`	Memory usage (weight) measured in weight units.

Member Functions

Name	Description
`~TxOrphanage` [destructor] [virtual]	Destroy the orphanage and release all stored orphans.
`AddAnnouncer` [virtual]	Add an additional announcer to an orphan if it exists. Otherwise, do nothing.
`AddChildrenToWorkSet` [virtual]	Add any orphans that list a particular tx as a parent into the from peer's work set
`AddTx` [virtual]	Add a new orphan transaction
`AnnouncementsFromPeer` [virtual]	Number of orphans stored from this peer.
`CountAnnouncements` [virtual]	Number of announcements, i.e. total size of m_orphans. Ones for the same wtxid are not de-duplicated. Not the same as TotalLatencyScore().
`CountUniqueOrphans` [virtual]	Number of unique orphans (by wtxid).
`EraseForBlock` [virtual]	Erase all orphans included in or invalidated by a new block
`EraseForPeer` [virtual]	Maybe erase all orphans announced by a peer (eg, after that peer disconnects). If an orphan has been announced by another peer, don't erase, just remove this peer from the list of announcers.
`EraseTx` [virtual]	Erase an orphan by wtxid, including all announcements if there are multiple. Returns true if an orphan was erased, false if no tx with this wtxid exists.
`GetChildrenFromSamePeer` [virtual]	Get all children that spend from this tx and were received from nodeid. Sorted reconsiderable before non-reconsiderable, then from most recent to least recent.
`GetOrphanTransactions` [virtual]	Get all orphan transactions
`GetTx` [virtual]	Get a transaction by its witness txid
`GetTxToReconsider` [virtual]	Extract a transaction from a peer's work set, and flip it back to non-reconsiderable. Returns nullptr if there are no transactions to work on. Otherwise returns the transaction reference, and removes it from the work set.
`HaveTx` [virtual]	Check if we already have an orphan transaction (by wtxid only)
`HaveTxFromPeer` [virtual]	Check if a {tx, peer} exists in the orphanage.
`HaveTxToReconsider` [virtual]	Does this peer have any work to do?
`LatencyScoreFromPeer` [virtual]	Latency score of transactions announced by this peer.
`MaxGlobalLatencyScore` [virtual]	Get the maximum global latency score allowed
`MaxGlobalUsage` [virtual]	Get the maximum global usage allowed
`MaxPeerLatencyScore` [virtual]	Get the maximum latency score allowed per peer
`ReservedPeerUsage` [virtual]	Get the reserved usage per peer
`SanityCheck` [virtual]	Check consistency between PeerOrphanInfo and m_orphans. Recalculate counters and ensure they match what is cached.
`TotalLatencyScore` [virtual]	Get the total latency score of all orphans
`TotalOrphanUsage` [virtual]	Get the total usage (weight) of all orphans. If an orphan has multiple announcers, its usage is only counted once within this total.
`UsageByPeer` [virtual]	Total usage (weight) of orphans for which this peer is an announcer. If an orphan has multiple announcers, its weight will be accounted for in each PeerOrphanInfo, so the total of all peers' UsageByPeer() may be larger than TotalOrphanUsage(). Similarly, UsageByPeer() may be far higher than ReservedPeerUsage(), particularly if many peers have provided the same orphans.

Non-Member Functions

Name	Description
`MakeTxOrphanage`	Create a new TxOrphanage instance
`MakeTxOrphanage`	Create a new TxOrphanage instance with explicit limits.