diff --git a/protocol/network/messages/addr.md b/protocol/network/messages/addr.md index c41b74d..2d661db 100644 --- a/protocol/network/messages/addr.md +++ b/protocol/network/messages/addr.md @@ -1,13 +1,24 @@
{ "title":"ADDR", -"related":["/protocol","/protocol/p2p/getaddr"] +"related":["/protocol","/protocol/network/messages/getaddr"] }
+# Response: Addr ("addr") + Provide information about other prospective P2P protocol peers. Peers SHOULD not send this message unsolicited, 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. -| compact int | 4 bytes | 8 bytes | 16 bytes | 2 bytes | -|----------------------------------------|---------|----------|----------|---------| -|[vector](/protocol/p2p/vector) size N of| time | services | IP address | port +## 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[(LE)](/protocol/misc/endian/little) | last known alive time | +| services 0 | 8 bytes | unsigned int[(LE)](/protocol/misc/endian/little) bit field | the services this node supports | +| IP address 0 | 16 bytes | bytes | connect using this IP address +| port 0 | 2 bytes | unsigned integer[(BE)](/protocol/misc/endian/little) | connect using this IP port +| ... | +| time N, etc + *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. diff --git a/protocol/network/messages/filteradd.md b/protocol/network/messages/filteradd.md index 6dc909d..6c56544 100644 --- a/protocol/network/messages/filteradd.md +++ b/protocol/network/messages/filteradd.md @@ -3,8 +3,12 @@ "related":["/protocol","/protocol/p2p/getdata","/protocol/p2p/filterload","/protocol/p2p/filterclear"] } +# Request: Filter Add (“filteradd”) + Add an entry into the installed bloom filter. +## Message Format + | compact int | N bytes | |-------------|---------| |[vector](/protocol/p2p/vector) size N of| data diff --git a/protocol/network/messages/filterclear.md b/protocol/network/messages/filterclear.md index 43ac53e..83a589f 100644 --- a/protocol/network/messages/filterclear.md +++ b/protocol/network/messages/filterclear.md @@ -1,8 +1,11 @@
{ "title":"FILTERCLEAR", -"related":["/protocol","/protocol/p2p/getdata","/protocol/p2p/filterload","/protocol/p2p/filterclear"] +"related":["/protocol","/protocol/network/messages/getdata.md","/protocol/network/messages/filterload.md"] }
+# Request: Filter Clear (“filterclear”) + Remove the installed bloom filter, and therefore disable bloom filtering. -This message has no contents. +## Message Format +This message has no contents. \ No newline at end of file diff --git a/protocol/network/messages/filterload.md b/protocol/network/messages/filterload.md index 1f9b7a9..0f7c181 100644 --- a/protocol/network/messages/filterload.md +++ b/protocol/network/messages/filterload.md @@ -3,12 +3,9 @@ "related":["/protocol","/protocol/network/messages/filterclear.md", "/protocol/network/messages/inv.md", "/protocol/network/messages/merkleblock.md"] } +# Request: Filter Load (“filterload”) -*Inserts a transaction and merkle block filter into the peer* - -| up to 36000 bytes | -|-------------------| -| [bloom filter](/objects/bloom_filter.md) | +Inserts a transaction and merkle block filter into the peer, overwriting any existing filter. ### Effect on Transactions @@ -25,4 +22,24 @@ 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. \ No newline at end of file +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. + +## 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[(LE)](/protocol/misc/endian/little) | number of hash functions used when generating this filter (max 50) | +| tweak | 4 bytes | unsigned integer[(LE)](/protocol/misc/endian/little) | arbitrary number that uniquifies this bloom filter | +flags | 1 byte | bit field | bloom filter flags + +### Bloom Filter Flags + + The lowest two bits of flags control how the installed bloom filter is automatically updated. The remaining bits are reserved and **should** be set to 0. + +| value | description | +|--|--| +| 0 | Do not update +| 1 | update all +| 2 | update pay-to-pubkey, multi-sig, or check-lock-time-verify scripts only + diff --git a/protocol/network/messages/getblocks.md b/protocol/network/messages/getblocks.md index 190d03a..ab4c7c4 100644 --- a/protocol/network/messages/getblocks.md +++ b/protocol/network/messages/getblocks.md @@ -1,18 +1,24 @@
{ "title":"GETBLOCKS", -"related":["/protocol","/protocol/p2p/getdata","/protocol/p2p/getheaders"] +"related":["/protocol","/protocol/network/messages/getdata.md","/protocol/network/messages/getheaders.md"] }
-Request the sequence of blocks that occur after a specific block. If the specified block is on the server's most-work chain, the server responds with a set of up to 500 [INV](/protocol/p2p/inv) messages identifying the next blocks on that chain. If the specified block is not on the most-work chain, the server uses block information in the *locator* structure to determine the fork point and provides [INV](/protocol/p2p/inv) messages from that point. +# Request: Get Blocks (“getblocks”) + +Request the sequence of blocks that occur after a specific block. If the specified block is on the server's most-work chain, the server responds with a set of up to 500 [INV](/protocol/network/messages/inv.md) messages identifying the next blocks on that chain. If the specified block is not on the most-work chain, the server uses block information in the *locator* structure to determine the fork point and provides [INV](/protocol/network/messages/inv.md) messages from that point. + +## Message Format + +| Field | Length | Format | Description | +|--|--|--|--| +| locator | variable | [vector](/protocol/p2p/vector.md) of 32 byte block [hash identifiers](/glossary/hash__identifier.md) | identifies the desired blocks location in the blockchain| +| stop at hash | 32 bytes | bytes | send no more INVs if this hash is encountered -| locator | stop at hash | -|-----------------------------------------------------------------------------------------------|----------| -| [vector](/protocol/p2p/vector) of 32 byte block [hash identifiers](/glossary/hash__identifier)| 32 bytes | ### Locator -See [GETHEADERS](/protocol/p2p/getheaders) for a detailed description of the Locator object. +See [GETHEADERS](/protocol/network/messages/getheaders.md) for a detailed description of the Locator object. The response will begin at **the child of** the first hash in the locator list that matches a block hash identifier held by the responder. If no hashes match, there will be no INV messages sent. @@ -22,4 +28,8 @@ The response will begin at **the child of** the first hash in the locator list t The sender will stop sending INVs if it encounters this hash. If the hash is never encountered, the sender will stop after 500 INV messages or when it hits the blockchain tip. -Server Implementations: [Bitcoin Unlimited](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/net_processing.cpp#L1077) +## Server Implementations + +[Bitcoin Unlimited](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/net_processing.cpp#L1077) + +## Client Implementations \ No newline at end of file diff --git a/protocol/network/messages/getdata.md b/protocol/network/messages/getdata.md index 90a244d..60d1d68 100644 --- a/protocol/network/messages/getdata.md +++ b/protocol/network/messages/getdata.md @@ -3,17 +3,33 @@ "related":["/protocol","/protocol/p2p/inv"] } +# Request: Get Data (“getdata”) + Requests information (generally previously announced via an INV) from a peer. -A GETDATA request is formatted as a vector of INV data: +A GETDATA request is a [vector](/protocol/p2p/vector.md) of INV-formatted data. + +## Message Format + +| Field | Length | Format | Description | +|--|--|--|--| +| vector length N | variable | compact int | number of items | +| item 0 type | 4 bytes | unsigned int[(LE)](/protocol/misc/endian/little) | type of the requested object | +| item 0 hash | 32 bytes | bytes | hash of the requested object | +| ... | | | | +| item N-1 type | +| item N-1 hash -| compact int | 4 bytes | 32 bytes | ... | additional objects | -|---------------|-----------|------------|--|------| -| [vector](/protocol/p2p/vector) size N elements of | element 1 type | element 1 hash | ... | element N type and hash ### Type -The type of the desired object. See [INV](/protocol/p2p/inv) for specific values +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. \ No newline at end of file +The [hash identifier](glossary/hash__identifier) of the desired object. + +## Server Implementations + +[Bitcoin Unlimited](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/net_processing.cpp#L1021) + +## Client Implementations \ No newline at end of file diff --git a/protocol/network/messages/getheaders.md b/protocol/network/messages/getheaders.md index 216f76d..a9ce452 100644 --- a/protocol/network/messages/getheaders.md +++ b/protocol/network/messages/getheaders.md @@ -4,12 +4,16 @@ "related":["/protocol"] } +# Request: Get Headers ("getheaders") + Request a sequence of block hash identifiers -| locator | stop at hash | -|-----------------------------------------------------------------------------------------------|----------| -| [vector](/protocol/p2p/vector) of 32 byte block [hash identifiers](/glossary/hash__identifier)| 32 bytes | +## Message Format +| Field | Length | Format | Description | +|--|--|--|--| +| locator | variable | [vector](/protocol/p2p/vector) of 32 byte block [hash identifiers](/glossary/hash__identifier) | identifies the location of the desired headers | +| stop at hash | 32 bytes | bytes | stop providing headers at this hash ### Locator @@ -31,4 +35,8 @@ If the locator is empty, the response includes only the header identified by thi *Use an empty locator and a valid block hash identifier to request the header of a specific block.* -Server Implementations: [Bitcoin Unlimited](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/net_processing.cpp#L1131) \ No newline at end of file +## Server Implementations + +[Bitcoin Unlimited](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/net_processing.cpp#L1131) + +## Client Implementations diff --git a/protocol/network/messages/merkleblock.md b/protocol/network/messages/merkleblock.md index 8821caa..0291762 100644 --- a/protocol/network/messages/merkleblock.md +++ b/protocol/network/messages/merkleblock.md @@ -3,14 +3,16 @@ "related":["/protocol", "/protocol/p2p/filteradd"] } +# Response: Merkle Block ("merkleblock") + *Provides a block header and partial merkle proof tree to show that selected transaction ids 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. 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. -**MERKLEBLOCK Message Format** +## Message Format | ... | 4 bytes | ... | ...| |----|---------------|-----------|------------| -| [block header](/protocol/p2p/block__header)| # tx in block | [vector](/protocol/p2p/vector) of 32 byte hashes | [vector](/protocol/p2p/vector) of bytes that define the merkle block traversal \ No newline at end of file +| [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 \ No newline at end of file diff --git a/protocol/network/messages/ping.md b/protocol/network/messages/ping.md index 9f9fadf..8261655 100644 --- a/protocol/network/messages/ping.md +++ b/protocol/network/messages/ping.md @@ -1,13 +1,18 @@ +# Request: Ping ("ping") + Connection keep-alive, "aliveness" and latency discovery. -| nonce | -|---------| -| 8 bytes | +If a node receives a PING message, it replies as quickly as possible with a [PONG](/protocol/network/messages/pong.md) message with the provided *nonce*. -If a node receives a PING message, it replies as quickly as possible with a [PONG](/protocol/p2p/pong) message with the provided *nonce*. \ No newline at end of file + +## Message Format + +| Field | Length | Format | Description | +|--|--|--|--| +| nonce | 8 bytes | unsigned 64 bit integer[(LE)](/protocol/misc/endian/little.md) | An arbitrary value provided to connect the ping message with the pong reply \ No newline at end of file diff --git a/protocol/network/messages/pong.md b/protocol/network/messages/pong.md index 339f4e5..71f99d5 100644 --- a/protocol/network/messages/pong.md +++ b/protocol/network/messages/pong.md @@ -1,13 +1,15 @@ -Connection keep-alive, "aliveness" and latency discovery. +# Response: Pong ("pong") -| nonce | -|---------| -| 8 bytes | +Connection keep-alive, "aliveness" and latency discovery. This message is sent in response to a [PING](/protocol/network/messages/ping.md) message. -This message is sent in response to a [PING](/protocol/p2p/ping) message. \ No newline at end of file +## Message Format + +| Field | Length | Format | Description | +|--|--|--|--| +| nonce | 8 bytes | unsigned 64 bit integer[(LE)](/protocol/misc/endian/little) | The value provided by the [PING](/protocol/network/messages/ping.md) message.