docs: group Lightning liquidity is built, but for the LSP's own splices, and off (liquidity, Phase 10)

The plan's build table now says each phase's state. Phase 9, a splice the LSP starts to deliver a
payment, is left to the group as the plan left it. GroupLightningRollout.LIQUIDITY_ENABLED stays
off: the regtest run passed, but the mainnet half of Phase 0 -- ACINQ's LSP accepting a splice whose
funding key from us does not change, and its rates -- needs a purchase with real money. The group
Lightning wallet note's check 8 points here, as do the docs index and the regtest README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-11-01 12:47:24 +02:00
1 parent 94015fd3f8
commit 67351eeaa5
4 files changed
+15 -5

No files matched your search

+5 -2
View File
@@ -150,11 +150,14 @@ constraints and its decision table before any phase, its trust table before
arguing with either, and its two tables of what the build found before
changing anything it describes.
The group Lightning liquidity note is a phased plan that has not been built.
The group Lightning liquidity note is a phased plan that has been built, but for
its Phase 9, and is off until a purchase is made on mainnet.
It is the group Lightning wallet note's check 8 built for one kind of splice:
read that note's D6, Phase 9 and Phase 13 first, and the lightning
remediation README's step 2, which this plan waits for, then its six
constraints and eight decisions before any phase.
constraints and eight decisions before any phase, and its table of what
Phase 0 found against eclair before the code: the minute eclair allows a whole
splice is what every group signature in it has to fit inside.
The standalone-electrum note is a phased plan that has been built, and is the
group chain wallet note's *An identity without a node* answered: read that
+3 -1
View File
@@ -6,7 +6,7 @@ group's Lightning wallet the same button. The difference is who presses it. In P
person decides and one key signs. Here the group decides, with a FROST-signed authorisation,
and `2t-1` co-signers sign a splice that every one of them has checked.
**Being built.** Written against `84984ca8` on `bennu-lightning`, with the
**Built, but for Phase 9, and off.** Written against `84984ca8` on `bennu-lightning`, with the
`lightning-kmp-app` submodule at `6f3f792` and lightning-kmp at `bd78ed62` (branch
`claude/group-lightning-wallet`). The library phases land on a new branch,
`claude/group-lightning-liquidity`, in both `lightning-kmp-app` and `experimental/lightning-kmp`;
@@ -37,6 +37,8 @@ differently, this table says so.
| 6 | done: `PeerHandle.fundingRates`, `feeratePerByte` and `buyLiquidity`, `GroupLightningNode.buyAuthorised` on the node's watch, and the snapshot's rates, feerate and purchases. Four tests with the stand-in peer in `GroupLightningLiquidityJvmTest` |
| 7 | done, behind `GroupLightningRollout.LIQUIDITY_ENABLED`, which is off until Phase 10: `GroupLightningLiquidityScreen` and its route, view model and state; *Add liquidity* on the wallet's balance card, or the reason it is not there; a purchase's state on its channel row; *Inbound liquidity added* in the payment list; and two transcript lines from the snapshot, added and failed. `LiquidityPrice` works out the price on the member's device, and matches what eclair charged in Phase 0 to the sat. Tests: `LiquidityPriceJvmTest`, and two more cases in `LightningPaymentRowJvmTest`. `m3Audit` meets every budget |
| 8 | **run**, in `GroupLightningRegtestJvmTest`, between *receive* and *pay*: a member prices 200,000 sats from the operator's snapshot, the group authorises it at the default cap, the operator's node splices, every co-signer checks the splice and none refuses; the channel grows from 100,000 to 299,779 sats for 2,521 sats, the figure the member's device estimated; a 50,000-sat payment then arrives with no on-the-fly splice; and *pay*, *close* (124,295 sats to the onchain wallet) and *sweep* run on the spliced channel. Sixty seconds from a fresh network |
| 9 | **not built**, as the plan leaves it: whether the LSP may splice the channel to deliver a payment nobody asked for is the group's decision, and a statement field to record it. Until then such a splice is refused at its first commitment, by every co-signer, as *the group has not authorised buying liquidity for this channel* |
| 10 | the documents, and `GroupLightningRollout.LIQUIDITY_ENABLED` is **off**. Phase 8 passed, which is what the plan named for it, but Phase 0's mainnet half was not run: ACINQ's LSP has not been seen to accept a splice in which our funding key does not change, nor its rates read. Both need a node on mainnet and a purchase with real money, which is the owner's to make. Until then the button is not shown and the operator's node buys nothing; every co-signer checks a purchase regardless, so the group is ready when it lifts |
| what the plan said | what it turned out to be |
|---|---|
+2 -2
View File
@@ -81,7 +81,7 @@ build chose differently, this table says so.
| the fresh-nonce label is a counter per channel, strictly increasing | a pool counter. The co-signer's guard is the ledger, never answer a label twice, and the echo rule across members, not monotonicity: a verification label assigned early is signed under at a force close, long after higher counters were answered |
| check 5 compares our main output with the last amount signed, less budgets and allowance | `CoSignerPolicy` tracks the *value* the group can claim (our balance plus HTLCs we offered), against a floor that starts at the first commitment less the fee allowance, rises by what is received, and falls only by authorised payments that settle. A new HTLC we offer must be authorised, with budget left after what is already in flight for it. Without this, a receipt could refill a spent budget |
| check 6, our own commitment, needs a force-close authorisation | refused outright until Phase 13 adds authorisations |
| check 8, splices | refused: the channel is pinned to its funding output the first time a device signs for it, and a request for any other output is refused. Splices arrive with Phase 13 |
| check 8, splices | refused: the channel is pinned to its funding output the first time a device signs for it, and a request for any other output is refused. Splices arrive with Phase 13. **Since built for one kind:** a liquidity purchase the group authorised, in [group-lightning-liquidity.md](./group-lightning-liquidity.md) Phase 5. Every other splice is still refused |
| a co-signer whose database was restored collects high-water marks from `t` others | **not built.** The ledger is never pruned and a restored device starts with an empty one, so a restored co-signer could echo a label it answered before the restore. The echo rule still stops the label being signed under two messages unless `n-t+1` members echo the second, which needs the restored device and `n-2t+1` others to be wrong. It is listed under what is left |
| the operator collects `t` shares | `2t-1`, the quorum the scheme wants online for round two; `aggregatePartialSignatures` degree-checks a set larger than `t` |
| first find out whether `lightning-kmp-app/library` can host a second `PhoenixBusiness` | it does not need to. `GroupLightningNode` builds a lightning-kmp `Peer` itself, on Phoenix's SQLite channel and payment databases (`createSqliteChannelsDb`, `createSqlitePaymentsDb`), under file names prefixed `group-` so they never meet the identity's own |
@@ -89,7 +89,7 @@ build chose differently, this table says so.
| the start gate reads when the room last synced | the newest group event this device saved for the room (`MarmotGroupEventDao.newestSavedAt`), because the app keeps no sync time. A sync time taken from the live subscription's end-of-stored-events is the follow-up |
| a foreground service keeps the node running on Android | **not built.** The node runs while the app does |
| the node stays connected to the LSP | it did not: lightning-kmp never redials, the identity's own node has Phoenix's connection daemon for that, and the group's node connected once, so one drop left it offline for the rest of the term. It now redials after every drop, from two seconds doubling to five minutes; a connection that ends inside a minute counts as a failure, so an LSP that hangs up on our features is not redialled every two seconds. Each drop is logged with why, naming a feature we require that the LSP's `init` did not offer (`GroupLightningNode.dropReason`) |
| the LSP offers simple taproot channels (Phase 0, step 1) | **yes, on mainnet, from 2026-10-26.** The first try failed by our own doing: ACINQ's mainnet LSP (`03864ef0…`) hung up seven milliseconds after `init`, every time, because the group's node *required* bit 564 and ACINQ's `init` -- the same one a fresh Phoenix node gets -- lists neither 564 nor 565 (eclair's `option_simple_taproot_phoenix`), nor zero-reserve, trampoline or wake-up. BOLT 9 obliges a peer to hang up on a required feature it does not offer. With lightning-kmp's default of optional, the run that followed, on four emulators with Medium_Phone as operator, went through. A 10,000-sat payment arrived as `will_add_htlc`; the node asked for an on-the-fly channel (fee 1,442 sats: 342 mining, 1,100 service); ACINQ funded 25,000 sats; the taproot channel `3442db60…` was `Normal` 2.6 seconds after the request; and 8,558 sats settled to the group. A 21-sat payment then left with a 4.084-sat trampoline fee and settled in 11.5 seconds. Every co-signer checked each of the five commitments and none refused; each group signature took 0.4 to 0.9 seconds. That is four emulators on one machine, so it says nothing yet of how long ACINQ waits (Phase 0, step 2). The channel was left with 16,442 sats of inbound: a larger payment is funded by splicing this channel, which the co-signers still refuse (check 8), so it would fail |
| the LSP offers simple taproot channels (Phase 0, step 1) | **yes, on mainnet, from 2026-10-26.** The first try failed by our own doing: ACINQ's mainnet LSP (`03864ef0…`) hung up seven milliseconds after `init`, every time, because the group's node *required* bit 564 and ACINQ's `init` -- the same one a fresh Phoenix node gets -- lists neither 564 nor 565 (eclair's `option_simple_taproot_phoenix`), nor zero-reserve, trampoline or wake-up. BOLT 9 obliges a peer to hang up on a required feature it does not offer. With lightning-kmp's default of optional, the run that followed, on four emulators with Medium_Phone as operator, went through. A 10,000-sat payment arrived as `will_add_htlc`; the node asked for an on-the-fly channel (fee 1,442 sats: 342 mining, 1,100 service); ACINQ funded 25,000 sats; the taproot channel `3442db60…` was `Normal` 2.6 seconds after the request; and 8,558 sats settled to the group. A 21-sat payment then left with a 4.084-sat trampoline fee and settled in 11.5 seconds. Every co-signer checked each of the five commitments and none refused; each group signature took 0.4 to 0.9 seconds. That is four emulators on one machine, so it says nothing yet of how long ACINQ waits (Phase 0, step 2). The channel was left with 16,442 sats of inbound: a larger payment is funded by splicing this channel, which the co-signers still refuse (check 8), so it would fail. A purchase made ahead of time is now possible ([group-lightning-liquidity.md](./group-lightning-liquidity.md)); a splice the LSP starts for a payment is that plan's Phase 9, left to the group |
| the node acts on the room's requests at its next check | it did, every ten seconds, and on that run the poll was most of the wait: six seconds from a member's invoice request to the invoice, five from the group's signed authorisation to the payment leaving. It now watches the room's invoice requests and authorisations (counts of kinds 30364 and 30363, which cover channel actions too) and acts as either changes. The poll stays, for expiries and snapshots, and one lock covers both, so nothing is answered or paid twice |
| the node's logs leave payment secrets out | lightning-kmp prints a fulfilled HTLC's `paymentPreimage` at info; it already writes `<private_key>` for per-commitment secrets. Since the Android build writes to Logcat, a release build passes every line through `redactSecrets`, which replaces any preimage with `<redacted>`. A debuggable build logs it as it is |
| the node is set up as Phoenix sets up its own | it is now, where the group's terms allow: lightning-kmp's default features, zero-conf with the LSP, the LSP's own wallet parameters, Phoenix's connect and handshake timeouts growing with each attempt (tripled over Tor), the LSP's onion address while the identity has Tor on, a refusal to dial a clearnet address over Tor, and Phoenix's 50% relative cap on liquidity fees. Two things differ on purpose. The absolute cap is the statement's, which the group signed, not a member's setting. And the redial pauses grow to five minutes and reset only after a minute connected, where Phoenix's reach eight seconds and reset at every handshake, which against an LSP that hangs up after `init` would redial every tenth of a second |
+5
View File
@@ -5,6 +5,11 @@ group Lightning wallet, receive, pay, close and sweep against a real lightning-k
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".
`LiquidityPurchaseRegtestJvmTest` uses the same network for the liquidity plan's Phase 0
([docs/group-lightning-liquidity.md](../../docs/group-lightning-liquidity.md)): a stock node that keeps one
funding key buys inbound liquidity from the LSP, with its signatures delayed, to see what eclair accepts
and how long it waits. The group run buys liquidity too, between receiving and paying.
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.