Governance Overview
Cryptographic governance for Bitcoin Commons repositories: tiers, signatures, and audit trails. Not required for operating a node.
Running a node? Use the Operator guide and Deployment posture. Return here when you contribute code, sign releases, or configure governance tooling.
Building modules? See the Developer guide and SDK overview.
Governance documentation
| Topic | Guide |
|---|---|
| Constitutional model, tiers, capture resistance | Governance Model |
| Layers × tiers and signature rules | Layer-tier model |
| PR lifecycle, signatures, merge rules | PR process |
| Human review and AI review intelligence | Review standards |
| Multisig thresholds | Multisig configuration |
| Maintainer key duties | Keyholder procedures |
| Audit logging and verification | Audit trails |
| Governance tooling config | Governance configuration |
| Governance forks | Governance fork system |
| P2P governance messages | P2P governance messages |
| blvm-commons enforcement | blvm-commons |
| OpenTimestamps / Nostr integrations | OpenTimestamps, Nostr |
| Operator FAQ (governance) | FAQ: governance |
The governance system enforces development processes cryptographically across Bitcoin Commons repositories. Module README (below) covers day-to-day governance module usage; the Governance Model page includes the full constitutional document.
Bitcoin Commons Governance System
Central source of truth for governance rules across all Bitcoin Commons repositories (managed by BTCDecoded organization).
⚠️ ACTIVATION STATUS
For verified system status: See SYSTEM_STATUS.md in the BTCDecoded organization repository.
Current Status: Phase 1 (Infrastructure Building)
- ✅ Infrastructure Complete: All core components implemented
- ⚠️ Not Yet Activated: Governance rules are not enforced
- 🔧 Test Keys Only: No real cryptographic enforcement
- 📋 Development Phase: System is in rapid AI-assisted development
Timeline: Phase 2 Activation: Governance enforcement begins | Phase 3 Full Operation: Mature, stable system
Overview
This repository defines:
- Repository Governance (Binding): Who can merge what, and when
- Protocol Governance (Advisory): User signaling for consensus changes
- Emergency Response: Three-tiered system for critical issues
- Maintainer Lifecycle: Selection, removal, and rotation processes
Key Distinction: We govern repository access (binding) and provide guidance for protocol changes (advisory). Users remain sovereign over Bitcoin's consensus rules.
Constitutional Governance Model
Bitcoin Commons implements a 5-tier constitutional governance system with complete transparency through cryptographic audit trails and user-protective mechanisms. That system operates under the Bitcoin Commons Compact.
Action Tiers
- Tier 1: Routine Maintenance (3-of-5, 7 days) - Bug fixes, documentation, performance
- Tier 2: Feature Changes (4-of-5, 30 days) - New RPC methods, P2P changes, wallet features
- Tier 3: Consensus-Adjacent (5-of-5, 90 days) - Changes affecting consensus validation
- Tier 4: Emergency Actions (4-of-5, 0 days review period) - Critical security patches, network threats
- Tier 5: Governance Changes (Special process, 180 days) - Changes to governance rules themselves
Layer Hierarchy
| Layer | Repository | Signatures | Review Period |
|---|---|---|---|
| 1 | blvm-spec | 6-of-7 | 180 days (365 for consensus) |
| 2 | blvm-consensus | 6-of-7 | 180 days (365 for consensus) |
| 3 | blvm-protocol | 4-of-5 | 90 days |
| 4 | blvm-node / blvm | 3-of-5 | 60 days |
| 5 | blvm-sdk | 2-of-3 | 14 days |
Documentation
Quick Reference
- GETTING_STARTED.md - Quick orientation
- QUICK_REFERENCE.md - Lookup tables and commands
- HOW_TO.md - Task instructions
- DECISION_TREES.md - Decision flows
Core Documentation
- docs/ACTION_TIERS.md - PR action tiers (
action-tiers.yml) vs emergency tiers - COMPACT.md - Bitcoin Commons Compact
- GOVERNANCE.md - Main governance process
- LAYER_TIER_MODEL.md - How layers and tiers combine
- SCOPE.md - Repository vs protocol governance
Guides
- guides/MAINTAINER_GUIDE.md — Maintainer guide
- guides/ONBOARDING.md — New maintainer onboarding
- REVIEW_EXPECTATIONS.md — Human reviewer expectations (guidelines for maintainers)
- guides/REVIEW_INTELLIGENCE.md — AI-assisted code review intelligence (operating document; Compact, Orange Paper, differential testing)
- blvm-commons - Governance enforcement application
- blvm-docs - Unified mdBook site: docs.thebitcoincommons.org
- Audit materials — see security and disclosure policy in this repo (
SECURITY.md,guides/) and organization-wide SECURITY.md where applicable
Review standards
Human maintainer expectations and AI-assisted “review intelligence” for Bitcoin Commons code are canonical in the governance repository; they are not duplicated in this book.
- Review expectations: Expected practices for human reviewers and maintainers (guidelines, not rigid rules; see challenge mechanism there).
- Review intelligence: Operating document for AI-assisted review of Bitcoin implementations: true alternative vs Core fork taxonomy, flag structure, and alignment with the Orange Paper and the Bitcoin Commons Compact.
For PR tiers, cryptographic signatures, and merge rules, see PR process and Layer-tier model.
See Also
- Governance Model: Constitutional model and included governance policy
- PR Process: How tiers apply to pull requests
- Multisig Configuration: Configuring multisig thresholds
- Keyholder Procedures: Maintainer responsibilities
- Audit Trails: Audit logging and verification
- SDK API Reference: Governance primitives API