Blocklore
Esc

Type to search every published claim: statements, sources and topics.

Enter opens the claim; with no match, suggests the questionUp and down to move
976,842

A claim is the atomic unit of Blocklore: one statement, the sources that support it with exact locators and quotes, the machine checks that confirm it against the chain or the code, and the history of every change to it. Pages, proposals, debates, the Pulse and the digests are views over claims.

The normative schema is code: core/src/schema.ts (zod). This document explains it. When they disagree, the code wins and this document has a bug.

A complete example

id: taproot.activation-height
statement: >-
  Taproot's consensus rules have been enforced on mainnet since block 709,632, mined on
  14 November 2021.
kind: event
topics: [taproot]
depth: user
status: established
confidence: high
people: []
sources:
  - tier: T1
    kind: code
    title: Bitcoin Core chainparams.cpp, mainnet Taproot deployment
    url: https://github.com/bitcoin/bitcoin/blob/<commit>/src/kernel/chainparams.cpp#L110-L113
    locator: CMainParams, DEPLOYMENT_TAPROOT
    quote: min_activation_height = 709632
    accessed: 2026-11-20
    supports: direct
  - tier: T2
    kind: optech
    title: Bitcoin Optech Newsletter #175
    url: https://bitcoinops.org/en/newsletters/2021/11/17/
    locator: News, Taproot activated
    quote: <a short exact sentence from the page>
    accessed: 2026-11-20
    supports: direct
checks:
  - type: code.contains
    repo: bitcoin/bitcoin
    ref: <40-hex commit>
    path: src/kernel/chainparams.cpp
    text: min_activation_height = 709632
  - type: chain.block-hash
    height: 709632
    expect: <64-hex block hash>
first_seen: { time: 2026-11-20T15:00:00Z, height: 976744 }
last_verified:
  time: 2026-11-20T15:00:00Z
  height: 976744
  run: 2026-11-20-seed
  method: quotes 2/2, code 1/1, chain 1/1 (esplora pair agreed)
run: 2026-11-20-seed
related: [segwit.witness-versions]
revisions:
  - rev: 1
    at: { time: 2026-11-20T15:00:00Z, height: 976744 }
    run: 2026-11-20-seed
    change: created

Fields

FieldRequiredMeaning
idyes<primary topic>.<slug>, lowercase, [a-z0-9-]. Never changes and never reused. A claim that must say something different in substance is superseded by a new id.
statementyesOne self-contained statement in the brain's voice (EDITORIAL.md). Readable on its own and in sequence with its section. 12 to 80 words. Numbers carry units. No em dashes.
kindyesdefinition, fact, mechanism, event, trace, stance, argument or open-question.
topicsyesTopic slugs. The first is the primary topic and the folder the file lives in.
depthyesThe lowest reader level the claim is written for: curious, user, holder, builder, researcher.
statusyesestablished, contested, speculative or superseded.
confidenceyeshigh, medium or low (meanings below).
peopleyesNamed people the statement mentions or attributes to. Non-empty means the human gate.
attributed_tofor stance, argumentWho holds the position: { name, url } per person or group, linking to where they said it.
sourcesyes, 1 or moreSee Sources.
checksnoDeterministic checks against the chain or code. See Checks.
first_seenyesWhen and at what block height the brain first published the claim.
last_verifiedyesWhen, at what height, by which run and how the claim was last re-checked.
runyesThe research run that produced the current revision.
relatednoClaim ids a reader should see next.
supersedes, superseded_bynoClaim ids, when one claim replaces another.
reviewwhen gated{ reasons, by, at, note }: why the gate held it and who let it through.
revisionsyesThe append-only change log. See Revisions.

Kinds

  • definition: what a term means. "A UTXO is ..."
  • fact: a checkable state of the world. "The block subsidy is 3.125 BTC since block 840,000."
  • mechanism: how something works. "Nodes recompute the target every 2,016 blocks by ..."
  • event: something that happened at a time or height.
  • trace: where an idea lives in specs, code and review history. "BIP 341's signature hash is implemented in Bitcoin Core's SignatureHashSchnorr in src/script/interpreter.cpp."
  • stance: a named person's or group's public position, dated, in their own words, linked. Always attributed, never the brain's view. Always gated.
  • argument: a reason given for or against a proposal or position, attributed to who makes it. Always gated.
  • open-question: something unresolved, stated as a question with what would resolve it.

Status

  • established: the sources agree and nothing credible disputes it.
  • contested: informed people disagree about it. Every contested claim links the sides.
  • speculative: a projection, a proposal's claimed effect, or a result not yet reproduced.
  • superseded: no longer current. Kept, linked to its replacement, shown in the time machine.

Confidence

  • high: verified against the chain or the code, or supported directly by two or more independent T1 or T2 sources.
  • medium: supported directly by one T1 or T2 source, not mechanically verified.
  • low: supported only partially, only by T3 or T4 sources, or by inference the verifier accepted.

A claim whose sources are all T3 or T4 carries a visible "media and social sources only" label, whatever its confidence.

Sources

- tier: T1                # T1, T2, T3, T4 (SOURCES.md)
  kind: bip               # see the list below
  title: BIP 341          # what a reader sees
  url: https://...        # the exact locator
  locator: Specification, Script validation rules   # where inside it, in words
  quote: an exact passage of at most 50 words found at url
  published: 2020-01-19   # optional, when the source said it
  accessed: 2026-11-20    # when the brain read it
  supports: direct        # direct, partial or background
