bip54: describe the tree format of the timestamp test vectors #2308

pull FlashWayne wants to merge 2 commits into bitcoin:master from FlashWayne:bip54-vectors-readme changing 1 files +14 −3

FlashWayne commented at 12:11 PM on September 25, 2026: none

977300d restructured timestamps.json into a tree so the common headers aren't repeated for every test case, but the README in bip-0054/test_vectors/ still describes the old format: a JSON array of objects with header_chain, valid and comment. The file no longer has a header_chain key. The root is an object with block_headers and extensions, and only the leaves carry valid and comment.

This updates the format description to match the file and the way bip54_tests.cpp reads it. Inner nodes have block_headers and extensions. Leaves have block_headers, valid and comment. A test case's header chain is the concatenation of block_headers from the root to the leaf, starting at genesis. I walked the file with a small script to check this: 9 test cases, every node matches one of the two shapes, and the root starts with the genesis header.

bip54: describe the tree format of the timestamp test vectors

Since 977300d timestamps.json is a tree of nodes with block_headers and
either extensions or valid/comment, but the README still described the
earlier flat array of objects with a header_chain entry.

167b16698e

in bip-0054/test_vectors/README.md:34 in 167b16698e

  29 | @@ -30,9 +30,17 @@ is (in)valid according to BIP54.  All test cases are valid according to current
  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 | +To avoid repeating the headers that test cases have in common, the test vector file is a tree of
  37 | +JSON objects rather than a list. Each node features the following entries:

murchandamus commented at 2:21 PM on September 25, 2026:

The README should describe the new structure without referencing the obsolete old structure. The point is that the test vectors can be used by future readers, not to document how they were changed in perpetuity. The change of the structure could be documented in the Changelog on the BIP, if the BIP owners think it’s useful.

in bip-0054/test_vectors/README.md:43 in 167b16698e

  41 | +- `extensions`: a JSON array of JSON objects. The child nodes, each extending this node's header
  42 | +  chain. Only present on inner nodes.
  43 | +
  44 | +Each leaf node corresponds to a test case, whose header chain is made of the `block_headers` of every
  45 | +node on the path from the root to this leaf, in order. Instead of `extensions`, leaf nodes feature
  46 | +the following entries:

murchandamus commented at 2:23 PM on September 25, 2026:

This paragraph needs to be improved. Especially “Instead of extensions”… makes no sense.

murchandamus commented at 2:24 PM on September 25, 2026: member

I agree that this README should be updated, but this PR has room for improvement.
murchandamus added the label Proposed BIP modification on Sep 25, 2026
murchandamus added the label Pending acceptance on Sep 25, 2026
murchandamus commented at 2:25 PM on September 25, 2026: member

cc: @darosior
darosior commented at 2:53 PM on September 25, 2026: member

Good call, i somehow forgot to include that in #2122.
murchandamus added the label PR Author action required on Sep 25, 2026

bip54: reword test vector tree description

Describe the tree without reference to the previous format, and list the
entries common to all nodes, to inner nodes and to leaf nodes separately.

d5834b4faa

FlashWayne commented at 3:51 PM on September 25, 2026: none

Thanks, reworded in d5834b4. The README now only describes the current tree structure, with the entries common to all nodes, to inner nodes and to leaves listed separately. Happy to squash if you prefer a single commit.

Contributors

FlashWayne

murchandamus

darosior

Labels

Proposed BIP modification Pending acceptance PR Author action required