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