Skip to content

BIP54: Consensus Cleanup test vectors #2015

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonatack merged 3 commits into from
Nov 25, 2025
Merged

BIP54: Consensus Cleanup test vectors #2015

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
89dfe03
bip-0054: add a reference implementation section
darosior Oct 19, 2025
30b0084
bip-0054: add test vectors for each mitigation
darosior Sep 16, 2025
0777a81
bip-0054: document the test vectors
darosior Oct 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion bip-0054.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,14 +154,24 @@ knowledge, there does not exist an open source reference broadly in use today fo
We encourage mining pools to update their software to craft coinbase transactions that are
forward-compatible with the changes proposed in this BIP.

## Reference implementation

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

## Test vectors

Documented test vectors are available [here](./bip-0054/test_vectors/) for all mitigations
introduced in this BIP.

## Acknowledgements

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

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

## Copyright

Expand Down Expand Up @@ -232,3 +242,4 @@ notably of Bitcoin Core but also of all other implementations the authors are aw
[Delving duplicable]: https://delvingbitcoin.org/t/great-consensus-cleanup-revival/710/4
[Core 0.16.1]: https://bitcoincore.org/en/releases/0.16.1
[Core 29.0]: https://bitcoincore.org/en/releases/29.0
[inquisition-implem]: https://github.com/darosior/bitcoin/tree/2509_inquisition_consensus_cleanup
102 changes: 102 additions & 0 deletions bip-0054/test_vectors/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
## BIP54 test vectors

This folder contains a set of test vectors for each mitigation introduced in the BIP. This document
presents them in more detail.

The code used to generate half of the test vectors is included with the implementation and available
[here][other-vectors]. The other half requires mining mainnet blocks and is [published
separately][bip54-miner]. In both cases it is implemented as a regular Bitcoin Core unit test, and
the test vectors are persisted as a JSON file if the `UPDATE_JSON_TESTS` preprocessor directive is
set (off by default).

To compile the [header][header-miner] and [block][block-miner] miners you may have to link to
libatomic explicitly. This can be achieved like so:
```
cmake -B atomicbuild -DAPPEND_LDFLAGS="-latomic"
cmake --build atomicbuild/ -j $(nproc)
```

[Premined headers][premined-headers] are also provided along with the header miner to allow changing
some of the last headers without having to re-generate the whole chain.


### Difficulty adjustment exploits

The [`timestamps.json`](./timestamps.json) test vectors exercise the two constraints on block header
timestamps introduced by BIP54 to mitigate the Timewarp and Murch-Zawy attacks. Each test case
features a chain of mainnet headers starting from the genesis block, and whether this header chain
is valid by BIP54 rules. Each test case also contains a comment describing why this particular chain
is (in)valid according to BIP54. All test cases are valid according to current Bitcoin consensus
rules. It is intended to be used to test a BIP54 implementation by feeding the header chain to a
Copy link

@ariard ariard Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Started to look on the timestamps.json file, I’m understanding that the headers for the 9 chain of headers have been drawn the historical mainnet chain, and then permutation of a subset of those chain of headers have been made accordingly to make some of them (in)valid according to BIP54, assuming that BIP54 would have been enforced as a rule since the genesis block.

Given the difficulty adjustment is proposing rules for the validation state where block is equal to height N % 2016 equal 0 and the state where block is equal to height N % 2016 equal 2016, and there is at least >, =, < to test for each boundary check, there should be at least 6 tests. From checking timestamps.json, there at least 9 test chains in the file.

Wondering if there is full coverage for the first equality check, given you have > and = to test each for the variations of minus 7200 (and then same, you have >, =, < I think that are valuable to test for).

Copy link
Member Author

@darosior darosior Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not exactly. Only the genesis block's header is in common with the historical main chain. But you are correct in how it's used: creating various forks which test the Timewarp and Murch-Zawy fixes in various conditions.

Rather than >, =, <, i think what's important to test is the boundary: the last value for which the test pass and the first for which it fails. So using your terms it would be <, =. Plus of course also testing that it does not trigger at other heights, especially those off-by-one from the height that needs to be checked.

At the moment the tests exercise for Timewarp that:

  • The check is not performed on heights in the difficulty adjustment period (heights 41 and 2001)
  • The lowest value for which the check passes for the correct height (2016)
  • The first value for which the check fails for the correct height
  • The check is not performed on the height just preceding the one on which it should be enforced (2015) to check for off-by-one in implementations
  • The check is not performed on the height just following the one on which it should be enforced (2017) to check for off-by-one in implementations

At the moment the tests exercise for Murch-Zawy that:

  • The check fails on the first value for which it is supposed to fail
  • The passes on the first value for which it is not supposed to fail
  • The check is not enforced on the height just following the one on which it should be enforced (4032 instead of 4031)

Which test cases do you think should be added exactly and for what reason? I think the above is sufficient for a first shot, but i'm happy to consider re-mining the chain of headers and add the test cases you would suggest in a followup.

Copy link

@ariard ariard Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Which test cases do you think should be added exactly and for what reason?

I think it’s on the situation where the height of the checked block is a difficulty-adjustement block and verifying the variation for the triplet where the previous block time is T - 7199, 7200 and 7201 so testing the boundary of MAX_TIMEWARP when current block time and previous block time are 2 temporal points with strictly MAX_TIMEWARP between them. Thanks already for more comment on what is already covered.

