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 ```