Branch data Line data Source code
1 : : // Copyright (c) 2023-present The Bitcoin Core developers
2 : : // Distributed under the MIT software license, see the accompanying
3 : : // file COPYING or https://opensource.org/license/mit/.
4 : :
5 : : #ifndef BITCOIN_PRIVATE_BROADCAST_H
6 : : #define BITCOIN_PRIVATE_BROADCAST_H
7 : :
8 : : #include <net.h>
9 : : #include <primitives/transaction.h>
10 : : #include <primitives/transaction_identifier.h>
11 : : #include <sync.h>
12 : : #include <util/time.h>
13 : :
14 : : #include <optional>
15 : : #include <tuple>
16 : : #include <unordered_map>
17 : : #include <vector>
18 : :
19 : : /**
20 : : * Store a list of transactions to be broadcast privately. Supports the following operations:
21 : : * - Add a new transaction
22 : : * - Remove a transaction
23 : : * - Pick a transaction for sending to one recipient
24 : : * - Query which transaction has been picked for sending to a given recipient node
25 : : * - Mark that a given recipient node has confirmed receipt of a transaction
26 : : * - Query whether a given recipient node has confirmed reception
27 : : * - Query whether any transactions that need sending are currently on the list
28 : : */
29 [ + + ]: 7256 : class PrivateBroadcast
30 : : {
31 : : public:
32 : :
33 : : /// If a transaction is not sent to any peer for this duration,
34 : : /// then we consider it stale / for rebroadcasting.
35 : : static constexpr auto INITIAL_STALE_DURATION{5min};
36 : :
37 : : /// If a transaction is not received back from the network for this duration
38 : : /// after it is broadcast, then we consider it stale / for rebroadcasting.
39 : : static constexpr auto STALE_DURATION{1min};
40 : :
41 : 0 : struct PeerSendInfo {
42 : : CService address;
43 : : NodeClock::time_point sent;
44 : : std::optional<NodeClock::time_point> received;
45 : : };
46 : :
47 : 0 : struct TxBroadcastInfo {
48 : : CTransactionRef tx;
49 : : NodeClock::time_point time_added;
50 : : std::vector<PeerSendInfo> peers;
51 : : };
52 : :
53 : : /**
54 : : * Add a transaction to the storage.
55 : : * @param[in] tx The transaction to add.
56 : : * @retval true The transaction was added.
57 : : * @retval false The transaction was already present.
58 : : */
59 : : bool Add(const CTransactionRef& tx)
60 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
61 : :
62 : : /**
63 : : * Forget a transaction.
64 : : * @param[in] tx Transaction to forget.
65 : : * @retval !nullopt The number of times the transaction was sent and confirmed
66 : : * by the recipient (if the transaction existed and was removed).
67 : : * @retval nullopt The transaction was not in the storage.
68 : : */
69 : : std::optional<size_t> Remove(const CTransactionRef& tx)
70 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
71 : :
72 : : /**
73 : : * Pick the transaction with the fewest send attempts, and confirmations,
74 : : * and oldest send/confirm times.
75 : : * @param[in] will_send_to_nodeid Will remember that the returned transaction
76 : : * was picked for sending to this node.
77 : : * @param[in] will_send_to_address Address of the peer to which this transaction
78 : : * will be sent.
79 : : * @return Most urgent transaction or nullopt if there are no transactions.
80 : : */
81 : : std::optional<CTransactionRef> PickTxForSend(const NodeId& will_send_to_nodeid, const CService& will_send_to_address)
82 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
83 : :
84 : : /**
85 : : * Get the transaction that was picked for sending to a given node by PickTxForSend().
86 : : * @param[in] nodeid Node to which a transaction is being (or was) sent.
87 : : * @return Transaction or nullopt if the nodeid is unknown.
88 : : */
89 : : std::optional<CTransactionRef> GetTxForNode(const NodeId& nodeid)
90 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
91 : :
92 : : /**
93 : : * Mark that the node has confirmed reception of the transaction we sent it by
94 : : * responding with `PONG` to our `PING` message.
95 : : * @param[in] nodeid Node that we sent a transaction to.
96 : : */
97 : : void NodeConfirmedReception(const NodeId& nodeid)
98 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
99 : :
100 : : /**
101 : : * Check if the node has confirmed reception of the transaction.
102 : : * @retval true Node has confirmed, `NodeConfirmedReception()` has been called.
103 : : * @retval false Node has not confirmed, `NodeConfirmedReception()` has not been called.
104 : : */
105 : : bool DidNodeConfirmReception(const NodeId& nodeid)
106 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
107 : :
108 : : /**
109 : : * Check if there are transactions that need to be broadcast.
110 : : */
111 : : bool HavePendingTransactions()
112 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
113 : :
114 : : /**
115 : : * Get the transactions that have not been broadcast recently.
116 : : */
117 : : std::vector<CTransactionRef> GetStale() const
118 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
119 : :
120 : : /**
121 : : * Get stats about all transactions currently being privately broadcast.
122 : : */
123 : : std::vector<TxBroadcastInfo> GetBroadcastInfo() const
124 : : EXCLUSIVE_LOCKS_REQUIRED(!m_mutex);
125 : :
126 : : private:
127 : : /// Status of a transaction sent to a given node.
128 : 0 : struct SendStatus {
129 : : /// Node to which the transaction will be sent (or was sent).
130 : : const NodeId nodeid;
131 : : /// Address of the node.
132 : : const CService address;
133 : : /// When was the transaction picked for sending to the node.
134 : : const NodeClock::time_point picked;
135 : : /// When was the transaction reception confirmed by the node (by PONG).
136 : : std::optional<NodeClock::time_point> confirmed;
137 : :
138 : 0 : SendStatus(const NodeId& nodeid, const CService& address, const NodeClock::time_point& picked) : nodeid{nodeid}, address{address}, picked{picked} {}
139 : : };
140 : :
141 : : /// Cumulative stats from all the send attempts for a transaction. Used to prioritize transactions.
142 : : struct Priority {
143 : : size_t num_picked{0}; ///< Number of times the transaction was picked for sending.
144 : : NodeClock::time_point last_picked{}; ///< The most recent time when the transaction was picked for sending.
145 : : size_t num_confirmed{0}; ///< Number of nodes that have confirmed reception of a transaction (by PONG).
146 : : NodeClock::time_point last_confirmed{}; ///< The most recent time when the transaction was confirmed.
147 : :
148 : 0 : auto operator<=>(const Priority& other) const
149 : : {
150 : : // Invert `other` and `this` in the comparison because smaller num_picked, num_confirmed or
151 : : // earlier times mean greater priority. In other words, if this.num_picked < other.num_picked
152 : : // then this > other.
153 : 0 : return std::tie(other.num_picked, other.num_confirmed, other.last_picked, other.last_confirmed) <=>
154 : 0 : std::tie(num_picked, num_confirmed, last_picked, last_confirmed);
155 : : }
156 : : };
157 : :
158 : : /// A pair of a transaction and a sent status for a given node. Convenience return type of GetSendStatusByNode().
159 : : struct TxAndSendStatusForNode {
160 : : const CTransactionRef& tx;
161 : : SendStatus& send_status;
162 : : };
163 : :
164 : : // No need for salted hasher because we are going to store just a bunch of locally originating transactions.
165 : :
166 : : struct CTransactionRefHash {
167 : 0 : size_t operator()(const CTransactionRef& tx) const
168 : : {
169 [ # # ]: 0 : return static_cast<size_t>(tx->GetWitnessHash().ToUint256().GetUint64(0));
170 : : }
171 : : };
172 : :
173 : : struct CTransactionRefComp {
174 : 0 : bool operator()(const CTransactionRef& a, const CTransactionRef& b) const
175 : : {
176 [ # # ]: 0 : return a->GetWitnessHash() == b->GetWitnessHash(); // If wtxid equals, then txid also equals.
177 : : }
178 : : };
179 : :
180 : : /**
181 : : * Derive the sending priority of a transaction.
182 : : * @param[in] sent_to List of nodes that the transaction has been sent to.
183 : : */
184 : : static Priority DerivePriority(const std::vector<SendStatus>& sent_to);
185 : :
186 : : /**
187 : : * Find which transaction we sent to a given node (marked by PickTxForSend()).
188 : : * @return That transaction together with the send status or nullopt if we did not
189 : : * send any transaction to the given node.
190 : : */
191 : : std::optional<TxAndSendStatusForNode> GetSendStatusByNode(const NodeId& nodeid)
192 : : EXCLUSIVE_LOCKS_REQUIRED(m_mutex);
193 : 0 : struct TxSendStatus {
194 : : const NodeClock::time_point time_added{NodeClock::now()};
195 : : std::vector<SendStatus> send_statuses;
196 : : };
197 : : mutable Mutex m_mutex;
198 : : std::unordered_map<CTransactionRef, TxSendStatus, CTransactionRefHash, CTransactionRefComp>
199 : : m_transactions GUARDED_BY(m_mutex);
200 : : };
201 : :
202 : : #endif // BITCOIN_PRIVATE_BROADCAST_H
|
