src/protocol.h

   1 // Copyright (c) 2009-2010 Satoshi Nakamoto
   2 // Copyright (c) 2009-2017 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 <serialize.h>
  15 #include <uint256.h>
  16 #include <version.h>
  17
  18 #include <stdint.h>
  19 #include <string>
  20
  21 /** Message header.
  22  * (4) message start.
  23  * (12) command.
  24  * (4) size.
  25  * (4) checksum.
  26  */
  27 class CMessageHeader
  28 {
  29 public:
  30     static constexpr size_t MESSAGE_START_SIZE = 4;
  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 = MESSAGE_START_SIZE + COMMAND_SIZE;
  35     static constexpr size_t CHECKSUM_OFFSET = MESSAGE_SIZE_OFFSET + MESSAGE_SIZE_SIZE;
  36     static constexpr size_t HEADER_SIZE = MESSAGE_START_SIZE + COMMAND_SIZE + MESSAGE_SIZE_SIZE + CHECKSUM_SIZE;
  37     typedef unsigned char MessageStartChars[MESSAGE_START_SIZE];
  38
  39     explicit CMessageHeader(const MessageStartChars& pchMessageStartIn);
  40     CMessageHeader(const MessageStartChars& pchMessageStartIn, const char* pszCommand, unsigned int nMessageSizeIn);
  41
  42     std::string GetCommand() const;
  43     bool IsValid(const MessageStartChars& messageStart) const;
  44
  45     ADD_SERIALIZE_METHODS;
  46
  47     template <typename Stream, typename Operation>
  48     inline void SerializationOp(Stream& s, Operation ser_action)
  49     {
  50         READWRITE(FLATDATA(pchMessageStart));
  51         READWRITE(FLATDATA(pchCommand));
  52         READWRITE(nMessageSize);
  53         READWRITE(FLATDATA(pchChecksum));
  54     }
  55
  56     char pchMessageStart[MESSAGE_START_SIZE];
  57     char pchCommand[COMMAND_SIZE];
  58     uint32_t nMessageSize;
  59     uint8_t pchChecksum[CHECKSUM_SIZE];
  60 };
  61
  62 /**
  63  * Bitcoin protocol message types. When adding new message types, don't forget
  64  * to update allNetMessageTypes in protocol.cpp.
  65  */
  66 namespace NetMsgType {
  67
  68 /**
  69  * The version message provides information about the transmitting node to the
  70  * receiving node at the beginning of a connection.
  71  * @see https://bitcoin.org/en/developer-reference#version
  72  */
  73 extern const char *VERSION;
  74 /**
  75  * The verack message acknowledges a previously-received version message,
  76  * informing the connecting node that it can begin to send other messages.
  77  * @see https://bitcoin.org/en/developer-reference#verack
  78  */
  79 extern const char *VERACK;
  80 /**
  81  * The addr (IP address) message relays connection information for peers on the
  82  * network.
  83  * @see https://bitcoin.org/en/developer-reference#addr
  84  */
  85 extern const char *ADDR;
  86 /**
  87  * The inv message (inventory message) transmits one or more inventories of
  88  * objects known to the transmitting peer.
  89  * @see https://bitcoin.org/en/developer-reference#inv
  90  */
  91 extern const char *INV;
  92 /**
  93  * The getdata message requests one or more data objects from another node.
  94  * @see https://bitcoin.org/en/developer-reference#getdata
  95  */
  96 extern const char *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  * @see https://bitcoin.org/en/developer-reference#merkleblock
 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  * @see https://bitcoin.org/en/developer-reference#getblocks
 108  */
 109 extern const char *GETBLOCKS;
 110 /**
 111  * The getheaders message requests a headers message that provides block
 112  * headers starting from a particular point in the block chain.
 113  * @since protocol version 31800.
 114  * @see https://bitcoin.org/en/developer-reference#getheaders
 115  */
 116 extern const char *GETHEADERS;
 117 /**
 118  * The tx message transmits a single transaction.
 119  * @see https://bitcoin.org/en/developer-reference#tx
 120  */
 121 extern const char *TX;
 122 /**
 123  * The headers message sends one or more block headers to a node which
 124  * previously requested certain headers with a getheaders message.
 125  * @since protocol version 31800.
 126  * @see https://bitcoin.org/en/developer-reference#headers
 127  */
 128 extern const char *HEADERS;
 129 /**
 130  * The block message transmits a single serialized block.
 131  * @see https://bitcoin.org/en/developer-reference#block
 132  */
 133 extern const char *BLOCK;
 134 /**
 135  * The getaddr message requests an addr message from the receiving node,
 136  * preferably one with lots of IP addresses of other receiving nodes.
 137  * @see https://bitcoin.org/en/developer-reference#getaddr
 138  */
 139 extern const char *GETADDR;
 140 /**
 141  * The mempool message requests the TXIDs of transactions that the receiving
 142  * node has verified as valid but which have not yet appeared in a block.
 143  * @since protocol version 60002.
 144  * @see https://bitcoin.org/en/developer-reference#mempool
 145  */
 146 extern const char *MEMPOOL;
 147 /**
 148  * The ping message is sent periodically to help confirm that the receiving
 149  * peer is still connected.
 150  * @see https://bitcoin.org/en/developer-reference#ping
 151  */
 152 extern const char *PING;
 153 /**
 154  * The pong message replies to a ping message, proving to the pinging node that
 155  * the ponging node is still alive.
 156  * @since protocol version 60001 as described by BIP31.
 157  * @see https://bitcoin.org/en/developer-reference#pong
 158  */
 159 extern const char *PONG;
 160 /**
 161  * The notfound message is a reply to a getdata message which requested an
 162  * object the receiving node does not have available for relay.
 163  * @since protocol version 70001.
 164  * @see https://bitcoin.org/en/developer-reference#notfound
 165  */
 166 extern const char *NOTFOUND;
 167 /**
 168  * The filterload message tells the receiving peer to filter all relayed
 169  * transactions and requested merkle blocks through the provided filter.
 170  * @since protocol version 70001 as described by BIP37.
 171  *   Only available with service bit NODE_BLOOM since protocol version
 172  *   70011 as described by BIP111.
 173  * @see https://bitcoin.org/en/developer-reference#filterload
 174  */
 175 extern const char *FILTERLOAD;
 176 /**
 177  * The filteradd message tells the receiving peer to add a single element to a
 178  * previously-set bloom filter, such as a new public key.
 179  * @since protocol version 70001 as described by BIP37.
 180  *   Only available with service bit NODE_BLOOM since protocol version
 181  *   70011 as described by BIP111.
 182  * @see https://bitcoin.org/en/developer-reference#filteradd
 183  */
 184 extern const char *FILTERADD;
 185 /**
 186  * The filterclear message tells the receiving peer to remove a previously-set
 187  * bloom filter.
 188  * @since protocol version 70001 as described by BIP37.
 189  *   Only available with service bit NODE_BLOOM since protocol version
 190  *   70011 as described by BIP111.
 191  * @see https://bitcoin.org/en/developer-reference#filterclear
 192  */
 193 extern const char *FILTERCLEAR;
 194 /**
 195  * The reject message informs the receiving node that one of its previous
 196  * messages has been rejected.
 197  * @since protocol version 70002 as described by BIP61.
 198  * @see https://bitcoin.org/en/developer-reference#reject
 199  */
 200 extern const char *REJECT;
 201 /**
 202  * Indicates that a node prefers to receive new block announcements via a
 203  * "headers" message rather than an "inv".
 204  * @since protocol version 70012 as described by BIP130.
 205  * @see https://bitcoin.org/en/developer-reference#sendheaders
 206  */
 207 extern const char *SENDHEADERS;
 208 /**
 209  * The feefilter message tells the receiving peer not to inv us any txs
 210  * which do not meet the specified min fee rate.
 211  * @since protocol version 70013 as described by BIP133
 212  */
 213 extern const char *FEEFILTER;
 214 /**
 215  * Contains a 1-byte bool and 8-byte LE version number.
 216  * Indicates that a node is willing to provide blocks via "cmpctblock" messages.
 217  * May indicate that a node prefers to receive new block announcements via a
 218  * "cmpctblock" message rather than an "inv", depending on message contents.
 219  * @since protocol version 70014 as described by BIP 152
 220  */
 221 extern const char *SENDCMPCT;
 222 /**
 223  * Contains a CBlockHeaderAndShortTxIDs object - providing a header and
 224  * list of "short txids".
 225  * @since protocol version 70014 as described by BIP 152
 226  */
 227 extern const char *CMPCTBLOCK;
 228 /**
 229  * Contains a BlockTransactionsRequest
 230  * Peer should respond with "blocktxn" message.
 231  * @since protocol version 70014 as described by BIP 152
 232  */
 233 extern const char *GETBLOCKTXN;
 234 /**
 235  * Contains a BlockTransactions.
 236  * Sent in response to a "getblocktxn" message.
 237  * @since protocol version 70014 as described by BIP 152
 238  */
 239 extern const char *BLOCKTXN;
 240 };
 241
 242 /* Get a vector of all valid message types (see above) */
 243 const std::vector<std::string> &getAllNetMessageTypes();
 244
 245 /** nServices flags */
 246 enum ServiceFlags : uint64_t {
 247     // Nothing
 248     NODE_NONE = 0,
 249     // NODE_NETWORK means that the node is capable of serving the complete block chain. It is currently
 250     // set by all Bitcoin Core non pruned nodes, and is unset by SPV clients or other light clients.
 251     NODE_NETWORK = (1 << 0),
 252     // NODE_GETUTXO means the node is capable of responding to the getutxo protocol request.
 253     // Bitcoin Core does not support this but a patch set called Bitcoin XT does.
 254     // See BIP 64 for details on how this is implemented.
 255     NODE_GETUTXO = (1 << 1),
 256     // NODE_BLOOM means the node is capable and willing to handle bloom-filtered connections.
 257     // Bitcoin Core nodes used to support this by default, without advertising this bit,
 258     // but no longer do as of protocol version 70011 (= NO_BLOOM_VERSION)
 259     NODE_BLOOM = (1 << 2),
 260     // NODE_WITNESS indicates that a node can be asked for blocks and transactions including
 261     // witness data.
 262     NODE_WITNESS = (1 << 3),
 263     // NODE_XTHIN means the node supports Xtreme Thinblocks
 264     // If this is turned off then the node will not service nor make xthin requests
 265     NODE_XTHIN = (1 << 4),
 266     // NODE_NETWORK_LIMITED means the same as NODE_NETWORK with the limitation of only
 267     // serving the last 288 (2 day) blocks
 268     // See BIP159 for details on how this is implemented.
 269     NODE_NETWORK_LIMITED = (1 << 10),
 270
 271     // Bits 24-31 are reserved for temporary experiments. Just pick a bit that
 272     // isn't getting used, or one not being used much, and notify the
 273     // bitcoin-development mailing list. Remember that service bits are just
 274     // unauthenticated advertisements, so your code must be robust against
 275     // collisions and other cases where nodes may be advertising a service they
 276     // do not actually support. Other service bits should be allocated via the
 277     // BIP process.
 278 };
 279
 280 /**
 281  * Gets the set of service flags which are "desirable" for a given peer.
 282  *
 283  * These are the flags which are required for a peer to support for them
 284  * to be "interesting" to us, ie for us to wish to use one of our few
 285  * outbound connection slots for or for us to wish to prioritize keeping
 286  * their connection around.
 287  *
 288  * Relevant service flags may be peer- and state-specific in that the
 289  * version of the peer may determine which flags are required (eg in the
 290  * case of NODE_NETWORK_LIMITED where we seek out NODE_NETWORK peers
 291  * unless they set NODE_NETWORK_LIMITED and we are out of IBD, in which
 292  * case NODE_NETWORK_LIMITED suffices).
 293  *
 294  * Thus, generally, avoid calling with peerServices == NODE_NONE.
 295  */
 296 static ServiceFlags GetDesirableServiceFlags(ServiceFlags services) {
 297     return ServiceFlags(NODE_NETWORK | NODE_WITNESS);
 298 }
 299
 300 /**
 301  * A shortcut for (services & GetDesirableServiceFlags(services))
 302  * == GetDesirableServiceFlags(services), ie determines whether the given
 303  * set of service flags are sufficient for a peer to be "relevant".
 304  */
 305 static inline bool HasAllDesirableServiceFlags(ServiceFlags services) {
 306     return !(GetDesirableServiceFlags(services) & (~services));
 307 }
 308
 309 /**
 310  * Checks if a peer with the given service flags may be capable of having a
 311  * robust address-storage DB. Currently an alias for checking NODE_NETWORK.
 312  */
 313 static inline bool MayHaveUsefulAddressDB(ServiceFlags services) {
 314     return services & NODE_NETWORK;
 315 }
 316
 317 /** A CService with information about it as peer */
 318 class CAddress : public CService
 319 {
 320 public:
 321     CAddress();
 322     explicit CAddress(CService ipIn, ServiceFlags nServicesIn);
 323
 324     void Init();
 325
 326     ADD_SERIALIZE_METHODS;
 327
 328     template <typename Stream, typename Operation>
 329     inline void SerializationOp(Stream& s, Operation ser_action)
 330     {
 331         if (ser_action.ForRead())
 332             Init();
 333         int nVersion = s.GetVersion();
 334         if (s.GetType() & SER_DISK)
 335             READWRITE(nVersion);
 336         if ((s.GetType() & SER_DISK) ||
 337             (nVersion >= CADDR_TIME_VERSION && !(s.GetType() & SER_GETHASH)))
 338             READWRITE(nTime);
 339         uint64_t nServicesInt = nServices;
 340         READWRITE(nServicesInt);
 341         nServices = (ServiceFlags)nServicesInt;
 342         READWRITE(*(CService*)this);
 343     }
 344
 345     // TODO: make private (improves encapsulation)
 346 public:
 347     ServiceFlags nServices;
 348
 349     // disk and network only
 350     unsigned int nTime;
 351 };
 352
 353 /** getdata message type flags */
 354 const uint32_t MSG_WITNESS_FLAG = 1 << 30;
 355 const uint32_t MSG_TYPE_MASK    = 0xffffffff >> 2;
 356
 357 /** getdata / inv message types.
 358  * These numbers are defined by the protocol. When adding a new value, be sure
 359  * to mention it in the respective BIP.
 360  */
 361 enum GetDataMsg
 362 {
 363     UNDEFINED = 0,
 364     MSG_TX = 1,
 365     MSG_BLOCK = 2,
 366     // The following can only occur in getdata. Invs always use TX or BLOCK.
 367     MSG_FILTERED_BLOCK = 3,  //!< Defined in BIP37
 368     MSG_CMPCT_BLOCK = 4,     //!< Defined in BIP152
 369     MSG_WITNESS_BLOCK = MSG_BLOCK | MSG_WITNESS_FLAG, //!< Defined in BIP144
 370     MSG_WITNESS_TX = MSG_TX | MSG_WITNESS_FLAG,       //!< Defined in BIP144
 371     MSG_FILTERED_WITNESS_BLOCK = MSG_FILTERED_BLOCK | MSG_WITNESS_FLAG,
 372 };
 373
 374 /** inv message data */
 375 class CInv
 376 {
 377 public:
 378     CInv();
 379     CInv(int typeIn, const uint256& hashIn);
 380
 381     ADD_SERIALIZE_METHODS;
 382
 383     template <typename Stream, typename Operation>
 384     inline void SerializationOp(Stream& s, Operation ser_action)
 385     {
 386         READWRITE(type);
 387         READWRITE(hash);
 388     }
 389
 390     friend bool operator<(const CInv& a, const CInv& b);
 391
 392     std::string GetCommand() const;
 393     std::string ToString() const;
 394
 395     // TODO: make private (improves encapsulation)
 396 public:
 397     int type;
 398     uint256 hash;
 399 };
 400
 401 #endif // BITCOIN_PROTOCOL_H