Stack overview

Bitcoin Commons is a Bitcoin implementation ecosystem built as a six-layer technology stack on the Orange Paper.

“Layer” here means stack position, not governance repository layers or PR tiers. blvm-consensus and blvm-protocol share blvm-primitives for types, serialization, and crypto.

The stack implements consensus from the spec, abstracts protocol variants, ships a reference full node, SDK, and governance enforcement tooling.

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

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)

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)

Stack layer 4: blvm-node (Node Implementation)

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

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

Runtime data flow and crate dependencies: Component Relationships.

Cross-Layer Validation

Dependency rules, crate-graph boundaries, and version coordination: Component Relationships.

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

Source repositories

Stack layerCrateRepository
2blvm-consensusBTCDecoded/blvm-consensus
3blvm-protocolBTCDecoded/blvm-protocol
4blvm-nodeBTCDecoded/blvm-node
5blvm-sdkBTCDecoded/blvm-sdk
6blvm-commonsBTCDecoded/blvm-commons
Umbrella binaryblvmBTCDecoded/blvm

See Also