Branch data     Line data    Source code

       1                 :            : // Copyright (c) 2012 Pieter Wuille
       2                 :            : // Copyright (c) 2012-2022 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 <netgroup.h>
      11                 :            : #include <protocol.h>
      12                 :            : #include <streams.h>
      13                 :            : #include <util/time.h>
      14                 :            : 
      15                 :            : #include <cstdint>
      16                 :            : #include <memory>
      17                 :            : #include <optional>
      18                 :            : #include <utility>
      19                 :            : #include <vector>
      20                 :            : 
      21                 :          0 : class InvalidAddrManVersionError : public std::ios_base::failure
      22                 :            : {
      23                 :            : public:
      24                 :          0 :     InvalidAddrManVersionError(std::string msg) : std::ios_base::failure(msg) { }
      25                 :            : };
      26                 :            : 
      27                 :            : class AddrManImpl;
      28                 :            : 
      29                 :            : /** Default for -checkaddrman */
      30                 :            : static constexpr int32_t DEFAULT_ADDRMAN_CONSISTENCY_CHECKS{0};
      31                 :            : 
      32                 :            : /** Test-only struct, capturing info about an address in AddrMan */
      33                 :            : struct AddressPosition {
      34                 :            :     // Whether the address is in the new or tried table
      35                 :            :     const bool tried;
      36                 :            : 
      37                 :            :     // Addresses in the tried table should always have a multiplicity of 1.
      38                 :            :     // Addresses in the new table can have multiplicity between 1 and
      39                 :            :     // ADDRMAN_NEW_BUCKETS_PER_ADDRESS
      40                 :            :     const int multiplicity;
      41                 :            : 
      42                 :            :     // If the address is in the new table, the bucket and position are
      43                 :            :     // populated based on the first source who sent the address.
      44                 :            :     // In certain edge cases, this may not be where the address is currently
      45                 :            :     // located.
      46                 :            :     const int bucket;
      47                 :            :     const int position;
      48                 :            : 
      49                 :            :     bool operator==(AddressPosition other) {
      50                 :            :         return std::tie(tried, multiplicity, bucket, position) ==
      51                 :            :                std::tie(other.tried, other.multiplicity, other.bucket, other.position);
      52                 :            :     }
      53                 :          0 :     explicit AddressPosition(bool tried_in, int multiplicity_in, int bucket_in, int position_in)
      54                 :          0 :         : tried{tried_in}, multiplicity{multiplicity_in}, bucket{bucket_in}, position{position_in} {}
      55                 :            : };
      56                 :            : 
      57                 :            : /** Stochastic address manager
      58                 :            :  *
      59                 :            :  * Design goals:
      60                 :            :  *  * Keep the address tables in-memory, and asynchronously dump the entire table to peers.dat.
      61                 :            :  *  * Make sure no (localized) attacker can fill the entire table with his nodes/addresses.
      62                 :            :  *
      63                 :            :  * To that end:
      64                 :            :  *  * Addresses are organized into buckets that can each store up to 64 entries.
      65                 :            :  *    * Addresses to which our node has not successfully connected go into 1024 "new" buckets.
      66                 :            :  *      * Based on the address range (/16 for IPv4) of the source of information, or if an asmap is provided,
      67                 :            :  *        the AS it belongs to (for IPv4/IPv6), 64 buckets are selected at random.
      68                 :            :  *      * The actual bucket is chosen from one of these, based on the range in which the address itself is located.
      69                 :            :  *      * The position in the bucket is chosen based on the full address.
      70                 :            :  *      * One single address can occur in up to 8 different buckets to increase selection chances for addresses that
      71                 :            :  *        are seen frequently. The chance for increasing this multiplicity decreases exponentially.
      72                 :            :  *      * When adding a new address to an occupied position of a bucket, it will not replace the existing entry
      73                 :            :  *        unless that address is also stored in another bucket or it doesn't meet one of several quality criteria
      74                 :            :  *        (see IsTerrible for exact criteria).
      75                 :            :  *    * Addresses of nodes that are known to be accessible go into 256 "tried" buckets.
      76                 :            :  *      * Each address range selects at random 8 of these buckets.
      77                 :            :  *      * The actual bucket is chosen from one of these, based on the full address.
      78                 :            :  *      * When adding a new good address to an occupied position of a bucket, a FEELER connection to the
      79                 :            :  *        old address is attempted. The old entry is only replaced and moved back to the "new" buckets if this
      80                 :            :  *        attempt was unsuccessful.
      81                 :            :  *    * Bucket selection is based on cryptographic hashing, using a randomly-generated 256-bit key, which should not
      82                 :            :  *      be observable by adversaries.
      83                 :            :  *    * Several indexes are kept for high performance. Setting m_consistency_check_ratio with the -checkaddrman
      84                 :            :  *      configuration option will introduce (expensive) consistency checks for the entire data structure.
      85                 :            :  */
      86                 :            : class AddrMan
      87                 :            : {
      88                 :            : protected:
      89                 :            :     const std::unique_ptr<AddrManImpl> m_impl;
      90                 :            : 
      91                 :            : public:
      92                 :            :     explicit AddrMan(const NetGroupManager& netgroupman, bool deterministic, int32_t consistency_check_ratio);
      93                 :            : 
      94                 :            :     ~AddrMan();
      95                 :            : 
      96                 :            :     template <typename Stream>
      97                 :            :     void Serialize(Stream& s_) const;
      98                 :            : 
      99                 :            :     template <typename Stream>
     100                 :            :     void Unserialize(Stream& s_);
     101                 :            : 
     102                 :            :     /**
     103                 :            :     * Return size information about addrman.
     104                 :            :     *
     105                 :            :     * @param[in] net              Select addresses only from specified network (nullopt = all)
     106                 :            :     * @param[in] in_new           Select addresses only from one table (true = new, false = tried, nullopt = both)
     107                 :            :     * @return                     Number of unique addresses that match specified options.
     108                 :            :     */
     109                 :            :     size_t Size(std::optional<Network> net = std::nullopt, std::optional<bool> in_new = std::nullopt) const;
     110                 :            : 
     111                 :            :     /**
     112                 :            :      * Attempt to add one or more addresses to addrman's new table.
     113                 :            :      *
     114                 :            :      * @param[in] vAddr           Address records to attempt to add.
     115                 :            :      * @param[in] source          The address of the node that sent us these addr records.
     116                 :            :      * @param[in] time_penalty    A "time penalty" to apply to the address record's nTime. If a peer
     117                 :            :      *                            sends us an address record with nTime=n, then we'll add it to our
     118                 :            :      *                            addrman with nTime=(n - time_penalty).
     119                 :            :      * @return    true if at least one address is successfully added. */
     120                 :            :     bool Add(const std::vector<CAddress>& vAddr, const CNetAddr& source, std::chrono::seconds time_penalty = 0s);
     121                 :            : 
     122                 :            :     /**
     123                 :            :      * Mark an address record as accessible and attempt to move it to addrman's tried table.
     124                 :            :      *
     125                 :            :      * @param[in] addr            Address record to attempt to move to tried table.
     126                 :            :      * @param[in] time            The time that we were last connected to this peer.
     127                 :            :      * @return    true if the address is successfully moved from the new table to the tried table.
     128                 :            :      */
     129                 :            :     bool Good(const CService& addr, NodeSeconds time = Now<NodeSeconds>());
     130                 :            : 
     131                 :            :     //! Mark an entry as connection attempted to.
     132                 :            :     void Attempt(const CService& addr, bool fCountFailure, NodeSeconds time = Now<NodeSeconds>());
     133                 :            : 
     134                 :            :     //! See if any to-be-evicted tried table entries have been tested and if so resolve the collisions.
     135                 :            :     void ResolveCollisions();
     136                 :            : 
     137                 :            :     /**
     138                 :            :      * Randomly select an address in the tried table that another address is
     139                 :            :      * attempting to evict.
     140                 :            :      *
     141                 :            :      * @return CAddress The record for the selected tried peer.
     142                 :            :      *         seconds  The last time we attempted to connect to that peer.
     143                 :            :      */
     144                 :            :     std::pair<CAddress, NodeSeconds> SelectTriedCollision();
     145                 :            : 
     146                 :            :     /**
     147                 :            :      * Choose an address to connect to.
     148                 :            :      *
     149                 :            :      * @param[in] new_only Whether to only select addresses from the new table. Passing `true` returns
     150                 :            :      *                     an address from the new table or an empty pair. Passing `false` will return an
     151                 :            :      *                     empty pair or an address from either the new or tried table (it does not
     152                 :            :      *                     guarantee a tried entry).
     153                 :            :      * @param[in] network  Select only addresses of this network (nullopt = all). Passing a network may
     154                 :            :      *                     slow down the search.
     155                 :            :      * @return    CAddress The record for the selected peer.
     156                 :            :      *            seconds  The last time we attempted to connect to that peer.
     157                 :            :      */
     158                 :            :     std::pair<CAddress, NodeSeconds> Select(bool new_only = false, std::optional<Network> network = std::nullopt) const;
     159                 :            : 
     160                 :            :     /**
     161                 :            :      * Return all or many randomly selected addresses, optionally by network.
     162                 :            :      *
     163                 :            :      * @param[in] max_addresses  Maximum number of addresses to return (0 = all).
     164                 :            :      * @param[in] max_pct        Maximum percentage of addresses to return (0 = all).
     165                 :            :      * @param[in] network        Select only addresses of this network (nullopt = all).
     166                 :            :      *
     167                 :            :      * @return                   A vector of randomly selected addresses from vRandom.
     168                 :            :      */
     169                 :            :     std::vector<CAddress> GetAddr(size_t max_addresses, size_t max_pct, std::optional<Network> network) const;
     170                 :            : 
     171                 :            :     /** We have successfully connected to this peer. Calling this function
     172                 :            :      *  updates the CAddress's nTime, which is used in our IsTerrible()
     173                 :            :      *  decisions and gossiped to peers. Callers should be careful that updating
     174                 :            :      *  this information doesn't leak topology information to network spies.
     175                 :            :      *
     176                 :            :      *  net_processing calls this function when it *disconnects* from a peer to
     177                 :            :      *  not leak information about currently connected peers.
     178                 :            :      *
     179                 :            :      * @param[in]   addr     The address of the peer we were connected to
     180                 :            :      * @param[in]   time     The time that we were last connected to this peer
     181                 :            :      */
     182                 :            :     void Connected(const CService& addr, NodeSeconds time = Now<NodeSeconds>());
     183                 :            : 
     184                 :            :     //! Update an entry's service bits.
     185                 :            :     void SetServices(const CService& addr, ServiceFlags nServices);
     186                 :            : 
     187                 :            :     /** Test-only function
     188                 :            :      * Find the address record in AddrMan and return information about its
     189                 :            :      * position.
     190                 :            :      * @param[in] addr       The address record to look up.
     191                 :            :      * @return               Information about the address record in AddrMan
     192                 :            :      *                       or nullopt if address is not found.
     193                 :            :      */
     194                 :            :     std::optional<AddressPosition> FindAddressEntry(const CAddress& addr);
     195                 :            : };
     196                 :            : 
     197                 :            : #endif // BITCOIN_ADDRMAN_H