1 // Copyright (c) 2012 Pieter Wuille
2 // Copyright (c) 2012-present The Bitcoin Core developers
3 // Distributed under the MIT software license, see the accompanying
4 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
5 6 #ifndef BITCOIN_ADDRMAN_H
7 #define BITCOIN_ADDRMAN_H
8 9 #include <netaddress.h>
10 #include <protocol.h>
11 #include <util/time.h>
12 13 #include <cstddef>
14 #include <cstdint>
15 #include <ios>
16 #include <memory>
17 #include <optional>
18 #include <string>
19 #include <tuple>
20 #include <unordered_set>
21 #include <utility>
22 #include <vector>
23 24 class NetGroupManager;
25 26 /** Over how many buckets entries with tried addresses from a single group (/16 for IPv4) are spread */
27 static constexpr uint32_t ADDRMAN_TRIED_BUCKETS_PER_GROUP{8};
28 /** Over how many buckets entries with new addresses originating from a single group are spread */
29 static constexpr uint32_t ADDRMAN_NEW_BUCKETS_PER_SOURCE_GROUP{64};
30 /** Maximum number of times an address can occur in the new table */
31 static constexpr int32_t ADDRMAN_NEW_BUCKETS_PER_ADDRESS{8};
32 /** How old addresses can maximally be */
33 static constexpr auto ADDRMAN_HORIZON{30 * 24h};
34 /** After how many failed attempts we give up on a new node */
35 static constexpr int32_t ADDRMAN_RETRIES{3};
36 /** How many successive failures are allowed ... */
37 static constexpr int32_t ADDRMAN_MAX_FAILURES{10};
38 /** ... in at least this duration */
39 static constexpr auto ADDRMAN_MIN_FAIL{7 * 24h};
40 /** How recent a successful connection should be before we allow an address to be evicted from tried */
41 static constexpr auto ADDRMAN_REPLACEMENT{4h};
42 /** The maximum number of tried addr collisions to store */
43 static constexpr size_t ADDRMAN_SET_TRIED_COLLISION_SIZE{10};
44 /** The maximum time we'll spend trying to resolve a tried table collision */
45 static constexpr auto ADDRMAN_TEST_WINDOW{40min};
46 47 class InvalidAddrManVersionError : public std::ios_base::failure
48 {
49 public:
50 InvalidAddrManVersionError(std::string msg) : std::ios_base::failure(msg) { }
51 };
52 53 class AddrManImpl;
54 class AddrInfo;
55 56 /** Default for -checkaddrman */
57 static constexpr int32_t DEFAULT_ADDRMAN_CONSISTENCY_CHECKS{0};
58 59 /** Location information for an address in AddrMan */
60 struct AddressPosition {
61 // Whether the address is in the new or tried table
62 const bool tried;
63 64 // Addresses in the tried table should always have a multiplicity of 1.
65 // Addresses in the new table can have multiplicity between 1 and
66 // ADDRMAN_NEW_BUCKETS_PER_ADDRESS
67 const int multiplicity;
68 69 // If the address is in the new table, the bucket and position are
70 // populated based on the first source who sent the address.
71 // In certain edge cases, this may not be where the address is currently
72 // located.
73 const int bucket;
74 const int position;
75 76 bool operator==(AddressPosition other) {
77 return std::tie(tried, multiplicity, bucket, position) ==
78 std::tie(other.tried, other.multiplicity, other.bucket, other.position);
79 }
80 explicit AddressPosition(bool tried_in, int multiplicity_in, int bucket_in, int position_in)
81 : tried{tried_in}, multiplicity{multiplicity_in}, bucket{bucket_in}, position{position_in} {}
82 };
83 84 /** Stochastic address manager
85 *
86 * Design goals:
87 * * Keep the address tables in-memory, and asynchronously dump the entire table to peers.dat.
88 * * Make sure no (localized) attacker can fill the entire table with his nodes/addresses.
89 *
90 * To that end:
91 * * Addresses are organized into buckets that can each store up to 64 entries.
92 * * Addresses to which our node has not successfully connected go into 1024 "new" buckets.
93 * * Based on the address range (/16 for IPv4) of the source of information, or if an asmap is provided,
94 * the AS it belongs to (for IPv4/IPv6), 64 buckets are selected at random.
95 * * The actual bucket is chosen from one of these, based on the range in which the address itself is located.
96 * * The position in the bucket is chosen based on the full address.
97 * * One single address can occur in up to 8 different buckets to increase selection chances for addresses that
98 * are seen frequently. The chance for increasing this multiplicity decreases exponentially.
99 * * When adding a new address to an occupied position of a bucket, it will not replace the existing entry
100 * unless that address is also stored in another bucket or it doesn't meet one of several quality criteria
101 * (see IsTerrible for exact criteria).
102 * * Addresses of nodes that are known to be accessible go into 256 "tried" buckets.
103 * * Each address range selects at random 8 of these buckets.
104 * * The actual bucket is chosen from one of these, based on the full address.
105 * * When adding a new good address to an occupied position of a bucket, a FEELER connection to the
106 * old address is attempted. The old entry is only replaced and moved back to the "new" buckets if this
107 * attempt was unsuccessful.
108 * * Bucket selection is based on cryptographic hashing, using a randomly-generated 256-bit key, which should not
109 * be observable by adversaries.
110 * * Several indexes are kept for high performance. Setting m_consistency_check_ratio with the -checkaddrman
111 * configuration option will introduce (expensive) consistency checks for the entire data structure.
112 */
113 class AddrMan
114 {
115 protected:
116 const std::unique_ptr<AddrManImpl> m_impl;
117 118 public:
119 explicit AddrMan(const NetGroupManager& netgroupman, bool deterministic, int32_t consistency_check_ratio);
120 121 ~AddrMan();
122 123 template <typename Stream>
124 void Serialize(Stream& s_) const;
125 126 template <typename Stream>
127 void Unserialize(Stream& s_);
128 129 /**
130 * Return size information about addrman.
131 *
132 * @param[in] net Select addresses only from specified network (nullopt = all)
133 * @param[in] in_new Select addresses only from one table (true = new, false = tried, nullopt = both)
134 * @return Number of unique addresses that match specified options.
135 */
136 size_t Size(std::optional<Network> net = std::nullopt, std::optional<bool> in_new = std::nullopt) const;
137 138 /**
139 * Attempt to add one or more addresses to addrman's new table.
140 * If an address already exists in addrman, the existing entry may be updated
141 * (e.g. adding additional service flags). If the existing entry is in the new table,
142 * it may be added to more buckets, improving the probability of selection.
143 *
144 * @param[in] vAddr Address records to attempt to add.
145 * @param[in] source The address of the node that sent us these addr records.
146 * @param[in] time_penalty A "time penalty" to apply to the address record's nTime. If a peer
147 * sends us an address record with nTime=n, then we'll add it to our
148 * addrman with nTime=(n - time_penalty).
149 * @return true if at least one address is successfully added, or added to an additional bucket. Unaffected by updates. */
150 bool Add(const std::vector<CAddress>& vAddr, const CNetAddr& source, std::chrono::seconds time_penalty = 0s);
151 152 /**
153 * Mark an address record as accessible and attempt to move it to addrman's tried table.
154 *
155 * @param[in] addr Address record to attempt to move to tried table.
156 * @param[in] time The time that we were last connected to this peer.
157 * @return true if the address is successfully moved from the new table to the tried table.
158 */
159 bool Good(const CService& addr, NodeSeconds time = Now<NodeSeconds>());
160 161 //! Mark an entry as connection attempted to.
162 void Attempt(const CService& addr, bool fCountFailure, NodeSeconds time = Now<NodeSeconds>());
163 164 //! See if any to-be-evicted tried table entries have been tested and if so resolve the collisions.
165 void ResolveCollisions();
166 167 /**
168 * Randomly select an address in the tried table that another address is
169 * attempting to evict.
170 *
171 * @return CAddress The record for the selected tried peer.
172 * seconds The last time we attempted to connect to that peer.
173 */
174 std::pair<CAddress, NodeSeconds> SelectTriedCollision();
175 176 /**
177 * Choose an address to connect to.
178 *
179 * @param[in] new_only Whether to only select addresses from the new table. Passing `true` returns
180 * an address from the new table or an empty pair. Passing `false` will return an
181 * empty pair or an address from either the new or tried table (it does not
182 * guarantee a tried entry).
183 * @param[in] networks Select only addresses of these networks (empty = all). Passing networks may
184 * slow down the search.
185 * @return CAddress The record for the selected peer.
186 * seconds The last time we attempted to connect to that peer.
187 */
188 std::pair<CAddress, NodeSeconds> Select(bool new_only = false, const std::unordered_set<Network>& networks = {}) const;
189 190 /**
191 * Return all or many randomly selected addresses, optionally by network.
192 *
193 * @param[in] max_addresses Maximum number of addresses to return (0 = all).
194 * @param[in] max_pct Maximum percentage of addresses to return (0 = all). Value must be from 0 to 100.
195 * @param[in] network Select only addresses of this network (nullopt = all).
196 * @param[in] filtered Select only addresses that are considered good quality (false = all).
197 *
198 * @return A vector of randomly selected addresses from vRandom.
199 */
200 std::vector<CAddress> GetAddr(size_t max_addresses, size_t max_pct, std::optional<Network> network, bool filtered = true) const;
201 202 /**
203 * Returns an information-location pair for all addresses in the selected addrman table.
204 * If an address appears multiple times in the new table, an information-location pair
205 * is returned for each occurrence. Addresses only ever appear once in the tried table.
206 *
207 * @param[in] from_tried Selects which table to return entries from.
208 *
209 * @return A vector consisting of pairs of AddrInfo and AddressPosition.
210 */
211 std::vector<std::pair<AddrInfo, AddressPosition>> GetEntries(bool from_tried) const;
212 213 /** We have successfully connected to this peer. Calling this function
214 * updates the CAddress's nTime, which is used in our IsTerrible()
215 * decisions and gossiped to peers. Callers should be careful that updating
216 * this information doesn't leak topology information to network spies.
217 *
218 * net_processing calls this function when it *disconnects* from a peer to
219 * not leak information about currently connected peers.
220 *
221 * @param[in] addr The address of the peer we were connected to
222 * @param[in] time The time that we were last connected to this peer
223 */
224 void Connected(const CService& addr, NodeSeconds time = Now<NodeSeconds>());
225 226 //! Update an entry's service bits.
227 void SetServices(const CService& addr, ServiceFlags nServices);
228 229 /** Test-only function
230 * Find the address record in AddrMan and return information about its
231 * position.
232 * @param[in] addr The address record to look up.
233 * @return Information about the address record in AddrMan
234 * or nullopt if address is not found.
235 */
236 std::optional<AddressPosition> FindAddressEntry(const CAddress& addr);
237 };
238 239 #endif // BITCOIN_ADDRMAN_H
240