The Recipient Roster and the Admission Protocol

[!NOTE] Technical Context: private_broadcast.h | Lines 50-56

In lines 50 through 56 of private_broadcast.h, we complete the definition of the internal data model and arrive at the first "Entry Gate" of the public interface. This block demonstrates how the module organizes its relationships with peers and establishes the "Contract" for adding new transactions to the system.

1. std::vector<PeerSendInfo> peers;: The Recipient Roster

Line 50 is the final member of the TxBroadcastInfo struct. It is a vector of PeerSendInfo objects.

The Topology of a Private Broadcast

This line reveals the "Fan-Out" strategy of the PrivateBroadcast module. For every transaction we want to send privately, we don't just pick one peer—we maintain a List of Recipients.

By storing a vector of peers within the transaction info, the node can track the unique status of each individual peer for that specific transaction. For example, Transaction A might have been successfully sent to Peer 1 but is still "Stale" for Peer 2. This granular tracking is what makes the private broadcast robust. If one peer fails, the node doesn't have to restart the whole process; it simply consults this vector to see which other peers are still "In Play."

2. The Power of "Logical Grouping"

By nesting the peers vector inside TxBroadcastInfo, the architect has created a Self-Contained Unit of State. Everything needed to manage the broadcast of Transaction X—the bytes of the transaction, the time it was added, and the list of everyone who was supposed to receive it—is stored in a single memory structure.

This design pattern is called "Data Locality." When the CPU needs to process a transaction's broadcast, it doesn't have to jump around the RAM to find the list of peers; the peer list is right there "next" to the transaction data. This significantly increases the performance of the node by reducing "Cache Misses."

3. The Add Method: The Admission Protocol

Lines 52-56 mark the beginning of the public documentation for the Add method:

Copy

/**
 * Add a transaction to the storage.
 * @param[in] tx The transaction to add.
 * @retval true The transaction was added.

This is the formal declaration of the "Input Pipeline." In any high-stakes software system, the way you "Accept Data" is just as important as how you "Process Data."

4. Doxygen Syntax: @param and @retval

The use of @param[in] and @retval (Return Value) is part of the Doxygen Documentation Standard. Bitcoin Core developers use this to generate automated, high-fidelity documentation.

• @param[in]: This explicitly tells the developer that the function only "Reads" the transaction; it doesn't modify it. This is a "Safety Guarantee."

• @retval true: The function returns a Boolean. This return value is the node's way of saying "I have accepted responsibility for this transaction."

5. The Semantic Meaning of "Added"

When a transaction is "Added" to the PrivateBroadcast storage, it is not immediately sent to the network. This is a common misconception. The Add function simply places the transaction into the "State of Intent."

By returning true, the module is essentially issuing a "Receipt" to the caller (usually the Wallet). It says: "The transaction is now in the private queue. I will now manage its lifecycle, handle its timeouts, and ensure it eventually reaches a peer." This decoupling of "Adding" and "Sending" is what allows the node to manage its bandwidth and privacy carefully, rather than acting impulsively the moment a transaction is created.

Conclusion: The Gatekeeper's Promise

Lines 50-56 represent the "Handshake" between the privacy module and the rest of the Bitcoin engine. We have a robust roster for tracking recipients (peers) and a clear, documented gateway for new data (Add). This is the point where a local secret begins its transformation into a global cryptographic truth, protected by the structural integrity of the PrivateBroadcast class.