Introduction

BLVM (Bitcoin Low-Level Virtual Machine) implements Bitcoin consensus from the Orange Paper, provides protocol abstraction for multiple Bitcoin variants, a reference full node with P2P networking, a developer SDK, and cryptographic governance for transparent development.

Who is this for?

Running a Bitcoin node? Operator guide: Installation, Quick Start, First Node Setup (mainnet IBD hub). Read Deployment posture before exposing RPC on mainnet.

Building a module or integrating with the SDK? Developer guide: Building your first module, then Building modules.

Studying the spec or contributing to consensus? The Orange Paper is the normative spec. Formal Verification explains verification. Contributors: Repository layout, Contributing.

What is BLVM?

BLVM is compiler-like infrastructure for Bitcoin implementations. The Orange Paper is the mathematical specification (IR), readable by mathematicians without implementation code. blvm-consensus implements those rules; BLVM Specification Lock (Z3), differential testing, fuzzing, and tests check the code against the spec. See compiler-like architecture, Formal Verification, and the six-layer stack.

Why "LVM"? Like LLVM’s shared compiler infrastructure, BLVM provides shared infrastructure for Bitcoin implementations; the Orange Paper is the reference spec; node and consensus code is validated against it.

Documentation Structure

The sidebar follows three paths from Who is this for:

• Operators: Getting Started → Node → Security
• Developers: Getting Started → SDK and modules → Module runtime (under Architecture)
• Spec and consensus: Architecture → Consensus → Protocol → Reference (Orange Paper)

Cross-cutting: Governance, Development, Appendices.

Documentation is maintained in source repositories alongside code and is aggregated at docs.thebitcoincommons.org. Machine-readable index: docs llms.txt.

Getting Help

Report bugs or request features via GitHub Issues, ask questions in GitHub Discussions, or report security issues to security@thebitcoincommons.org.

Operator guide

How-to hub for running a BLVM node. You do not need the Consensus, Protocol, or Governance sections for day-to-day operations.

New to BLVM? Installation → Quick Start (regtest, ~5 minutes) → this page for ongoing tasks.

First sync and daily run

Initial block download (IBD)

Mainnet first sync touches several docs, use this map instead of reading them in arbitrary order.

Security before mainnet

RPC and monitoring

Storage and network

Mining (optional)

Optional modules

Examples and troubleshooting

• RBF configuration examples
• FAQ
• Troubleshooting

When you need deeper context

• Stack overview: what the crates are
• Node overview: node architecture
• API Index: cross-repo API map

Developer guide

How-to hub for building modules and integrating with the SDK. Consensus and governance docs are optional unless you change consensus-critical code.

Start here: Quick Start (verify a node) → Building your first module (~15 minutes).

Module development

SDK and APIs

Contributing

Spec and verification (when touching consensus)

Architecture context

• Design Philosophy
• Crate dependencies
• Stack overview

Installation

Pre-built blvm binaries, Linux packages, Windows builds, and Docker images are published on GitHub Releases. The book does not pin release numbers: use the install page for the current tag, filenames, and checksum commands.

Install (downloads + verify): btcdecoded.org/install

Always verify checksums.sha256 (or the release checksum file) before running a downloaded artifact.

Platform matrix

Details: Release process: Build variants.

Local cargo build in the blvm repo uses default features unless you pass --no-default-features or explicit --features.

Experimental build variant

Stable GitHub Releases ship the base binary set per tag (platform-specific features: see Release process: Build variants). Extra compile-time features: BIP119 CTV, Stratum V2 node demux, sigop counting, Quinn transport, and flags not in your platform artifact: require a source build with explicit --features.

Build from source

For other architectures, experimental compile-time features, or development: blvm on GitHub and Release process.

Managed installs (not ready yet)

Umbrel App Store: coming soon. Use btcdecoded.org/install, Docker on GHCR, or build from source until managed marketplace listings ship.

Who is this for?

• Operators: Quick Start (regtest) → First Node Setup (config + mainnet IBD)
• Module developers: Building your first module
• Researchers: Introduction

Next steps

• Quick Start
• Deployment posture (before mainnet RPC)
• Node configuration

See also

• Install page: current release downloads
• GitHub Releases (latest)

Quick Start

Tutorial: install the binary, run a regtest node, query RPC, and mine one block. About five minutes. For mainnet, use First Node Setup: Mainnet IBD instead of the steps below.

Prerequisites: Installation completed (blvm on your PATH).

1. Verify the binary

blvm version
blvm --help

You should see a version string and help text (no “command not found”). Version is a subcommand (blvm version), not blvm --version.

2. Start a regtest node

Use a dedicated data directory and a minimal config so regtest mining RPCs work (generatetoaddress is admin-only):

mkdir -p ~/.local/share/blvm-quickstart
cat > ~/.local/share/blvm-quickstart/blvm.toml <<'EOF'
transport_preference = "tcponly"
protocol_version = "Regtest"

[storage]
data_dir = "~/.local/share/blvm-quickstart"

[rpc_auth]
admin_tokens = ["quickstart"]
EOF

blvm --config ~/.local/share/blvm-quickstart/blvm.toml --verbose

In the first log lines, confirm:

• Network: Regtest (or equivalent)
• RPC listening on 127.0.0.1:18443 (regtest default; testnet uses 18332)

Leave this process running. On a fresh datadir, wait until logs show Component startup complete or NodeStartupCompleted (~10-15 seconds) before mining in step 4: RPC listens earlier, but generatetoaddress needs an initialized chain tip.

3. Check chain state

Regtest uses RPC port 18443 (Core-aligned; mainnet 8332, testnet 18332):

curl -s -X POST http://127.0.0.1:18443 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc":"2.0","method":"getblockchaininfo","params":[],"id":1}'

Expected at genesis: "chain":"regtest" and "blocks":0.

4. Mine one block (regtest)

generatetoaddress requires an admin Bearer token (listed in [rpc_auth].admin_tokens):

curl -s -X POST http://127.0.0.1:18443 \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer quickstart" \
 -d '{"jsonrpc":"2.0","method":"generatetoaddress","params":[1,"bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"],"id":2}'

Expected: JSON result with an array of one block hash (hex). Without the Bearer header you get HTTP 403 (requires admin privileges).

5. Confirm the new height

Run getblockchaininfo again (step 3). Expected: "blocks":1 (or higher if you mined more).

You now have a running regtest node that processed at least one block.

Next steps

• Config file and mainnet/testnet: First Node Setup
• Mainnet: First Node Setup: Mainnet IBD and Deployment posture
• Core datadir import: Starting from a Bitcoin Core datadir
• Build a module: Building your first module
• RPC details: RPC API Reference
• Configuration: Node Configuration

First Node Setup

Config-file walkthrough: create ~/.config/blvm/blvm.toml, validate it, start the node, and confirm RPC. For a five-minute regtest tutorial, use Quick Start instead.

Choose a network

Bind addresses and CLI defaults: Node Configuration. Wire magic bytes and ports: Protocol variants.

Use a separate [storage].data_dir per network so chain state never mixes.

Step 1: Create configuration directory

mkdir -p ~/.config/blvm

Step 2: Create blvm.toml

Example for testnet (~/.config/blvm/blvm-testnet.toml) or learning config shape:

transport_preference = "tcponly"
listen_addr = "0.0.0.0:18333"
protocol_version = "Testnet3"

[storage]
data_dir = "~/.local/share/blvm-testnet"
database_backend = "auto"

[logging]
level = "info"

For mainnet first sync, skip this minimal template: use the IBD example config (blvm-mainnet-ibd.toml.example) with pruning and parallel IBD instead.

• transport_preference is required in TOML (no serde default when loading a file).
• RPC bind uses --rpc-addr / BLVM_RPC_ADDR; the optional [rpc] table is limits only: see Node Configuration.
• Production: configure [rpc_auth] before exposing RPC beyond loopback. See Deployment posture.

Step 2b: Validate the file

blvm config validate ~/.config/blvm/blvm-testnet.toml

Expected: Configuration file is valid: (with the path).

Step 3: Start the node

env -u BLVM_ASSUME_VALID_HEIGHT \
 blvm --config ~/.config/blvm/blvm-testnet.toml --verbose

Confirm in the first log lines: config loaded, Network: …, and Data directory: matches [storage].data_dir.

Step 4: Verify RPC

Testnet 18332; regtest 18443; mainnet 8332:

curl -s -X POST http://127.0.0.1:18332 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc":"2.0","method":"getblockchaininfo","params":[],"id":1}'

See RPC API Reference for authentication and the full method list.

Mainnet initial sync

After Installation. Do not start first mainnet sync with bare blvm --network mainnet: use the release IBD example config (pruning, [ibd].mode = "parallel", [modules].enabled = false during sync). Source: blvm-mainnet-ibd.toml.example.

From a release directory (contains blvm, scripts/, and the example TOML):

cd /path/to/your/blvm-release
./scripts/start-ibd-mainnet.sh

Seed ~/.config/blvm/blvm.toml from the example: ./scripts/start-ibd-mainnet.sh --init-config, edit peers if you have LAN Core, then run again.

With blvm on PATH only:

blvm --config /path/to/blvm-mainnet-ibd.toml.example \
 --network mainnet \
 --data-dir ~/.local/share/blvm-mainnet \
 --verbose

What you should see: config loads → Network: Mainnet → quiet 15-60s (peer discovery) → IBD: <height> / <tip> in logs. Plan for ~15 GB+ pruned disk, hours on WAN-only (faster with LAN Core). Validation slows near ~900k+ when assume-valid ends: expected.

Monitor (match start flags):

blvm --network mainnet \
 --config ~/.config/blvm/blvm.toml \
 --data-dir ~/.local/share/blvm-mainnet \
 sync

Resume: reuse the same --data-dir; never delete the active backend dir (heed3/, rocksdb/, …) mid-IBD.

Tune when needed: BLVM_IBD_PEERS, BLVM_IBD_MODE, BLVM_IBD_WAN_SINGLE_PEER=1, BLVM_IBD_ENGINE=1: see Node configuration: IBD, IBD UTXO engine, Troubleshooting: Mainnet IBD.

Other network examples

Regtest (local dev)

transport_preference = "tcponly"
listen_addr = "127.0.0.1:18445" # default P2P is 18444
protocol_version = "Regtest"

[storage]
data_dir = "~/.local/share/blvm-regtest"
database_backend = "auto"

[rpc_auth]
admin_tokens = ["dev"]

No public seeds: see Quick Start for generatetoaddress.

Storage

Blocks, UTXO set, chain state, and indexes live under [storage].data_dir. See Storage Backends.

Peers and sync

• Mainnet / testnet: DNS seeds and addr relay.
• Regtest: only configured peers; height stays at genesis until you add one.

See also

• Node Configuration · Configuration Reference
• Node Operations: backup, Core datadir import
• Deployment posture: before exposing mainnet RPC

Building your first module

Tutorial: load a minimal read-only module on a regtest node and confirm it receives NewBlock events.

Prerequisites: Quick Start (regtest node running), Rust toolchain, Module system overview.

Time: ~15 minutes for an experienced Rust developer.

What you will build

hello-module: a process-isolated module that:

• Declares read_blockchain and subscribe_events in module.toml
• Subscribes to NewBlock and logs the block hash
• Loads via a [modules] pin in blvm.toml

Full patterns (manifest fields, NodeAPI, publishing events) live in Building modules.

1. Scaffold the crate

mkdir -p modules/hello-module/src
cd modules/hello-module

Cargo.toml (minimal):

[package]
name = "hello-module"
version = "0.1.0" # your crate semver (not tied to BLVM releases)
edition = "2024"

[dependencies]
blvm-sdk = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
tracing = "0.1"
tracing-subscriber = "0.3"

module.toml:

name = "hello-module"
version = "0.1.0" # manifest semver for your module
description = "Tutorial hello module"
entry_point = "hello-module"

capabilities = [
 "read_blockchain",
 "subscribe_events",
]

Implement main.rs using the blvm-sdk module runner: subscribe to NewBlock, log block_hash from the event payload. Copy the event-loop skeleton from Building modules: Module lifecycle and replace the handler body with a tracing::info! on NewBlock.

2. Build the binary

cargo build --release

Expected: target/release/hello-module with no errors.

3. Install on the module search path

Either copy into the node modules directory:

NODE_MODULES=~/.local/share/blvm/modules
mkdir -p "$NODE_MODULES/hello-module/target/release"
cp target/release/hello-module "$NODE_MODULES/hello-module/target/release/"
cp module.toml "$NODE_MODULES/hello-module/"

Or pin a published crate via the registry (production path): see Installing modules.

4. Enable in blvm.toml

On the regtest node from Quick Start, add:

[modules]
registry_url = "https://raw.githubusercontent.com/BTCDecoded/blvm/main/registry/modules.json"
hello-module = "0.1.*" # local build: place binary under modules_dir first
modules_dir = "~/.local/share/blvm-quickstart/modules"

Restart the node with --verbose.

5. Verify loading

Expected log lines (wording may vary):

• Module hello-module loaded / started
• No capability or manifest errors

Mine a block (Quick Start step 4) or use First Node Setup. Expected when a block connects:

• NewBlock log line with a 32-byte hash from your module

Troubleshooting

Next steps

• Building modules: IPC, NodeAPI, publishing events, inter-module calls
• Module catalog: production modules (mesh, zmq, stratum-v2, …)
• SDK overview

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)

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)

• Reference full node: non-consensus storage, P2P, RPC, and module system
• Multi-transport networking and operational hardening for real deployments
• Component detail, lifecycle, and features: Node overview

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

• Direct implementation of Orange Paper specifications
• Formal verification with BLVM Specification Lock
• Property-based testing for mathematical invariants
• Formal proofs verify critical consensus functions

Protocol Abstraction

• Multiple Bitcoin variants (mainnet, testnet, regtest)
• Commons-specific protocol extensions
• BIP implementations (BIP152, BIP157, BIP158)
• Protocol evolution support

Node and operational features

• Full Bitcoin node-style functionality when configured and secured appropriately
• Details: Node overview, performance, storage backends, transport abstraction

Governance Infrastructure

• Cryptographic governance primitives
• Multisig threshold enforcement
• Transparent audit trails
• Forkable governance rules

Source repositories

See Also

• Crate dependencies - Dependency graph and governance layers by crate
• Design Philosophy - Core design principles
• Module System - Module system architecture
• Node Overview - Node implementation details
• Consensus Overview - Consensus layer details
• Protocol Overview - Protocol layer details

Design Philosophy

BLVM is built for teams who need Bitcoin consensus correctness to be checkable, protocol evolution to be bounded, and node features to be extensible without touching consensus. The principles below are the reasoning behind that shape, not slogans.

Core Principles

1. Mathematical correctness first

Problem: Hand-wavy “Bitcoin-compatible” implementations drift from mainnet rules under edge cases (witness nesting, sighash variants, soft-fork activation boundaries).

Alternative: Interpret Bitcoin Core’s C++ informally and patch when differential tests fail.

Choice: The Orange Paper is the normative spec, written so consensus can be reviewed in mathematical notation without reading implementation code. blvm-consensus implements it; BLVM Specification Lock, differential testing, fuzzing, and review keep the code aligned with that document. Pure functions where the design allows so behavior is reproducible in tests and proofs.

2. Layered architecture

Problem: Monolithic nodes mix networking bugs with consensus bugs; upgrades become risky all-or-nothing releases.

Alternative: Microservices with shared mutable state (harder to reason about than a disciplined monolith).

Choice: Strict crate layers: spec → consensus → protocol → node → SDK → governance tooling. Lower layers do not depend on RPC or modules. Each layer can be tested and versioned independently within release sets.

3. Zero consensus re-implementation

Problem: A payment module or RPC handler that “fixes” validation logic creates a fork risk invisible until mainnet.

Alternative: Allow application code to call internal consensus helpers with ad hoc flags.

Choice: All rule changes flow through blvm-consensus. blvm-protocol varies network parameters and message framing; blvm-node orchestrates I/O. Modules run out-of-process and cannot rewrite the UTXO set or block acceptance rules.

4. Cryptographic governance

Problem: Open-source governance often relies on social consensus alone; capture and silent policy drift are hard to detect.

Alternative: Fully automated on-chain governance (inappropriate for a node implementation project).

Choice: Apply Bitcoin-style multisig and audit trails to repository and release policy (governance). Power is visible; changing security-critical code requires documented tiers and signatures, not a single maintainer click.

5. User sovereignty

Problem: Forced upgrades and opaque defaults push operators onto configurations they did not choose.

Alternative: Infinite per-user consensus forks in one binary (unmaintainable).

Choice: Operators pick network, features, and modules. Governance is forkable: disagree with policy → run a fork with transparent rules rather than hidden behavior in a shared binary.

Design Decisions (expanded)

Why pure functions in consensus?

Deterministic, side-effect-free validation makes differential testing against Core, property tests, and spec-lock proofs tractable. The cost is explicit data passing (UTXO views, flags) instead of hidden global state, which is appropriate for consensus.

Why formal verification alongside tests?

Tests cannot exhaust script and block combinatorics. BLVM Specification Lock, differential testing, fuzzing, and proptest form a continuous assurance stack on top of the Orange Paper. See Formal Verification.

Why process-isolated modules?

In-process plugins are faster but share address space with the node. Choice: optional features (Lightning, Stratum, ZMQ, mesh) as separate processes with capability-based IPC. A module crash should not corrupt chainstate; a malicious module should not get write access to consensus state.

Why cryptographic governance instead of policy docs only?

Policy PDFs do not enforce themselves on GitHub. Wiring security-control classification into PR tiers makes “who must sign this change?” a machine-checkable question for contributors. Operators still rely on Deployment posture for runtime exposure, not this system.

Trade-offs

Design Evolution

BLVM targets long-horizon Bitcoin infrastructure:

• Protocol evolution through blvm-protocol variants and BIPs, not ad hoc node patches
• Feature addition via modules and optional compile-time features (experimental builds)
• Governance evolution through documented tier changes, not silent CI edits
• Multiple implementations sharing the Orange Paper as common IR

See Also

• Stack overview: Six-layer stack summary
• Crate dependencies: Dependency graph
• Consensus Overview: How correctness is structured in code
• Governance Overview: Cryptographic governance
• Orange Paper: Mathematical foundation

Crate dependencies

BLVM is a six-layer stack. Stack layer means architecture position, not governance repository layers or governance tiers (PR classification). Layer descriptions and the stack diagram: Stack overview.

Dependency Graph

Edges point from a crate toward a crate it depends on (library import direction). The Orange Paper is not a Rust crate; it informs consensus (dotted).

blvm-primitives (types, serialization, crypto) sits under blvm-consensus and blvm-protocol; it is not shown as its own stack layer here.

Governance repository layers by crate

See Governance layers and tiers for how layers combine with PR tiers.

Data flow

The dependency graph above is the accurate picture for crate dependencies. At runtime, blocks and transactions flow through the node, which calls into protocol and consensus libraries to validate; the Orange Paper remains the specification those libraries implement.

Figure: Operational view (IBD, validation, modules, governance). For which crate depends on which, use the dependency graph in this page.

