github.com/dashpay/godash@v0.0.0-20160726055534-e038a21e0e3d/addrmgr/doc.go (about)

     1  // Copyright (c) 2014 The btcsuite developers
     2  // Copyright (c) 2016 The Dash developers
     3  // Use of this source code is governed by an ISC
     4  // license that can be found in the LICENSE file.
     5  
     6  /*
     7  Package addrmgr implements concurrency safe Bitcoin address manager.
     8  
     9  Address Manager Overview
    10  
    11  In order maintain the peer-to-peer Bitcoin network, there needs to be a source
    12  of addresses to connect to as nodes come and go.  The Bitcoin protocol provides
    13  a the getaddr and addr messages to allow peers to communicate known addresses
    14  with each other.  However, there needs to a mechanism to store those results and
    15  select peers from them.  It is also important to note that remote peers can't
    16  be trusted to send valid peers nor attempt to provide you with only peers they
    17  control with malicious intent.
    18  
    19  With that in mind, this package provides a concurrency safe address manager for
    20  caching and selecting peers in a non-determinstic manner.  The general idea is
    21  the caller adds addresses to the address manager and notifies it when addresses
    22  are connected, known good, and attempted.  The caller also requests addresses as
    23  it needs them.
    24  
    25  The address manager internally segregates the addresses into groups and
    26  non-deterministically selects groups in a cryptographically random manner.  This
    27  reduce the chances multiple addresses from the same nets are selected which
    28  generally helps provide greater peer diversity, and perhaps more importantly,
    29  drastically reduces the chances an attacker is able to coerce your peer into
    30  only connecting to nodes they control.
    31  
    32  The address manager also understands routability and tor addresses and tries
    33  hard to only return routable addresses.  In addition, it uses the information
    34  provided by the caller about connected, known good, and attempted addresses to
    35  periodically purge peers which no longer appear to be good peers as well as
    36  bias the selection toward known good peers.  The general idea is to make a best
    37  effort at only providing usuable addresses.
    38  */
    39  package addrmgr