stale-blocks

Dataset of stale headers and blocks observed on the Bitcoin network.

Using this dataset

The dashboard at bitcoin-data.github.io/stale-blocks shows the current contents of the dataset: the stale-block rate over time and every stale block with its decoded header.

The data itself lives in two places:

• stale-blocks.csv: one row per stale block, with its height, its hash and, where known, the raw block header as hex.
• blocks/: the full blocks, where we have them, as binary files named <height>-<hash>.bin.

Releases of this repository are archived on Zenodo, which mints a DOI for each of them. The DOI above covers all versions and always resolves to the newest one:

bitcoin-data/stale-blocks: Dataset of stale headers and blocks observed on the Bitcoin network. https://doi.org/10.5281/zenodo.22667157

Every release also has a version DOI of its own, listed on the Zenodo page. Cite that one to point at the exact snapshot of the data that was used.

The data is public domain (CC0 1.0) and attribution isn't required, but it helps others find the dataset.

Contributing stale-block headers

Ideally, stale-block hashes should be provided along with the corresponding block-header. A hash without a block header could easily be fake.

Stale block data can be queried via the getchaintips RPC of Bitcoin Core. The get-data.py script can be used to directly query the stale-blocks and their headers. It produces CSV output in the same format as the stale-blocks.csv file. Tips that are active or invalid are already filtered.

To automatically add your data to stale-blocks.csv you can use the following:

python3 get-data.py
git diff stale-blocks.csv

Create a commit and open a PR. Keep in mind that this allows to figure out how long you've been running a Bitcoin node. If that's a problem, you can also submit your data to the project's maintainer to contribute anonymously.

Contributing full stale blocks

Where possible, it's favorable to have the full blocks belonging to the stale block headers. The get-data.py script will try to fetch them and store the full blocks as binary blobs in the blocks directory. Feel free to commit these too.

The full blocks can be imported back to a Bitcoin node with, for example:

cat blocks/813210-000000000000000000021c9f203786c0adcd7ae9a68a25d5e430d2a3dba613d5.bin | xxd -p | tr -d $'\n' | bitcoin-cli -stdin submitblock

Show missing headers and blocks

To list the headers and block-files missing from the dataset, the following command can be used:

$ python3 get-data.py --show-missing
...
Missing blockfile 845869 00000000000000000000858fe3cb999f449bcbfcadd3bdb240641b6b9c39bb30
Missing blockfile 833411 000000000000000000018450917aeae08339ffd3172807420dd35c736032898f
Missing header 824221 00000000000000000003a0653dbab14cc0f6fef121442b29d6b4005cdcdbc0d5
...

License

This repository contains both code and data, which are licensed separately:

• Code (in get-data.py, ci/* and other source files) is licensed under the MIT License. See LICENSE.
• Data (in stale-blocks.csv and blocks/*) is dedicated to the public domain under CC0 1.0. See LICENSE-DATA.