**Built**, phases 1–6, one commit each: `638c5aab`, `03833a1c`, `3922c15d`,
`1b4ed097`, `3ec79b95`, `a660fabd`, and Phase 7 is the commit that changed this
paragraph. Written against `515ddea2`. The phases are kept as written; where the
build chose differently the table below says so.
| what the plan said | what it turned out to be |
|---|---|
| a manual migration 32 → 33, and Phase 5's column in it if both landed together | two steps: `MIGRATION_32_33` deletes the bubbles and changes no shape, and v34 is an `AutoMigration` that adds `ChatMessage.lightningFactKey` |
| `AwaitingCeremony` gains a `kind` and a small sealed step | one sealed `Ask` replaces both `step` and `roomAwaitingCreation`: `SharedKeyStep`, `RoomCreation`, `LightningKeyStep`, `LightningWalletOpening`. A kind beside a step could disagree with it; the ask cannot |
| the unused-key notice is asked of any member who holds a share | of whoever opened the ceremony only, as ChillDKG's room creation is. Every holder being asked to open the wallet is how a room gets four proposals for one wallet |
| the chat's view model takes a `GroupLightningRepository` | and so does every screen between it and the nav host. `GroupLightningRepository.NO_OP_GROUP_LIGHTNING_REPOSITORY` joins the other repositories' no-ops, for the previews and the screen tests |
| `RitualNotice`'s chevron says what each family opens | and the families that lead nowhere draw none and are not clickable. The approved tick moved to request lines only: a chronicle line, passed as answered to keep it quiet, was showing "You approved this" |
| the invoice request line drops its accent once answered | it never has one. Nobody but the operator's node can answer it, so it is a quiet line like the rest, and the node's answer is a line of its own naming whoever asked |
| the authorisation line names a closing channel's peer and amount | unchanged. The line is written from the signed event alone, before any snapshot that would say the amount; Phase 5's closed line says it when the channel does close |
| a channel's balance disagreeing with this device's ledger is an error line (Phase 6) | not built. The wallet screen already flags it per channel, and a snapshot can lag a commitment the device has just signed, so a line would raise alarms that settle themselves a minute later |
| refusals are said once per request | from `check()`'s own reasons, which were already sentences. A request from a member who is not the operator is still only logged: after a handover the old operator's requests are in flight for a while, and each would be a line |
Every phase was checked with `:composeApp:jvmTest` (1,598 tests; one,
`IdentitySwitchJvmTest`, timed out under the full run's load and passes alone),
| A Marmot inner event is held back from the transcript only if its kind is in `DkgRitualEvents.ALL` or `FrostSigningEvents.ALL` | [ChatMessage.kt:946](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) `isProtocolMessage` | `GroupLightningEvents` is in neither, so every Lightning kind goes on to `applyInnerEvent` |
| `applyInnerEvent` handles the three group-signed kinds (30355, 30356, 30363) and sends everything else to `unsupported()`, a bubble of `event.toJson()` | [ChatMessage.kt:1224, 1530](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) | the ceremony's 30350–30354, the co-signing 30358–30361 and the wallet traffic 30357, 30362, 30364–30366 each leave a raw-JSON bubble, attributed to whoever sent it |
| The same events are *also* acted on, after the line is written | [NostrDao.kt:1585–1648](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/dao/NostrDao.kt) | the managers already work; only the transcript is wrong. A ceremony therefore shows its readable lines *and* a JSON bubble beside each |
| `IcebergRitualManager` writes `TYPE_ICEBERG_*` lines, request lines included, and `ChatTranscript` renders them as `RitualNotice`s that open `IcebergCeremonyScreen` | [IcebergRitualManager.kt:464–506](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [ChatTranscript.kt:285](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | the readable half of the ceremony is built; it is buried, not missing |
| The co-signing traffic is high-volume: a nonce batch per pool window per member, an echo per member per signing request, a share per member per label | [GroupIcebergTransport.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupIcebergTransport.kt), [GroupLightningCoSigner.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupLightningCoSigner.kt) | a room with a running node fills with JSON faster than anyone talks in it, and the room list's preview reads the newest row's `content` (`ChatRoomDao`), so it shows JSON too |
| `ProtocolKindDispatchJvmTest` asserts "no chat line" for `DkgRitualEvents.ALL` and `FrostSigningEvents.ALL` only | [ProtocolKindDispatchJvmTest.kt:120, 169](../composeApp/src/jvmTest/kotlin/mobi/giza/compose/database/model/ProtocolKindDispatchJvmTest.kt) | nothing caught this. The third family needs the same test |
| `MIGRATION_26_27` deleted the `unsupported` rows written for the ChillDKG kinds, found by the kind of the inner event behind them | [RemoveDocumentsMigration.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/migrations/RemoveDocumentsMigration.kt) | the exact precedent for cleaning rooms that already hold the bubbles. The schema is at 32 |
| The standing notice above the composer is fed by `ceremoniesAwaitingYou`, which observes `dkgRepository` only, and its card always calls `onOpenSharedKey` | [ChatMessageListViewModel.kt:112–140, 267–291](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/view/model/ChatMessageListViewModel.kt), [ChatTranscript.kt:203, 613](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | an Iceberg gate never reaches it. The member has to scroll to the request line, which the JSON is burying |
| `IcebergRitualManager.pendingApproval` and `GroupLightningRepository.pendingApproval` / `observeCeremonies` / `hasUnusedKey` exist | [IcebergRitualManager.kt:402](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [GroupLightningRepository.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/repository/GroupLightningRepository.kt) | everything the notice needs is already exposed, the same way the ChillDKG notice reads `pendingApproval` |
| No Lightning manager writes a chat line. A co-signer's refusal and an operator's equivocation are `logger` calls | [GroupLightningCoSigner.kt:193, 232](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupLightningCoSigner.kt) | the wallet doc promises both as transcript lines ("A person only sees a refusal, as a transcript line"); neither is |
| The operator line says "The group chose who runs its Lightning wallet" without saying who | [ChatMessage.kt:1464–1483](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) | the one fact the line exists for is missing. The member-wallet lines already name people with `memberName` |
| A ceremony abandoned by somebody else is recorded as `"Abandoned by ${sender.take(8)}: ${content}"`, and a local fault as the exception's message; the screen shows `failureReason` verbatim | [IcebergRitualManager.kt:280, 365](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [IcebergCeremonyScreen.kt:200](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/IcebergCeremonyScreen.kt) | a key prefix and an exception string where ChillDKG shows a name and a sentence |
| The Iceberg gates are an inline card on the ceremony screen; ChillDKG's each have a screen of their own on `DkgApprovalScaffold` | [IcebergCeremonyScreen.kt:210–233](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/IcebergCeremonyScreen.kt), [DkgApprovalScaffold.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/DkgApprovalScaffold.kt) | a difference in shape, not a defect. Decision D5 |
| `RitualNotice`'s chevron says "Open the shared key ceremony" for every family it draws, signing lines and Lightning lines included | [ChatTranscript.kt:972](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | a screen reader is told the wrong destination |
`InconsistentShares`) and `advance`'s two `check`s (a disagreeing transcript, a
wrong public share) map to one sentence each, naming the member at fault through
`Fault.participant` where there is one, in the shape ChillDKG's blame lines use.
`failureReason` keeps the raw message for the log.
- `IcebergCeremonyScreen` shows that sentence in place of `abandoned_s` with the
raw reason, and names the culprit from the room's participants.
- `RitualNotice`'s chevron description follows the family: the shared key
ceremony, the Lightning wallet's key ceremony, the signing proposal, the
Lightning wallet. Each one a catalogue string.
- The JOIN request line for the member who opened the ceremony: today they are
approved at proposal time and get no request line, which is right. Asserted in
a test so it stays right.
**Done when** a ceremony abandoned on another device reads "@name abandoned the
Lightning wallet's key ceremony" with the reason in a sentence, on both the line
and the screen.
## Phase 4: what the operator and the members say to each other
The direct traffic outside the two protocols, as lines. New types on
`ChatMessage`, in a `LIGHTNING_TYPES` set with an `LIGHTNING_AUTHORED_TYPES`
subset (D7):
| kind | type | line | written by |
|---|---|---|---|
| 30357 node seed | `TYPE_LIGHTNING_SEED_SHARED` | "@name gave each key holder the Lightning node's seed." | `GroupLightningWalletManager`, on send (D3) and on `receiveSeed` |
| 30364 invoice request | `TYPE_LIGHTNING_INVOICE_REQUESTED` | "@name asked the operator's node for an invoice of 21,000 sats." or "…for an invoice." with no amount | `GroupLightningReports.requestInvoice` on send; on arrival, every device |
| 30365 invoice | `TYPE_LIGHTNING_INVOICE_ISSUED` | "The operator's node made @name's invoice." | `GroupLightningReports.receiveInvoice`, only once the invoice passes the checks it already makes |
| 30366 stopped | `TYPE_LIGHTNING_OPERATOR_STOPPED` | "@name stopped running the group's Lightning node." | `GroupLightningOperatorManager.announceStopped` on send; a new arm in the `NostrDao` dispatch on arrival |
- The invoice request is a request, and the invoice answers it: both lines carry
the request id, and the request line drops its accent once its invoice line
exists, through the same `answeredRequests` shape, keyed on the request id
rather than `isUserMessage`. Nobody but the operator's node can answer it, so
it is never put above the composer.
- The operator statement's line names the operator: "@name runs the group's
Lightning wallet now." / "Nobody runs the group's Lightning wallet now. It stops
until someone is chosen." The term number leaves the sentence; it means nothing
to a reader and is on the wallet screen.
- The authorisation line names the channel's peer and amount for a close where
the snapshot this device holds can say them, and keeps today's sentence where
it cannot.
- Dedupe: each line is keyed on the inner event's id (`marmotInnerEventId`),
which re-delivery and negentropy repeat. The send-side row and the arrival row
for the same event are the same row, so `reconcileMarmotLine`'s rule holds.
- `ChatTranscript`: a `LIGHTNING_TYPES` branch drawing `RitualNotice`, with icons
(`Key` for the seed, `RequestQuote`/`Receipt` for the invoice pair, `PowerOff`
for the stop), opening the Lightning wallet screen through
`onOpenLightningWallet`.
- Tests: each line from a two-device exchange, its author's copy written once,
and no line from an invoice that fails the operator check.
**Done when** a member can follow, from the room alone, who set the node up, who
asked to be paid, and who stopped running it.
## Phase 5: what the snapshots say happened
Lines from the operator's snapshots, written once per fact (D4). All in
`GroupLightningReports.file`, which already has the held snapshot and the new one
side by side.
| fact | type | line |
|---|---|---|
| a channel id this device has not filed before | `TYPE_LIGHTNING_CHANNEL_OPENED` | "The group's Lightning node opened a channel of 500,000 sats." |
| a held channel that turns closing or closed | `TYPE_LIGHTNING_CHANNEL_CLOSED` | "A Lightning channel closed. Its 480,120 sats go to the onchain wallet." |
| a payment row that first gets a `completedAt`, incoming, succeeded | `TYPE_LIGHTNING_PAYMENT_RECEIVED` | "The group's Lightning wallet received 21,000 sats." with the description where there is one |
| the same, outgoing | `TYPE_LIGHTNING_PAYMENT_SENT` | "The group's Lightning wallet sent 21,000 sats, with 12 sats in fees." |
| the same, failed | `TYPE_LIGHTNING_PAYMENT_FAILED` | "A Lightning payment of 21,000 sats failed. Nothing left the wallet." |
- No author: the node did these, and the operator is already named by Phase 4's
election line. Attributing a payment to the operator would read as them having
chosen it.
- A channel check that disagrees with this device's ledger (`ChannelCheck`) is
not a line here. It is Phase 6's.
- Dedupe by the fact, not the event: a `chatMessageDao` lookup on
`(chatRoomId, messageType, factKey)`, where `factKey` is the channel id or
payment id. That is a new nullable column, `lightningFactKey`, in the same
migration as Phase 1 if both land together, an `AutoMigration` if not.
- Payments on a busy wallet are many lines. Decision D8 below.
**Done when** a regtest run (`GroupLightningRegtestJvmTest`) leaves exactly one
opened line per channel, one line per settled payment and one closed line per
close, on every device, whatever the number of snapshots between.
## Phase 6: refusals and the equivocation alarm
What the wallet doc promised and the co-signer only logs.
- A co-signer's refusal (`GroupLightningCoSigner.handleRequest`, the `check`
result) writes `TYPE_LIGHTNING_REFUSED` on *this device only*: "Your device
refused to co-sign for the Lightning node: the channel would grow past the
1,000,000 sat cap." One sentence per refusal reason, once per request id. It
is not broadcast; another member's refusal is theirs to see.
- Two hashes echoed for one label writes `TYPE_LIGHTNING_EQUIVOCATION`, in the
error tint, on every device that sees both: "The operator's node asked the
group to sign two different things under one label. Nobody will sign it." Once
per label.
- A channel whose `ChannelCheck` disagrees with this device's ledger writes one
error line per channel per disagreement, naming the difference in sats.
- Both error types join the tint `when` in `RitualNotice` beside
`TYPE_ICEBERG_FAILED`.
**Done when** the existing refusal tests and the equivocation test each assert
their line, and a second identical request writes no second line.
## Phase 7: the notes, the audit and a device run
- [group-lightning-wallet.md](./group-lightning-wallet.md)'s state table gains a
row saying the transcript is done and pointing here; the "A person only sees a
refusal, as a transcript line" sentence becomes true.
- This document's status line, and a "what the plan said / what it turned out to
be" table as the other built plans have.
- `./gradlew :composeApp:m3Audit` and `check`: every new notice string in the
catalogue, sentence case, no `contentDescription = null`.
- A four-device run on regtest: ceremony, wallet, election, an invoice, a
payment each way, a close. Screenshots of the room and of the room list,
neither showing JSON.
---
## Still to decide
**D8. A line per payment, or a summary.** One per settled payment matches the
onchain wallet's one per confirmed transaction, and a group wallet is not a
merchant's. A busy wallet would want "3 payments received today" instead, which
needs a day boundary and a line that updates. The plan writes one per payment;
the summary can come later without a schema change if the fact key is kept.
**D9. Whether a refusal is told to the group.** Phase 6 keeps it on the refusing
device, because a refusal names a check the operator failed, and the group
learns that the payment stalled from the snapshot. Telling the group would mean
a new broadcast kind; not in this plan.
## Order and size
Phase 1 alone fixes what a member sees today, and should land first and on its
own. Phases 2 and 3 are the ceremony and can go together. Phases 4 and 5 depend
on Phase 1's dispatch change and share `LIGHTNING_TYPES`; Phase 5 depends on
Phase 4 for the family and on D8. Phase 6 depends on Phase 4 for the family only.