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