github.com/btcsuite/btcd@v0.24.0/wire/README.md (about)

     1  wire
     2  ====
     3  
     4  [![Build Status](https://github.com/btcsuite/btcd/workflows/Build%20and%20Test/badge.svg)](https://github.com/btcsuite/btcd/actions)
     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)](https://pkg.go.dev/github.com/btcsuite/btcd/wire)
     7  =======
     8  
     9  Package wire implements the bitcoin wire protocol.  A comprehensive suite of
    10  tests with 100% test coverage is provided to ensure proper functionality.
    11  
    12  There 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  
    15  This package has intentionally been designed so it can be used as a standalone
    16  package for any projects needing to interface with bitcoin peers at the wire
    17  protocol 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  
    27  The bitcoin protocol consists of exchanging messages between peers. Each message
    28  is preceded by a header which identifies information about it such as which
    29  bitcoin network it is a part of, its type, how big it is, and a checksum to
    30  verify validity. All encoding and decoding of message headers is handled by this
    31  package.
    32  
    33  To 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
    35  around through channels, functions, etc. In addition, concrete implementations
    36  of most of the currently supported bitcoin messages are provided. For these
    37  supported messages, all of the details of marshalling and unmarshalling to and
    38  from the wire using bitcoin encoding are handled so the caller doesn't have to
    39  concern themselves with the specifics.
    40  
    41  ## Reading Messages Example
    42  
    43  In order to unmarshal bitcoin messages from the wire, use the `ReadMessage`
    44  function. It accepts any `io.Reader`, but typically this will be a `net.Conn`
    45  to 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  
    63  See the package documentation for details on determining the message type.
    64  
    65  ## Writing Messages Example
    66  
    67  In order to marshal bitcoin messages to the wire, use the `WriteMessage`
    68  function. It accepts any `io.Writer`, but typically this will be a `net.Conn`
    69  to a remote node running a bitcoin peer. Example syntax to request addresses
    70  from 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  
    92  All official release tags are signed by Conformal so users can ensure the code
    93  has not been tampered with and is coming from the btcsuite developers.  To
    94  verify 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  
   112  Package wire is licensed under the [copyfree](http://copyfree.org) ISC
   113  License.