Intent Memory: The GetTxForNode Inquiry and Architectural State

[!NOTE] Technical Context: private_broadcast.h | Lines 85-91

In lines 85 through 91 of private_broadcast.h, we encounter the method GetTxForNode. While PickTxForSend was a "State-Changing" operation (it selects a transaction), GetTxForNode is a "State-Observing" operation. It represents the Memory of the private broadcast module—the ability to remember which transaction was assigned to which peer.

1. The Necessity of Remembrance

In the chaotic environment of a P2P network, a transaction is rarely sent and confirmed in a single millisecond. There is a period of "In-Flight" existence.

The GetTxForNode method (Line 89) allows the node to ask: "What are we currently trying to tell Peer X?" This is essential for Request Correlation. If Peer X sends back a message saying "I received it!", the node needs to know what they received. Since the nodeid is the primary key for the connection, mapping that ID back to a CTransactionRef is the only way to close the loop.

2. The Nullopt Return: Handling Disconnection

The return type std::optional<CTransactionRef> is once again used to handle the "Empty Case." If the nodeid is unknown—perhaps because the connection was dropped or the transaction was already "Forgotten"—the function returns nullopt.

This is a vital "Defensive Query." Before a networking thread performs a task related to a peer, it can check GetTxForNode. If it gets nothing back, it knows that the "Private Context" for that peer has expired, and it should stop its efforts. This prevents "Stale Work," where the CPU spends time processing data for a connection that no longer exists in the private broadcast queue.

3. NodeId: The Stable Key

The parameter is const NodeId& nodeid. In Bitcoin Core, a NodeId is a long-lived, unique integer assigned to a peer when they first connect. It is more stable than an IP address because a single IP could potentially have multiple connections or could change.

By using NodeId as the key for the inquiry, the PrivateBroadcast module ensures that its "Intent Memory" is tied to the Logical Connection, not the physical network path. This is a subtle but important distinction that increases the reliability of the private broadcast logic during network reconfigurations.

4. EXCLUSIVE_LOCKS_REQUIRED(!m_mutex)

Even though this is a "Query" (which might imply a "Read-Only" operation), the code still requires an exclusive lock (Line 90).

Why not a Shared Lock?

In many C++ systems, "Read" operations use a Shared Lock. However, in Bitcoin Core's PrivateBroadcast class, the internal data structures (unordered_map) are not thread-safe for concurrent read/write. If one thread is calling Remove() (which changes the map) while another thread is calling GetTxForNode() (which reads the map), the system could crash.

By using an exclusive lock even for queries, the architect is prioritizing Correctness over Concurrency. In the context of private broadcasting—where a single crash could lead to a loss of privacy or a node failure—this is the "Safe" choice. It ensures that the "Memory" of the node is always consistent and never corrupted by a simultaneous update.

5. Architectural Synthesis: The Observer Pattern

GetTxForNode is the implementation of the Observer Pattern. It allows the "Networking Layer" (the observer) to stay synchronized with the "Broadcast Manager" (the subject).

This decoupling is a hallmark of "Developer-Grade" code. The networking layer doesn't need to store its own copy of the private transaction list; it simply "asks" the PrivateBroadcast manager whenever it needs information. This "Single Source of Truth" architecture prevents "State Inconsistency" bugs, where two different parts of the software have different ideas about what is happening on the network.

Conclusion: The Stable Intent

Lines 85-91 provide the "Query Interface" for the private broadcast system. It is the method by which the node verifies its current actions. By mapping NodeId to CTransactionRef with type-safe optionality and strict locking, the class ensures that every private communication attempt is backed by a stable, queryable "Intent."

In the next batch (0014-0020), we will move from "Queries" to "Confirmations," seeing how the node finally marks a transaction as successfully delivered.