Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@
- [Commons Mesh](modules/mesh.md)
- [Stratum V2](modules/stratum-v2.md)
- [Datum](modules/datum.md)
- [Mining OS](modules/miningos.md)
- [Selective Sync](modules/selective-sync.md)
- [FIBRE](modules/fibre.md)
- [ZMQ](modules/zmq.md)
Expand Down
2 changes: 2 additions & 0 deletions src/modules/datum.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Datum Module

> **Registry status:** Not listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json). `[modules]` registry bootstrap cannot download `blvm-datum`; [build it from source](overview.md#build-from-source) and place it under `modules_dir`.

## Overview

The Datum module (`blvm-datum`) implements the DATUM Gateway mining protocol for Ocean pool support. Pool communication runs here; miners connect through `blvm-stratum-v2`.
Expand Down
2 changes: 2 additions & 0 deletions src/modules/fibre.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# FIBRE module (`blvm-fibre`)

> **Registry status:** Listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json) as `blvm-fibre`. Pin it under `[modules]` for [registry bootstrap](overview.md#registry-bootstrap-recommended).

UDP/FEC **block** relay as a **loadable Commons module**. Distinct from Dandelion++ transaction relay in [Privacy relay](../node/privacy-relay.md).

## Overview
Expand Down
2 changes: 2 additions & 0 deletions src/modules/governance-module.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Governance module (`blvm-governance`)

> **Registry status:** Listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json) as `blvm-governance`. Pin it under `[modules]` for [registry bootstrap](overview.md#registry-bootstrap-recommended).

On-chain proposal tracking and optional webhook notifications for **`blvm-node`**. Distinct from the **Bitcoin Commons governance framework** documented under [Governance](../governance/overview.md): this page covers the **loadable module** only.

## Overview
Expand Down
2 changes: 2 additions & 0 deletions src/modules/lightning.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Lightning Network Module

> **Registry status:** Not listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json). `[modules]` registry bootstrap cannot download `blvm-lightning`; [build it from source](overview.md#build-from-source) and place it under `modules_dir`.

## Overview

The Lightning Network module (`blvm-lightning`) handles invoice verification, payment routing, channel management, and payment state tracking for blvm-node.
Expand Down
2 changes: 2 additions & 0 deletions src/modules/marketplace-module.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Marketplace module (`blvm-marketplace`)

> **Registry status:** Listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json) as `blvm-marketplace`. Pin it under `[modules]` for [registry bootstrap](overview.md#registry-bootstrap-recommended).

Optional **module discovery, registry, and payment** integration for **`blvm-node`**. Most operators use **`[modules].registry_url`** bootstrap (GitHub Releases + `modules.json`) without loading this module.

## Overview
Expand Down
2 changes: 2 additions & 0 deletions src/modules/mesh.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Commons Mesh Module

> **Registry status:** Not listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json). `[modules]` registry bootstrap cannot download `blvm-mesh`; [build it from source](overview.md#build-from-source) and place it under `modules_dir`.

Payment-gated mesh overlay for **blvm-node**: route discovery, replay prevention, optional payment proofs, and subprocess ModuleAPI. Wire format and smoke tests live in the [blvm-mesh](https://github.com/BTCDecoded/blvm-mesh) repo ([mesh transport](https://github.com/BTCDecoded/blvm-mesh/blob/main/docs/TRANSPORT.md), [mesh API](https://github.com/BTCDecoded/blvm-mesh/blob/main/API.md)).

## Install
Expand Down
2 changes: 2 additions & 0 deletions src/modules/miningos.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Mining OS Module

> **Registry status:** Not listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json). `[modules]` registry bootstrap cannot download `blvm-miningos`; [build it from source](overview.md#build-from-source) and place it under `modules_dir`.

## Overview

The Mining OS module (`blvm-miningos`) integrates BLVM with MiningOS (Mos): BLVM runs as a MiningOS "rack" (worker) and exposes miners as "things".
Expand Down
2 changes: 2 additions & 0 deletions src/modules/miniscript.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Miniscript module (`blvm-miniscript`)

> **Registry status:** Listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json) as `blvm-miniscript`. Pin it under `[modules]` for [registry bootstrap](overview.md#registry-bootstrap-recommended).

Descriptor and PSBT helpers for **`blvm-node`**. Overrides two core JSON-RPC methods via the module RPC extender when loaded.

## Overview
Expand Down
21 changes: 12 additions & 9 deletions src/modules/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,25 @@ BLVM node runs optional features as separate, process-isolated modules. See [Bui

## Available modules

**Core integration modules** (documented in this book):
Registry status comes from [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json) in the `blvm` repository. Each module page repeats it in a **Registry status** line.

- **[Lightning Network Module](lightning.md)**: Lightning payment processing (LNBits, LDK, Stub)
- **[Commons Mesh Module](mesh.md)**: Payment-gated mesh overlay; four JSON-RPC methods when loaded
- **[Stratum V2 Module](stratum-v2.md)**: Stratum V2 mining protocol
- **[Datum Module](datum.md)**: DATUM Gateway (with Stratum V2)
- **[Selective Sync Module](selective-sync.md)**: IBD sync policy and witness filtering

**Registry modules** (bootstrap from `registry/modules.json`):
**In the registry** (bootstrap via `[modules].registry_url`):

- **blvm-zmq**: ZMQ PUB notifications ([ZMQ module](zmq.md))
- **blvm-miniscript**: Descriptor / PSBT RPC overrides ([Miniscript module](miniscript.md))
- **blvm-governance**: On-chain proposal webhook module ([Governance module](governance-module.md))
- **blvm-marketplace**: Optional registry/payments ([Marketplace module](marketplace-module.md))
- **blvm-fibre**: FIBRE UDP/FEC block relay ([FIBRE module](fibre.md))

**Not in the registry** (build from source; registry bootstrap cannot download these):

- **blvm-lightning**: Lightning payment processing (LNBits, LDK, Stub) ([Lightning Network Module](lightning.md))
- **blvm-mesh**: Payment-gated mesh overlay; four JSON-RPC methods when loaded ([Commons Mesh Module](mesh.md))
- **blvm-stratum-v2**: Stratum V2 mining protocol ([Stratum V2 Module](stratum-v2.md))
- **blvm-datum**: DATUM Gateway (with Stratum V2) ([Datum Module](datum.md))
- **blvm-selective-sync**: IBD sync policy and witness filtering ([Selective Sync Module](selective-sync.md))
- **blvm-miningos**: MiningOS rack integration ([Mining OS Module](miningos.md))

## Module system architecture

```mermaid
Expand Down Expand Up @@ -49,8 +52,8 @@ Pin modules in `blvm.toml` under **`[modules]`** (merge into your existing file:
```toml
[modules]
registry_url = "https://raw.githubusercontent.com/BTCDecoded/blvm/main/registry/modules.json"
blvm-mesh = "0.1.*"
blvm-zmq = "0.1.*"
blvm-miniscript = "0.1.*"
```

The node downloads version-pinned binaries from GitHub Releases (`sha256sums.txt` on each tag) when a pinned module is missing on disk. See [blvm README](https://github.com/BTCDecoded/blvm/blob/main/README.md) in the `blvm` repository for the full bootstrap contract.
Expand Down
2 changes: 2 additions & 0 deletions src/modules/selective-sync.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Selective Synchronization Module

> **Registry status:** Not listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json). `[modules]` registry bootstrap cannot download `blvm-selective-sync`; [build it from source](overview.md#build-from-source) and place it under `modules_dir`.

The **blvm-selective-sync** module provides a configurable **sync policy**: operators can avoid serving or persisting certain flagged transaction content during IBD while keeping full cryptographic validation of the chain.

## Requirements
Expand Down
2 changes: 2 additions & 0 deletions src/modules/stratum-v2.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# Stratum V2 Module

> **Registry status:** Not listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json). `[modules]` registry bootstrap cannot download `blvm-stratum-v2`; [build it from source](overview.md#build-from-source) and place it under `modules_dir`.

## Overview

The Stratum V2 module (`blvm-stratum-v2`) implements [Stratum V2 mining protocol](../node/mining-stratum-v2.md) support: server, pool management, and job distribution.
Expand Down
2 changes: 2 additions & 0 deletions src/modules/zmq.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# ZMQ module (`blvm-zmq`)

> **Registry status:** Listed in [`registry/modules.json`](https://github.com/BTCDecoded/blvm/blob/main/registry/modules.json) as `blvm-zmq`. Pin it under `[modules]` for [registry bootstrap](overview.md#registry-bootstrap-recommended).

Bitcoin-compatible **ZeroMQ PUB** notifications for blocks and mempool events. Replaces the former in-process **`[zmq]`** section on `blvm-node`: configure endpoints on this module instead.

## Overview
Expand Down