Introduction

Welcome to the BLVM (Bitcoin Low-Level Virtual Machine) documentation!

BLVM implements Bitcoin consensus rules directly from the Orange Paper, provides protocol abstraction for multiple Bitcoin variants, delivers a production-ready node with full P2P networking, includes a developer SDK for custom implementations, and enforces cryptographic governance for transparent development.

What is BLVM?

BLVM (Bitcoin Low-Level Virtual Machine) is compiler-like infrastructure for Bitcoin implementations. Like LLVM transforms source code through optimization passes, BLVM transforms the Orange Paper mathematical specification into optimized, production-ready code via optimization passes.

Compiler-Like Architecture

Like a compiler transforms source code → IR → optimized machine code, BLVM transforms:

Orange Paper - Mathematical specification (IR/intermediate representation)
BLVM Specification Lock - Formal verification tooling linking code to Orange Paper specifications using Z3
Optimization Passes - Transform spec into optimized code
blvm-consensus - Optimized implementation with formal verification
blvm-protocol - Protocol abstraction for mainnet, testnet, regtest
blvm-node - Full Bitcoin node with storage, networking, RPC
blvm-sdk - Developer toolkit and module composition
Governance - Cryptographic governance enforcement

Why “LVM”?

Like LLVM’s compiler infrastructure, BLVM provides Bitcoin implementation infrastructure with optimization passes. The Orange Paper serves as the intermediate representation (IR) transformed into production-ready code, enabling safe alternative implementations while maintaining consensus correctness.

Documentation Structure

This documentation is organized into several sections:

Getting Started - Installation and quick start guides
Architecture - System-wide design and component relationships
Component Documentation - Detailed documentation for each layer
Developer Guides - SDK usage and module development
Governance - Governance model and procedures
Reference - Specifications, API documentation, and glossary

Documentation Sources

This unified documentation site aggregates content from multiple source repositories:

Documentation is maintained in source repositories alongside code
Changes to source documentation automatically propagate here
Each component’s documentation is authored by its maintainers

blvm-consensus - Pure mathematical implementation with formal verification, BIP integration (BIP30, BIP34, BIP66, BIP90, BIP147)
blvm-protocol - Protocol variants (mainnet, testnet, regtest) and network messages
blvm-node - Full Bitcoin node with RPC, storage, and module system
blvm-sdk - Governance primitives and CLI tools (blvm-keygen, blvm-sign, blvm-verify)
blvm-commons - Governance enforcement system with GitHub integration, OpenTimestamps, Nostr, and cross-layer validation

Module System

BLVM includes a process-isolated module system enabling optional features:

blvm-lightning - Lightning Network module (LDK implementation)
blvm-mesh - Mesh networking module with submodules (onion routing, mining pool, messaging)
blvm-stratum-v2 - Stratum V2 mining module
blvm-datum - Datum blockchain module
blvm-miningos - Mining OS module

Key Capabilities

BLVM includes comprehensive Bitcoin node functionality:

Module System: Process-isolated modules with enhanced security and process isolation
RBF and Mempool Policies: Configurable replacement-by-fee modes with 5 eviction strategies
Payment Processing: CTV (CheckTemplateVerify) support for advanced payment flows
Advanced Indexing: Address and value range indexing for efficient queries
Formal Verification: Formal verification for critical proofs
Differential Testing: Infrastructure for comparing against Bitcoin Core
FIBRE Protocol: High-performance relay protocol support

License

This documentation is licensed under the MIT License, same as the BLVM codebase.

BLVM Documentation