Line data Source code
1 : // Copyright (c) 2009-2010 Satoshi Nakamoto
2 : // Copyright (c) 2009-2019 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 :
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 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;
35 : static constexpr size_t MESSAGE_SIZE_OFFSET = MESSAGE_START_SIZE + COMMAND_SIZE;
36 : static constexpr size_t CHECKSUM_OFFSET = MESSAGE_SIZE_OFFSET + MESSAGE_SIZE_SIZE;
37 : static constexpr size_t HEADER_SIZE = MESSAGE_START_SIZE + COMMAND_SIZE + MESSAGE_SIZE_SIZE + CHECKSUM_SIZE;
38 : typedef unsigned char MessageStartChars[MESSAGE_START_SIZE];
39 :
40 : explicit CMessageHeader(const MessageStartChars& pchMessageStartIn);
41 :
42 : /** Construct a P2P message header from message-start characters, a command and the size of the message.
43 : * @note Passing in a `pszCommand` longer than COMMAND_SIZE will result in a run-time assertion error.
44 : */
45 : CMessageHeader(const MessageStartChars& pchMessageStartIn, const char* pszCommand, unsigned int nMessageSizeIn);
46 :
47 : std::string GetCommand() const;
48 : bool IsValid(const MessageStartChars& messageStart) const;
49 :
50 534321 : SERIALIZE_METHODS(CMessageHeader, obj) { READWRITE(obj.pchMessageStart, obj.pchCommand, obj.nMessageSize, obj.pchChecksum); }
51 :
52 : char pchMessageStart[MESSAGE_START_SIZE];
53 : char pchCommand[COMMAND_SIZE];
54 : uint32_t nMessageSize;
55 : uint8_t pchChecksum[CHECKSUM_SIZE];
56 : };
57 :
58 : /**
59 : * Bitcoin protocol message types. When adding new message types, don't forget
60 : * to update allNetMessageTypes in protocol.cpp.
61 : */
62 : namespace NetMsgType {
63 :
64 : /**
65 : * The version message provides information about the transmitting node to the
66 : * receiving node at the beginning of a connection.
67 : */
68 : extern const char* VERSION;
69 : /**
70 : * The verack message acknowledges a previously-received version message,
71 : * informing the connecting node that it can begin to send other messages.
72 : */
73 : extern const char* VERACK;
74 : /**
75 : * The addr (IP address) message relays connection information for peers on the
76 : * network.
77 : */
78 : extern const char* ADDR;
79 : /**
80 : * The inv message (inventory message) transmits one or more inventories of
81 : * objects known to the transmitting peer.
82 : */
83 : extern const char* INV;
84 : /**
85 : * The getdata message requests one or more data objects from another node.
86 : */
87 : extern const char* GETDATA;
88 : /**
89 : * The merkleblock message is a reply to a getdata message which requested a
90 : * block using the inventory type MSG_MERKLEBLOCK.
91 : * @since protocol version 70001 as described by BIP37.
92 : */
93 : extern const char* MERKLEBLOCK;
94 : /**
95 : * The getblocks message requests an inv message that provides block header
96 : * hashes starting from a particular point in the block chain.
97 : */
98 : extern const char* GETBLOCKS;
99 : /**
100 : * The getheaders message requests a headers message that provides block
101 : * headers starting from a particular point in the block chain.
102 : * @since protocol version 31800.
103 : */
104 : extern const char* GETHEADERS;
105 : /**
106 : * The tx message transmits a single transaction.
107 : */
108 : extern const char* TX;
109 : /**
110 : * The headers message sends one or more block headers to a node which
111 : * previously requested certain headers with a getheaders message.
112 : * @since protocol version 31800.
113 : */
114 : extern const char* HEADERS;
115 : /**
116 : * The block message transmits a single serialized block.
117 : */
118 : extern const char* BLOCK;
119 : /**
120 : * The getaddr message requests an addr message from the receiving node,
121 : * preferably one with lots of IP addresses of other receiving nodes.
122 : */
123 : extern const char* GETADDR;
124 : /**
125 : * The mempool message requests the TXIDs of transactions that the receiving
126 : * node has verified as valid but which have not yet appeared in a block.
127 : * @since protocol version 60002.
128 : */
129 : extern const char* MEMPOOL;
130 : /**
131 : * The ping message is sent periodically to help confirm that the receiving
132 : * peer is still connected.
133 : */
134 : extern const char* PING;
135 : /**
136 : * The pong message replies to a ping message, proving to the pinging node that
137 : * the ponging node is still alive.
138 : * @since protocol version 60001 as described by BIP31.
139 : */
140 : extern const char* PONG;
141 : /**
142 : * The notfound message is a reply to a getdata message which requested an
143 : * object the receiving node does not have available for relay.
144 : * @since protocol version 70001.
145 : */
146 : extern const char* NOTFOUND;
147 : /**
148 : * The filterload message tells the receiving peer to filter all relayed
149 : * transactions and requested merkle blocks through the provided filter.
150 : * @since protocol version 70001 as described by BIP37.
151 : * Only available with service bit NODE_BLOOM since protocol version
152 : * 70011 as described by BIP111.
153 : */
154 : extern const char* FILTERLOAD;
155 : /**
156 : * The filteradd message tells the receiving peer to add a single element to a
157 : * previously-set bloom filter, such as a new public key.
158 : * @since protocol version 70001 as described by BIP37.
159 : * Only available with service bit NODE_BLOOM since protocol version
160 : * 70011 as described by BIP111.
161 : */
162 : extern const char* FILTERADD;
163 : /**
164 : * The filterclear message tells the receiving peer to remove a previously-set
165 : * bloom filter.
166 : * @since protocol version 70001 as described by BIP37.
167 : * Only available with service bit NODE_BLOOM since protocol version
168 : * 70011 as described by BIP111.
169 : */
170 : extern const char* FILTERCLEAR;
171 : /**
172 : * Indicates that a node prefers to receive new block announcements via a
173 : * "headers" message rather than an "inv".
174 : * @since protocol version 70012 as described by BIP130.
175 : */
176 : extern const char* SENDHEADERS;
177 : /**
178 : * The feefilter message tells the receiving peer not to inv us any txs
179 : * which do not meet the specified min fee rate.
180 : * @since protocol version 70013 as described by BIP133
181 : */
182 : extern const char* FEEFILTER;
183 : /**
184 : * Contains a 1-byte bool and 8-byte LE version number.
185 : * Indicates that a node is willing to provide blocks via "cmpctblock" messages.
186 : * May indicate that a node prefers to receive new block announcements via a
187 : * "cmpctblock" message rather than an "inv", depending on message contents.
188 : * @since protocol version 70014 as described by BIP 152
189 : */
190 : extern const char* SENDCMPCT;
191 : /**
192 : * Contains a CBlockHeaderAndShortTxIDs object - providing a header and
193 : * list of "short txids".
194 : * @since protocol version 70014 as described by BIP 152
195 : */
196 : extern const char* CMPCTBLOCK;
197 : /**
198 : * Contains a BlockTransactionsRequest
199 : * Peer should respond with "blocktxn" message.
200 : * @since protocol version 70014 as described by BIP 152
201 : */
202 : extern const char* GETBLOCKTXN;
203 : /**
204 : * Contains a BlockTransactions.
205 : * Sent in response to a "getblocktxn" message.
206 : * @since protocol version 70014 as described by BIP 152
207 : */
208 : extern const char* BLOCKTXN;
209 : /**
210 : * getcfilters requests compact filters for a range of blocks.
211 : * Only available with service bit NODE_COMPACT_FILTERS as described by
212 : * BIP 157 & 158.
213 : */
214 : extern const char* GETCFILTERS;
215 : /**
216 : * cfilter is a response to a getcfilters request containing a single compact
217 : * filter.
218 : */
219 : extern const char* CFILTER;
220 : /**
221 : * getcfheaders requests a compact filter header and the filter hashes for a
222 : * range of blocks, which can then be used to reconstruct the filter headers
223 : * for those blocks.
224 : * Only available with service bit NODE_COMPACT_FILTERS as described by
225 : * BIP 157 & 158.
226 : */
227 : extern const char* GETCFHEADERS;
228 : /**
229 : * cfheaders is a response to a getcfheaders request containing a filter header
230 : * and a vector of filter hashes for each subsequent block in the requested range.
231 : */
232 : extern const char* CFHEADERS;
233 : /**
234 : * getcfcheckpt requests evenly spaced compact filter headers, enabling
235 : * parallelized download and validation of the headers between them.
236 : * Only available with service bit NODE_COMPACT_FILTERS as described by
237 : * BIP 157 & 158.
238 : */
239 : extern const char* GETCFCHECKPT;
240 : /**
241 : * cfcheckpt is a response to a getcfcheckpt request containing a vector of
242 : * evenly spaced filter headers for blocks on the requested chain.
243 : */
244 : extern const char* CFCHECKPT;
245 : /**
246 : * Indicates that a node prefers to relay transactions via wtxid, rather than
247 : * txid.
248 : * @since protocol version 70016 as described by BIP 339.
249 : */
250 : extern const char* WTXIDRELAY;
251 : }; // namespace NetMsgType
252 :
253 : /* Get a vector of all valid message types (see above) */
254 : const std::vector<std::string>& getAllNetMessageTypes();
255 :
256 : /** nServices flags */
257 : enum ServiceFlags : uint64_t {
258 : // NOTE: When adding here, be sure to update serviceFlagToStr too
259 : // Nothing
260 : NODE_NONE = 0,
261 : // NODE_NETWORK means that the node is capable of serving the complete block chain. It is currently
262 : // set by all Bitcoin Core non pruned nodes, and is unset by SPV clients or other light clients.
263 : NODE_NETWORK = (1 << 0),
264 : // NODE_GETUTXO means the node is capable of responding to the getutxo protocol request.
265 : // Bitcoin Core does not support this but a patch set called Bitcoin XT does.
266 : // See BIP 64 for details on how this is implemented.
267 : NODE_GETUTXO = (1 << 1),
268 : // NODE_BLOOM means the node is capable and willing to handle bloom-filtered connections.
269 : // Bitcoin Core nodes used to support this by default, without advertising this bit,
270 : // but no longer do as of protocol version 70011 (= NO_BLOOM_VERSION)
271 : NODE_BLOOM = (1 << 2),
272 : // NODE_WITNESS indicates that a node can be asked for blocks and transactions including
273 : // witness data.
274 : NODE_WITNESS = (1 << 3),
275 : // NODE_COMPACT_FILTERS means the node will service basic block filter requests.
276 : // See BIP157 and BIP158 for details on how this is implemented.
277 : NODE_COMPACT_FILTERS = (1 << 6),
278 : // NODE_NETWORK_LIMITED means the same as NODE_NETWORK with the limitation of only
279 : // serving the last 288 (2 day) blocks
280 : // See BIP159 for details on how this is implemented.
281 : NODE_NETWORK_LIMITED = (1 << 10),
282 :
283 : // Bits 24-31 are reserved for temporary experiments. Just pick a bit that
284 : // isn't getting used, or one not being used much, and notify the
285 : // bitcoin-development mailing list. Remember that service bits are just
286 : // unauthenticated advertisements, so your code must be robust against
287 : // collisions and other cases where nodes may be advertising a service they
288 : // do not actually support. Other service bits should be allocated via the
289 : // BIP process.
290 : };
291 :
292 : /**
293 : * Convert service flags (a bitmask of NODE_*) to human readable strings.
294 : * It supports unknown service flags which will be returned as "UNKNOWN[...]".
295 : * @param[in] flags multiple NODE_* bitwise-OR-ed together
296 : */
297 : std::vector<std::string> serviceFlagsToStr(uint64_t flags);
298 :
299 : /**
300 : * Gets the set of service flags which are "desirable" for a given peer.
301 : *
302 : * These are the flags which are required for a peer to support for them
303 : * to be "interesting" to us, ie for us to wish to use one of our few
304 : * outbound connection slots for or for us to wish to prioritize keeping
305 : * their connection around.
306 : *
307 : * Relevant service flags may be peer- and state-specific in that the
308 : * version of the peer may determine which flags are required (eg in the
309 : * case of NODE_NETWORK_LIMITED where we seek out NODE_NETWORK peers
310 : * unless they set NODE_NETWORK_LIMITED and we are out of IBD, in which
311 : * case NODE_NETWORK_LIMITED suffices).
312 : *
313 : * Thus, generally, avoid calling with peerServices == NODE_NONE, unless
314 : * state-specific flags must absolutely be avoided. When called with
315 : * peerServices == NODE_NONE, the returned desirable service flags are
316 : * guaranteed to not change dependent on state - ie they are suitable for
317 : * use when describing peers which we know to be desirable, but for which
318 : * we do not have a confirmed set of service flags.
319 : *
320 : * If the NODE_NONE return value is changed, contrib/seeds/makeseeds.py
321 : * should be updated appropriately to filter for the same nodes.
322 : */
323 : ServiceFlags GetDesirableServiceFlags(ServiceFlags services);
324 :
325 : /** Set the current IBD status in order to figure out the desirable service flags */
326 : void SetServiceFlagsIBDCache(bool status);
327 :
328 : /**
329 : * A shortcut for (services & GetDesirableServiceFlags(services))
330 : * == GetDesirableServiceFlags(services), ie determines whether the given
331 : * set of service flags are sufficient for a peer to be "relevant".
332 : */
333 340 : static inline bool HasAllDesirableServiceFlags(ServiceFlags services)
334 : {
335 340 : return !(GetDesirableServiceFlags(services) & (~services));
336 : }
337 :
338 : /**
339 : * Checks if a peer with the given service flags may be capable of having a
340 : * robust address-storage DB.
341 : */
342 10013 : static inline bool MayHaveUsefulAddressDB(ServiceFlags services)
343 : {
344 10013 : return (services & NODE_NETWORK) || (services & NODE_NETWORK_LIMITED);
345 : }
346 :
347 : /** A CService with information about it as peer */
348 2550867 : class CAddress : public CService
349 : {
350 : static constexpr uint32_t TIME_INIT{100000000};
351 :
352 : public:
353 530156 : CAddress() : CService{} {};
354 71286 : explicit CAddress(CService ipIn, ServiceFlags nServicesIn) : CService{ipIn}, nServices{nServicesIn} {};
355 :
356 131244 : SERIALIZE_METHODS(CAddress, obj)
357 : {
358 56183 : SER_READ(obj, obj.nTime = TIME_INIT);
359 43748 : int nVersion = s.GetVersion();
360 43748 : if (s.GetType() & SER_DISK) {
361 24894 : READWRITE(nVersion);
362 24894 : }
363 59767 : if ((s.GetType() & SER_DISK) ||
364 18854 : (nVersion != INIT_PROTO_VERSION && !(s.GetType() & SER_GETHASH))) {
365 : // The only time we serialize a CAddress object without nTime is in
366 : // the initial VERSION messages which contain two CAddress records.
367 : // At that point, the serialization version is INIT_PROTO_VERSION.
368 : // After the version handshake, serialization version is >=
369 : // MIN_PEER_PROTO_VERSION and all ADDR messages are serialized with
370 : // nTime.
371 40913 : READWRITE(obj.nTime);
372 40913 : }
373 43746 : READWRITE(Using<CustomUintFormatter<8>>(obj.nServices));
374 43746 : READWRITEAS(CService, obj);
375 43746 : }
376 :
377 : // disk and network only
378 509174 : uint32_t nTime{TIME_INIT};
379 :
380 473531 : ServiceFlags nServices{NODE_NONE};
381 : };
382 :
383 : /** getdata message type flags */
384 : const uint32_t MSG_WITNESS_FLAG = 1 << 30;
385 : const uint32_t MSG_TYPE_MASK = 0xffffffff >> 2;
386 :
387 : /** getdata / inv message types.
388 : * These numbers are defined by the protocol. When adding a new value, be sure
389 : * to mention it in the respective BIP.
390 : */
391 : enum GetDataMsg : uint32_t {
392 : UNDEFINED = 0,
393 : MSG_TX = 1,
394 : MSG_BLOCK = 2,
395 : MSG_WTX = 5, //!< Defined in BIP 339
396 : // The following can only occur in getdata. Invs always use TX/WTX or BLOCK.
397 : MSG_FILTERED_BLOCK = 3, //!< Defined in BIP37
398 : MSG_CMPCT_BLOCK = 4, //!< Defined in BIP152
399 : MSG_WITNESS_BLOCK = MSG_BLOCK | MSG_WITNESS_FLAG, //!< Defined in BIP144
400 : MSG_WITNESS_TX = MSG_TX | MSG_WITNESS_FLAG, //!< Defined in BIP144
401 : // MSG_FILTERED_WITNESS_BLOCK is defined in BIP144 as reserved for future
402 : // use and remains unused.
403 : // MSG_FILTERED_WITNESS_BLOCK = MSG_FILTERED_BLOCK | MSG_WITNESS_FLAG,
404 : };
405 :
406 : /** inv message data */
407 : class CInv
408 : {
409 : public:
410 : CInv();
411 : CInv(uint32_t typeIn, const uint256& hashIn);
412 :
413 562020 : SERIALIZE_METHODS(CInv, obj) { READWRITE(obj.type, obj.hash); }
414 :
415 : friend bool operator<(const CInv& a, const CInv& b);
416 :
417 : std::string GetCommand() const;
418 : std::string ToString() const;
419 :
420 : // Single-message helper methods
421 25296 : bool IsMsgTx() const { return type == MSG_TX; }
422 24619 : bool IsMsgBlk() const { return type == MSG_BLOCK; }
423 52083 : bool IsMsgWtx() const { return type == MSG_WTX; }
424 1022 : bool IsMsgFilteredBlk() const { return type == MSG_FILTERED_BLOCK; }
425 195 : bool IsMsgCmpctBlk() const { return type == MSG_CMPCT_BLOCK; }
426 11630 : bool IsMsgWitnessBlk() const { return type == MSG_WITNESS_BLOCK; }
427 :
428 : // Combined-message helper methods
429 91462 : bool IsGenTxMsg() const
430 : {
431 91462 : return type == MSG_TX || type == MSG_WTX || type == MSG_WITNESS_TX;
432 : }
433 15128 : bool IsGenBlkMsg() const
434 : {
435 15128 : return type == MSG_BLOCK || type == MSG_FILTERED_BLOCK || type == MSG_CMPCT_BLOCK || type == MSG_WITNESS_BLOCK;
436 : }
437 :
438 : uint32_t type;
439 : uint256 hash;
440 : };
441 :
442 : /** Convert a TX/WITNESS_TX/WTX CInv to a GenTxid. */
443 : GenTxid ToGenTxid(const CInv& inv);
444 :
445 : #endif // BITCOIN_PROTOCOL_H
|
