The Bitcoin Commons

Bitcoin Commons is a project that solves Bitcoin's governance asymmetry through two complementary innovations: BLLVM (the technical stack providing mathematical rigor) and Bitcoin Commons (the governance framework providing coordination without civil war). Together, they enable safe alternative Bitcoin implementations with forkable governance.

Bitcoin Core is a single implementation with informal governance. Bitcoin Commons provides: (1) BLLVM - Mathematical rigor enabling safe alternatives, (2) Commons - Forkable governance enabling coordination. Bitcoin Core has excellent consensus security; Bitcoin Commons adds governance security and implementation diversity.

No. Neither BLLVM nor Bitcoin Commons forks Bitcoin's blockchain or consensus rules. BLLVM provides mathematical specification enabling safe alternative implementations. Bitcoin Commons provides governance framework enabling coordination. Both maintain full Bitcoin consensus compatibility.

The system is in Phase 1 (Infrastructure Complete). All core components of both BLLVM and Bitcoin Commons are implemented, but governance is not yet activated. Phase 2 (Governance Activation) will proceed when a suitable cohort of keyholders has been found. The system is not yet battle-tested in production.

BLLVM provides the mathematical foundation and compiler-like architecture (Orange Paper as IR, formal verification passes). Bitcoin Commons provides the governance framework (coordination without civil war). The modular architecture is where both meet: BLLVM ensures correctness through architectural enforcement; Commons ensures coordination through governance rules. You can't have safe alternative implementations without BLLVM's mathematical rigor, and you can't have coordination without Commons' governance framework.

BLLVM (Bitcoin Low-Level Virtual Machine): Technical innovation providing mathematical rigor through the Orange Paper (mathematical specification), formal verification (Kani proofs), proofs locked to code, and a compiler-like architecture. This ensures correctness.

Bitcoin Commons (Cryptographic Commons): Governance innovation providing forkable governance through Ostrom's principles, cryptographic enforcement, 5-tier governance model, and transparent audit trails. This ensures coordination.

Bitcoin Commons is the governance framework; BTCDecoded is the first complete implementation of both innovations (BLLVM + Commons). Think of BLLVM as the technical foundation, Bitcoin Commons as the governance constitution, and BTCDecoded as the first "government" built on both. Other implementations can adopt the same framework.

BLLVM (Bitcoin Low-Level Virtual Machine) is the technical stack that provides mathematical rigor for Bitcoin implementations. It includes: (1) bllvm-spec (Orange Paper) - complete mathematical specification of Bitcoin consensus, (2) bllvm-consensus - pure mathematical implementation with formal verification, (3) bllvm-protocol - Bitcoin abstraction layer, (4) bllvm-node - full node implementation, (5) bllvm - binary wrapper for bllvm-node, (6) bllvm-sdk - developer toolkit. Think of it as a compiler-like architecture where the Orange Paper is the IR (intermediate representation).

The Orange Paper is a complete mathematical specification of Bitcoin's consensus protocol, extracted from Bitcoin Core using AI-assisted analysis. It serves as the "intermediate representation" (IR) in BLLVM's compiler-like architecture. It enables safe alternative implementations by providing formal, verifiable consensus rules that can be mathematically proven correct.

BLLVM uses Kani model checking to formally verify consensus-critical code. The Orange Paper provides the mathematical specification; bllvm-consensus implements it with proofs locked to code. All consensus decisions flow through verified functions, and the dependency chain prevents bypassing verification. This provides mathematical proof of correctness, not just testing.

Bitcoin Core embeds consensus rules in 350,000+ lines of C++ with no mathematical specification. BLLVM provides: (1) Mathematical specification (Orange Paper), (2) Formal verification (Kani proofs), (3) Proofs locked to code, (4) Compiler-like architecture enabling safe alternative implementations. BLLVM doesn't replace Bitcoin Core; it enables safe alternatives.

Like a compiler has source code → IR → machine code, BLLVM has: Bitcoin Core code → Orange Paper (IR) → bllvm-consensus → bllvm-node. The Orange Paper serves as the intermediate representation that multiple implementations can target, just like multiple compilers can target the same IR. This enables implementation diversity while maintaining consensus correctness.

Bitcoin Commons is a forkable governance framework that applies Elinor Ostrom's proven commons management principles through cryptographic enforcement. It solves Bitcoin's governance asymmetry by making development governance as robust as technical consensus. It provides coordination without civil war through forkable rules, cryptographic signatures, and transparent audit trails.

