BLVM - Bitcoin Low-Level Virtual Machine Node

Main binary for Bitcoin Commons BLVM node implementation.

This is the standalone binary crate that provides the blvm executable. It depends on the blvm-node library and provides a command-line interface for running a full Bitcoin node.

Table of Contents

• Installation
• Quick Start
• Configuration
  • Configuration Hierarchy
  • CLI Arguments
  • Environment Variables
  • Config File
• Operation
  • Running the Node
  • Monitoring
  • Network Modes
• Verification
  • Binary Verification
  • Checksum Verification
  • Verification Bundles
• Advanced Topics
  • Feature Flags
  • Module System
  • Network Configuration
  • Resource Limits
• Troubleshooting
• Architecture
• Building from Source
• License

---

Installation

From Source

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

The binary will be at target/release/blvm.

From Packages

Official and prerelease workflows attach artifacts to GitHub Releases (built on self-hosted Linux):

• Debian/Ubuntu: .deb packages (blvm and blvm-experimental where published; install with sudo apt install ./blvm_*.deb or sudo dpkg -i)
• RPM-based distros: .rpm (native builds and/or conversions from .deb depending on the release)
• Arch-style: .pkg.tar.gz payload tarball (manual pacman -U or unpack usr/bin)
• Windows: .exe installer and cross-compiled .zip archives for x86_64-pc-windows-gnu — download the asset names listed on the release page

---

Quick Start

# Start node in regtest mode (default, safe for development)
blvm

# Start node on testnet
blvm --network testnet

# Custom data directory
blvm --data-dir /var/lib/blvm

# Verbose logging
blvm --verbose

Mainnet: use First mainnet sync below (example config + IBD tuning). Bare blvm --network mainnet skips that and is for advanced use only.

First mainnet sync (release binary)

See Mainnet initial sync for full detail.

tar xzf blvm-v0.1.27-linux-x86_64.tar.gz
cd blvm-v0.1.27-linux-x86_64
sha256sum -c SHA256SUMS-blvm-linux-x86_64
./scripts/start-ibd-mainnet.sh
# BLVM_BACKGROUND=1 ./scripts/start-ibd-mainnet.sh

Uses bundled blvm-mainnet-ibd.toml.example and ~/.local/share/blvm-mainnet. No BLVM_IBD_* env vars required.

Manual: blvm --config blvm-mainnet-ibd.toml.example --network mainnet --data-dir ~/.local/share/blvm-mainnet --verbose

Monitor / resume: blvm --network mainnet --config blvm-mainnet-ibd.toml.example sync — same flags as start; keep the same --data-dir.

Commands

The blvm binary supports subcommands for node management and information queries. If no subcommand is provided, the node starts (default behavior).

Node Information Commands

# Show comprehensive node status
blvm status

# Health check (exit code 0 if healthy)
blvm health

# Show version and build information
blvm version

# Show blockchain information
blvm chain

# Show connected peers
blvm peers

# Show network information
blvm network

# Show sync status (default RPC is regtest :18332 — pass --network for mainnet)
blvm sync
blvm --network mainnet --config blvm-mainnet-ibd.toml.example sync

Subcommands use the same --network, --config, and --rpc-addr as node start. Bare blvm sync targets regtest RPC (18332); a mainnet node listens on 8332.

Configuration Commands

# Show loaded configuration
blvm config show

# Validate configuration file
blvm config validate [path]

# Show configuration file path
blvm config path

RPC Commands

# Direct RPC call
blvm rpc <method> [params]

# Example: Get blockchain info
blvm rpc getblockchaininfo

# Example: Get peer info with custom RPC address
blvm rpc getpeerinfo --rpc-addr 127.0.0.1:8332

Command Options

All information commands support --rpc-addr to override the RPC server address:

blvm status --rpc-addr 127.0.0.1:8332
blvm health --rpc-addr 127.0.0.1:8332

---

Configuration

BLVM supports multiple configuration methods with a clear hierarchy. Configuration is applied in this order (highest to lowest priority):

