Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Lightning Network Module

Overview

The Lightning Network module (blvm-lightning) handles Lightning Network payment processing for blvm-node: invoice verification, payment routing, channel management, and payment state tracking. For information on developing custom modules, see Module Development.

Features

  • Invoice Verification: Validates Lightning Network invoices (BOLT11) using multiple provider backends
  • Payment Processing: Processes Lightning payments via LNBits API or LDK
  • Provider Abstraction: Supports multiple Lightning providers (LNBits, LDK, Stub) with unified interface
  • Payment State Tracking: Monitors payment lifecycle from request to settlement

Installation

Via Cargo

cargo install blvm-lightning

Via Module Installer

cargo install cargo-blvm-module
cargo blvm-module install blvm-lightning

Manual Installation

  1. Clone the repository:

    git clone https://github.com/BTCDecoded/blvm-lightning.git
cd blvm-lightning

  2. Build the module:

    cargo build --release

  3. Install to node modules directory:

    mkdir -p /path/to/node/modules/blvm-lightning/target/release
cp target/release/blvm-lightning /path/to/node/modules/blvm-lightning/target/release/

Configuration

The module supports multiple Lightning providers. Create a config.toml file in the module directory:

[lightning]
provider = "lnbits"

[lightning.lnbits]
api_url = "https://lnbits.example.com"
api_key = "your_lnbits_api_key"
wallet_id = "optional_wallet_id"  # Optional

LDK Provider (Rust-native)

[lightning]
provider = "ldk"

[lightning.ldk]
data_dir = "data/ldk"
network = "testnet"  # or "mainnet" or "regtest"
node_private_key = "hex_encoded_private_key"  # Optional, will generate if not provided

Stub Provider (Testing)

[lightning]
provider = "stub"

Configuration Options

  • provider (required): Lightning provider to use ("lnbits", "ldk", or "stub")
  • LNBits: api_url, api_key, wallet_id (optional)
  • LDK: data_dir, network, node_private_key (optional)
  • Stub: No additional configuration needed

Provider Comparison

FeatureLNBitsLDKStub
Status✅ Production-ready✅ Fully implemented✅ Testing
API TypeREST (HTTP)Rust-native (lightning-invoice)None
Real Lightning✅ Yes✅ Yes❌ No
External Service✅ Yes❌ No❌ No
Invoice Creation✅ Via API✅ Native✅ Mock
Payment Verification✅ Via API✅ Native✅ Mock
Best ForPayment processingFull control, Rust-nativeTesting

Switching Providers: All providers implement the same interface, so switching providers is just a configuration change. No code changes required.

Module Manifest

The module includes a module.toml manifest (see Module Development):

name = "blvm-lightning"
version = "0.1.0"
description = "Lightning Network payment processor"
author = "Bitcoin Commons Team"
entry_point = "blvm-lightning"

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

Events

Subscribed Events

The module subscribes to the following node events:

  • PaymentRequestCreated - New payment request created
  • PaymentSettled - Payment confirmed on-chain
  • PaymentFailed - Payment failed

Published Events

The module publishes the following events:

  • PaymentVerified - Lightning payment verified
  • PaymentRouteFound - Payment route discovered
  • PaymentRouteFailed - Payment routing failed
  • ChannelOpened - Lightning channel opened
  • ChannelClosed - Lightning channel closed

Usage

Once installed and configured, the module automatically:

  1. Subscribes to payment-related events from the node (PaymentRequestCreated, PaymentSettled, PaymentFailed)
  2. Verifies Lightning invoices (BOLT11) when payment requests are created
  3. Processes payments using the configured provider (LNBits, LDK, or Stub)
  4. Publishes payment verification and status events (PaymentVerified, PaymentRouteFound, PaymentRouteFailed)
  5. Monitors payment lifecycle and publishes status events

The module automatically selects the provider based on configuration. All providers implement the same interface, so switching providers requires only a configuration change.

Provider Selection

The module uses the LightningProcessor to handle payment processing. The processor:

  • Reads provider configuration from lightning.provider
  • Creates the appropriate provider instance (LNBits, LDK, or Stub)
  • Routes all payment operations through the provider interface
  • Stores provider configuration in module storage for persistence

Batch Payment Verification

The module supports batch payment verification for improved performance when processing multiple payments:

#![allow(unused)]
fn main() {
use blvm_lightning::processor::LightningProcessor;

// Verify multiple payments in parallel
let payments = vec![
    ("invoice1", "payment_id_1"),
    ("invoice2", "payment_id_2"),
    ("invoice3", "payment_id_3"),
];

let results = processor.verify_payments_batch(&payments).await?;
// Returns Vec<bool> with verification results in same order as inputs
}

Batch verification processes all payments concurrently, significantly improving throughput for high-volume payment processing scenarios.

API Integration

The module integrates with the node via ModuleClient and NodeApiIpc:

  • Read-only blockchain access: Queries blockchain data for payment verification
  • Event subscription: Receives real-time events from the node
  • Event publication: Publishes Lightning-specific events
  • Module storage: Stores provider configuration and channel statistics in module storage tree lightning_config

Storage Usage

The module uses module storage to persist configuration and statistics:

  • provider_type: Current provider type (lnbits, ldk, stub)
  • channel_count: Number of active Lightning channels
  • total_capacity_sats: Total channel capacity in satoshis

Troubleshooting

Module Not Loading

  • Verify the module binary exists at the correct path
  • Check module.toml manifest is present and valid
  • Verify module has required capabilities
  • Check node logs for module loading errors

Payment Verification Failing

  • LNBits Provider: Verify API URL and API key are correct, check LNBits service is accessible
  • LDK Provider: Verify data directory permissions, check network configuration (mainnet/testnet/regtest)
  • General: Verify module has read_blockchain capability, check node logs for detailed error messages

Provider-Specific Issues

  • LNBits: Check API endpoint is accessible, verify wallet_id if specified, check API rate limits
  • LDK: Verify data directory exists and is writable, check network matches node configuration
  • Stub: No real verification - only for testing

Repository

See Also