**Built**, one commit per phase on `claude/automate-key-ceremony-803bb9`
(`e9c413ac` to `0a60da6e`), against the code as it stood at `d4dd87f2`. After
the joins, a group's own ceremony runs to a signed key state and a room-creation
call with nobody asked anything: `KeyStateSignsItselfJvmTest` runs it across
three in-memory devices with real ChillDKG and real FROST. The phases are kept
as written because they are the reasoning. Where the build chose differently:
| what the plan said | what it turned out to be |
|---|---|
| Phase 2's tampered `cmsg1` is caught by every honest member at round 2, and each broadcasts FAILURE | depends on which bytes change. The flipped byte the test uses is not one a member's share check covers, so the members confirm, the confirmations disagree, and the coordinator's `coordinatorFinalize` refuses to make a certificate. Every device fails and nobody holds a key, which is the property. The test asserts that and that somebody said so, not that every member did |
| Phase 3's sweep is wired "where the live subscription is built" | in `SynchronizationViewModel`, after `reopenInbox`, through `NostrRepository.resumeRunningCeremonies`, and under the same lock as the inbound path that otherwise drives a ritual |
| Phase 4's notice loses its `ROUND_1` and `ROUND_2` arms | they stay, answering `null`: the `when` is over the enum, which keeps both values for old rows. Nothing reaches them |
| Phase 5 dates a stall from the newest transcript line | from the newest `DkgParticipantMessage`. A `ChatMessage` has no session id, so in a room that has run more than one ceremony its lines cannot be told apart. That needed one fix: `record` and `publishOwn` rewrote a message's row on every redelivery, which restarted the clock each time a relay repeated itself. A message is now stored once, on first arrival |
| Phase 5 puts the abandon action inline on the waiting rung | a card at the top of the ladder, above the rungs, naming who and since when, with the button. The stall is the most important thing on the screen when there is one |
| Phase 6 runs the follow-through at the end of `advance` and when a signing session completes | a long-running driver beside the live subscription, `ChatRepository.followThroughCeremonies`, that looks again when a ceremony finishes, a certificate or key state is signed, or a key package arrives. Creating a room waits on relays for key packages, and the inbound path is what delivers them: run inside it, under its lock, it would wait on itself. It does not run in the sweep for the same reason |
| Phase 6 moves the ladder buttons' code into the manager | the buttons keep their own code and share `roomName` and `roomPurpose`. They are now the retry after a failure, which the automatic path never does. A button pressed in the moment before the coordinator's device proposes could open a second key-state session; both sign the same statement, so the cost is a second session, not a wrong one |
| Phase 6's ladder ends in **Open the room** | it does, and the room-creation notice on the coordinator's chat stays: it still names a ceremony whose room does not exist yet, and opens the ladder that says what it is waiting on |
| Phase 7 calls the checks `stateFrom` makes | `stateFrom` became `claimFrom` plus the signature check, so the rule for signing and the rule for keeping are one function. One check was added: the unsigned event's author is the room it names |
| Phase 7's tests sit beside the existing key-state tests unchanged | two in `SignedGroupKeyStateTest` asserted the gate this phase removes and now assert the new rule. A member who hears a proposal only after the quorum finished it may still publish a nonce for it, since the signature can arrive after the proposal; it is never used |
**Not done:** the emulator session in Phase 8. Nothing here has run on a device,
including the upgrade in place and a subgroup from proposal to room. A subgroup's
certificate needs its parent's quorum to sign, so no test runs that path end to
end; `CeremonyFollowThroughJvmTest` covers each step of it separately.
| 5 | publish the CertEq signature (round 2) | every participant | `DkgRound2ApprovalScreen` | automatic. If the device's check fails, the ceremony fails and says so, as it does today |
| 6 | certificate (`cmsg2`), finalize, keep share | coordinator, then every participant | automatic | automatic |
| 7 | propose the birth certificate *(subgroup)* | coordinator, or any parent admin in it | button on the ladder | automatic (Phase 6) |
| 8 | sign the birth certificate *(subgroup)* | the parent's quorum | signing approval | **unchanged**: the parent's own decision, see Phase 0 |
| 9 | propose the key state | coordinator, or any participant | button on the ladder | automatic (Phase 6) |
| 10 | sign the key state | each participant, `t` needed | signing approval | automatic when the statement passes the checks in Phase 7, asked as today otherwise |
| 11 | create the room | coordinator, or any participant | button on the ladder | automatic, retried when it is blocked on key packages (Phase 6) |
| — | abandon | any participant | button on the ritual screen | **kept** |
Today a member who joins a group's own ceremony is asked three more times before
the group has a working room (rows 3, 5 and 10), and the coordinator presses
three more buttons (rows 9 and 11, plus 3 and 5 for themselves). After this plan
the member is asked nothing after row 2, and the coordinator nothing after row 1.
### Where the gates are
| finding | where |
|---|---|
| G1. `advance` stops at round 1 until `round1ApprovedAt` is set, and asks for it | `ChillDkgRitualManager.kt:751` |
| G2. `advance` stops at round 2 until `round2ApprovedAt` is set, and asks for it | `ChillDkgRitualManager.kt:788` |
| G3. `pendingApproval` mirrors G1 and G2, and must keep doing so | `ChillDkgRitualManager.kt:1123` |
| G4. The coordinator is approved for the host key on proposal but still asked for both rounds | `ChillDkgRitualManager.kt:305-309` |
| G5. The ritual screen's bottom bar offers a review button per step, and three routes and three screens back it | `DkgRitualScreen.kt:209-246`, `GizaNavHost.kt:621-659` |
| G6. The room's chat notice names three steps | `ChatTranscript.kt:627-631`, `ChatMessageListViewModel.kt:275` |
| G7. The join screen promises the member two more asks | `DkgJoinApprovalScreen.kt:82` |
| G8. Key state, certificate and room are buttons wired to view-model actions, so they run only while somebody has the screen open | `DkgRitualViewModel.kt:308, 370, 499` |
| G9. A key-state signing session waits on `signApprovedAt` like every other signature | `FrostSigningManager.kt:977` |
| G10. Nothing resumes a ritual except an arriving message. A ceremony paused at round 1 when the upgrade lands has every message it needs already and will receive no more, so it would never move | `NostrDao.kt:995, 1600` are the only callers of `processRitualPayload` |
G10 matters beyond the upgrade. The rounds have always been safe to resume, but
until now a person's tap was the thing that resumed them. Take the tap away and
something else has to do that job.
---
## Phase 0: before any code
**An hour, to settle eight things the phases assume.**
1.**Joining means consenting to the whole ceremony.**`hostKeyApprovedAt` keeps
its column and name. It now means "agreed to take part", and a member is not
asked about this ceremony again. The join screen has to show everything the
round-1 screen used to show, the participant list in particular. That costs
nothing: the list is the proposal's p-tags, fixed before anyone joins, so the
round-1 screen never showed anything the join screen could not have.
2.**Nothing new goes on the wire.** The kinds, tags and ordering stay as they
are. Older Giza and Bennu peers keep their own gates, and a ceremony with one
of them in it finishes when that member taps, as it does today.
3.**`round1ApprovedAt` and `round2ApprovedAt` stay in the schema, unread.** A
version bump to drop two nullable columns costs a migration and a migration
test and buys nothing. Their KDoc says they were written by builds before
this one. `DkgApprovalStep.ROUND_1` and `ROUND_2` stay in the enum for the
same reason: `approvalRequestedThrough` stores them by name on rows already
written, and removing them would stop those rows decoding.
4. **The coordinator's open-ceremony button stays a decision, and so does the
parent's signature on a birth certificate (row 8).** That signature is the
parent group agreeing that a subgroup exists, under a name, with these
admins. Most of the parent's signers were never in the ceremony, and what
they are judging is whether the parent wants this subgroup. That is
governance, and a device cannot answer it. The proposal is a request, so it
can go out automatically (Phase 6). The answer cannot.
5.**A key state signs itself only when exactly one statement could be true.**
For a ceremony this device completed, there is one key, one path and, for a
subgroup, one certificate the parent's quorum signed. So there is exactly one
key state that is correct. If the statement matches it, a person has nothing
to add. If anything differs, the device asks, as it does today. Phase 7 lists
the checks.
6. **The resume sweep runs once the live subscription has started and the active
key pair is in reach.** The likely place is next to where
`SynchronizationViewModel` builds `LiveSubscriptionManager`. If the key pair
is not available there, use wherever `NostrDao` gets the `activeKeyPair` it
passes to `processRitualPayload`. Decide which before Phase 3. Either way a
ceremony moves whenever the app is in the foreground, and never while it is
closed (see *What this does not do*).
7. **Abandon keeps its rule: any participant, only participants, at any point
before COMPLETE.** Automation makes a joined member's silence the only
remaining way for a ceremony to stall, so abandon becomes the normal way out
of a stall. Phase 5 makes the screen say so.
8.**Phases 6 and 7 are in scope.** "The ceremony" means everything up to a
working room, not just ChillDKG. A ceremony is only useful once its room
exists, and none of the buttons between the key and the room asks anyone
anything. Phases 1 to 5 would be complete on their own, but they would leave
the coordinator pressing two more buttons (three for a subgroup), so they are
not a stopping point.
---
## Phase 1: a ceremony that really runs, across devices, in a test
**A day. Do this before changing anything, so every later phase has something
to change.**
No test today runs ChillDKG from proposal to COMPLETE. `GroupFixtures` gets its
key material from `Frost.trustedDealerKeygen`, and the ceremony tests stop after
the host key. The rounds this plan automates have never been exercised end to end
off a device.
A `CeremonyNetwork` fixture in `jvmTest/.../managers/`:
-`n` in-memory databases, one per member, each with the room seeded the way
`SubgroupCeremonyInParentRoomTest` seeds its two;
-`deliver()` reads every database's outbound rows (`giftWrapPayloadDao` in a
NIP-17 room, `marmotInnerEventDao` in a Marmot one). It writes each row into
every other member's matching store first, because `replayStoredMessages` reads
that store, and then calls `processRitualPayload` on it;
-`deliverUntilQuiet()` repeats until a pass moves nothing;
- an optional shuffle of each pass's order. Relays reorder events, and the
replay path exists because of it.
Tests, written against today's behaviour:
- three members, 2-of-3, NIP-17: with every approval given, all three reach
COMPLETE and hold the same `thresholdPublicKey` and three different shares;
- the same in a parent's Marmot room for a subgroup over two of its three
members, where the third records nothing;
- **today's gates, pinned:** after the joins and nothing more, the network goes
quiet with every member at `pendingApproval == ROUND_1`. Phase 2 flips this
assertion, and that flip is the change this plan makes.
This is also the harness Phases 2, 3, 6 and 7 assert against.
---
## Phase 2: the manager stops at the join and nowhere else
**Half a day. Closes G1 to G4.**
In `ChillDkgRitualManager`:
- **`advance`** loses the two `if (session.roundNApprovedAt == null)` blocks. The
host-key gate at the top stays, with its comment rewritten: it is now the only
gate. The steps between are already idempotent through `ownMessage` and the
`coordinatorRound1`/`certificate` checks, so removing the gates adds no new
path. It only stops cutting the existing path short.
- **`pendingApproval`** becomes:
```kotlin
if (session.stage == COMPLETE || session.stage == FAILED) return null
return if (session.hostKeyApprovedAt == null) DkgApprovalStep.HOST_KEY else null
```
It is still "a step is pending exactly when `advance` would stop at it", which
is now easy to see. Its KDoc says the other two steps used to be gates.
- **`approve`** accepts only `HOST_KEY`. For the other two it logs and does
nothing, the same answer it gives a stale screen today. A `ROUND_*` approval
from a screen left open across the upgrade then does no harm.
- **`proposeRitual`**: the comment at `:305` changes from "Rounds 1 and 2 are
still asked for" to say that opening a ceremony is agreeing to all of it, and
the coordinator is never asked.
- **`announceApprovalNeeded`** only ever receives `HOST_KEY`. The `ROUND_1` and
`ROUND_2` arms of its `when` stay, because the enum keeps those values, but
nothing reaches them. They get a one-line comment saying so, so nobody mistakes
them for live wording.
- **`DkgApprovalStep`**'s KDoc is rewritten. It becomes the list of things a
ritual has *ever* asked for: one that is still asked, two kept so old rows
decode.
A round-2 fault keeps the failure path it has today: `raiseIfFaulty`, then
`fail`, then a broadcast FAILURE. The difference is that it can now happen with
nobody looking at the screen. The transcript's *failed* line and the ritual
screen's failed state already cover that case, and Phase 4 checks the room's
notice does too.
**Tests**, on the Phase 1 network:
- after each member joins, and with no other call, every member reaches COMPLETE
with the same key. This is Phase 1's pinned assertion, flipped;
- the coordinator is never asked, so `pendingApproval` is null for them from the
moment they propose;
- the last member to join publishes host key and round 1 in that one `approve`
call, because the host keys were already all in;
- a coordinator who substitutes `cmsg1` (the fixture tampers with it in transit)
fails the ceremony on every honest device, with no approval in between, and
each of them broadcasts FAILURE. This was always the protection, and the test
shows it no longer depends on a person;
- `approve(ROUND_1)` and `approve(ROUND_2)` publish nothing;
- a guarded subgroup still cannot be joined, and nothing goes out.
`SubgroupCeremonyInParentRoomTest` and `RobustRoomKeyCeremonyTest` assert only
the host-key step and should pass unchanged. Check that they do.
---
## Phase 3: running ceremonies resume without a message
**Half a day. Closes G10.**
```kotlin
/**
* Moves every running ceremony of this user's as far as its stored messages
* allow. What a tap on "Contribute" used to do, for ceremonies that already
* have everything they need and will receive nothing more.
*/
suspend fun resumeRunning(database: GizaDatabase, userPublicKey: HexKey, nostrPrivateKey: ByteArray)
```
It selects sessions for `userPublicKey` that are not COMPLETE or FAILED and have
`hostKeyApprovedAt` set. It looks up each session's room (skipping a session
whose room is gone, with a warning) and calls `advance`. That needs one DAO
query, `getRunningSessionsFor(userPublicKey)`. `advance` is already safe to
re-run, so the sweep can run every time sync starts at no real cost: a
ceremony with nothing to do returns at its first missing input.
It is wired into `SynchronizationViewModel` where the live subscription is built,
once per identity, after the subscription opens. That way a sweep that publishes
something is publishing into a pipeline that is already running.
**Tests:**
- **the upgrade case:** a session with all host keys stored, `round1ApprovedAt`
null and `approvalRequestedThrough = ROUND_1`, which is exactly what a
ceremony paused by the old build leaves. Run the sweep with no message
arriving: it publishes round 1, and on the Phase 1 network the ceremony
completes;
- a session whose host key was never approved is not touched;
- a FAILED or COMPLETE session is not touched;
- two sweeps in a row publish nothing twice.
---
## Phase 4: one approval screen
**A day. Closes G5 to G7.**
**The join screen takes on what the round-1 screen showed.** In
`DkgJoinApprovalScreen`:
- the participant list, moved from `DkgRound1ApprovalScreen`, under the existing
`taking_part_with_these_members` string;
- the three points become what joining now commits to: *your device publishes
the key it is identified by, then contributes to the shared key and confirms
the result once everyone has, without asking you again*; *your share never
leaves this device*; *the ceremony cannot finish until every member has taken
part, and any of them can abandon it if it stalls*;
- the footnote keeps "Nothing has been published from this device yet."
Every new string goes in `strings.xml` in sentence case. The existing literals on
this screen move there too, since the screen is being rewritten anyway.