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 [ + + + - ]: 1237 : 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 : 108 : struct PeerSendInfo {
42 : : CService address;
43 : : NodeClock::time_point sent;
44 : : std::optional<NodeClock::time_point> received;
45 : : };
46 : :
47 : 25 : 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 : 21 : struct SendStatus {
129 : : const NodeId nodeid; /// Node to which the transaction will be sent (or was sent).
130 : : const CService address; /// Address of the node.
131 : : const NodeClock::time_point picked; ///< When was the transaction picked for sending to the node.
132 : : std::optional<NodeClock::time_point> confirmed; ///< When was the transaction reception confirmed by the node (by PONG).
133 : :
134 : 12 : SendStatus(const NodeId& nodeid, const CService& address, const NodeClock::time_point& picked) : nodeid{nodeid}, address{address}, picked{picked} {}
135 : : };
136 : :
137 : : /// Cumulative stats from all the send attempts for a transaction. Used to prioritize transactions.
138 : : struct Priority {
139 : : size_t num_picked{0}; ///< Number of times the transaction was picked for sending.
140 : : NodeClock::time_point last_picked{}; ///< The most recent time when the transaction was picked for sending.
141 : : size_t num_confirmed{0}; ///< Number of nodes that have confirmed reception of a transaction (by PONG).
142 : : NodeClock::time_point last_confirmed{}; ///< The most recent time when the transaction was confirmed.
143 : :
144 : 5 : auto operator<=>(const Priority& other) const
145 : : {
146 : : // Invert `other` and `this` in the comparison because smaller num_picked, num_confirmed or
147 : : // earlier times mean greater priority. In other words, if this.num_picked < other.num_picked
148 : : // then this > other.
149 : 5 : return std::tie(other.num_picked, other.num_confirmed, other.last_picked, other.last_confirmed) <=>
150 : 5 : std::tie(num_picked, num_confirmed, last_picked, last_confirmed);
151 : : }
152 : : };
153 : :
154 : : /// A pair of a transaction and a sent status for a given node. Convenience return type of GetSendStatusByNode().
155 : : struct TxAndSendStatusForNode {
156 : : const CTransactionRef& tx;
157 : : SendStatus& send_status;
158 : : };
159 : :
160 : : // No need for salted hasher because we are going to store just a bunch of locally originating transactions.
161 : :
162 : : struct CTransactionRefHash {
163 : 15182 : size_t operator()(const CTransactionRef& tx) const
164 : : {
165 [ + + ]: 15182 : return static_cast<size_t>(tx->GetWitnessHash().ToUint256().GetUint64(0));
166 : : }
167 : : };
168 : :
169 : : struct CTransactionRefComp {
170 : 7 : bool operator()(const CTransactionRef& a, const CTransactionRef& b) const
171 : : {
172 [ - - ]: 7 : return a->GetWitnessHash() == b->GetWitnessHash(); // If wtxid equals, then txid also equals.
173 : : }
174 : : };
175 : :
176 : : /**
177 : : * Derive the sending priority of a transaction.
178 : : * @param[in] sent_to List of nodes that the transaction has been sent to.
179 : : */
180 : : static Priority DerivePriority(const std::vector<SendStatus>& sent_to);
181 : :
182 : : /**
183 : : * Find which transaction we sent to a given node (marked by PickTxForSend()).
184 : : * @return That transaction together with the send status or nullopt if we did not
185 : : * send any transaction to the given node.
186 : : */
187 : : std::optional<TxAndSendStatusForNode> GetSendStatusByNode(const NodeId& nodeid)
188 : : EXCLUSIVE_LOCKS_REQUIRED(m_mutex);
189 : 9 : struct TxSendStatus {
190 : : const NodeClock::time_point time_added{NodeClock::now()};
191 : : std::vector<SendStatus> send_statuses;
192 : : };
193 : : mutable Mutex m_mutex;
194 : : std::unordered_map<CTransactionRef, TxSendStatus, CTransactionRefHash, CTransactionRefComp>
195 : : m_transactions GUARDED_BY(m_mutex);
196 : : };
197 : :
198 : : #endif // BITCOIN_PRIVATE_BROADCAST_H
|
