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