Skip to content

Commit 2fead0c

Browse files
darosiordarosior
committed
bip-0054: document the test vectors
1 parent 30b0084 commit 2fead0c

File tree

2 files changed

+109
-1
lines changed

2 files changed

+109
-1
lines changed

‎bip-0054.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,14 +158,20 @@ forward-compatible with the changes proposed in this BIP.
158158

159159
An implementation of BIP54 for Bitcoin Core is available [here][inquisition-implem].
160160

161+
## Test vectors
162+
163+
Documented test vectors are available [here](./bip-0054/test_vectors/) for all mitigations
164+
introduced in this BIP.
165+
161166
## Acknowledgements
162167

163168
This document builds upon an [earlier proposal][BIP-XXXX] by Matt Corallo.
164169

165170
The authors would like to thank everyone involved in researching the most appropriate mitigation for
166171
each of these bugs. We would like to thank in particular Anthony Towns and Sjors Provoost for their
167172
direct contributions to this proposal, as well as @0xb10c and Brian Groll for providing the authors
168-
with data to analyze the proposed mitigations.
173+
with data to analyze the proposed mitigations. Thanks to Chris Stewart for digging up historical
174+
violations to the new transaction size rule, which are partially reused in this BIP's test vectors.
169175

170176
## Copyright
171177

‎bip-0054/test_vectors/README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
## BIP54 test vectors
2+
3+
This folder contains a set of test vectors for each mitigation introduced in the BIP. This document
4+
presents them in more details.
5+
6+
The code used to generate half of the test vectors is included with the implementation and available
7+
[here][other-vectors]. The other half requires mining mainnet blocks and is [published
8+
separately][bip54-miner]. In both cases it is implemented as a regular Bitcoin Core unit test, and
9+
the test vectors are persisted as a JSON file if the `UPDATE_JSON_TESTS` preprocessor directive is
10+
set (off by default).
11+
12+
To compile the [header][header-miner] and [block][block-miner] miners you may have to link to
13+
libatomic explicitly. This can be achieved like so:
14+
```
15+
cmake -B atomicbuild -DAPPEND_LDFLAGS="-latomic"
16+
cmake --build atomicbuild/ -j $(nproc)
17+
```
18+
19+
[Premined headers][premined-headers] are also provided along with the header miner to allow changing
20+
some of the last headers without having to re-generate the whole chain.
21+
22+
23+
### Difficulty adjustment exploits
24+
25+
The [`timestamps.json`](./timestamps.json) test vectors exercise the two constraints on block header
26+
timestamps introduced by BIP54 to mitigate the Timewarp and Murch-Zawy attacks. Each test case
27+
features a chain of mainnet headers starting from the genesis block, and whether this header chain
28+
is valid by BIP54 rules. Each test case also contains a comment describing why this particular chain
29+
is (in)valid according to BIP54. All test cases are valid according to current Bitcoin consensus
30+
rules. It is intended to be used to test a BIP54 implementation by feeding the header chain to a
31+
Bitcoin node implementation, enforcing the BIP54 rules on this chain from genesis.
32+
33+
The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
34+
JSON object features the following entries:
35+
- `header_chain`: a JSON array of strings. An ordered list of hex-encoded mainnet block headers.
36+
- `valid`: a JSON boolean. Whether this chain of headers is valid according to BIP54.
37+
- `comment`: a JSON string. Description of the test case.
38+
39+
For the purpose of testing a Timewarp fix, a Timewarp attack was included early on in the history of
40+
testnet3. An implementer of BIP54 may want to ensure that syncing testnet3 by enforcing BIP54 since
41+
genesis will treat block `00000000118da1e2165a19307b86f87eba814845e8a0f99734dce279ca3fb029` as
42+
invalid.
43+
44+
45+
### Long block validation time
46+
47+
The [`sigops.json`](sigops.json) file contains test vectors for the limit on the number of
48+
potentially-executed legacy signature operations in a single transaction, introduced by BIP54 in
49+
order to mitigate long block validation times. Each test case represents a transaction and whether a
50+
block containing it would be valid according to BIP54. The test cases feature an extensive set of
51+
combinations of inputs and output types, ways to run into the limit, historical violations and some
52+
pathological transactions exhibiting the specific implementation details. All test cases but those
53+
belonging to this last category feature transactions that are valid under current Bitcoin consensus
54+
rules. Each test case also features a comment describing why the transaction is (in)valid according
55+
to BIP54.
56+
57+
The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
58+
JSON object features the following entries:
59+
- `spent_outputs`: a JSON array of strings. An ordered list of hex-encoded Bitcoin-serialized
60+
transaction outputs spent by each input of this test case's transaction.
61+
- `tx`: a JSON string. A hex-encoded Bitcoin-serialized transaction to be evaluated.
62+
- `valid`: a JSON boolean. Whether this transaction is valid according to current consensus rules
63+
supplemented by BIP54.
64+
- `comment`: a JSON string. Description of the test case.
65+
66+
67+
### Merkle tree malleability with 64-byte transactions
68+
69+
The [`txsize.json`](./txsize.json) file contains test cases exercising the new constraint on
70+
non-witness transaction size introduced in BIP54. Each test case contains a transaction and whether
71+
it would be valid according to BIP54, as well as a comment describing why it is (in)valid. All test
72+
cases are otherwise valid according to current Bitcoin consensus rules.
73+
74+
The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
75+
JSON object features the following entries:
76+
- `tx`: a JSON string. A hex-encoded Bitcoin-serialized transaction to be evaluated.
77+
- `valid`: a JSON boolean. Whether this transaction is valid according to BIP54.
78+
- `comment`: a JSON string. Description of the test case.
79+
80+
81+
### Possibility of duplicate coinbase transactions
82+
83+
The [`coinbases.json`](./coinbases.json) file contains test cases exercising the new restrictions on
84+
coinbase transactions introduced in BIP54 to prevent duplicate coinbase transactions without
85+
resorting to BIP30 validation. Each test case contains a chain of mainnet blocks (including the
86+
genesis block), and whether this block chain is valid according to BIP54. All test cases are valid
87+
according to current Bitcoin's consensus rules, except one that features a block containing a
88+
coinbase transaction timelocked to a future block height.
89+
90+
The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
91+
JSON object features the following entries:
92+
- `block_chain`: a JSON array of strings. An ordered list of hex-encoded mainnet blocks.
93+
- `valid`: a JSON boolean. Whether this block chain is valid according to current Bitcoin consensus
94+
rules supplemented by BIP54.
95+
- `comment`: a JSON string. Description of the test case.
96+
97+
98+
[bip54-miner]: https://github.com/darosior/bitcoin/blob/bip54_miner/commits
99+
[header-miner]: https://github.com/darosior/bitcoin/blob/bip54_miner/src/test/bip54_header_miner.cpp
100+
[block-miner]: https://github.com/darosior/bitcoin/blob/bip54_miner/src/test/bip54_block_miner.cpp
101+
[other-vectors]: https://github.com/darosior/bitcoin/blob/2509_inquisition_consensus_cleanup/src/test/bip54_tests.cpp
102+
[premined-headers]: https://github.com/darosior/bitcoin/blob/bip54_miner/src/test/bip54_premined_headers.h

0 commit comments

Comments
 (0)