1. CLI Arguments - Always wins
2. Environment Variables - Override config file
3. Config File - Main configuration source
4. Defaults - Built-in defaults

Configuration Hierarchy

# Example: CLI overrides everything
# Config file: network = "testnet"
# ENV: BLVM_NETWORK="mainnet"
# CLI: --network regtest
# Result: network = regtest (CLI wins)

blvm --config blvm.toml --network regtest

CLI Arguments

Basic Options

Option	Short	Description	Default
--network	-n	Network to connect to (regtest/testnet/mainnet)	regtest
--rpc-addr	-r	RPC server address (network-aware when omitted; see note below)	regtest/testnet: 127.0.0.1:18332; mainnet: 127.0.0.1:8332
--listen-addr	-l	P2P listen address	0.0.0.0:8333
--data-dir	-d	Data directory	./data
--config	-c	Config file path (TOML or JSON)	Auto-detected
--verbose	-v	Enable verbose logging	false

RPC default: When --rpc-addr is omitted, mainnet uses 127.0.0.1:8332; testnet and regtest use 127.0.0.1:18332. BLVM_RPC_ADDR overrides this. Regtest’s default is not Bitcoin Core’s usual 18443; set --rpc-addr or BLVM_RPC_ADDR if you need Core-aligned ports.

Feature Flags

Option	Description
--enable-stratum-v2	Enable Stratum V2 P2P demux + module hooks (requires compile-time feature); miner TCP is blvm-stratum-v2
--disable-stratum-v2	Disable Stratum V2 P2P demux + module hooks (compile-time feature)
--enable-bip158	BIP158 logging preference (filters are always compiled in)
--disable-bip158	BIP158 logging preference (filters are always compiled in)
--enable-dandelion	Enable Dandelion++ privacy relay (requires compile-time feature)
--disable-dandelion	Disable Dandelion++ privacy relay
--enable-sigop	Enable signature operations counting (requires compile-time feature)
--disable-sigop	Disable signature operations counting

Advanced Options

Option	Description	Default
--target-peer-count	Target number of peers to connect to	8
--async-request-timeout	Async request timeout in seconds	300
--module-max-cpu-percent	Module max CPU usage percentage	50
--module-max-memory-bytes	Module max memory in bytes	536870912 (512MB)

Examples:

# Basic usage with CLI
blvm --network mainnet --data-dir /var/lib/blvm

# With feature flags
blvm --enable-stratum-v2 --enable-dandelion

# With advanced options
blvm --target-peer-count 16 --async-request-timeout 600

# Combined
blvm --network testnet \
      --data-dir ./testnet-data \
      --enable-bip158 \
      --target-peer-count 12 \
      --verbose

Environment Variables

Environment variables are ideal for deployment scenarios, especially in containers and systemd services.

Deployment-Critical Variables

Examples below use mainnet-style RPC 8332. The blvm CLI default is 127.0.0.1:18332 unless you override it; set BLVM_RPC_ADDR to the same socket you pass to --rpc-addr.

Variable	Description	Example
BLVM_DATA_DIR	Data directory	/var/lib/blvm
BLVM_NETWORK	Network (regtest/testnet/mainnet)	mainnet
BLVM_LISTEN_ADDR	P2P listen address	0.0.0.0:8333
BLVM_RPC_ADDR	RPC server address	Example: 127.0.0.1:8332 (match your --rpc-addr / network)
BLVM_LOG_LEVEL	Logging level (trace/debug/info/warn/error)	info

Node Settings

Variable	Description	Example
BLVM_NODE_MAX_PEERS	Maximum peer connections	200
BLVM_NODE_TRANSPORT	Transport preference (tcp_only/iroh_only/hybrid)	tcp_only

Feature Flags

Variable	Description	Values
BLVM_NODE_FEATURES_STRATUM_V2	Enable/disable Stratum V2	true/false
BLVM_NODE_FEATURES_DANDELION	Enable/disable Dandelion++	true/false
BLVM_NODE_FEATURES_BIP158	Logged BIP158 preference (true/false) — not a compile-time gate
BLVM_NODE_FEATURES_SIGOP	Enable/disable Sigop counting	true/false