Bitcoin Commons uses a 5-tier constitutional governance model with graduated signature thresholds (3-of-5 for routine maintenance, up to 6-of-7 for consensus changes) and review periods (7 days to 365 days). The system combines Layers (which repository) and Tiers (what type of change), using "most restrictive wins" for maximum security. All governance actions are cryptographically signed and transparently auditable. Economic nodes (mining pools, exchanges, custodians) can veto consensus-adjacent changes. Users can fork governance rulesets if they disagree, creating exit competition. A three-tiered emergency system provides proportional response to critical issues.

Multiple mechanisms: (1) Forkable governance rules allow users to exit if governance is captured, (2) Multiple implementations compete, preventing monopoly, (3) Cryptographic enforcement makes power visible and accountable, (4) Economic alignment through merge mining, (5) Graduated thresholds prevent rapid changes, (6) Transparent audit trails.

Users can fork the governance rules (not just the code) if they disagree with decisions. This creates exit competition: if governance is captured, users can fork to a better governance model while maintaining Bitcoin consensus compatibility. The threat of forking prevents capture.

Elinor Ostrom's Nobel Prize-winning research identified 8 principles for managing commons successfully. Bitcoin Commons applies these through: clearly defined boundaries, proportional equivalence, collective choice, monitoring, graduated sanctions, conflict resolution, minimal recognition of rights, and nested enterprises.

BLLVM solves the technical problem (mathematical rigor, safe alternative implementations). Bitcoin Commons solves the governance problem (coordination without civil war). You can't have safe alternatives without BLLVM's mathematical foundation, and you can't have coordination without Commons' governance framework. They enable each other.

The modular architecture has three layers: (1) Mandatory Consensus (BLLVM ensures correctness), (2) Optional Modules (Commons enables competition), (3) Economic Coordination (merge mining funds both). BLLVM ensures correctness through architectural enforcement; Commons ensures coordination through governance rules. The architecture is where both meet.

Technically yes: BLLVM is a technical stack that can be used independently. However, without Bitcoin Commons governance, you'd still have the governance capture problem. The innovations are designed to work together: BLLVM enables safe alternatives, Commons enables coordination between alternatives.

The governance framework could theoretically be applied to other implementations, but BLLVM's mathematical rigor (Orange Paper, formal verification) is what makes alternative implementations safe. Without BLLVM, you'd have governance but still risk consensus bugs from informal implementations.

BLLVM uses Kani model checking to mathematically prove code correctness. The Orange Paper provides the specification; bllvm-consensus implements it with proofs. All consensus decisions flow through verified functions. This provides mathematical proof, not just testing.

BLLVM has nearly 200 formal proofs in the source code, providing comprehensive formal verification coverage of consensus-critical functions. The proofs are embedded directly in the codebase and verified continuously.

Formal verification proofs are embedded in the code itself, not separate documentation. The proofs verify that the code matches the Orange Paper specification. If code changes, proofs must be updated, ensuring correctness is maintained.

Through multiple layers: (1) Orange Paper provides mathematical specification, (2) Formal verification proves implementation matches spec, (3) Proofs locked to code prevent drift, (4) Dependency chain forces all consensus through verified functions, (5) Spec drift detection alerts if code diverges from spec.

The Fork Registry is a public, self-service registry for governance forks. Anyone can submit a pull request to add their governance fork—no approval needed, just automated validation. The registry tracks governance forks with their signature thresholds, review periods, and relationships (which fork was created from which). Use the "Fork Your Governance" section on this website to browse the registry, compare forks, view the genealogy tree, and create your own fork.

All governance actions require cryptographic signatures from maintainers. The bllvm-commons (GitHub App) verifies signatures, enforces thresholds (e.g., 6-of-7), and blocks merges until requirements are met. This makes power visible and accountable: you can see who signed what, when.

Forkable governance means users can fork to a better governance model. This creates exit competition: captured governance loses users to better-governed implementations. The threat of forking prevents capture. Unlike Bitcoin Core, you can fork the governance rules, not just the code.

Through merge mining revenue. Secondary chains merge-mine with Bitcoin, providing revenue that flows to development priorities through governance decisions. Miners have economic incentives to support well-governed implementations because they benefit from network health.

