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