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

Merge remote-tracking branch 'upstream/master'

Browse Source
This commit is contained in:
Christopher-Zeng
2020-11-02 09:55:39 -05:00
parent 4910fb8f9b 1dbef6b055
commit f680b201e8
25 changed files with 715 additions and 110 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+7
View File
@@ -2,3 +2,10 @@
This repository contains markdown documentation that specifies the Bitcoin Cash cryptocurrency protocol.
However, this repository should not be directly used for normal browsing because this document uses some markdown extensions.
Instead, read this documentation at one of the following places:
- [reference.cash](http://reference.cash)
- [documentation.cash](http://documentation.cash)
- [bitcoinprotocol.cash](http://bitcoinprotocol.cash)
glossary/outpoint.md
+1
View File
@@ -0,0 +1 @@
An outpoint is a (transaction [hash identifier](/glossary/hash__identifier), index pair) that uniquely identifies a particular [UTXO](/glossary/UTXO).
glossary/output__script.md
+8
View File
@@ -0,0 +1,8 @@
<div class="cwikmeta">
{
"title":"Output Script",
"related":["/glossary/redeem__script","/glossary/input__script"]
}
</div>
The output script constrains the subsequent spend of Bitcoins.
glossary/spv.md
+1
View File
@@ -0,0 +1 @@
SPV is an acronym for "Simplified Payment Validation".
glossary/utxo__set.md
+6
View File
@@ -0,0 +1,6 @@
<!-- TITLE: UTXO Set -->
<!-- SUBTITLE: Unspent Transaction Output Set -->
The UTXO set contains information that describes the current spending constraints on every coin in the blockchain at a particular moment (generally "now"). This information is used to determine the validity of new transactions, and to report information such as wallet balances.
This data is extracted from the blockchain, which contains the full history (all transfers, spent or unspent) of all coins since their creation.
home.md
+4 -4
View File
@@ -8,7 +8,7 @@
[Overview](protocol\Overview.md) — [Blockchain Basics](/protocol/blockchain) — [Protocol Hashing Algorithms](/protocol/blockchain/hash) — Memory Pool
### Transactions
[Bitcoin Transaction](/protocol/blockchain/transaction) — [Unlocking Script](/protocol/blockchain/transaction/unlocking-script)— [Locking Script](/protocol/blockchain/transaction/locking-script)
[Bitcoin Transaction](/protocol/blockchain/transaction) — [Unlocking Script](/protocol/blockchain/transaction/unlocking-script) — [Locking Script](/protocol/blockchain/transaction/locking-script) — [Transaction Signing](/protocol/blockchain/transaction/transaction-signing)
### Blocks
[Bitcoin Blocks](/protocol/blockchain/block) —
@@ -28,10 +28,10 @@
Pay To Public Key (P2PK) — Pay To Public Key Hash (P2PKH) — Pay To Script Hash (P2SH) — [Base58Check encoding (legacy)](/protocol/blockchain/encoding/base58check) — [Cashaddr Encoding](/protocol/blockchain/encoding/cashaddr)
### Cryptography
Secp256k1 — Public Key — Private Key — ECDSA Signatures — Schnorr Signatures — [Multisignature (M-of-N multisig)](/protocol/blockchain/cryptography/multisignature.md)
Secp256k1 — Public Key — Private Key — ECDSA Signatures — Schnorr Signatures — [Multisignature (M-of-N multisig)](/protocol/blockchain/cryptography/multisignature)
### Network upgrades
[Bip-16](/protocol/forks/bip-0016) — [Bip-34](/protocol/forks/bip-0034) — [Bip-37](/protocol/forks/bip-0037) — [Bip-64](/protocol/forks/bip-0064) — [Bip-65](/protocol/forks/bip-0065) — [Bip-66](/protocol/forks/bip-0066) — [Bip-68](/protocol/forks/bip-0068) — [Bip-112](/protocol/forks/bip-0112) — [Bip-113](/protocol/forks/bip-0113) — [Bip-157](/protocol/forks/bip-0157) — [Bip-158](/protocol/forks/bip-0158) — [Bip-159](/protocol/forks/bip-0159) — BCH-UAHF (BUIP-55) — [HF-20171113](/protocol/forks/hf-20171113) — HF-20180515 — HF-20181115 — HF-20190515 — HF-20191115
[Bip-16](/protocol/forks/bip-0016) — [Bip-34](/protocol/forks/bip-0034) — [Bip-37](/protocol/forks/bip-0037) — [Bip-64](/protocol/forks/bip-0064) — [Bip-65](/protocol/forks/bip-0065) — [Bip-66](/protocol/forks/bip-0066) — [Bip-68](/protocol/forks/bip-0068) — [Bip-112](/protocol/forks/bip-0112) — [Bip-113](/protocol/forks/bip-0113) — [Bip-157](/protocol/forks/bip-0157) — [Bip-158](/protocol/forks/bip-0158) — [Bip-159](/protocol/forks/bip-0159) — [BCH-UAHF (BUIP-55)](/protocol/forks/bch-uahf) — [HF-20171113](/protocol/forks/hf-20171113) — HF-20180515 — HF-20181115 — HF-20190515 — HF-20191115
### Network protocol
@@ -53,7 +53,7 @@ Secp256k1 — Public Key — Private Key — ECDSA Signatures — Schnorr Signat
#### Other messages (extensions)
sendcmpct — get_xthin — xthinblock — thinblock — get_xblocktx — xblocktx — [xupdate](/protocol/p2p/xupdate) — [xversion](/protocol/p2p/xversion) —xverack
sendcmpct — get_xthin — xthinblock — thinblock — get_xblocktx — xblocktx — [xupdate](/protocol/network/messages/xupdate) — [xversion](/protocol/network/messages/xversion) — [xverack](/protocol/network/messages/xverack)
### Simple Payment Verification (SPV)
[Bloom Filters](/objects/bloom__filter)
objects/bloom__filter.md
+17
View File
@@ -0,0 +1,17 @@
<div class="cwikmeta">{
"title":"Bloom Filter",
"related":["/protocol/p2p/filterload"]
}</div>
A bloom filter is an imperfect but efficient set membership test. The filter will never incorrectly report that member is NOT in the set. However, it may report that a member is in a set when it is actually not. See [wikipedia](https://en.wikipedia.org/wiki/Bloom_filter), or the [original paper](https://dl.acm.org/citation.cfm?id=362686.362692) for details.
Therefore bloom filters are often used during set membership testing as a quick pre-check to eliminate most elements.
### Use in the Bitcoin Peer-to-Peer Protocol
Bloom filters are used in the bitcoin peer-to-peer protocol to filter the transactions and blocks that a client is sent from another node. The client first "installs" a bloom filter that contains information about the objects it is interested in by sending a [FILTERLOAD](/protocol/p2p/filterload) message to a peer. The peer will subsequently only provide objects that match the installed filter.
At a minimum, an [SPV](/glossary/SPV) client must insert addresses and [outpoints](/glossary/outpoint) into the bloom filter. The addresses will cause every transaction that pays INTO the wallet to be reported, and the outpoints will cause every transaction that pays OUT OF the wallet to be reported.
Bitcoin Bloom filters have an additional feature. Based on the setting of a flag byte, it is possible to direct the peer to automatically insert new data into the bloom filter based on transactions that match. In particular, outpoints will be automatically inserted that correspond to the outputs of addresses that match the filter. This facility is extremely important because if a receive and spend occur within the same transaction, the client does not have the opportunity to update the filter. Bloom filters should therefore be sized with the expectation that new elements will be inserted.
However, due to the bloom filter's tendency to have false positives, these insertions means that unnecessary data will be inserted into the filter, creating even more false positives in a positive feedback loop. Eventually the node will start sending a lot of unnecessary traffic to the client. Therefore, it is essential for clients to periodically refresh (using [FILTERLOAD](/protocol/p2p/filterload)) the bloom filter to remove these unnecessary entries.
objects/wallet__objects.md
+19
View File
@@ -0,0 +1,19 @@
<div class="cwikmeta">
{
"title": "Wallet Objects"
} </div>
The following graph shows the derivation relationship between wallet objects.
```mermaid
graph TB
PrivK["Private Key"] ==>PubK[Public key]
PubK == RIPEMD and SHA256 ==> PubKH[Public Key Hash]
PubKH==>Address
Address==>PubKH
Script==>Address
style PubK fill:#906,stroke:#333,stroke-width:2px;
style PrivK fill:#f06,stroke:#333,stroke-width:8px;
style PubKH fill:#2f6,stroke:#333,stroke-width:2px;
style Address fill:#2f6,stroke:#333,stroke-width:2px;
```
protocol/blockchain.md
+1 -1
View File
@@ -22,7 +22,7 @@ Sibling blocks can happen if a block is created with sufficient work before the
Sibling blocks are incompatible with one another, and eventually one will become orphaned.
The [genesis block](/protocol/blockchain#genesis-block) is the first block in a chain, and has a block height of `0` (as its distance to the genesis block is zero).
As of [BIP-0034](/blockchain/forks/bip-34), the `block height` is included within the [coinbase transaction](/protocol/blockchain/block#coinbase-transaction).
As of [BIP-34](/protocol/forks/bip-0034), the `block height` is included within the [coinbase transaction](/protocol/blockchain/block#coinbase-transaction).
## Work
protocol/blockchain/chainwork-proof.md
+106
View File
@@ -0,0 +1,106 @@
# Chainwork Proof
The idea of chainwork is intrinsic to blockchains. Nodes switch to the chain tip with the most cumulative "work" to help preserve the blockchain assumption that the majority of the miners on a chain are honest. Chainwork is calculated by summing the "work" done in each block in the chain.
Is summing work a valid operation?
More formally, *is the expected number of hashes to solve one block candidate with work W is equal to the expected number of hashes to solve N block candidates with work W/N?*
## Warm-up
For every block candidate, a target (specified in a nonstandard floating point form in the block header as 'nBits') is calculated. Any hash less than this target solves the block. Under the random oracle model (that is, assuming that cryptographic hash functions produce unpredictable output), this is equivalent to rolling a $2^{256}$ sided die with any number less than or equal to the target resulting in a "win". The probability of this is:
$$
P(target) = (target + 1)/2^{256} \tag1
$$
*We add one to target because the number range of target is from 0 to $2^{256}-1$, rather than 1 to $2^{256}$.*
Equation 1 is about the target, but we sum work. We need the relationship between work and target which is defined in the code as follows:
$$
work = 2^{256}/ (target + 1)
$$
or, solving for target:
$$
T(work) = (2^{256}/work) -1 \tag2
$$
Finally we need an equation from general statistics. The expected number of trials before a success for such a random variable is given by (see [wikipedia](https://en.wikipedia.org/wiki/Geometric_distribution#Properties)):
$$
E(probability\_of\_success) = 1/probability\_of\_success \tag3
$$
'Trials' in our case are individual attempts to solve a block. So if the expected number of trials of two different processes are the same then we can say those two processes would take the same amount of work (on average).
## Proof
Recall our question "*is the expected number of hashes to solve one block candidate with work W is equal to the expected number of hashes to solve N block candidates with work W/N?*"
With the above definitions this can be expressed in mathematical notation:
$$
E(P(T(work))) \stackrel{?}{=} n * E(P(T(work/n))) \tag4
$$
With all of our preparation, this proof is easy. But I'll go through each step to make it convenient to read along.
First we'll replace the functions with their defintions on the left side **to prove that what the blockchain community calls "work" is the expected number of hashes**.
$$
E(P(T(work))) = E(P((2^{256}/work) -1))
$$
$$
= E(((2^{256}/work) -1 + 1)/2^{256})
$$
$$
= E((2^{256}/work)/2^{256})
$$
$$
= E(1/work)
$$
$$
= work
$$
Second we'll do the same on the right side and simplify to prove that the result is the same:
First, substitute the definition of T() (eqn 2):
$$
n * E(P(T(work/n))) = n * E(P((n*2^{256}/work) -1)
$$
Next, substitute the definition of P() (eqn 1):
$$
= n * E( ((n*2^{256}/work))/2^{256})
$$
Third, substitute the defintion of E() (eqn 3):
$$
= \dfrac{n}{\frac{(n*2^{256}/work )}{2^{256}}}
$$
Finally, simplify:
$$
= \dfrac{n*2^{256}} {(n*2^{256}/work)}
$$
$$
= \dfrac{n*2^{256}*work} {n*2^{256}}
$$
$$
= work
$$
protocol/blockchain/hash.md
+5 -4
View File
@@ -24,9 +24,10 @@ Since [BIP-34](/protocol/forks/bip-0034), the block height is now required to be
- `D5D27987D2A3DFC724E359870C6644B40E497BDC0589A033220FE15429D88599`
- `E3BF3D07D4B0375638D5F1DB5255FE07BA2C4CB067CD81B84EE974B6585FB468`
In contrast to many hashing algorithm implementations, Bitcoin Cash block and transaction hashes use a little-endian representation.
This means they are displayed and sent over the network with the least-significant byte first.
And ultimately permits a block hash stored in memory to be interpreted without swapping endianness for integer operations such as the comparison with the block difficulty during block validation or mining.
In contrast to many other protocols, Bitcoin Cash sometimes treats block and transaction hashes as a number, for example when comparing with block difficulty during block validation or mining.
In these situations, the output byte array of the hashing algorithm is interpreted as a 256 bit number in little-endian format, particularly when transmitted over the network.
This is the opposite of standard protocol design, so it may be simpler to think of hashes as byte arrays that occasionally are turned into little-endian numbers, than as numbers with a lot of display/encoding caveats.
## RIPEMD-160
[RIPEMD-160](https://en.wikipedia.org/wiki/RIPEMD) is used in Bitcoin Cash scripts to create short, quasi-anonymous representations of payees for transactions.
Since its brevity is also a potential liability for the anonymity it provides (since shorter hashes generally provide less collision-resistance), it is used in conjunction with SHA-256 when generating an address from a public key.
@@ -35,4 +36,4 @@ This SHA-256 then RIPEMD-160 process has its own operation for ease-of-use, [OP_
## Murmur
[MurmurHash](https://en.wikipedia.org/wiki/MurmurHash) is used in Bitcoin to support [Bloom filters](https://en.wikipedia.org/wiki/Bloom_filter).
The specific version used is the MurmurHash version 3 (32-bit), with the first hash initialized to `(numberOfHashesRequired * 0xFBA4C795L + nonce)` where `nonce` is a randomly chosen 32-bit unsigned integer.
The specific version used is the MurmurHash version 3 (32-bit), with the first hash initialized to `(numberOfHashesRequired * 0xFBA4C795L + nonce)` where `nonce` is a randomly chosen 32-bit unsigned integer.
protocol/blockchain/proof-of-work.md
+14 -3
View File
@@ -22,14 +22,25 @@ For more details on how the target is calculated, see [Difficulty Adjustment Alg
## Difficulty
Though the term difficulty is often used colloquially to refer generally to the changes to the target as blocks are mined, it can also refer specifically to the integer value of one target divided by another. Generally, the numerator is a base target, e.g. the [genesis block](/protocol/blockchain#genesis-block) target, while the denominator is the target of the block whose "difficulty" is to be calculated. This results in two benefits relative to using targets directly:
Though the term difficulty is often used colloquially to refer generally to the changes to the target as blocks are mined, it can also refer specifically to the integer value of one target divided by another.
Generally, the numerator is a base target, e.g. the [genesis block](/protocol/blockchain#genesis-block) target, while the denominator is the target of the block whose "difficulty" is to be calculated.
This results in two benefits relative to using targets directly:
- **More Intuitive:** Higher numbers mean the block required more hashing power to mine, while lower number mean less hashing power was required. Increased difficulty is easier to understand than decreased target, even though these means the same thing.
- **More Manageable:** The difficulty calculation produces much more human-readable numbers than trying to interpret targets as an integer directory.
## Chainwork
Chainwork is a representation of the work performed through a block's entire history. It is calculated using the difficulties of each of the blocks in the chain. The work for a single block is calculated as <code>2<sup>256</sup> / (target + 1)</code>, or equivalently in 256-bit two's-complement arithmetic, <code>(~target / (target + 1)) + 1</code>, where `~` is the bitwise NOT operation. The chainwork for a block is the sum of its work with the work of all the blocks preceeding it. As such, when a new block is mined, its chainwork is simply its work plus the chainwork of the block before it.
Chainwork is a representation of the work performed through a block's entire history.
It is the [expected](https://en.wikipedia.org/wiki/Expected_value) number of hashes required to re-solve every block in the chain.
It is calculated using the difficulties of each of the blocks in the chain.
The work for a single block is calculated as <code>2<sup>256</sup> / (target + 1)</code>, or equivalently in 256-bit two's-complement arithmetic, <code>(~target / (target + 1)) + 1</code>, where `~` is the bitwise NOT operation.
The chainwork for a block is the sum of its work with the work of all the blocks preceeding it.
As such, when a new block is mined, its chainwork is simply its work plus the chainwork of the block before it.
This algorithm implies that summing chainwork makes sense.
More formally, the expected number of hashes to solve one block candidate with work `W` is equal to the expected number of hashes to solve `N` block candidates with work `W/N`.
This, and that chainwork is the expected number of hashes, is proved [here](/protocol/blockchain/chainwork-proof).
## Extra Nonce
@@ -40,4 +51,4 @@ As a result, there was a need for additional data to be varied.
The only other parameter of the block header that a miner has any power over is the merkle root.
In order to change the merkle root, the transactions in the block would need to be changed.
But since the [coinbase transaction](/protocol/blockchain/block#coinbase-transaction) is already created by the miner of the block, and updating its hash would allow for efficient re-calculation of the merkle root, putting this "extra nonce" in the coinbase transaction was the logical conclusion.
Ultimately, the extra nonce is included as a part of the coinbase message, usually following the block height that is required to be first.
Ultimately, the extra nonce is included as a part of the coinbase message, usually following the block height that is required to be first.
protocol/blockchain/transaction.md
+2 -2
View File
@@ -18,7 +18,7 @@ Verification of a transaction ensures that:
| transaction inputs | variable | `input_count` [transaction inputs](#transaction-inputs) | Each of the transaction's inputs serialized in order. |
| output count | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of output in the transaction. |
| transaction outputs | variable | `output_count` [transaction outputs](#transaction-outputs) | Each of the transaction's outputs serialized in order. |
| lock-time | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The block height or timestamp after which this transaction is allowed to be included in a block. If less than `500,000,000`, this is interpreted as a block height. If equal or greater than `500,000,000`, this is interpreted as a unix timestamp in seconds. If less than zero, this is interpreted as an error. Ignored, including less than zero case, if all of the transaction input sequence numbers are `0xFFFFFFFF`.<br/><br/>Note that at 10 minutes per block, it will take over 9,500 years to reach block height 500,000,000. Also note that when Bitcoin was created the unix timestamp was well over 1,000,000,000.<br/><br/>Additionally, since [BIP-113](/protocol/forks/bip-0113), when the lock-time is intepreted as a time, it is compared to the [median-time-past](#median-time-past) of a block, not it's timestamp. |
| lock-time | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The block height or timestamp after which this transaction is allowed to be included in a block. If less than `500,000,000`, this is interpreted as a block height. If equal or greater than `500,000,000`, this is interpreted as a unix timestamp in seconds. Ignored if all of the transaction input sequence numbers are `0xFFFFFFFF`.<br/><br/>Note that at 10 minutes per block, it will take over 9,500 years to reach block height 500,000,000. Also note that when Bitcoin was created the unix timestamp was well over 1,000,000,000.<br/><br/>Additionally, since [BIP-113](/protocol/forks/bip-0113), when the lock-time is intepreted as a time, it is compared to the [median-time-past](#median-time-past) of a block, not it's timestamp. |
### Median-Time-Past
@@ -74,7 +74,7 @@ A Transaction Output that is being spent by a Transaction Input is often referre
| Field | Length | Format | Description |
|--|--|--|--|
| value | 8 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The number of satoshis to be transferred. |
| locking script length | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the unlocking script in bytes. |
| locking script length | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the locking script in bytes. |
| locking script | variable | bytes<sup>[(BE)](/protocol/misc/endian/big)</sup> | The contents of the locking script. |
## Transaction Fee
protocol/blockchain/transaction/transaction-signing.md
+130
View File
@@ -0,0 +1,130 @@
# Transaction Signatures
Transaction signatures are central to how [Bitcoin Cash transactions](/protocol/blockchain/transaction) are generally secured, preventing people other than the intended recipient of funds from spending them. Bitcoin Cash signatures are created using [asymmetric cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography) and involve generating a [hash](/protocol/blockchain/hash) of the transaction and performing a signature operation using the sender's private key. Anyone with the corresponding public key can then verify the validity of the signature. As described in [Standard Scripts](/protocol/blockchain/transaction/locking-script#standard-scripts), the [OP_CHECKSIG and related operations](/protocol/blockchain/script#cryptography) are used to validate signatures included in the unlocking script of a future transaction input.
However, there are a number of issues with signing a transaction that must be addressed:
1. Transactions are identified by hashes of the full contents of the transaction
2. The signatures are a part of the transaction data
3. The signatures are created from a hash of the transaction's data
Points (1) and (2) mean that if the signature is changed, the transaction's hash will change. Points (2) and (3) mean that the data that the signature hash preimage (i.e. the data that is hashed and signed) must not be the full transaction data. In addition, because signatures relate only to a single input to a transaction (i.e. spending an unspent transaction output or UTXO) the may be multiple signatures in a transaction potentially created by different private keys, or even different people.
As a consequence of these factors, signatures have more parameters than may be immediately obvious, and the details of how signatures are generated can be, and have been, changed in a number of ways. These parameters are encoded in the [Hash Type](#hash-type).
In addition, as a part of [BCH-UAHF](/protocol/forks/bch-uahf) (activated in block 478,559), the transaction signed format changed from the legacy [Bitcoin (BTC) method](#btc-signatures) to the [Bitcoin Cash (BCH) Signatures](#bch-signatures). In both cases, there is a signature preimage format (input) and a signature format (output).
### Hash Type
Parameters that change the way a signature hash is generated are encoded in the hash type field.
This field (which is always included in the preimage), is contained in 4 bytes.
The two least significant bits have the following collective meaning:
| Value | Meaning |
|--|--|
| `0x01` | `SIGHASH_ALL`. This is the default and indicates that all outputs are included in the signature preimage. |
| `0x02` | `SIGHASH_NONE`. Indicates that no outputs are included in the signature preimage. |
| `0x03` | `SIGHASH_SINGLE`. Indicates that only the output with the same index as the input the signature is being generated for will be included in the signature preimage. |
In conjunction with the above values, the higher-order bits act as a bitmask with the following meaning:
| Bit | Meaning |
|--|--|
| `0x00000040` | `SIGHASH_FORKID`. If set, indicates that this signature is for a Bitcoin Cash transaction. Required following BCH-UAHF, to prevent transactions from being valid on both the BTC and BCH chains. |
| `0x00000080` | `SIGHASH_ANYONECANPAY`. Indicates that only information about the input the signature is for will be included, allowing other inputs to be added without impacting the signature for the current input. |
Combining these, there are 6 valid signature hash types in Bitcoin Cash. Only the least significant byte (LSB) is shown in binary, since the rest of the bits are zero.
| Signature hash type | Value (hex) | LSB (bin) | Description |
| -------------------------------------------------------- | ----------- | ----------- | --------------------------------------------------------------------- |
| SIGHASH_ALL \| SIGHASH_FORKID | 0x00000041 | 0b01000001 | Signature applies to all inputs and outputs. |
| SIGHASH_NONE \| SIGHASH_FORKID | 0x00000042 | 0b01000010 | Signature applies to all inputs and none of the outputs. |
| SIGHASH_SINGLE \| SIGHASH_FORKID | 0x00000043 | 0b01000011 | Signature applies to all inputs and the output with the same index. |
| SIGHASH_ALL \| SIGHASH_ANYONECANPAY \| SIGHASH_FORKID | 0x000000C1 | 0b11000001 | Signature applies to its own input and all outputs. |
| SIGHASH_NONE \| SIGHASH_ANYONECANPAY \| SIGHASH_FORKID | 0x000000C2 | 0b11000010 | Signature applies to its own input and none of the outputs. |
| SIGHASH_SINGLE \| SIGHASH_ANYONECANPAY \| SIGHASH_FORKID | 0x000000C3 | 0b11000011 | Signature applies to its own input and the output with the same index.|
## BCH Signatures
In Bitcoin Cash, transaction signature uses the transaction digest algorithm described in [BIP143](https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki), in order to minimize redundant data hashing in verification and to cover the input value by the signature.
### Preimage Format
| Field | Length | Format | Description |
|--|--|--|--|
| transaction version | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The value of transaction's version field. |
| previous outputs hash | 32 bytes | hash<sup>[(BE)](/protocol/misc/endian/big)</sup> | A double SHA-256 hash of the set of previous outputs spent by the inputs of the transaction. See [Previous Outputs](#previous-outputs-hash) for the hash preimage format.<br/><br/>If hash type is "ANYONE CAN PAY" then this is all `0x00` bytes. |
| sequence numbers hash | 32 bytes | hash<sup>[(BE)](/protocol/misc/endian/big)</sup> | A double SHA-256 hash of the set of sequence numbers of the inputs of the transaction. See [Sequence Numbers](#sequence-numbers-hash) for the hash preimage format.<br/><br/>If hash type is "ANYONE CAN PAY" then this is all `0x00` bytes. |
| previous output hash | 32 bytes | hash<sup>[(LE)](/protocol/misc/endian/little)</sup> | The transaction ID of the previous output being spent. |
| previous output index | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The index of the output to be spent. |
| modified locking script length | variable | [variable length integer](/protocol/format/variable-length-integer) | The number of bytes for `modified_locking_script`. |
| modified locking script | `modified_locking_script_length` bytes | bytes<sup>[(BE)](/protocol/misc/endian/big)</sup> | The subset of the locking script used for signing. See [Modified Locking Script](#modified-locking-script) |
| previous output value | 8 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The value of the transaction output being spent. |
| input sequence number | 8 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The sequence number of the input this signature is for. |
| transaction outputs hash | 32 bytes | hash<sup>[(BE)](/protocol/misc/endian/big)</sup> | A double SHA-256 hash of the outputs of the transaction. See [Transaction Outputs](#transaction-outputs-hash) for the hash preimage format. |
| transaction lock time | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The lock time of the transaction. |
| hash type | 4 bytes | [Hash Type](#hash-type)<sup>[(LE)](/protocol/misc/endian/little)</sup> | Flags indicating the rules for how this signature was generated. |
#### Previous Outputs Hash
The double-SHA256-hash of the following data is used.
For each transaction input in the transaction, append the following information:
| Field | Length | Format | Description |
|--|--|--|--|
| previous transaction hash | 32 bytes | bytes<sup>[(LE)](/protocol/misc/endian/little)</sup> | The hash of the transaction that generated the output to be spent. |
| output index | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The index of the output to be spent from the specified transaction. |
#### Sequence Numbers Hash
The double-SHA256-hash of the following data is used.
For each transaction input in the transaction, append the following information:
| Field | Length | Format | Description |
|--|--|--|--|
| sequence number | 4 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The sequence number field of the transaction input. |
#### Modified Locking Script
The locking script included in the signature preimage is, first, dependent on the type of locking script included in the previous output. For non-[P2SH](/protocol/blockchain/transaction/locking-script#pay-to-script-hash-p2sh) outputs, the locking script itself is used. However, for P2SH outputs, the redeem script is used instead.
Second, the selected script (locking script or redeem script) is modified as follows.
* Find the [`OP_CODESEPARATOR`](/protocol/blockchain/script#cryptography) operation in the script preceding the expected [signature-verification operation](/protocol/blockchain/script#cryptography) (e.g. `OP_CHECKSIG`).
* Remove all operations before this point.
* Remove any remaining `OP_CODESEPARATOR` operations.
The resulting script is what is included in the signature preimage.
#### Transaction Outputs Hash
If the hash type is `SIGHASH_NONE` then the hash should be all `0x00` bytes.
If hash type is `SIGHASH_SINGLE` then only the output with the same index as the input being signed is included.
If no such output exists (i.e. there are fewer outputs than the index of the input to be signed), this is again all `0x00` bytes.
Otherwise, all outputs of the transaction should be signed (i.e. `SIGHASH_ALL`).
For each transaction output to be signed (per the hash mode), append the following information:
| Field | Length | Format | Description |
|--|--|--|--|
| value | 8 bytes | unsigned integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The number of satoshis to be transferred. |
| locking script length | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the locking script in bytes. |
| locking script | variable | bytes<sup>[(BE)](/protocol/misc/endian/big)</sup> | The contents of the locking script. |
### Signature Format
## BTC Signatures
### Preimage Format
### Signature Format
protocol/blockchain/transaction/unlocking-script.md
+1 -1
View File
@@ -5,4 +5,4 @@ This is accomplished by first executing the unlocking script and then executing
If this execution triggers no failures and leaves a single non-zero (TRUE) value on the stack, the UTXO has been successfully unlocked.
One way to look at this is that the unlocking script provides an initial state that acts as an inverse to the previously published locking script.
For more information about how script execution works, see [Script](/protocol/blockchain/script).
For more information about how script execution works, see [Script](/protocol/blockchain/script). For information on how signatures (which typically go in the unlocking script) are generated, see [Transaction Signatures](/protocol/blockchain/transaction/signatures).
protocol/forks/bch-uahf.md
+284
View File
@@ -0,0 +1,284 @@
<pre>
layout: specification
title: UAHF Technical Specification
category: spec
date: 2017-07-24
activation: 1501590000
version: 1.6
</pre>
## Introduction
This document describes proposed requirements for a block size Hard Fork (HF).
BUIP 55 specified a block height fork. This UAHF specification is
inspired by the idea of a flag day, but changed to a time-based fork due
to miner requests. It should be possible to change easily to a height-based
fork - the sense of the requirements would largely stay the same.
## Definitions
MTP: the "median time past" value of a block, calculated from its nTime
value, and the nTime values of its up to 10 immediate ancestors.
"activation time": once the MTP of the chain tip is equal to or greater
than this time, the next block must be a valid fork block. The fork block
and subsequent blocks built on it must satisfy the new consensus rules.
"fork block": the first block built on top of a chain tip whose MTP is
greater than or equal to the activation time.
"fork EB": the user-specified value that EB shall be set to at
activation time. EB can be adjusted post-activation by the user.
"fork MG": the user-specified value that MG shall be set to at activation
time. It must be > 1MB. The user can adjust MG to any value once the
fork has occurred (not limited to > 1MB after the fork).
"Large block" means a block satisfying 1,000,000 bytes < block
size <= EB, where EB is as adjusted by REQ-4-1 and a regular block
is a block up to 1,000,000 bytes in size.
"Core rules" means all blocks <= 1,000,000 bytes (Base block size).
"Extended BU tx/sigops rules" means the existing additional consensus rules (1) and
(2) below, as formalized by BUIP040 [1] and used by the Bitcoin Unlimited
client's excessive checks for blocks larger than 1MB, extended with rule
(3) below:
1. maximum sigops per block is calculated based on the actual size of
a block using
max_block_sigops = 20000 * ceil((max(blocksize, 1000000) / 1000000))
2. maximum allowed size of a single transaction is 1,000,000 bytes (1MB)
3. maximum allowed number of sigops for a single transaction is 20k .
NOTE 1: In plain English, the maximum allowed sigops per block is
20K sigops per the size of the block, rounded up to nearest integer in MB.
i.e. 20K if <= 1MB, 40K for the blocks > 1MB and up to 2MB, etc.
## Requirements
### REQ-1 (fork by default)
The client (with UAHF implementation) shall default to activating
a hard fork with new consensus rules as specified by the remaining
requirements.
RATIONALE: It is better to make the HF active by default in a
special HF release version. Users have to download a version capable
of HF anyway, it is more convenient for them if the default does not
require them to make additional configuration.
NOTE 1: It will be possible to disable the fork behavior (see
REQ-DISABLE)
### REQ-2 (configurable activation time)
The client shall allow a "activation time" to be configured by the user,
with a default value of 1501590000 (epoch time corresponding to Tue
1 Aug 2017 12:20:00 UTC)
RATIONALE: Make it configurable to adapt easily to UASF activation
time changes.
NOTE 1: Configuring a "activation time" value of zero (0) shall disable
any UAHF hard fork special rules (see REQ-DISABLE)
### REQ-3 (fork block must be > 1MB)
The client shall enforce a block size larger than 1,000,000 bytes
for the fork block.
RATIONALE: This enforces the hard fork from the original 1MB
chain and prevents a re-organization of the forked chain to
the original chain.
### REQ-4-1 (require "fork EB" configured to at least 8MB at startup)
If UAHF is not disabled (see REQ-DISABLE), the client shall enforce
that the "fork EB" is configured to at least 8,000,000 (bytes) by raising
an error during startup requesting the user to ensure adequate configuration.
RATIONALE: Users need to be able to run with their usual EB prior to the
fork (e.g. some are running EB1 currently). The fork code needs to adjust
this EB automatically to a > 1MB value. 8MB is chosen as a minimum since
miners have indicated in the past that they would be willing to support
such a size, and the current network is capable of handling it.
### REQ-4-2 (require user to specify suitable *new* MG at startup)
If UAHF is not disabled (see REQ-DISABLE), the client shall require
the user to specify a "fork MG" (mining generation size) greater than
1,000,000 bytes.
RATIONALE: This ensures a suitable MG is set at the activation time so
that a mining node would produce a fork block compatible with REQ-3.
It also forces the user (miner) to decide on what size blocks they want to
produce immediately after the fork.
NOTE 1: The DEFAULT_MAX_GENERATED_BLOCK_SIZE in the released client needs
to remain 1,000,000 bytes so that the client will not generate invalid
blocks before the fork activates. At activation time, however, the "fork MG"
specified by the user (default: 2MB) will take effect.
### REQ-5 (max tx / max block sigops rules for blocks > 1 MB)
Blocks larger than 1,000,000 shall be subject to "Extended BU tx/sigops rules"
as follows:
1. maximum sigops per block shall be calculated based on the actual size of
a block using
`max_block_sigops = 20000 * ceil((max(blocksize_bytes, 1000000) / 1000000))`
2. maximum allowed size of a single transaction shall be 1,000,000 bytes
NOTE 1: Blocks up to and including 1,000,000 bytes in size shall be subject
to existing pre-fork Bitcoin consensus rules.
NOTE 2: Transactions exceeding 100,000 bytes (100KB) shall remain
non-standard after the activation time, meaning they will not be relayed.
NOTE 3: BU treats both rules (1) and (2) as falling under the Emergent
Consensus rules (AD). Other clients may choose to implement them as
firm rules at their own risk.
### REQ-6-1 (disallow special OP_RETURN-marked transactions with sunset clause)
Once the fork has activated, transactions consisting exclusively of a single OP_RETURN output, followed by a single minimally-coded data push with the specific magic data value of
Bitcoin: A Peer-to-Peer Electronic Cash System
(46 characters, including the single spaces separating the words, and
without any terminating null character) shall be considered invalid until
block 530,000 inclusive.
RATIONALE: (DEPRECATED - see NOTE 2) To give users on the legacy chain (or other fork chains)
an opt-in way to exclude their transactions from processing on the UAHF
fork chain. The sunset clause block height is calculated as approximately
1 year after currently planned UASF activation time (Aug 1 2017 00:00:00 GMT),
rounded down to a human friendly number.
NOTE 1: Transactions with such OP_RETURNs shall be considered valid again
for block 530,001 and onwards.
NOTE 2: With the changes in v1.6 of this specification, mandatory use
of SIGHASH_FORKID replay protection on UAHF chain makes the use of this
opt-out protection unnecessary. Clients should nevertheless implement this
requirement, as removing it would constitute a hard fork vis-a-vis the
existing network. The sunset clause in this requirement will take care
of its expiry by itself.
### REQ-6-2 (mandatory signature shift via hash type)
Once the fork has activated, a transaction shall be deemed valid only if
the following are true in combination:
- its nHashType has bit 6 set (SIGHASH_FORKID, mask 0x40)
- a magic 'fork id' value is added to the nHashType before the hash is
calculated (see note 4)
- it is digested using the new algorithm described in REQ-6-3
RATIONALE: To provide strong protection against replay of existing
transactions on the UAHF chain, only transactions signed with the new
hash algorithm and having SIGHASH_FORKID set will be accepted, by consensus.
NOTE 1: It is possible for other hard forks to allow SIGHASH_FORKID-protected
transactions on their chain by implementing a compatible signature.
However, this does require a counter hard fork by legacy chains.
NOTE 2: (DEPRECATED) ~~The client shall still accept transactions whose signatures~~
~~verify according to pre-fork rules, subject to the additional OP_RETURN~~
~~constraint introduced by REQ-6-1.~~
NOTE 3: (DEPRECATED) ~~If bit 6 is not set, only the unmodified nHashType will be used~~
~~to compute the hash and verify the signature.~~
NOTE 4: The magic 'fork id' value used by UAHF-compatible clients is zero.
This means that the change in hash when bit 6 is set is effected only by
the adapted signing algorithm (see REQ-6-3).
NOTE 5: See also REQ-6-4 which introduces a requirement for use of
SCRIPT_VERIFY_STRICTENC.
### REQ-6-3 (use adapted BIP143 hash algorithm for protected transactions)
Once the fork has activated, any transaction that has bit 6 set in its
hash type shall have its signature hash computed using a minimally revised
form of the transaction digest algorithm specified in BIP143.
RATIONALE: see Motivation section of BIP143 [2].
NOTE 1: refer to [3] for the specificaton of the revised transaction
digest based on BIP143. Revisions were made to account for non-Segwit
deployment.
### REQ-6-4 (mandatory use of SCRIPT_VERIFY_STRICTENC)
Once the fork has activated, transactions shall be validated with
SCRIPT_VERIFY_STRICTENC flag set.
RATIONALE: Use of SCRIPT_VERIFY_STRICTENC also ensures that the
nHashType is validated properly.
NOTE: As SCRIPT_VERIFY_STRICTENC is not clearly defined by BIP,
implementations seeking to be compliant should consult the Bitcoin C++
source code to emulate the checks enforced by this flag.
### REQ-7 Difficulty adjustement in case of hashrate drop
In case the MTP of the tip of the chain is 12h or more after the MTP 6 block
before the tip, the proof of work target is increased by a quarter, or 25%,
which corresponds to a difficulty reduction of 20% .
RATIONALE: The hashrate supporting the chain is dependent on market price and
hard to predict. In order to make sure the chain remains viable no matter what
difficulty needs to adjust down in case of abrupt hashrate drop.
### REQ-DISABLE (disable fork by setting fork time to 0)
If the activation time is configured to 0, the client shall not enforce
the new consensus rules of UAHF, including the activation of the fork,
the size constraint at a certain time, and the enforcing of EB/AD
constraints at startup.
RATIONALE: To make it possible to use such a release as a compatible
client with legacy chain / i.e. to decide to not follow the HF on one's
node / make a decision at late stage without needing to change client.
### OPT-SERVICEBIT (NODE_BITCOIN_CASH service bit)
A UAHF-compatible client should set service bit 5 (value 0x20).
RATIONALE: This service bit allows signaling that the node is a UAHF
supporting node, which helps DNS seeders distinguish UAHF implementations.
NOTE 1: This is an optional feature which clients do not strictly have to
implement.
NOTE 2: This bit is currently referred to as NODE_BITCOIN_CASH and displayed
as "CASH" in user interfaces of some Bitcoin clients (BU, ABC).
## References
[1] https://bitco.in/forum/threads/buip040-passed-emergent-consensus-parameters-and-defaults-for-large-1mb-blocks.1643/
[2] https://github.com/bitcoin/bips/blob/master/bip-0143.mediawiki#Motivation
[3] [Digest for replay protected signature verification accross hard forks](https://github.com/bitcoincashorg/bitcoincash.org/blob/master/spec/replay-protected-sighash.md)
[4] https://github.com/bitcoincashorg/bitcoincash.org/blob/master/spec/uahf-test-plan.md
END
protocol/network/messages.md
+31 -12
View File
@@ -2,11 +2,17 @@
The Bitcoin Cash Peer-to-Peer (P2P) Network protocol is a binary protocol used by Full Nodes and [SPV](/protocol/simple-payment-verification) Nodes, transmitted over TCP/IP.
Individual nodes on the Bitcoin Cash network connect and create a mesh network where each node is indirectly connected to many others via just a couple of hops.
In the original Satoshi implementation of the P2P protocol the design of INV and getdata have been used for propagating transaction data using the rules of the gossip protocol values: forwarding validated transactions to a few peer-nodes who send it to others until the entire network has the transaction. This emergent behavior of the P2P layer allows fast propagation without undue strain on any individual node.
In the original Satoshi implementation of the P2P protocol the design of INV and getdata have been used for propagating transaction data using the rules of the gossip protocol values: forwarding validated transactions to a few peer-nodes who send it to others until the entire network has the transaction.
This emergent behavior of the P2P layer allows fast propagation without undue strain on any individual node.
The P2P protocol is designed around messages. Each message is separate and self-contained. Nodes should be tolerant of message-types they do not understand. It is best to simply ignore those.
Detailed descriptions of the messages follows below. Generally speaking, each message is an event that the node can choose to respond to. Events range from notifications of new data (transactions/blocks/etc) and
actual requests for such data to be send and last the actual data being sent. Or, in some specific cases a `reject` message.
The P2P protocol is designed around messages.
Each message is separate and self-contained.
Nodes should be tolerant of message-types they do not understand.
It is best to simply ignore those.
Generally speaking, each message is an event that the node can choose to respond to.
Events can be notifications of new data (transactions/blocks/etc), requests for such data to be sent, or the sending of the data itself.
In some specific cases a message can indicate the rejection of another message, though this is optional and should not be relied upon.
These design decisions were made with consideration to communication with untrusted/uncooperative partners.
@@ -17,7 +23,6 @@ These design decisions were made with consideration to communication with untrus
The P2P network has a variety of message types.
All P2P messages follow a binary format with the following structure:
| Field | Length | Format | Description |
|--|--|--|--|
| net magic | 4 bytes | byte array<sup>[(BE)](/protocol/misc/endian/big)</sup> | See [net magic](#net-magic). |
@@ -26,15 +31,16 @@ All P2P messages follow a binary format with the following structure:
| 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. |
See [Example Message](#example-message) for a concrete example of this with a message that does not contain an extended payload.
### Net Magic
The network identifier is used to separate blockchains and test networks.
This reduces unnecessary load on peers, allowing them to rapidly ban nodes rather then forcing the peer to do a blockchain analysis before banning or disconnecting.
For Bitcoin Cash main net, the `net magic` field is always `0xE3E1F3E8`.
For Bitcoin Cash main net, the `net magic` field is always `0xE3E1F3E8` (the ASCII string, "cash", with each byte's highest bit set).
Any message received that does not begin with the `net magic` is invalid.
The `net magic` is designed to be unlikely to occur in normal data--the characters are rarely used upper ASCII, are not valid as UTF-8, and produce a large 32-bit integer with any alignment.
`0xE3E1F3E8` is the ASCII string, "cash", with each byte's highest bit set.
### Command String
@@ -91,11 +97,24 @@ Messages with an unrecognized `command string` are ignored by most implementatio
| thinblock | | |
| xblocktx | | |
| xthinblock | | |
| [xupdate](/protocol/p2p/xupdate) | *Communicates a change in peer capabilities* | BCHUnlimited
| [xversion](/protocol/p2p/xversion) | *Describes peer capabilities in an extensible manner* | BCHUnlimited
| xverack | *Response to an [xversion](/protocol/p2p/xversion) message* | BCHUnlimited
| [xupdate](/protocol/network/messages/xupdate) | *Communicates a change in peer capabilities* | BCHUnlimited
| [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
# Example message
## Example message
The below segments, when concatenated in order, create a sample [verack](/protocol/network/messages/verack) message.
| Label | Sample Value (Hexadecimal Representation) |
|-------|------|
| Net Magic<sup>[(BE)](/protocol/misc/endian/little)</sup> | `E3E1F3E8` |
| Command String ("verack")<sup>[(BE)](/protocol/misc/endian/big)</sup> | `76657261636B000000000000` |
| Payload Byte Count<sup>[(LE)](/protocol/misc/endian/little)</sup> | `00000000` |
| Payload Checksum<sup>[(LE)](/protocol/misc/endian/little)</sup> | `5DF6E0E2` |
Below is the full, concatenated sample message (in hexadecimal):
`E3E1F3E876657261636B000000000000000000005DF6E0E2`
# Node Specific Behavior
@@ -103,4 +122,4 @@ Messages with an unrecognized `command string` are ignored by most implementatio
### Payload Checksum
Bitcoin Unlimited does not validate the message checksum
Bitcoin Unlimited does not validate the message checksum since messages are sent via TCP which has its own checksum paradigm.
protocol/network/messages/feefilter.md
+1 -1
View File
@@ -8,4 +8,4 @@ The recipient node may, but is not required to, begin to perform this filtering
| Field | Length | Format | Description |
|--|--|--|--|
| minimum fee per byte | 8 bytes | unsigned 64 bit integer<sup>[(LE)](/protocol/misc/endian/little.md)</sup> | The minimum number of satoshis per byte in fees desired by the sender.
| minimum fee per byte | 8 bytes | unsigned 64 bit integer<sup>[(LE)](/protocol/misc/endian/little)</sup> | The minimum number of satoshis per byte in fees desired by the sender.
protocol/network/messages/verack.md
+3 -13
View File
@@ -1,4 +1,4 @@
# Handshake: Acknowledge ("verack")
# Handshake: Version Acknowledgement ("verack")
The `verack` message is sent in reply to a [version](/protocol/network/messages/version) message.
Sending a `verack` in response to a `version` message indicates to the remote that its connection and version has been accepted.
@@ -7,16 +7,6 @@ There is no version negotiation functionality between nodes; therefore if the no
This `verack` message consists of only a message header; the command string is "verack".
## Example Serialized Data
## Message Format
Net Magic<sup>[(BE)](/protocol/misc/endian/little)</sup>
`E3E1F3E8`
Command String ("verack")<sup>[(BE)](/protocol/misc/endian/big)</sup>
`76657261636B000000000000`
Payload Byte Count<sup>[(LE)](/protocol/misc/endian/little)</sup>
`00000000`
Payload Checksum<sup>[(LE)](/protocol/network/messages/message-checksum)</sup>
`5DF6E0E2`
This message has no contents.
protocol/network/messages/xupdate.md
+21
View File
@@ -0,0 +1,21 @@
<div class="cwikmeta">{
"title":"XUPDATE",
"related":["/protocol/network/messages","/protocol/network/messages/xversion"]
}</div>
# Handshake Extension: XVersion (“xversion”)
This message notifies a peer about changes to protocol parameters. It follows the same format as [xversion](/protocol/network/messages/xversion) protocol parameters. Implementations **SHOULD** only send changed parameters, rather than every parameter. Note that some XVERSION parameters are not changeable and therefore will be ignored if they appear in this message.
See the [xversion fields](/protocol/network/messages/xversion#xversion-fields) for detailed information about each parameter.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| number of values | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of values being sent. |
| values | variable | `number_of_values` * [xversion values](/protocol/network/messages/xversion#xversion-value-format) | The list of values to communicate. |
### Support
Supported by: **Bitcoin Unlimited**
protocol/network/messages/xverack.md
+8
View File
@@ -0,0 +1,8 @@
# Handshake Extension: XVersion Acknowledgement (“xverack”)
The `xverack` message is sent in reply to an [xversion](/protocol/network/messages/xversion) message.
Sending an `xverack` in response to a `version` message indicates to the remote that its XVersion values have been accepted.
## Message Format
This message has no contents.
protocol/network/messages/xversion.md
+45
View File
@@ -0,0 +1,45 @@
<div class="cwikmeta">{
"title":"XVERSION",
"related":["/protocol/network/messages","/protocol/network/messages/xupdate","/protocol/network/messages/xverack"]
}</div>
# Handshake Extension: XVersion (“xversion”)
This message notifies a peer about extended protocol parameters. This message MAY be sent during connection initialization. If sent, it MUST be sent immediately subsequent to the receipt of the [verack](/protocol/network/messages/verack.md) message, and before other non-initialization messages are sent.
## Message Format
| Field | Length | Format | Description |
|--|--|--|--|
| number of values | variable | [variable length integer](/protocol/formats/variable-length-integer) | The number of values being sent. |
| values | variable | `number_of_values` * [xversion values](#xversion-value-format) | The list of values to communicate. |
### XVersion Value Format
| Field | Length | Format | Description |
|--|--|--|--|
| field | variable | [variable length integer](/protocol/formats/variable-length-integer) | Indicates the field type of the value to follow. See [XVersion Fields](#xversion-fields). |
| size of value | variable | [variable length integer](/protocol/formats/variable-length-integer) | The size of the value to follow. |
| value | `size_of_value` bytes | bytes | The value for the preceding field type (`key`). The format of the value is defined by the `field`, but must be the specified number of bytes. |
#### XVersion Fields
XVersion field identifiers are 32 bits and split into a 16 bit prefix and 16 bit suffix. Each development group is assigned a prefix so that new identifiers do not accidentally conflict. Once a field identifier is created by group A, it should be used by other software both to receive that information from A and to present that information to other software. Therefore, group A **MUST NOT** change the syntax or semantics of a field once defined. To change a field, create a new identifier and deprecate (by no longer using the original identifier).
#### Prefix and Suffix Assignments
##### Prefix Assignments
| Group | Value |
|-------------------------|-------|
| Reserved for versioning | 0 |
| Bitcoin Cash Node | 1 |
| Bitcoin Unlimited | 2 |
See [xversionkeys.dat](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/xversionkeys.dat) for the most up-to-date field definitions defined by the BitcoinUnlimited full node.
Note that:
* *u64c* refers to a [variable length integer](/protocol/formats/variable-length-integer).
* *Changeable* fields MAY be changed during the course of a connection via the [xupdate](/protocol/network/messages/xupdate) message.
### Support
Supported by: **Bitcoin Unlimited**
protocol/p2p/xupdate.md
-18
View File
@@ -1,18 +0,0 @@
<div class="cwikmeta">{
"title":"XUPDATE",
"related":["/protocol","/protocol/p2p/xversion" ,"/protocol/p2p/xversionkeys"]
}</div>
*Notifies peers about an XVERSION configuration value update*
This message notifies a peer about changes to protocol parameters. It follows the same format as [XVERSION](/protocol/p2p/xversion.md) protocol parameters. Implementations **SHOULD** only send changed parameters, rather than every parameter. Note that some XVERSION parameters are not changeable and therefore will be ignored if they appear in this message.
See the [XVERSION](/protocol/p2p/xversion.md) message for detailed information about each parameter.
| compact int | compact int | variable bytes |... | compact int | 32 bytes |
|----------|---------|----------|---|---------|----------|
|[vector](/protocol/p2p/vector) size N of| key 1 | [vector](/protocol/p2p/vector) of bytes | | key N | [vector](/protocol/p2p/vector) of bytes
### Support
Supported by: **Bitcoin Unlimited**
protocol/p2p/xversion.md
-27
View File
@@ -1,27 +0,0 @@
<div class="cwikmeta">{
"title":"XVERSION",
"related":["/protocol","/protocol/p2p/xupdate","/protocol/p2p/xversionkeys"]
}</div>
*Notifies peers about a protocol configuration value*
This message notifies a peer about extended protocol parameters. This message MAY be sent during connection initialization. If sent, it MUST be sent immediately subsequent to the receipt of the [VERACK](/protocol/p2p/verack.md) message, and before other non-initialization messages are sent.
| compact int | compact int | variable bytes |... | compact int | variable bytes |
|----------|---------|----------|---|---------|----------|
|[vector](/protocol/p2p/vector) size N of| key 1 | value 1 [vector](/protocol/p2p/vector) of bytes | | key N | value N [vector](/protocol/p2p/vector) of bytes
The *value* is a vector of bytes. These bytes can be an object that is itself serialized, but **MUST** exist within the vector "envelope" so that implementations that do not recognize a field can skip it. The serialization format of the bytes inside the "envelope" is defined by the creator of the key, however, Bitcoin P2P network serialization is recommended since it is also used to encode/decode all the messages of this protocol.
See [XVERSION specification](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/doc/xversionmessage.md) for additional details.
### XVERSION Fields
XVERSION field identifiers are 32 bits and split into a 16 bit prefix and 16 bit suffix. Each development group is assigned a prefix so that new identifiers do not accidentally conflict. Once a field identifier is created by group A, it should be used by other software both to receive that information from A and to present that information to other software. Therefore, group A **MUST NOT** change the syntax or semantics of a field once defined. To change a field, create a new identifier and deprecate (by no longer using the original identifier).
#### Prefix and Suffix Assignments
See [xversionkeys](/protocol/p2p/xversionkeys.md) for a full list of assigned prefixes and field definitions.
### Support
Supported by: **Bitcoin Unlimited**
protocol/p2p/xversionkeys.md
-24
View File
@@ -1,24 +0,0 @@
<div class="cwikmeta">{
"title":"XVERSIONKEYS",
"related":["/protocol","/protocol/p2p/xversion","/protocol/p2p/xupdate"]
}</div>
### Prefix Assignments
| Group | Value |
|-------------------------|-------|
| Reserved for versioning | 0 |
| Bitcoin Cash Node | 1 |
| Bitcoin Unlimited | 2 |
#### Field Assignments
See [xversionkeys.dat](https://github.com/BitcoinUnlimited/BitcoinUnlimited/blob/bucash1.7.0.0/src/xversionkeys.dat) for the most up-to-date field definitions defined by the BitcoinUnlimited full node.
Note that:
* *u64c* refers to a [compact int](/protocol/p2p/compact__int.md) serialization of an unsigned 64-bit value.
* *Changeable* fields MAY be changed during the course of a connection via the [XUPDATE](/protocol/p2p/xupdate) message.
### Support
Supported by: **Bitcoin Unlimited**