[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"0WswenKnZr":3},"# btc-verified\n\n[![CI](https://github.com/ProofOfKeags/btc-verified/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/ProofOfKeags/btc-verified/actions/workflows/ci.yml?query=branch%3Amaster)\n\nMachine-checked components of the Bitcoin protocol, in Lean 4.\n\nConsensus code is the kind of software testing alone cannot secure: every\nnode must reach the same verdict on every byte, a divergence between\nimplementations is a chain split, and the failures that matter are exactly\nthe inputs no test suite thought to include. This repository builds Bitcoin's\ncore in a proof assistant instead — the data structures, their serialization,\nthe hash commitments that link them, the ledger they act on, and, ahead, the\nvalidity rules, the monetary guarantee, and fork choice — so that the\nproperties Bitcoin depends on are theorems a machine re-checks on every\nbuild, not claims a reader has to take on trust.\n\nThe repo grows as small \"proof leaves\": each module builds cleanly, states\nexactly what it proves, and makes the next claim easier to state. The proofs\nstay anchored to the real network — the verified decoders and computable\nhashes run against actual mainnet blocks at build time, and an axiom audit\nfails CI if any headline theorem depends on an unproved assumption.\n\nThe ambition, laid out in the roadmap below, is machine-checked proofs of\nthe guarantees Bitcoin is valued for: that its rules cap issuance below 21\nmillion coins, and that the fork-choice rule selects the valid chain backed\nby the most work.\n\n## Current proof leaves\n\nWhat is proved so far, by directory. Each directory's README carries the\nprecise checked claims, theorem by theorem; each line here is the plain\nstatement of what stands.\n\n- [`Serialize/`](BtcVerified/Serialize/README.md) — Every encoder/decoder\n  pair carries machine-checked proofs that decoding inverts encoding and that\n  each value has exactly one accepted encoding, including Bitcoin's\n  CompactSize integers.\n- [`Crypto/`](BtcVerified/Crypto/README.md) — A computable SHA-256 checked\n  against published test vectors, and Bitcoin's merkle tree with proofs of\n  exactly what a merkle root does and does not commit to, including the\n  defense against the CVE-2012-2459 duplication attack.\n- [`Transaction/`](BtcVerified/Transaction/README.md) — Bitcoin transactions,\n  legacy and SegWit, with verified serialization in both directions and\n  proofs that transaction ids are binding commitments to the transaction.\n- [`Block/`](BtcVerified/Block/README.md) — Every byte of a block parses\n  through a verified codec (checked against real mainnet blocks), block\n  hashes are proved binding, and a chain's tip hash provably commits to the\n  entire history behind it.\n- [`Script/`](BtcVerified/Script/README.md) — Bitcoin Script programs\n  modeled as the raw bytes consensus actually validates, with the boundary\n  between parsing and execution drawn where the protocol draws it.\n- [`Chainstate/`](BtcVerified/Chainstate/README.md) — The set of spendable\n  coins and the single action every transaction performs on it, with the\n  accounting identity the supply-limit theorem will be built on.\n- [`Impl/`](BtcVerified/Impl/README.md) — Functions transcribed from Bitcoin\n  Core's own source code and proved to satisfy the specification, starting\n  with its merkle-root computation.\n- [`BitVM/`](BtcVerified/BitVM/README.md) — An abstract model of BitVM's bit\n  commitments, with a proof that equivocating on a committed bit yields a\n  hash collision.\n\n## Roadmap\n\nThe trail toward the larger artifacts is tracked as\n[GitHub milestones](https://github.com/ProofOfKeags/btc-verified/milestones),\nin dependency order. Each milestone page states its claims precisely and\ntracks the work items; in outline:\n\n1. [Consensus guards: transaction and block validity](https://github.com/ProofOfKeags/btc-verified/milestone/1)\n   — Write down the rules that decide whether a transaction or block is\n   valid, and prove that every valid block updates the set of spendable\n   coins exactly as specified.\n2. [The supply limit theorem](https://github.com/ProofOfKeags/btc-verified/milestone/2)\n   — Prove that under those validity rules, the total number of bitcoins\n   that can ever exist stays below 21 million.\n3. [Proof of work and cumulative work](https://github.com/ProofOfKeags/btc-verified/milestone/3)\n   — Define what it means for a block to prove work — the hash target its\n   header must meet — and prove how that work adds up along a chain.\n4. [The block tree and fork choice](https://github.com/ProofOfKeags/btc-verified/milestone/4)\n   — Prove that when competing chains exist, Bitcoin's rule for choosing\n   between them selects the valid chain backed by the most total work.\n5. [The Core transcription track](https://github.com/ProofOfKeags/btc-verified/milestone/5)\n   — Translate consensus-critical functions from Bitcoin Core's actual\n   source code into Lean and prove they satisfy the specification, as is\n   already done for its merkle-root computation.\n6. [Script: tokenization and the execution core](https://github.com/ProofOfKeags/btc-verified/milestone/6)\n   — Build a verified interpreter for the core of Bitcoin's Script\n   language, and prove the standard payment types accept exactly the\n   spends that present a correct signature.\n7. [ByteArray transport and the full-chain demo](https://github.com/ProofOfKeags/btc-verified/milestone/7)\n   — Make the verified components efficient enough for real use, and\n   demonstrate it by checking actual Bitcoin mainnet history with them.\n\n## Build\n\nWith Nix, enter the development shell first:\n\n```\nnix develop\n```\n\n```\nlake exe cache get   # fetch the mathlib cache (first build only)\nlake build           # the library, plus the golden vectors and axiom audit\nlake test            # block 481824 through the block codec (fetched on first run)\nlake lint\n```\n\n`lake build` also elaborates `Tests/`: golden vectors that run the verified\ndecoder over real mainnet bytes (the first Bitcoin payment, the SegWit\nactivation coinbase, the first SegWit spend, the genesis block, block 170,\nand the genesis → block 1 chain link) and an axiom audit that fails the\nbuild if any headline theorem depends on `sorry` or an unexpected axiom.\n`lake test` decodes the full SegWit activation block,\nfetching it from a block explorer on first run and caching it locally (it is\npublic chain data, so it is not committed). See `CONTRIBUTING.md` for the\ncontribution workflow.\n\n## License\n\nLicensed under the Apache License, Version 2.0 — matching the Lean and Mathlib\necosystem this builds on, and carrying an explicit patent grant. See\n[`LICENSE`](LICENSE).\n\n## About\n\n`btc-verified` is built by Keagan McClelland ([@ProofOfKeags](https://x.com/ProofOfKeags),\n[proofofkeags.com](https://proofofkeags.com)) — an independent Bitcoin/Lightning\nengineer working toward verified cores for the protocol's correctness-critical\nsurfaces.\n\nThe thesis behind the work — why AI-assisted authorship is making formal\nverification the defensible posture for protocol engineering, rather than a\nluxury — is laid out in\n[Formal Vibefication](https://proofofkeags.com/research/2026-05-12-formal-vibefication.html).\n",1784558039065]