src/protocol.h

   1 // Copyright (c) 2009-2010 Satoshi Nakamoto
   2 // Copyright (c) 2009-2016 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 block chain. It is currently
 250     // set by all Bitcoin Core nodes, and is unset by SPV clients or other peers that just want
 251     // network services but don't provide them.
 252     NODE_NETWORK = (1 << 0),
 253     // NODE_GETUTXO means the node is capable of responding to the getutxo protocol request.
 254     // Bitcoin Core does not support this but a patch set called Bitcoin XT does.
 255     // See BIP 64 for details on how this is implemented.
 256     NODE_GETUTXO = (1 << 1),
 257     // NODE_BLOOM means the node is capable and willing to handle bloom-filtered connections.
 258     // Bitcoin Core nodes used to support this by default, without advertising this bit,
 259     // but no longer do as of protocol version 70011 (= NO_BLOOM_VERSION)
 260     NODE_BLOOM = (1 << 2),
 261     // NODE_WITNESS indicates that a node can be asked for blocks and transactions including
 262     // witness data.
 263     NODE_WITNESS = (1 << 3),
 264     // NODE_XTHIN means the node supports Xtreme Thinblocks
 265     // If this is turned off then the node will not service nor make xthin requests
 266     NODE_XTHIN = (1 << 4),
 267
 268     // Bits 24-31 are reserved for temporary experiments. Just pick a bit that
 269     // isn't getting used, or one not being used much, and notify the
 270     // bitcoin-development mailing list. Remember that service bits are just
 271     // unauthenticated advertisements, so your code must be robust against
 272     // collisions and other cases where nodes may be advertising a service they
 273     // do not actually support. Other service bits should be allocated via the
 274     // BIP process.
 275 };
 276
 277 /**
 278  * Gets the set of service flags which are "desirable" for a given peer.
 279  *
 280  * These are the flags which are required for a peer to support for them
 281  * to be "interesting" to us, ie for us to wish to use one of our few
 282  * outbound connection slots for or for us to wish to prioritize keeping
 283  * their connection around.
 284  *
 285  * Relevant service flags may be peer- and state-specific in that the
 286  * version of the peer may determine which flags are required (eg in the
 287  * case of NODE_NETWORK_LIMITED where we seek out NODE_NETWORK peers
 288  * unless they set NODE_NETWORK_LIMITED and we are out of IBD, in which
 289  * case NODE_NETWORK_LIMITED suffices).
 290  *
 291  * Thus, generally, avoid calling with peerServices == NODE_NONE.
 292  */
 293 static ServiceFlags GetDesirableServiceFlags(ServiceFlags services) {
 294     return ServiceFlags(NODE_NETWORK | NODE_WITNESS);
 295 }
 296
 297 /**
 298  * A shortcut for (services & GetDesirableServiceFlags(services))
 299  * == GetDesirableServiceFlags(services), ie determines whether the given
 300  * set of service flags are sufficient for a peer to be "relevant".
 301  */
 302 static inline bool HasAllDesirableServiceFlags(ServiceFlags services) {
 303     return !(GetDesirableServiceFlags(services) & (~services));
 304 }
 305
 306 /**
 307  * Checks if a peer with the given service flags may be capable of having a
 308  * robust address-storage DB. Currently an alias for checking NODE_NETWORK.
 309  */
 310 static inline bool MayHaveUsefulAddressDB(ServiceFlags services) {
 311     return services & NODE_NETWORK;
 312 }
 313
 314 /** A CService with information about it as peer */
 315 class CAddress : public CService
 316 {
 317 public:
 318     CAddress();
 319     explicit CAddress(CService ipIn, ServiceFlags nServicesIn);
 320
 321     void Init();
 322
 323     ADD_SERIALIZE_METHODS;
 324
 325     template <typename Stream, typename Operation>
 326     inline void SerializationOp(Stream& s, Operation ser_action)
 327     {
 328         if (ser_action.ForRead())
 329             Init();
 330         int nVersion = s.GetVersion();
 331         if (s.GetType() & SER_DISK)
 332             READWRITE(nVersion);
 333         if ((s.GetType() & SER_DISK) ||
 334             (nVersion >= CADDR_TIME_VERSION && !(s.GetType() & SER_GETHASH)))
 335             READWRITE(nTime);
 336         uint64_t nServicesInt = nServices;
 337         READWRITE(nServicesInt);
 338         nServices = (ServiceFlags)nServicesInt;
 339         READWRITE(*(CService*)this);
 340     }
 341
 342     // TODO: make private (improves encapsulation)
 343 public:
 344     ServiceFlags nServices;
 345
 346     // disk and network only
 347     unsigned int nTime;
 348 };
 349
 350 /** getdata message type flags */
 351 const uint32_t MSG_WITNESS_FLAG = 1 << 30;
 352 const uint32_t MSG_TYPE_MASK    = 0xffffffff >> 2;
 353
 354 /** getdata / inv message types.
 355  * These numbers are defined by the protocol. When adding a new value, be sure
 356  * to mention it in the respective BIP.
 357  */
 358 enum GetDataMsg
 359 {
 360     UNDEFINED = 0,
 361     MSG_TX = 1,
 362     MSG_BLOCK = 2,
 363     // The following can only occur in getdata. Invs always use TX or BLOCK.
 364     MSG_FILTERED_BLOCK = 3,  //!< Defined in BIP37
 365     MSG_CMPCT_BLOCK = 4,     //!< Defined in BIP152
 366     MSG_WITNESS_BLOCK = MSG_BLOCK | MSG_WITNESS_FLAG, //!< Defined in BIP144
 367     MSG_WITNESS_TX = MSG_TX | MSG_WITNESS_FLAG,       //!< Defined in BIP144
 368     MSG_FILTERED_WITNESS_BLOCK = MSG_FILTERED_BLOCK | MSG_WITNESS_FLAG,
 369 };
 370
 371 /** inv message data */
 372 class CInv
 373 {
 374 public:
 375     CInv();
 376     CInv(int typeIn, const uint256& hashIn);
 377
 378     ADD_SERIALIZE_METHODS;
 379
 380     template <typename Stream, typename Operation>
 381     inline void SerializationOp(Stream& s, Operation ser_action)
 382     {
 383         READWRITE(type);
 384         READWRITE(hash);
 385     }
 386
 387     friend bool operator<(const CInv& a, const CInv& b);
 388
 389     std::string GetCommand() const;
 390     std::string ToString() const;
 391
 392     // TODO: make private (improves encapsulation)
 393 public:
 394     int type;
 395     uint256 hash;
 396 };
 397
 398 #endif // BITCOIN_PROTOCOL_H