Bitcoin Commons Node

Minimal Bitcoin node implementation using blvm-protocol for protocol abstraction and blvm-consensus for consensus decisions.

📚 Comprehensive Documentation: See docs.thebitcoincommons.org (source repo: blvm-docs).
For verified system status: See SYSTEM_STATUS.md in the BTCDecoded organization repository.

Provides a minimal Bitcoin node implementation using blvm-protocol for protocol abstraction and blvm-consensus for all consensus decisions. Adds only non-consensus infrastructure: storage, networking, RPC, and orchestration.

Architecture Position

Tier 4 of the 6-tier Bitcoin Commons architecture (BLVM technology stack):

1. blvm-spec (Orange Paper - mathematical foundation)
2. blvm-consensus (pure math implementation)
3. blvm-protocol (Bitcoin abstraction)
4. blvm-node (full node implementation)
5. blvm-sdk (developer toolkit)
6. blvm-commons (governance enforcement)

Design Principles

1. Zero Consensus Re-implementation: All consensus logic from blvm-consensus
2. Protocol Abstraction: Uses blvm-protocol for variant support
3. Pure Infrastructure: Only adds storage, networking, RPC, orchestration
4. Production Ready: Full Bitcoin node functionality

Features

• Consensus Integration: All consensus logic from blvm-consensus
• Protocol Support: Multiple variants (mainnet, testnet, regtest)
• RBF Support: Configurable RBF modes (Disabled, Conservative, Standard, Aggressive)
• Mempool Policies: Comprehensive mempool configuration with 5 eviction strategies
• Payment Processing: CTV (CheckTemplateVerify) support for advanced payment flows
• Advanced Indexing: Address and value range indexing for efficient queries
• RPC Interface: JSON-RPC server with methods aligned to common Bitcoin node documentation
• Storage: UTXO set management and chain state with multiple backends (tidesdb, redb, sled, rocksdb)
• Module System: Process-isolated modules for optional features
• P2P Governance: Governance message relay via P2P protocol

See Security for production considerations.

Storage Backends

Supports multiple database backends via feature flags:

• rocksdb (default): High-performance database; reads common LevelDB/blk*.dat layouts; strong IBD performance
• redb: Embedded database with ACID transactions
• sled: Embedded key-value store (fallback)
• tidesdb (optional): LSM-tree key-value store; requires TidesDB C library

RocksDB (default backend):

• Automatic detection of common Bitcoin-style data directories
• Direct access to raw block files (blk*.dat) where supported
• Parsers for common on-disk chain formats

Default binary builds enable RocksDB (rocksdb feature). RocksDB requires a working C++ toolchain; CI installs libclang where bindgen is needed.

To build with redb only (pure Rust, no librocksdb-sys):

cargo build --no-default-features --features "redb,production,sysinfo,nix,libc,governance,utxo-commitments,protocol-verification"

Omit governance if you do not need the HTTP client (Commons auto-detect uses reqwest via that feature). For Bitcoin-style ZMQ PUB notifications, load the blvm-zmq module (no longer a blvm-node feature flag).

Note: RocksDB and erlay features are mutually exclusive due to dependency conflicts.

RBF and Mempool Policies

Supports configurable RBF (Replace-By-Fee) modes and comprehensive mempool policies:

• RBF Modes: Disabled, Conservative, Standard (default), Aggressive
• Mempool Policies: Size limits, fee thresholds, eviction strategies, ancestor/descendant limits

See the Configuration Guide for details:

• RBF Configuration - Detailed RBF mode configuration
• Mempool Policies - Detailed mempool policy configuration

Protocol Variants

Supports multiple Bitcoin protocol variants:

• Regtest (default): Regression testing network for development
• Testnet3: Bitcoin test network
• BitcoinV1: Production Bitcoin mainnet

use blvm_node::{Node, NodeConfig};

// Default: Regtest for safe development
let config = NodeConfig::default();
let node = Node::new(config)?;

// Explicit testnet
let mut config = NodeConfig::default();
config.network = ProtocolVersion::Testnet3;
let testnet_node = Node::new(config)?;

Building

Quick Start

git clone https://github.com/BTCDecoded/blvm-node
cd blvm-node
cargo build --release

Cargo resolves blvm-consensus and other blvm-* dependencies from crates.io according to Cargo.toml. The [patch] flow below is only for local sibling development.

Local Development

If you're developing both blvm-node and blvm-consensus:

1. Clone both repos:

   git clone https://github.com/BTCDecoded/blvm-consensus
   git clone https://github.com/BTCDecoded/blvm-node
   

2. Set up local override:

   cd blvm-node
   mkdir -p .cargo
   echo '[patch."https://github.com/BTCDecoded/blvm-consensus"]' > .cargo/config.toml
   echo 'blvm-consensus = { path = "../blvm-consensus" }' >> .cargo/config.toml
   

3. Build:

   cargo build
   

Changes to blvm-consensus are now immediately reflected without git push.

Testing

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

Usage

Running the Node

# Start node in regtest mode (default)
cargo run

# Start in testnet mode
cargo run -- --network testnet

# Start in mainnet mode (use with caution)
cargo run -- --network mainnet

Programmatic Usage

use blvm_node::{Node, NodeConfig};

// Default: Regtest for safe development
let config = NodeConfig::default();
let node = Node::new(config)?;

// Start the node
node.start().await?;

See docs/ for detailed documentation including:

• Configuration Guide - Complete configuration options
• Module System - Process-isolated module system
• RPC Reference - JSON-RPC API documentation

Security

See SECURITY.md for security policies and BTCDecoded Security Policy for organization-wide guidelines.

Additional hardening required for production mainnet use.

Dependencies

Monorepo vs crates.io: In-tree builds use path dependencies for blvm-protocol, blvm-consensus, blvm-muhash, and optional blvm-spec-lock. From crates.io:

[dependencies]
blvm-node = ">=0.1, <1"

• blvm-consensus: All consensus logic (via blvm-protocol or direct optional dep)
• tokio: Async runtime for networking
• serde: Serialization
• anyhow/thiserror: Error handling
• tracing: Logging
• clap: CLI interface

Contributing

See CONTRIBUTING.md and the BTCDecoded Contribution Guide.

License

MIT License - see LICENSE file for details.