Bitcoin node implementation, enforcing the BIP54 rules on this chain from genesis.

The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
JSON object features the following entries:
- `header_chain`: a JSON array of strings. An ordered list of hex-encoded mainnet block headers.
- `valid`: a JSON boolean. Whether this chain of headers is valid according to BIP54.
- `comment`: a JSON string. Description of the test case.

For the purpose of testing a Timewarp fix, a Timewarp attack was included early on in the history of
testnet3. An implementer of BIP54 may want to ensure that syncing testnet3 by enforcing BIP54 since
genesis will treat block `00000000118da1e2165a19307b86f87eba814845e8a0f99734dce279ca3fb029` as
invalid.
Copy link

@ariard ariard Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very open question: how hard it would be to coordinate a Murch-Zawy attack variant on testnet3.

Copy link
Member Author

@darosior darosior Nov 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'd need some non-trivial hash power to mine at least 3 difficulty adjustment periods without publishing them. We'd also need to ramp up the difficulty first, which is currently 1 on testnet3. A Murch-Zawy can also be done on testnet4, for what it's worth.

If we can find someone with some hashrate that could be interesting to do.

Copy link

@ariard ariard Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I’m reading back the computational cost estimations for a Murch-Zawy attack. Always interesting to have coverage for edge case, even if it’s only to test more the novel code logic.



### Long block validation time

The [`sigops.json`](sigops.json) file contains test vectors for the limit on the number of
potentially-executed legacy signature operations in a single transaction, introduced by BIP54 in
order to mitigate long block validation times. Each test case represents a transaction and whether a
block containing it would be valid according to BIP54. The test cases feature an extensive set of
combinations of inputs and output types, ways to run into the limit, historical violations and some
pathological transactions exhibiting the specific implementation details. All test cases but those
belonging to this last category feature transactions that are valid under current Bitcoin consensus
rules. Each test case also features a comment describing why the transaction is (in)valid according
to BIP54.

The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
JSON object features the following entries:
- `spent_outputs`: a JSON array of strings. An ordered list of hex-encoded Bitcoin-serialized
transaction outputs spent by each input of this test case's transaction.
- `tx`: a JSON string. A hex-encoded Bitcoin-serialized transaction to be evaluated.
- `valid`: a JSON boolean. Whether this transaction is valid according to current consensus rules
supplemented by BIP54.
- `comment`: a JSON string. Description of the test case.


### Merkle tree malleability with 64-byte transactions

The [`txsize.json`](./txsize.json) file contains test cases exercising the new constraint on
non-witness transaction size introduced in BIP54. Each test case contains a transaction and whether
it would be valid according to BIP54, as well as a comment describing why it is (in)valid. All test
cases are otherwise valid according to current Bitcoin consensus rules.

The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
JSON object features the following entries:
- `tx`: a JSON string. A hex-encoded Bitcoin-serialized transaction to be evaluated.
- `valid`: a JSON boolean. Whether this transaction is valid according to BIP54.
- `comment`: a JSON string. Description of the test case.
Copy link

@ariard ariard Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a read of the sigops.json but I cannot comment directly on it because it is considered as a “diff too large” by Github.

On the test vector: "Mixed input types reaching exactly 2500 BIP54-sigops + a future Segwit program input”, I think it could be valuable to multiply it for the whole range of future Segwit program (i.e from OP_02 to OP_16) to ensure the CheckSigopsBIP54 parser works well.

Copy link
Member Author

@darosior darosior Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now i think that would be overkill, each of these cases takes quite a lot of space and i don't think there is much value in testing every single Segwit version here. We already test for versions 0, 1 and 2. Maybe i could add a version 16 in a followup if you really think it's worthwhile.

Copy link

@ariard ariard Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know it’s a bit overkill…on the same time the CheckSigopsBIP54 parser it's consensus. Maybe it’s worthwhile to add it in a follow-up when there are more test coverage vectors worthy to add.



### Possibility of duplicate coinbase transactions

The [`coinbases.json`](./coinbases.json) file contains test cases exercising the new restrictions on
coinbase transactions introduced in BIP54 to prevent duplicate coinbase transactions without
resorting to BIP30 validation. Each test case contains a chain of mainnet blocks (including the
genesis block), and whether this block chain is valid according to BIP54. All test cases are valid
according to current Bitcoin's consensus rules, except one that features a block containing a
coinbase transaction timelocked to a future block height.

The test vector file features a JSON array of JSON objects, each corresponding to a test case. Each
JSON object features the following entries:
- `block_chain`: a JSON array of strings. An ordered list of hex-encoded mainnet blocks.
- `valid`: a JSON boolean. Whether this block chain is valid according to current Bitcoin consensus
rules supplemented by BIP54.
- `comment`: a JSON string. Description of the test case.


[bip54-miner]: https://github.com/darosior/bitcoin/blob/bip54_miner/commits
[header-miner]: https://github.com/darosior/bitcoin/blob/bip54_miner/src/test/bip54_header_miner.cpp
[block-miner]: https://github.com/darosior/bitcoin/blob/bip54_miner/src/test/bip54_block_miner.cpp
[other-vectors]: https://github.com/darosior/bitcoin/blob/2509_inquisition_consensus_cleanup/src/test/bip54_tests.cpp
[premined-headers]: https://github.com/darosior/bitcoin/blob/bip54_miner/src/test/bip54_premined_headers.h
Loading