1 /*Package wire implements the bitcoin wire protocol.
2 3 For the complete details of the bitcoin protocol, see the official wiki entry at
4 https://en.bitcoin.it/wiki/Protocol_specification. The following only serves as a quick overview to provide information
5 on how to use the package.
6 7 At a high level, this package provides support for marshalling and unmarshalling supported bitcoin messages to and from
8 the wire. This package does not deal with the specifics of message handling such as what to do when a message is
9 received. This provides the caller with a high level of flexibility.
10 11 Bitcoin Message Overview
12 13 The bitcoin protocol consists of exchanging messages between peers. Each message is preceded by a header which
14 identifies information about it such as which bitcoin network it is a part of, its type, how big it is, and a checksum
15 to verify validity. All encoding and decoding of message headers is handled by this package.
16 17 To accomplish this, there is a generic interface for bitcoin messages named Message which allows messages of any type to
18 be read, written, or passed around through channels, functions, etc. In addition, concrete implementations of most of
19 the currently supported bitcoin messages are provided. For these supported messages, all of the details of marshalling
20 and unmarshalling to and from the wire using bitcoin encoding are handled so the caller doesn't have to concern
21 themselves with the specifics.
22 23 Message Interaction
24 25 The following provides a quick summary of how the bitcoin messages are intended to interact with one another. As stated
26 above, these interactions are not directly handled by this package. For more in-depth details about the appropriate
27 interactions, see the official bitcoin protocol wiki entry at https://en.bitcoin.it/wiki/Protocol_specification.
28 29 The initial handshake consists of two peers sending each other a version message (MsgVersion) followed by responding
30 with a verack message (MsgVerAck). Both peers use the information in the version message (MsgVersion) to negotiate
31 things such as protocol version and supported services with each other. Once the initial handshake is complete, the
32 following chart indicates message interactions in no particular order.
33 34 Peer A Sends Peer B Responds
35 ----------------------------------------------------------------------------
36 getaddr message (MsgGetAddr) addr message (MsgAddr)
37 getblocks message (MsgGetBlocks) inv message (MsgInv)
38 inv message (MsgInv) getdata message (MsgGetData)
39 getdata message (MsgGetData) block message (Block) -or-
40 tx message (MsgTx) -or-
41 notfound message (MsgNotFound)
42 getheaders message (MsgGetHeaders) headers message (MsgHeaders)
43 ping message (MsgPing) pong message (MsgHeaders)* -or-
44 (none -- Ability to send message is enough)
45 NOTES:
46 * The pong message was not added until later protocol versions as defined
47 in BIP0031. The BIP0031Version constant can be used to detect a recent
48 enough protocol version for this purpose (version > BIP0031Version).
49 50 Common Parameters
51 52 There are several common parameters that arise when using this package to read and write bitcoin messages. The following
53 sections provide a quick overview of these parameters so the next sections can podbuild on them.
54 55 Protocol Version
56 57 The protocol version should be negotiated with the remote peer at a higher level than this package via the version
58 (MsgVersion) message exchange, however, this package provides the wire.ProtocolVersion constant which indicates the
59 latest protocol version this package supports and is typically the value to use for all outbound connections before a
60 potentially lower protocol version is negotiated.
61 62 Bitcoin Network
63 64 The bitcoin network is a magic number which is used to identify the start of a message and which bitcoin network the
65 message applies to. This package provides the following constants:
66 67 wire.MainNet
68 wire.TestNet (Regression test network)
69 wire.TestNet3 (Test network version 3)
70 wire.SimNet (Simulation test network)
71 72 Determining Message Type
73 74 As discussed in the bitcoin message overview section, this package reads and writes bitcoin messages using a generic
75 interface named Message. In order to determine the actual concrete type of the message, use a type switch or type
76 assertion. An example of a type switch follows:
77 78 79 // Assumes msg is already a valid concrete message such as one created
80 81 // via NewMsgVersion or read via ReadMessage.
82 83 switch msg := msg.(type) {
84 85 86 case *wire.MsgVersion:
87 88 // The message is a pointer to a MsgVersion struct.
89 log.Printf("Protocol version: %v", msg.ProtocolVersion)
90 case *wire.Block:
91 92 // The message is a pointer to a Block struct.
93 log.Printf("Number of tx in block: %v", msg.Header.TxnCount)
94 }
95 96 Reading Messages
97 98 In order to unmarshall bitcoin messages from the wire, use the ReadMessage function. It accepts any io.Reader, but
99 typically this will be a net.Conn to a remote node running a bitcoin peer. Example syntax is:
100 101 // Reads and validates the next bitcoin message from conn using the
102 // protocol version pver and the bitcoin network btcnet. The returns
103 // are a wire.Message, a []byte which contains the unmarshalled
104 // raw payload, and a possible error.
105 msg, rawPayload, e := wire.ReadMessage(conn, pver, btcnet)
106 if e != nil {
107 // Log and handle the error
108 }
109 110 Writing Messages
111 112 In order to marshall bitcoin messages to the wire, use the WriteMessage function. It accepts any io.Writer, but
113 typically this will be a net.Conn to a remote node running a bitcoin peer. Example syntax to request addresses from a
114 remote peer is:
115 116 // Create a new getaddr bitcoin message.
117 msg := wire.NewMsgGetAddr()
118 // Writes a bitcoin message msg to conn using the protocol version
119 // pver, and the bitcoin network btcnet. The return is a possible
120 // error.
121 e := wire.WriteMessage(conn, msg, pver, btcnet)
122 if e != nil {
123 // Log and handle the error
124 }
125 126 Errors
127 128 Errors returned by this package are either the raw errors provided by underlying calls to read/write from streams such
129 as io.EOF, io.ErrUnexpectedEOF, and io.ErrShortWrite, or of type wire.MessageError. This allows the caller to
130 differentiate between general IO errors and malformed messages through type assertions.
131 132 Bitcoin Improvement Proposals
133 134 This package includes spec changes outlined by the following BIPs:
135 BIP0014 (https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki)
136 BIP0031 (https://github.com/bitcoin/bips/blob/master/bip-0031.mediawiki)
137 BIP0035 (https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki)
138 BIP0037 (https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki)
139 BIP0111 (https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki)
140 BIP0130 (https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki)
141 BIP0133 (https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki)
142 */
143 package wire
144