/tmp/bitcoin/src/addrman.h

Source
// Copyright (c) 2012 Pieter Wuille
// Copyright (c) 2012-present The Bitcoin Core developers
// Distributed under the MIT software license, see the accompanying
// file COPYING or http://www.opensource.org/licenses/mit-license.php.

#ifndef BITCOIN_ADDRMAN_H
#define BITCOIN_ADDRMAN_H

#include <netaddress.h>
#include <protocol.h>
#include <util/time.h>

#include <cstddef>
#include <cstdint>
#include <ios>
#include <memory>
#include <optional>
#include <string>
#include <tuple>
#include <unordered_set>
#include <utility>
#include <vector>

class NetGroupManager;

/** Over how many buckets entries with tried addresses from a single group (/16 for IPv4) are spread */
static constexpr uint32_t ADDRMAN_TRIED_BUCKETS_PER_GROUP{8};
/** Over how many buckets entries with new addresses originating from a single group are spread */
static constexpr uint32_t ADDRMAN_NEW_BUCKETS_PER_SOURCE_GROUP{64};
/** Maximum number of times an address can occur in the new table */
static constexpr int32_t ADDRMAN_NEW_BUCKETS_PER_ADDRESS{8};
/** How old addresses can maximally be */
static constexpr auto ADDRMAN_HORIZON{30 * 24h};
/** After how many failed attempts we give up on a new node */
static constexpr int32_t ADDRMAN_RETRIES{3};
/** How many successive failures are allowed ... */
static constexpr int32_t ADDRMAN_MAX_FAILURES{10};
/** ... in at least this duration */
static constexpr auto ADDRMAN_MIN_FAIL{7 * 24h};
/** How recent a successful connection should be before we allow an address to be evicted from tried */
static constexpr auto ADDRMAN_REPLACEMENT{4h};
/** The maximum number of tried addr collisions to store */
static constexpr size_t ADDRMAN_SET_TRIED_COLLISION_SIZE{10};
/** The maximum time we'll spend trying to resolve a tried table collision */
static constexpr auto ADDRMAN_TEST_WINDOW{40min};

class InvalidAddrManVersionError : public std::ios_base::failure
{
public:
    InvalidAddrManVersionError(std::string msg) : std::ios_base::failure(msg) { }
};

class AddrManImpl;
class AddrInfo;

/** Default for -checkaddrman */
static constexpr int32_t DEFAULT_ADDRMAN_CONSISTENCY_CHECKS{0};

/** Location information for an address in AddrMan */
struct AddressPosition {
    // Whether the address is in the new or tried table
    const bool tried;

    // Addresses in the tried table should always have a multiplicity of 1.
    // Addresses in the new table can have multiplicity between 1 and
    // ADDRMAN_NEW_BUCKETS_PER_ADDRESS
    const int multiplicity;

    // If the address is in the new table, the bucket and position are
    // populated based on the first source who sent the address.
    // In certain edge cases, this may not be where the address is currently
    // located.
    const int bucket;
    const int position;

    bool operator==(AddressPosition other) {
        return std::tie(tried, multiplicity, bucket, position) ==
               std::tie(other.tried, other.multiplicity, other.bucket, other.position);
    }
    explicit AddressPosition(bool tried_in, int multiplicity_in, int bucket_in, int position_in)
        : tried{tried_in}, multiplicity{multiplicity_in}, bucket{bucket_in}, position{position_in} {}
};

/** Stochastic address manager
 *
 * Design goals:
 *  * Keep the address tables in-memory, and asynchronously dump the entire table to peers.dat.
 *  * Make sure no (localized) attacker can fill the entire table with his nodes/addresses.
 *
 * To that end:
 *  * Addresses are organized into buckets that can each store up to 64 entries.
 *    * Addresses to which our node has not successfully connected go into 1024 "new" buckets.
 *      * Based on the address range (/16 for IPv4) of the source of information, or if an asmap is provided,
 *        the AS it belongs to (for IPv4/IPv6), 64 buckets are selected at random.
 *      * The actual bucket is chosen from one of these, based on the range in which the address itself is located.
 *      * The position in the bucket is chosen based on the full address.
 *      * One single address can occur in up to 8 different buckets to increase selection chances for addresses that
 *        are seen frequently. The chance for increasing this multiplicity decreases exponentially.
 *      * When adding a new address to an occupied position of a bucket, it will not replace the existing entry
 *        unless that address is also stored in another bucket or it doesn't meet one of several quality criteria
 *        (see IsTerrible for exact criteria).
 *    * Addresses of nodes that are known to be accessible go into 256 "tried" buckets.
 *      * Each address range selects at random 8 of these buckets.
 *      * The actual bucket is chosen from one of these, based on the full address.
 *      * When adding a new good address to an occupied position of a bucket, a FEELER connection to the
 *        old address is attempted. The old entry is only replaced and moved back to the "new" buckets if this
 *        attempt was unsuccessful.
 *    * Bucket selection is based on cryptographic hashing, using a randomly-generated 256-bit key, which should not
 *      be observable by adversaries.
 *    * Several indexes are kept for high performance. Setting m_consistency_check_ratio with the -checkaddrman
 *      configuration option will introduce (expensive) consistency checks for the entire data structure.
 */
class AddrMan
{
protected:
    const std::unique_ptr<AddrManImpl> m_impl;

public:
    explicit AddrMan(const NetGroupManager& netgroupman, bool deterministic, int32_t consistency_check_ratio);

    ~AddrMan();

