Dev Docs: Describe Almost All Remaining P2P Network Messages

* Describes all remaining messages except filterload. Specificially, the
  following messages are described: Addr, Alert, FilterAdd, FilterClear,
  GetAddr, Ping, Pong, Reject, VerAck, and Version

* New makefile test: report broken markdown tables

* Put relevant protocol version changes at the top of all message
  subsections.
This commit is contained in:
David A. Harding 2014-10-28 14:28:14 -04:00
parent e29104fb82
commit a149ae1f37
No known key found for this signature in database
GPG key ID: 4B29C30FF29EC4B7
8 changed files with 650 additions and 19 deletions

View file

@ -37,7 +37,8 @@ pre-build-tests-fast: check-for-non-ascii-urls
## Post-build tests which, aggregated together, take less than 5 seconds to run on a typical PC
post-build-tests-fast: check-for-build-errors ensure-each-svg-has-a-png check-for-liquid-errors \
check-for-missing-anchors check-for-broken-markdown-reference-links
check-for-missing-anchors check-for-broken-markdown-reference-links \
check-for-broken-kramdown-tables
## All pre-build tests, including those which might take multiple minutes
pre-build-tests: pre-build-tests-fast
@ -107,3 +108,9 @@ check-for-non-ascii-urls:
; do grep -H . $$file | sed -n -e '/url:/,$$p' \
| grep -P '[^\x00-\x7f]|[a-z\-] [a-z\-]' \
; done | eval $(ERROR_ON_OUTPUT)
check-for-broken-kramdown-tables:
## Kramdown tables are easy to break. When broken, they produce a
## paragraph starting with a | (pipe). I can't imagine any reason we'd
## have a regular paragraph starting with a pipe, so error on any occurences.
$S grep '<p>|' _site/en/developer-* | eval $(ERROR_ON_OUTPUT)

View file

@ -6,9 +6,12 @@
## To prevent a ref for term, use: "term: DO NOT AUTOCROSSREF"
51 percent attack:
'`addr`': addr message
'`addr` message': addr message
'`addr` messages': addr message
address:
addresses: address
'`alert` message': alert message
'`alert` messages': alert message
'`amount`': pp amount
base-58: base58check
base58: base58check
@ -26,6 +29,7 @@ block-chain: block chain
block header:
block height:
'`block` message': block message
'`block` messages': block message
block reward:
block time:
block version:
@ -79,17 +83,27 @@ extended keys: extended key
extended private key:
extended public key:
fiat:
'`filteradd` message': filteradd message
'`filteradd` messages': filteradd message
'`filterclear` message': filterclear message
'`filterclear` messages': filterclear message
fork:
forks: fork
'`getblocks` message': getblocks message
'`getdata` message': getdata message
'`getheaders` message': getheaders message
genesis block:
'`getblocks` message': getblocks message
'`getblocks` messages': getblocks message
'`getdata` message': getdata message
'`getdata` messages': getdata message
'`getheaders` message': getheaders message
'`getheaders` messages': getheaders message
'`getaddr` message': getaddr message
'`getaddr` messages': getaddr message
hard fork:
hard forks: hard fork
hardened extended private key:
HD protocol:
'`headers` message': headers message
'`headers` messages': headers message
high-priority transaction: high-priority transactions
high-priority transactions:
inputs: input
@ -98,8 +112,13 @@ intermediate certificate:
intermediate certificates: intermediate certificate
internal byte order:
'`inv` message': inv message
'`inv` messages': inv message
IP address: DO NOT AUTOCROSSREF
IP addresses: DO NOT AUTOCROSSREF
IPv4 address: DO NOT AUTOCROSSREF
IPv4 addresses: DO NOT AUTOCROSSREF
IPv6 address: DO NOT AUTOCROSSREF
IPv6 addresses: DO NOT AUTOCROSSREF
inventories: inventory
inventory:
key index:
@ -115,12 +134,15 @@ master chain code:
master private key:
'`memo`': pp memo
'`mempool` message': mempool message
'`mempool` messages': mempool message
'`message`': message
message header:
message headers: message header
message payload:
'`merchant_data`': pp merchant data
merkleblock: merkleblock message
'`merkleblock` message': merkleblock message
'`merkleblock` messages': merkleblock message
merkle root:
merkle tree:
merge:
@ -141,6 +163,7 @@ multisig:
nbits:
network:
'`notfound` message': notfound message
'`notfound` messages': notfound message
null data:
'`op_checkmultisig`': op_checkmultisig
'`op_checksig`': op_checksig
@ -172,15 +195,23 @@ peer:
peers: peer
peer-to-peer: network
peer-to-peer network: network
'`ping` message': ping message
'`ping` messages': ping message
pki:
'`pki_type`': pp pki type
'`point()`': point function
'`pong` message': pong message
'`pong` messages': pong message
private key:
private keys: private key
proof of work:
proof-of-work: proof of work
protocol buffer: protobuf
protocol buffers: protobuf
protocol version 106: section protocol versions
protocol version 209: section protocol versions
protocol version 311: section protocol versions
protocol version 31402: section protocol versions
protocol version 60000: section protocol versions
protocol version 60001: section protocol versions
protocol version 60002: section protocol versions
@ -208,6 +239,8 @@ refund:
refunds: refund
regression test mode:
regtest: regression test mode
'`reject` message': reject message
'`reject` messages': reject message
root certificate:
root seed:
RPCs: rpc
@ -253,6 +286,7 @@ transaction object format:
transaction version number:
'`transactions`': pp transactions
'`tx` message': tx message
'`tx` messages': tx message
txid:
txids: txid
unconfirmed:
@ -263,8 +297,12 @@ unique address: unique addresses
unique addresses:
utxo:
utxos: utxo
'`verack` message': verack message
'`verack` messages': verack message
verified payments:
version 2 blocks: v2 block
'`version` message': version message
'`version` messages': version message
wallet:
wallets: wallet
wallet import format:
@ -272,13 +310,17 @@ x.509: x509
X509Certificates:
## BIPs in numerical order; don't use padding zeros (e.g. BIP70 not BIP0070)
BIP14:
BIP16:
BIP21:
BIP30:
BIP31:
BIP32:
BIP34:
BIP37:
BIP39:
BIP50:
BIP61:
BIP62:
BIP70:
BIP71:
@ -364,6 +406,10 @@ CVE-2012-2459:
'`walletpassphrasechange`': rpc walletpassphrasechange
## Versions of Bitcoin Core (linked to Bitcoin.org release notes)
Bitcoin Core 0.1.6:
Bitcoin Core 0.2.9:
Bitcoin Core 0.3.11:
Bitcoin Core 0.3.15:
Bitcoin Core 0.6.0:
Bitcoin Core 0.6.1:
Bitcoin Core 0.7.0:

View file

@ -64,7 +64,7 @@ blocks. For this reason, programs should not rely on DNS seeds
exclusively.
Once a program has connected to the network, its peers can begin to send
it [`addr`][addr message]{:#term-addr-message}{:.term}
it `addr`
(address<!--noref-->) messages with the IP addresses and port numbers of
other peers on the network, providing a fully decentralized method of
peer discovery. Bitcoin Core keeps a record of known peers in a

View file

@ -51,16 +51,21 @@ and testnet.
{% autocrossref %}
The table below lists some notable versions of the P2P network protocol,
with the most recent versions listed first. (If you would like to help
document older protocol versions, please [open an issue][docs issue].)
with the most recent versions listed first. (If you know of a protocol
version that implemented a major change but which is not listed here,
please [open an issue][docs issue].)
| Version | Implementation | Major Changes
|---------|------------------------------------|--------------
| 70002 | Bitcoin Core 0.9.0 <br>(Mar 2014) | • Send multiple `inv` messages in response to a `mempool` message if necessary <br><br>[BIP61][]: <br>• Added `reject` message
| 70001 | Bitcoin Core 0.8.0 <br>(Feb 2013) | [BIP37][]: <br>• Added `filterload` message. <br>• Added `filteradd` message. <br>• Added `filterclear` message. <br>• Added `merkleblock` message. <br>• Added relay field to `version` message <br>• Added `MSG_FILTERED_BLOCK` inventory type to `getdata` message.
| 70001 | Bitcoin Core 0.8.0 <br>(Feb 2013) | • Added `notfound` message. <br><br>[BIP37][]: <br>• Added `filterload` message. <br>• Added `filteradd` message. <br>• Added `filterclear` message. <br>• Added `merkleblock` message. <br>• Added relay field to `version` message <br>• Added `MSG_FILTERED_BLOCK` inventory type to `getdata` message.
| 60002 | Bitcoin Core 0.7.0 <br>(Sep 2012) | [BIP35][]: <br>• Added `mempool` message. <br>• Extended `getdata` message to allow download of memory pool transactions
| 60001 | Bitcoin Core 0.6.1 <br>(May 2012) | [BIP31][]: <br>• Added `pong` message
| 60001 | Bitcoin Core 0.6.1 <br>(May 2012) | [BIP31][]: <br> Added nonce field to `ping` message <br> Added `pong` message
| 60000 | Bitcoin Core 0.6.0 <br>(Mar 2012) | [BIP14][]: <br>• Separated protocol version from Bitcoin Core version
| 31402 | Bitcoin Core 0.3.15 <br>(Oct 2010) | • Added time field to `addr` message.
| 311 | Bitcoin Core 0.3.11 <br>(Aug 2010) | • Added `alert` message.
| 209 | Bitcoin Core 0.2.9 <br>(May 2010) | • Added checksum field to message headers.
| 106 | Bitcoin Core 0.1.6 <br>(Oct 2009) | • Added receive IP address fields to `version` message.
{% endautocrossref %}
@ -68,6 +73,8 @@ document older protocol versions, please [open an issue][docs issue].)
{% autocrossref %}
*Added checksum field in protocol version 209.*
All messages in the network protocol use the same container format,
which provides a required multi-field header and an optional payload.
The header format is:
@ -77,7 +84,7 @@ The header format is:
| 4 | start string | char[4] | Magic bytes indicating the originating network; used to seek to next message when stream state is unknown.
| 12 | command name | char[12] | ASCII string which identifies what message type is contained in the payload. Followed by nulls (0x00) to pad out byte count; for example: `version\0\0\0\0\0`.
| 4 | payload size | uint32_t | Number of bytes in payload. The current maximum number of bytes ([`MAX_SIZE`][max_size]) allowed in the payload by Bitcoin Core is 32 MiB---messages with a payload size larger than this will be dropped or rejected.
| 4 | checksum | char[4] | First 4 bytes of SHA256(SHA256(payload)) in internal byte order.<br /><br /> If payload is empty, as in `verack` and `getaddr` messages, the checksum is always 0x5df6e0e2 (SHA256(SHA256(\<empty string>))).<br /><br /> *The checksum field was introduced in protocol version 209; Bitcoin Core 0.2.9, May 2010.*
| 4 | checksum | char[4] | First 4 bytes of SHA256(SHA256(payload)) in internal byte order.<br /><br /> If payload is empty, as in `verack` and `getaddr` messages, the checksum is always 0x5df6e0e2 (SHA256(SHA256(\<empty string>))).<br /><br /> *The checksum field was introduced in protocol version 209.*
The following example is an annotated hex dump of a mainnet message
header from a `verack` message which has no payload.
@ -294,13 +301,13 @@ a055aaf1d872e94ae85e9817b2c68dc7 ... Hash (TXID)
{% autocrossref %}
*Added in protocol version 60002.*
The `mempool` message requests the TXIDs of transactions that the
receiving node has verified as valid but which have not yet appeared in
a block. That is, transactions which are in the receiving node's memory
pool. The response to the `mempool` message is one or more `inv`
messages containing the TXIDs in the usual inventory format. The
`mempool` message was introduced in protocol version 60002 as
implemented in Bitcoin Core 0.7.0 (September 2012).
messages containing the TXIDs in the usual inventory format.
Sending the `mempool` message is mostly useful when a program first
connects to the network. Full nodes can use it to quickly gather most or
@ -342,15 +349,13 @@ section][message header] for an example of a message without a payload.
{% autocrossref %}
*Added in protocol version 70001 as described by BIP37.*
The `merkleblock` message is a reply to a `getdata` message which
requested a block using the inventory type `MSG_MERKLEBLOCK`. It is
only part of the reply: if any matching transactions are found, they will
be sent separately as `tx` messages.
This message is part of the bloom filters described in BIP37, added in
protocol version 70001 and implemented in Bitcoin Core 0.8.0
(February 2013).
If a filter has been previously set with the `filterload` message, the
`merkleblock` message will contain the TXIDs of any transactions in the
requested block that matched the filter, as well as any parts of the
@ -525,6 +530,8 @@ template near the beginning of this subsection.
{% autocrossref %}
*Added in protocol version 70001.*
The `notfound` message is a reply to a `getdata` message which
requested an object the receiving node does not have available for
relay. (Nodes are not expected to relay historic transactions which
@ -562,3 +569,440 @@ transaction section][raw format].
{% endautocrossref %}
### Control Messages
{% autocrossref %}
The following network messages all help control the connection between
two peers or allow them to advise each other about the rest of the
network.
![Overview Of P2P Protocol Control And Advisory Messages](/img/dev/en-p2p-control-messages.svg)
Note that almost none of the control messages are authenticated in any
way, meaning they can contain incorrect or intentionally harmful
information. In addition, this section does not yet cover P2P protocol
operation over the [Tor network][tor]; if you would like to contribute
information about Tor, please [open an issue][docs issue].
{% endautocrossref %}
#### Addr
{% autocrossref %}
*Time field added in protocol version 31402.*
The `addr` (IP address) message relays connection information
for peers on the network. Each peer which wants to accept incoming
connections creates an `addr` message providing its connection
information and then sends that message to its peers unsolicited. Some
of its peers send that information to their peers (also unsolicited),
some of which further distribute it, allowing decentralized peer
discovery for any program already on the network.
An `addr` message may also be sent in response to a `getaddr` message.
| Bytes | Name | Data Type | Description
|------------|------------------|--------------------|----------------
| *Varies* | IP address count | compactSize uint | The number of IP address entries up to a maximum of 1,000.
| *Varies* | IP addresses | network IP address | IP address entries. See the table below for the format of a Bitcoin network IP address.
Each encapsulated network IP address currently uses the following structure:
| Bytes | Name | Data Type | Description
|-------|------------|-----------|---------------
| 4 | time | uint32 | A time in Unix epoch time format. Nodes advertising their own IP address set this to the current time. Nodes advertising IP addresses they've connected to set this to the last time they connected to that node. Other nodes just relaying the IP address should not change the time. Nodes can use the time field to avoid relaying old `addr` messages. <br><br>Malicious nodes may change times or even set them in the future. <br><br>The time field was added in protocol version 31402 .
| 8 | services | uint64_t | The services the node advertised in its `version` message.
| 16 | IP address | char | IPv6 address in **big endian byte order**. IPv4 addresses can be provided as [IPv4-mapped IPv6 addresses][]
| 2 | port | uint16_t | Port number in **big endian byte order**. Note that Bitcoin Core will only connect to nodes with non-standard port numbers as a last resort for finding peers. This is to prevent anyone from trying to use the network to disrupt non-Bitcoin services that run on other ports.
The following annotated hexdump shows part of an `addr` message. (The
message header has been omitted and the actual IP address has been
replaced with a [RFC5737][] reserved IP address.)
{% highlight text %}
fde803 ............................. Address count: 1000
d91f4854 ........................... Epoch time: 1414012889
0100000000000000 ................... Service bits: 01 (network node)
00000000000000000000ffffc0000233 ... IP Address: ::ffff:192.0.2.51
208d ............................... Port: 8333
[...] .............................. (999 more addresses omitted)
{% endhighlight %}
{% endautocrossref %}
#### Alert
{% autocrossref %}
*Added in protocol version 311.*
The `alert` message warns nodes of problems that may affect them or the
rest of the network. Each `alert` message is signed using a key controlled
by respected community members, mostly Bitcoin Core developers.
To ensure all nodes can validate and forward `alert` messages,
encapsulation is used. Developers create an alert using the data
structure appropriate for the versions of the software they want to
notify; then they serialize that data and sign it. The serialized data
and its signature make up the outer `alert` message---allowing nodes
which don't understand the data structure to validate the signature and
relay the alert to nodes which do understand it. The nodes which
actually need the message can decode the serialized data to access the
inner `alert` message.
The outer `alert` message has four fields:
| Bytes | Name | Data Type | Description
|-------------|-----------------|------------------|-------------
| *Variable* | alert bytes | compactSize uint | The number of bytes in following alert field.
| *Variable* | alert | uchar | The serialized alert. See below for a description of the current alert format.
| *Variable* | signature bytes | compactSize uint | The number of bytes in the following signature field.
| *Variable* | signature | uchar | A DER-encoded ECDSA (secp256k1) signature of the alert signed with the developer's alert key.
Although designed to be easily upgraded, the format of the inner
serialized alert has not changed since the `alert` message was first
introduced in protocol version 311.
| Bytes | Name | Data Type | Description
|----------|-------------------|---------------------------|-------------
| 4 | version | int32_t | Alert format version. Version 1 from protocol version 311 through at least protocol version 70002.
| 8 | relayUntil | int64_t | The time beyond which nodes should stop relaying this alert. Unix epoch time format.
| 8 | expiration | int64_t | The time beyond which this alert is no longer in effect and should be ignored. Unix epoch time format.
| 4 | ID | int32_t | A unique ID number for this alert
| 4 | cancel | int32_t | All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future
| *Varies* | setCancel count | compactSize uint | The number of IDs in the following setCancel field. May be zero.
| *Varies* | setCancel | int32_t | Alert IDs which should be canceled. Each alert ID is a separate int32_t number.
| 4 | minVer | int32_t | This alert only applies to protocol versions greater than or equal to this version. Nodes running other protocol versions should still relay it.
| 4 | maxVer | int32_t | This alert only applies to protocol versions less than or equal to this version. Nodes running other protocol versions should still relay it.
| *Varies* | user\_agent count | compactSize uint | The number of user agent strings in the following setUser\_agent field. May be zero.
| *Varies* | setUser\_agent | compactSize uint + string | If this field is empty, it has no effect on the alert. If there is at least one entry is this field, this alert only applies to programs with a user agent that exactly matches one of the strings in this field. Each entry in this field is a compactSize uint followed by a string---the uint indicates how many bytes are in the following string. This field was originally called setSubVer; since BIP14, it applies to user agent strings as defined in the `version` message.
| 4 | priority | int32_t | Relative priority compared to other alerts
| *Varies* | comment bytes | compactSize uint | The number of bytes in the following comment field. May be zero.
| *Varies* | comment | string | A comment on the alert that is not displayed
| *Varies* | statusBar bytes | compactSize uint | The number of bytes in the following statusBar field. May be zero.
| *Varies* | statusBar | string | The alert message that is displayed to the user
| *Varies* | reserved bytes | compactSize uint | The number of bytes in the following reserved field. May be zero.
| *Varies* | reserved | string | Reserved for future use. Originally called RPC Error.
The annotated hexdump below shows an `alert` message. (The message
header has been omitted.)
<!-- example below from Bitcoin Wiki; TODO: replace with a more recent
alert the next time one is live on the network. -->
{% highlight text %}
73 ................................. Bytes in encapsulated alert: 115
01000000 ........................... Version: 1
3766404f00000000 ................... RelayUntil: 1329620535
b305434f00000000 ................... Expiration: 1330917376
f2030000 ........................... ID: 1010
f1030000 ........................... Cancel: 1009
00 ................................. setCancel count: 0
10270000 ........................... MinVer: 10000
48ee0000 ........................... MaxVer: 61000
00 ................................. setUser_agent bytes: 0
64000000 ........................... Priority: 100
00 ................................. Bytes In Comment String: 0
46 ................................. Bytes in StatusBar String: 70
53656520626974636f696e2e6f72672f
666562323020696620796f7520686176
652074726f75626c6520636f6e6e6563
74696e67206166746572203230204665
627275617279 ....................... Status Bar String: "See [...]"
00 ................................. Bytes In Reserved String: 0
47 ................................. Bytes in signature: 71
30450221008389df45f0703f39ec8c1c
c42c13810ffcae14995bb648340219e3
53b63b53eb022009ec65e1c1aaeec1fd
334c6b684bde2b3f573060d5b70c3a46
723326e4e8a4f1 ..................... Signature
{% endhighlight %}
**Alert key compromise:** Bitcoin Core's source code defines a
particular set of alert parameters that can be used to notify users that
the alert signing key has been compromised and that they should upgrade
to get a new alert public key. Once a signed alert containing those
parameters has been received, no other alerts can cancel or override it.
See the `ProcessAlert()` function in the Bitcoin Core [alert.cpp][core
alert.cpp] source code for the parameters of this message.
{% endautocrossref %}
#### FilterAdd
{% autocrossref %}
*Added in protocol version 70001 as described by BIP37.*
The `filteradd` message tells the receiving peer to add a single object to
a previously-set bloom filter, such as a new public key. The object is
sent directly to the receiving peer; the peer then uses the parameters set
in the `filterload` message to add the object to the bloom filter.
Because the object is sent directly to the receiving peer, there is no
obfuscation of the object and none of the plausible-deniability privacy
provided by the bloom filter. Clients that want to maintain greater
privacy should recalculate the bloom filter themselves and send a new
`filterload` message with the recalculated bloom filter.
| Bytes | Name | Data Type | Description
|----------|--------------|------------------|-----------------
| *Varies* | object bytes | compactSize uint | The number of bytes in the following object field.
| *Varies* | object | uint8_t[] | The object to add to the current filter. Maximum of 520 bytes, which is the maximum size of an object which can be pushed onto the stack in a pubkey or signature script. Objects must be sent in the byte order they would use when appearing in a raw transaction; for example, hashes should be sent in internal byte order.
The annotated hexdump below shows an `filteradd` message adding a TXID.
(The message header has been omitted.) This TXID appears in the same
block used for the example hexdump in the `merkleblock` message; if that
`merkleblock` message is re-sent after sending this `filteradd` message,
six hashes are returned instead of four.
{% highlight text %}
20 ................................. Object bytes: 32
fdacf9b3eb077412e7a968d2e4f11b9a
9dee312d666187ed77ee7d26af16cb0b ... Object (A TXID)
{% endhighlight %}
{% endautocrossref %}
#### FilterClear
{% autocrossref %}
*Added in protocol version 70001 as described by BIP37.*
The `filterclear` message tells the receiving peer to remove a
previously-set bloom filter. This also undoes the effect of setting the
relay field in the `version` message to 0, allowing unfiltered access to
`inv` messages announcing new transactions.
Bitcoin Core does not require a `filterclear` message before a
replacement filter is loaded with `filterload`. It also doesn't require
a `filterload` message before a `filterclear` message.
There is no payload in a `filterclear` message. See the [message header
section][message header] for an example of a message without a payload.
{% endautocrossref %}
<!-- TODO: filterload message -->
#### GetAddr
{% autocrossref %}
The `getaddr` message requests an `addr` message from the receiving
node, preferably one with lots of IP addresses of other receiving nodes.
The transmitting node can use those IP addresses to quickly update its
database of available nodes rather than waiting for unsolicited `addr`
messages to arrive over time.
There is no payload in a `getaddr` message. See the [message header
section][message header] for an example of a message without a payload.
{% endautocrossref %}
#### Ping
{% autocrossref %}
*Added nonce field in protocol version 60001 as described by BIP31.*
The `ping` message helps confirm that the receiving peer is still
connected. If a TCP/IP error is encountered when sending the `ping`
message (such as a connection timeout), the transmitting node can assume
that the receiving node is disconnected. The response to a `ping`
message is the `pong` message.
Before protocol version 60000, the `ping` message had no payload. As of
protocol version 60001 and all later versions, the message includes a
single field, the nonce.
| Bytes | Name | Data Type | Description
|-------|-------|-----------|---------------
| 8 | nonce | uint64_t | Random nonce assigned to this `ping` message. The responding `pong` message will include this nonce to identify the `ping` message to which it is replying.
The annotated hexdump below shows a `ping` message. (The message
header has been omitted.)
{% highlight text %}
0094102111e2af4d ... Nonce
{% endhighlight %}
{% endautocrossref %}
#### Pong
{% autocrossref %}
*Added in protocol version 60001 as described by BIP31.*
The `pong` message replies to a `ping` message, proving to the pinging
node that the ponging node is still alive. Bitcoin Core will, by
default, disconnect from any clients which have not responded to a
`ping` message within 20 minutes.
To allow nodes to keep track of latency, the `pong` message sends back
the same nonce received in the `ping` message it is replying to.
The format of the `pong` message is identical to the `ping` message;
only the message header differs.
{% endautocrossref %}
#### Reject
{% autocrossref %}
*Added in protocol version 70002 as described by BIP61.*
The `reject` message informs the receiving node that one of its previous
messages has been rejected.
| Bytes | Name | Data Type | Description
|----------|---------------|------------------|--------------
| *Varies* | message bytes | compactSize uint | The number of bytes in the following message field.
| *Varies* | message | string | The type of message rejected as ASCII text *without null padding*. For example: "tx", "block", or "version".
| 1 | code | char | The reject message code. See the table below.
| *Varies* | reason bytes | compactSize uint | The number of bytes in the following reason field. May be 0x00 if a text reason isn't provided.
| *Varies* | reason | string | The reason for the rejection in ASCII text. This should not be displayed to the user; it is only for debugging purposes.
| *Varies* | extra data | *varies* | Optional additional data provided with the rejection. For example, most rejections of `tx` messages or `block` messages include the hash of the rejected transaction or block header. See the code table below.
The following table lists message reject codes. Codes are tied to the
type of message they reply to; for example there is a 0x10 reject code
for transactions and a 0x10 reject code for blocks.
<!-- several descriptions below copied verbatim from BIP61; sort order:
ascending code number (primary) and alphabetic in reply to (secondary) -->
| Code | In Reply To | Extra Bytes | Extra Type | Description
|------|-------------------|-------------|------------|----------------
| 0x01 | *any message* | 0 | N/A | Message could not be decoded. Be careful of `reject` message feedback loops where two peers each don't understand each other's `reject` messages and so keep sending them back and forth forever.
| 0x10 | `block` message | 32 | char[32] | Block is invalid for some reason (invalid proof-of-work, invalid signature, etc). Extra data is the rejected block's header hash.
| 0x10 | `tx` message | 32 | char[32] | Transaction is invalid for some reason (invalid signature, output value greater than input, etc.). Extra data is the rejected transaction's TXID.
| 0x11 | `block` message | 32 | char[32] | The block uses a version that is no longer supported. Extra data is the rejected block's header hash.
| 0x11 | `version` message | 0 | N/A | Connecting node is using a protocol version that the rejecting node considers obsolete and unsupported.
| 0x12 | `tx` message | 32 | char[32] | Duplicate input spend (double spend): the rejected transaction spends the same input as a previously-received transaction. Extra data is the rejected transaction's TXID.
| 0x12 | `version` message | 0 | N/A | More than one `version` message received in this connection.
| 0x40 | `tx` message | 32 | char[32] | The transaction will not be mined or relayed because the rejecting node considers it non-standard---a transaction type or version unknown by the server. Extra data is the rejected transaction's TXID.
| 0x41 | `tx` message | 32 | char[32] | One or more output amounts are below the dust threshold. Extra data is the rejected transaction's TXID.
| 0x42 | `tx` message | | char[32] | The transaction did not have a large enough fee or priority to be relayed or mined. Extra data is the rejected transaction's TXID.
| 0x43 | `block` message | 32 | char[32] | The block belongs to a block chain which is not the same block chain as provided by a compiled-in checkpoint. Extra data is the rejected block's header hash.
The annotated hexdump below shows a `reject` message. (The message
header has been omitted.)
{% highlight text %}
02 ................................. Number of bytes in message: 2
7478 ............................... Type of message rejected: tx
12 ................................. Reject code: 0x12 (duplicate)
15 ................................. Number of bytes in reason: 21
6261642d74786e732d696e707574732d
7370656e74 ......................... Reason: bad-txns-inputs-spent
394715fcab51093be7bfca5a31005972
947baf86a31017939575fb2354222821 ... TXID
{% endhighlight %}
{% endautocrossref %}
#### VerAck
{% autocrossref %}
The `verack` message acknowledges a previously-received `version`
message, informing the connecting node that it can begin to send
other messages. The `verack` message has no payload; for an example
of a message with no payload, see the [message headers
section][message header].
{% endautocrossref %}
#### Version
{% autocrossref %}
*Receive IP address fields were added in protocol version 106. The
subStr field was renamed the user\_agent field in protocol version 60000
as described by BIP14. Relay field was added in protocol version 70001
as described by BIP37.*
The `version` message provides information about the transmitting node
to the receiving node at the beginning of a connection. Until both peers
have exchanged `version` messages, no other messages will be accepted.
If a `version` message is accepted, the receiving node should send a
`verack` message---but no node should send a `verack` message
before initializing its half of the connection by first sending a
`version` message.
| Bytes | Name | Data Type | Description
|----------|-----------------------|------------------|--------------
| 4 | version | int32_t | The highest protocol version understood by the transmitting node. See the [protocol version section][section protocol versions].
| 8 | services | uint64_t | The services supported by the transmitting node encoded as a bitfield. See the list of service codes below.
| 8 | timestamp | int64_t | The current Unix epoch time according to the transmitting node's clock. Because nodes will reject blocks with timestamps more than two hours in the future, this field can help other nodes to determine that their clock is wrong.
| 8 | addr_recv services | uint64_t | The services supported by the receiving node as perceived by the transmitting node. Same format as the 'services' field above. Bitcoin Core will attempt to provide accurate information. BitcoinJ will, by default, always send 0. <br><br>Added in protocol version 106.
| 16 | addr_recv IP address | char | The IPv6 address of the receiving node as perceived by the transmitting node in **big endian byte order**. IPv4 addresses can be provided as [IPv4-mapped IPv6 addresses][]. Bitcoin Core will attempt to provide accurate information. BitcoinJ will, by default, always return ::ffff:127.0.0.1<br><br>Added in protocol version 106.
| 2 | addr_recv port | uint16_t | The port number of the receiving node as perceived by the transmitting node in **big endian byte order**. <br><br>Added in protocol version 106.
| 8 | addr_trans services | uint64_t | The services supported by the transmitting node. Should be identical to the 'services' field above.
| 16 | addr_trans IP address | char | The IPv6 address of the transmitting node in **big endian byte order**. IPv4 addresses can be provided as [IPv4-mapped IPv6 addresses][]. Set to ::ffff:127.0.0.1 if unknown.
| 2 | addr_trans port | uint16_t | The port number of the transmitting node in **big endian byte order**.
| 8 | nonce | uint64_t | A random nonce which can help a node detect a connection to itself. If the nonce is 0, the nonce field is ignored. If the nonce is anything else, a node should terminate the connection on receipt<!--noref--> of a `version` message with a nonce it previously sent.
| *Varies* | user_agent bytes | compactSize uint | Number of bytes in following user\_agent field. If 0x00, no user agent field is sent.
| *Varies* | user_agent | string | User agent as defined by BIP14. Prior to protocol version 60000, this field was called subVer.
| 4 | start_height | int32_t | The height of the transmitting node's best block chain or, in the case of an SPV client, best block header chain.
| 1 | relay | bool | Transaction relay flag. If 0x00, no `inv` messages or `tx` messages announcing new transactions should be sent to this client until it sends a `filterload` message or `filterclear` message. If 0x01, this node wants `inv` messages and `tx` messages announcing new transactions. <br><br> Added in protocol version 70001.
The following service identifiers have been assigned.
| Value | Name | Description
|-------|--------------|---------------
| 0x00 | *Unnamed* | This node is not a full node. It may not be able to provide any data except for the transactions it originates.
| 0x01 | NODE_NETWORK | This is a full node and can be asked for full blocks. It should implement all protocol features available in its self-reported protocol version.
The following annotated hexdump shows a `version` message. (The
message header has been omitted and the actual IP addresses have been
replaced with [RFC5737][] reserved IP addresses.)
{% highlight text %}
72110100 ........................... Protocol version: 70002
0100000000000000 ................... Services: NODE_NETWORK
bc8f5e5400000000 ................... Epoch time: 1415483324
0100000000000000 ................... Receiving node's services
00000000000000000000ffffc61b6409 ... Receiving node's IPv6 address
208d ............................... Receiving node's port number
0100000000000000 ................... Transmitting node's services
00000000000000000000ffffcb0071c0 ... Transmitting node's IPv6 address
208d ............................... Transmitting node's port number
128035cbc97953f8 ................... Nonce
0f ................................. Bytes in user agent string: 15
2f5361746f7368693a302e392e332f ..... User agent: /Satoshi:0.9.2.1/
cf050500 ........................... Start height: 329167
01 ................................. Relay flag: true
{% endhighlight %}
{% endautocrossref %}

