github.com/lbryio/lbcd@v0.22.119/wire/README.md (about)

     1  wire
     2  ====
     3  
     4  Package wire implements the bitcoin wire protocol.  A comprehensive suite of
     5  tests with 100% test coverage is provided to ensure proper functionality.
     6  
     7  There is an associated blog post about the release of this package
     8  [here](https://blog.conformal.com/btcwire-the-bitcoin-wire-protocol-package-from-btcd/).
     9  
    10  This package has been augmented from the original btcd implementation.
    11  The block header was modified to contain the claimtrie hash.
    12  
    13  ## Bitcoin Message Overview
    14  
    15  The bitcoin protocol consists of exchanging messages between peers. Each message
    16  is preceded by a header which identifies information about it such as which
    17  bitcoin network it is a part of, its type, how big it is, and a checksum to
    18  verify validity. All encoding and decoding of message headers is handled by this
    19  package.
    20  
    21  To accomplish this, there is a generic interface for bitcoin messages named
    22  `Message` which allows messages of any type to be read, written, or passed
    23  around through channels, functions, etc. In addition, concrete implementations
    24  of most of the currently supported bitcoin messages are provided. For these
    25  supported messages, all of the details of marshalling and unmarshalling to and
    26  from the wire using bitcoin encoding are handled so the caller doesn't have to
    27  concern themselves with the specifics.
    28  
    29  ## Reading Messages Example
    30  
    31  In order to unmarshal bitcoin messages from the wire, use the `ReadMessage`
    32  function. It accepts any `io.Reader`, but typically this will be a `net.Conn`
    33  to a remote node running a bitcoin peer.  Example syntax is:
    34  
    35  ```Go
    36  	// Use the most recent protocol version supported by the package and the
    37  	// main bitcoin network.
    38  	pver := wire.ProtocolVersion
    39  	btcnet := wire.MainNet
    40  
    41  	// Reads and validates the next bitcoin message from conn using the
    42  	// protocol version pver and the bitcoin network btcnet.  The returns
    43  	// are a wire.Message, a []byte which contains the unmarshalled
    44  	// raw payload, and a possible error.
    45  	msg, rawPayload, err := wire.ReadMessage(conn, pver, btcnet)
    46  	if err != nil {
    47  		// Log and handle the error
    48  	}
    49  ```
    50  
    51  See the package documentation for details on determining the message type.
    52  
    53  ## Writing Messages Example
    54  
    55  In order to marshal bitcoin messages to the wire, use the `WriteMessage`
    56  function. It accepts any `io.Writer`, but typically this will be a `net.Conn`
    57  to a remote node running a bitcoin peer. Example syntax to request addresses
    58  from a remote peer is:
    59  
    60  ```Go
    61  	// Use the most recent protocol version supported by the package and the
    62  	// main bitcoin network.
    63  	pver := wire.ProtocolVersion
    64  	btcnet := wire.MainNet
    65  
    66  	// Create a new getaddr bitcoin message.
    67  	msg := wire.NewMsgGetAddr()
    68  
    69  	// Writes a bitcoin message msg to conn using the protocol version
    70  	// pver, and the bitcoin network btcnet.  The return is a possible
    71  	// error.
    72  	err := wire.WriteMessage(conn, msg, pver, btcnet)
    73  	if err != nil {
    74  		// Log and handle the error
    75  	}
    76  ```