Bitcoin Core  21.99.0
P2P Digital Currency
protocol.h
Go to the documentation of this file.
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 <uint256.h>
17 #include <version.h>
18 
19 #include <stdint.h>
20 #include <string>
21 
29 {
30 public:
31  static constexpr size_t MESSAGE_START_SIZE = 4;
32  static constexpr size_t COMMAND_SIZE = 12;
33  static constexpr size_t MESSAGE_SIZE_SIZE = 4;
34  static constexpr size_t CHECKSUM_SIZE = 4;
38  typedef unsigned char MessageStartChars[MESSAGE_START_SIZE];
39 
40  explicit CMessageHeader();
41 
45  CMessageHeader(const MessageStartChars& pchMessageStartIn, const char* pszCommand, unsigned int nMessageSizeIn);
46 
47  std::string GetCommand() const;
48  bool IsCommandValid() const;
49 
50  SERIALIZE_METHODS(CMessageHeader, obj) { READWRITE(obj.pchMessageStart, obj.pchCommand, obj.nMessageSize, obj.pchChecksum); }
51 
54  uint32_t nMessageSize;
56 };
57 
62 namespace NetMsgType {
63 
68 extern const char* VERSION;
73 extern const char* VERACK;
78 extern const char* ADDR;
84 extern const char *ADDRV2;
90 extern const char *SENDADDRV2;
95 extern const char* INV;
99 extern const char* GETDATA;
105 extern const char* MERKLEBLOCK;
110 extern const char* GETBLOCKS;
116 extern const char* GETHEADERS;
120 extern const char* TX;
126 extern const char* HEADERS;
130 extern const char* BLOCK;
135 extern const char* GETADDR;
141 extern const char* MEMPOOL;
146 extern const char* PING;
152 extern const char* PONG;
158 extern const char* NOTFOUND;
166 extern const char* FILTERLOAD;
174 extern const char* FILTERADD;
182 extern const char* FILTERCLEAR;
188 extern const char* SENDHEADERS;
194 extern const char* FEEFILTER;
202 extern const char* SENDCMPCT;
208 extern const char* CMPCTBLOCK;
214 extern const char* GETBLOCKTXN;
220 extern const char* BLOCKTXN;
226 extern const char* GETCFILTERS;
231 extern const char* CFILTER;
239 extern const char* GETCFHEADERS;
244 extern const char* CFHEADERS;
251 extern const char* GETCFCHECKPT;
256 extern const char* CFCHECKPT;
262 extern const char* WTXIDRELAY;
263 }; // namespace NetMsgType
264 
265 /* Get a vector of all valid message types (see above) */
266 const std::vector<std::string>& getAllNetMessageTypes();
267 
269 enum ServiceFlags : uint64_t {
270  // NOTE: When adding here, be sure to update serviceFlagToStr too
271  // Nothing
273  // NODE_NETWORK means that the node is capable of serving the complete block chain. It is currently
274  // set by all Bitcoin Core non pruned nodes, and is unset by SPV clients or other light clients.
275  NODE_NETWORK = (1 << 0),
276  // NODE_BLOOM means the node is capable and willing to handle bloom-filtered connections.
277  // Bitcoin Core nodes used to support this by default, without advertising this bit,
278  // but no longer do as of protocol version 70011 (= NO_BLOOM_VERSION)
279  NODE_BLOOM = (1 << 2),
280  // NODE_WITNESS indicates that a node can be asked for blocks and transactions including
281  // witness data.
282  NODE_WITNESS = (1 << 3),
283  // NODE_COMPACT_FILTERS means the node will service basic block filter requests.
284  // See BIP157 and BIP158 for details on how this is implemented.
286  // NODE_NETWORK_LIMITED means the same as NODE_NETWORK with the limitation of only
287  // serving the last 288 (2 day) blocks
288  // See BIP159 for details on how this is implemented.
289  NODE_NETWORK_LIMITED = (1 << 10),
290 
291  // Bits 24-31 are reserved for temporary experiments. Just pick a bit that
292  // isn't getting used, or one not being used much, and notify the
293  // bitcoin-development mailing list. Remember that service bits are just
294  // unauthenticated advertisements, so your code must be robust against
295  // collisions and other cases where nodes may be advertising a service they
296  // do not actually support. Other service bits should be allocated via the
297  // BIP process.
298 };
299 
305 std::vector<std::string> serviceFlagsToStr(uint64_t flags);
306 
332 
334 void SetServiceFlagsIBDCache(bool status);
335 
341 static inline bool HasAllDesirableServiceFlags(ServiceFlags services)
342 {
343  return !(GetDesirableServiceFlags(services) & (~services));
344 }
345 
350 static inline bool MayHaveUsefulAddressDB(ServiceFlags services)
351 {
352  return (services & NODE_NETWORK) || (services & NODE_NETWORK_LIMITED);
353 }
354 
356 class CAddress : public CService
357 {
358  static constexpr uint32_t TIME_INIT{100000000};
359 
360 public:
361  CAddress() : CService{} {};
362  CAddress(CService ipIn, ServiceFlags nServicesIn) : CService{ipIn}, nServices{nServicesIn} {};
363  CAddress(CService ipIn, ServiceFlags nServicesIn, uint32_t nTimeIn) : CService{ipIn}, nTime{nTimeIn}, nServices{nServicesIn} {};
364 
366  {
367  SER_READ(obj, obj.nTime = TIME_INIT);
368  int nVersion = s.GetVersion();
369  if (s.GetType() & SER_DISK) {
370  READWRITE(nVersion);
371  }
372  if ((s.GetType() & SER_DISK) ||
373  (nVersion != INIT_PROTO_VERSION && !(s.GetType() & SER_GETHASH))) {
374  // The only time we serialize a CAddress object without nTime is in
375  // the initial VERSION messages which contain two CAddress records.
376  // At that point, the serialization version is INIT_PROTO_VERSION.
377  // After the version handshake, serialization version is >=
378  // MIN_PEER_PROTO_VERSION and all ADDR messages are serialized with
379  // nTime.
380  READWRITE(obj.nTime);
381  }
382  if (nVersion & ADDRV2_FORMAT) {
383  uint64_t services_tmp;
384  SER_WRITE(obj, services_tmp = obj.nServices);
386  SER_READ(obj, obj.nServices = static_cast<ServiceFlags>(services_tmp));
387  } else {
388  READWRITE(Using<CustomUintFormatter<8>>(obj.nServices));
389  }
390  READWRITEAS(CService, obj);
391  }
392 
393  // disk and network only
394  uint32_t nTime{TIME_INIT};
395 
397 };
398 
400 const uint32_t MSG_WITNESS_FLAG = 1 << 30;
401 const uint32_t MSG_TYPE_MASK = 0xffffffff >> 2;
402 
407 enum GetDataMsg : uint32_t {
409  MSG_TX = 1,
411  MSG_WTX = 5,
412  // The following can only occur in getdata. Invs always use TX/WTX or BLOCK.
417  // MSG_FILTERED_WITNESS_BLOCK is defined in BIP144 as reserved for future
418  // use and remains unused.
419  // MSG_FILTERED_WITNESS_BLOCK = MSG_FILTERED_BLOCK | MSG_WITNESS_FLAG,
420 };
421 
423 class CInv
424 {
425 public:
426  CInv();
427  CInv(uint32_t typeIn, const uint256& hashIn);
428 
429  SERIALIZE_METHODS(CInv, obj) { READWRITE(obj.type, obj.hash); }
430 
431  friend bool operator<(const CInv& a, const CInv& b);
432 
433  std::string GetCommand() const;
434  std::string ToString() const;
435 
436  // Single-message helper methods
437  bool IsMsgTx() const { return type == MSG_TX; }
438  bool IsMsgBlk() const { return type == MSG_BLOCK; }
439  bool IsMsgWtx() const { return type == MSG_WTX; }
440  bool IsMsgFilteredBlk() const { return type == MSG_FILTERED_BLOCK; }
441  bool IsMsgCmpctBlk() const { return type == MSG_CMPCT_BLOCK; }
442  bool IsMsgWitnessBlk() const { return type == MSG_WITNESS_BLOCK; }
443 
444  // Combined-message helper methods
445  bool IsGenTxMsg() const
446  {
447  return type == MSG_TX || type == MSG_WTX || type == MSG_WITNESS_TX;
448  }
449  bool IsGenBlkMsg() const
450  {
452  }
453 
454  uint32_t type;
456 };
457 
459 GenTxid ToGenTxid(const CInv& inv);
460 
461 #endif // BITCOIN_PROTOCOL_H
ADDRV2_FORMAT
static constexpr int ADDRV2_FORMAT
A flag that is ORed into the protocol version to designate that addresses should be serialized in (un...
Definition: netaddress.h:32
CMessageHeader::pchCommand
char pchCommand[COMMAND_SIZE]
Definition: protocol.h:53
CService
A combination of a network address (CNetAddr) and a (TCP) port.
Definition: netaddress.h:551
MSG_BLOCK
@ MSG_BLOCK
Definition: protocol.h:410
CMessageHeader::CHECKSUM_OFFSET
static constexpr size_t CHECKSUM_OFFSET
Definition: protocol.h:36
CInv::IsMsgWitnessBlk
bool IsMsgWitnessBlk() const
Definition: protocol.h:442
NetMsgType
Bitcoin protocol message types.
Definition: protocol.cpp:12
SER_DISK
@ SER_DISK
Definition: serialize.h:167
CAddress::TIME_INIT
static constexpr uint32_t TIME_INIT
Definition: protocol.h:358
GenTxid
A generic txid reference (txid or wtxid).
Definition: transaction.h:390
CMessageHeader::nMessageSize
uint32_t nMessageSize
Definition: protocol.h:54
flags
int flags
Definition: bitcoin-tx.cpp:512
transaction.h
MSG_FILTERED_BLOCK
@ MSG_FILTERED_BLOCK
Defined in BIP37.
Definition: protocol.h:413
MSG_CMPCT_BLOCK
@ MSG_CMPCT_BLOCK
Defined in BIP152.
Definition: protocol.h:414
uint256.h
CAddress::CAddress
CAddress()
Definition: protocol.h:361
NetMsgType::PING
const char * PING
The ping message is sent periodically to help confirm that the receiving peer is still connected.
Definition: protocol.cpp:28
NetMsgType::FILTERLOAD
const char * FILTERLOAD
The filterload message tells the receiving peer to filter all relayed transactions and requested merk...
Definition: protocol.cpp:31
GetDesirableServiceFlags
ServiceFlags GetDesirableServiceFlags(ServiceFlags services)
Gets the set of service flags which are "desirable" for a given peer.
Definition: protocol.cpp:137
NetMsgType::SENDADDRV2
const char * SENDADDRV2
The sendaddrv2 message signals support for receiving ADDRV2 messages (BIP155).
Definition: protocol.cpp:17
CAddress::CAddress
CAddress(CService ipIn, ServiceFlags nServicesIn)
Definition: protocol.h:362
ServiceFlags
ServiceFlags
nServices flags
Definition: protocol.h:269
CMessageHeader::GetCommand
std::string GetCommand() const
Definition: protocol.cpp:112
CAddress::nServices
ServiceFlags nServices
Definition: protocol.h:396
NODE_NETWORK_LIMITED
@ NODE_NETWORK_LIMITED
Definition: protocol.h:289
CMessageHeader::MESSAGE_SIZE_SIZE
static constexpr size_t MESSAGE_SIZE_SIZE
Definition: protocol.h:33
NODE_NETWORK
@ NODE_NETWORK
Definition: protocol.h:275
NetMsgType::CFHEADERS
const char * CFHEADERS
cfheaders is a response to a getcfheaders request containing a filter header and a vector of filter h...
Definition: protocol.cpp:43
SetServiceFlagsIBDCache
void SetServiceFlagsIBDCache(bool status)
Set the current IBD status in order to figure out the desirable service flags.
Definition: protocol.cpp:144
CInv
inv message data
Definition: protocol.h:423
CustomUintFormatter
Serialization wrapper class for custom integers and enums.
Definition: serialize.h:508
NetMsgType::PONG
const char * PONG
The pong message replies to a ping message, proving to the pinging node that the ponging node is stil...
Definition: protocol.cpp:29
READWRITEAS
#define READWRITEAS(type, obj)
Definition: serialize.h:176
NODE_COMPACT_FILTERS
@ NODE_COMPACT_FILTERS
Definition: protocol.h:285
CAddress::nTime
uint32_t nTime
Definition: protocol.h:394
version.h
MayHaveUsefulAddressDB
static bool MayHaveUsefulAddressDB(ServiceFlags services)
Checks if a peer with the given service flags may be capable of having a robust address-storage DB.
Definition: protocol.h:350
HasAllDesirableServiceFlags
static bool HasAllDesirableServiceFlags(ServiceFlags services)
A shortcut for (services & GetDesirableServiceFlags(services)) == GetDesirableServiceFlags(services),...
Definition: protocol.h:341
NetMsgType::SENDCMPCT
const char * SENDCMPCT
Contains a 1-byte bool and 8-byte LE version number.
Definition: protocol.cpp:36
CInv::IsGenTxMsg
bool IsGenTxMsg() const
Definition: protocol.h:445
NetMsgType::ADDRV2
const char * ADDRV2
The addrv2 message relays connection information for peers on the network just like the addr message,...
Definition: protocol.cpp:16
MSG_TX
@ MSG_TX
Definition: protocol.h:409
CAddress::CAddress
CAddress(CService ipIn, ServiceFlags nServicesIn, uint32_t nTimeIn)
Definition: protocol.h:363
NetMsgType::INV
const char * INV
The inv message (inventory message) transmits one or more inventories of objects known to the transmi...
Definition: protocol.cpp:18
NetMsgType::GETHEADERS
const char * GETHEADERS
The getheaders message requests a headers message that provides block headers starting from a particu...
Definition: protocol.cpp:22
NetMsgType::CFILTER
const char * CFILTER
cfilter is a response to a getcfilters request containing a single compact filter.
Definition: protocol.cpp:41
MSG_WITNESS_TX
@ MSG_WITNESS_TX
Defined in BIP144.
Definition: protocol.h:416
NetMsgType::FEEFILTER
const char * FEEFILTER
The feefilter message tells the receiving peer not to inv us any txs which do not meet the specified ...
Definition: protocol.cpp:35
NetMsgType::HEADERS
const char * HEADERS
The headers message sends one or more block headers to a node which previously requested certain head...
Definition: protocol.cpp:24
netaddress.h
NetMsgType::GETCFCHECKPT
const char * GETCFCHECKPT
getcfcheckpt requests evenly spaced compact filter headers, enabling parallelized download and valida...
Definition: protocol.cpp:44
CMessageHeader::MESSAGE_SIZE_OFFSET
static constexpr size_t MESSAGE_SIZE_OFFSET
Definition: protocol.h:35
CInv::operator<
friend bool operator<(const CInv &a, const CInv &b)
Definition: protocol.cpp:156
NetMsgType::WTXIDRELAY
const char * WTXIDRELAY
Indicates that a node prefers to relay transactions via wtxid, rather than txid.
Definition: protocol.cpp:46
CMessageHeader::COMMAND_SIZE
static constexpr size_t COMMAND_SIZE
Definition: protocol.h:32
CMessageHeader::IsCommandValid
bool IsCommandValid() const
Definition: protocol.cpp:117
NODE_BLOOM
@ NODE_BLOOM
Definition: protocol.h:279
NetMsgType::GETCFHEADERS
const char * GETCFHEADERS
getcfheaders requests a compact filter header and the filter hashes for a range of blocks,...
Definition: protocol.cpp:42
CompactSizeFormatter
Formatter for integers in CompactSize format.
Definition: serialize.h:544
CInv::IsMsgTx
bool IsMsgTx() const
Definition: protocol.h:437
NetMsgType::FILTERCLEAR
const char * FILTERCLEAR
The filterclear message tells the receiving peer to remove a previously-set bloom filter.
Definition: protocol.cpp:33
uint256
256-bit opaque blob.
Definition: uint256.h:124
READWRITE
#define READWRITE(...)
Definition: serialize.h:175
CInv::SERIALIZE_METHODS
SERIALIZE_METHODS(CInv, obj)
Definition: protocol.h:429
NetMsgType::SENDHEADERS
const char * SENDHEADERS
Indicates that a node prefers to receive new block announcements via a "headers" message rather than ...
Definition: protocol.cpp:34
CMessageHeader::MESSAGE_START_SIZE
static constexpr size_t MESSAGE_START_SIZE
Definition: protocol.h:31
CAddress::SERIALIZE_METHODS
SERIALIZE_METHODS(CAddress, obj)
Definition: protocol.h:365
NetMsgType::GETBLOCKS
const char * GETBLOCKS
The getblocks message requests an inv message that provides block header hashes starting from a parti...
Definition: protocol.cpp:21
CMessageHeader::CMessageHeader
CMessageHeader()
Definition: protocol.cpp:90
NetMsgType::GETDATA
const char * GETDATA
The getdata message requests one or more data objects from another node.
Definition: protocol.cpp:19
CInv::IsMsgFilteredBlk
bool IsMsgFilteredBlk() const
Definition: protocol.h:440
CInv::GetCommand
std::string GetCommand() const
Definition: protocol.cpp:161
NetMsgType::NOTFOUND
const char * NOTFOUND
The notfound message is a reply to a getdata message which requested an object the receiving node doe...
Definition: protocol.cpp:30
NODE_NONE
@ NODE_NONE
Definition: protocol.h:272
CMessageHeader::CHECKSUM_SIZE
static constexpr size_t CHECKSUM_SIZE
Definition: protocol.h:34
NetMsgType::ADDR
const char * ADDR
The addr (IP address) message relays connection information for peers on the network.
Definition: protocol.cpp:15
NetMsgType::BLOCK
const char * BLOCK
The block message transmits a single serialized block.
Definition: protocol.cpp:25
NODE_WITNESS
@ NODE_WITNESS
Definition: protocol.h:282
NetMsgType::MEMPOOL
const char * MEMPOOL
The mempool message requests the TXIDs of transactions that the receiving node has verified as valid ...
Definition: protocol.cpp:27
CInv::CInv
CInv()
Definition: protocol.cpp:148
CAddress
A CService with information about it as peer.
Definition: protocol.h:356
CInv::IsMsgCmpctBlk
bool IsMsgCmpctBlk() const
Definition: protocol.h:441
CMessageHeader
Message header.
Definition: protocol.h:28
NetMsgType::TX
const char * TX
The tx message transmits a single transaction.
Definition: protocol.cpp:23
CInv::hash
uint256 hash
Definition: protocol.h:455
getAllNetMessageTypes
const std::vector< std::string > & getAllNetMessageTypes()
Definition: protocol.cpp:189
MSG_WTX
@ MSG_WTX
Defined in BIP 339.
Definition: protocol.h:411
NetMsgType::CMPCTBLOCK
const char * CMPCTBLOCK
Contains a CBlockHeaderAndShortTxIDs object - providing a header and list of "short txids".
Definition: protocol.cpp:37
CMessageHeader::SERIALIZE_METHODS
SERIALIZE_METHODS(CMessageHeader, obj)
Definition: protocol.h:50
MSG_TYPE_MASK
const uint32_t MSG_TYPE_MASK
Definition: protocol.h:401
CMessageHeader::MessageStartChars
unsigned char MessageStartChars[MESSAGE_START_SIZE]
Definition: protocol.h:38
CMessageHeader::pchMessageStart
char pchMessageStart[MESSAGE_START_SIZE]
Definition: protocol.h:52
CMessageHeader::HEADER_SIZE
static constexpr size_t HEADER_SIZE
Definition: protocol.h:37
serialize.h
NetMsgType::VERACK
const char * VERACK
The verack message acknowledges a previously-received version message, informing the connecting node ...
Definition: protocol.cpp:14
CInv::IsMsgBlk
bool IsMsgBlk() const
Definition: protocol.h:438
SER_WRITE
#define SER_WRITE(obj, code)
Definition: serialize.h:178
NetMsgType::FILTERADD
const char * FILTERADD
The filteradd message tells the receiving peer to add a single element to a previously-set bloom filt...
Definition: protocol.cpp:32
CInv::IsGenBlkMsg
bool IsGenBlkMsg() const
Definition: protocol.h:449
NetMsgType::GETBLOCKTXN
const char * GETBLOCKTXN
Contains a BlockTransactionsRequest Peer should respond with "blocktxn" message.
Definition: protocol.cpp:38
serviceFlagsToStr
std::vector< std::string > serviceFlagsToStr(uint64_t flags)
Convert service flags (a bitmask of NODE_*) to human readable strings.
Definition: protocol.cpp:220
CInv::IsMsgWtx
bool IsMsgWtx() const
Definition: protocol.h:439
NetMsgType::CFCHECKPT
const char * CFCHECKPT
cfcheckpt is a response to a getcfcheckpt request containing a vector of evenly spaced filter headers...
Definition: protocol.cpp:45
SER_READ
#define SER_READ(obj, code)
Definition: serialize.h:177
NetMsgType::VERSION
const char * VERSION
The version message provides information about the transmitting node to the receiving node at the beg...
Definition: protocol.cpp:13
CMessageHeader::pchChecksum
uint8_t pchChecksum[CHECKSUM_SIZE]
Definition: protocol.h:55
Using
static Wrapper< Formatter, T & > Using(T &&t)
Cause serialization/deserialization of an object to be done using a specified formatter class.
Definition: serialize.h:476
UNDEFINED
@ UNDEFINED
Definition: protocol.h:408
ToGenTxid
GenTxid ToGenTxid(const CInv &inv)
Convert a TX/WITNESS_TX/WTX CInv to a GenTxid.
Definition: protocol.cpp:233
NetMsgType::BLOCKTXN
const char * BLOCKTXN
Contains a BlockTransactions.
Definition: protocol.cpp:39
MSG_WITNESS_BLOCK
@ MSG_WITNESS_BLOCK
Defined in BIP144.
Definition: protocol.h:415
SER_GETHASH
@ SER_GETHASH
Definition: serialize.h:168
CInv::type
uint32_t type
Definition: protocol.h:454
CInv::ToString
std::string ToString() const
Definition: protocol.cpp:180
MSG_WITNESS_FLAG
const uint32_t MSG_WITNESS_FLAG
getdata message type flags
Definition: protocol.h:400
NetMsgType::GETCFILTERS
const char * GETCFILTERS
getcfilters requests compact filters for a range of blocks.
Definition: protocol.cpp:40
NetMsgType::GETADDR
const char * GETADDR
The getaddr message requests an addr message from the receiving node, preferably one with lots of IP ...
Definition: protocol.cpp:26
INIT_PROTO_VERSION
static const int INIT_PROTO_VERSION
initial proto version, to be increased after version/verack negotiation
Definition: version.h:15
NetMsgType::MERKLEBLOCK
const char * MERKLEBLOCK
The merkleblock message is a reply to a getdata message which requested a block using the inventory t...
Definition: protocol.cpp:20
GetDataMsg
GetDataMsg
getdata / inv message types.
Definition: protocol.h:407