CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a Bitcoin Lightning Network regtest environment for local development and testing. It provides a Docker Compose setup with multiple interconnected Lightning nodes (LND, Core Lightning, Eclair), Bitcoin Core, Elements/Liquid sidechain, and supporting services like LNbits, Boltz, and Electrs.

Common Commands

Start the Environment

./start-regtest          # Start all services and run initialization tests
source docker-scripts.sh # Load helper functions for CLI access

Stop the Environment

source docker-scripts.sh
lnbits-regtest-stop      # Stops containers and cleans up node data

CLI Helpers (after sourcing docker-scripts.sh)

bitcoin-cli-sim -generate 1              # Mine blocks
lightning-cli-sim 1 getinfo              # CLN node 1 (use 1, 2, or 3)
lncli-sim 1 getinfo                      # LND node 1 (use 1, 2, 3, or 4)
elements-cli-sim getinfo                 # Elements/Liquid
boltzcli-sim getinfo                     # Boltz client

View Logs

docker logs lnbits-lnbits-1 -f
docker logs lnbits-lnd-1-1 -f
docker logs lnbits-clightning-1-1 -f
docker logs lnbits-boltz-1 -f

Architecture

Lightning Network Topology

lnd-1: Hub node with channels to all other nodes. Used for local LNbits testing
lnd-2: Used for Boltz backend swaps
lnd-3: Backend for the dockerized LNbits instance
lnd-4: Standalone node
cln-1, cln-2, cln-3: Core Lightning nodes. cln-2 has REST API via clightning-2-rest
eclair-1: Eclair node with channels from lnd-1 and lnd-2

Channel Graph

lnd-1 is the central hub connected to: lnd-2, lnd-3, cln-1, cln-2, cln-3, eclair-1. Additional connections: lnd-2→cln-2, lnd-3→cln-3, lnd-3→cln-1, lnd-2→eclair-1

Supporting Services

bitcoind: Regtest Bitcoin Core (RPC on 18443)
elementsd: Liquid regtest sidechain (RPC on 18884)
electrs: Bitcoin Electrum server (ports 19001, 3002)
electrs-liquid: Liquid Electrum server (ports 19002, 3003)
boltz + boltz-client: Swap service with Postgres backend
lnbits: Lightning wallet/app platform (port 5001)
litd: Lightning Terminal connected to lnd-1 (ports 8443, 8080)
fava: Beancount accounting interface (port 3333)

Web Interfaces

LNbits: http://localhost:5001/
Mempool (via electrs): http://localhost:3002/
Boltz API: http://localhost:9001/
Lightning Terminal: https://localhost:8443/ (password: testpassword123)
Fava: http://localhost:3333/
Eclair API: http://localhost:8082/ (password: lnbits)

Configuration for Local LNbits Development

When running LNbits locally against this regtest:

# LND backend
LNBITS_BACKEND_WALLET_CLASS="LndRestWallet"
LND_REST_ENDPOINT=https://127.0.0.1:8081/
LND_REST_CERT=./docker/data/lnd-1/tls.cert
LND_REST_MACAROON=./docker/data/lnd-1/data/chain/bitcoin/regtest/admin.macaroon

# Or CLN backend
LNBITS_BACKEND_WALLET_CLASS="CoreLightningWallet"
CORELIGHTNING_RPC=./docker/data/clightning-1/regtest/lightning-rpc

Data Persistence

Node data stored in ./data/<service-name>/
lnbits-regtest-stop cleans up Lightning node directories but preserves config files
Bitcoin/Elements data uses Docker volumes (cleaned on stop)

3.3 KiB Raw Permalink Blame History