vendor/github.com/btcsuite/btcd/peer/doc.go

   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://godoc.org/github.com/btcsuite/btcd/wire#hdr-Bitcoin_Improvement_Proposals)
 149 */
 150 package peer