Network Timing

Variable	Description	Default
BLVM_NETWORK_TARGET_PEER_COUNT	Target number of peers	8
BLVM_NETWORK_PEER_CONNECTION_DELAY	Peer connection delay (seconds)	2
BLVM_NETWORK_MAX_ADDRESSES_FROM_DNS	Max addresses from DNS seeds	100

Request Timeouts

Variable	Description	Default
BLVM_REQUEST_ASYNC_TIMEOUT	Async request timeout (seconds)	300
BLVM_REQUEST_UTXO_COMMITMENT_TIMEOUT	UTXO commitment timeout (seconds)	30
BLVM_REQUEST_CLEANUP_INTERVAL	Request cleanup interval (seconds)	60
BLVM_REQUEST_PENDING_MAX_AGE	Max age for pending requests (seconds)	300

IBD (Initial Block Download)

Variable	Description	Values
BLVM_IBD_EVICTION	UTXO eviction strategy during IBD	dynamic / fifo (default) / lifo

• fifo (default): Evict oldest entries first.
• lifo: Evict newest entries first.
• dynamic: Age/dust heuristics — prefer evicting dust, very old outputs, then older; never evict outputs from last 100 blocks.

Module Resource Limits

Variable	Description	Default
BLVM_MODULE_MAX_CPU_PERCENT	Module max CPU usage (%)	50
BLVM_MODULE_MAX_MEMORY_BYTES	Module max memory (bytes)	536870912
BLVM_MODULE_MAX_FILE_DESCRIPTORS	Module max file descriptors	256
BLVM_MODULE_MAX_CHILD_PROCESSES	Module max child processes	10
BLVM_MODULE_STARTUP_WAIT_MILLIS	Module startup wait (ms)	100
BLVM_MODULE_SOCKET_TIMEOUT	Module socket timeout (seconds)	5
BLVM_MODULE_SOCKET_CHECK_INTERVAL	Socket check interval (ms)	100
BLVM_MODULE_SOCKET_MAX_ATTEMPTS	Max socket check attempts	50

Examples:

# Docker/Container deployment
export BLVM_NETWORK=mainnet
export BLVM_DATA_DIR=/data
export BLVM_LISTEN_ADDR=0.0.0.0:8333
export BLVM_RPC_ADDR=0.0.0.0:8332
export BLVM_NODE_MAX_PEERS=200
export BLVM_LOG_LEVEL=info
blvm

# Systemd service (see systemd example below)

Config File

Config files support complex nested configurations. Config files are searched in this order:

1. --config flag path (if specified)
2. ./blvm.toml (current directory)
3. ~/.config/blvm/blvm.toml (user config)
4. /etc/blvm/blvm.toml (system config)

Example config file (blvm.toml):

# Network listening address
listen_addr = "0.0.0.0:8333"

# Transport: in TOML use serde tag tcponly (not tcp_only). CLI / BLVM_NODE_TRANSPORT accept tcp_only.
transport_preference = "tcponly"

# Maximum number of peers
max_peers = 100

# Protocol version: "BitcoinV1", "Testnet3", or "Regtest"
protocol_version = "Regtest"

# Enable self-advertisement (send own address to peers)
enable_self_advertisement = true

# Persistent peers (peers to connect to on startup)
# persistent_peers = ["1.2.3.4:8333", "5.6.7.8:8333"]

# Network timing configuration
[network_timing]
target_peer_count = 8
peer_connection_delay_seconds = 2
addr_relay_min_interval_seconds = 8640
max_addresses_per_addr_message = 1000
max_addresses_from_dns = 100

# Request timeout configuration
[request_timeouts]
async_request_timeout_seconds = 300
utxo_commitment_request_timeout_seconds = 30
request_cleanup_interval_seconds = 60
pending_request_max_age_seconds = 300

