BitcoinCash/specification
1
Fork 0
Code Issues Pull Requests Releases Activity

Making format documentation more consistent.

Browse Source 
Expanded upon some existing pages and populated some pages that were linked to despite not existing.
This commit is contained in:
Andrew Groot
2020-09-24 16:49:32 -04:00
committed by bitcoin
parent ae2a746a71
commit fed06d280a
13 changed files with 171 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files
protocol/formats/network-address.md
+21
View File
@@ -0,0 +1,21 @@
# Network Address
Specifies the basic information necessary to connect to a peer node.
## Format
| Field | Length | Format | Description |
|--|--|--|--|
| timestamp* | 4 bytes | unix timestamp<sup>[(LE)](/protocol/misc/endian/little)</sup> | Last known time (in seconds) that the peer was known to be "live." |
| services | 8 bytes | bitfield<sup>[(LE)](/protocol/misc/endian/little)</sup> | The services this node supports. See [Services Bitfield](/protocol/network/messages/version#services-bitfield). |
| IP address | 16 bytes | [ip address](#ip-address-format) | The IP (v4 or v6) address used to connect to the peer. |
| port | 2 bytes | unsigned integer<sup>[(BE)](/protocol/misc/endian/little)</sup> | The port used to the connect to the peer. |
\* *timestamp* is not included where network addresses appear in the [version](/protocol/network/messages/version) message format
#### IP Address Format
A single format is used to specify IPv4 and IPv6 addresses, [IPv4-mapped IPv6 addresses](https://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses):
* If the intended address is IPv6, the standard "network byte order" or [big-endian](/protocol/misc/endian/big) byte encoding is used.
* If the intended address is IPv4, the first 12 bytes are set to 0x00000000000000000000FFFF, followed by the big-endian IPv4 address.
protocol/formats/variable-length-integer.md
+40
View File
@@ -0,0 +1,40 @@
# Variable Length Integer
A variable-width data format for unsigned integers allowing a more compact representation for smaller values.
## Format
Numbers are encoded with the first rule that applies of the following:
* If the number < 253 (0xFD), store it in 1 byte, left-padded with zeros.
* If the number fits in 16 bits (but is greater than 252), store it in 3 bytes: a 1-byte value 253 (0xFD) followed by the 2 byte little-endian number.
| Byte Index | C-Style Calculation |
|-------------|------------------------|
| 0 | 0xFD |
| 1 | value & 255 |
| 2 | value >> 8 |
* If the number fits in 32 bits (but not 8 or 16), store it in 5 bytes: a 1-byte value 254 (0xFE) followed by the 4 byte little-endian number
| Byte Index | C-Style Calculation |
|-------------|------------------------|
| 0 | 0xFE |
| 1 | value & 255 |
| 2 | (value >> 8) & 255 |
| 3 | (value >> 16) & 255 |
| 4 | (value >> 24) & 255 |
* If the number fits in 64 bits (but not 8, 16, or 32), store it in 9 bytes: a 1-byte value 255 (0xFF) followed by the 8 byte little-endian number
| Byte Index | C-Style Calculation |
|-------------|------------------------|
| 0 | 0xFF |
| 1 | value & 255 |
| 2 | (value >> 8) & 255 |
| 3 | (value >> 16) & 255 |
| 4 | (value >> 24) & 255 |
| 5 | (value >> 32) & 255 |
| 6 | (value >> 40) & 255 |
| 7 | (value >> 48) & 255 |
| 8 | (value >> 56) & 255 |
protocol/formats/variable-length-string.md
+10
View File
@@ -0,0 +1,10 @@
# Variable Length String
A variable-width data format for ASCII character strings.
## Format
| Field | Length | Format | Description |
|--|--|--|--|
| character count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of ASCII characters (bytes) to follow. |
| character string | `character_count` bytes | ASCII Characters | The string of characters. |
protocol/network/messages.md
+40 -58
View File
@@ -18,13 +18,13 @@ The P2P network has a variety of message types.
All P2P messages follow a binary format with the following structure:
| Field | Length | Format |
|--|--|--|
| net magic | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> |
| command string | 12 bytes | string<sup>[(BE)](/protocol/misc/endian/big)</sup> |
| payload byte count | 4 bytes | integer<sup>[(LE)](/protocol/misc/endian/little)</sup> |
| payload checksum | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> |
| payload | variable | |
| Field | Length | Format | Description |
|--|--|--|--|
| net magic | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> | See [net magic](#net-magic). |
| command string | 12 bytes | string<sup>[(BE)](/protocol/misc/endian/big)</sup> | See [command string](#command-string).
| payload byte count | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The size of the payload. The total max size of any message is `268,435,456` bytes (256 MiB), and the header for a message is always 24 bytes, therefore the max value of the payload byte count is `268,435,432` bytes, while the min value is zero (indicating no additional payload). |
| payload checksum | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> | The message checksum is the first 4 bytes of a double-sha256 hash of the payload. |
| payload | variable | message-specific | See [message types](#message-types) for links to message-specific page, which describe the payload for each message. |
### Net Magic
@@ -44,51 +44,49 @@ Commands that are shorter than 12 bytes are right-padded with null bytes (`0x00`
The command string is used to determine the type of message being transmitted.
Messages with an unrecognized `command string` are ignored by most implementations but may result in a ban by implementations that diverge from the Satoshi-client defacto standard.
The following messages are considered standard by all node implementations.
(TODO: the protocol is versioned, commands are introduced at certain versions, the previous line is ignoring this.
TODO: saying something is "standard" doesn't mean much in terms of spec. Is there an obligation to implement them?)
### Message Types
#### Announcements
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
| [filteradd](/protocol/network/messages/filteradd) | *Adds a single item into an installed filter* | all
| [filterclear](/protocol/network/messages/filterclear) | *Removes an installed filter* | all
| [filterload](/protocol/network/messages/filterload) | *Inserts a transaction and merkle block filter into the peer* | all
| [inv](/protocol/network/messages/inv) | *Notifies peers about the existence of some information (generally a block or transaction)* | all
| [xupdate](/protocol/network/messages/xupdate) | *Communicates a change in peer capabilities* | BCHUnlimited
| Command String | Synopsis |
| -- | -- |
| [filteradd](/protocol/network/messages/filteradd) | *Adds a single item into an installed filter* |
| [filterclear](/protocol/network/messages/filterclear) | *Removes an installed filter* |
| [filterload](/protocol/network/messages/filterload) | *Inserts a transaction and merkle block filter into the peer* |
| [inv](/protocol/network/messages/inv) | *Notifies peers about the existence of some information (generally a block or transaction)* |
#### Requests
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
| [feefilter](/protocol/network/messages/feefilter) | *Requests that transactions without sufficient fees are not relayed* | all
| [getaddr](/protocol/network/messages/getaddr) | *Requests a list of active peers* | all
| [getblocks](/protocol/network/messages/getblocks) | *Requests block hash identifiers* | all |
| [getdata](/protocol/network/messages/getdata) | *Requests information from a peer* | all |
| [getheaders](/protocol/network/messages/getheaders) | *Requests block headers from a peer* | all |
| [ping](/protocol/network/messages/ping) | *Requests a confirmation (pong) that the peer is still active* | all |
| [sendheaders](/protocol/network/messages/sendheaders) | *Requests that new blocks are sent as headers instead of hashes* | all
| [version](/protocol/network/messages/version) | *Describes peer capabilities* | all
| [xversion](/protocol/network/messages/xversion) | *Describes peer capabilities in an extensible manner* | BCHUnlimited
| Command String | Synopsis |
| -- | -- |
| [feefilter](/protocol/network/messages/feefilter) | *Requests that transactions without sufficient fees are not relayed* |
| [getaddr](/protocol/network/messages/getaddr) | *Requests a list of active peers* |
| [getblocks](/protocol/network/messages/getblocks) | *Requests block hash identifiers* |
| [getdata](/protocol/network/messages/getdata) | *Requests information from a peer* |
| [getheaders](/protocol/network/messages/getheaders) | *Requests block headers from a peer* |
| [ping](/protocol/network/messages/ping) | *Requests a confirmation (pong) that the peer is still active* |
| [sendheaders](/protocol/network/messages/sendheaders) | *Requests that new blocks are sent as headers instead of hashes* |
| [version](/protocol/network/messages/version) | *Describes peer capabilities* |
#### Responses
| Command String | Synopsis |
| -- | -- |
| [addr](/protocol/network/messages/addr) | *Provides a peer with the addresses of other peers* |
| [block](/protocol/network/messages/block) | *Provides the contents of a block* |
| [headers](/protocol/network/messages/headers) | *Provides a set of block headers (unsolicited or GETHEADERS response)* |
| [notfound](/protocol/network/messages/notfound) | *Indicates that a requested resource could not be relayed* |
| [merkleblock](/protocol/network/messages/merkleblock) | *Provides a provable subset of a block's transactions, as filtered by FILTERADD* |
| [pong](/protocol/network/messages/pong) | *Reply to a ping message* |
| [reject](/protocol/network/messages/reject) | *Response by well-behaved clients if a message cannot be handled* |
| [tx](/protocol/network/messages/tx) | *Provides a transaction* |
| [verack](/protocol/network/messages/verack) | *Response to a [version](/protocol/network/messages/version) message* |
#### Other Message Types (Extensions)
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
| [addr](/protocol/network/messages/addr) | *Provides a peer with the addresses of other peers* | all
| [block](/protocol/network/messages/block) | *Provides the contents of a block* | all
| [headers](/protocol/network/messages/headers) | *Provides a set of block headers (unsolicited or GETHEADERS response)* | all |
| [notfound](/protocol/network/messages/notfound) | *Indicates that a requested resource could not be relayed* | all
| [merkleblock](/protocol/network/messages/merkleblock) | *Provides a provable subset of a block's transactions, as filtered by FILTERADD* | all |
| [pong](/protocol/network/messages/pong) | *Reply to a ping message* | all |
| [reject](/protocol/network/messages/reject) | *Response by well-behaved clients if a message cannot be handled* | all
| [tx](/protocol/network/messages/tx) | *Provides a transaction* | all
| [verack](/protocol/network/messages/verack) | *Response to a [version](/protocol/network/messages/version) message* | all
| [xversion](/protocol/network/messages/xversion) | *Describes peer capabilities in an extensible manner* | BCHUnlimited
| [xverack](/protocol/network/messages/xverack) | *Response to an [xversion](/protocol/network/messages/xversion) message* | BCHUnlimited
The following messages are well known, but not implemented by all node implementations.
| Command String | Synopsis | Supported Implementations
| -- | -- | -- |
| [xupdate](/protocol/network/messages/xupdate) | *Communicates a change in peer capabilities* | BCHUnlimited
| get_xblocktx | | |
| get_xthin | | |
| mempool | |
@@ -97,22 +95,6 @@ The following messages are well known, but not implemented by all node implement
| xblocktx | | |
| xthinblock | | |
### Payload Byte Count
The payload byte count is the size of the payload, encoded as a [little-endian](/protocol/misc/endian/little) 4-byte integer.
The total max size of any message is `268,435,456` bytes (256 MiB), and the header for a message is always 24 bytes, therefore the max value of the payload byte count is `268,435,432` bytes.
The payload byte count may be zero, but must not be negative.
### Payload Checksum
The message checksum is the first 4 bytes of a double-sha256 hash of the payload.
The checksum is transmitted as a byte array, and is encoded as [big-endian](/protocol/misc/endian/big).
### Payload
The message payload is defined by the message type.
# Example message
# Node Specific Behavior
protocol/network/messages/addr.md
+3 -16
View File
@@ -5,25 +5,12 @@
# Response: Addresses ("addr")
Provide information about other prospective P2P protocol peers. Peers SHOULD not send this message unsolicited (see [getaddr](/protocol/network/messages/getaddr)), and nodes that receive an unsolicited ADDR message MUST ignore it. This behavior helps prevent eclipse and partitioning attacks by not allowing an attacker to aggressively seed peer connection tables with its own nodes.
Provide information about other prospective P2P protocol peers. Peers SHOULD not send this message unsolicited (see [getaddr](/protocol/network/messages/getaddr)), and nodes that receive an unsolicited addr message MUST ignore it. This behavior helps prevent eclipse and partitioning attacks by not allowing an attacker to aggressively seed peer connection tables with its own nodes.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| vector length N | variable | [compact int](/protocol/p2p/compact__int.md) | The following fields are repeated N times |
| time 0 | 4 bytes | unsigned int<sup>[(LE)](/protocol/misc/endian/little)</sup> | last known alive time |
| services 0 | 8 bytes | unsigned int<sup>[(LE)](/protocol/misc/endian/little)</sup> bit field | the services this node supports |
| IP address 0 | 16 bytes | bytes | connect using this IP address
| port 0 | 2 bytes | unsigned integer<sup>[(BE)](/protocol/misc/endian/little)</sup> | connect using this IP port
| ... |
| time N, etc
| peer count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of peers whose connection information is being sent in this message. |
| peer network addresses | `peer_count` * 30 | `peer_count` [network addresses](/protocol/formats/network-address) | The peer information for each of the peers being transmitted. |
*services* is a bit field describing supported functionality, that is also used in the [version](/protocol/p2p/version) message. See [services field](/protocol/p2p/services__field) for bit definitions.
*time* is a 4 byte unsigned little-endian integer denoting the last time in epoch seconds that this node was known to be "live".
*IP address* is the IPv4 or IPv6 address of the prospective node.
*port* is the IP port of the prospective node, serialized as an unsigned 2 byte big-endian value.
protocol/network/messages/block.md
+1 -1
View File
@@ -13,5 +13,5 @@ Provides the contents of a block.
| hash target | 4 bytes | [compressed target](/protocol/blockchain/block/block-header#compressed-target-format) | The target that the hash of this block is expected to satisfy. See [Target](/protocol/blockchain/proof-of-work#target). |
| nonce | 4 bytes | bytes | Nonce used to update the block hash during mining. See [Proof of Work](/protocol/blockchain/proof-of-work). |
| transaction count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of transactions in the block (and therefore following in this message). |
| transactions | variable | &lt;transaction_count&gt; [transactions](/protocol/network/messages/tx#message-format) | The transactions contained within this block, formatted the same way they are in a [tx](/protocol/network/messages/tx) message. |
| transactions | variable | `transaction_count` [transactions](/protocol/network/messages/tx#message-format) | The transactions contained within this block, formatted the same way they are in a [tx](/protocol/network/messages/tx) message. |
protocol/network/messages/filteradd.md
+4 -3
View File
@@ -9,8 +9,9 @@ Add an entry into the installed bloom filter.
## Message Format
| compact int | N bytes |
|-------------|---------|
|[vector](/protocol/p2p/vector) size N of| data
| Field | Length | Format | Description |
|--|--|--|--|
| data length | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the piece of the data to be added to the bloom filter. |
| data | `data_length` bytes | bytes | The raw data of the object to the be added. |
*data* is inserted into the bloom filter, exactly as if the [insert](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/eb264e627e231f7219e60eef41b4e37cc52d6d9d/src/bloom.cpp#L116) operation had been called locally before sending the filter.
protocol/network/messages/filterload.md
+7 -6
View File
@@ -9,7 +9,7 @@ Inserts a transaction and merkle block filter into the peer, overwriting any exi
### Effect on Transactions
This message installs a bloom filter into the peer. Subsequent INV notifications and MERKLEBLOCK messages only provide transactions that in match this bloom filter in some manner. The following items in a transaction are checked against the bloom filter:
This message installs a bloom filter into the peer. Subsequent [inv](/protocol/network/messages/inv) and [merkleblock](/protocol/network/messages/merkleblock) messages only provide transactions that in match this bloom filter in some manner. The following items in a transaction are checked against the bloom filter:
- The transaction hash
- Each data field in every [output script](/glossary/output__script.md) in the transaction
@@ -22,16 +22,17 @@ See [CBloomFilter::MatchAndInsertOutputs](https://github.com/BitcoinUnlimited/Bi
### Effect on Merkle Blocks
If a [filtered block](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/protocol.h#L483) is requested via in [INV](/protocol/network/messages/inv.md) message, the installed bloom filter is used to choose which transactions are included in the response using the same matching algorithm as described above for transaction INVs.
If a [filtered block](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/protocol.h#L483) is requested via an inventory message, the installed bloom filter is used to choose which transactions are included in the response using the same matching algorithm as described above for transaction inventories.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| [vector](/protocol/p2p/vector.md) of bytes | up to 36000 bytes | bit vector | bloom filter data |
| num hash funcs | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | number of hash functions used when generating this filter (max 50) |
| tweak | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | arbitrary number that uniquifies this bloom filter |
flags | 1 byte | bit field | bloom filter flags
| bloom filter size | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the bloom filter to be used. |
| bloom filter data | variable | `bloom_filter_size` bytes | Raw bloom filter data (up to 36,000 bytes). |
| number of hash functions | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The number of hash functions used when generating this filter (max 50). |
| tweak | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | Arbitrary number that helps randomize this bloom filter. |
| flags | 1 byte | bit field | See [bloom filter flags](#bloom-filter-flags). |
### Bloom Filter Flags
protocol/network/messages/getdata.md
+4 -17
View File
@@ -5,28 +5,15 @@
# Request: Get Data (“getdata”)
Requests information (generally previously announced via an INV) from a peer.
A GETDATA request is a [vector](/protocol/p2p/vector.md) of INV-formatted data.
Requests information (generally previously announced via an [inv](/protocol/network/messages/inv) message) from a peer.
As such, a getdata request carries the same general format as an inventory message and is used to request any items that the node was previously unaware.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| vector length N | variable | compact int | number of items |
| item 0 type | 4 bytes | unsigned int<sup>[(LE)](/protocol/misc/endian/little)</sup> | type of the requested object |
| item 0 hash | 32 bytes | bytes | hash of the requested object |
| ... | | | |
| item N-1 type |
| item N-1 hash
### Type
The type of the desired object. See [INV](/protocol/network/messages/inv.md) for specific values
### Hash
The [hash identifier](glossary/hash__identifier) of the desired object.
| inventory count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of inventory items being requested in this message. |
| inventory items | `inventory_count` * 36 bytes | `inventory_count` [inventory items](/protocol/network/messages/inv#inventory-item-format) | The set of inventory items being requested. |
## Server Implementations
protocol/network/messages/inv.md
+2 -2
View File
@@ -24,8 +24,8 @@ NOTE: Since a block header is a relatively small data structure, and block propa
| Field | Length | Format | Description |
|--|--|--|--|
| type | 4 bytes | [inventory type](#inventory-types) | Indicates what the following hash represents. |
| item hash | 32 bytes | bytes | The [hash](/protocol/blockchain/hash) that identifies the item. |
| type | 4 bytes | [inventory type](#inventory-types)<sup>[(LE)](/protocol/misc/endian/little)</sup> | Indicates what the following hash represents. |
| item hash | 32 bytes | bytes<sup>[(LE)](/protocol/misc/endian/little)</sup> | The [hash](/protocol/blockchain/hash) that identifies the item. |
#### Inventory Types
The type of the object that is available.
protocol/network/messages/merkleblock.md
+18 -6
View File
@@ -5,14 +5,26 @@
# Response: Merkle Block ("merkleblock")
*Provides a block header and partial merkle proof tree to show that selected transaction ids exist in the block.*
Provides a block header and partial merkle proof tree to show that the selected transaction [hashes](/protocol/blockchain/hash) exist in the block.
Transactions are selected by honest servers if they match the bloom filter installed by the client. However, note that servers can omit transactions and this cannot be detected except by receiving a MERKLEBLOCK message from an honest server.
Transactions are selected by honest servers if they match the bloom filter installed by the client. However, note that servers can omit transactions and this cannot be detected except by receiving a merkleblock message from an honest server.
All selected transactions are subsequently sent as separate TX messages. Due to multi-threading on the server, clients should not assume that these TX messages directly follow the MERKLEBLOCK message.
All selected transactions are subsequently sent as separate [tx](/protocol/network/messages/tx) messages. Due to multi-threading on the server, clients should not assume that these transaction messages directly follow the merkleblock message.
## Message Format
| ... | 4 bytes | ... | ...|
|----|---------------|-----------|------------|
| [block header](/protocol/blockchain/block/block-header.md)| # tx in block | [vector](/protocol/p2p/vector) of 32 byte hashes | [vector](/protocol/p2p/vector) of bytes that define the merkle block traversal
| Field | Length | Format | Description |
|--|--|--|--|
| block header | 80 bytes | [block header](/protocol/blockchain/block/block-header#block-header-format) | The header of the block. |
| transaction count | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The number of transactions in the block. |
| filtered transaction count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of transactions matching the client's bloom filter. |
| transaction hashes | `transaction_count` * 32 bytes | bytes<sup>[(LE)](/protocol/misc/endian/little)</sup> | The hashes of the full set of transactions in the block, in the the order they appear in the block (i.e. depth-first order with respect to the merkle tree). |
| flag byte count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of flags bytes to follow. |
| flag bits | `flag_count` bytes | bytes | Flag bits, collected into bytes (zero-padded to a full byte as necessary) indicating inclusion information with respect to traversal of the partial merkle tree of matches. See [partial merkle tree flag bits](#partial-merkle-tree-flag-bits). |
#### Partial Merkle Tree Flag Bits
The partial merkle tree flag bits effectively create a variable-width bitfield, indicating which transaction hashes from the block the merkleblock message pertains to actually matched the client's bloom filter.
If you picture the merkle tree root at the top, the flag bits represent a top-down yes/no approach to whether the a given branch (or leaf node) of the tree includes any matching transactions.
For full details, see [BIP-37: Partial Merkle Branch Format](/protocol/forks/bip-0037#partial-merkle-branch-format).
protocol/network/messages/reject.md
+16 -16
View File
@@ -3,29 +3,29 @@
"related":["/protocol"]
}</div>
*Notifies peer that a message is invalid*
# Response: Reject ("reject")
Notifies peer that a received message is invalid.
| [compact int](/protocol/p2p/compact__int.md) N (max 12) | N bytes | 1 byte | [compact int](/protocol/p2p/compact__int.md) M (max 111) | M bytes |
|----------------|---------|-------------|---------------|---------|
| command length | command | error code | reason length | reason string |
## Message Format
*command length* and *command* form a [vector](/protocol/p2p/vector.md) of bytes that identify the type of the problem message. These bytes (less padded nulls) match the *command* field in the protocol [message envelope](/protocol.md).
| Field | Length | Format | Description |
|--|--|--|--|
| rejected message type | variable | [variable length string](/protocol/formats/variable-length-string) | The [command string](/protocol/network/messages#command-string) of the message that is being rejected (e.g. "tx"). |
| rejection code | 1 byte | [rejection code](#rejection-codes) | A code indicating why the message was rejected. |
| rejection reason* | variable | [variable length string](/protocol/formats/variable-length-string) | A description of why the message was rejected. |
*reason length* and *reason string* form a [vector](/protocol/p2p/vector.md) of bytes that is a string providing a human language explanation of the reason the message was rejected. This string is subject to change so client software **SHOULD NOT** use it programatically.
\* *rejection reason* is a string providing a human language explanation of the reason the message was rejected. This string is subject to change so client software **SHOULD NOT** use it programmatically.
*error code* provides a succinct machine-interpretable reason why the message was rejected.
#### Rejection Codes
### Reject Error Codes
| Name | Value | Response To | Description
| Name | Value | Response To | Description |
|-------------|-------|---------------|-----------|
| REJECT_MALFORMED | 0x01 | any | message cannot be deserialized |
| REJECT_INVALID | 0x10 | BLOCK, TX, FILTERSIZEXTHIN | block or transaction is invalid, or xthin filter size is too small |
| REJECT_MALFORMED | 0x01 | any | Message cannot be deserialized. |
| REJECT_INVALID | 0x10 | BLOCK, TX, FILTERSIZEXTHIN | Block or transaction is invalid, or xthin filter size is too small |
| REJECT_OBSOLETE | 0x11 | VERSION | This node no longer supports your client protocol version |
| REJECT_DUPLICATE | 0x12 | unused | |
| REJECT_NONSTANDARD | 0x40 | TX | Transaction is [non-standard](/standard__transactions.md), or [not final](/final__transactions.md) as per BIP68 |
| REJECT_DUST | 0x41 | TX | Transaction has an output that is too small |
| REJECT_INSUFFICIENTFEE | 0x42 | TX | Transaction does not pay enough to be relayed |
| REJECT_NONSTANDARD | 0x40 | TX | Transaction is [non-standard](/protocol/blockchain/transaction-validation/network-level-validation-rules#standard-transactions), or not final as per [BIP68](/protocol/forks/bip-0068). |
| REJECT_DUST | 0x41 | TX | Transaction has an output that is too small. |
| REJECT_INSUFFICIENTFEE | 0x42 | TX | Transaction does not pay enough in fees to be relayed. |
| REJECT_CHECKPOINT | 0x43 | unused | |
| REJECT_WAITING | 0x44 | TX | This transaction is [not final](/final__transactions.md) |
protocol/network/messages/version.md
+4 -4
View File
@@ -1,7 +1,7 @@
# Handshake: Version (“version”)
The version message is a part of the node connection [handshake](/protocol/network/node-handshake) and indicates various connection settings, networking information, and the services provided by the sending node (see Services Bitmask [below](#services-bitmask)).
The version message is a part of the node connection [handshake](/protocol/network/node-handshake) and indicates various connection settings, networking information, and the services provided by the sending node (see Services Bitfield [below](#services-bitfield)).
The node connection is not considered established until both nodes have sent and received both a `version` and [verack](/protocol/network/messages/verack) message.
@@ -10,7 +10,7 @@ The node connection is not considered established until both nodes have sent and
| Field | Length | Format | Description |
|--|--|--|--|
| version number | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The version number supported by the sending node. |
| services | 8 bytes | bitmask<sup>[(LE)](/protocol/misc/endian/little)</sup> | An indication of the services supported by the sending node. See Services Bitmask section below. |
| services | 8 bytes | bitfield<sup>[(LE)](/protocol/misc/endian/little)</sup> | An indication of the services supported by the sending node. See Services Bitfield section below. |
| timestamp | 8 bytes | unix timestamp<sup>[(LE)](/protocol/misc/endian/little)</sup> | The time the message was generated on the sending node. |
| remote address | 26 bytes | [network address](/protocol/formats/network-address) | The network address of the remote node. <p>_NOTE: this does not contain the timestamp normally included with network addresses._</p> |
| local address | 26 bytes | [network address](/protocol/formats/network-address) | The network address of the sending node. <p>_NOTE: this does not contain the timestamp normally included with network addresses._</p> |
@@ -30,11 +30,11 @@ Modern Nodes ignore extra data after the `relay flag`.
The most recent version of the network protocol is `70015`.
The `version` value often correlates to new behavior, parsing formats, and available services; for more details review the network protocol's [version history](/history/protocol-version).
Nodes should use `version` and the `services` bitmask to determine if the node should accept the incoming connection.
Nodes should use `version` and the `services` bitfield to determine if the node should accept the incoming connection.
Related: [node connection handshake](/protocol/network/node-handshake).
## Services Bitmask
## Services Bitfield
The services field is an 8 byte little-endian-serialized bitfield that described peer capabilities.
The following capabilities are defined, by bit position: