github.com/palcoin-project/palcd@v1.0.0/peer/doc.go (about)

     1  // Copyright (c) 2015-2016 The btcsuite developers
     2  // Use of this source code is governed by an ISC
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package peer provides a common base for creating and managing Bitcoin network
     7  peers.
     8  
     9  Overview
    10  
    11  This package builds upon the wire package, which provides the fundamental
    12  primitives necessary to speak the bitcoin wire protocol, in order to simplify
    13  the process of creating fully functional peers.  In essence, it provides a
    14  common base for creating concurrent safe fully validating nodes, Simplified
    15  Payment Verification (SPV) nodes, proxies, etc.
    16  
    17  A quick overview of the major features peer provides are as follows:
    18  
    19   - Provides a basic concurrent safe bitcoin peer for handling bitcoin
    20     communications via the peer-to-peer protocol
    21   - Full duplex reading and writing of bitcoin protocol messages
    22   - Automatic handling of the initial handshake process including protocol
    23     version negotiation
    24   - Asynchronous message queuing of outbound messages with optional channel for
    25     notification when the message is actually sent
    26   - Flexible peer configuration
    27     - Caller is responsible for creating outgoing connections and listening for
    28       incoming connections so they have flexibility to establish connections as
    29       they see fit (proxies, etc)
    30     - User agent name and version
    31     - Bitcoin network
    32     - Service support signalling (full nodes, bloom filters, etc)
    33     - Maximum supported protocol version
    34     - Ability to register callbacks for handling bitcoin protocol messages
    35   - Inventory message batching and send trickling with known inventory detection
    36     and avoidance
    37   - Automatic periodic keep-alive pinging and pong responses
    38   - Random nonce generation and self connection detection
    39   - Proper handling of bloom filter related commands when the caller does not
    40     specify the related flag to signal support
    41     - Disconnects the peer when the protocol version is high enough
    42     - Does not invoke the related callbacks for older protocol versions
    43   - Snapshottable peer statistics such as the total number of bytes read and
    44     written, the remote address, user agent, and negotiated protocol version
    45   - Helper functions pushing addresses, getblocks, getheaders, and reject
    46     messages
    47     - These could all be sent manually via the standard message output function,
    48       but the helpers provide additional nice functionality such as duplicate
    49       filtering and address randomization
    50   - Ability to wait for shutdown/disconnect
    51   - Comprehensive test coverage
    52  
    53  Peer Configuration
    54  
    55  All peer configuration is handled with the Config struct.  This allows the
    56  caller to specify things such as the user agent name and version, the bitcoin
    57  network to use, which services it supports, and callbacks to invoke when bitcoin
    58  messages are received.  See the documentation for each field of the Config
    59  struct for more details.
    60  
    61  Inbound and Outbound Peers
    62  
    63  A peer can either be inbound or outbound.  The caller is responsible for
    64  establishing the connection to remote peers and listening for incoming peers.
    65  This provides high flexibility for things such as connecting via proxies, acting
    66  as a proxy, creating bridge peers, choosing whether to listen for inbound peers,
    67  etc.
    68  
    69  NewOutboundPeer and NewInboundPeer functions must be followed by calling Connect
    70  with a net.Conn instance to the peer.  This will start all async I/O goroutines
    71  and initiate the protocol negotiation process.  Once finished with the peer call
    72  Disconnect to disconnect from the peer and clean up all resources.
    73  WaitForDisconnect can be used to block until peer disconnection and resource
    74  cleanup has completed.
    75  
    76  Callbacks
    77  
    78  In order to do anything useful with a peer, it is necessary to react to bitcoin
    79  messages.  This is accomplished by creating an instance of the MessageListeners
    80  struct with the callbacks to be invoke specified and setting the Listeners field
    81  of the Config struct specified when creating a peer to it.
    82  
    83  For convenience, a callback hook for all of the currently supported bitcoin
    84  messages is exposed which receives the peer instance and the concrete message
    85  type.  In addition, a hook for OnRead is provided so even custom messages types
    86  for which this package does not directly provide a hook, as long as they
    87  implement the wire.Message interface, can be used.  Finally, the OnWrite hook
    88  is provided, which in conjunction with OnRead, can be used to track server-wide
    89  byte counts.
    90  
    91  It is often useful to use closures which encapsulate state when specifying the
    92  callback handlers.  This provides a clean method for accessing that state when
    93  callbacks are invoked.
    94  
    95  Queuing Messages and Inventory
    96  
    97  The QueueMessage function provides the fundamental means to send messages to the
    98  remote peer.  As the name implies, this employs a non-blocking queue.  A done
    99  channel which will be notified when the message is actually sent can optionally
   100  be specified.  There are certain message types which are better sent using other
   101  functions which provide additional functionality.
   102  
   103  Of special interest are inventory messages.  Rather than manually sending MsgInv
   104  messages via Queuemessage, the inventory vectors should be queued using the
   105  QueueInventory function.  It employs batching and trickling along with
   106  intelligent known remote peer inventory detection and avoidance through the use
   107  of a most-recently used algorithm.
   108  
   109  Message Sending Helper Functions
   110  
   111  In addition to the bare QueueMessage function previously described, the
   112  PushAddrMsg, PushGetBlocksMsg, PushGetHeadersMsg, and PushRejectMsg functions
   113  are provided as a convenience.  While it is of course possible to create and
   114  send these message manually via QueueMessage, these helper functions provided
   115  additional useful functionality that is typically desired.
   116  
   117  For example, the PushAddrMsg function automatically limits the addresses to the
   118  maximum number allowed by the message and randomizes the chosen addresses when
   119  there are too many.  This allows the caller to simply provide a slice of known
   120  addresses, such as that returned by the addrmgr package, without having to worry
   121  about the details.
   122  
   123  Next, the PushGetBlocksMsg and PushGetHeadersMsg functions will construct proper
   124  messages using a block locator and ignore back to back duplicate requests.
   125  
   126  Finally, the PushRejectMsg function can be used to easily create and send an
   127  appropriate reject message based on the provided parameters as well as
   128  optionally provides a flag to cause it to block until the message is actually
   129  sent.
   130  
   131  Peer Statistics
   132  
   133  A snapshot of the current peer statistics can be obtained with the StatsSnapshot
   134  function.  This includes statistics such as the total number of bytes read and
   135  written, the remote address, user agent, and negotiated protocol version.
   136  
   137  Logging
   138  
   139  This package provides extensive logging capabilities through the UseLogger
   140  function which allows a btclog.Logger to be specified.  For example, logging at
   141  the debug level provides summaries of every message sent and received, and
   142  logging at the trace level provides full dumps of parsed messages as well as the
   143  raw message bytes using a format similar to hexdump -C.
   144  
   145  Bitcoin Improvement Proposals
   146  
   147  This package supports all BIPS supported by the wire package.
   148  (https://pkg.go.dev/github.com/palcoin-project/palcd/wire#hdr-Bitcoin_Improvement_Proposals)
   149  */
   150  package peer