# Module resource limits
[module_resource_limits]
default_max_cpu_percent = 50
default_max_memory_bytes = 536870912  # 512 MB
default_max_file_descriptors = 256
default_max_child_processes = 10
module_startup_wait_millis = 100
module_socket_timeout_seconds = 5
module_socket_check_interval_millis = 100
module_socket_max_attempts = 50

# DoS protection configuration
[dos_protection]
max_connections_per_window = 10
window_seconds = 60
max_message_queue_size = 1000
max_active_connections = 1000
auto_ban_threshold = 5
ban_duration_seconds = 3600

# Relay configuration
[relay]
relay_non_standard = false
min_relay_fee = 1000  # satoshis per kB

# Address database configuration
[address_database]
max_addresses = 10000
expiration_seconds = 604800  # 7 days

# Peer rate limiting
[peer_rate_limiting]
enabled = true
messages_per_second = 10
burst_size = 20

# Stratum V2 (requires compile-time feature). Miner TCP = blvm-stratum-v2 module only.
# [stratum_v2]
# enabled = false
# pool_url = "tcp://pool.example.com:3333"
# listen_addr = "0.0.0.0:3333"   # informational on node; does not start in-node miner listener
# p2p_stratum_demux = true       # false = disable P2P Stratum TLV demux (module TCP unchanged)
# transport_preference = "tcponly"
# merge_mining_enabled = false
# secondary_chains = []

# RPC authentication configuration
# [rpc_auth]
# required = false
# tokens = []
# certificates = []
# rate_limit_burst = 100
# rate_limit_rate = 10

# Ban list sharing configuration
# [ban_list_sharing]
# enabled = false
# share_interval_seconds = 3600
# max_entries = 1000

# Storage and pruning configuration
# [storage]
# database_backend = "auto"  # typical release: RocksDB; or "rocksdb", "redb", "sled", "tidesdb"
# 
# [storage.pruning]
# mode = { type = "normal", keep_from_height = 0, min_recent_blocks = 288 }
# auto_prune = true
# min_blocks_to_keep = 144

# Module system configuration
# [modules]
# enabled = true
# modules_dir = "modules"
# data_dir = "data/modules"
# socket_dir = "data/modules/sockets"
# registry_url = "https://raw.githubusercontent.com/BTCDecoded/blvm/main/registry/modules.json"
# enabled_modules = ["blvm-miniscript", "blvm-zmq"]  # default: bootstrap if missing; [] = on-disk only

See blvm.toml.example for a complete example configuration file.

Note: Config files support both TOML and JSON formats (auto-detected by file extension).

---

Operation

Running the Node

Basic Operation

# Start node (regtest mode, default)
blvm

# Start on testnet
blvm --network testnet

# Start on mainnet
blvm --network mainnet --data-dir /var/lib/blvm

With Configuration File

# Use config file
blvm --config /etc/blvm/blvm.toml

# Override config file with CLI
blvm --config /etc/blvm/blvm.toml --network testnet

With Environment Variables

# Set environment variables
export BLVM_NETWORK=mainnet
export BLVM_DATA_DIR=/var/lib/blvm
export BLVM_LOG_LEVEL=info

# Run node
blvm

Monitoring

The node logs to stdout/stderr. Use --verbose for detailed logging:

# Verbose logging
blvm --verbose

# Or set log level via environment
export BLVM_LOG_LEVEL=debug
blvm

Log levels (from most to least verbose):

• trace - Very detailed debugging
• debug - Debugging information
• info - General information (default)
• warn - Warning messages
• error - Error messages only

Network Modes

Regtest (Default)

Regtest mode is safe for development and testing. It creates a local blockchain that you control.

blvm --network regtest

Testnet

Testnet is a public test network with test coins.

blvm --network testnet

Mainnet

Mainnet is the production Bitcoin network. Use with caution.

blvm --network mainnet --data-dir /var/lib/blvm

---

Verification

GitHub Releases attach checksum files next to binaries and packages. Filenames differ by workflow and asset set — common examples: checksums.sha256, SHA256SUMS, SHA256SUMS-<variant>.txt, or a .sha256 next to each artifact. Always use the checksum and signature files from the same release you downloaded.

Checksums

