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

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