feat(lightning): the group node acts as requests arrive, and the mainnet run is recorded

On the first mainnet run, most of the wait for an invoice (six seconds) and for an authorised
payment to leave (five) was the node's ten-second poll. The node now watches the room's
invoice requests (30364) and authorisations (30363, which carry channel actions too), and acts
the moment either changes. The poll stays, for expiries and snapshots. Answering, paying and
closing each take one lock, so a wakeup, the poll and a direct call never act twice on the
same request: payAuthorised checks hasPaid, which suspends, before it marks a payment in hand.

Advances lightning-kmp-app to the commit that keeps payment preimages out of a release build's
Logcat.

The plan doc records the run with ACINQ's mainnet LSP: an on-the-fly 25,000-sat taproot
channel, 8,558 sats received, and a 21-sat payment sent. Every co-signer approved every
commitment. The doc also notes that a payment larger than the channel's 16,442 sats of
inbound would need the splice the co-signers still refuse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-10-26 23:47:32 +02:00
1 parent 309a486de9
commit 515ddea2be
7 files changed
+106 -13

No files matched your search

@@ -28,6 +28,13 @@ abstract class GroupSignedEventDao {
@Query("SELECT * FROM GroupSignedEvent WHERE chatRoomId = :chatRoomId AND kind = :kind ORDER BY createdAt ASC, id ASC")
abstract suspend fun getByChatRoomIdAndKind(chatRoomId: String, kind: Kind): List<GroupSignedEvent>
/**
* How many events of one kind a room has signed, as it changes: what the group's Lightning node watches
* to act on a payment or channel action the moment the group authorises it, rather than at its next poll.
*/
@Query("SELECT COUNT(*) FROM GroupSignedEvent WHERE chatRoomId = :chatRoomId AND kind = :kind")
abstract fun observeCountByChatRoomIdAndKind(chatRoomId: String, kind: Kind): Flow<Int>
/**
* Every signed event of one kind, whatever room it was signed in.
*
@@ -62,6 +62,13 @@ interface MarmotInnerEventDao {
@Query("SELECT * FROM MarmotInnerEvent WHERE chatRoomId = :chatRoomId AND kind IN (:kinds) ORDER BY createdAt ASC")
suspend fun getByChatRoomAndKinds(chatRoomId: String, kinds: List<Int>): List<MarmotInnerEvent>
/**
* How many of a room's inner events are of the given kinds, as it changes: what the group's Lightning
* node watches to answer an invoice request the moment one arrives, rather than at its next poll.
*/
@Query("SELECT COUNT(*) FROM MarmotInnerEvent WHERE chatRoomId = :chatRoomId AND kind IN (:kinds)")
fun observeCountByChatRoomAndKinds(chatRoomId: String, kinds: List<Int>): Flow<Int>
@Query("DELETE FROM MarmotInnerEvent WHERE id = :id")
suspend fun deleteById(id: String)
@@ -4,6 +4,7 @@ import co.touchlab.kermit.Logger
import com.machankura.bennu.compose.database.BennuDatabase
import com.machankura.bennu.compose.database.model.intermdiate.LocalChatRoom
import com.machankura.bennu.compose.nostr.lightning.GroupLightningAuthorisationEvent
import com.machankura.bennu.compose.nostr.lightning.GroupLightningEvents
import com.machankura.bennu.compose.nostr.lightning.GroupLightningWalletStatementEvent
import com.machankura.bennu.compose.wallet.GroupChainClients
import com.machankura.bennu.compose.wallet.lightning.GroupNodeKeyManager
@@ -59,11 +60,16 @@ import kotlinx.coroutines.Job
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.combine
import kotlinx.coroutines.flow.conflate
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.flow.filterNotNull
import kotlinx.coroutines.withTimeoutOrNull
import kotlinx.coroutines.isActive
import kotlinx.coroutines.launch
import kotlinx.coroutines.sync.Mutex
import kotlinx.coroutines.sync.withLock
/**
* The group's Lightning node, on the operator's device (`docs/group-lightning-wallet.md`, Phase 8).
@@ -151,6 +157,9 @@ class GroupLightningNode(
private var transport: GroupIcebergTransport? = null
private var watching: Job? = null
private var connecting: Job? = null
private var waking: Job? = null
/** Held while the node acts on what the room asked of it, so no two callers act on one request at once. */
private val acting = Mutex()
private var lastReported: Triple<List<WalletWire.ChannelView>, List<WalletWire.PaymentView>, List<GroupSweep.Input>>? = null
private var lastReportedAt: kotlin.time.Instant? = null
@@ -194,6 +203,7 @@ class GroupLightningNode(
lastReported = null
report(term, force = true)
watchForHandover(term)
wakeOnRequests()
logger.i("The group's node ${wallet.statement.nodeId.take(16)} is running, term $term")
return _state.value
}
@@ -211,6 +221,8 @@ class GroupLightningNode(
// First, or the disconnect below would read as a drop and be redialled.
connecting?.cancel()
connecting = null
waking?.cancel()
waking = null
peer?.disconnect()
transport?.stop()
peer = null
@@ -242,8 +254,8 @@ class GroupLightningNode(
}
/** Makes an invoice for every request in the room that has none yet. */
internal suspend fun answerInvoiceRequests() {
val handle = peer ?: return
internal suspend fun answerInvoiceRequests() = acting.withLock {
val handle = peer ?: return@withLock
GroupLightningReports.unanswered(database, localChatRoom.chatRoom.id, walletKey).forEach { request ->
val bolt11 = handle.createInvoice(request.amountMsat, request.description)
GroupLightningReports.answer(database, localChatRoom, userPublicKey, request, bolt11)
@@ -257,8 +269,8 @@ class GroupLightningNode(
* that fails is not tried again: the group signs a new authorisation for another attempt, and the
* co-signers' budgets are what stop either from paying twice.
*/
internal suspend fun payAuthorised() {
val handle = peer ?: return
internal suspend fun payAuthorised() = acting.withLock {
val handle = peer ?: return@withLock
GroupLightningAuthorisations.toPay(database, wallet, now()).forEach { pay ->
if (pay.paymentHash in paying || handle.hasPaid(pay.paymentHash)) return@forEach
paying += pay.paymentHash
@@ -277,12 +289,12 @@ class GroupLightningNode(
* the onchain wallet's first address, which is where the channel's own closing script already
* points, or by force.
*/
internal suspend fun closeAuthorised() {
val handle = peer ?: return
internal suspend fun closeAuthorised() = acting.withLock {
val handle = peer ?: return@withLock
val open = handle.channels().map { it.channelId }.toSet()
val actions = GroupLightningAuthorisations.channelActions(database, localChatRoom.chatRoom.id, wallet.statement, now())
if (actions.isEmpty()) return
val onchain = GroupWalletManager.walletFor(database, localChatRoom.chatRoom.id, chain, wallet.statement.onchainAccount) ?: return
if (actions.isEmpty()) return@withLock
val onchain = GroupWalletManager.walletFor(database, localChatRoom.chatRoom.id, chain, wallet.statement.onchainAccount) ?: return@withLock
val closeTo = GroupWalletDerivation.derive(onchain.account, GroupWalletDerivation.RECEIVE, 0).pubkeyScript
actions.filter { it.channelId in open }.forEach { action ->
if (!closing.add("${action.action}:${action.channelId}")) return@forEach
@@ -339,13 +351,40 @@ class GroupLightningNode(
return@launch
}
runCatching { report(term) }.onFailure { logger.e("Could not report the wallet to the room", it) }
runCatching { answerInvoiceRequests() }.onFailure { logger.e("Could not answer an invoice request", it) }
runCatching { payAuthorised() }.onFailure { logger.e("Could not make an authorised payment", it) }
runCatching { closeAuthorised() }.onFailure { logger.e("Could not close an authorised channel", it) }
act()
}
}
}
/**
* Answers invoice requests, and makes the payments and channel actions the group has authorised. Each
* takes [acting] itself, so the poll, a wakeup and a direct call never pay or answer the same thing twice.
*/
private suspend fun act() {
runCatching { answerInvoiceRequests() }.onFailure { logger.e("Could not answer an invoice request", it) }
runCatching { payAuthorised() }.onFailure { logger.e("Could not make an authorised payment", it) }
runCatching { closeAuthorised() }.onFailure { logger.e("Could not close an authorised channel", it) }
}
/**
* Acts the moment the room's invoice requests or authorisations change, rather than at the next
* [handoverCheck]: on the first mainnet run that poll was most of the wait for an invoice and for a
* payment to leave once the group had signed it. The poll still runs, for expiries and snapshots.
*/
private fun wakeOnRequests() {
waking?.cancel()
val roomId = localChatRoom.chatRoom.id
waking = scope.launch {
combine(
database.marmotInnerEventDao().observeCountByChatRoomAndKinds(roomId, listOf(GroupLightningEvents.INVOICE_REQUEST)),
database.groupSignedEventDao().observeCountByChatRoomIdAndKind(roomId, GroupLightningAuthorisationEvent.KIND),
) { requests, authorisations -> requests to authorisations }
.distinctUntilChanged()
.conflate()
.collect { act() }
}
}
companion object {
/** A lightning-kmp payment as the room hears of it. */
internal fun paymentView(payment: WalletPayment, incoming: Boolean) = WalletWire.PaymentView(
@@ -146,6 +146,29 @@ class GroupLightningPaymentsJvmTest {
assertEquals(listOf(bolt11 to 12_000_000L), nodes.single().paid)
}
@Test
fun `a payment leaves as the group signs it, not at the next poll`() = runBlocking<Unit> {
val (all, _) = opened()
val operator = all[1]
val id = randomBytes32().toHex()
operator.db.nostrEventDao().upsert(NostrEvent(id = id, pubKey = operator.publicKey, kind = 445, tags = emptyArray(), content = "", sig = "0".repeat(128)))
operator.db.marmotGroupEventDao().upsert(MarmotGroupEvent(id = id, userPublicKey = operator.publicKey, publicKey = operator.publicKey, chatRoomId = fixture.roomId, signature = "", encryptedContent = "", expiresAt = null, savedAt = Clock.System.now()))
val node = GroupLightningNode(
operator.db, operator.room, operator.publicKey, GroupLightningWalletManager.walletFor(operator.db, fixture.roomId, fixture.chain)!!, scope,
{ configuration -> FakeGroupNode(configuration).also { nodes += it } },
handoverCheck = 10.minutes,
minimumPool = 0,
)
assertIs<GroupLightningNode.State.Running>(node.start())
val wallet = GroupLightningWalletManager.walletFor(all[3].db, fixture.roomId, fixture.chain)!!
val bolt11 = invoice().write()
authorise(all, GroupLightningAuthorisations.prepare(wallet, bolt11, null, 1_000_000).getOrThrow())
withTimeout(5.seconds) { while (nodes.single().paid.isEmpty()) delay(20) }
delay(200)
assertEquals(listOf(bolt11 to 12_000_000L), nodes.single().paid)
node.stop()
}
@Test
fun `a close the group authorises is made once, to the onchain wallet, and a force close by force`() = runBlocking<Unit> {
val (all, wallet) = opened()
@@ -27,12 +27,15 @@ import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.time.Clock
import kotlin.time.Duration.Companion.minutes
import kotlin.time.Duration.Companion.seconds
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
import kotlinx.coroutines.delay
import kotlinx.coroutines.flow.first
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withTimeout
/**
* What the operator's node tells the room, and what each member makes of it
@@ -162,6 +165,18 @@ class GroupLightningReportsJvmTest {
}
}
@Test
fun `a request is answered as it arrives, not at the next poll`() = runBlocking<Unit> {
// The poll is ten minutes off: only the node's watch on the room can answer in time.
val (all, _) = running()
val wallet = GroupLightningWalletManager.walletFor(all[3].db, fixture.roomId, fixture.chain)!!
GroupLightningReports.requestInvoice(all[3].db, all[3].room, all[3].publicKey, wallet, 21_000_000, "lunch")
fixture.pump(all, setOf(GroupLightningEvents.INVOICE_REQUEST))
withTimeout(5.seconds) { while (nodes.single().invoices.isEmpty()) delay(20) }
delay(200)
assertEquals(1, nodes.single().invoices.size, "a request is answered once")
}
@Test
fun `an invoice is believed only from the operator, and only if it pays the group's node`() = runBlocking<Unit> {
val (all, _) = running()
+3 -1
View File
@@ -87,7 +87,9 @@ 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) | **still open on mainnet; the first try was our mistake.** On 2026-10-26, on an Android emulator, ACINQ's mainnet LSP (`03864ef0…`) hung up on the group's node seven milliseconds after `init`, every time. That `init`, sent identically to a fresh Phoenix node, lists neither bit 564 nor 565 (eclair's `option_simple_taproot_phoenix`), nor zero-reserve, trampoline or wake-up, which Phoenix wallets all use with it. The group's node *required* bit 564, and BOLT 9 obliges a peer to hang up on a required feature it does not offer. The identity's own node, with lightning-kmp's default of optional, stayed connected. The group's node now takes the default too, and holds the connection. Nothing is lost by it: lightning-kmp asks for the taproot channel type in every channel it opens, and the co-signers rebuild every funding output and commitment as taproot. Whether ACINQ then opens a taproot channel to the group's node, as it does to Phoenix wallets, is known only once one is opened on mainnet. Regtest does not answer it: `lsp.conf` advertises the feature, which ACINQ's `init` does not |
| 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 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 |
| a signing timeout disconnects the node | not done: lightning-kmp treats the timeout as a failed signature, and the channel retries on its own schedule |
| a test runs regtest end to end against the docker eclair | **run**, against eclair v0.14.4 as the LSP: see "The regtest run" below. It passes from a fresh network in about thirty seconds |