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>
96 lines
5.3 KiB
Markdown
96 lines
5.3 KiB
Markdown
# 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](../../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`, not `docker-compose`)
|
|
- `curl` and `python3`, which `regtest.sh` uses to call the nodes and read their answers
|
|
- About 800 MB for the images, which the first `up` downloads: `bitcoin/bitcoin:31.1`,
|
|
`getumbrel/electrs:v0.11.1` and `acinq/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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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 in
|
|
`composeApp/build/test-results/jvmTest/TEST-com.machankura.bennu.compose.managers.GroupLightningRegtestJvmTest.xml`,
|
|
under `<system-out>`: the `REGTEST …` 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 logs` shows almost nothing for eclair, which writes to a file in its
|
|
data directory:
|
|
|
|
```bash
|
|
docker compose exec lsp tail -n 200 /data/eclair.log
|
|
```
|
|
|
|
Use `payer` in place of `lsp` for the payer's.
|
|
- **bitcoind and electrs** log to the console: `docker compose logs bitcoind` or `docker 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 |
|