A complete mathematical specification of the Bitcoin consensus protocol, aligned with observable mainnet behavior.
The Orange Paper comprises two documents:
- PROTOCOL.md: Consensus rules, invariants, predicates (what must hold)
- ARCHITECTURE.md: Implementation algorithms and design choices (how to achieve it)
THE_ORANGE_PAPER.md: Umbrella document with structure and links
For spec-lock verification, pass absolute paths (or your own $BLVM_SPEC_ROOT/...) to PROTOCOL.md and ARCHITECTURE.md from your clone of this repository; see THE_ORANGE_PAPER.md for full commands.
To verify the Table of Contents links against real headings (in this directory): node scripts/check-toc.mjs
In the btc-commons monorepo, from the workspace root, node blvm-spec/scripts/check-spec-lock-ids.mjs checks that every #[spec_locked("…")] in blvm-consensus, blvm-protocol, and blvm-node matches a numbered heading in PROTOCOL.md or ARCHITECTURE.md.
Unlike informal summaries, this specification is derived from protocol rules as they operate on the live network today. It provides:
- Complete State Machine: Formal specification of Bitcoin's state transitions
- Economic Model: Mathematical description of the monetary system
- Validation Rules: Precise definition of all consensus-critical checks
- Security Properties: Formal statements of Bitcoin's security guarantees
The specification uses formal mathematical notation:
-
Hash Values:
$\mathbb{H} = {0,1}^{256}$ - Set of 256-bit hashes -
Byte Strings:
$\mathbb{S} = {0,1}^*$ - Set of byte strings -
Natural Numbers:
$\mathbb{N} = {0, 1, 2, \ldots}$ - Set of natural numbers -
Integers:
$\mathbb{Z} = {\ldots, -2, -1, 0, 1, 2, \ldots}$ - Set of integers
-
OutPoint:
$\mathcal{O} = \mathbb{H} \times \mathbb{N}$ -
Transaction:
$\mathcal{TX} = \mathbb{N} \times \mathcal{I}^* \times \mathcal{T}^* \times \mathbb{N}$ -
Block:
$\mathcal{B} = \mathcal{H} \times \mathcal{TX}^*$ -
UTXO Set:
$\mathcal{US} = \mathcal{O} \rightarrow \mathcal{U}$
The Orange Paper is split into PROTOCOL.md (consensus rules) and ARCHITECTURE.md (implementation design). See THE_ORANGE_PAPER.md for the full structure and section mapping.
This specification can be used for:
- Formal Verification: Proving correctness properties of Bitcoin implementations
- Protocol Analysis: Understanding security and economic properties
- Implementation Reference: Building Bitcoin-compatible software
- Academic Research: Studying distributed consensus systems
For best viewing experience, use a Markdown viewer that supports LaTeX mathematical notation and Mermaid diagrams.
We welcome contributions to improve the mathematical precision and completeness of this specification.
- Fork the repository
- Create a feature branch (
git checkout -b feature/improvement) - Make your changes with clear mathematical justification
- Ensure all formulas render correctly
- Commit your changes (
git commit -am 'Add mathematical proof for X') - Push to the branch (
git push origin feature/improvement) - Create a Pull Request
- Mathematical Accuracy: All formulas must be mathematically correct
- Proof Completeness: Provide complete proofs for new theorems
- Implementation Validation: Verify against a reference node implementation when possible
- Clear Notation: Use consistent mathematical notation throughout
- Cross-References: Update related sections when making changes
-
GFM / LaTeX: Prefer
\parallelfor byte concatenation in math; in long$$…$$blocks use\_{n}for subscripts when underscores would pair incorrectly in GitHub-flavored Markdown
This project is licensed under the MIT License - see the LICENSE file for details.
- Reference implementation (bitcoin/bitcoin)
- Bitcoin Improvement Proposals (BIPs)
- Satoshi Nakamoto, "Bitcoin: A Peer-to-Peer Electronic Cash System" (2008)
- FIPS 180-4: Secure Hash Standard
- SEC 2: Recommended Elliptic Curve Domain Parameters
- RFC 6979: Deterministic Usage of DSA and ECDSA
Version: 1.0
Authors: BTCDecoded.org, @secsovereign
This document represents the current state of Bitcoin. The protocol continues to evolve through the BIP process.