github.com/BlockABC/godash@v0.0.0-20191112120524-f4aa3a32c566/wire/README.md (about)

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