101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
# Lightning regtest (NixOS-native)
|
|
|
|
A reproducible, hermetic Lightning regtest stack — `bitcoind(regtest)` +
|
|
Core Lightning + LND in one VM — replacing the core of the docker
|
|
`legend-regtest-enviroment` (aiolabs/omnixient#27). No docker, no host state;
|
|
the whole thing is a NixOS VM built from the bitcoin pack's nix-bitcoin
|
|
modules.
|
|
|
|
There are **two ways to use it**, sharing one node definition
|
|
(`tests/regtest-node.nix`) so they can't drift:
|
|
|
|
| Mode | Command | For |
|
|
|---|---|---|
|
|
| **CI test** | `nix build .#checks.x86_64-linux.regtest-core -L` | automated pass/fail (fund → channel → pay → settle) |
|
|
| **Interactive dev VM** | `nix run .#regtest` | poking the nodes by hand in a real shell |
|
|
|
|
## Interactive dev VM — `nix run .#regtest`
|
|
|
|
The friendly path. Boots the stack headless and drops you straight into
|
|
an SSH shell as the `operator` user — real terminal, copy/paste,
|
|
scrollback, no log spam:
|
|
|
|
```bash
|
|
nix run .#regtest
|
|
```
|
|
|
|
You land in the VM with:
|
|
|
|
- **user** `operator`, **password** `password` (also `sudo`) — a throwaway
|
|
local VM with fake coins, so the trivial password is fine. Your
|
|
`settings.sshKeys` are accepted too, if set.
|
|
- **aliases**: `btc` → `bitcoin-cli -rpcwallet=test`, `cln` →
|
|
`lightning-cli`; `lncli` is the LND CLI as-is. (Plain `bitcoin-cli`
|
|
works too — the single `test` wallet auto-selects.)
|
|
- **helper**: `regtest-fund` — funds LND on-chain and opens an LND→CLN
|
|
channel, so you start with a working channel instead of building it by
|
|
hand.
|
|
- **nodes**: `bitcoind` (regtest), Core Lightning p2p `:9735`, LND p2p
|
|
`:9736`. The chain pre-mines 110 blocks on boot (give it a few seconds).
|
|
|
|
`exit` shuts the VM down and discards it (ephemeral disk in a tmp file).
|
|
|
|
### A typical spin
|
|
|
|
```bash
|
|
regtest-fund # fund + open a channel
|
|
|
|
bolt11=$(cln invoice 50000000 demo demo | jq -r .bolt11)
|
|
lncli payinvoice --force "$bolt11" # LND pays CLN
|
|
cln listinvoices demo | jq '.invoices[0].status' # paid
|
|
|
|
lncli listchannels | jq '.channels[] | {local_balance, remote_balance}'
|
|
btc getblockcount
|
|
```
|
|
|
|
### How it boots
|
|
|
|
`nix run .#regtest` runs a small wrapper that:
|
|
1. boots `packages.regtest-vm` (a `system.build.vm`) headless, with an
|
|
ephemeral disk and `host:2222 → guest:22` forwarded;
|
|
2. waits for SSH, then `ssh operator@localhost`;
|
|
3. tears the VM down and cleans up the temp disk on exit.
|
|
|
|
## CI test — `regtest-core`
|
|
|
|
The automated assertion that the stack actually settles a payment:
|
|
|
|
```bash
|
|
nix build .#checks.x86_64-linux.regtest-core -L # ~60s; exit 0 = passed
|
|
nix flake check -L # runs it with the rest
|
|
```
|
|
|
|
It pre-mines the chain, funds LND, opens an LND→CLN channel, has CLN issue
|
|
an invoice, LND pays it, and asserts CLN sees it `paid`. To poke the test
|
|
node by hand instead, use the raw nixos-test driver:
|
|
|
|
```bash
|
|
nix build .#checks.x86_64-linux.regtest-core.driverInteractive
|
|
./result/bin/nixos-test-driver # Python REPL; regtest.succeed("…")
|
|
```
|
|
|
|
(The `nix run .#regtest` dev VM is the nicer interactive experience — the
|
|
driver REPL is awkward for ad-hoc use: `Ctrl-C` tears down the VM, the
|
|
QEMU window has no clipboard, and daemon logs flood the console.)
|
|
|
|
## Layout
|
|
|
|
- `tests/regtest-node.nix` — **shared** bitcoind + CLN + LND config (the
|
|
one source of truth). Consumers also import `nix-bitcoin.nixosModules.default`.
|
|
- `tests/regtest-core.nix` — the CI test; imports the shared node.
|
|
- `tests/regtest-interactive.nix` — the dev-VM layer (SSH, operator login,
|
|
aliases, `regtest-fund`, port forward); imports nothing about the test.
|
|
- `flake.nix` — wires `checks.regtest-core`, `packages.regtest-vm`, and
|
|
`apps.regtest`.
|
|
|
|
## Follow-up: `regtest-full`
|
|
|
|
This is the **core** tier (#27 tier 1). A `regtest-full` tier — adding
|
|
boltz / elements-liquid / litd / lnbits like the docker stack, and more
|
|
directions (CLN→LND, an eclair node) — is the documented follow-up on
|
|
aiolabs/omnixient#27.
|