# Example when the release ships a combined file:
sha256sum -c checksums.sha256

# Some releases use SHA256SUMS or per-variant files — use the name shown on the release:
# sha256sum -c SHA256SUMS

Signatures

When detached signatures (.asc / .sig) are published, verify with GPG using the keys and steps linked from the release or from the Installation chapter in BLVM documentation.

Verification bundles (optional)

Some releases include verification-artifacts.tar.gz (tests, spec-lock outputs, source/config hashes). Check the release notes; verify the bundle with its published .sha256 and optional OpenTimestamps .ots when present.

sha256sum -c verification-artifacts.tar.gz.sha256
tar -xzf verification-artifacts.tar.gz
# Inspect verify-artifacts/ per release notes

For OpenTimestamps (if .ots is attached):

pip install opentimestamps-client
ots verify verification-artifacts.tar.gz.ots

---

Advanced Topics

Feature Flags

Some features require compile-time flags. Runtime flags will warn if a feature isn't compiled in.

Compile-time features (extras that are not in every build):

• stratum-v2 - Stratum V2 P2P demux + module integration
• dandelion - Dandelion++ privacy relay
• sigop - Signature operations counting
• iroh - Iroh transport support
• governance - HTTP client for module bootstrap (download official enabled_modules from registry_url; enabled by default in blvm default features)

Always in default blvm-node builds: BIP157/158 compact block filter code (no bip158 Cargo feature flag).

Build with features:

cargo build --release --features stratum-v2,dandelion

Runtime enable/disable:

# Enable via CLI
blvm --enable-stratum-v2 --enable-bip158

# Enable via ENV
export BLVM_NODE_FEATURES_STRATUM_V2=true
export BLVM_NODE_FEATURES_BIP158=true
blvm

# Enable via config file
# See config file example above

Module System

The module system allows extending node functionality with external modules.

Configuration:

[modules]
enabled = true
modules_dir = "modules"
data_dir = "data/modules"
socket_dir = "data/modules/sockets"
registry_url = "https://raw.githubusercontent.com/BTCDecoded/blvm/main/registry/modules.json"
# Default list bootstraps official GitHub Release binaries when missing under modules_dir:
enabled_modules = ["blvm-miniscript", "blvm-zmq"]
# Use enabled_modules = [] for on-disk-only (no HTTP bootstrap). Requires `governance` on the blvm build (default).

Module registry

registry/modules.json maps each module name to a module_toml_url. Download URLs and hashes are in that file’s [downloads] section, not in the JSON.

Only use bootstrap downloads when [downloads] has real url and sha256 values for your platform on the branch you trust (usually main). Empty placeholders mean the release is not ready yet; do a quick install test after a release before relying on it in production.

Resource Limits:

[module_resource_limits]
default_max_cpu_percent = 50
default_max_memory_bytes = 536870912  # 512 MB
default_max_file_descriptors = 256
default_max_child_processes = 10

Network Configuration

Peer Connection Settings

[network_timing]
target_peer_count = 8  # Target number of peers
peer_connection_delay_seconds = 2  # Delay before connecting
max_addresses_from_dns = 100  # Max addresses from DNS seeds

DoS Protection

[dos_protection]
max_connections_per_window = 10
window_seconds = 60
max_message_queue_size = 1000
max_active_connections = 1000
auto_ban_threshold = 5
ban_duration_seconds = 3600

Relay Configuration

[relay]
relay_non_standard = false
min_relay_fee = 1000  # satoshis per kB

Resource Limits

Configure resource limits for modules and network operations:

# Module resource limits
[module_resource_limits]
default_max_cpu_percent = 50
default_max_memory_bytes = 536870912

# Request timeouts
[request_timeouts]
async_request_timeout_seconds = 300
utxo_commitment_request_timeout_seconds = 30

---

Troubleshooting

Mainnet IBD