kindTierLocator formHow the checker reads it
bipT1github.com/bitcoin/bips/blob/<commit>/bip-NNNN.(mediawiki|md), optional #anchorraw file at that commit
boltT1github.com/lightning/bolts/blob/<commit>/NN-name.mdraw file at that commit
codeT1github.com/<org>/<repo>/blob/<commit>/<path>#Lx-Lyraw file at that commit
commitT1github.com/<org>/<repo>/commit/<commit>commit message and metadata (GitHub API)
pr, issueT1github.com/<org>/<repo>/pull/<n>, optional #issuecomment-<id> or #discussion_r<id>title, body and the named comment (GitHub API)
release-notesT1release notes file in the repo at a commit, or the project's release pageraw file or page text
mailing-listT1gnusha.org/pi/bitcoindev/<message-id>/ or mailing-list.bitcoindevs.xyz/bitcoindev/<message-id>/; older posts at lists.linuxfoundation.org/pipermail/<list>/<yyyy-Month>/<n>.htmlthe raw message
delvingT1delvingbitcoin.org/t/<slug>/<topic-id>/<post-number>that post's raw text (Discourse JSON)
chainT1optional mempool.space/block/<hash> for people; the evidence is a chain.* checkthe chain source
optechT2bitcoinops.org/en/newsletters/<yyyy>/<mm>/<dd>/#<anchor> or bitcoinops.org/en/topics/<topic>/page text
stackexchangeT2bitcoin.stackexchange.com/a/<answer-id> or /q/<question-id>the post body (Stack Exchange API)
transcriptT2btctranscripts.com/<path>, the locator names the timestamppage text
paperT2DOI or stable URL, the locator names section or pagepage text; PDFs as extracted text
docsT2project documentation at a commit or versioned URLpage text
mediaT3article URLpage text
socialT4post URL (X, Nostr via a public gateway, Stacker News)page text when public

Rules the checker enforces:

  1. Git-hosted sources (bip, bolt, code, release-notes in a repo) are cited at a 40-hex commit, never at a branch name.
  2. Every source except chain has a quote. The quote must be found at the URL after normalizing whitespace, quotes and case. A quote that is not found blocks publishing.
  3. Quotes are at most 50 words. Blocklore summarizes and links; it does not republish.
  4. A claim needs at least one direct source. A claim resting only on T3 or T4 sources is labeled so on every surface that shows it.
  5. Mailing-list posts are cited by message id, which outlives any one archive.

Checks

Deterministic checks the brain re-runs on every verification. Each one also renders as a command a reader can run against their own node or clone.

typeFieldsPasses whenReader's command
chain.block-hashheight, expectthe block at height has hash expectbitcoin-cli getblockhash <height>
chain.subsidyheight, expect_satscoinbase outputs minus fees equal expect_satsbitcoin-cli getblockstats <height> '["subsidy"]'
chain.headerheight, field (version, time, bits, nonce), expectthe header field equals expectbitcoin-cli getblockheader $(bitcoin-cli getblockhash <height>)
code.containsrepo, ref, path, text, optional livetext occurs in path at commit ref; with live: true, also on the default branchgit -C <repo> show <ref>:<path> | grep -F '<text>'
bip.fieldbip, field (Status, Type, Layer, Title, Authors), expectthe BIP's preamble on the default branch has that valuecurl -s <raw url> | sed -n '1,30p'

live checks and bip.field read the current default branch, so they catch drift: when a BIP's status changes, the claim fails its check, the brain flags it stale and queues re-research. Pinned checks prove provenance and never drift.

Revisions

The claim's top-level fields are its current state. revisions is an append-only log from which any earlier state can be rebuilt (the time machine).

revisions:
  - rev: 1
    at: { time: 2026-11-20T15:00:00Z, height: 976744 }
    run: 2026-11-20-seed
    change: created
  - rev: 2
    at: { time: 2026-12-02T09:12:00Z, height: 978420 }
    run: 2026-12-02-daily
    change: corrected
    note: The activation height was right; the date was the median time past, not the block time.
    before: { statement: "... on 12 November 2021." }
  • change is created, corrected (it was wrong), refined (clearer or more precise, same substance), sources (sources added, replaced or removed), status, confidence, depth, superseded or reviewed.
  • before holds the previous values of exactly the fields that changed.
  • corrected revisions are the corrections log. Nothing is ever edited without a revision; the publisher refuses a claim whose earlier revisions differ from the last snapshot.
  • Re-verification that changes nothing updates last_verified only and adds no revision.

Hashing

A claim's hash is SHA-256 over its canonical JSON: keys sorted, no insignificant whitespace, UTF-8, last_verified excluded (re-checking does not change what a claim says). A snapshot lists every claim's hash and the Merkle root over them in id order: leaf = SHA-256(0x00 || hash), node = SHA-256(0x01 || left || right), as in RFC 6962. Its file is timestamped with OpenTimestamps and never rewritten. See ARCHITECTURE.md, "Verifying Blocklore itself", and /verify.

Topics, proposals, debates

Topics are views:

slug: taproot
title: Taproot
lede: taproot.what-it-is
contested: false
safety: false
related: [segwit, covenants]
sections:
  - id: basics
    title: What it is
    depth: curious
    claims: [taproot.what-it-is, taproot.why-it-matters]

A topic has no prose beyond its titles; every sentence on the page is a claim. Its ladder (concept, BIP, code, review history, Optech coverage) is assembled from the sources of its claims.

Proposals (knowledge/proposals/) and debates (knowledge/debates/) follow the same rule: their structure is fields, their sentences are claims. Their schemas live in core/src/schema.ts beside the claim's.