1. Orange Paper specifies consensus rules.
2. blvm-consensus implements those rules (pure functions).
3. blvm-protocol layers network parameters, wire helpers, and protocol policy on top of consensus types.
4. blvm-node runs networking, storage, RPC, and orchestration; validation calls into protocol + consensus.
5. blvm-sdk supplies governance crypto, composition, and (optional) node integration for modules.
6. blvm-commons runs governance enforcement services using blvm-sdk and blvm-protocol types.

Cross-Layer Validation

• Dependencies between layers are strictly enforced in the crate graph (no application layer should 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 “one-shot” equivalence proof of the whole spec.
• Version coordination (Cargo / release sets) keeps compatible crate versions together.

See Also

• Stack overview - Six-layer stack and component summary
• Design Philosophy - Core design principles
• Consensus Overview - Consensus layer details
• Protocol Overview - Protocol layer details
• Node Overview - Node implementation details

Module system (design)

Overview

Optional features (Lightning Network, merge mining, privacy relays) run in separate processes with IPC communication.

Registry-backed modules (blvm-zmq, blvm-miniscript, blvm-governance, blvm-fibre, optional blvm-marketplace) bootstrap from [modules].registry_url (registry/modules.json) when pinned under [modules]: see Module catalog.

Available modules

• Lightning Network Module: Lightning payment processing
• Commons Mesh Module: Payment-gated mesh overlay; four JSON-RPC methods when blvm-mesh is loaded
• Stratum V2 Module: Stratum V2 mining protocol
• Datum Module: DATUM Gateway mining protocol
• blvm-zmq: ZMQ module
• blvm-miniscript: Miniscript module
• blvm-governance: Governance module
• blvm-fibre: FIBRE module
• blvm-marketplace: Marketplace module (optional; registry bootstrap usually does not need it)

For detailed documentation on each module, see the Modules section.

Writing modules: Use the SDK declarative style (blvm-sdk attribute macros and run_module!) to define CLI, RPC, and event handling in one impl block without manual IPC loops; see Building modules. Alternatively use the integration API or low-level IPC for custom control.

Architecture

Process Isolation

Each module runs in a separate process with isolated memory. The base node consensus state is protected and read-only to modules.

Core Components

ModuleManager

Orchestrates all modules, handling lifecycle, runtime loading/unloading/reloading, and coordination.

Features:

• Module discovery and loading
• Process spawning and monitoring
• IPC server management
• Event subscription management
• Dependency resolution
• Registry integration

Process Isolation

Modules run in separate processes via ModuleProcessSpawner:

• Separate memory space
• Isolated execution environment
• Resource limits enforced
• Crash containment

IPC Communication

Modules communicate with the base node via Unix domain sockets (Unix) or named pipes (Windows):

• Request/response protocol
• Event subscription system (SubscribeEvents / EventType: node → module notifications)
• Correlation IDs for async operations
• Type-safe message serialization
• Targeted node control (module → node): NodeAPI / IPC also exposes bounded writes that are not consensus changes: e.g. P2P serve denylists (block/tx getdata policy), get_sync_status, ban_peer, and block-serve maintenance mode. Details: Module IPC Protocol, Module development.

Security Sandbox

Modules run in sandboxed environments with:

• Resource limits (CPU, memory, file descriptors)
• Filesystem restrictions
• Network restrictions
• Permission-based API access

Permission System

Modules request capabilities that are validated before API access. Capabilities use snake_case in module.toml (e.g., read_blockchain) and map to Permission enum variants (e.g., ReadBlockchain).

Core Permissions:

• read_blockchain / ReadBlockchain - Read-only blockchain access (blocks, headers, transactions)
• read_utxo / ReadUTXO - Query UTXO set (read-only)
• read_chain_state / ReadChainState - Query chain state (height, tip)
• subscribe_events / SubscribeEvents - Subscribe to node events
• send_transactions / SendTransactions - Submit transactions to mempool (future: may be restricted)

Mempool & Network Permissions:

• read_mempool / ReadMempool - Read mempool data (transactions, size, fee estimates)
• read_network / ReadNetwork - Read network data (peers, stats)
• network_access / NetworkAccess - Send network packets (mesh packets, etc.)

Lightning & Payment Permissions:

• read_lightning / ReadLightning - Read Lightning network data
• read_payment / ReadPayment - Read payment data

Storage Permissions:

• read_storage / ReadStorage - Read from module storage
• write_storage / WriteStorage - Write to module storage
• manage_storage / ManageStorage - Manage storage (create/delete trees, manage quotas)

Filesystem Permissions:

• read_filesystem / ReadFilesystem - Read files from module data directory
• write_filesystem / WriteFilesystem - Write files to module data directory
• manage_filesystem / ManageFilesystem - Manage filesystem (create/delete directories, manage quotas)

RPC & Timers Permissions:

• register_rpc_endpoint / RegisterRpcEndpoint - Register RPC endpoints
• manage_timers / ManageTimers - Manage timers and scheduled tasks

Metrics Permissions:

• report_metrics / ReportMetrics - Report metrics
• read_metrics / ReadMetrics - Read metrics

Module Communication Permissions:

• discover_modules / DiscoverModules - Discover other modules
• publish_events / PublishEvents - Publish events to other modules
• call_module / CallModule - Call other modules' APIs
• register_module_api / RegisterModuleApi - Register in-process module API, or (spawned) send method descriptor so the node installs IpcForwardingModuleAPI

Module Lifecycle

Discovery → Verification → Loading → Execution → Monitoring
 │ │ │ │ │
 │ │ │ │ │
 ▼ ▼ ▼ ▼ ▼
Registry Signer Loader Process Monitor

Discovery

Modules are discovered through:

1. Local filesystem: scan [modules].modules_dir for module.toml + binaries
2. Registry bootstrap: when [modules].registry_url is set and a module is pinned (inline blvm-zmq = "0.1.*" etc.), missing versions are downloaded from GitHub Releases (see Installing modules)
3. Runtime load: loadmodule / blvm load after the node is running (admin RPC)
4. Optional marketplace: blvm-marketplace module for paid installs and legacy registry URL fallback; loadmodule remote auto-fetch is opt-in and off by default

Verification

Each module verified through:

• Hash verification (binary integrity)
• Signature verification (multisig maintainer signatures)
• Permission checking (capability validation)
• Compatibility checking (version requirements)

Loading

Module loaded into isolated process:

• Sandbox creation (resource limits)
• IPC connection establishment
• API subscription setup

Execution

Module runs in isolated process:

• Separate memory space
• Resource limits enforced
• IPC communication only
• Event subscription active

Monitoring

Module health monitored:

• Process status tracking
• Resource usage monitoring
• Error tracking
• Crash isolation

Security Model

Consensus Isolation

Modules cannot:

• Modify consensus rules
• Modify UTXO set
• Access node private keys
• Bypass security boundaries
• Affect other modules

Guarantee: Module failures are isolated and cannot affect consensus.

Crash Containment

Module crashes are isolated and do not affect the base node. The ModuleProcessMonitor detects crashes and automatically removes failed modules.

Security Flow

Module Binary
 │
 ├─→ Hash Verification ──→ Integrity Check
 │
 ├─→ Signature Verification ──→ Multisig Check ──→ Maintainer Verification
 │
 ├─→ Permission Check ──→ Capability Validation
 │
 └─→ Sandbox Creation ──→ Resource Limits ──→ Isolation

Module Manifest

Module manifests use TOML format:

# Module Identity (manifest `name` must match [modules] pin and [modules.<name>] tables)
name = "blvm-lightning"
version = "1.2.3"
description = "Lightning Network implementation"
author = "Alice <alice@example.com>"

# Governance
[governance]
tier = "application"
maintainers = ["alice", "bob", "charlie"]
threshold = "2-of-3"
review_period_days = 14

# Signatures
[signatures]
maintainers = [
 { name = "alice", key = "02abc...", signature = "..." },
 { name = "bob", key = "03def...", signature = "..." }
]
threshold = "2-of-3"

# Binary
[binary]
hash = "sha256:abc123..."
size = 1234567
download_url = "https://github.com/BTCDecoded/blvm-lightning/releases/download/v1.2.3/blvm-lightning"

# Dependencies
[dependencies]
"blvm-node" = ">=1.0.0"
"another-module" = ">=0.5.0"

# Compatibility
[compatibility]
min_consensus_version = "1.0.0"
min_protocol_version = "1.0.0"
min_node_version = "1.0.0"
tested_with = ["1.0.0", "1.1.0"]

# Capabilities
capabilities = [
 "read_blockchain",
 "subscribe_events"
]

API Hub

The ModuleApiHub routes API requests from modules to the appropriate handlers:

• Blockchain API (blocks, headers, transactions)
• Governance API (proposals, votes)
• Communication API (P2P messaging)

Event System

Modules subscribe to node state changes, blockchain events, and system lifecycle events through the event system.

Event Subscription

Modules subscribe to events they need during initialization:

#![allow(unused)]
fn main() {
let event_types = vec![
 EventType::NewBlock,
 EventType::NewTransaction,
 EventType::ModuleLoaded,
 EventType::ConfigLoaded,
];
client.subscribe_events(event_types).await?;
}

Event Categories

Catalog of shared EventType variants on the node bus. Individual modules subscribe/publish subsets only: see each module page (e.g. blvm-lightning does not emit ChannelOpened; blvm-stratum-v2 does not emit MiningPoolConnected).

• NewBlock - Block connected to chain
• NewTransaction - Transaction in mempool
• BlockDisconnected - Block disconnected (reorg)
• ChainReorg - Chain reorganization

Payment Events:

• PaymentRequestCreated - Payment request created
• PaymentSettled - Payment settled (confirmed on-chain)
• PaymentFailed - Payment failed
• PaymentVerified - Lightning payment verified
• PaymentRouteFound - Payment route discovered
• PaymentRouteFailed - Payment routing failed
• ChannelOpened - Lightning channel opened
• ChannelClosed - Lightning channel closed

Mining Events:

• BlockMined - Block mined successfully
• BlockTemplateUpdated - Block template updated
• MiningDifficultyChanged - Mining difficulty changed
• MiningJobCreated - Mining job created
• ShareSubmitted - Mining share submitted
• MergeMiningReward - Merge mining reward received
• MiningPoolConnected - Mining pool connected
• MiningPoolDisconnected - Mining pool disconnected

Mesh Networking Events:

• MeshPacketReceived - Mesh packet received from network

Stratum V2 Events:

• StratumV2MessageReceived - Stratum V2 message received from network

Module Lifecycle Events:

• ModuleLoaded - Module loaded (published after subscription)
• ModuleUnloaded - Module unloaded
• ModuleCrashed - Module crashed
• ModuleDiscovered - Module discovered
• ModuleInstalled - Module installed
• ModuleUpdated - Module updated
• ModuleRemoved - Module removed

Configuration Events:

• ConfigLoaded - Node configuration loaded/changed

Node Lifecycle Events:

• NodeStartupCompleted - Node fully operational
• NodeShutdown - Node shutting down
• NodeShutdownCompleted - Shutdown complete

Maintenance Events:

• DataMaintenance - Unified cleanup/flush event (replaces StorageFlush + DataCleanup)
• MaintenanceStarted - Maintenance started
• MaintenanceCompleted - Maintenance completed
• HealthCheck - Health check performed

Resource Management Events:

• DiskSpaceLow - Disk space low
• ResourceLimitWarning - Resource limit warning

Governance Events:

• GovernanceProposalCreated - Proposal created
• GovernanceProposalVoted - Vote cast
• GovernanceProposalMerged - Proposal merged
• GovernanceForkDetected - Governance fork detected
• WebhookSent - Webhook sent
• WebhookFailed - Webhook delivery failed

Network Events:

• PeerConnected - Peer connected
• PeerDisconnected - Peer disconnected
• PeerBanned - Peer banned
• PeerUnbanned - Peer unbanned
• MessageReceived - Network message received
• MessageSent - Network message sent
• BroadcastStarted - Broadcast started
• BroadcastCompleted - Broadcast completed
• RouteDiscovered - Route discovered
• RouteFailed - Route failed
• ConnectionAttempt - Connection attempt (success/failure)
• AddressDiscovered - New peer address discovered
• AddressExpired - Peer address expired
• NetworkPartition - Network partition detected
• NetworkReconnected - Network partition reconnected
• DoSAttackDetected - DoS attack detected
• RateLimitExceeded - Rate limit exceeded

Consensus Events:

• BlockValidationStarted - Block validation started
• BlockValidationCompleted - Block validation completed (success/failure)
• ScriptVerificationStarted - Script verification started
• ScriptVerificationCompleted - Script verification completed
• UTXOValidationStarted - UTXO validation started
• UTXOValidationCompleted - UTXO validation completed
• DifficultyAdjusted - Network difficulty adjusted
• SoftForkActivated - Soft fork activated (SegWit, Taproot, CTV, etc.)
• SoftForkLockedIn - Soft fork locked in (BIP9)
• ConsensusRuleViolation - Consensus rule violation detected

Sync Events:

• HeadersSyncStarted - Headers sync started
• HeadersSyncProgress - Headers sync progress update
• HeadersSyncCompleted - Headers sync completed
• BlockSyncStarted - Block sync started (IBD)
• BlockSyncProgress - Block sync progress update
• BlockSyncCompleted - Block sync completed

Mempool Events:

• MempoolTransactionAdded - Transaction added to mempool
• MempoolTransactionRemoved - Transaction removed from mempool
• FeeRateChanged - Fee rate changed

Additional Event Categories:

• Dandelion++ Events (DandelionStemStarted, DandelionStemAdvanced, DandelionFluffed, etc.)
• Compact Blocks Events (CompactBlockReceived, BlockReconstructionStarted, etc.)
• FIBRE Events (FibreBlockEncoded, FibreBlockSent, CompanionUdpPeerRegistered / CompanionUdpPeerUnregistered for NODE_FIBRE companion UDP)
• Package Relay Events (PackageReceived, PackageRejected)
• UTXO Commitments Events (UtxoCommitmentReceived, UtxoCommitmentVerified)
• Ban List Sharing Events (BanListShared, BanListReceived)

For a complete list of all event types, see EventType enum.

Delivery guarantees, timing (ModuleLoaded ordering), backpressure, and monitoring: Module events. Maintenance payloads: Janitorial events.

Module Registry

Two related mechanisms:

Bootstrap does not require the marketplace module for standard pins (blvm-zmq, blvm-miniscript, …). See Marketplace module.

Verification at install time includes release checksums (sha256sums.txt on module tags) when using bootstrap; additional signature/multisig policy is deployment-specific.

Usage

Loading a Module

#![allow(unused)]
fn main() {
use blvm_node::module::{ModuleManager, ModuleMetadata};

let mut manager = ModuleManager::new(
 modules_dir,
 data_dir,
 socket_dir,
);

manager.start(socket_path, node_api).await?;

manager.load_module(
 "blvm-lightning",
 binary_path,
 metadata,
 config,
).await?;
}

Auto-Discovery

#![allow(unused)]
fn main() {
// Automatically discover and load all modules
manager.auto_load_modules().await?;
}

Benefits

1. Consensus Isolation: Modules cannot affect consensus rules
2. Crash Containment: Module failures don't affect base node
3. Security: Process isolation and permission system
4. Extensibility: Add features without consensus changes
5. Flexibility: Load/unload modules at runtime
6. Governance: Modules subject to governance approval

Use Cases

• Lightning Network: Payment channel management
• Merge Mining: Auxiliary chain support
• Privacy Enhancements: Transaction mixing, coinjoin
• Alternative Mempool Policies: Custom transaction selection
• Smart Contracts: Layer 2 contract execution

Components

The module system includes:

• Process isolation
• IPC communication
• Security sandboxing
• Permission system
• Module registry
• Event system
• API hub

IPC Communication

Modules communicate with the node via the Module IPC Protocol:

• Protocol: Length-delimited binary messages over Unix domain sockets
• Message Types: Requests, Responses, Events, Logs
• Security: Process isolation, permission-based API access, resource sandboxing
• Performance: Persistent connections, concurrent requests, correlation IDs

Integration Approaches

There are two approaches for modules to integrate with the node:

1. ModuleIntegration (Recommended for New Modules)

The ModuleIntegration API wraps connect, subscribe, and RPC helpers:

#![allow(unused)]
fn main() {
use blvm_node::module::integration::ModuleIntegration;

// Connect to node (socket_path must be PathBuf)
let socket_path = std::path::PathBuf::from(socket_path);
let mut integration = ModuleIntegration::connect(
 socket_path,
 module_id,
 module_name,
 version,
).await?;

// Subscribe to events
integration.subscribe_events(event_types).await?;

// Get NodeAPI
let node_api = integration.node_api();

// Get event receiver
let mut event_receiver = integration.event_receiver();
}

Benefits:

• One API for connect, subscribe, and RPC calls
• Automatic handshake and connection management
• Simplified event subscription
• Direct access to NodeAPI and event receiver

Used by: blvm-mesh and its submodules (blvm-onion, blvm-mining-pool, blvm-messaging, blvm-bridge)

2. ModuleClient + NodeApiIpc (Legacy Approach)

The traditional approach uses separate components:

#![allow(unused)]
fn main() {
use blvm_node::module::ipc::client::ModuleIpcClient;
use blvm_node::module::api::node_api::NodeApiIpc;

// Connect to IPC socket
let mut ipc_client = ModuleIpcClient::connect(&socket_path).await?;

// Perform handshake manually
let handshake_request = RequestMessage { /* ... */ };
let response = ipc_client.request(handshake_request).await?;

// Create NodeAPI wrapper
// NodeApiIpc requires Arc<Mutex<ModuleIpcClient>> and module_id
let ipc_client_arc = Arc::new(tokio::sync::Mutex::new(ipc_client));
let node_api = Arc::new(NodeApiIpc::new(ipc_client_arc, "my-module".to_string()));

// Create ModuleClient for event subscription
let mut client = ModuleClient::connect(/* ... */).await?;
client.subscribe_events(event_types).await?;
let mut event_receiver = client.event_receiver();
}

Benefits:

• More granular control over IPC communication
• Direct access to IPC client for custom requests
• Established, stable API

Used by: blvm-lightning, blvm-stratum-v2, blvm-datum, blvm-miningos

Migration: New modules should use ModuleIntegration. Existing modules can continue using ModuleClient + NodeApiIpc, but migration to ModuleIntegration is recommended for consistency and simplicity.

For detailed protocol documentation, see Module IPC Protocol.

Source

• mod.rs
• manager.rs
• spawner.rs
• protocol.rs
• network.rs
• permissions.rs
• discovery.rs
• manifest_validator.rs
• monitor.rs
• manifest.rs
• hub.rs
• events.rs
• client.rs
• blvm-node/src/module/

See Also

• Module IPC Protocol - Complete IPC protocol documentation
• Module catalog - Overview of all available modules
• Lightning Network Module - Lightning Network payment processing
• Commons Mesh Module - Payment-gated mesh networking
• Stratum V2 Module - Stratum V2 mining protocol
• Datum Module - DATUM Gateway mining protocol
• Building modules - Guide for developing custom modules

Module IPC Protocol

Overview

The Module IPC (Inter-Process Communication) protocol enables secure communication between process-isolated modules and the base node. Modules run in separate processes and communicate via Unix domain sockets using a length-delimited binary message protocol.

Architecture

┌─────────────────────────────────────┐
│ blvm-node Process │
│ ┌───────────────────────────────┐ │
│ │ Module IPC Server │ │
│ │ (Unix Domain Socket) │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘
 │ IPC Protocol
 │ (Unix Domain Socket)
 │
┌─────────────┴─────────────────────┐
│ Module Process (Isolated) │
│ ┌───────────────────────────────┐ │
│ │ Module IPC Client │ │
│ │ (Unix Domain Socket) │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘

Protocol Format

Message Encoding

Messages use length-delimited binary encoding:

[4-byte length][message payload]

• Length: 4-byte little-endian integer (message size)
• Payload: Binary-encoded message (bincode serialization)

Message Types

The protocol uses length-delimited ModuleMessage variants:

1. Request: module → node (NodeAPI calls, handshake, RegisterModuleApi, …)
2. Response: node → module
3. Event: node → module (subscribed notifications)
4. Log: module → node (forwarded to node logging)
5. Invocation: node → module (CLI, RPC, or ModuleApi dispatch)
6. InvocationResult: module → node (correlated reply)

Message Structure

Request Message

#![allow(unused)]
fn main() {
pub struct RequestMessage {
 pub correlation_id: CorrelationId,
 pub request_type: MessageType,
 pub payload: RequestPayload,
}
}

Request types (representative):

Reads and subscriptions include GetBlock, GetBlockHeader, GetTransaction, GetChainTip, GetBlockHeight, GetUTXO, SubscribeEvents, GetMempoolTransactions, GetNetworkStats, GetNetworkPeers, GetChainInfo, and many others (mining, storage, RPC, timers, …).

P2P serve policy & sync (module → node):

These affect relay/serving only, not consensus validation. See NodeAPI for the Rust surface.

Response Message

#![allow(unused)]
fn main() {
pub struct ResponseMessage {
 pub correlation_id: CorrelationId,
 pub payload: ResponsePayload,
}
}

Response payload variants carry typed data (blocks, templates, snapshots, booleans, errors, etc.); denylist merges return dedicated merged/snapshot payloads where applicable.

Event Message

#![allow(unused)]
fn main() {
pub struct EventMessage {
 pub event_type: EventType,
 pub payload: EventPayload,
}
}

Event types: The node defines many EventType values (chain, mempool, network, payments, mining, mesh, sync, modules, governance, maintenance, …). Modules subscribe to a subset via SubscribeEvents. See the EventType enum in traits.rs for the authoritative list: do not assume a fixed count in docs.

Log Message

#![allow(unused)]
fn main() {
pub struct LogMessage {
 pub level: LogLevel,
 pub message: String,
 pub module_id: String,
}
}

Log Levels: Error, Warn, Info, Debug, Trace

Communication Flow

Request-Response Pattern

1. Module sends Request: Module sends request message with correlation ID
2. Node processes Request: Node processes request and generates response
3. Node sends Response: Node sends response with matching correlation ID
4. Module receives Response: Module matches response to request using correlation ID

Invocation pattern (CLI, RPC, ModuleAPI)

The node sends Invocation messages to a connected module subprocess:

The module replies with InvocationResult (same correlation_id). For ModuleApi, the payload is opaque bytes (InvocationResultPayload::ModuleApi).

Subprocess ModuleAPI registration

Spawned modules use blvm-sdk run_module_with_setup_and_api (not plain run_module!) when they register a ModuleAPI over IPC.

Spawned modules cannot pass Arc<dyn ModuleAPI> into the node process. Instead:

1. Module sends RegisterModuleApi with method names and API version.
2. Node installs IpcForwardingModuleAPI in the module registry.
3. Other callers use call_module (or node RPC such as meshsendpacket) → node sends InvocationType::ModuleApi to the subprocess.
4. On disconnect, the node unregisters the proxy.

Cross-task invocations use ModuleIpcHandle so callers do not lock the server accept loop.

Event Subscription Pattern

1. Module subscribes: Module sends SubscribeEvents request with event types
2. Node confirms: Node sends subscription confirmation
3. Node publishes Events: Node sends event messages as they occur
4. Module receives Events: Module processes events asynchronously

Connection Management

Handshake

On connection, the module sends a handshake as the first Request:

#![allow(unused)]
fn main() {
RequestPayload::Handshake {
 module_id,
 module_name,
 version,
}
}

The node replies with HandshakeAck (node version). Modules without a handshake receive a fallback connection id (legacy path).

Connection Lifecycle

1. Connect: Module connects to Unix domain socket
2. Handshake: Module sends handshake, node validates
3. Active: Connection active, ready for requests/events
4. Disconnect: Connection closed (graceful or error)

Security

Process Isolation

• Modules run in separate processes with isolated memory
• No shared memory between node and modules
• Module crashes don't affect the base node

Permission System

Modules request capabilities that are validated before API access:

• ReadBlockchain - Read-only blockchain access
• ReadUTXO - Query UTXO set (read-only)
• ReadChainState - Query chain state (height, tip)
• SubscribeEvents - Subscribe to node events
• SendTransactions - Submit transactions to mempool

Sandboxing

Modules run in sandboxed environments with:

• Resource limits (CPU, memory, file descriptors)
• Filesystem restrictions (module data dir)
• Network: modules do not open arbitrary sockets; P2P and mesh sends go through NodeAPI with the network_access capability
• Permission-based API access

Error Handling

Error Types

#![allow(unused)]
fn main() {
pub enum ModuleError {
 ConnectionError(String),
 ProtocolError(String),
 PermissionDenied(String),
 ResourceExhausted(String),
 Timeout(String),
}
}

Error Recovery

• Connection Errors: Automatic reconnection with exponential backoff
• Protocol Errors: Clear error messages, connection termination
• Permission Errors: Detailed error messages, request rejection
• Timeout Errors: Request timeout, connection remains active

Performance

Message Serialization

• Format: bincode (binary encoding)
• Size: Compact binary representation
• Speed: Fast serialization/deserialization

Connection Pooling

• Persistent Connections: Connections remain open for multiple requests
• Concurrent Requests: Multiple requests can be in-flight simultaneously
• Correlation IDs: Match responses to requests asynchronously

Implementation Details

IPC Server

The node-side IPC server:

• Listens on Unix domain sockets under [modules].socket_dir (default data/modules/sockets, relative to the process unless configured in blvm.toml)
• Accepts module connections (one socket per spawned module process)
• Routes requests to NodeAPI implementation
• Publishes events to subscribed modules

IPC Client

The module-side IPC client ( blvm-sdk runner):

• Connects to the socket path passed in ModuleContext.socket_path at spawn
• Sends requests and receives responses
• Subscribes to events
• Handles connection errors

Source

• mod.rs
• protocol.rs (ModuleMessage)
• protocol.rs
• protocol.rs, traits.rs
• server.rs
• server.rs, ipc_proxy.rs, runner.rs
• spawner.rs
• permissions.rs
• mod.rs, permissions.rs
• traits.rs
• client.rs

See Also

• Module System - Module system architecture
• Building modules - Building modules
• Module catalog - Available modules

Module Events

Delivery reliability, timing guarantees, and integration patterns for the module event system. For the full event type catalog and subscription API, see Module system. For maintenance event payloads, see Janitorial events.

Event timing

Event types follow fixed timing so modules subscribe before receiving ModuleLoaded.

ModuleLoaded

ModuleLoaded events are only published after a module has subscribed (startup complete).

Flow:

1. Module process is spawned
2. Module connects via IPC and sends Handshake
3. Module sends SubscribeEvents
4. At subscription time:

• Module receives ModuleLoaded for all already-loaded modules
• ModuleLoaded is published for the newly subscribing module (if loaded)

5. Module is operational

Why: subscription completes before ModuleLoaded, so hotloaded modules receive existing modules and ordering is always subscription → ModuleLoaded.

Startup (Module A first): spawn → connect → subscribe → ModuleLoaded for A.

Hotload (Module B later): B subscribes → receives ModuleLoaded for A → ModuleLoaded published for B.

DataMaintenance

Single event for flush/cleanup (replaces StorageFlush and DataCleanup).

Payload: operation (flush, cleanup, both), urgency (low, medium, high), reason, optional target_age_days, optional timeout_seconds.

#![allow(unused)]
fn main() {
// Shutdown flush
DataMaintenance { operation: "flush", urgency: "high", reason: "shutdown", timeout_seconds: Some(5) }

// Periodic cleanup
DataMaintenance { operation: "cleanup", urgency: "low", reason: "periodic", target_age_days: Some(30) }
}

Migration from old events:

#![allow(unused)]
fn main() {
// Old: separate StorageFlush / DataCleanup handlers
// New: one DataMaintenance handler keyed on operation + urgency
match event_type {
 EventType::DataMaintenance => {
 if let EventPayload::DataMaintenance { operation, .. } = payload {
 if operation == "flush" || operation == "both" { flush_data().await?; }
 if operation == "cleanup" || operation == "both" { cleanup_data().await?; }
 }
 }
 _ => {}
}
}

Delivery and backpressure

Reliability model

• At-most-once per subscriber; full channel drops the event (no retry)
• Best-effort: slow or dead modules may miss events; statistics track success/failure
• Per-module ordering on a single channel; no cross-module ordering guarantee

Channel behavior

• Buffer: 100 events per module (hardcoded today)
• Non-blocking publish: try_send; publisher never blocks
• Channel full: event dropped with warning; subscription kept (module is slow, not dead)
• Channel closed: subscription removed (module dead)

#![allow(unused)]
fn main() {
let stats = event_manager.get_delivery_stats("module_id").await;
// Option<(successful_deliveries, failed_deliveries, channel_full_count)>
}

Hotload and missed events

Newly subscribing modules receive ModuleLoaded for all already-loaded modules so late starters get a consistent view without replaying the full event log.

Event categories (summary)

Full enum lists and subscription examples: Module system → Event System.

Monitoring

#![allow(unused)]
fn main() {
let stats = event_manager.get_delivery_stats("module_id").await;
let all_stats = event_manager.get_all_delivery_stats().await;
let subscribers = event_manager.get_subscribers(EventType::NewBlock).await;
event_manager.reset_delivery_stats("module_id").await; // testing
}

Module developer checklist

1. Subscribe immediately after handshake
2. Handle ModuleLoaded to discover peer modules
3. Keep handlers non-blocking
4. Handle NodeShutdown and high-urgency DataMaintenance
5. Monitor delivery statistics if events seem missing

Node developer checklist

1. Publish through EventPublisher at stable code points
2. Log delivery warnings
3. Watch per-module channel-full counts for slow consumers
4. Cover startup, hotload, and slow-module paths in integration tests

Extending events

1. Add variants to EventType and EventPayload
2. Add publisher helpers on EventPublisher
3. Follow existing patterns (e.g. DataMaintenance for maintenance)

See Also

• Module system (design): IPC, lifecycle, event catalog
• Janitorial events: maintenance event payloads
• Module IPC Protocol: wire protocol

Janitorial and Maintenance Events

Overview

Janitorial and maintenance events let modules participate in node lifecycle, resource management, and data maintenance in sync with the node.

Event Categories

1. Node Lifecycle Events

NodeShutdown

When: Node is shutting down (before components stop) Purpose: Allow modules to clean up gracefully Payload:

• reason: String - Shutdown reason ("graceful", "signal", "rpc", "error")
• timeout_seconds: u64 - Graceful shutdown timeout

Module Action:

• Save state
• Close connections
• Flush data
• Clean up resources

NodeShutdownCompleted

When: Node shutdown is complete Purpose: Notify modules that shutdown finished Payload:

• duration_ms: u64 - Shutdown duration

NodeStartupCompleted

When: Node startup is complete (all components initialized) Purpose: Notify modules that node is fully operational Payload:

• duration_ms: u64 - Startup duration
• components: Vec<String> - Components that were initialized

Module Action:

• Initialize connections
• Load state
• Start processing

2. Storage Events

DataMaintenance (Unified)

When: Data maintenance is requested (shutdown, periodic, low disk, manual) Purpose: Allow modules to flush data and/or clean up old data Payload:

• operation: String - "flush", "cleanup", or "both"
• urgency: String - "low", "medium", or "high"
• reason: String - "periodic", "shutdown", "low_disk", "manual"
• target_age_days: Option<u64> - Target age for cleanup (if operation includes cleanup)
• timeout_seconds: Option<u64> - Timeout for high urgency operations

Module Action:

• Flush: Write pending data to disk
• Cleanup: Delete old data based on target_age_days
• Both: Flush and cleanup

Urgency Levels:

• Low: Periodic maintenance, can be done asynchronously
• Medium: Scheduled maintenance, should complete soon
• High: Urgent (shutdown, low disk), must complete quickly

3. Maintenance Events

MaintenanceStarted

When: Maintenance operation started Purpose: Allow modules to prepare for maintenance Payload:

• maintenance_type: String - "backup", "cleanup", "prune"
• estimated_duration_seconds: Option<u64> - Estimated duration

Module Action:

• Pause non-critical operations
• Prepare for maintenance

MaintenanceCompleted

When: Maintenance operation completed Purpose: Notify modules that maintenance finished Payload:

• maintenance_type: String - Maintenance type
• success: bool - Success status
• duration_ms: u64 - Duration in milliseconds
• results: Option<String> - Results/statistics (optional JSON)

Module Action:

• Resume normal operations
• Process results if needed

HealthCheck

When: Health check performed Purpose: Allow modules to report their health status Payload:

• check_type: String - "periodic", "manual", "startup"
• node_healthy: bool - Node health status
• health_report: Option<String> - Health report (optional JSON)

Module Action:

• Report module health status
• Perform internal health checks

4. Resource Management Events

DiskSpaceLow

When: Disk space is low Purpose: Allow modules to clean up data to free space Payload:

• available_bytes: u64 - Available space in bytes
• total_bytes: u64 - Total space in bytes
• percent_free: f64 - Percentage free
• disk_path: String - Disk path

Module Action:

• Clean up old data
• Reduce data retention
• Flush and compress data

ResourceLimitWarning

When: Resource limit approaching Purpose: Allow modules to reduce resource usage Payload:

• resource_type: String - "memory", "cpu", "disk", "network"
• usage_percent: f64 - Current usage percentage
• current_usage: u64 - Current usage value
• limit: u64 - Limit value
• threshold_percent: f64 - Warning threshold percentage

Module Action:

• Reduce resource usage
• Clean up resources
• Optimize operations

Usage Examples

Handling Shutdown

#![allow(unused)]
fn main() {
match event_type {
    EventType::NodeShutdown => {
        if let EventPayload::NodeShutdown { reason, timeout_seconds } = payload {
            info!("Node shutting down: {}, timeout: {}s", reason, timeout_seconds);
            
            // Save state
            save_state().await?;
            
            // Close connections
            close_connections().await?;
            
            // Flush data
            flush_data().await?;
        }
    }
    _ => {}
}
}

Handling Data Maintenance

#![allow(unused)]
fn main() {
match event_type {
    EventType::DataMaintenance => {
        if let EventPayload::DataMaintenance { operation, urgency, reason, target_age_days, timeout_seconds } = payload {
            match operation.as_str() {
                "flush" => {
                    flush_pending_data().await?;
                }
                "cleanup" => {
                    let age_days = target_age_days.unwrap_or(30);
                    cleanup_old_data(age_days).await?;
                }
                "both" => {
                    flush_pending_data().await?;
                    let age_days = target_age_days.unwrap_or(30);
                    cleanup_old_data(age_days).await?;
                }
                _ => {}
            }
            
            if urgency == "high" {
                // High urgency - must complete quickly
                if let Some(timeout) = timeout_seconds {
                    tokio::time::timeout(
                        Duration::from_secs(timeout),
                        maintenance_operation()
                    ).await?;
                }
            }
        }
    }
    _ => {}
}
}

Handling Disk Space Low

#![allow(unused)]
fn main() {
match event_type {
    EventType::DiskSpaceLow => {
        if let EventPayload::DiskSpaceLow { available_bytes, percent_free, .. } = payload {
            warn!("Disk space low: {} bytes available, {:.2}% free", available_bytes, percent_free);
            
            // Clean up old data
            cleanup_old_data(7).await?; // Keep only last 7 days
            
            // Compress data
            compress_data().await?;
        }
    }
    _ => {}
}
}

Best Practices

1. Always Handle Shutdown: Modules must handle NodeShutdown and DataMaintenance (urgency: "high")
2. Non-Blocking Operations: Keep maintenance operations fast and non-blocking
3. Respect Timeouts: For high urgency operations, respect timeout_seconds
4. Clean Up Resources: Always clean up resources on shutdown
5. Monitor Health: Report health status during HealthCheck events

Integration Timing

Startup Sequence

1. Node starts
2. Modules load
3. Modules subscribe to events
4. NodeStartupCompleted published
5. Modules can start processing

Shutdown Sequence

1. NodeShutdown published (with timeout)
2. Modules clean up (within timeout)
3. DataMaintenance published (urgency: "high", operation: "flush")
4. Modules flush data
5. Node components stop
6. NodeShutdownCompleted published

Periodic Maintenance

1. DataMaintenance published (urgency: "low", operation: "cleanup", reason: "periodic")
2. Modules clean up old data
3. MaintenanceCompleted published

See Also

• Module System - Module system architecture
• Module events - Delivery, timing, and integration patterns
• Module IPC Protocol - IPC communication details

Consensus Layer Overview

blvm-consensus answers one question: given a transaction, block, UTXO set, and activation flags, does Bitcoin consensus accept it? It does not open sockets, read blvm.toml, or choose mainnet vs regtest. That belongs to blvm-protocol and blvm-node.

What this layer is for

Consensus code is the trust anchor of the stack. Wallets, pools, and modules depend on the node reporting chain state that matches what every other Bitcoin mainnet participant would accept. If validation is wrong here, every higher layer is wrong.

The layer implements rules from the Orange Paper as deterministic Rust: script execution, block connection, subsidy and difficulty math, mempool acceptance rules used by the node, and soft-fork behavior at documented activation heights. Block and script logic live in block/ and script/ submodules; canonical types, serialization, and crypto come from blvm-primitives (re-exported by blvm-consensus for API stability).

Relationship to the Orange Paper

The Orange Paper is the specification (implementation-agnostic IR). blvm-consensus is the implementation, validated against that spec, not generated from it. Optimization passes speed the code without changing specified meaning; see Optimization passes.

Chain of trust: Orange Paper → blvm-consensus → tests + spec-lock → node deployment

Verification methodology, coverage, and CI: Formal Verification. Policy: verification policy, proof limitations.

What lives here vs elsewhere

Architecture position

Stack layer 2: between the Orange Paper (layer 1) and protocol abstraction (layer 3). Full stack: Stack overview.

Design principles

1. Pure functions: Deterministic validation; explicit inputs instead of hidden globals
2. No rule interpretation in apps: Node calls into consensus; modules never patch rules
3. Controlled dependencies: Cargo.toml pins and ranges are the source of truth for crypto and BLVM crates
4. Testing in depth: Testing, property-based tests, differential testing via blvm-bench
5. Formal verification: Spec-lock proofs complement tests; see Formal Verification
6. No consensus rule interpretation: Only mathematical implementation of the Orange Paper
7. Optimization passes: Runtime optimizations speed the code without changing specified meaning; see Optimization passes

Core functions

Transaction validation

• Transaction structure and limit validation
• Input validation against UTXO set
• Script execution and verification

Block validation

• Block connection and validation
• Transaction application to UTXO set
• Proof of work verification

Economic model

• Block reward calculation
• Total supply computation
• Difficulty adjustment

Mempool protocol

• Transaction mempool validation
• Standard transaction checks
• Transaction replacement (RBF) logic

Mining protocol

• Block creation from mempool
• Block mining and nonce finding
• Block template generation

Chain management

• Reorganization primitives in blvm-consensus (src/reorganization.rs); blvm-node wires them for the live process_block path (block index, chainwork tip selection, undo persistence, events: see blvm-node fork choice and reorg)
• P2P network message processing

Advanced features

• SegWit: Witness data validation and weight calculation (see BIP141)
• Taproot: P2TR output validation and key aggregation (see BIP341)

Optimization passes

The implementation is validated against the Orange Paper; optimization passes optimize the implementation code (not the spec). Meaning is defined by the Orange Paper; see compiler-like architecture. Production and Rayon feature flags: consensus features.

• Constant folding: Pre-computed constants and constant propagation
• Memory layout optimization: Cache-aligned structures and compact stack frames
• SIMD vectorization: Batch hash operations with parallel processing
• Bounds check optimization: Removes redundant runtime bounds checks using BLVM Specification Lock-proven bounds
• Dead code elimination: Removes unused code paths
• Inlining hints: Aggressive inlining of hot functions

Spec maintenance workflow

Figure: Specification maintenance workflow showing how changes are detected, verified, and integrated.

BIP implementation

Consensus integrates consensus-critical BIPs in validation paths, for example BIP30/34/66/90/147 in block connection and script verification. Activation heights and network variants are coordinated with blvm-protocol network parameters.

Performance

Consensus hot paths support PGO builds (./scripts/pgo-build.sh in blvm-consensus), batch script verification, and optimization passes. Optimize after correctness gates; measure on your workload.

Mathematical protection mechanisms and formal properties are documented in Mathematical Specifications.

Dependencies

Declare versions from blvm-consensus Cargo.toml. blvm-primitives supplies shared types; consensus re-exports many for API stability.

Source code

See Also

• API Index: Consensus functions
• Formal Verification: Methodology
• Mathematical Specifications: Formal properties
• Orange Paper: Normative spec

Mathematical Specifications

Canonical spec: The Orange Paper on thebitcoincommons.org (Consensus Spec). This page is an in-book digest of formal properties and notation used when reasoning about blvm-consensus, checked by tests and BLVM Specification Lock, not a substitute for the full commons spec.

Overview

Bitcoin Commons documents Orange Paper-aligned mathematical specifications for consensus behavior. The Rust code implements this spec, checked by tests and BLVM Specification Lock on spec-locked functions. Proof scope: proof limitations.

Specification Format

Mathematical specifications use formal notation to define consensus rules:

• Quantifiers: Universal (∀) and existential (∃) quantifiers
• Functions: Mathematical function definitions
• Invariants: Properties that must always hold
• Constraints: Bounds and limits

Core Specifications

Chain Selection

Mathematical Specification:

∀ chains C₁, C₂: work(C₁) > work(C₂) ⇒ select(C₁)

Invariants:

• Selected chain has maximum cumulative work
• Work calculation is deterministic
• Empty chains are rejected
• Chain work is always non-negative

Key functions:

• should_reorganize: Longest-work selection
• calculate_chain_work: Cumulative work calculation
• expand_target: Difficulty target edge cases (see also PoW specs)

Block Subsidy

Mathematical Specification:

∀ h ∈ ℕ: subsidy(h) = 50 * 10^8 * 2^(-⌊h/210000⌋) if ⌊h/210000⌋ < 64 else 0

Invariants:

• Subsidy halves every 210,000 blocks
• Subsidy is non-negative
• Subsidy decreases monotonically
• Total supply converges to 21 million BTC

Total Supply

Mathematical Specification:

∀ h ∈ ℕ: total_supply(h) = Σ(i=0 to h) subsidy(i)

Invariants:

• Total supply is monotonic (never decreases)
• Total supply is bounded (≤ 21 * 10^6 * 10^8 satoshis)
• Total supply converges to 21 million BTC

Difficulty Adjustment

Mathematical Specification:

target_new = target_old * (timespan / expected_timespan)
timespan_clamped = clamp(timespan, expected/4, expected*4)

Invariants:

• Target is always positive
• Timespan is clamped to [expected/4, expected*4]
• Difficulty adjustment is deterministic

Consensus Threshold

Mathematical Specification:

required_agreement_count = ceil(total_peers * threshold)
consensus_met ⟺ agreement_count >= required_agreement_count

Invariants:

• 1 <= required_agreement_count <= total_peers
• agreement_count >= required ⟺ ratio >= threshold
• Integer comparison is deterministic

Median Calculation

Mathematical Specification:

median(tips) = {
 tips[n/2] if n is odd,
 (tips[n/2-1] + tips[n/2]) / 2 if n is even
}

Invariants:

• min(tips) <= median <= max(tips)
• Median is deterministic
• Checkpoint = max(0, median - safety_margin)

Proof of Work

Mathematical Specification:

∀ header H: CheckProofOfWork(H) = SHA256(SHA256(H)) < ExpandTarget(H.bits)

Target compression/expansion:

∀ bits ∈ [0x03000000, 0x1d00ffff]:
 Let expanded = expand_target(bits)
 Let compressed = compress_target(expanded)
 Let re_expanded = expand_target(compressed)

 Then:
 - re_expanded ≤ expanded (compression truncates, never increases)
 - re_expanded.0[2] = expanded.0[2] ∧ re_expanded.0[3] = expanded.0[3]
 - Precision loss in words 0, 1 is acceptable (compact format limitation)

Invariants:

• Hash must be less than target for valid proof of work
• Target expansion handles edge cases correctly
• Target compression preserves significant bits (words 2, 3) exactly
• Difficulty adjustment respects bounds [0.25, 4.0]
• Work calculation is deterministic

Key functions:

• check_proof_of_work: hash vs target
• expand_target / compress_target: compact difficulty encoding
• get_next_work_required: difficulty adjustment bounds

Transaction Validation

Mathematical Specification:

∀ tx ∈ 𝒯𝒳: CheckTransaction(tx) = valid ⟺
 (|tx.inputs| > 0 ∧ |tx.outputs| > 0 ∧
 ∀o ∈ tx.outputs: 0 ≤ o.value ≤ M_max ∧
 |tx.inputs| ≤ M_max_inputs ∧ |tx.outputs| ≤ M_max_outputs ∧
 |tx| ≤ M_max_tx_size)

Invariants:

• Valid transactions have non-empty inputs and outputs
• Output values are bounded [0, MAX_MONEY]
• Input/output counts and transaction size respect limits
• Coinbase transactions have special validation rules

Key functions:

• check_transaction: structural validity
• check_tx_inputs: input checks including coinbase
• is_coinbase: coinbase detection

Block Connection

Mathematical Specification:

∀ block B, UTXO set US, height h: ConnectBlock(B, US, h) = (valid, US') ⟺
 (ValidateHeader(B.header) ∧
 ∀ tx ∈ B.transactions: CheckTransaction(tx) ∧ CheckTxInputs(tx, US, h) ∧
 VerifyScripts(tx, US) ∧
 CoinbaseOutput ≤ TotalFees + GetBlockSubsidy(h) ∧
 US' = ApplyTransactions(B.transactions, US))

Invariants:

• Valid blocks have valid headers and transactions
• UTXO set consistency is preserved
• Coinbase output respects economic rules
• Transaction application is atomic

Key functions:

• connect_block: full block validation
• apply_transaction: UTXO updates
• calculate_tx_id: transaction id

Specification Coverage

Functions with Specifications

Multiple functions have formal mathematical specifications:

• Chain selection (should_reorganize, calculate_chain_work)
• Block subsidy (get_block_subsidy)
• Total supply (total_supply)
• Difficulty adjustment (get_next_work_required, expand_target)
• Transaction validation (check_transaction, check_tx_inputs)
• Block validation (connect_block, apply_transaction)
• Script execution (eval_script, verify_script)
• Consensus threshold (find_consensus)
• Median calculation (determine_checkpoint_height)

Mathematical Protections

Integer-Based Arithmetic

Floating-point arithmetic replaced with integer-based calculations:

#![allow(unused)]
fn main() {
// Integer-based threshold calculation
let required_agreement_count = ((total_peers as f64) * threshold).ceil() as usize;
if agreement_count >= required_agreement_count {
 // Consensus met
}
}

Runtime Assertions

Runtime assertions verify mathematical invariants:

• Threshold calculation bounds
• Consensus result invariants
• Median calculation bounds
• Checkpoint bounds

Checked Arithmetic

Checked arithmetic prevents overflow/underflow:

#![allow(unused)]
fn main() {
// Median calculation with overflow protection
let median_tip = if sorted_tips.len() % 2 == 0 {
 let mid = sorted_tips.len() / 2;
 let lower = sorted_tips[mid - 1];
 let upper = sorted_tips[mid];
 (lower + upper) / 2 // Safe: Natural type prevents overflow
} else {
 sorted_tips[sorted_tips.len() / 2]
};
}

How verification applies

BLVM Specification Lock uses Z3 to prove spec-locked functions against Orange Paper contracts. The symbolic specs on this page are not each a separate Z3 theorem; methodology, CI, and tooling live on Formal Verification. Proof bounds: proof limitations.

Property-based tests and runtime assertions (below) complement spec-lock on the same invariants.

Documentation

Consensus repository references (see consensus docs index):

• verification policy: how to run verification and what is in scope
• proof limitations: proof bounds, coverage, and protections beyond formal verification

Components

The mathematical specifications system includes formal notation, invariants, integer-based arithmetic, runtime assertions, and checked arithmetic on consensus paths. Verification tooling and CI: Formal Verification and Testing Infrastructure.

Source

• verification policy
• proof limitations
• repository docs

See Also

• Consensus Overview: Consensus layer introduction
• Formal Verification: BLVM Specification Lock methodology
• Orange Paper: Normative specification on Bitcoin Commons
• Property-Based Testing: Property-based testing

Formal Verification

How BLVM checks consensus against the Orange Paper: spec-lock methodology, coverage, CI gates, and tooling. For what blvm-consensus implements and how it relates to the spec, see Consensus Overview.

BLVM Specification Lock binds #[spec_locked] Rust functions to Orange Paper contracts and discharges obligations with Z3. Empirical layers (testing, differential testing, fuzz, MIRI) stress the same surface from complementary angles. Together: Rust + Tests + Math Specs = Source of Truth.

Inventory and verification policy: consensus verification guide, spec-lock coverage inventory, and proof limitations.

What formal verification delivers

A human-auditable source of meaning. Consensus rules live in the Orange Paper first. Reviewers, including mathematicians who never read the node, can argue about subsidy, PoW, and script semantics in the same language the proofs use.

Proofs locked to the functions they protect. Annotation with #[spec_locked] attaches Orange Paper contracts to concrete Rust. Change the code, and the obligations travel with it: proofs are not a detached appendix that drifts from the implementation.

Machine-checked alignment on merge. Z3 verifies those contracts on every change. CI runs check-drift then verify on self-hosted runners, so a PR that softens a rule or breaks a proven invariant fails the gate instead of shipping as “still green on unit tests.”

Growing, measurable coverage. Spec-lock covers 251 #[spec_locked] functions across the stack (240 in blvm-consensus, 5 in blvm-node, 6 in blvm-protocol) and ~433 parseable obligations (reconfirm with cargo spec-lock coverage).

Confidence to evolve. Proven bounds feed optimization passes. Refactors and performance work land against the same contracts. Future implementations can share the Orange Paper as common IR; each codebase earns trust by locking to that IR, not by copying another node’s source.

A full assurance stack. Specification Lock answers: does this function still mean what the Orange Paper says? Property tests, fuzzing, MIRI, and differential testing against Bitcoin Core answer complementary questions about edge cases, undefined behavior, and historical mainnet agreement. Each layer strengthens the others; none is ornamental.

Consensus verification operates on public block data. Secret-path constant-time cryptography (signing, ECDH, MuSig secrets) lives in blvm-secp256k1, a deliberate split so conformance proofs and timing discipline each have the right home.

Verification Stack

Layer 1: Empirical Testing

• Unit tests: Broad coverage across consensus modules and public APIs
• Property-based tests: Randomized testing with proptest to discover edge cases
• Integration tests: Cross-system validation between consensus components

Layer 2: Symbolic Verification

• BLVM Specification Lock: Z3-backed proofs on spec-locked functions
• Mathematical specifications: in-book digest and Orange Paper contracts
• State space exploration: Paths relevant to spec-lock contracts

Layer 3: CI Enforcement

• Automated testing: Required for merge
• BLVM Specification Lock: Required on merge; see verification policy
• OpenTimestamps audit logging: Optional timestamps of verification artifacts

Verify JSON semantics (blvm-spec-lock)

cargo spec-lock verify emits structured status per function. Failed means the proof obligation did not pass: CI gates on these when strict mode is enabled. Partial marks obligations demoted or skipped (timeout, translation gap, advisory tier): read the log and verify JSON format for jq filters; treat Passed under explicit policy as the release signal.

Verification Statistics

Formal Proofs

BLVM Specification Lock runs a single verify pass over all spec-locked functions and merged F_* formula registry rows.

Coverage snapshot (count #[spec_locked] in source; re-run cargo spec-lock coverage for contract totals):

Parseable obligations: ~433 (reconfirm with cargo spec-lock coverage --spec-path …).

Verification Command (clone blvm-spec next to the crate so ../blvm-spec exists, or set SPEC_LOCK_SPEC_PATH):

# Install CLI (matches library floor; picks latest published 0.1.x)
cargo install blvm-spec-lock --version '>=0.1, <1' --locked --features z3

export SPEC_LOCK_STRICT=1
export SPEC_LOCK_Z3_TIMEOUT_SECS=120   # overrides --timeout when set

cargo spec-lock check-drift \
  --crate-path . \
  --spec-path ../blvm-spec/PROTOCOL.md ../blvm-spec/ARCHITECTURE.md \
  --scoped-unparseables

cargo spec-lock verify \
  --crate-path . \
  --spec-path ../blvm-spec/PROTOCOL.md ../blvm-spec/ARCHITECTURE.md \
  --timeout 120 \
  --format human \
  --json-out spec_lock_verify.json

Common filters (same verify subcommand):

cargo spec-lock verify --name get_block_subsidy --crate-path . --spec-path ../blvm-spec/PROTOCOL.md
cargo spec-lock verify --section 6.1 --crate-path . --spec-path ../blvm-spec/PROTOCOL.md
cargo spec-lock verify --subsystem economic --crate-path . --spec-path ../blvm-spec/PROTOCOL.md

There is no --tier flag. CI runs one full verify pass on self-hosted runners ([self-hosted, Linux, X64, builds]): check-drift (with --scoped-unparseables, and --scoped-formulas when the installed CLI supports it), then verify with --json-out. See the consensus CI workflow and spec-lock dependency guide.

Proof rigor (policy classification, not separate runner pools): verification-tiers.toml groups functions by expected proof depth:

• Tier 1: Full Z3 body proof required (subsidy, PoW, reorg primitives)
• Tier 2: Invariant + proptest coverage for complex bodies
• Tier 3: Differential equivalence harnesses (crypto backends, FFI boundaries)

Local development uses the same verify command as CI. For property tests, fuzz, MIRI, and the full test matrix, see Testing Infrastructure.

CI Integration

The Verify / verify jobs in blvm-consensus, blvm-node, and blvm-protocol CI are the authoritative cargo-spec-lock gates. Optional umbrella workflow_dispatch mirrors exist for multi-repo workspace checkouts.

1. Unit & Property Tests (required in each crate CI): cargo test --all-features
2. BLVM Specification Lock (required where #[spec_locked] is enabled): check-drift then verify per the spec-lock dependency guide
3. OpenTimestamps Audit (non-blocking: consensus umbrella CI parity / monorepo only where enabled)

Run commands locally: Testing Infrastructure. Other subcommands: coverage, summary, list, check-formulas, verify-formulas. Full CLI reference: blvm-spec-lock.

Network Protocol Verification

blvm-protocol uses the same BLVM Specification Lock machinery for wire messages: headers, checksums, size limits, and round-trip properties for the message types in scope.

Proof targets: Header layout (magic, command, length, checksum), checksum validation, size limits, parse(serialize(msg)) == msg for covered messages.

Wire message groups (verification scope): Group A: Version, VerAck, Ping, Pong. Group B: Transaction, Block, Headers, Inv, GetData, GetHeaders. (This grouping is for protocol verification only, not governance tiers.)

Use the verify feature for full protocol verification builds; see protocol overview.

Consensus Coverage Comparison

Figure: Baseline: broad tests and review. Bitcoin Commons adds BLVM Specification Lock and Orange Paper-driven methodology on top.

Proof Maintenance Cost

Figure: Proof maintenance cost: proofs changed per change by area; highlights refactor hotspots.

Spec Drift vs Test Coverage

Figure: Spec drift decreases as test coverage increases. Higher test coverage reduces the likelihood of specification drift over time.

See also Network Protocol for transport and wire-format documentation.

Policy and inventory: verification policy and proof limitations. Formal properties per rule: Mathematical Specifications.

Source

• Consensus CI workflow (Verify job; MIRI when nightly is available)

See Also

• Consensus Overview: What the consensus layer implements
• Mathematical Specifications: Mathematical spec details
• Property-Based Testing: Property-based testing
• Differential Testing: BLVM vs Bitcoin Core
• Fuzzing: Fuzzing infrastructure
• Testing Infrastructure: Complete testing overview

Protocol Layer Overview

The protocol layer (blvm-protocol) abstracts Bitcoin protocol for multiple variants and protocol evolution. It sits between the pure mathematical consensus rules (blvm-consensus) and the Bitcoin node implementation (blvm-node), supporting mainnet, testnet, regtest, and future protocol variants.

Architecture Position

Stack layer 3: protocol abstraction between blvm-consensus and blvm-node.

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

Full stack: Stack overview.

Protocol Variants

The protocol layer supports multiple Bitcoin network variants:

Network Parameters

Each variant also defines genesis block hash, difficulty targets, halving interval (210,000 blocks), and feature activation heights (SegWit, Taproot).

Core Components

Protocol Engine

The BitcoinProtocolEngine is the main interface:

#![allow(unused)]
fn main() {
pub struct BitcoinProtocolEngine {
 version: ProtocolVersion,
 network_params: NetworkParams,
 config: ProtocolConfig,
}
}

Features:

• Protocol variant selection
• Network parameter access
• Feature flag management
• Validation rule enforcement

Network Messages

Supports Bitcoin P2P protocol messages:

Core Messages:

• Version, VerAck - Connection handshake
• Addr, GetAddr - Peer address management
• Inv, GetData, NotFound - Inventory management
• Block, Tx - Block and transaction relay
• GetHeaders, Headers, GetBlocks - Header synchronization
• Ping, Pong - Connection keepalive
• MemPool, FeeFilter - Mempool synchronization

BIP152 (Compact Block Relay):

• SendCmpct - Compact block negotiation
• CmpctBlock - Compact block transmission
• GetBlockTxn, BlockTxn - Transaction reconstruction

FIBRE Protocol:

• FIBREPacket - High-performance relay protocol
• Packet format and serialization
• Performance optimizations

Governance Messages:

• Governance messages via P2P protocol
• Message format and routing
• Integration with governance system

Commons Extensions:

• GetUTXOSet, UTXOSet - UTXO commitment protocol
• GetFilteredBlock, FilteredBlock - Spam-filtered blocks
• GetBanList, BanList - Distributed ban list sharing

Service Flags

Service flags indicate node capabilities:

Standard Flags:

• NODE_NETWORK - Full node with all blocks
• NODE_WITNESS - SegWit support
• NODE_COMPACT_FILTERS - BIP157/158 support
• NODE_NETWORK_LIMITED - Pruned node

Commons Flags:

• NODE_UTXO_COMMITMENTS - UTXO commitment support
• NODE_BAN_LIST_SHARING - Ban list sharing
• NODE_FIBRE - FIBRE protocol support
• NODE_DANDELION - Dandelion++ privacy relay
• NODE_PACKAGE_RELAY - BIP331 package relay

Validation Rules

Protocol-specific validation rules:

• Size Limits: Block (4MB), transaction (1MB), script (10KB)
• Feature Flags: SegWit, Taproot, RBF support
• Fee Rules: Minimum and maximum fee rates
• DoS Protection: Message size limits, address count limits

Commons-Specific Extensions

UTXO Commitments

Protocol messages for UTXO set synchronization:

• GetUTXOSet - Request UTXO set at specific height
• UTXOSet - UTXO set response with merkle proof

Filtered Blocks

Spam-filtered block relay for efficient syncing:

• GetFilteredBlock - Request filtered block
• FilteredBlock - Filtered block with spam transactions removed

Ban List Sharing

Distributed ban list management:

• GetBanList - Request ban list
• BanList - Ban list response with signatures

BIP Support

Compact block relay (BIP152)

Short transaction IDs and block reconstruction (SendCmpct, CmpctBlock). See Network messages above.

Client-side block filtering (BIP157/158)

GCS compact block filters and filter header chain. Node handlers and UTXO-commitment integration: BIP158 in UTXO Commitments.

Implemented Bitcoin Improvement Proposals:

• BIP152: Compact Block Relay: above
• BIP157: Client-side Block Filtering: above
• BIP158: Compact Block Filters: above
• BIP173/350/351: Bech32/Bech32m Address Encoding
• BIP70: Payment Protocol

Protocol Evolution

The protocol layer supports protocol evolution:

• Version Support: Multiple protocol versions
• Feature Management: Enable/disable features based on version
• Breaking Changes: Track and manage protocol evolution
• Backward Compatibility: Maintain compatibility with existing nodes
• Wire and transport: P2P message formats and Bitcoin-compatible peer behavior live in blvm-protocol; the reference node delivers them over transports (TCP by default; optional QUIC-based paths where features enable them). Treat encrypted Bitcoin P2P (BIP324) and other transport experiments as build- and release-specific, see blvm-protocol and blvm-node features and release notes rather than assuming one global default.

Usage Example

#![allow(unused)]
fn main() {
use blvm_protocol::{BitcoinProtocolEngine, ProtocolVersion};

// Create a mainnet protocol engine
let engine = BitcoinProtocolEngine::new(ProtocolVersion::BitcoinV1)?;

// Get network parameters
let params = engine.get_network_params();
println!("Network: {}", params.network_name);
println!("Port: {}", params.default_port);

// Check feature support
if engine.supports_feature("segwit") {
 println!("SegWit is supported");
}
}

Source

• network_params.rs
• lib.rs
• network.rs (NetworkMessage), wire/mod.rs (command names and serialization)
• service_flags.rs
• validation.rs
• commons.rs (message structs); utxo_commitments/mod.rs (UTXO commitment protocol)
• commons.rs (GetFilteredBlockMessage, FilteredBlockMessage)
• commons.rs (GetBanListMessage, BanListMessage)
• bip157.rs

See Also

• Network Protocol - Transport abstraction, wire framing, and message types
• Protocol Specifications - BIP implementations
• Node Configuration - Configuring protocol variants

Network Protocol

Bitcoin P2P wire format and framing in blvm-protocol. For the protocol engine, variants, message catalog, service flags, and BIPs: Protocol Overview. For transports (TCP, Quinn, Iroh), transport_preference, and the NetworkManager: Transport Abstraction. For operator bind addresses and CLI defaults: Node Configuration.

Bitcoin wire and framing (blvm-protocol)

blvm-protocol owns Bitcoin P2P message framing (message type, length, payload, checksum) and related helpers. For TCP, entry points such as node_tcp tie that logic to the node’s socket path. Treat blvm-protocol src/ as the source of truth rather than this summary.

Wire envelope

Implementation: blvm-protocol wire layer.

Network identifiers on the wire

Magic bytes and default P2P/RPC ports per variant: Protocol overview: Protocol variants.

Message taxonomy

Handshake, inventory, sync, relay, keepalive, and Commons extension commands: Protocol overview: Network messages.

See Also

• Protocol Overview - Protocol layer introduction
• Transport Abstraction - TCP, Quinn, and Iroh transports
• Node Configuration - Network and transport configuration
• Protocol Specifications - BIP implementations

Node Implementation Overview

The node implementation (blvm-node) is a minimal reference Bitcoin node: it adds only non-consensus infrastructure on top of the consensus and protocol layers. Treat mainnet and high-value deployments like any consensus-adjacent system, hardening, monitoring, and review are required. Consensus logic comes from blvm-consensus, and protocol abstraction from blvm-protocol.

Release mainnet IBD: First Node Setup: Mainnet IBD.

Architecture

The node follows a layered architecture:

Key Components

Network Manager

• P2P protocol implementation (Bitcoin wire protocol)
• Multi-transport support (TCP, Quinn QUIC, Iroh)
• Peer connection management
• Message routing and relay
• Privacy protocols (Dandelion++ when dandelion feature enabled; FIBRE via blvm-fibre module)
• Package relay (BIP331)

Storage Layer

• Database abstraction with multiple backends (see Storage Backends)
• Bitcoin Core drop-in: one-time import from a synced Core datadir into <datadir>/blvm/ when the rocksdb feature is enabled (see Operations: Starting from a Core datadir)
• Automatic backend fallback on failure
• Block storage and indexing
• UTXO set management
• Chain state tracking
• Transaction indexing
• Pruning support

RPC Server

• JSON-RPC 2.0 compliant API (see RPC API Reference)
• Bearer token RBAC (tokens, admin_tokens) and HTTP Basic (username, password) for ckpool / Core-style clients
• Optional REST /api/v1/* when built with rest-api and [rest_api].enabled (separate bind; off by default: see RPC API: REST)
• Optional JSON-RPC over QUIC / HTTP/3 (see RPC API: QUIC)
• Authentication and rate limiting
• Method coverage

Module System

• Process-isolated modules (see Module System Architecture)
• IPC communication (Unix domain sockets, see Module IPC Protocol)
• Security sandboxing
• Permission-based API access
• Hot reload support

Mempool Manager

• Transaction validation and storage
• Fee-based transaction selection
• RBF (Replace-By-Fee) support with 4 configurable modes (Disabled, Conservative, Standard, Aggressive)
• Mempool policies and limits
• Transaction expiry
• Advanced indexing (address and value range indexing)

Mining Coordinator

• Block template generation (RPC)
• Stratum V2 (optional blvm-stratum-v2 module)

Payment Processing

• CTV (CheckTemplateVerify) payment state machine when ctv compile-time feature is enabled
• BIP70 HTTP payment RPC when bip70-http is in the binary (blvm default features; omitted from portable release builds: see Installation)
• Lightning Network via optional blvm-lightning module (not core node RPC)
• Payment vaults / covenant tooling in blvm-node payment layer (CTV-gated at runtime)

Governance Integration

• Optional [governance] configuration (e.g. Commons URL, relay toggles) and NODE_GOVERNANCE P2P capability for extensions such as ban list sharing
• Module-visible governance events (proposal lifecycle, webhooks, fork detection) for optional out-of-process modules

Design Principles

1. Zero Consensus Re-implementation: All consensus logic delegated to blvm-consensus
2. Protocol Abstraction: Uses blvm-protocol for variant support (mainnet, testnet, regtest)
3. Pure Infrastructure: Adds storage, networking, RPC, orchestration only
4. Feature-complete infrastructure: Full node-style behavior (storage, P2P, RPC, modules) with performance optimizations; not a substitute for operational security review before production

Features

Network Features

• Multi-transport architecture (TCP, QUIC)
• Transaction relay (Dandelion++; FIBRE via blvm-fibre module)
• High-performance block relay (FIBRE module)
• Package relay (BIP331)
• UTXO commitments (compile-time feature in release binaries; enable at runtime when used)
• Peer consensus protocol, spam filtering (bandwidth optimization during sync)
• LAN peering system (automatic local network discovery for faster IBD when LAN peers exist)
• Parallel IBD with optional IBD UTXO engine (BLVM_IBD_ENGINE=1)

Storage Features

• Multiple database backends with abstraction layer (auto → heed3 (LMDB) in typical release builds; optional RocksDB, redb, sled, tidesdb)
• Common on-disk chain layouts via RocksDB backend
• Automatic backend fallback on failure
• Pruning support
• Advanced transaction indexing (address and value range indexes)
• UTXO set management

Security Features

• IBD bandwidth protection (per-peer/IP/subnet limits, reputation scoring)

Module Features

• Process isolation
• IPC communication
• Security sandboxing
• Hot reload
• Module registry

Mining Features

• Block template generation
• Stratum V2 protocol (optional blvm-stratum-v2 module)
• Merge mining (optional blvm-merge-mining plugin)
• Mining pool coordination

Payment Features

• Lightning Network via optional blvm-lightning module
• CTV payment vaults and covenant proofs (requires ctv feature at build time)
• BIP70 payment RPC (requires bip70-http in the binary)
• Payment state machines (BIP70 / on-chain verify paths)

Integration Features

• Governance webhook integration
• ZeroMQ notifications (optional blvm-zmq module: see ZMQ module)
• Optional REST /api/v1/* (same caveats as RPC Server)
• Module registry (P2P discovery)

Node Lifecycle

1. Initialization: Load configuration, initialize storage, create network manager
2. Startup: Connect to P2P network, discover peers, load modules
3. Sync: Download and validate blockchain history
4. Running: Validate blocks/transactions, relay messages, serve RPC requests
5. Shutdown: Graceful shutdown of all components

Metrics and Monitoring

The node includes metrics collection:

• Network Metrics: Peer count, bytes sent/received, connection statistics
• Storage Metrics: Block count, UTXO count, database size
• RPC Metrics: Request count, error rate, response times
• Performance Metrics: Block validation time, transaction processing time
• System Metrics: CPU usage, memory usage, disk I/O

Source

• network/mod.rs (module root), network_manager.rs (connection and message handling)
• mod.rs
• mod.rs
• manager.rs
• mempool.rs
• miner.rs
• mod.rs
• config/governance.rs, network/peer_manager.rs (governance feature), P2P governance extensions
• mod.rs
• metrics.rs

See Also

• Installation - Installing the node
• Quick Start - Running your first node
• Node Configuration - Configuration options
• Node Operations - Node management and operations
• RPC API Reference - JSON-RPC API documentation
• Mining Integration - Mining functionality
• Module System - Module system architecture
• Storage Backends - Storage backend details

Node Operations

Operational guide for running and maintaining a BLVM node.

Operations runbook

Starting the Node

Basic Startup

# Regtest mode (default, safe for development)
blvm

# Testnet mode
blvm --network testnet

# Mainnet: first sync: see First Node Setup (IBD example config), not bare mainnet
# blvm --network mainnet

With Configuration

blvm --config blvm.toml

Starting from a Bitcoin Core datadir

Use when Core is fully synced and you want the same tip without full IBD.

# Recommended: auto-migrate on start → ~/.bitcoin/blvm/
blvm start --network mainnet --data-dir ~/.bitcoin

On first start BLVM detects the Core layout, migrates once into <datadir>/blvm/, then opens the BLVM store. Block files are not copied by default: BLVM keeps reading bodies from Core blocks/ (~700 GB stays in one place). Only the UTXO set and indexes are converted into BLVM format (~15-30 GB under blvm/).

# Optional: explicit migrate with verify, then start the BLVM store
blvm migrate core --source ~/.bitcoin --destination ~/.bitcoin/blvm \
 --network mainnet --verify
blvm start --network mainnet --data-dir ~/.bitcoin/blvm

What gets migrated

After a successful migrate you may delete Core chainstate/ (~12 GB) if you will not run bitcoind on that datadir again.

Flags and settings

Requires the rocksdb Cargo feature (blvm default features; omitted from portable Windows/aarch64 release builds). Config and ENV details: Bitcoin Core drop-in, Storage Backends.

Verify: --verify on blvm migrate core; regtest test core_drop_in (fixture: blvm-node/scripts/gen-core-regtest-fixture.sh); mainnet smoke: blvm-node/scripts/core-drop-in-mainnet-smoke.sh.

Node Lifecycle

The node follows a lifecycle with multiple states and transitions.

Sync state machine

State descriptions:

State transitions are managed by the SyncStateMachine (Initial → Headers → Blocks → Synced). Progress weighting in UI/logs uses ~30% at headers complete and ~60% at blocks complete before full sync.

Initial sync checklist

When starting for the first time, the node will:

1. Initialize Components: Storage, network, RPC, modules
2. Connect to P2P Network: Discover peers via DNS seeds or persistent peers
3. Download Headers: Request and validate block headers
4. Download Blocks: Request and validate blocks
5. Build UTXO Set: Construct UTXO set from validated blocks
6. Sync to Current Height: Continue until caught up with network

Running State

Once synced, the node maintains:

• Peer Connections: Active P2P connections
• Block Validation: Validates and relays new blocks (via blvm-consensus)
• Transaction Processing: Validates and relays transactions
• Chain State Updates: Updates chain tip and height
• RPC Requests: Serves JSON-RPC API requests
• Health Monitoring: Periodic health checks

Health States

The node tracks health status for each component:

• Healthy: Component operating normally
• Degraded: Component functional but with issues
• Unhealthy: Component not functioning correctly
• Down: Component not responding

Error Recovery

The node implements graceful error recovery:

• Network Errors: Automatic reconnection with exponential backoff
• Storage Errors: Timeout protection, graceful degradation
• Validation Errors: Logged and reported, node continues operation
• Disk Space: Periodic checks with warnings

Monitoring

Health Checks

# CLI health check (uses JSON-RPC getblockchaininfo on the configured RPC address)
blvm health
# Mainnet node:
blvm --network mainnet --rpc-addr 127.0.0.1:8332 health

# HTTP health on the RPC port (GET: same port as JSON-RPC)
curl -s http://127.0.0.1:8332/health # mainnet: quick status
curl -s http://127.0.0.1:18332/health # testnet
curl -s http://127.0.0.1:18443/health # regtest
curl -s http://127.0.0.1:18443/health/live # liveness (same body as /health)
curl -s http://127.0.0.1:18443/health/ready # readiness (healthy only)
curl -s http://127.0.0.1:18443/health/detailed # full gethealth JSON

# Prometheus metrics (GET /metrics: requires auth when [rpc_auth] is enabled)
curl -s http://127.0.0.1:8332/metrics

# JSON-RPC node health extension (blvm-node; not Bitcoin Core): use your RPC port
curl -X POST http://127.0.0.1:18443 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "method": "gethealth", "params": [], "id": 1}'

# JSON-RPC metrics extension (blvm-node; not Bitcoin Core)
curl -X POST http://127.0.0.1:18443 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "method": "getmetrics", "params": [], "id": 1}'

# JSON-RPC blockchain info
curl -X POST http://127.0.0.1:8332 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "method": "getblockchaininfo", "params": [], "id": 1}'

Logging

The node uses structured logging. Set log level via environment variable:

# Set log level
RUST_LOG=info blvm

# Debug mode
RUST_LOG=debug blvm

# Trace all operations
RUST_LOG=trace blvm

Maintenance

Database Maintenance

The node automatically maintains block storage, UTXO set, chain indexes, and transaction indexes.

Backup

Regular backups recommended:

# Backup data directory
tar -czf blvm-backup-$(date +%Y%m%d).tar.gz /var/lib/blvm

Updates

When updating the node:

1. Stop the node gracefully
2. Backup data directory
3. Download new binary from GitHub Releases
4. Replace old binary with new one
5. Restart node

Troubleshooting

See Troubleshooting for detailed solutions to common issues.

Source

• sync.rs
• mod.rs
• health.rs

See Also

• Node Configuration - Configuration options
• Node Overview - Node architecture and features
• RPC API Reference - Complete RPC API documentation
• Troubleshooting - Common issues and solutions
• Performance Optimizations - Performance tuning

Node Configuration

BLVM node configuration supports different use cases.

Protocol Variants

The node supports multiple Bitcoin protocol variants: Regtest (default, regression testing network for development), Testnet3 (Bitcoin test network), and BitcoinV1 (production Bitcoin mainnet). See Protocol Variants for details.

Configuration Precedence

CLI > ENV > config file > defaults

Environment variables (e.g. BLVM_DATA_DIR, BLVM_IBD_EVICTION) override config file values. See Environment variables in the configuration reference for the full list. Some options (relay, fibre, dandelion) are config-file-only; use CLI flags like --enable-dandelion for common overrides.

Network defaults (blvm binary, no --rpc-addr override)

Separate data_dir per network. REST bind (when enabled) derives from RPC port: 8080 (mainnet), 18080 (testnet), 28443 (regtest).

Path Expansion

Config path fields (storage.data_dir, modules.modules_dir, ibd.dump_dir, etc.) support ~ expansion to the home directory when loading from file. Example: data_dir = "~/.local/share/blvm-mainnet" resolves to /home/user/.local/share/blvm-mainnet on Unix.

Configuration File

Create a blvm.toml configuration file. Keys are top-level or in nested tables such as [storage]: there is no [network] wrapper.

RPC bind address is set by the blvm binary (--rpc-addr / BLVM_RPC_ADDR), not by a port/host table. The optional [rpc] table holds RPC server limits only (e.g. max_request_size_bytes, IP rate limits). Auth uses [rpc_auth]. See the configuration reference.

# P2P listen address (NodeConfig library default: 127.0.0.1:8333; `blvm` CLI without config file uses network-aware ports)
listen_addr = "127.0.0.1:8333"

# TOML uses serde enum tags (lowercase, no underscore): tcponly, irohonly, quinnonly, hybrid, all
# The `blvm` CLI and BLVM_NODE_TRANSPORT accept forms like tcp_only
transport_preference = "tcponly"

max_peers = 100
protocol_version = "BitcoinV1" # mainnet-style; use "Regtest" / Testnet3 naming per protocol variant docs
enable_self_advertisement = true

[storage]
data_dir = "/var/lib/blvm"
database_backend = "auto" # auto | rocksdb | tidesdb | heed3 | redb | sled: see storage docs

# Optional: RPC limits only (not bind address)
# [rpc]
# max_request_size_bytes = 1048576

Defaults (two layers):

• blvm operator binary (no config file): default network regtest. RPC when --rpc-addr is omitted: mainnet 127.0.0.1:8332, testnet 127.0.0.1:18332, regtest 127.0.0.1:18443 (Core-aligned). P2P: mainnet 0.0.0.0:8333, testnet 0.0.0.0:18333, regtest 0.0.0.0:18444. Override with --listen-addr / BLVM_LISTEN_ADDR and --rpc-addr / BLVM_RPC_ADDR.
• NodeConfig library default (used when embedding blvm-node): listen_addr localhost 8333, protocol_version "BitcoinV1", transport_preference TCP-only, max_peers 100.

Configuration is organized in logical sections (storage, ibd, modules, optional [stratum_v2], etc.) in the node codebase. Initial block download uses parallel IBD only.

Bitcoin Core bitcoin.conf versus BLVM

BLVM does not read bitcoin.conf. Runtime configuration is blvm.toml / JSON, blvm CLI, and BLVM_* environment variables.

To draft a blvm.toml from a Core config file, use blvm config convert-core <path/to/bitcoin.conf> (or the convert-bitcoin-core-config shell/Rust tools in the blvm-node repo). Review and normalize the output: remove legacy [network] wrappers and nested [transport_preference] blobs. [rpc_auth].username / password are valid for HTTP Basic (map from Core rpcuser / rpcpassword), or use tokens / admin_tokens for Bearer auth: see the blvm-node Integration Guide: Migrating from bitcoin.conf. Always wire --rpc-addr and set storage.data_dir separately.

IBD Configuration

Default mode = "parallel". LAN peers are auto-preferred for download. On WAN-only sync, parallel mode uses multi-peer work-stealing; set BLVM_IBD_WAN_SINGLE_PEER=1 to force a single download peer. Overrides: BLVM_IBD_PEERS, BLVM_IBD_MODE, BLVM_IBD_ENGINE. First sync: First Node Setup: Mainnet IBD. Engine details: IBD UTXO engine.

[ibd]
chunk_size = 128
max_blocks_in_transit_per_peer = 128
download_timeout_secs = 30
mode = "parallel"
eviction = "fifo"
headers_timeout_secs = 30
headers_max_failures = 10

ENV: BLVM_IBD_*: see configuration reference.

Protocol Limits

Tune P2P message limits for constrained networks:

[protocol_limits]
max_protocol_message_length = 33554432 # 32 MB default
max_addr_to_send = 1000
max_inv_sz = 50000
max_headers_results = 2000

Environment Variables

You can also configure via environment variables (ENV overrides config file):

export BLVM_NETWORK=testnet
export BLVM_DATA_DIR=/var/lib/blvm
# Use the RPC socket your node binds (example: mainnet 8332; testnet 18332; regtest 18443)
export BLVM_RPC_ADDR=127.0.0.1:8332
export BLVM_IBD_EVICTION=dynamic
export BLVM_NETWORK_TARGET_PEER_COUNT=125

Common ENV vars: BLVM_DATA_DIR, BLVM_NETWORK, BLVM_LISTEN_ADDR, BLVM_RPC_ADDR, BLVM_LOG_LEVEL, BLVM_NODE_MAX_PEERS, BLVM_IBD_*, BLVM_NETWORK_TARGET_PEER_COUNT, BLVM_REQUEST_*, BLVM_MODULE_MAX_*, RPC_AUTH_TOKENS, COMMONS_API_KEY, RUST_LOG.

See Environment variables for the complete list.

Command Line Options

Precedence: CLI > ENV > config file > defaults

Global Options

Feature Flags

--enable-stratum-v2, --enable-dandelion, --enable-sigop and corresponding --disable-* flags (each requires that compile-time feature in the binary).

BIP158: --enable-bip158 / --disable-bip158 adjust logged preference only, compact block filter code is compiled without a separate bip158 Cargo feature (present in typical blvm / blvm-node builds).

REST API: enable in blvm.toml with [rest_api].enabled = true (requires rest-api in the binary). Binds a separate loopback port (default 8080 when RPC is 8332, 18080 when RPC is 18332, otherwise RPC port + 10000: e.g. 28443 for regtest 18443). See RPC API: REST.

Advanced Options

--assumevalid, --noassumevalid, --assumeutxo, --target-peer-count, --async-request-timeout, --module-max-cpu-percent, --module-max-memory-bytes.

Commands

start (default), status, health, version, chain, peers, network, sync, config show|validate|path|set|convert-core, configpath <module> (offline module config path), load / unload / reload / module list (admin RPC to a running node), migrate core (requires rocksdb), rpc, plus dynamic module CLI (e.g. blvm sync-policy list when selective-sync is loaded). Remote subcommands use [rpc_auth] from the same --config as the node (admin Bearer token or Basic password).

blvm --network mainnet -d /var/lib/blvm
blvm migrate core --source ~/.bitcoin --destination ~/.bitcoin/blvm --network mainnet --verify
blvm start --data-dir ~/.bitcoin --migrate-core-only # migrate only, then exit
blvm config show
blvm status --rpc-addr 127.0.0.1:8332

Bitcoin Core drop-in

BLVM does not read Core chainstate in place. With rocksdb, a synced Core --data-dir triggers one-time migration into <datadir>/blvm/ unless disabled. After migrate, point --data-dir at the BLVM store or keep the Core path (node opens blvm/ when marked).

Default behavior: migrate UTXOs and indexes only; do not copy Core blocks/ (~700 GB on mainnet). BLVM reads block bodies from the original Core blocks/ directory via a fallback reader. Set storage.reuse_core_block_files = false (or BLVM_REUSE_CORE_BLOCK_FILES=0) only if you want a self-contained BLVM store that duplicates block files.

[storage]
auto_migrate_core = true
# core_migrate_destination = "/var/lib/blvm-mainnet"
# reuse_core_block_files = true # default; set false to copy block bodies into BLVM store

ENV and reference: Configuration Reference (storage.auto_migrate_core, storage.reuse_core_block_files, BLVM_*). Operator flow: Operations. Storage details: Storage Backends. Map Core datadir= via blvm config convert-core: see bitcoin.conf vs BLVM.

Storage Backends

The node uses multiple storage backends with automatic fallback:

Database Backends

• auto (default): Resolve by build features, heed3 when heed3 feature enabled, then RocksDB, TidesDB, Redb, Sled (see Configuration Reference)
• rocksdb, tidesdb, redb, sled: Force a specific backend (see Storage Backends); auto matches default_backend() order in code

Storage Configuration

[storage]
data_dir = "/var/lib/blvm"
database_backend = "auto" # or "rocksdb", "tidesdb", "heed3", "redb", "sled"

[storage.cache]
block_cache_mb = 100
utxo_cache_mb = 50
header_cache_mb = 10

# Pruning uses PruningConfig: see configuration reference. Example: normal mode with ~288 recent blocks
[storage.pruning]
mode = { type = "normal", keep_from_height = 0, min_recent_blocks = 288 }
auto_prune = true
min_blocks_to_keep = 144

Backend Selection

When database_backend = "auto", the node selects by build features: heed3 (LMDB, if heed3 feature enabled: default), then RocksDB, TidesDB, Redb, Sled. Falls back to the next option if the preferred backend is unavailable.

Cache Configuration

Storage cache sizes can be configured:

• Block / UTXO / header cache: See Configuration Reference for canonical defaults (e.g. 100 / 50 / 10 MB).

Pruning

Pruning reduces storage requirements by trimming old block data. PruningConfig defaults in code use an aggressive-style mode with UTXO-commitment expectations; validate your build features (utxo-commitments for aggressive) or choose type = "normal" / type = "disabled" explicitly. See configuration reference and blvm-node pruning examples.

[storage.pruning]
mode = { type = "disabled" }
auto_prune = false
min_blocks_to_keep = 144

Note: Pruning reduces storage but limits ability to serve historical blocks to peers.

Network Configuration

Transport Options

Configure transport selection at the top level of blvm.toml (see Transport Abstraction):

# File (TOML): serde tags: tcponly | irohonly | quinnonly | hybrid | all
transport_preference = "tcponly"

Mapping (CLI / ENV vs config file):

• TOML/JSON on NodeConfig: lowercase enum tags as above (tcponly, …).
• blvm flags / BLVM_NODE_TRANSPORT: e.g. tcp_only, iroh_only, hybrid (see blvm --help).

Available Transport Options:

• TCP-only (tcponly in file): default, Bitcoin P2P compatible
• Iroh-only (irohonly): requires iroh feature
• Quinn-only (quinnonly): requires quinn feature
• Hybrid (hybrid): TCP + Iroh; requires iroh feature
• All (all): requires both quinn and iroh features

Feature Requirements:

• iroh feature: Enables Iroh QUIC transport with NAT traversal
• quinn feature: Enables standalone Quinn QUIC transport

RBF Configuration

Configure Replace-By-Fee (RBF) behavior with 4 modes: Disabled, Conservative, Standard (default), and Aggressive.

RBF Modes

Disabled: No RBF replacements allowed

[rbf]
mode = "disabled"

Conservative: Strict rules with higher fee requirements

[rbf]
mode = "conservative"
min_fee_rate_multiplier = 2.0
min_fee_bump_satoshis = 5000
min_confirmations = 1
max_replacements_per_tx = 3
cooldown_seconds = 300

Standard (default): BIP125-compliant RBF

[rbf]
mode = "standard"
min_fee_rate_multiplier = 1.1
min_fee_bump_satoshis = 1000

Aggressive: Relaxed rules for miners

[rbf]
mode = "aggressive"
min_fee_rate_multiplier = 1.05
min_fee_bump_satoshis = 500
allow_package_replacements = true

See RBF and Mempool Policies for complete configuration guide.

Advanced Indexing

Enable address and value range indexing for efficient queries:

[storage.indexing]
enable_address_index = true
enable_value_index = true
strategy = "eager" # or "lazy"
max_indexed_addresses = 0 # 0 = unlimited
enable_compression = false # zstd index blobs; requires compression (blvm default features)
background_indexing = false # lazy only: index on txindex-bg thread

Module Configuration

Configure process-isolated modules. There is no hardcoded default module list in the node: copy pins from blvm.toml.example or set your own. An empty pin map auto-discovers modules already on disk under modules_dir (no HTTP bootstrap).

[modules]
enabled = true # Enable module system (default: true)
modules_dir = "modules" # Directory containing module binaries (default: "modules")
data_dir = "data/modules" # Directory for module data/state (default: "data/modules")
socket_dir = "data/modules/sockets" # Directory for IPC sockets (default: "data/modules/sockets")
registry_url = "https://raw.githubusercontent.com/BTCDecoded/blvm/main/registry/modules.json"
# Version pins (wildcard or exact semver). Omit pins to load on-disk modules only.
blvm-miniscript = "0.1.*"
# When a module needs spawn overrides, put the pin in its table as `version`:
[modules.blvm-zmq]
version = "0.1.*"
hashblock = "tcp://127.0.0.1:28332"
# Legacy unpinned allowlist: enabled_modules = ["blvm-miniscript"]

See Module System and node modules README for bootstrap and registry details. ZMQ topic endpoints: ZMQ module.

Module resource limits (optional) use the [module_resource_limits] table on NodeConfig, not [modules.resource_limits]:

[module_resource_limits]
default_max_cpu_percent = 50
default_max_memory_bytes = 536870912
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

See Module System for module configuration details.

See Also

• Node Overview - Node features and architecture
• Node Operations - Running and managing your node
• Storage Backends - Detailed storage backend information
• Transport Abstraction - Transport options
• Network Protocol - Protocol variants and network configuration
• Configuration Reference - Complete configuration reference
• Getting Started - Installation guide
• Troubleshooting - Common configuration issues

RPC API Reference

BLVM node provides both a JSON-RPC 2.0 interface (conventional Bitcoin RPC surface) and a modern REST API for interacting with the node.

On this page: API Overview · Connection · Authentication · JSON-RPC over QUIC · Methods operators use most · Core parity matrix · Available Methods · Errors · REST API

API Overview

• JSON-RPC 2.0: Methods aligned with widely documented Bitcoin node RPC docs. The blvm binary binds JSON-RPC to --rpc-addr / BLVM_RPC_ADDR. When omitted, RPC is network-aware: mainnet 127.0.0.1:8332, testnet 127.0.0.1:18332, regtest 127.0.0.1:18443 (Core-aligned).
• REST API (optional): Requires rest-api feature and [rest_api].enabled = true in blvm.toml. Binds a separate port (default 8080 when RPC is 8332, 18080 when RPC is 18332, otherwise RPC port + 10000). See REST API.

Connection

Use the same host:port you configure as --rpc-addr / BLVM_RPC_ADDR. Defaults: mainnet http://127.0.0.1:8332, testnet http://127.0.0.1:18332, regtest http://127.0.0.1:18443. There is no separate RPC port key in NodeConfig. See Node Configuration.

Authentication

Configure RPC authentication with [rpc_auth]. Two common patterns:

Bearer tokens (wallets, automation):

[rpc_auth]
required = true
tokens = ["your-long-random-token"]
admin_tokens = ["admin-token-for-mining-rpcs"] # optional; mining/destructive methods

Pass Authorization: Bearer <token> on each request. Tokens in tokens alone are read-only unless also listed in admin_tokens.

HTTP Basic (ckpool, Bitcoin Core-style tools, curl -u):

[rpc_auth]
required = true
username = "ckpool"
password = "your-long-random-secret"

The password is registered as admin automatically (required for getblocktemplate / submitblock). Bind RPC to loopback (--rpc-addr 127.0.0.1:8332): Basic auth is cleartext on the wire.

Optional: token_file, certificates, RPC_AUTH_TOKENS. [rpc] in NodeConfig is only for limits / rate limits, not credentials.

TLS client certificates are supported when QUIC transport and certificate fingerprints are configured (certificates in [rpc_auth]).

See RPC transport × authentication and Deployment posture.

JSON-RPC over QUIC (HTTP/3)

Bitcoin Commons optionally serves JSON-RPC over HTTP/3 on QUIC (Quinn + h3) alongside the default TCP HTTP server. Both paths share RpcServer and RpcAuthManager.

Authentication: Send Authorization: Bearer … on HTTP/3 requests; rpc_auth.required and token configuration match TCP HTTP. Read RPC transport × authentication before exposing QUIC RPC beyond localhost.

When to use: High-throughput internal services where clients support QUIC and you want built-in TLS without a separate layer.

When not to use: Most ecosystem tooling assumes TCP HTTP to port 8332 (mainnet), 18332 (testnet), or 18443 (regtest). Prefer TCP for scripts, curl, and Core-compatible clients.

Enable QUIC RPC

QUIC RPC requires the quinn feature:

[dependencies]
blvm-node = { path = "../blvm-node", features = ["quinn"] }

cargo build --features quinn

Server setup

#![allow(unused)]
fn main() {
use blvm_node::rpc::RpcManager;
use std::net::SocketAddr;

let tcp_addr: SocketAddr = "127.0.0.1:8332".parse().unwrap();
let quinn_addr: SocketAddr = "127.0.0.1:18332".parse().unwrap();

#[cfg(feature = "quinn")]
let mut rpc_manager = RpcManager::with_quinn(tcp_addr, quinn_addr);

// Or enable after creation:
// let mut rpc_manager = RpcManager::new(tcp_addr);
// #[cfg(feature = "quinn")]
// rpc_manager.enable_quinn(quinn_addr);

rpc_manager.start().await?;
}

QuinnRpcServer generates self-signed certificates for development; production deployments need proper certificate management. QUIC adds transport encryption; same security boundaries as TCP RPC (no wallet access).

QUIC client (example)

#![allow(unused)]
fn main() {
use quinn::Endpoint;
use std::net::SocketAddr;

let server_addr: SocketAddr = "127.0.0.1:18332".parse().unwrap();
let endpoint = Endpoint::client("0.0.0.0:0".parse().unwrap())?;
let connection = endpoint.connect(server_addr, "localhost")?.await?;
let (mut send, mut recv) = connection.open_bi().await?;

let request = r#"{"jsonrpc":"2.0","method":"getblockchaininfo","params":[],"id":1}"#;
send.write_all(request.as_bytes()).await?;
send.finish().await?;

let mut response = Vec::new();
recv.read_to_end(&mut response).await?;
}

Source: QUIC RPC, quinn_server.rs.

Example Requests

Get Blockchain Info

# Mainnet 8332; testnet 18332; regtest 18443
curl -X POST http://localhost:8332 \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "method": "getblockchaininfo",
 "params": [],
 "id": 1
 }'

Get Block

# Mainnet 8332; testnet 18332; regtest 18443
curl -X POST http://localhost:8332 \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "method": "getblock",
 "params": ["000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f"],
 "id": 1
 }'

Get Network Info

# Mainnet 8332; testnet 18332; regtest 18443
curl -X POST http://localhost:8332 \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "method": "getnetworkinfo",
 "params": [],
 "id": 1
 }'

Methods operators use most

Fifteen RPC methods cover most operator, wallet, and mining workflows. Full catalog: Available Methods below.

getblockchaininfo (example response fields)

{
 "chain": "regtest",
 "blocks": 1,
 "headers": 1,
 "bestblockhash": "...",
 "difficulty": 1.0,
 "chainwork": "...",
 "pruned": false
}

On regtest at genesis, "blocks": 0, "difficulty": 1.0, and "initialblockdownload": true are typical.

sendrawtransaction

Submit hex-encoded signed transaction. Returns txid on success; errors if policy or consensus rejects the tx.

# Testnet example (18332); regtest uses 18443, mainnet 8332
curl -X POST http://127.0.0.1:18332 \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc":"2.0","method":"sendrawtransaction","params":["<hex>"],"id":1}'

Requires valid auth when [rpc_auth].required = true.

Bitcoin Core RPC parity (selected)

BLVM targets common Bitcoin Core JSON-RPC shapes for interoperability (ckpool, scripts, wallets). This is not a complete Core parity audit: verify critical paths for your deployment.

Ports: BLVM defaults RPC to 18332 (testnet) and 18443 (regtest, Core-aligned). Set --rpc-addr / BLVM_RPC_ADDR when you need a different bind.

Available Methods

Core JSON-RPC: 75 methods in CORE_RPC_METHODS (see blvm-node/src/rpc/methods.rs). Module RPC (mesh, miniscript overrides, etc.) registers at runtime.

Blockchain Methods

Raw Transaction Methods

Mempool Methods

Network Methods

Mining Methods

Module Methods

Dynamic module RPC (mesh, miniscript overrides, …) registers at load time. See module pages and JSON-RPC error reference.

Control Methods

Mesh Methods

Requires blvm-mesh loaded.

See Commons Mesh Module.

Address Methods

Transaction Methods

Payment Methods (BIP70)

Build / platform: bip70-http requires full blvm features; portable Windows/aarch64 CI builds omit it. ctv is a separate compile-time feature. See Installation.

Source of truth: blvm-node/src/rpc/methods.rs (CORE_RPC_METHODS).

Error Codes

BLVM uses standard JSON-RPC 2.0 codes, Bitcoin-style application codes (-1, -5, -25, -27), BLVM server codes (-32001), and HTTP 401/403/429 for auth, admin RBAC, and rate limits.

Full catalog: JSON-RPC error reference: every code, error.data fields, admin-only methods, and transport vs JSON-RPC shapes.

Quick reference

Example JSON-RPC error

{
 "jsonrpc": "2.0",
 "error": {
 "code": -32602,
 "message": "Invalid params",
 "data": {
 "param": "blockhash",
 "reason": "Invalid hex string"
 }
 },
 "id": 1
}

Rate Limiting

Rate limiting is enforced per IP, per user, and per method:

• Authenticated users: 100 burst, 10 req/sec
• Unauthenticated: 50 burst, 5 req/sec
• Per-method limits: May override defaults for specific methods

Request/Response Format

Request Format

{
 "jsonrpc": "2.0",
 "method": "getblockchaininfo",
 "params": [],
 "id": 1
}

Response Format

Success Response:

{
 "jsonrpc": "2.0",
 "result": {
 "chain": "regtest",
 "blocks": 123456,
 "headers": 123456,
 "bestblockhash": "0000...",
 "difficulty": 4.656542373906925e-10
 },
 "id": 1
}

Error Response:

{
 "jsonrpc": "2.0",
 "error": {
 "code": -32602,
 "message": "Invalid params"
 },
 "id": 1
}

Batch Requests

Multiple requests can be sent in a single batch:

[
 {"jsonrpc": "2.0", "method": "getblockchaininfo", "params": [], "id": 1},
 {"jsonrpc": "2.0", "method": "getblockhash", "params": [100], "id": 2},
 {"jsonrpc": "2.0", "method": "getblock", "params": ["0000..."], "id": 3}
]

Responses are returned in the same order as requests.

Implementation Status

The RPC API implements JSON-RPC 2.0 methods documented in the Available Methods section above.

REST API

Overview

The REST API is a separate HTTP server from JSON-RPC (blvm-node/src/rpc/rest/). It requires the rest-api compile-time feature (included in blvm default features; omitted from portable Windows/aarch64 release builds).

Operator note: REST is off by default ([rest_api].enabled = false). When enabled, it binds its own address (default loopback 8080 / 18080 from RPC port). Handler coverage matches rest/server.rs routing, not every function in rest/*.rs.

When enabled programmatically, REST binds its own address (tests use 127.0.0.1:8080). It does not share the JSON-RPC port (8332 / 18332 / 18443). HTTP GET /health on the RPC port is separate (see Node Operations).

Base URL (when running): http://<rest-bind>/api/v1/

Authentication

Same RpcAuthConfig / RpcAuthManager as JSON-RPC when the REST server is built with RestServer::with_auth(...) (Bearer tokens, HTTP Basic, admin tokens). If auth is enabled on that instance, unauthenticated requests receive 401 Unauthorized before route handlers run: same guard as JSON-RPC. When auth is disabled, REST accepts anonymous requests (still subject to per-IP rate limits). Embedders must call with_auth explicitly; default test servers may run without it.

Admin RBAC mirrors JSON-RPC admin_rpc_methods() via rest/rbac.rs: each REST path maps to an equivalent RPC method; privileged routes return 403 Forbidden for authenticated non-admin tokens. Examples: GET /api/v1/mining/block-template, POST /api/v1/node/stop, POST /api/v1/transactions. Non-admin POST routes include POST /api/v1/transactions/decode, …/test, POST /api/v1/chain/verify, and POST /api/v1/network/ping. Unmapped POST/DELETE paths (e.g. payment writes) fail closed (admin required).

Endpoints (wired in rest/server.rs)

Chain

• GET /api/v1/chain/tip: Best block hash
• GET /api/v1/chain/height: Block height
• GET /api/v1/chain/info: Blockchain state summary
• GET /api/v1/chain/difficulty: Current difficulty
• GET /api/v1/chain/utxo-set: UTXO set summary
• GET /api/v1/chain/tips: Known chain tips
• GET /api/v1/chain/tx-stats?nblocks={n}: Transaction statistics
• GET /api/v1/chain/prune-info: Pruning status
• POST /api/v1/chain/verify: Verify chain (optional JSON: checklevel, numblocks)
• POST /api/v1/chain/prune: Prune to height (JSON: height)

Indexes

• GET /api/v1/indexes: Index status (optional ?index={name})

Blocks

• GET /api/v1/blocks/{hash}: Block by hash
• GET /api/v1/blocks/{hash}/header: Block header
• GET /api/v1/blocks/{hash}/stats: Block statistics
• GET /api/v1/blocks/{hash}/filter: Block filter
• GET /api/v1/blocks/{hash}/transactions: Block transactions
• GET /api/v1/blocks/height/{height}: Block by height
• POST /api/v1/blocks/{hash}/invalidate: Invalidate block (admin)
• POST /api/v1/blocks/{hash}/reconsider: Reconsider block (admin)

Transactions

• GET /api/v1/transactions/{txid}: Transaction details
• GET /api/v1/transactions/{txid}/confirmations
• GET /api/v1/transactions/{txid}/outputs/{n}?include_mempool=true: Output details
• POST /api/v1/transactions: Submit raw hex (body)
• POST /api/v1/transactions/test: Test mempool acceptance
• POST /api/v1/transactions/decode: Decode raw hex
• POST /api/v1/transactions/create: Create raw tx (JSON: inputs, outputs, optional locktime, replaceable, version)

Addresses

• GET /api/v1/addresses/{address}/balance
• GET /api/v1/addresses/{address}/transactions
• GET /api/v1/addresses/{address}/utxos

Mempool

• GET /api/v1/mempool: List txids (verbose via query where supported)
• GET /api/v1/mempool/transactions/{txid}: Mempool entry
• GET /api/v1/mempool/transactions/{txid}/ancestors: Ancestor txids
• GET /api/v1/mempool/transactions/{txid}/descendants: Descendant txids
• GET /api/v1/mempool/stats: Mempool info (maps to getmempoolinfo)
• POST /api/v1/mempool/save: Persist mempool to disk
• POST /api/v1/mempool/transactions/{txid}/priority: Adjust effective fee (JSON: fee_delta; admin; maps to prioritisetransaction)

Network

• GET /api/v1/network/info
• GET /api/v1/network/peers
• GET /api/v1/network/connections/count
• GET /api/v1/network/connections/totals
• GET /api/v1/network/nodes: Known nodes
• GET /api/v1/network/addresses: Network addresses
• GET /api/v1/network/bans: Ban list
• POST /api/v1/network/ping: Ping peers
• POST /api/v1/network/nodes: Add/remove node (JSON: address, command)
• POST /api/v1/network/active: Set network active (JSON: state)
• POST /api/v1/network/bans: Ban subnet (JSON body)
• DELETE /api/v1/network/nodes/{addr}: Disconnect node
• DELETE /api/v1/network/bans/{subnet}: Remove ban

Node

• GET /api/v1/node/uptime
• GET /api/v1/node/memory
• GET /api/v1/node/rpc-info
• GET /api/v1/node/help?command={name}
• GET /api/v1/node/logging
• POST /api/v1/node/stop: Stop node (admin)
• POST /api/v1/node/logging: Set logging categories (JSON body)

Mining

• GET /api/v1/mining/info
• GET /api/v1/mining/block-template
• POST /api/v1/mining/blocks: Submit block (JSON body)

Fees

• GET /api/v1/fees/estimate?blocks=6: Smart fee estimate (default 6 blocks)

Payment / CTV (bip70-http, ctv)

When the REST server is running and payment state is configured:

• GET|POST /api/v1/payments: List / create payment requests
• GET /api/v1/payments/{id}: Payment state
• POST /api/v1/payments/{id}/covenant: CTV covenant proof (ctv feature)
• Vault: POST /api/v1/vaults, GET /api/v1/vaults/{id}, POST …/unvault, POST …/withdraw
• Pool: POST /api/v1/pools, GET /api/v1/pools/{id}, POST …/join, POST …/distribute
• Batch: POST /api/v1/batches, GET /api/v1/batches/{id}, POST …/transactions, POST …/broadcast
• GET /api/v1/congestion: Congestion metrics

Legacy BIP70 HTTP also registers under /api/v1/payment/* when bip70-http is enabled.

Response format

Success and error envelopes use ApiResponse (status, data / error, request_id). See rest/types.rs.

Error codes

Standard HTTP status codes: 200, 400, 401, 404, 429, 500, 503 (feature or payment engine unavailable).

Source

• auth.rs
• server.rs
• types.rs
• rest/mod.rs
• rest/server.rs
• rest/types.rs
• rest/node.rs
• rest/blocks.rs
• rest/network.rs
• rest/payment.rs
• rest/vault.rs
• rest/pool.rs
• rest/congestion.rs

See Also

• Node Overview - Node implementation details
• Node Configuration - RPC configuration options
• JSON-RPC error reference - Error codes and HTTP auth failures
• Node Operations - Node management
• Getting Started - Quick start guide
• API Index - Cross-reference to all APIs
• Troubleshooting - Common RPC issues
• Commons Mesh Module - Payment endpoints and mesh networking
• Module System - Module architecture and IPC

Storage Backends

Overview

The node supports multiple database backends for persistent storage of blocks, UTXO set, and chain state. When database_backend = "auto" (the default), the backend is chosen by build features via default_backend(): not by host OS. heed3 (LMDB) wins when the heed3 feature is compiled in, then RocksDB, TidesDB, Redb, Sled. blvm / blvm-node Cargo.toml defaults enable heed3, so auto → heed3 on a normal local build and on Linux x86_64 release artifacts. Windows portable and Linux aarch64 cross-release builds include heed3 (bundled LMDB) plus redb/sled fallbacks: omit rocksdb and other native-heavy deps. There auto → heed3. See Configuration Reference.

Supported Backends

rocksdb (optional; explicit config or fallback)

RocksDB remains available when the rocksdb feature is enabled (default builds include both heed3 and rocksdb). Use database_backend = "rocksdb" to keep or create a RocksDB store, or when migrating from Core LevelDB layouts:

• High performance for large chain state
• Interop: Can work with typical LevelDB-format chain state and blk*.dat layouts where supported
• Build: Requires system libclang / LLVM for the librocksdb-sys stack
• Feature: rocksdb (on by default in blvm-node / blvm default features)

Note: RocksDB and erlay features are mutually exclusive in this tree (dependency conflicts).

redb (pure Rust)

redb is a production-ready embedded database. It is chosen by auto only when RocksDB and TidesDB are not in the build (or you set database_backend = "redb"):

• Pure Rust: No C dependencies
• ACID Compliance: Full ACID transactions
• Typical use: --no-default-features / minimal builds that omit RocksDB, or explicit operator choice

tidesdb

TidesDB is optional; in auto it is preferred over Redb/Sled only when RocksDB is not enabled. See crate features and Configuration Reference.

heed3 (LMDB mdb.master3)

heed3 wraps LMDB with MVCC concurrent readers (WithoutTls read transactions). Default backend when database_backend = "auto" in standard builds (heed3 feature enabled):

• MVCC: Many concurrent read transactions; single writer (LMDB model)
• rkyv UTXO encoding: Zero-copy field access from mmap'd pages (storage/rkyv_codec.rs, storage/utxo_value_codec.rs)
• Build: Requires system liblmdb
• Data directory: {datadir}/heed3/
• Feature: heed3 (enabled in default blvm / blvm-node features)

LMDB map size defaults to 64 GiB (max(65536, dbcache_mb × 128) MB). Override only if you know your UTXO footprint:

[storage]
database_backend = "heed3"

[storage.heed3]
# map_size_mb = 65536 # default; required headroom for mainnet UTXO set
max_readers = 512

Existing RocksDB datadir: auto on a tree that already has {datadir}/rocksdb/ does not migrate it. Use a fresh datadir for heed3, or set database_backend = "rocksdb" to keep the existing store.

sled (Fallback)

sled is available as a fallback option:

• Beta Quality: Not recommended for production
• Pure Rust: No C dependencies
• Performance: Good for development and testing
• Storage: Key-value storage with B-tree indexing

Backend Selection

When database_backend = "auto", the node picks the first compiled-in backend below (not OS). Explicit values skip this chain.

Core chainstate import requires the rocksdb feature: use blvm migrate core / auto-migrate, independent of auto selection above.

Selection order (auto)

1. heed3 / LMDB (if the heed3 feature is enabled: default in standard builds)
2. RocksDB (if the rocksdb feature is enabled)
3. TidesDB (if the tidesdb feature is enabled and neither heed3 nor RocksDB is)
4. Redb (if the redb feature is enabled and no higher-priority backend is)
5. Sled (if the sled feature is enabled and no other backend is)

At least one backend feature must be enabled at build time. If the chosen backend fails to open (e.g. missing data dir or lock), the node may fall back to another enabled backend where implemented.

Interop: When RocksDB is enabled, the node may detect and use existing LevelDB-format chain data. That is separate from the auto selection order above.

Core LevelDB interop

Bitcoin Core chainstate/ uses LevelDB (.ldb / .log files). BLVM’s rocksdb migration path reads typical Core layouts via a dedicated LevelDB reader: not by opening chainstate as a native RocksDB database.

Portable Windows/aarch64 builds without rocksdb cannot run Core chainstate migration: use Linux x86_64 / default-feature builds or sync without Core import.

See Starting from a Bitcoin Core datadir and Troubleshooting: Corrupted database.

Automatic Fallback

If the backend chosen by auto fails to open, the node may fall back to another enabled backend (see fallback_backend() in code).

#![allow(unused)]
fn main() {
// Backend is chosen by default_backend() when using "auto"; fallback on open failure
let storage = Storage::new(data_dir)?;
}

Database Abstraction

The storage layer uses one database abstraction interface:

Database Trait

#![allow(unused)]
fn main() {
pub trait Database: Send + Sync {
 fn open_tree(&self, name: &str) -> Result<Box<dyn Tree>>;
 fn flush(&self) -> Result<()>;
}
}

Tree Trait

#![allow(unused)]
fn main() {
pub trait Tree: Send + Sync {
 fn insert(&self, key: &[u8], value: &[u8]) -> Result<()>;
 fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>>;
 fn remove(&self, key: &[u8]) -> Result<()>;
 fn contains_key(&self, key: &[u8]) -> Result<bool>;
 fn len(&self) -> Result<usize>;
 fn iter(&self) -> Box<dyn Iterator<Item = Result<(Vec<u8>, Vec<u8>)>> + '_>;
}
}

Storage Components

BlockStore

Stores blocks by hash:

• Key: Block hash (32 bytes)
• Value: Serialized block data
• Indexing: Hash-based lookup

UtxoStore

Manages UTXO set:

• Key: OutPoint (36 bytes: txid + output index)
• Value: UTXO data (script, amount)
• Operations: Add, remove, query UTXOs

ChainState

Tracks chain metadata:

• Tip Hash: Current chain tip
• Height: Current block height
• Chain Work: Cumulative proof-of-work
• UTXO Stats: Cached UTXO set statistics

TxIndex

Transaction indexing:

• Key: Transaction ID (32 bytes)
• Value: Transaction data and metadata
• Lookup: Fast transaction retrieval

Configuration

Backend Selection

[storage]
data_dir = "/var/lib/blvm"
database_backend = "auto" # typical release: heed3 (LMDB); or "rocksdb" | "tidesdb" | "redb" | "sled"

Options:

• "auto": Select by build features (heed3 when heed3 enabled, then RocksDB, TidesDB, Redb, Sled)
• "heed3": Force heed3 / LMDB (requires heed3 feature; rkyv UTXO encoding)
• "rocksdb": Force RocksDB (requires rocksdb feature)
• "tidesdb": Force TidesDB (requires tidesdb feature)
• "redb": Force redb backend
• "sled": Force sled backend

RocksDB Configuration

The rocksdb feature is enabled by default in blvm-node / blvm; you only need flags when building a minimal tree without RocksDB:

cargo build -p blvm-node --features rocksdb

System Requirements:

• libclang must be installed (required for RocksDB FFI bindings)
• On Ubuntu/Debian: sudo apt-get install libclang-dev
• On Arch: sudo pacman -S clang
• On macOS: brew install llvm

Default data directories (common layouts): The system can detect typical Bitcoin-style data directories:

• Mainnet: ~/.bitcoin/ or ~/Library/Application Support/Bitcoin/
• Testnet: ~/.bitcoin/testnet3/ or ~/Library/Application Support/Bitcoin/testnet3/
• Regtest: ~/.bitcoin/regtest/ or ~/Library/Application Support/Bitcoin/regtest/

Cache Configuration

[storage.cache]
block_cache_mb = 100
utxo_cache_mb = 50
header_cache_mb = 10

Cache Sizes: See Configuration Reference for canonical defaults (e.g. block 100 MB, UTXO 50 MB, header 10 MB).

Performance Characteristics

redb Backend

• When: Explicit database_backend = "redb" or auto without RocksDB/TidesDB in the build
• Read Performance: Excellent for sequential and random reads
• Write Performance: Good for batch writes
• Production: A solid pure-Rust choice when you are not using RocksDB

heed3 (LMDB) Backend

• When: Default auto path in standard blvm builds (heed3 feature enabled)
• Read/Write: LMDB + rkyv UTXO encoding; mmap-friendly reads for IBD

RocksDB Backend

• When: Explicit database_backend = "rocksdb", or auto when the heed3 feature is absent from the build (Windows portable CI). Standard Linux / default-feature builds use heed3 for auto.
• Read/Write: Tuned for large chain-state workloads; required for Core LevelDB migration reader

sled Backend

• Read Performance: Good for sequential reads
• Write Performance: Good for batch writes
• Storage Efficiency: Efficient with B-tree indexing
• Memory Usage: Higher memory footprint
• Production Ready: Beta quality, not recommended for production

Migration

Bitcoin Core drop-in (migrate on start)

With the rocksdb feature (blvm default features; omitted from portable Windows/aarch64 release builds), point --data-dir at a synced Core tree (chainstate/ + blocks/) to import once into <datadir>/blvm/. Stop bitcoind first; match --network to the datadir.

Operator steps: Starting from a Bitcoin Core datadir. Flags and ENV: Bitcoin Core drop-in. Config keys: storage.auto_migrate_core, core_migrate_destination, storage.reuse_core_block_files.

After success, blvm_meta/migration.json marks the store; interrupted runs resume via blvm_meta/migration_checkpoint.json.

Reuse Core block files (default): storage.reuse_core_block_files defaults to true. Migration converts the UTXO set and builds indexes under blvm/ but leaves Core blocks/ in place: BLVM reads blk*.dat via a fallback reader. Do not delete the Core blocks/ directory while this mode is active. Disable with storage.reuse_core_block_files = false or BLVM_REUSE_CORE_BLOCK_FILES=0 to copy block bodies into the BLVM store (requires roughly double disk space for blocks).

Pruned Core: migration may fail if block files do not cover the chain tip; use a full node datadir or disable reuse and accept limited coverage.

Limits: no concurrent Core + BLVM on the same chainstate; no write-back into Core LevelDB.

Code: bitcoin_core_migrate.rs, storage/mod.rs (open_for_node).

Backend migration

To migrate between backends:

1. Export Data: Export all data from current backend
2. Import Data: Import data into new backend
3. Verify: Verify data integrity

Note: Manual migration is supported. Export data from the current backend and import into the new backend.

Pruning Support

All backends support pruning:

[storage.pruning]
mode = { type = "normal", keep_from_height = 0, min_recent_blocks = 288 }
auto_prune = true
auto_prune_interval = 144

Pruning Modes:

• Disabled: Keep all blocks (archival node)
• Normal: Conservative pruning (keep recent blocks)
• Aggressive: Prune with UTXO commitments (requires utxo-commitments feature)
• Custom: Fine-grained control over what to keep

Error Handling

The storage layer handles backend failures gracefully:

• Automatic Fallback: Falls back to alternative backend if primary fails
• Error Recovery: Attempts to recover from transient errors
• Data Integrity: Verifies data integrity on startup
• Corruption Detection: Detects and reports database corruption

Source

• database/mod.rs (default_backend(), fallback_backend(), Database / Tree traits)
• heed3_impl.rs
• storage/mod.rs, bitcoin_core_migrate.rs
• blockstore.rs, utxostore.rs, chainstate.rs, txindex.rs
• config/storage.rs, bitcoin_core_detection.rs

See Also

• Node Configuration - Storage configuration options
• Node Operations - Storage operations and maintenance
• Pruning: pruning configuration on this page; see also Node configuration

IBD Bandwidth Protection

Protects your node when serving block data to peers during their IBD: not the same as download tuning. IBD doc map: Operator guide: IBD hub. If you are downloading the chain, see IBD UTXO engine: Sync tuning guide and Performance: Parallel IBD.

Overview

The node protects against Initial Block Download (IBD) bandwidth exhaustion attacks.

Protection summary

Protection Mechanisms

Per-Peer Bandwidth Limits

Tracks bandwidth usage per peer with configurable daily and hourly limits:

• Daily Limit: Maximum bytes a peer can request per day
• Hourly Limit: Maximum bytes a peer can request per hour
• Automatic Throttling: Blocks requests when limits are exceeded
• Legitimate Node Protection: First request always allowed, reasonable limits for legitimate sync

Per-IP Bandwidth Limits

Tracks bandwidth usage per IP address to prevent single-IP attacks:

• IP-Based Tracking: Monitors all peers from the same IP
• Aggregate Limits: Combined daily/hourly limits for all peers from an IP
• Attack Detection: Identifies coordinated attacks from single IP

Per-Subnet Bandwidth Limits

Tracks bandwidth usage per subnet to prevent distributed attacks:

• IPv4 Subnets: Tracks /24 subnets (256 addresses)
• IPv6 Subnets: Tracks /64 subnets
• Subnet Aggregation: Combines bandwidth from all IPs in subnet
• Distributed Attack Mitigation: Prevents coordinated attacks from subnet

Concurrent IBD Serving Limits

Limits how many peers can simultaneously request IBD:

• Concurrent Limit: Maximum number of peers serving IBD at once
• Queue Management: Queues additional requests when limit reached
• Fair Serving: Rotates serving to queued peers

Peer Reputation Scoring

Tracks peer behavior to identify malicious patterns:

• Reputation System: Scores peers based on behavior
• Suspicious Pattern Detection: Identifies rapid reconnection with new peer IDs
• Cooldown Periods: Enforces cooldown after suspicious activity
• Legitimate Node Protection: First-time sync always allowed

Configuration

Default Limits

[ibd_protection]
max_bandwidth_per_peer_per_day_gb = 50
max_bandwidth_per_peer_per_hour_gb = 10
max_bandwidth_per_ip_per_day_gb = 100
max_bandwidth_per_ip_per_hour_gb = 20
max_bandwidth_per_subnet_per_day_gb = 500
max_bandwidth_per_subnet_per_hour_gb = 100
max_concurrent_ibd_serving = 3
ibd_request_cooldown_seconds = 3600
suspicious_reconnection_threshold = 3
reputation_ban_threshold = -100
enable_emergency_throttle = false
emergency_throttle_percent = 50

Configuration Options

• max_bandwidth_per_peer_per_day_gb: Daily limit per peer (default: 50 GB)
• max_bandwidth_per_peer_per_hour_gb: Hourly limit per peer (default: 10 GB)
• max_bandwidth_per_ip_per_day_gb: Daily limit per IP (default: 100 GB)
• max_bandwidth_per_ip_per_hour_gb: Hourly limit per IP (default: 20 GB)
• max_bandwidth_per_subnet_per_day_gb: Daily limit per subnet (default: 500 GB)
• max_bandwidth_per_subnet_per_hour_gb: Hourly limit per subnet (default: 100 GB)
• max_concurrent_ibd_serving: Maximum concurrent IBD serving (default: 3)
• ibd_request_cooldown_seconds: Cooldown period after suspicious activity (default: 3600 seconds)
• suspicious_reconnection_threshold: Number of reconnections in 1 hour to be considered suspicious (default: 3)
• reputation_ban_threshold: Reputation score below which peer is banned (default: -100)
• enable_emergency_throttle: Enable emergency bandwidth throttling (default: false)
• emergency_throttle_percent: Percentage of bandwidth to throttle when emergency throttle is enabled (default: 50)

Attack Mitigation

Single IP Attack

Attack: Attacker runs multiple fake nodes from same IP Protection: Per-IP bandwidth limits aggregate all peers from IP Result: Blocked after IP limit reached

Subnet Attack

Attack: Attacker distributes fake nodes across subnet Protection: Per-subnet bandwidth limits aggregate all IPs in subnet Result: Blocked after subnet limit reached

Rapid Reconnection Attack

Attack: Attacker disconnects and reconnects with new peer ID Protection: Reputation scoring detects pattern, enforces cooldown Result: Blocked during cooldown period

Distributed Attack

Attack: Coordinated attack from multiple IPs/subnets Protection: Concurrent serving limits prevent serving too many peers simultaneously Result: Additional requests queued, serving rotated fairly

Legitimate New Node

Scenario: Legitimate new node requests full sync Protection: First request always allowed, reasonable limits accommodate legitimate sync Result: Allowed to sync within limits

Resource pressure during IBD (memory and queues)

The limits above address bandwidth and fair serving to peers. Initial block download can also stress RAM and internal queues when blocks arrive quickly (parallel fetch, fast sync paths). If the process OOMs, stalls, or thrashes despite healthy bandwidth settings, check blvm-node configuration and release notes for IBD / sync resource behavior, not only the bandwidth counters in this chapter.

Integration

The IBD protection is automatically integrated into the network manager:

• Automatic Tracking: Tracks bandwidth when serving Headers/Block messages
• Request Protection: Protects GetHeaders and GetData requests
• Cleanup: Automatically cleans up tracking on peer disconnect

LAN Peer Prioritization

LAN peers are auto-preferred for IBD download (still subject to bandwidth limits). See LAN Peering System.

Source

• ibd_protection.rs
• network_manager.rs (IBD protection wiring and config)

See Also

• LAN Peering System - Automatic local network discovery and prioritization
• Network Operations - General network operations
• Node Configuration - IBD protection configuration
• PR security control classification - Contributor CI security control mapping

IBD UTXO engine

Sync tuning guide

First mainnet sync always starts from First Node Setup: Mainnet IBD (release IBD example config). For other IBD topics, use the operator IBD hub or:

Overview

During parallel initial block download (IBD), the node validates blocks in height order while downloading from one or more peers. By default, UTXO updates use the legacy in-process store. When enabled, an age-tiered UTXO engine holds live UTXOs in memory and on disk under storage/ibd_engine/, with mid-sync checkpoints for crash-safe resume.

Enable the engine only when you understand checkpoint storage and disk use. The release mainnet IBD example config does not turn it on.

Enable

Set before starting sync:

export BLVM_IBD_ENGINE=1

Optional environment variables:

Download scheduling still uses parallel IBD ([ibd].mode = "parallel"). The engine replaces how validated blocks apply UTXO changes during that pipeline.

Architecture

1. Index and table: Age-tiered structures track live UTXOs and support fast spend lookups during validation.
2. Spend session: Batches spend/create operations per block and feeds the engine from the validation loop.
3. Checkpoint export: Periodic snapshots of engine state allow resume after interruption without re-downloading from genesis.
4. Import / seed: On restart, the node seeds validation from the last exported checkpoint height when present.

Operator notes

• Use the same storage.data_dir on every run; do not delete the active database backend directory (heed3/, rocksdb/, …) mid-sync.
• On SIGTERM / SIGINT during parallel IBD, the node drains in-flight validation and flushes the UTXO watermark before exit when possible.
• io_uring accelerates engine table I/O on Linux; other platforms use a pread fallback (engine still runs on Windows).
• Assume-valid skips signature verification below a configured height; block structure, Merkle roots, and proof-of-work are still checked.
• First mainnet sync: First Node Setup: Mainnet IBD. Tune [ibd] in config or BLVM_IBD_* overrides only when you need explicit peer or mode control.

Configuration

See IBD Configuration for [ibd] keys and BLVM_IBD_* environment variables shared with parallel download.

Source

• ibd_engine/, parallel_ibd/validation_loop.rs
• ibd_engine/mod.rs, spend_session.rs, export.rs

See Also

• Operator guide: IBD hub: Map of all IBD docs
• Performance Optimizations: Parallel download, pipelining, reorder buffer
• IBD Bandwidth Protection: Serving-side bandwidth limits
• LAN Peering System: LAN peer preference during download
• Storage Backends: database_backend and data_dir

UTXO Commitments

Layer: Optional node fast-sync feature (blvm-protocol / blvm-node). Not part of Orange Paper consensus rules; see Consensus overview.

Build: utxo-commitments is in blvm default features (Linux x86_64 release artifacts; also in portable Windows/aarch64 CI subset). Enable at runtime via config when your deployment uses it.

Overview

UTXO Commitments enable fast synchronization of the Bitcoin UTXO set without requiring a naïve full-block replay of the entire chain. The system uses cryptographic Merkle tree commitments with peer consensus verification. Reported savings are scenario-dependent (chain size, filter usage, peer set); treat order-of-magnitude comparisons as illustrations, not guarantees.

Architecture

Core Components

1. Merkle Tree: Sparse Merkle Tree for incremental UTXO set updates
2. Peer Consensus: N-of-M diverse peer verification model
3. Spam Filtering: Filters spam transactions from commitments
4. Verification: PoW-based commitment verification
5. Network Integration: Works with TCP and Iroh transports

Merkle Tree Implementation

Sparse Merkle Tree

The system uses a sparse Merkle tree for efficient incremental updates:

• Incremental Updates: Insert/remove UTXOs without full tree rebuild
• Proof Generation: Generate Merkle proofs for UTXO inclusion
• Root Calculation: Efficient root hash calculation
• SHA256 Hashing: Uses SHA256 for all hashing operations

Usage

#![allow(unused)]
fn main() {
use blvm_protocol::utxo_commitments::{UtxoMerkleTree, UtxoCommitment};
use blvm_consensus::types::{OutPoint, UTXO};

// Create UTXO Merkle tree
let mut tree = UtxoMerkleTree::new()?;

// Add UTXO
let outpoint = OutPoint { hash: [1; 32], index: 0 };
let utxo = UTXO { value: 1000, script_pubkey: vec![].into(), height: 0, is_coinbase: false };
tree.insert(outpoint, utxo)?;

// Generate commitment
let commitment = tree.generate_commitment(block_hash, height);
}

Peer Consensus Protocol

N-of-M Verification Model

The peer consensus protocol discovers diverse peers and finds consensus among them to verify UTXO commitments without trusting any single peer.

Peer Diversity

Peers are selected for diversity across:

• ASN (Autonomous System Number): Maximum 2 peers per ASN
• Country: Geographic distribution
• Subnet: /16 subnet distribution
• Implementation: Different Bitcoin implementations may adopt commitment schemes independently

Consensus Configuration

#![allow(unused)]
fn main() {
pub struct ConsensusConfig {
 pub min_peers: usize, // Minimum: 5
 pub target_peers: usize, // Target: 10
 pub consensus_threshold: f64, // 0.8 (80% agreement)
 pub max_peers_per_asn: usize, // 2
 pub safety_margin: Natural, // 2016 blocks (~2 weeks)
}
}

Consensus Process

1. Discover Diverse Peers: Find peers across different ASNs, countries, subnets
2. Request Commitments: Query each peer for UTXO commitment at checkpoint height
3. Group Responses: Group commitments by value (merkle root + supply + count + height)
4. Find Consensus: Identify group with highest agreement
5. Verify Threshold: Check if agreement meets consensus threshold (80%)
6. Verify Commitment: Verify consensus commitment against block headers and PoW

Fast Sync Protocol

Initial Sync Process

1. Download Headers: Download block headers from genesis to tip
2. Select Checkpoint: Choose checkpoint height (safety margin back from tip)
3. Request UTXO Sets: Query diverse peers for UTXO commitment at checkpoint
4. Find Consensus: Use peer consensus to verify commitment
5. Verify Commitment: Verify against block headers and PoW
6. Sync Forward: Download filtered blocks from checkpoint to tip
7. Update Incrementally: Update UTXO set incrementally for each block

Bandwidth savings

Fast sync downloads far less data than replaying every full block for all heights, headers plus filtered or incremental payloads instead of full blocks at each height. Actual volume and ratios depend on tip height, peer behavior, and configuration; measure on your deployment.

Conceptually:

• Headers only vs full blocks per height reduces volume dramatically
• Filtered blocks and incremental updates avoid re-downloading the entire chain as raw blocks
• At comparable tips, a naïve full-block archive can be orders of magnitude larger than a headers + filters + incremental path

Spam Filtering Integration

UTXO Commitments use spam filtering to reduce bandwidth during sync. Spam filtering is a general-purpose feature that can be used independently of UTXO commitments.

For detailed spam filtering documentation, see: Spam Filtering

Integration with UTXO Commitments

When processing blocks for UTXO commitments, spam filtering is applied:

• Location: initial_sync.rs
• Process: All transactions are processed, but spam outputs are filtered out
• Benefit: Additional bandwidth reduction during ongoing sync in some configurations
• Critical Design: INPUTS are always removed (maintains UTXO consistency), OUTPUTS are filtered (bandwidth savings)

Effect on bandwidth (spam filtering)

• Maintains consensus correctness
• Enables efficient UTXO commitment synchronization

BIP158 Compact Block Filters

BIP158 compact block filters support light clients and integrate with UTXO commitments for efficient filtered block serving.

Location

• Protocol (algorithm): blvm-protocol/src/bip158.rs, blvm-protocol/src/bip157.rs: GCS filter construction and filter header chain
• Node (handlers): blvm-node/src/network/bip157_handler.rs, blvm-node/src/network/filter_service.rs: serving and network integration

Capabilities

Filter Generation

• Golomb-Rice Coded Sets (GCS) for efficient encoding
• False Positive Rate: ~1 in 524,288 (P=19)
• Filter Contents:

1. All spendable output scriptPubKeys in the block
2. All scriptPubKeys from outputs spent by block's inputs

Filter Header Chain

• Maintains filter header chain for efficient verification
• Checkpoints every 1000 blocks (per BIP157)
• Enables light clients to verify filter integrity

Algorithm

1. Collect Scripts: All output scriptPubKeys from block transactions and all scriptPubKeys from UTXOs being spent
2. Hash to Range: Hash each script with SHA256, map to range [0, N*M) where N = number of elements, M = 2^19
3. Golomb-Rice Encoding: Sort hashed values, compute differences, encode using Golomb-Rice
4. Filter Matching: Light clients hash their scripts and check if script hash is in set

Integration with UTXO Commitments

BIP158 filters can be included in FilteredBlockMessage alongside spam-filtered transactions and UTXO commitments, enabling efficient light client synchronization.

Verification

Verification Levels

1. Minimal: Peer consensus only
2. Standard: Peer consensus + PoW + supply checks
3. Paranoid: All checks + background genesis verification

Verification Checks

• PoW Verification: Verify block headers have valid proof-of-work
• Supply Verification: Verify total supply matches expected value
• Header Chain Verification: Verify commitment height matches header chain
• Merkle Root Verification: Verify Merkle root matches UTXO set

Network Integration

Transport Support

UTXO Commitments work with both TCP and Iroh transports via the transport abstraction layer:

• TCP: Bitcoin P2P compatible
• Iroh/QUIC: QUIC with NAT traversal and DERP

Network Messages

• GetUTXOSet: Request UTXO commitment from peer
• UTXOSet: Response with UTXO commitment
• GetFilteredBlock: Request filtered block (spam-filtered)
• FilteredBlock: Response with filtered block

Configuration

Sync Modes

• PeerConsensus: Use peer consensus for initial sync (fast, trusts N of M peers)
• Genesis: Sync from genesis (slow, but no trust required)
• Hybrid: Use peer consensus but verify from genesis in background

Configuration Example

``toml [utxo_commitments] sync_mode = "PeerConsensus" # or "Genesis" or "Hybrid" verification_level = "Standard" # or "Minimal" or "Paranoid"

[utxo_commitments.consensus] min_peers = 5 target_peers = 10 consensus_threshold = 0.8 max_peers_per_asn = 2 safety_margin = 2016

[utxo_commitments.spam_filter] min_value = 546 # dust threshold min_fee_rate = 1 # sat/vB ``

Formal Verification

The UTXO Commitments module includes blvm-spec-lock proofs verifying:

• Merkle tree operations (insert, remove, root calculation)
• Commitment generation
• Verification logic
• Peer consensus calculations

Storage correctness for UTXO set operations is covered by tests and blvm-spec-lock verification in the consensus and protocol crates. The UTXO commitments implementation in blvm-protocol (merkle tree, verification, peer consensus) is the reference for commitment-related logic.

Usage

Initial Sync

#![allow(unused)]
fn main() {
use blvm_protocol::utxo_commitments::InitialSync;

let sync = InitialSync::new(
 peer_consensus,
 network_client,
 config,
);

// Sync from checkpoint
let commitment = sync.sync_from_checkpoint(
 header_chain,
 diverse_peers,
).await?;

// Complete sync forward with full validation
// Note: checkpoint_utxo_set should be obtained from the verified commitment
// For now, passing None starts with empty set (commitment verified at checkpoint)
sync.complete_sync_from_checkpoint(
 &mut utxo_tree,
 checkpoint_height,
 current_tip,
 network_client,
 get_block_hash_fn,
 peer_id,
 Network::Mainnet,
 network_time,
 Some(&header_chain),
 None, // checkpoint_utxo_set - can be obtained separately if needed
).await?;
}

Update After Block

#![allow(unused)]
fn main() {
use blvm_protocol::utxo_commitments::update_commitments_after_block;

update_commitments_after_block(
 &mut utxo_tree,
 block,
 height,
)?;
}

Benefits

1. Fast sync: Substantially less data than naïve full-block replay (see Bandwidth savings)
2. Security: N-of-M peer consensus prevents single peer attacks
3. Efficiency: Incremental updates, no full set download
4. Flexibility: Multiple sync modes and verification levels
5. Transport Agnostic: Works with TCP or QUIC
6. Formal Verification: blvm-spec-lock proofs ensure correctness

Components

The UTXO Commitments system includes:

• Sparse Merkle Tree with incremental updates
• Peer consensus protocol (N-of-M verification)
• Spam filtering
• Commitment verification
• Network integration (TCP and Iroh)
• Fast sync protocol
• blvm-spec-lock proofs