System Overview

Bitcoin Commons is a Bitcoin implementation ecosystem with six stack layers (numbered below) building on the Orange Paper mathematical specifications. “Layer” here means position in the technology stack, not repository governance layers or governance tiers (PR classification). 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.

Six-layer stack (architecture)

graph TB L1[Orange Paper
Mathematical Foundation] L2[blvm-consensus
Pure Math Implementation] L3[blvm-protocol
Protocol Abstraction] L4[blvm-node
Full Node Implementation] L5[blvm-sdk
Developer Toolkit] L6[blvm-commons
Governance Enforcement] L1 -->|direct implementation| L2 L2 -->|protocol abstraction| L3 L3 -->|full node| L4 L4 -->|ergonomic API| L5 L5 -->|cryptographic governance| L6 style L1 fill:#f9f,stroke:#333,stroke-width:2px style L2 fill:#bbf,stroke:#333,stroke-width:2px style L3 fill:#bfb,stroke:#333,stroke-width:2px style L4 fill:#fbf,stroke:#333,stroke-width:2px style L5 fill:#ffb,stroke:#333,stroke-width:2px style L6 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 mermaid diagram above is the canonical six stack layers list.

Component Overview

Stack layer 1: Orange Paper (Mathematical Foundation)

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

Stack layer 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 and transitive pins follow Cargo.toml (BLVM crates use published ranges; many third-party crates use = where pinned)

Code: README.md

Stack layer 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

Stack layer 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

Stack layer 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

Stack layer 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