Symptom	Fix
Quiet 15–60s after start	Wait for peer discovery → IBD: lines
P2P 8333 in use	Stop Core or change listen_addr
blvm sync won't connect	blvm --network mainnet --config … sync (same flags as start)
Slow / stalled sync	Auto-LAN when Core on LAN; else optional BLVM_IBD_PEERS=<ip>:8333
Slow near ~900k+	Normal after assume-valid — see mainnet sync docs
Lost progress on restart	Same --data-dir; don't delete rocksdb/

Common Issues

Node Won't Start

Check data directory permissions:

ls -la /var/lib/blvm
# Ensure directory is writable
chmod 755 /var/lib/blvm

Check port availability:

# Check if port is in use
netstat -tuln | grep 8333
# Or use different port
blvm --listen-addr 0.0.0.0:18333

Connection Issues

Check firewall:

# Allow Bitcoin P2P port (8333 for mainnet, 18333 for testnet)
sudo ufw allow 8333/tcp

Check network configuration:

# Verify network mode
blvm --network testnet --verbose
# Look for connection attempts in logs

Configuration Issues

Verify config file syntax:

# TOML syntax check (if toml-cli installed)
toml validate blvm.toml

Check configuration hierarchy:

# CLI overrides ENV and config file
# Use --verbose to see which values are used
blvm --config blvm.toml --verbose

Debugging

Enable verbose logging:

blvm --verbose
# Or
export BLVM_LOG_LEVEL=debug
blvm

Check logs:

# Logs go to stdout/stderr
blvm 2>&1 | tee blvm.log

Verify binary:

blvm version
# Or: blvm --version

# Checksums: see [Verification](#verification) — filenames on the release vary (`checksums.sha256`, `SHA256SUMS-*`, etc.)

---

Architecture

This binary depends on:

• blvm-node: Core node library (depends on blvm-protocol and blvm-consensus)

Dependency Chain:

blvm (binary)
  └── blvm-node (library)
       ├── blvm-protocol (library)
       │    └── blvm-consensus (library)
       └── blvm-consensus (library)

---

Building from Source

Prerequisites

• Rust toolchain (see rust-toolchain.toml for required version)
• Cargo (comes with Rust)
• Git

Build Steps

# Clone repository
git clone https://github.com/BTCDecoded/blvm.git
cd blvm

# Build release binary
cargo build --release

# Binary will be at target/release/blvm

Build with Features

# Build with all features
cargo build --release --all-features

# Build with specific features
cargo build --release --features stratum-v2,dandelion

Deterministic Builds

For reproducible builds:

# Use locked dependencies
cargo build --release --locked

# Compare locally with the digest published for that release (see GitHub Releases / checksums file for that tag)
sha256sum target/release/blvm

---

Deployment Examples

Docker/Container

# Use environment variables
docker run -e BLVM_NETWORK=mainnet \
           -e BLVM_DATA_DIR=/data \
           -e BLVM_LISTEN_ADDR=0.0.0.0:8333 \
           -e BLVM_RPC_ADDR=0.0.0.0:8332 \
           -e BLVM_NODE_MAX_PEERS=200 \
           -v /path/to/data:/data \
           -p 8333:8333 \
           -p 8332:8332 \
           blvm:latest

Systemd Service

Create /etc/systemd/system/blvm.service:

[Unit]
Description=BLVM Bitcoin Node
After=network.target

[Service]
Type=simple
User=blvm
Group=blvm
Environment="BLVM_NETWORK=mainnet"
Environment="BLVM_DATA_DIR=/var/lib/blvm"
Environment="BLVM_LISTEN_ADDR=0.0.0.0:8333"
Environment="BLVM_RPC_ADDR=127.0.0.1:8332"
Environment="BLVM_LOG_LEVEL=info"
ExecStart=/usr/bin/blvm
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable blvm
sudo systemctl start blvm
sudo systemctl status blvm

Development

# Use config file for development
blvm --config ./blvm.toml --network regtest --verbose

---

License

MIT

---

Additional Resources

• Configuration Guide: See CONFIGURATION.md for detailed configuration documentation
• Example Config: See blvm.toml.example for a complete configuration example
• Project Documentation: https://github.com/BTCDecoded
• Website: https://btcdecoded.org