Merge mining allows miners to mine multiple blockchains simultaneously using the same proof-of-work. Bitcoin Commons implementations can merge-mine with Bitcoin, providing economic sustainability without changing Bitcoin's consensus. 1% of merged chain rewards fund development.

Economic nodes represent Bitcoin's economic stakeholders (mining pools, exchanges, custodians) and provide veto power over consensus-adjacent changes. They ensure governance decisions align with economic incentives. For Tier 3+ changes, economic nodes can veto if 30%+ hashpower or 40%+ economic activity signals opposition. This protects users by ensuring major changes consider economic impact.

Governance forks allow users to choose different governance rulesets without affecting Bitcoin consensus. Users can export governance rulesets as versioned, signed packages and fork to a better governance model if they disagree with decisions. This provides an escape hatch: captured governance loses users to better-governed implementations. The threat of forking prevents capture while maintaining Bitcoin consensus immutability.

Interactive Tools: Use the "Fork Your Governance" section on this website to browse existing forks, start from templates, customize your own ruleset, compare different governance models, and view the fork genealogy tree. The system includes a self-service fork registry where anyone can submit their governance fork via pull request—no approval needed, just automated validation.

Bitcoin Commons uses a dual-dimensional system: Layers (which repository) and Tiers (what type of change). When both apply, the system uses "most restrictive wins" - taking the highest signature threshold and longest review period. For example, a bug fix in the Protocol Engine (Layer 3) requires 4-of-5 signatures and 90 days, even though Tier 1 (routine maintenance) normally requires only 3-of-5 and 7 days. This ensures maximum security for sensitive repositories.

Bitcoin Commons uses a three-tiered emergency response system for proportional handling of critical issues: Tier 1: Critical Emergency (network-threatening, 0 days, 4-of-7 maintainers, 7 day max), Tier 2: Urgent Security (security issues, 7 days, 5-of-7 maintainers, 30 day max), Tier 3: Elevated Priority (important but not critical, 30 days, 6-of-7 maintainers, 90 day max). This ensures rapid response to critical threats while maintaining appropriate review for less urgent issues.

All 8 layers are implemented: bllvm-spec (Orange Paper) complete, bllvm-consensus with nearly 200 formal proofs, bllvm-protocol, bllvm-node, bllvm (binary wrapper), and bllvm-sdk all functional. Recent work includes high availability features, build state tracking, fork verification, binary signing tools, and deterministic build verification. The system is not yet battle-tested in production.

All core governance infrastructure is implemented: bllvm-commons (GitHub integration, signature verification, status checks), economic node system (veto power for consensus-adjacent changes), governance fork capability (ruleset export and forking), emergency tier system (three-tiered response), and layer+tier combination model. However, governance is not yet activated (test keys only) and keyholders are not yet onboarded. Phase 2 activation will proceed when a suitable cohort of keyholders has been found.

Phase 2 activation will proceed when a suitable cohort of keyholders has been found. This requires: (1) Security audits, (2) Keyholder onboarding, (3) Governance app deployment, (4) Community testing. Phase 3 (full operation) will follow after Phase 2 is stable.

Review BLLVM code and formal proofs, review Bitcoin Commons governance rules, submit issues and pull requests, help with testing and security audits, build your own implementation using both innovations, or participate in governance discussions.

Yes! You can use BLLVM's technical stack (Orange Paper, bllvm-consensus) and adopt Bitcoin Commons governance framework. Fork the governance model, customize it for your organization, and build your own Bitcoin-compatible implementation. See the Implementations Registry.

All code is open source on GitHub under the BTCDecoded organization. Key repositories: BLLVM (bllvm-spec/Orange Paper, bllvm-consensus, bllvm-protocol, bllvm-node, bllvm, bllvm-sdk) and Commons (governance, bllvm-commons). The fork registry is maintained in the governance repository.

White Paper for complete technical and governance overview, Documentation for unified technical documentation, and Governance Docs for governance rules and processes.

Bitcoin's codebase is a commons: a shared resource that benefits everyone but no one owns. Traditional commons fail due to tragedy of the commons. Ostrom showed how to manage commons successfully. Bitcoin Commons applies these proven principles through cryptographic enforcement.

Cypherpunks focused on eliminating trusted third parties in transactions. Bitcoin Commons extends this to development: eliminate trusted parties in governance through cryptographic enforcement, transparency, and forkability. BLLVM extends this to implementation: eliminate trusted implementations through mathematical proof.