1 // Package btcwire implements the Bitcoin P2P wire format and the message
2 // payloads needed by a BIP157 compact-filter light client.
3 //
4 // The package is a pure codec: it performs no I/O of its own beyond reading
5 // from and writing to the io.Reader and []byte values supplied by the caller.
6 // It deliberately avoids the net and os packages so that it can be compiled
7 // for constrained targets such as wasm.
8 //
9 // # Framing
10 //
11 // Every message is framed as a 24-byte header followed by the payload:
12 //
13 // magic uint32, big endian
14 // command 12 bytes, ASCII, NUL padded
15 // length uint32, little endian
16 // checksum 4 bytes, first 4 bytes of SHA256d(payload)
17 // payload length bytes
18 //
19 // EncodeMessage produces one such frame; DecodeMessage and Reader consume
20 // them.
21 //
22 // # Byte order
23 //
24 // Unless documented otherwise, integers use Bitcoin's little-endian wire
25 // encoding. Hashes are chainhash.Hash values in internal byte order: the
26 // bytes as they appear on the wire, which is the reverse of the order used
27 // for display.
28 //
29 // The frame magic is big endian, and network ports are big endian as specified
30 // by the version message. Both are exceptions: a magic is a four-byte string
31 // that Bitcoin writes "f9beb4d9" and sends as those bytes, so the uint32
32 // constants hold that string read big endian and the codec writes it back out
33 // the same way. Writing a magic little endian reverses it on the wire, and a
34 // node reads the reversed bytes as an unknown network and drops the peer.
35 //
36 // # Untrusted input
37 //
38 // Decoders never panic: truncated, oversized, or otherwise invalid input is
39 // reported as an error. Truncation errors wrap io.ErrUnexpectedEOF, so
40 // callers can test for them with errors.Is. Compact size integers must be
41 // minimally encoded.
42 //
43 // Byte slices returned by DecodePayload (and by ReadVarBytes) alias the input
44 // buffer they were decoded from. Callers that keep such a slice after the
45 // payload buffer is reused must copy it.
46 package btcwire
47