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