Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

System Overview

Bitcoin Commons is a Bitcoin implementation ecosystem with six tiers building on the Orange Paper mathematical specifications. blvm-consensus and blvm-protocol share the blvm-primitives crate for types, serialization, and crypto. The system implements consensus rules directly from the spec, provides protocol abstraction, delivers a full node implementation, and includes a developer SDK.

6-Tier Component Architecture

graph TB T1[Orange Paper
Mathematical Foundation] T2[blvm-consensus
Pure Math Implementation] T3[blvm-protocol
Protocol Abstraction] T4[blvm-node
Full Node Implementation] T5[blvm-sdk
Developer Toolkit] T6[blvm-commons
Governance Enforcement] T1 -->|direct implementation| T2 T2 -->|protocol abstraction| T3 T3 -->|full node| T4 T4 -->|ergonomic API| T5 T5 -->|cryptographic governance| T6 style T1 fill:#f9f,stroke:#333,stroke-width:2px style T2 fill:#bbf,stroke:#333,stroke-width:2px style T3 fill:#bfb,stroke:#333,stroke-width:2px style T4 fill:#fbf,stroke:#333,stroke-width:2px style T5 fill:#ffb,stroke:#333,stroke-width:2px style T6 fill:#fbb,stroke:#333,stroke-width:2px

BLVM Stack Architecture

BLVM Stack Architecture Figure: BLVM stack (marketing image): Orange Paper / blvm-spec as the foundation, blvm-consensus with verification tooling, then blvm-protocol, blvm-node, blvm-sdk, and governance enforcement (blvm-commons). The numbered 6-tier diagram above is the canonical layer list.

Tiered Architecture

Tiered Architecture Figure: High-level tiered view (simplified graphic). Canonical numbering is the six layers in the mermaid diagram and section headings above (Orange Paper → consensus → protocol → node → SDK → blvm-commons); this image simplifies the stack for layout.

Component Overview

Tier 1: Orange Paper (Mathematical Foundation)

  • Mathematical specifications for Bitcoin consensus rules
  • Source of truth for all implementations
  • Timeless, immutable consensus rules

Tier 2: blvm-consensus (Pure Math Implementation)

  • Direct implementation of Orange Paper functions
  • Formal proofs verify mathematical correctness
  • Side-effect-free, deterministic functions
  • Consensus-critical dependencies pinned to exact versions

Code: README.md

Tier 3: blvm-protocol (Protocol Abstraction)

  • Bitcoin protocol abstraction for multiple variants
  • Supports mainnet, testnet, regtest
  • Commons-specific protocol extensions (UTXO commitments, ban list sharing)
  • BIP implementations (BIP152, BIP157, BIP158, BIP173/350/351)

Code: README.md

Tier 4: blvm-node (Node Implementation)

  • Reference full node (non-consensus infrastructure: storage, P2P, RPC, modules); operational hardening required for real deployments
  • Storage layer (database abstraction with multiple backends)
  • Network manager (multi-transport: TCP, QUIC, Iroh)
  • RPC server (JSON-RPC 2.0, conventional Bitcoin RPC surface)
  • Module system (process-isolated runtime modules)
  • Payment processing with CTV (CheckTemplateVerify) support
  • RBF and mempool policies (4 configurable modes)
  • Advanced indexing (address and value range indexing)
  • Mining coordination (Stratum V2, merge mining)
  • P2P governance message relay
  • Governance integration (webhooks, user signaling)
  • ZeroMQ notifications (optional)

Code: README.md

Tier 5: blvm-sdk (Developer Toolkit)

  • Governance primitives (key management, signatures, multisig)
  • CLI tools (blvm-keygen, blvm-sign, blvm-verify)
  • Composition framework (declarative node composition)
  • Bitcoin-compatible signing standards

Code: README.md

Tier 6: blvm-commons (Governance Enforcement)

  • GitHub App for governance enforcement
  • Cryptographic signature verification
  • Multisig threshold enforcement
  • Audit trail management
  • OpenTimestamps integration

Data Flow

  1. Orange Paper provides mathematical consensus specifications
  2. blvm-consensus directly implements mathematical functions
  3. blvm-protocol layers protocol parameters and network behavior on blvm-consensus types and validation
  4. blvm-node uses blvm-protocol and blvm-consensus for validation
  5. blvm-sdk provides governance primitives
  6. blvm-commons uses blvm-sdk and blvm-protocol for governance enforcement and shared types

Cross-Layer Validation

  • Dependencies between layers are strictly enforced in the crate graph (application layers do not reimplement consensus).
  • Consensus rule modifications are prevented in application layers by design (validation calls into blvm-consensus).
  • The Orange Paper is the specification; blvm-consensus is checked with formal verification, tests, and review—not a single proof of the entire spec in one step.
  • Version coordination (Cargo / release sets) keeps compatible crate versions together.

Key Features

Mathematical Rigor

Protocol Abstraction

  • Multiple Bitcoin variants (mainnet, testnet, regtest)
  • Commons-specific protocol extensions
  • BIP implementations (BIP152, BIP157, BIP158)
  • Protocol evolution support

Node and operational features

Governance Infrastructure

See Also