    template <typename Stream>
    void Serialize(Stream& s_) const;

    template <typename Stream>
    void Unserialize(Stream& s_);

    /**
    * Return size information about addrman.
    *
    * @param[in] net              Select addresses only from specified network (nullopt = all)
    * @param[in] in_new           Select addresses only from one table (true = new, false = tried, nullopt = both)
    * @return                     Number of unique addresses that match specified options.
    */
    size_t Size(std::optional<Network> net = std::nullopt, std::optional<bool> in_new = std::nullopt) const;

    /**
     * Attempt to add one or more addresses to addrman's new table.
     * If an address already exists in addrman, the existing entry may be updated
     * (e.g. adding additional service flags). If the existing entry is in the new table,
     * it may be added to more buckets, improving the probability of selection.
     *
     * @param[in] vAddr           Address records to attempt to add.
     * @param[in] source          The address of the node that sent us these addr records.
     * @param[in] time_penalty    A "time penalty" to apply to the address record's nTime. If a peer
     *                            sends us an address record with nTime=n, then we'll add it to our
     *                            addrman with nTime=(n - time_penalty).
     * @return    true if at least one address is successfully added, or added to an additional bucket. Unaffected by updates. */
    bool Add(const std::vector<CAddress>& vAddr, const CNetAddr& source, std::chrono::seconds time_penalty = 0s);

    /**
     * Mark an address record as accessible and attempt to move it to addrman's tried table.
     *
     * @param[in] addr            Address record to attempt to move to tried table.
     * @param[in] time            The time that we were last connected to this peer.
     * @return    true if the address is successfully moved from the new table to the tried table.
     */
    bool Good(const CService& addr, NodeSeconds time = Now<NodeSeconds>());

    //! Mark an entry as connection attempted to.
    void Attempt(const CService& addr, bool fCountFailure, NodeSeconds time = Now<NodeSeconds>());

    //! See if any to-be-evicted tried table entries have been tested and if so resolve the collisions.
    void ResolveCollisions();

    /**
     * Randomly select an address in the tried table that another address is
     * attempting to evict.
     *
     * @return CAddress The record for the selected tried peer.
     *         seconds  The last time we attempted to connect to that peer.
     */
    std::pair<CAddress, NodeSeconds> SelectTriedCollision();

    /**
     * Choose an address to connect to.
     *
     * @param[in] new_only Whether to only select addresses from the new table. Passing `true` returns
     *                     an address from the new table or an empty pair. Passing `false` will return an
     *                     empty pair or an address from either the new or tried table (it does not
     *                     guarantee a tried entry).
     * @param[in] networks Select only addresses of these networks (empty = all). Passing networks may
     *                     slow down the search.
     * @return    CAddress The record for the selected peer.
     *            seconds  The last time we attempted to connect to that peer.
     */
    std::pair<CAddress, NodeSeconds> Select(bool new_only = false, const std::unordered_set<Network>& networks = {}) const;

    /**
     * Return all or many randomly selected addresses, optionally by network.
     *
     * @param[in] max_addresses  Maximum number of addresses to return (0 = all).
     * @param[in] max_pct        Maximum percentage of addresses to return (0 = all). Value must be from 0 to 100.
     * @param[in] network        Select only addresses of this network (nullopt = all).
     * @param[in] filtered       Select only addresses that are considered good quality (false = all).
     *
     * @return                   A vector of randomly selected addresses from vRandom.
     */
    std::vector<CAddress> GetAddr(size_t max_addresses, size_t max_pct, std::optional<Network> network, bool filtered = true) const;

    /**
     * Returns an information-location pair for all addresses in the selected addrman table.
     * If an address appears multiple times in the new table, an information-location pair
     * is returned for each occurrence. Addresses only ever appear once in the tried table.
     *
     * @param[in] from_tried     Selects which table to return entries from.
     *
     * @return                   A vector consisting of pairs of AddrInfo and AddressPosition.
     */
    std::vector<std::pair<AddrInfo, AddressPosition>> GetEntries(bool from_tried) const;

    /** We have successfully connected to this peer. Calling this function
     *  updates the CAddress's nTime, which is used in our IsTerrible()
     *  decisions and gossiped to peers. Callers should be careful that updating
     *  this information doesn't leak topology information to network spies.
     *
     *  net_processing calls this function when it *disconnects* from a peer to
     *  not leak information about currently connected peers.
     *
     * @param[in]   addr     The address of the peer we were connected to
     * @param[in]   time     The time that we were last connected to this peer
     */
    void Connected(const CService& addr, NodeSeconds time = Now<NodeSeconds>());

    //! Update an entry's service bits.
    void SetServices(const CService& addr, ServiceFlags nServices);

    /** Test-only function
     * Find the address record in AddrMan and return information about its
     * position.
     * @param[in] addr       The address record to look up.
     * @return               Information about the address record in AddrMan
     *                       or nullopt if address is not found.
     */
    std::optional<AddressPosition> FindAddressEntry(const CAddress& addr);
};

#endif // BITCOIN_ADDRMAN_H

Coverage Report

Created: 2026-06-16 16:41

Line	Count	Source
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	1	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	2	bool operator==(AddressPosition other) {
77	2	return std::tie(tried, multiplicity, bucket, position) ==
78	2	std::tie(other.tried, other.multiplicity, other.bucket, other.position);
79	2	}
80		explicit AddressPosition(bool tried_in, int multiplicity_in, int bucket_in, int position_in)
81	40	: 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