vendor/github.com/btcsuite/btcd/wire/README.md

   1 wire
   2 ====
   3
   4 [![Build Status](http://img.shields.io/travis/btcsuite/btcd.svg)](https://travis-ci.org/btcsuite/btcd)
   5 [![ISC License](http://img.shields.io/badge/license-ISC-blue.svg)](http://copyfree.org)
   6 [![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](http://godoc.org/github.com/btcsuite/btcd/wire)
   7
   8 Package wire implements the bitcoin wire protocol.  A comprehensive suite of
   9 tests with 100% test coverage is provided to ensure proper functionality.
  10
  11 There is an associated blog post about the release of this package
  12 [here](https://blog.conformal.com/btcwire-the-bitcoin-wire-protocol-package-from-btcd/).
  13
  14 This package has intentionally been designed so it can be used as a standalone
  15 package for any projects needing to interface with bitcoin peers at the wire
  16 protocol level.
  17
  18 ## Installation and Updating
  19
  20 ```bash
  21 $ go get -u github.com/btcsuite/btcd/wire
  22 ```
  23
  24 ## Bitcoin Message Overview
  25
  26 The bitcoin protocol consists of exchanging messages between peers. Each message
  27 is preceded by a header which identifies information about it such as which
  28 bitcoin network it is a part of, its type, how big it is, and a checksum to
  29 verify validity. All encoding and decoding of message headers is handled by this
  30 package.
  31
  32 To accomplish this, there is a generic interface for bitcoin messages named
  33 `Message` which allows messages of any type to be read, written, or passed
  34 around through channels, functions, etc. In addition, concrete implementations
  35 of most of the currently supported bitcoin messages are provided. For these
  36 supported messages, all of the details of marshalling and unmarshalling to and
  37 from the wire using bitcoin encoding are handled so the caller doesn't have to
  38 concern themselves with the specifics.
  39
  40 ## Reading Messages Example
  41
  42 In order to unmarshal bitcoin messages from the wire, use the `ReadMessage`
  43 function. It accepts any `io.Reader`, but typically this will be a `net.Conn`
  44 to a remote node running a bitcoin peer.  Example syntax is:
  45
  46 ```Go
  47         // Use the most recent protocol version supported by the package and the
  48         // main bitcoin network.
  49         pver := wire.ProtocolVersion
  50         btcnet := wire.MainNet
  51
  52         // Reads and validates the next bitcoin message from conn using the
  53         // protocol version pver and the bitcoin network btcnet.  The returns
  54         // are a wire.Message, a []byte which contains the unmarshalled
  55         // raw payload, and a possible error.
  56         msg, rawPayload, err := wire.ReadMessage(conn, pver, btcnet)
  57         if err != nil {
  58                 // Log and handle the error
  59         }
  60 ```
  61
  62 See the package documentation for details on determining the message type.
  63
  64 ## Writing Messages Example
  65
  66 In order to marshal bitcoin messages to the wire, use the `WriteMessage`
  67 function. It accepts any `io.Writer`, but typically this will be a `net.Conn`
  68 to a remote node running a bitcoin peer. Example syntax to request addresses
  69 from a remote peer is:
  70
  71 ```Go
  72         // Use the most recent protocol version supported by the package and the
  73         // main bitcoin network.
  74         pver := wire.ProtocolVersion
  75         btcnet := wire.MainNet
  76
  77         // Create a new getaddr bitcoin message.
  78         msg := wire.NewMsgGetAddr()
  79
  80         // Writes a bitcoin message msg to conn using the protocol version
  81         // pver, and the bitcoin network btcnet.  The return is a possible
  82         // error.
  83         err := wire.WriteMessage(conn, msg, pver, btcnet)
  84         if err != nil {
  85                 // Log and handle the error
  86         }
  87 ```
  88
  89 ## GPG Verification Key
  90
  91 All official release tags are signed by Conformal so users can ensure the code
  92 has not been tampered with and is coming from the btcsuite developers.  To
  93 verify the signature perform the following:
  94
  95 - Download the public key from the Conformal website at
  96   https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt
  97
  98 - Import the public key into your GPG keyring:
  99   ```bash
 100   gpg --import GIT-GPG-KEY-conformal.txt
 101   ```
 102
 103 - Verify the release tag with the following command where `TAG_NAME` is a
 104   placeholder for the specific tag:
 105   ```bash
 106   git tag -v TAG_NAME
 107   ```
 108
 109 ## License
 110
 111 Package wire is licensed under the [copyfree](http://copyfree.org) ISC
 112 License.