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

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.

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

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.

darosior commented at 2:50 PM on September 28, 2026: member

The latest version looks pretty good, but it think it is important to conserve the description of the data format, in particular the type of the top-level object. I think we can also provide a slightly clearer idea of nested JSON objects representing a chain of headers, with a hint about how implementers can parse it.

What do you think of the following?

<details> <summary>Click to expand suggestion</summary>

The test vector file contains a single JSON object, with child objects nested recursively in extensions arrays. Each object contains a segment of a header chain, and its children contain alternative continuations of that chain. Each path from the top-level object to a leaf represents one complete test case, allowing test cases to share common prefixes.

Every object contains:

block_headers: a JSON array of strings containing consecutive, hex-encoded mainnet block headers. The top-level object's headers start with genesis. Each child object's headers directly follow the last header of its parent.

An object that branches into further continuations also contains:

extensions: a JSON array of child objects with the same format.

A leaf object has no extensions entry and instead contains:

valid: a JSON boolean indicating whether the complete header chain is valid according to BIP54.
comment: a JSON string describing the test case.

To reconstruct a test case's header chain, concatenate the block_headers arrays along the path from the top-level object to that test case's leaf, in that order.

</details>

Also, could you squash your commits?

bip54: describe the tree format of the timestamp test vectors

Since 977300d timestamps.json is a single JSON object whose children are
nested recursively in extensions arrays, with valid and comment only on the
leaves, but the README still described a flat array of objects with a
header_chain entry.

b58f8ef865

FlashWayne force-pushed on Sep 28, 2026

FlashWayne commented at 2:57 PM on September 28, 2026: none

Thanks, applied your wording and squashed into a single commit.

darosior approved

darosior commented at 3:02 PM on September 28, 2026: member

ACK b58f8ef865dfb0768a5582905e4718d0f9e03076

jonatack removed the label Pending acceptance on Sep 28, 2026

jonatack removed the label PR Author action required on Sep 28, 2026

jonatack merged this on Sep 28, 2026

jonatack closed this on Sep 28, 2026