testing/regtest/README.md now covers the prerequisites and ports, where the run's output and eclair's log end up, and a troubleshooting table. The docs index and CLAUDE.md's "Checking your work" link to it. The test checks the network before it starts. If a service isn't listening, or `regtest.sh up` didn't finish, it fails at once, names what is missing and says how to start it. Before, that was a bare connection error or a three-minute timeout. BENNU_REGTEST is now an input of the test task. Before, a skipped run left jvmTest up to date, and asking for the regtest run afterwards replayed the skip without running anything. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.3 KiB
Regtest network for the group Lightning wallet
A Bitcoin regtest network on one machine, for GroupLightningRegtestJvmTest: four devices open a
group Lightning wallet, receive, pay, close and sweep against a real lightning-kmp node and an eclair
LSP. What the run checks, what it found, and why each LSP setting is there is in
docs/group-lightning-wallet.md, "The regtest run".
The run is not part of ./gradlew check or CI. Without BENNU_REGTEST=1 the test is reported as
skipped, so a green jvmTest says nothing about it.
Prerequisites
- Docker with the Compose v2 plugin (
docker compose, notdocker-compose) curlandpython3, whichregtest.shuses to call the nodes and read their answers- About 800 MB for the images, which the first
updownloads:bitcoin/bitcoin:31.1,getumbrel/electrs:v0.11.1andacinq/eclair:v0.14.4. eclair 0.14.4 refuses a Bitcoin Core older than 31. - These localhost ports free:
| port | what |
|---|---|
| 28443 | bitcoind RPC (foo / bar) |
| 28001 | electrs, Electrum protocol, no TLS |
| 29735 | the LSP's Lightning port, which the group's node connects to |
| 28080 | the LSP's API (password lsp) |
| 28081 | the payer's API (password payer) |
Nothing listens on any other interface, and the compose project is named bennu-regtest, so it sits
beside other stacks without touching them.
Running it
From this directory:
./regtest.sh up
up starts bitcoind, makes three wallets (a miner, the LSP's, the payer's) and funds two of them,
starts electrs and both eclair nodes, and opens a 5,000,000-sat channel from the payer to the LSP. It
finishes by printing the LSP's node id. Allow a minute the first time, after the downloads.
From the repository root:
BENNU_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest'
It takes about thirty seconds. It can be run again on the same network as often as you like. Each run makes a new Lightning wallet with a new node. The group's onchain key is fixed in the test fixture, though, so its first address collects coins across runs; the checks compare balances before and after.
When you are done:
./regtest.sh down
down removes the containers, bitcoind's volume and the network. The images stay cached.
To reach each piece by hand: ./regtest.sh mine 6, ./regtest.sh btc <rpc> [args],
./regtest.sh lsp <method> -d key=value and ./regtest.sh payer <method> -d key=value. The last two
call eclair's API, for example ./regtest.sh lsp channels or ./regtest.sh payer usablebalances.
Where the output goes
-
The run's own lines and the node's log. With Gradle's
-q, or whenever the test passes, nothing reaches the console. Everything the test printed is incomposeApp/build/test-results/jvmTest/TEST-com.machankura.bennu.compose.managers.GroupLightningRegtestJvmTest.xml, under<system-out>: theREGTEST …progress lines, lightning-kmp's log (fr.acinq.lightning.*), and the app's managers (GroupLightningNode,GroupLightningCoSigner,FrostSigningManager). The HTML report beside it,composeApp/build/reports/tests/jvmTest/index.html, shows the same. -
eclair's log.
docker compose logsshows almost nothing for eclair, which writes to a file in its data directory:docker compose exec lsp tail -n 200 /data/eclair.logUse
payerin place oflspfor the payer's. -
bitcoind and electrs log to the console:
docker compose logs bitcoindordocker compose logs electrs.
Troubleshooting
| what you see | what it means |
|---|---|
| the test is reported as skipped | BENNU_REGTEST=1 was not set in the environment Gradle runs the test in |
The regtest network is not running: nothing answers for … on 127.0.0.1:… |
that service is down. Run ./regtest.sh up, or check it with docker compose ps -a and its logs |
the payer has no open channel to the LSP |
up stopped part way through. Run ./regtest.sh down, then up again |
up prints timed out waiting for: … |
a container exited: docker compose ps -a shows which, and its log says why |
timed out waiting for … from the test |
it lists the round-one label assignments and pool counts first (REGTEST assigned … and REGTEST pool … in the report). A pool counter with fewer than three rows is a co-signer that never answered. Otherwise look for Error( and Warn: lines in the node's log and for WARN in the LSP's |
Error(… data=…) in the node's log |
an error message from the LSP or to it. Its data is text in hex: python3 -c "print(bytes.fromhex('<hex>').decode())" reads it |
the payment failed: … route not found |
the LSP has no usable route to the payer. Check ./regtest.sh lsp usablebalances and ./regtest.sh lsp allupdates: an update with htlcMaximumMsat of 1 means eclair's balance thresholds were on when the channel opened (lsp.conf turns them off; ./regtest.sh lsp updaterelayfee -d nodeIds=<payer> -d feeBaseMsat=1000 -d feeProportionalMillionths=100 refreshes one) |
| a port is already in use | another stack has it. Change the host side of that port in compose.yml, and the matching port in GroupLightningRegtestJvmTest |
the LSP refuses to start: requires Bitcoin Core 31 or higher |
compose.yml was changed to an older bitcoind image |