Modules Overview

Introduction

BLVM node uses a modular architecture where optional features run as separate, process-isolated modules. This extends node functionality without affecting consensus or base node stability.

Available Modules

The following modules are available for blvm-node:

Core Modules

  • Lightning Network Module - Lightning Network payment processing with multiple provider support (LNBits, LDK, Stub), invoice verification, and payment state tracking
  • Commons Mesh Module - Payment-gated mesh overlay with route discovery, payment proofs, and subprocess ModuleAPI
  • Stratum V2 Module - Stratum V2 mining protocol support with network integration complete and mining pool management
  • Datum Module - DATUM Gateway mining protocol module for Ocean pool integration (works with Stratum V2)
  • Mining OS Module - Operating system-level mining optimizations and hardware management
  • Selective Sync Module — Configurable IBD sync policy (e.g. skip flagged transaction content during IBD); blvm sync-policy … CLI when the module is loaded

Module System Architecture

All modules run in separate processes with IPC communication (see Module System Architecture for details), providing:

  • Process Isolation: Each module runs in isolated memory space
  • Crash Containment: Module failures don't affect the base node
  • Consensus Isolation: Modules cannot modify consensus rules or UTXO set
  • Security: Modules communicate only through well-defined APIs

For detailed information about the module system architecture, see Module System.

Installing Modules

Modules can be installed in several ways:

Via Cargo

cargo install blvm-lightning
cargo install blvm-mesh
cargo install blvm-stratum-v2
cargo install blvm-datum
cargo install blvm-miningos
cargo install blvm-selective-sync

Via Module Installer

cargo install cargo-blvm-module
cargo blvm-module install blvm-lightning
cargo blvm-module install blvm-mesh
cargo blvm-module install blvm-stratum-v2
cargo blvm-module install blvm-datum
cargo blvm-module install blvm-miningos
cargo blvm-module install blvm-selective-sync

Manual Installation

  1. Build the module: cargo build --release
  2. Copy the binary to modules/<module-name>/target/release/
  3. Create module.toml manifest in the module directory
  4. Restart the node or use runtime module loading

Module Configuration

Each module requires a config.toml file in its module directory where applicable. See individual module documentation (Lightning, Mesh, Stratum V2, Datum, Mining OS, Selective Sync). For blvm-mesh submodules, see the Mesh Module documentation.

Module Lifecycle

Modules can be:

  • Loaded at node startup (if enabled in configuration)
  • Loaded at runtime via RPC or module manager API
  • Unloaded at runtime without affecting the base node
  • Reloaded (hot reload) for configuration updates

WASM modules (wasm-modules)

When the node loads WebAssembly modules (wasm-modules / blvm-sdk embedding), treat guests as trusted only if your governance policy says so. The embedder uses wasmtime fuel and store limits (memory / instance counts) with conservative defaults; operators can override per module via [modules.<name>] keys documented in blvm-node/docs/CONFIGURATION_GUIDE.md. Third-party or internet-exposed WASM should use explicitly reviewed budgets (see workspace hardening plan Track C).

See Also