View file

@ -1,8 +1,9 @@
<!-- Terms; must have tooltip description in "quotes"; alphabetical order -->
[51 percent attack]: /en/developer-guide#term-51-attack "The ability of someone controlling a majority of hashing power to revise transactions history and prevent new transactions from confirming"
[addr message]: /en/developer-guide#term-addr-message "A Bitcoin network protocol message which relays IP addresses and port numbers of active nodes to other nodes and clients, allowing decentralized peer discovery."
[addr message]: /en/developer-reference#alert "The P2P network message which relays IP addresses and port numbers of active nodes to other nodes and clients, allowing decentralized peer discovery."
[addresses]: /en/developer-guide#term-address "A 20-byte hash formatted as a P2PKH or P2SH Bitcoin Address"
[address]: /en/developer-guide#term-address "A 20-byte hash formatted as a P2PKH or P2SH Bitcoin Address"
[alert message]: /en/developer-reference#alert "The P2P network message which sends alerts in case of major software problems."
[base58Check]: /en/developer-reference#term-base58check "The method used in Bitcoin for converting 160-bit hashes into Bitcoin addresses"
[bitcoin URI]: /en/developer-guide#term-bitcoin-uri "A URI which allows receivers to encode payment details so spenders don't have to manually enter addresses and other details"
[bitcoins]: /en/developer-guide#term-bitcoins "A primary accounting unit used in Bitcoin; 100 million satoshis"
@ -45,8 +46,11 @@
[extended public key]: /en/developer-guide#term-extended-public-key "A public key extended with the chain code so that it can derive child public keys"
[escrow contract]: /en/developer-guide#term-escrow-contract "A contract in which the spender and receiver store satoshis in a multisig output until both parties agree to release the satoshis"
[fiat]: /en/developer-guide#term-fiat "National currencies such as the dollar or euro"
[filteradd message]: /en/developer-reference#filteradd "A P2P protocol message used to add a data element to an existing bloom filter."
[filterclear message]: /en/developer-reference#filterclear "A P2P protocol message used to remove an existing bloom filter."
[fork]: /en/developer-guide#term-fork "When two or more blocks have the same block height, forking the block chain."
[genesis block]: /en/developer-guide#term-genesis-block "The first block created; also called block 0"
[getaddr message]: /en/developer-reference#getaddr "A P2P protool message used to request an addr message containing connection information for other nodes"
[getblocks message]: /en/developer-reference#getblocks "A P2P protocol message used to request an inv message containing a range of block header hashes"
[getdata message]: /en/developer-reference#getdata "A P2P protocol message used to request one or more transactions, blocks, or merkleblocks"
[getheaders message]: /en/developer-reference#getheaders "A P2P protocol message used to request a range of block headers"
@ -115,8 +119,10 @@
[PaymentRequests]: /en/developer-examples#term-paymentrequest "The PaymentRequest of the payment protocol which contains and allows signing of the PaymentDetails"
[peer]: /en/developer-guide#term-peer "Peer on the P2P network who receives and broadcasts transactions and blocks"
[peers]: /en/developer-guide#term-peer "Peers on the P2P network who receive and broadcast transactions and blocks"
[ping message]: /en/developer-reference#ping "A P2P network message used to see if the remote host is still connected"
[PKI]: /en/developer-examples#term-pki "Public Key Infrastructure; usually meant to indicate the X.509 certificate system used for HTTP Secure (https)."
[point function]: /en/developer-guide#term-point-function "The ECDSA function used to create a public key from a private key"
[pong message]: /en/developer-reference#pong "A P2P network message used to reply to a P2P network ping message"
[private key]: /en/developer-guide#term-private-key "The private portion of a keypair which can create signatures which other people can verify using the public key"
[private keys]: /en/developer-guide#term-private-key "The private portion of a keypair which can create signatures which other people can verify using the public key"
[pubkey hash]: /en/developer-guide#term-pubkey-hash "The hash of a public key which can be included in a P2PKH output"
@ -138,6 +144,7 @@
[redeem script]: /en/developer-guide#term-redeem-script "A pubkey script created by the recipient, hashed, and given to the spender for use in a P2SH output"
[refund]: /en/developer-guide#issuing-refunds "A transaction which refunds some or all satoshis received in a previous transaction"
[regression test mode]: /en/developer-examples#regtest-mode "A local testing environment in which developers can control blocks"
[reject message]: /en/developer-reference#reject "A P2P network message used to indicate a previously-received message was rejected for some reason"
[root certificate]: /en/developer-examples#term-root-certificate "A certificate belonging to a certificate authority (CA)"
[root seed]: /en/developer-guide#term-root-seed "A potentially-short value used as a seed to generate a master private key and master chain code for an HD wallet"
[RPC byte order]: /en/developer-reference#hash-byte-order "A hash digest displayed with the byte order reversed; used in Bitcoin Core RPCs and other software."
@ -177,7 +184,9 @@
[unique addresses]: /en/developer-guide#term-unique-address "Address which are only used once to protect privacy and increase security"
[URI QR Code]: /en/developer-guide#term-uri-qr-code "A QR code containing a bitcoin: URI"
[utxo]: /en/developer-guide#term-utxo "Unspent Transaction Output (UTXO) holding satoshis which have not yet been spent"
[verack message]: /en/developer-reference#verack "A P2P network message sent in reply to a version message to confirm a connection has been established"
[verified payments]: /en/developer-guide#verifying-payment "Payments which the receiver believes won't be double spent"
[version message]: /en/developer-reference#version "A P2P network message sent at the begining of a connection to allow protocol version negotiation"
[v2 block]: /en/developer-reference#term-v2-block "The current version of Bitcoin blocks"
[wallet]: /en/developer-guide#wallets "Software which stores private keys to allow users to spend and receive satoshis"
[Wallet Import Format]: /en/developer-guide#term-wallet-import-format "A private key specially formatted to allow easy import into a wallet"
@ -325,6 +334,10 @@
<!-- Other external site links; alphabetical order -->
[BFGMiner]: https://github.com/luke-jr/bfgminer
[Bitcoin Core]: https://bitcoin.org/en/download
[Bitcoin Core 0.1.6]: https://github.com/bitcoin/bitcoin/commit/cc0b4c3b62367a2aebe5fc1f4d0ed4b97e9c2ac9
[Bitcoin Core 0.2.9]: https://github.com/bitcoin/bitcoin/commit/42605ce8bcc9bd01b86491c74fee14de77960868
[Bitcoin Core 0.3.11]: https://github.com/bitcoin/bitcoin/commit/343328c6b8db85e58a1feea85f0d10e62967fa19
[Bitcoin Core 0.3.15]: https://github.com/bitcoin/bitcoin/commit/c891967b6fcab2e8dc4ce0c787312b36c07efa4d
[bitcoin core fee drop commit]: https://github.com/bitcoin/bitcoin/commit/6a4c196dd64da2fd33dc7ae77a8cdd3e4cf0eff1
[Bitcoin Core issue #2381]: https://github.com/bitcoin/bitcoin/issues/2381
[Bitcoin Seeder]: https://github.com/sipa/bitcoin-seeder
@ -333,6 +346,7 @@
[bitcoinj micropayment tutorial]: https://bitcoinj.github.io/working-with-micropayments
[block170]: https://www.biteasy.com/block/00000000d1145790a8694403d4063f323d499e655c83426834d4ce2f8dd4a2ee
[casascius address utility]: https://github.com/casascius/Bitcoin-Address-Utility
[core alert.cpp]: https://github.com/bitcoin/bitcoin/blob/master/src/alert.cpp
[core base58.h]: https://github.com/bitcoin/bitcoin/blob/master/src/base58.h
[core chainparams.cpp]: https://github.com/bitcoin/bitcoin/blob/master/src/chainparams.cpp
[core git]: https://github.com/bitcoin/bitcoin
@ -351,6 +365,7 @@
[HMAC-SHA512]: https://en.wikipedia.org/wiki/HMAC
[HTTP longpoll]: https://en.wikipedia.org/wiki/Push_technology#Long_polling
[IP-to-IP payment protocol]: https://en.bitcoin.it/wiki/IP_Transactions
[IPv4-mapped IPv6 addresses]: http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses
[irc channels]: https://en.bitcoin.it/wiki/IRC_channels
[libblkmaker]: https://gitorious.org/bitcoin/libblkmaker
[makeseeds script]: https://github.com/bitcoin/bitcoin/tree/master/contrib/seeds
@ -366,6 +381,7 @@
[python-blkmaker]: https://gitorious.org/bitcoin/python-blkmaker
[SHA256]: https://en.wikipedia.org/wiki/SHA-2
[Stratum mining protocol]: http://mining.bitcoin.cz/stratum-mining
[Tor]: https://en.wikipedia.org/wiki/Tor_%28anonymity_network%29
[unix epoch time]: https://en.wikipedia.org/wiki/Unix_time
[URI encoded]: https://tools.ietf.org/html/rfc3986
[wiki script]: https://en.bitcoin.it/wiki/Script

View file

@ -0,0 +1,26 @@
digraph {
size="6.25";
rankdir=TB
nodesep=0.2;
ranksep=0.3;
splines="false"
edge [ penwidth = 1.75, fontname="Sans", dir="none" ]
node [ penwidth = 1.75, shape = "box", fontname="Sans", ]
graph [ penwidth = 1.75, fontname="Sans" ]
version -> verack;
ping -> pong;
getaddr -> addr;
filterload -> filteradd;
filterload -> filterclear;
alert;
ERROR [ style = "invis" ];
ERROR -> reject [ style = "invis" ];
label = " \nOverview Of P2P Protocol Control And Advisory Messages"
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.3 KiB

View file

@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 2.26.3 (20100126.1600)
-->
<!-- Title: _anonymous_0 Pages: 1 -->
<svg width="450pt" height="134pt"
viewBox="0.00 0.00 450.00 134.16" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph1" class="graph" transform="scale(0.931677 0.931677) rotate(0) translate(4 140)">
<title>_anonymous_0</title>
<polygon fill="white" stroke="white" points="-4,5 -4,-140 480,-140 480,5 -4,5"/>
<text text-anchor="middle" x="237.5" y="-25.4" font-family="Sans" font-size="14.00"> </text>
<text text-anchor="middle" x="237.5" y="-8.4" font-family="Sans" font-size="14.00">Overview Of P2P Protocol Control And Advisory Messages</text>
<!-- version -->
<g id="node1" class="node"><title>version</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="66,-136 2.84217e-14,-136 0,-100 66,-100 66,-136"/>
<text text-anchor="middle" x="33" y="-113.9" font-family="Sans" font-size="14.00">version</text>
</g>
<!-- verack -->
<g id="node3" class="node"><title>verack</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="64,-78 2,-78 2,-42 64,-42 64,-78"/>
<text text-anchor="middle" x="33" y="-55.9" font-family="Sans" font-size="14.00">verack</text>
</g>
<!-- version&#45;&gt;verack -->
<g id="edge2" class="edge"><title>version&#45;&gt;verack</title>
<path fill="none" stroke="black" stroke-width="1.75" d="M33,-99.9664C33,-93.0495 33,-85.1566 33,-78.2222"/>
</g>
<!-- ping -->
<g id="node4" class="node"><title>ping</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="134,-136 80,-136 80,-100 134,-100 134,-136"/>
<text text-anchor="middle" x="107" y="-113.9" font-family="Sans" font-size="14.00">ping</text>
</g>
<!-- pong -->
<g id="node6" class="node"><title>pong</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="134,-78 80,-78 80,-42 134,-42 134,-78"/>
<text text-anchor="middle" x="107" y="-55.9" font-family="Sans" font-size="14.00">pong</text>
</g>
<!-- ping&#45;&gt;pong -->
<g id="edge4" class="edge"><title>ping&#45;&gt;pong</title>
<path fill="none" stroke="black" stroke-width="1.75" d="M107,-99.9664C107,-93.0495 107,-85.1566 107,-78.2222"/>
</g>
<!-- getaddr -->
<g id="node7" class="node"><title>getaddr</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="218,-136 148,-136 148,-100 218,-100 218,-136"/>
<text text-anchor="middle" x="183" y="-113.9" font-family="Sans" font-size="14.00">getaddr</text>
</g>
<!-- addr -->
<g id="node9" class="node"><title>addr</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="210,-78 156,-78 156,-42 210,-42 210,-78"/>
<text text-anchor="middle" x="183" y="-55.9" font-family="Sans" font-size="14.00">addr</text>
</g>
<!-- getaddr&#45;&gt;addr -->
<g id="edge6" class="edge"><title>getaddr&#45;&gt;addr</title>
<path fill="none" stroke="black" stroke-width="1.75" d="M183,-99.9664C183,-93.0495 183,-85.1566 183,-78.2222"/>
</g>
<!-- filterload -->
<g id="node10" class="node"><title>filterload</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="311,-136 235,-136 235,-100 311,-100 311,-136"/>
<text text-anchor="middle" x="273" y="-113.9" font-family="Sans" font-size="14.00">filterload</text>
</g>
<!-- filteradd -->
<g id="node12" class="node"><title>filteradd</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="304,-78 230,-78 230,-42 304,-42 304,-78"/>
<text text-anchor="middle" x="267" y="-55.9" font-family="Sans" font-size="14.00">filteradd</text>
</g>
<!-- filterload&#45;&gt;filteradd -->
<g id="edge8" class="edge"><title>filterload&#45;&gt;filteradd</title>
<path fill="none" stroke="black" stroke-width="1.75" d="M271.134,-99.9664C270.419,-93.0495 269.602,-85.1566 268.885,-78.2222"/>
</g>
<!-- filterclear -->
<g id="node14" class="node"><title>filterclear</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="400,-78 318,-78 318,-42 400,-42 400,-78"/>
<text text-anchor="middle" x="359" y="-55.9" font-family="Sans" font-size="14.00">filterclear</text>
</g>
<!-- filterload&#45;&gt;filterclear -->
<g id="edge10" class="edge"><title>filterload&#45;&gt;filterclear</title>
<path fill="none" stroke="black" stroke-width="1.75" d="M299.74,-99.9664C310.094,-92.983 321.924,-85.0048 332.277,-78.0225"/>
</g>
<!-- alert -->
<g id="node15" class="node"><title>alert</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="385,-136 331,-136 331,-100 385,-100 385,-136"/>
<text text-anchor="middle" x="358" y="-113.9" font-family="Sans" font-size="14.00">alert</text>
</g>
<!-- ERROR -->
<!-- reject -->
<g id="node18" class="node"><title>reject</title>
<polygon fill="none" stroke="black" stroke-width="1.75" points="470,-78 414,-78 414,-42 470,-42 470,-78"/>
<text text-anchor="middle" x="442" y="-55.9" font-family="Sans" font-size="14.00">reject</text>
</g>
<!-- ERROR&#45;&gt;reject -->
</g>
</svg>

After

Width:  |  Height:  |  Size: 4.9 KiB