protocol.h
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 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 SERIALIZE_METHODS(CMessageHeader, obj) { READWRITE(obj.pchMessageStart, obj.pchCommand, obj.nMessageSize, obj.pchChecksum); } 49 50 MessageStartChars pchMessageStart{}; 51 char pchCommand[COMMAND_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 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 // NODE_P2P_V2 means the node supports BIP324 transport 295 NODE_P2P_V2 = (1 << 11), 296 297 // Bits 24-31 are reserved for temporary experiments. Just pick a bit that 298 // isn't getting used, or one not being used much, and notify the 299 // bitcoin-development mailing list. Remember that service bits are just 300 // unauthenticated advertisements, so your code must be robust against 301 // collisions and other cases where nodes may be advertising a service they 302 // do not actually support. Other service bits should be allocated via the 303 // BIP process. 304 }; 305 306 /** 307 * Convert service flags (a bitmask of NODE_*) to human readable strings. 308 * It supports unknown service flags which will be returned as "UNKNOWN[...]". 309 * @param[in] flags multiple NODE_* bitwise-OR-ed together 310 */ 311 std::vector<std::string> serviceFlagsToStr(uint64_t flags); 312 313 /** 314 * State independent service flags. 315 * If the return value is changed, contrib/seeds/makeseeds.py 316 * should be updated appropriately to filter for nodes with 317 * desired service flags (compatible with our new flags). 318 */ 319 constexpr ServiceFlags SeedsServiceFlags() { return ServiceFlags(NODE_NETWORK | NODE_WITNESS); } 320 321 /** 322 * Checks if a peer with the given service flags may be capable of having a 323 * robust address-storage DB. 324 */ 325 static inline bool MayHaveUsefulAddressDB(ServiceFlags services) 326 { 327 return (services & NODE_NETWORK) || (services & NODE_NETWORK_LIMITED); 328 } 329 330 /** A CService with information about it as peer */ 331 class CAddress : public CService 332 { 333 static constexpr std::chrono::seconds TIME_INIT{100000000}; 334 335 /** Historically, CAddress disk serialization stored the CLIENT_VERSION, optionally OR'ed with 336 * the ADDRV2_FORMAT flag to indicate V2 serialization. The first field has since been 337 * disentangled from client versioning, and now instead: 338 * - The low bits (masked by DISK_VERSION_IGNORE_MASK) store the fixed value DISK_VERSION_INIT, 339 * (in case any code exists that treats it as a client version) but are ignored on 340 * deserialization. 341 * - The high bits (masked by ~DISK_VERSION_IGNORE_MASK) store actual serialization information. 342 * Only 0 or DISK_VERSION_ADDRV2 (equal to the historical ADDRV2_FORMAT) are valid now, and 343 * any other value triggers a deserialization failure. Other values can be added later if 344 * needed. 345 * 346 * For disk deserialization, ADDRV2_FORMAT in the stream version signals that ADDRV2 347 * deserialization is permitted, but the actual format is determined by the high bits in the 348 * stored version field. For network serialization, the stream version having ADDRV2_FORMAT or 349 * not determines the actual format used (as it has no embedded version number). 350 */ 351 static constexpr uint32_t DISK_VERSION_INIT{220000}; 352 static constexpr uint32_t DISK_VERSION_IGNORE_MASK{0b00000000'00000111'11111111'11111111}; 353 /** The version number written in disk serialized addresses to indicate V2 serializations. 354 * It must be exactly 1<<29, as that is the value that historical versions used for this 355 * (they used their internal ADDRV2_FORMAT flag here). */ 356 static constexpr uint32_t DISK_VERSION_ADDRV2{1 << 29}; 357 static_assert((DISK_VERSION_INIT & ~DISK_VERSION_IGNORE_MASK) == 0, "DISK_VERSION_INIT must be covered by DISK_VERSION_IGNORE_MASK"); 358 static_assert((DISK_VERSION_ADDRV2 & DISK_VERSION_IGNORE_MASK) == 0, "DISK_VERSION_ADDRV2 must not be covered by DISK_VERSION_IGNORE_MASK"); 359 360 public: 361 CAddress() : CService{} {}; 362 CAddress(CService ipIn, ServiceFlags nServicesIn) : CService{ipIn}, nServices{nServicesIn} {}; 363 CAddress(CService ipIn, ServiceFlags nServicesIn, NodeSeconds time) : CService{ipIn}, nTime{time}, nServices{nServicesIn} {}; 364 365 enum class Format { 366 Disk, 367 Network, 368 }; 369 struct SerParams : CNetAddr::SerParams { 370 const Format fmt; 371 SER_PARAMS_OPFUNC 372 }; 373 static constexpr SerParams V1_NETWORK{{CNetAddr::Encoding::V1}, Format::Network}; 374 static constexpr SerParams V2_NETWORK{{CNetAddr::Encoding::V2}, Format::Network}; 375 static constexpr SerParams V1_DISK{{CNetAddr::Encoding::V1}, Format::Disk}; 376 static constexpr SerParams V2_DISK{{CNetAddr::Encoding::V2}, Format::Disk}; 377 378 SERIALIZE_METHODS_PARAMS(CAddress, obj, SerParams, params) 379 { 380 bool use_v2; 381 if (params.fmt == Format::Disk) { 382 // In the disk serialization format, the encoding (v1 or v2) is determined by a flag version 383 // that's part of the serialization itself. ADDRV2_FORMAT in the stream version only determines 384 // whether V2 is chosen/permitted at all. 385 uint32_t stored_format_version = DISK_VERSION_INIT; 386 if (params.enc == Encoding::V2) stored_format_version |= DISK_VERSION_ADDRV2; 387 READWRITE(stored_format_version); 388 stored_format_version &= ~DISK_VERSION_IGNORE_MASK; // ignore low bits 389 if (stored_format_version == 0) { 390 use_v2 = false; 391 } else if (stored_format_version == DISK_VERSION_ADDRV2 && params.enc == Encoding::V2) { 392 // Only support v2 deserialization if V2 is set. 393 use_v2 = true; 394 } else { 395 throw std::ios_base::failure("Unsupported CAddress disk format version"); 396 } 397 } else { 398 assert(params.fmt == Format::Network); 399 // In the network serialization format, the encoding (v1 or v2) is determined directly by 400 // the value of enc in the stream params, as no explicitly encoded version 401 // exists in the stream. 402 use_v2 = params.enc == Encoding::V2; 403 } 404 405 READWRITE(Using<LossyChronoFormatter<uint32_t>>(obj.nTime)); 406 // nServices is serialized as CompactSize in V2; as uint64_t in V1. 407 if (use_v2) { 408 uint64_t services_tmp; 409 SER_WRITE(obj, services_tmp = obj.nServices); 410 READWRITE(Using<CompactSizeFormatter<false>>(services_tmp)); 411 SER_READ(obj, obj.nServices = static_cast<ServiceFlags>(services_tmp)); 412 } else { 413 READWRITE(Using<CustomUintFormatter<8>>(obj.nServices)); 414 } 415 // Invoke V1/V2 serializer for CService parent object. 416 const auto ser_params{use_v2 ? CNetAddr::V2 : CNetAddr::V1}; 417 READWRITE(ser_params(AsBase<CService>(obj))); 418 } 419 420 //! Always included in serialization. The behavior is unspecified if the value is not representable as uint32_t. 421 NodeSeconds nTime{TIME_INIT}; 422 //! Serialized as uint64_t in V1, and as CompactSize in V2. 423 ServiceFlags nServices{NODE_NONE}; 424 425 friend bool operator==(const CAddress& a, const CAddress& b) 426 { 427 return a.nTime == b.nTime && 428 a.nServices == b.nServices && 429 static_cast<const CService&>(a) == static_cast<const CService&>(b); 430 } 431 }; 432 433 /** getdata message type flags */ 434 const uint32_t MSG_WITNESS_FLAG = 1 << 30; 435 const uint32_t MSG_TYPE_MASK = 0xffffffff >> 2; 436 437 /** getdata / inv message types. 438 * These numbers are defined by the protocol. When adding a new value, be sure 439 * to mention it in the respective BIP. 440 */ 441 enum GetDataMsg : uint32_t { 442 UNDEFINED = 0, 443 MSG_TX = 1, 444 MSG_BLOCK = 2, 445 MSG_WTX = 5, //!< Defined in BIP 339 446 // The following can only occur in getdata. Invs always use TX/WTX or BLOCK. 447 MSG_FILTERED_BLOCK = 3, //!< Defined in BIP37 448 MSG_CMPCT_BLOCK = 4, //!< Defined in BIP152 449 MSG_WITNESS_BLOCK = MSG_BLOCK | MSG_WITNESS_FLAG, //!< Defined in BIP144 450 MSG_WITNESS_TX = MSG_TX | MSG_WITNESS_FLAG, //!< Defined in BIP144 451 // MSG_FILTERED_WITNESS_BLOCK is defined in BIP144 as reserved for future 452 // use and remains unused. 453 // MSG_FILTERED_WITNESS_BLOCK = MSG_FILTERED_BLOCK | MSG_WITNESS_FLAG, 454 }; 455 456 /** inv message data */ 457 class CInv 458 { 459 public: 460 CInv(); 461 CInv(uint32_t typeIn, const uint256& hashIn); 462 463 SERIALIZE_METHODS(CInv, obj) { READWRITE(obj.type, obj.hash); } 464 465 friend bool operator<(const CInv& a, const CInv& b); 466 467 std::string GetCommand() const; 468 std::string ToString() const; 469 470 // Single-message helper methods 471 bool IsMsgTx() const { return type == MSG_TX; } 472 bool IsMsgBlk() const { return type == MSG_BLOCK; } 473 bool IsMsgWtx() const { return type == MSG_WTX; } 474 bool IsMsgFilteredBlk() const { return type == MSG_FILTERED_BLOCK; } 475 bool IsMsgCmpctBlk() const { return type == MSG_CMPCT_BLOCK; } 476 bool IsMsgWitnessBlk() const { return type == MSG_WITNESS_BLOCK; } 477 478 // Combined-message helper methods 479 bool IsGenTxMsg() const 480 { 481 return type == MSG_TX || type == MSG_WTX || type == MSG_WITNESS_TX; 482 } 483 bool IsGenBlkMsg() const 484 { 485 return type == MSG_BLOCK || type == MSG_FILTERED_BLOCK || type == MSG_CMPCT_BLOCK || type == MSG_WITNESS_BLOCK; 486 } 487 488 uint32_t type; 489 uint256 hash; 490 }; 491 492 /** Convert a TX/WITNESS_TX/WTX CInv to a GenTxid. */ 493 GenTxid ToGenTxid(const CInv& inv); 494 495 #endif // BITCOIN_PROTOCOL_H