Line data Source code
1 : // Copyright (c) 2009-2010 Satoshi Nakamoto
2 : // Copyright (c) 2009-2022 The Bitcoin Core developers
3 : // Distributed under the MIT software license, see the accompanying
4 : // file COPYING or http://www.opensource.org/licenses/mit-license.php.
5 :
6 : #ifndef BITCOIN_PROTOCOL_H
7 : #define BITCOIN_PROTOCOL_H
8 :
9 : #include <kernel/messagestartchars.h> // IWYU pragma: export
10 : #include <netaddress.h>
11 : #include <primitives/transaction.h>
12 : #include <serialize.h>
13 : #include <streams.h>
14 : #include <uint256.h>
15 : #include <util/time.h>
16 :
17 : #include <array>
18 : #include <cstdint>
19 : #include <limits>
20 : #include <string>
21 :
22 : /** Message header.
23 : * (4) message start.
24 : * (12) command.
25 : * (4) size.
26 : * (4) checksum.
27 : */
28 : class CMessageHeader
29 : {
30 : public:
31 : static constexpr size_t COMMAND_SIZE = 12;
32 : static constexpr size_t MESSAGE_SIZE_SIZE = 4;
33 : static constexpr size_t CHECKSUM_SIZE = 4;
34 : static constexpr size_t MESSAGE_SIZE_OFFSET = std::tuple_size_v<MessageStartChars> + COMMAND_SIZE;
35 : static constexpr size_t CHECKSUM_OFFSET = MESSAGE_SIZE_OFFSET + MESSAGE_SIZE_SIZE;
36 : static constexpr size_t HEADER_SIZE = std::tuple_size_v<MessageStartChars> + COMMAND_SIZE + MESSAGE_SIZE_SIZE + CHECKSUM_SIZE;
37 :
38 0 : explicit CMessageHeader() = default;
39 :
40 : /** Construct a P2P message header from message-start characters, a command and the size of the message.
41 : * @note Passing in a `pszCommand` longer than COMMAND_SIZE will result in a run-time assertion error.
42 : */
43 : CMessageHeader(const MessageStartChars& pchMessageStartIn, const char* pszCommand, unsigned int nMessageSizeIn);
44 :
45 : std::string GetCommand() const;
46 : bool IsCommandValid() const;
47 :
48 0 : SERIALIZE_METHODS(CMessageHeader, obj) { READWRITE(obj.pchMessageStart, obj.pchCommand, obj.nMessageSize, obj.pchChecksum); }
49 :
50 0 : MessageStartChars pchMessageStart{};
51 0 : char pchCommand[COMMAND_SIZE]{};
52 0 : uint32_t nMessageSize{std::numeric_limits<uint32_t>::max()};
53 0 : uint8_t pchChecksum[CHECKSUM_SIZE]{};
54 : };
55 :
56 : /**
57 : * Bitcoin protocol message types. When adding new message types, don't forget
58 : * to update allNetMessageTypes in protocol.cpp.
59 : */
60 : namespace NetMsgType {
61 :
62 : /**
63 : * The version message provides information about the transmitting node to the
64 : * receiving node at the beginning of a connection.
65 : */
66 : extern const char* VERSION;
67 : /**
68 : * The verack message acknowledges a previously-received version message,
69 : * informing the connecting node that it can begin to send other messages.
70 : */
71 : extern const char* VERACK;
72 : /**
73 : * The addr (IP address) message relays connection information for peers on the
74 : * network.
75 : */
76 : extern const char* ADDR;
77 : /**
78 : * The addrv2 message relays connection information for peers on the network just
79 : * like the addr message, but is extended to allow gossiping of longer node
80 : * addresses (see BIP155).
81 : */
82 : extern const char *ADDRV2;
83 : /**
84 : * The sendaddrv2 message signals support for receiving ADDRV2 messages (BIP155).
85 : * It also implies that its sender can encode as ADDRV2 and would send ADDRV2
86 : * instead of ADDR to a peer that has signaled ADDRV2 support by sending SENDADDRV2.
87 : */
88 : extern const char *SENDADDRV2;
89 : /**
90 : * The inv message (inventory message) transmits one or more inventories of
91 : * objects known to the transmitting peer.
92 : */
93 : extern const char* INV;
94 : /**
95 : * The getdata message requests one or more data objects from another node.
96 : */
97 : extern const char* GETDATA;
98 : /**
99 : * The merkleblock message is a reply to a getdata message which requested a
100 : * block using the inventory type MSG_MERKLEBLOCK.
101 : * @since protocol version 70001 as described by BIP37.
102 : */
103 : extern const char* MERKLEBLOCK;
104 : /**
105 : * The getblocks message requests an inv message that provides block header
106 : * hashes starting from a particular point in the block chain.
107 : */
108 : extern const char* GETBLOCKS;
109 : /**
110 : * The getheaders message requests a headers message that provides block
111 : * headers starting from a particular point in the block chain.
112 : * @since protocol version 31800.
113 : */
114 : extern const char* GETHEADERS;
115 : /**
116 : * The tx message transmits a single transaction.
117 : */
118 : extern const char* TX;
119 : /**
120 : * The headers message sends one or more block headers to a node which
121 : * previously requested certain headers with a getheaders message.
122 : * @since protocol version 31800.
123 : */
124 : extern const char* HEADERS;
125 : /**
126 : * The block message transmits a single serialized block.
127 : */
128 : extern const char* BLOCK;
129 : /**
130 : * The getaddr message requests an addr message from the receiving node,
131 : * preferably one with lots of IP addresses of other receiving nodes.
132 : */
133 : extern const char* GETADDR;
134 : /**
135 : * The mempool message requests the TXIDs of transactions that the receiving
136 : * node has verified as valid but which have not yet appeared in a block.
137 : * @since protocol version 60002 as described by BIP35.
138 : * Only available with service bit NODE_BLOOM, see also BIP111.
139 : */
140 : extern const char* MEMPOOL;
141 : /**
142 : * The ping message is sent periodically to help confirm that the receiving
143 : * peer is still connected.
144 : */
145 : extern const char* PING;
146 : /**
147 : * The pong message replies to a ping message, proving to the pinging node that
148 : * the ponging node is still alive.
149 : * @since protocol version 60001 as described by BIP31.
150 : */
151 : extern const char* PONG;
152 : /**
153 : * The notfound message is a reply to a getdata message which requested an
154 : * object the receiving node does not have available for relay.
155 : * @since protocol version 70001.
156 : */
157 : extern const char* NOTFOUND;
158 : /**
159 : * The filterload message tells the receiving peer to filter all relayed
160 : * transactions and requested merkle blocks through the provided filter.
161 : * @since protocol version 70001 as described by BIP37.
162 : * Only available with service bit NODE_BLOOM since protocol version
163 : * 70011 as described by BIP111.
164 : */
165 : extern const char* FILTERLOAD;
166 : /**
167 : * The filteradd message tells the receiving peer to add a single element to a
168 : * previously-set bloom filter, such as a new public key.
169 : * @since protocol version 70001 as described by BIP37.
170 : * Only available with service bit NODE_BLOOM since protocol version
171 : * 70011 as described by BIP111.
172 : */
173 : extern const char* FILTERADD;
174 : /**
175 : * The filterclear message tells the receiving peer to remove a previously-set
176 : * bloom filter.
177 : * @since protocol version 70001 as described by BIP37.
178 : * Only available with service bit NODE_BLOOM since protocol version
179 : * 70011 as described by BIP111.
180 : */
181 : extern const char* FILTERCLEAR;
182 : /**
183 : * Indicates that a node prefers to receive new block announcements via a
184 : * "headers" message rather than an "inv".
185 : * @since protocol version 70012 as described by BIP130.
186 : */
187 : extern const char* SENDHEADERS;
188 : /**
189 : * The feefilter message tells the receiving peer not to inv us any txs
190 : * which do not meet the specified min fee rate.
191 : * @since protocol version 70013 as described by BIP133
192 : */
193 : extern const char* FEEFILTER;
194 : /**
195 : * Contains a 1-byte bool and 8-byte LE version number.
196 : * Indicates that a node is willing to provide blocks via "cmpctblock" messages.
197 : * May indicate that a node prefers to receive new block announcements via a
198 : * "cmpctblock" message rather than an "inv", depending on message contents.
199 : * @since protocol version 70014 as described by BIP 152
200 : */
201 : extern const char* SENDCMPCT;
202 : /**
203 : * Contains a CBlockHeaderAndShortTxIDs object - providing a header and
204 : * list of "short txids".
205 : * @since protocol version 70014 as described by BIP 152
206 : */
207 : extern const char* CMPCTBLOCK;
208 : /**
209 : * Contains a BlockTransactionsRequest
210 : * Peer should respond with "blocktxn" message.
211 : * @since protocol version 70014 as described by BIP 152
212 : */
213 : extern const char* GETBLOCKTXN;
214 : /**
215 : * Contains a BlockTransactions.
216 : * Sent in response to a "getblocktxn" message.
217 : * @since protocol version 70014 as described by BIP 152
218 : */
219 : extern const char* BLOCKTXN;
220 : /**
221 : * getcfilters requests compact filters for a range of blocks.
222 : * Only available with service bit NODE_COMPACT_FILTERS as described by
223 : * BIP 157 & 158.
224 : */
225 : extern const char* GETCFILTERS;
226 : /**
227 : * cfilter is a response to a getcfilters request containing a single compact
228 : * filter.
229 : */
230 : extern const char* CFILTER;
231 : /**
232 : * getcfheaders requests a compact filter header and the filter hashes for a
233 : * range of blocks, which can then be used to reconstruct the filter headers
234 : * for those blocks.
235 : * Only available with service bit NODE_COMPACT_FILTERS as described by
236 : * BIP 157 & 158.
237 : */
238 : extern const char* GETCFHEADERS;
239 : /**
240 : * cfheaders is a response to a getcfheaders request containing a filter header
241 : * and a vector of filter hashes for each subsequent block in the requested range.
242 : */
243 : extern const char* CFHEADERS;
244 : /**
245 : * getcfcheckpt requests evenly spaced compact filter headers, enabling
246 : * parallelized download and validation of the headers between them.
247 : * Only available with service bit NODE_COMPACT_FILTERS as described by
248 : * BIP 157 & 158.
249 : */
250 : extern const char* GETCFCHECKPT;
251 : /**
252 : * cfcheckpt is a response to a getcfcheckpt request containing a vector of
253 : * evenly spaced filter headers for blocks on the requested chain.
254 : */
255 : extern const char* CFCHECKPT;
256 : /**
257 : * Indicates that a node prefers to relay transactions via wtxid, rather than
258 : * txid.
259 : * @since protocol version 70016 as described by BIP 339.
260 : */
261 : extern const char* WTXIDRELAY;
262 : /**
263 : * Contains a 4-byte version number and an 8-byte salt.
264 : * The salt is used to compute short txids needed for efficient
265 : * txreconciliation, as described by BIP 330.
266 : */
267 : extern const char* SENDTXRCNCL;
268 : }; // namespace NetMsgType
269 :
270 : /* Get a vector of all valid message types (see above) */
271 : const std::vector<std::string>& getAllNetMessageTypes();
272 :
273 : /** nServices flags */
274 : enum ServiceFlags : uint64_t {
275 : // NOTE: When adding here, be sure to update serviceFlagToStr too
276 : // Nothing
277 : NODE_NONE = 0,
278 : // NODE_NETWORK means that the node is capable of serving the complete block chain. It is currently
279 : // set by all Bitcoin Core non pruned nodes, and is unset by SPV clients or other light clients.
280 : NODE_NETWORK = (1 << 0),
281 : // NODE_BLOOM means the node is capable and willing to handle bloom-filtered connections.
282 : NODE_BLOOM = (1 << 2),
283 : // NODE_WITNESS indicates that a node can be asked for blocks and transactions including
284 : // witness data.
285 : NODE_WITNESS = (1 << 3),
286 : // NODE_COMPACT_FILTERS means the node will service basic block filter requests.
287 : // See BIP157 and BIP158 for details on how this is implemented.
288 : NODE_COMPACT_FILTERS = (1 << 6),
289 : // NODE_NETWORK_LIMITED means the same as NODE_NETWORK with the limitation of only
290 : // serving the last 288 (2 day) blocks
291 : // See BIP159 for details on how this is implemented.
292 : NODE_NETWORK_LIMITED = (1 << 10),
293 :
294 : // Bits 24-31 are reserved for temporary experiments. Just pick a bit that
295 : // isn't getting used, or one not being used much, and notify the
296 : // bitcoin-development mailing list. Remember that service bits are just
297 : // unauthenticated advertisements, so your code must be robust against
298 : // collisions and other cases where nodes may be advertising a service they
299 : // do not actually support. Other service bits should be allocated via the
300 : // BIP process.
301 : };
302 :
303 : /**
304 : * Convert service flags (a bitmask of NODE_*) to human readable strings.
305 : * It supports unknown service flags which will be returned as "UNKNOWN[...]".
306 : * @param[in] flags multiple NODE_* bitwise-OR-ed together
307 : */
308 : std::vector<std::string> serviceFlagsToStr(uint64_t flags);
309 :
310 : /**
311 : * Gets the set of service flags which are "desirable" for a given peer.
312 : *
313 : * These are the flags which are required for a peer to support for them
314 : * to be "interesting" to us, ie for us to wish to use one of our few
315 : * outbound connection slots for or for us to wish to prioritize keeping
316 : * their connection around.
317 : *
318 : * Relevant service flags may be peer- and state-specific in that the
319 : * version of the peer may determine which flags are required (eg in the
320 : * case of NODE_NETWORK_LIMITED where we seek out NODE_NETWORK peers
321 : * unless they set NODE_NETWORK_LIMITED and we are out of IBD, in which
322 : * case NODE_NETWORK_LIMITED suffices).
323 : *
324 : * Thus, generally, avoid calling with peerServices == NODE_NONE, unless
325 : * state-specific flags must absolutely be avoided. When called with
326 : * peerServices == NODE_NONE, the returned desirable service flags are
327 : * guaranteed to not change dependent on state - ie they are suitable for
328 : * use when describing peers which we know to be desirable, but for which
329 : * we do not have a confirmed set of service flags.
330 : *
331 : * If the NODE_NONE return value is changed, contrib/seeds/makeseeds.py
332 : * should be updated appropriately to filter for the same nodes.
333 : */
334 : ServiceFlags GetDesirableServiceFlags(ServiceFlags services);
335 :
336 : /** Set the current IBD status in order to figure out the desirable service flags */
337 : void SetServiceFlagsIBDCache(bool status);
338 :
339 : /**
340 : * A shortcut for (services & GetDesirableServiceFlags(services))
341 : * == GetDesirableServiceFlags(services), ie determines whether the given
342 : * set of service flags are sufficient for a peer to be "relevant".
343 : */
344 0 : static inline bool HasAllDesirableServiceFlags(ServiceFlags services)
345 : {
346 0 : return !(GetDesirableServiceFlags(services) & (~services));
347 : }
348 :
349 : /**
350 : * Checks if a peer with the given service flags may be capable of having a
351 : * robust address-storage DB.
352 : */
353 0 : static inline bool MayHaveUsefulAddressDB(ServiceFlags services)
354 : {
355 0 : return (services & NODE_NETWORK) || (services & NODE_NETWORK_LIMITED);
356 : }
357 :
358 : /** A CService with information about it as peer */
359 : class CAddress : public CService
360 : {
361 : static constexpr std::chrono::seconds TIME_INIT{100000000};
362 :
363 : /** Historically, CAddress disk serialization stored the CLIENT_VERSION, optionally OR'ed with
364 : * the ADDRV2_FORMAT flag to indicate V2 serialization. The first field has since been
365 : * disentangled from client versioning, and now instead:
366 : * - The low bits (masked by DISK_VERSION_IGNORE_MASK) store the fixed value DISK_VERSION_INIT,
367 : * (in case any code exists that treats it as a client version) but are ignored on
368 : * deserialization.
369 : * - The high bits (masked by ~DISK_VERSION_IGNORE_MASK) store actual serialization information.
370 : * Only 0 or DISK_VERSION_ADDRV2 (equal to the historical ADDRV2_FORMAT) are valid now, and
371 : * any other value triggers a deserialization failure. Other values can be added later if
372 : * needed.
373 : *
374 : * For disk deserialization, ADDRV2_FORMAT in the stream version signals that ADDRV2
375 : * deserialization is permitted, but the actual format is determined by the high bits in the
376 : * stored version field. For network serialization, the stream version having ADDRV2_FORMAT or
377 : * not determines the actual format used (as it has no embedded version number).
378 : */
379 : static constexpr uint32_t DISK_VERSION_INIT{220000};
380 : static constexpr uint32_t DISK_VERSION_IGNORE_MASK{0b00000000'00000111'11111111'11111111};
381 : /** The version number written in disk serialized addresses to indicate V2 serializations.
382 : * It must be exactly 1<<29, as that is the value that historical versions used for this
383 : * (they used their internal ADDRV2_FORMAT flag here). */
384 : static constexpr uint32_t DISK_VERSION_ADDRV2{1 << 29};
385 : static_assert((DISK_VERSION_INIT & ~DISK_VERSION_IGNORE_MASK) == 0, "DISK_VERSION_INIT must be covered by DISK_VERSION_IGNORE_MASK");
386 : static_assert((DISK_VERSION_ADDRV2 & DISK_VERSION_IGNORE_MASK) == 0, "DISK_VERSION_ADDRV2 must not be covered by DISK_VERSION_IGNORE_MASK");
387 :
388 : public:
389 0 : CAddress() : CService{} {};
390 0 : CAddress(CService ipIn, ServiceFlags nServicesIn) : CService{ipIn}, nServices{nServicesIn} {};
391 0 : CAddress(CService ipIn, ServiceFlags nServicesIn, NodeSeconds time) : CService{ipIn}, nTime{time}, nServices{nServicesIn} {};
392 :
393 : enum class Format {
394 : Disk,
395 : Network,
396 : };
397 : struct SerParams : CNetAddr::SerParams {
398 : const Format fmt;
399 0 : SER_PARAMS_OPFUNC
400 : };
401 : static constexpr SerParams V1_NETWORK{{CNetAddr::Encoding::V1}, Format::Network};
402 : static constexpr SerParams V2_NETWORK{{CNetAddr::Encoding::V2}, Format::Network};
403 : static constexpr SerParams V1_DISK{{CNetAddr::Encoding::V1}, Format::Disk};
404 : static constexpr SerParams V2_DISK{{CNetAddr::Encoding::V2}, Format::Disk};
405 :
406 0 : SERIALIZE_METHODS_PARAMS(CAddress, obj, SerParams, params)
407 : {
408 : bool use_v2;
409 0 : if (params.fmt == Format::Disk) {
410 : // In the disk serialization format, the encoding (v1 or v2) is determined by a flag version
411 : // that's part of the serialization itself. ADDRV2_FORMAT in the stream version only determines
412 : // whether V2 is chosen/permitted at all.
413 0 : uint32_t stored_format_version = DISK_VERSION_INIT;
414 0 : if (params.enc == Encoding::V2) stored_format_version |= DISK_VERSION_ADDRV2;
415 0 : READWRITE(stored_format_version);
416 0 : stored_format_version &= ~DISK_VERSION_IGNORE_MASK; // ignore low bits
417 0 : if (stored_format_version == 0) {
418 0 : use_v2 = false;
419 0 : } else if (stored_format_version == DISK_VERSION_ADDRV2 && params.enc == Encoding::V2) {
420 : // Only support v2 deserialization if V2 is set.
421 0 : use_v2 = true;
422 0 : } else {
423 0 : throw std::ios_base::failure("Unsupported CAddress disk format version");
424 : }
425 0 : } else {
426 0 : assert(params.fmt == Format::Network);
427 : // In the network serialization format, the encoding (v1 or v2) is determined directly by
428 : // the value of enc in the stream params, as no explicitly encoded version
429 : // exists in the stream.
430 0 : use_v2 = params.enc == Encoding::V2;
431 : }
432 :
433 0 : READWRITE(Using<LossyChronoFormatter<uint32_t>>(obj.nTime));
434 : // nServices is serialized as CompactSize in V2; as uint64_t in V1.
435 0 : if (use_v2) {
436 : uint64_t services_tmp;
437 0 : SER_WRITE(obj, services_tmp = obj.nServices);
438 0 : READWRITE(Using<CompactSizeFormatter<false>>(services_tmp));
439 0 : SER_READ(obj, obj.nServices = static_cast<ServiceFlags>(services_tmp));
440 0 : } else {
441 0 : READWRITE(Using<CustomUintFormatter<8>>(obj.nServices));
442 : }
443 : // Invoke V1/V2 serializer for CService parent object.
444 0 : const auto ser_params{use_v2 ? CNetAddr::V2 : CNetAddr::V1};
445 0 : READWRITE(WithParams(ser_params, AsBase<CService>(obj)));
446 0 : }
447 :
448 : //! Always included in serialization. The behavior is unspecified if the value is not representable as uint32_t.
449 0 : NodeSeconds nTime{TIME_INIT};
450 : //! Serialized as uint64_t in V1, and as CompactSize in V2.
451 0 : ServiceFlags nServices{NODE_NONE};
452 :
453 0 : friend bool operator==(const CAddress& a, const CAddress& b)
454 : {
455 0 : return a.nTime == b.nTime &&
456 0 : a.nServices == b.nServices &&
457 0 : static_cast<const CService&>(a) == static_cast<const CService&>(b);
458 : }
459 : };
460 :
461 : /** getdata message type flags */
462 : const uint32_t MSG_WITNESS_FLAG = 1 << 30;
463 : const uint32_t MSG_TYPE_MASK = 0xffffffff >> 2;
464 :
465 : /** getdata / inv message types.
466 : * These numbers are defined by the protocol. When adding a new value, be sure
467 : * to mention it in the respective BIP.
468 : */
469 : enum GetDataMsg : uint32_t {
470 : UNDEFINED = 0,
471 : MSG_TX = 1,
472 : MSG_BLOCK = 2,
473 : MSG_WTX = 5, //!< Defined in BIP 339
474 : // The following can only occur in getdata. Invs always use TX/WTX or BLOCK.
475 : MSG_FILTERED_BLOCK = 3, //!< Defined in BIP37
476 : MSG_CMPCT_BLOCK = 4, //!< Defined in BIP152
477 : MSG_WITNESS_BLOCK = MSG_BLOCK | MSG_WITNESS_FLAG, //!< Defined in BIP144
478 : MSG_WITNESS_TX = MSG_TX | MSG_WITNESS_FLAG, //!< Defined in BIP144
479 : // MSG_FILTERED_WITNESS_BLOCK is defined in BIP144 as reserved for future
480 : // use and remains unused.
481 : // MSG_FILTERED_WITNESS_BLOCK = MSG_FILTERED_BLOCK | MSG_WITNESS_FLAG,
482 : };
483 :
484 : /** inv message data */
485 : class CInv
486 : {
487 : public:
488 : CInv();
489 : CInv(uint32_t typeIn, const uint256& hashIn);
490 :
491 0 : SERIALIZE_METHODS(CInv, obj) { READWRITE(obj.type, obj.hash); }
492 :
493 : friend bool operator<(const CInv& a, const CInv& b);
494 :
495 : std::string GetCommand() const;
496 : std::string ToString() const;
497 :
498 : // Single-message helper methods
499 0 : bool IsMsgTx() const { return type == MSG_TX; }
500 0 : bool IsMsgBlk() const { return type == MSG_BLOCK; }
501 0 : bool IsMsgWtx() const { return type == MSG_WTX; }
502 0 : bool IsMsgFilteredBlk() const { return type == MSG_FILTERED_BLOCK; }
503 0 : bool IsMsgCmpctBlk() const { return type == MSG_CMPCT_BLOCK; }
504 0 : bool IsMsgWitnessBlk() const { return type == MSG_WITNESS_BLOCK; }
505 :
506 : // Combined-message helper methods
507 0 : bool IsGenTxMsg() const
508 : {
509 0 : return type == MSG_TX || type == MSG_WTX || type == MSG_WITNESS_TX;
510 : }
511 0 : bool IsGenBlkMsg() const
512 : {
513 0 : return type == MSG_BLOCK || type == MSG_FILTERED_BLOCK || type == MSG_CMPCT_BLOCK || type == MSG_WITNESS_BLOCK;
514 : }
515 :
516 : uint32_t type;
517 : uint256 hash;
518 : };
519 :
520 : /** Convert a TX/WITNESS_TX/WTX CInv to a GenTxid. */
521 : GenTxid ToGenTxid(const CInv& inv);
522 :
523 : #endif // BITCOIN_PROTOCOL_H
|
