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

wiki commit

Browse Source
This commit is contained in:
qr8ruwyx0u7fqeyu5n49t2paw0ghhp8xsgmffesqzs
2020-02-06 18:24:36 -05:00
committed by buwiki
parent 24de826eb0
commit 777b8d2b6f
10 changed files with 120 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
protocol/network/messages/addr.md
+15 -4
View File
@@ -1,13 +1,24 @@
<div class="cwikmeta">{
"title":"ADDR",
"related":["/protocol","/protocol/p2p/getaddr"]
"related":["/protocol","/protocol/network/messages/getaddr"]
}</div>
# 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<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
*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.
protocol/network/messages/filteradd.md
+4
View File
@@ -3,8 +3,12 @@
"related":["/protocol","/protocol/p2p/getdata","/protocol/p2p/filterload","/protocol/p2p/filterclear"]
}</div>
# 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
protocol/network/messages/filterclear.md
+4 -1
View File
@@ -1,8 +1,11 @@
<div class="cwikmeta">{
"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"]
}</div>
# Request: Filter Clear (“filterclear”)
Remove the installed bloom filter, and therefore disable bloom filtering.
## Message Format
This message has no contents.
protocol/network/messages/filterload.md
+22 -5
View File
@@ -3,12 +3,9 @@
"related":["/protocol","/protocol/network/messages/filterclear.md", "/protocol/network/messages/inv.md", "/protocol/network/messages/merkleblock.md"]
}</div>
# 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
@@ -26,3 +23,23 @@ 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.
## 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 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
protocol/network/messages/getblocks.md
+17 -7
View File
@@ -1,18 +1,24 @@
<div class="cwikmeta">{
"title":"GETBLOCKS",
"related":["/protocol","/protocol/p2p/getdata","/protocol/p2p/getheaders"]
"related":["/protocol","/protocol/network/messages/getdata.md","/protocol/network/messages/getheaders.md"]
}</div>
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
protocol/network/messages/getdata.md
+21 -5
View File
@@ -3,17 +3,33 @@
"related":["/protocol","/protocol/p2p/inv"]
}</div>
# 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<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
| 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.
## Server Implementations
[Bitcoin Unlimited](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/net_processing.cpp#L1021)
## Client Implementations
protocol/network/messages/getheaders.md
+12 -4
View File
@@ -4,12 +4,16 @@
"related":["/protocol"]
} </div>
# 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)
## Server Implementations
[Bitcoin Unlimited](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/net_processing.cpp#L1131)
## Client Implementations
protocol/network/messages/merkleblock.md
+4 -2
View File
@@ -3,14 +3,16 @@
"related":["/protocol", "/protocol/p2p/filteradd"]
}</div>
# 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
| [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
protocol/network/messages/ping.md
+10 -5
View File
@@ -1,13 +1,18 @@
<div class="cwikmeta" style="visibility:hidden;">
{
"title":"PING",
"related":["/protocol/p2p/pong"]
"related":["/protocol/network/messages/pong.md"]
} </div>
# 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*.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| nonce | 8 bytes | unsigned 64 bit integer<sup>[(LE)](/protocol/misc/endian/little.md)</sup> | An arbitrary value provided to connect the ping message with the pong reply
protocol/network/messages/pong.md
+8 -6
View File
@@ -1,13 +1,15 @@
<div class="cwikmeta" style="visibility:hidden;">
{
"title":"PONG",
"related":["/protocol/p2p/ping"]
"related":["/protocol/network/messages/ping.md"]
} </div>
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.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| nonce | 8 bytes | unsigned 64 bit integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The value provided by the [PING](/protocol/network/messages/ping.md) message.