feat: joining is the only approval a key ceremony asks for (automatic ceremony, Phase 2)

advance no longer stops at rounds 1 and 2. Contributing follows from
having joined, and confirming is ChillDKG's own check, which refuses a
substituted result whether or not anybody is looking. pendingApproval
returns the join or nothing, and approving a round is a no-op.

ROUND_1 and ROUND_2 stay in the enum, and their timestamps in the
schema, so rows written by older builds keep decoding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-11-19 22:49:12 +02:00
1 parent e9c413ac66
commit ca5cda81db
5 files changed
+219 -105

No files matched your search

@@ -154,19 +154,23 @@ data class DkgSession(
*
* The ritual is otherwise driven entirely by arriving messages, which would
* mean a member is enrolled in the group's permanent signing quorum by a relay
* delivering an event to a phone in their pocket. Each of these three is a
* separate decision because each publishes something different and commits the
* member to something different -- see `ChillDkgRitualManager.pendingApproval`.
* delivering an event to a phone in their pocket. This is the one decision it
* asks for, and it covers the whole ceremony: the rounds after it run without
* asking -- see docs/automatic-key-ceremony.md.
*
* Set at creation for the member who opened the ceremony: starting one is
* already the act of agreeing to be in it.
*/
val hostKeyApprovedAt: Instant? = null,
/** When they approved publishing their contribution to the key. */
/**
* When they approved publishing their contribution to the key, on a row from a
* build that asked. Nothing reads or writes it now; kept rather than migrated
* away, since dropping a nullable column buys nothing.
*/
val round1ApprovedAt: Instant? = null,
/** When they approved signing to confirm the combined result. */
/** When they approved confirming the combined result. As [round1ApprovedAt]. */
val round2ApprovedAt: Instant? = null,
/**
@@ -1,39 +1,45 @@
package mobi.giza.compose.database.model.types
/**
* One thing a ChillDKG ritual needs this device's owner to agree to before it
* will publish on their behalf.
* Everything a ChillDKG ritual has ever asked this device's owner before publishing
* on their behalf. It asks one of them now.
*
* The ritual is driven by arriving messages, so without these it runs to
* completion on its own — a relay delivering an event to a phone in a pocket is
* enough to enrol its owner in a group's permanent signing quorum. Each step is a
* separate decision because each publishes something different and commits the
* member to something different, and each is presented on its own screen.
* The ritual is driven by arriving messages, so without a gate it runs to
* completion on its own -- a relay delivering an event to a phone in a pocket would
* be enough to enrol its owner in a group's permanent signing quorum. [HOST_KEY] is
* that gate, and the only one: joining is a decision nothing on the device can make
* for its owner. What follows it is not. Contributing follows from having joined,
* and confirming is a check the device makes itself, so neither is asked about
* (docs/automatic-key-ceremony.md).
*
* The coordinator's two aggregations are deliberately not here. They relay other
* members' already-published messages and disclose nothing of the coordinator's
* own, so gating them would stall the whole group on one person's attention
* without protecting anybody.
* [ROUND_1] and [ROUND_2] stay because they were asked about until then, and
* `DkgSession.approvalRequestedThrough` stores a step by name: a row written by an
* older build has to keep decoding, and its request lines keep rendering.
*
* The coordinator's two aggregations were never here. They relay other members'
* already-published messages and disclose nothing of the coordinator's own, so
* gating them would stall the whole group on one person's attention without
* protecting anybody.
*/
enum class DkgApprovalStep {
/**
* Publish this device's host public key, which is what puts its owner in the
* participant set. The most consequential of the three: `n` is fixed from here,
* and every later step assumes this member is in.
* participant set -- and, since nothing else is asked, agreeing to the whole
* ceremony. `n` is fixed from here, and every later step assumes this member is
* in.
*/
HOST_KEY,
/**
* Publish this device's contribution to the key. Every member's is mixed in, so
* this is the point at which the member's own secret material starts shaping a
* key they will be expected to help sign with.
* Publish this device's contribution to the key. Asked about by older builds;
* now taken automatically once every host key is in.
*/
ROUND_1,
/**
* Sign to confirm the coordinator's combined result matches what this device
* sent. Refusing here is what stops a coordinator substituting a different key
* than the members contributed to, so it is a check, not a formality.
* sent. Asked about by older builds; now taken automatically, since the device
* is what makes the check -- a mismatch fails the ceremony with nobody looking.
*/
ROUND_2
}
@@ -303,9 +303,8 @@ object ChillDkgRitualManager {
round1Random = RandomInstance.bytes(32).toHex(),
round2AuxRandom = RandomInstance.bytes(32).toHex(),
// Opening a ceremony is already the act of agreeing to be in it, so this
// member is not asked again to publish the host key they just committed
// the group to. Rounds 1 and 2 are still asked for: those publish key
// material, and by then the ceremony has other people in it.
// member is never asked about it: joining is the only approval a
// ceremony asks for, and this is it.
hostKeyApprovedAt = Clock.System.now(),
// What this ceremony is for, if it is for anything in particular. The
// coordinator's own copy of the claim they are about to put on the
@@ -732,10 +731,16 @@ object ChillDkgRitualManager {
val hostSeckey = deriveHostSecretKey(nostrPrivateKey)
try {
// Nothing of this device's own goes out before its owner has said so.
// Each gate returns rather than throwing: the ritual is not failing, it
// is waiting on a person, and everything already received stays stored
// so it resumes the moment they approve.
// Nothing of this device's own goes out before its owner has said so,
// and joining is the one thing they are asked. It returns rather than
// throwing: the ritual is not failing, it is waiting on a person, and
// everything already received stays stored so it resumes the moment
// they approve.
//
// Rounds 1 and 2 used to be gates of their own. They were never
// decisions: contributing follows from having joined, and confirming
// is the check ChillDKG makes below, which refuses a mismatch whether
// or not anybody is looking. See docs/automatic-key-ceremony.md.
if (session.hostKeyApprovedAt == null) return
if (ownMessage(database, session, DkgRitualEvents.HOST_KEY) == null) {
@@ -746,13 +751,6 @@ object ChillDkgRitualManager {
// nothing this device can compute yet.
val hostPublicKeys = hostPublicKeys(database, session) ?: return
// A second decision, and a different one: the host key only joined the
// ceremony, this contributes to the key itself.
if (session.round1ApprovedAt == null) {
announceApprovalNeeded(database, session, DkgApprovalStep.ROUND_1)
return
}
val step1 = ChillDKG.participantStep1(
hostSecretKey = hostSeckey,
hostPublicKeys = hostPublicKeys,
@@ -781,15 +779,12 @@ object ChillDkgRitualManager {
val coordinatorRound1 = session.coordinatorRound1 ?: return
// The last decision, and a real check rather than a formality: signing
// here asserts the combined result matches what this device sent, which
// is what stops a coordinator swapping in a key the members never
// contributed to.
if (session.round2ApprovedAt == null) {
announceApprovalNeeded(database, session, DkgApprovalStep.ROUND_2)
return
}
// A real check rather than a formality: signing here asserts the
// combined result matches what this device sent, which is what stops a
// coordinator swapping in a key the members never contributed to. The
// device makes it -- `participantStep2` faults on a mismatch, and the
// catch below fails the ceremony for everyone -- so a person approving
// it would add nothing to it.
val step2 = ChillDKG.participantStep2(
hostSecretKey = hostSeckey,
state = step1.state,
@@ -1115,32 +1110,21 @@ object ChillDkgRitualManager {
* What this ritual is waiting on its owner for, or null if it is waiting on
* somebody else — or on nothing, being finished.
*
* Mirrors the gates in [advance] rather than duplicating their reasoning: a step
* is pending exactly when [advance] would stop at it. The two must agree, or the
* screen offers an approval that does nothing, or none while the ritual sits
* still.
* Mirrors the gate in [advance]: a step is pending exactly when [advance] would
* stop at it. The two must agree, or the screen offers an approval that does
* nothing, or none while the ritual sits still. There is one gate now, joining;
* rounds 1 and 2 were gates until docs/automatic-key-ceremony.md, and are never
* returned here.
*
* Still suspending and still handed the database, though this reading needs
* neither, so a gate that does need them can come back without every caller
* changing shape.
*/
@Suppress("UNUSED_PARAMETER", "RedundantSuspendModifier")
suspend fun pendingApproval(database: GizaDatabase, session: DkgSession): DkgApprovalStep? {
if (session.stage == DkgRitualStage.COMPLETE || session.stage == DkgRitualStage.FAILED) return null
if (session.hostKeyApprovedAt == null) return DkgApprovalStep.HOST_KEY
if (session.round1ApprovedAt == null) {
// Nothing to contribute to until the participant set is settled: round 1
// is computed over every member's host key, so asking earlier would be
// asking about a ceremony whose shape is not yet known.
val hostKeys = database.dkgSessionDao()
.countMessagesByKind(session.id, DkgRitualEvents.HOST_KEY)
return if (hostKeys >= session.participantCount) DkgApprovalStep.ROUND_1 else null
}
if (session.round2ApprovedAt == null) {
// Nothing to check until the coordinator has combined the contributions.
return if (session.coordinatorRound1 != null) DkgApprovalStep.ROUND_2 else null
}
return null
return if (session.hostKeyApprovedAt == null) DkgApprovalStep.HOST_KEY else null
}
/**
@@ -1188,11 +1172,15 @@ object ChillDkgRitualManager {
/**
* Records that this device's owner agreed to [step], then lets the ritual run as
* far as the next thing it is waiting on.
* far as the next thing it is waiting on -- which, once they have joined, is
* the end of the ceremony or another member.
*
* Approving a step it is not actually waiting on is a no-op rather than an error:
* a stale screen left open across a redelivery should not publish anything, and
* the caller has no way to know the ritual has moved on since it was drawn.
* the caller has no way to know the ritual has moved on since it was drawn. That
* covers [DkgApprovalStep.ROUND_1] and [DkgApprovalStep.ROUND_2] too, which
* [pendingApproval] no longer returns: a screen for either left open across the
* upgrade does nothing.
*/
suspend fun approve(
database: GizaDatabase,
@@ -1263,6 +1251,9 @@ object ChillDkgRitualManager {
"Your approval is needed to join the shared key ceremony. Nothing has been " +
"published from this device yet."
// Never reached: rounds 1 and 2 are no longer asked for. Kept because the
// enum keeps the values for rows that recorded asking, and this is the
// wording those rows were written with -- MIGRATION_3_4 matches on it.
DkgApprovalStep.ROUND_1 -> ChatMessage.TYPE_DKG_APPROVAL_NEEDED_ROUND_1 to
"Everyone has joined the shared key ceremony. Your approval is needed to " +
"contribute to the key."
@@ -1,5 +1,6 @@
package mobi.giza.compose.managers
import com.vitorpamplona.quartz.nip01Core.core.Event
import fr.acinq.bitcoin.ByteVector32
import fr.acinq.bitcoin.PrivateKey
import fr.acinq.bitcoin.crypto.frost.Frost
@@ -8,10 +9,12 @@ import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertNotNull
import kotlin.test.assertNull
import kotlin.test.assertTrue
import kotlinx.coroutines.runBlocking
import mobi.giza.compose.database.model.types.DkgApprovalStep
import mobi.giza.compose.database.model.types.DkgRitualStage
import mobi.giza.compose.extensions.toHex
import mobi.giza.compose.nostr.dkg.DkgRitualEvents
/**
* A key ceremony run from proposal to key, across devices, with real ChillDKG.
@@ -19,53 +22,139 @@ import mobi.giza.compose.extensions.toHex
* Every other ceremony test stops at the host key, or gets its key from a trusted
* dealer, so the rounds -- the part that makes the key -- were only ever run on a
* phone. [CeremonyNetwork] plays the relay.
*
* Joining is the only thing a member is asked (docs/automatic-key-ceremony.md), so
* every ceremony here is driven by joins and deliveries and nothing else.
*/
class CeremonyAcrossDevicesJvmTest {
/**
* Today's gates, pinned: joining is not enough. Every member stops at round 1
* and waits to be asked, and stops again at round 2.
*/
/** The whole change: after the joins, nobody is asked anything and the key exists. */
@Test
fun `members who have only joined are each asked to contribute`(): Unit = runBlocking {
fun `members who have only joined finish the ceremony`(): Unit = runBlocking {
CeremonyNetwork.nip17(size = 3).use { network ->
val session = network.propose(threshold = 2)
network.deliverUntilQuiet()
network.devices.drop(1).forEach { member ->
assertEquals(DkgApprovalStep.HOST_KEY, network.pendingApproval(member, session.id))
network.approve(member, session.id, DkgApprovalStep.HOST_KEY)
}
joinAll(network, session.id, network.devices)
network.deliverUntilQuiet()
network.devices.forEach { device ->
assertEquals(
DkgApprovalStep.ROUND_1,
network.pendingApproval(device, session.id),
"$device waits to be asked to contribute",
)
assertEquals(DkgRitualStage.COLLECTING_HOST_KEYS, network.session(device, session.id)!!.stage)
assertNull(network.pendingApproval(device, session.id), "$device is asked nothing more")
}
assertOneKey(network, session.id, network.devices)
}
}
/** With every approval given, every device ends with the same key. */
/** Opening a ceremony is joining it, and the coordinator is never asked a thing. */
@Test
fun `a group's own ceremony makes one key across three devices`(): Unit = runBlocking {
fun `the coordinator is never asked`(): Unit = runBlocking {
CeremonyNetwork.nip17(size = 3).use { network ->
val session = network.propose(threshold = 2)
assertNull(network.pendingApproval(network.coordinator, session.id))
network.deliverUntilQuiet()
assertNull(network.pendingApproval(network.coordinator, session.id))
joinAll(network, session.id, network.devices)
network.deliverUntilQuiet()
assertEquals(DkgRitualStage.COMPLETE, network.session(network.coordinator, session.id)!!.stage)
}
}
/**
* The last member to join already holds everyone else's host key, so the one
* approval carries them straight on into contributing.
*/
@Test
fun `the last member to join contributes in the same approval`(): Unit = runBlocking {
CeremonyNetwork.nip17(size = 3).use { network ->
val (_, first, last) = network.devices
val session = network.propose(threshold = 2)
network.deliverUntilQuiet()
for (step in DkgApprovalStep.entries) {
network.devices.forEach { device ->
if (network.pendingApproval(device, session.id) == step) {
network.approve(device, session.id, step)
network.approve(first, session.id, DkgApprovalStep.HOST_KEY)
network.deliverUntilQuiet()
assertTrue(network.sent(last, DkgRitualEvents.HOST_KEY).isEmpty())
network.approve(last, session.id, DkgApprovalStep.HOST_KEY)
assertEquals(1, network.sent(last, DkgRitualEvents.HOST_KEY).size)
assertEquals(
1,
network.sent(last, DkgRitualEvents.ROUND_1).size,
"joining last puts the contribution out with the host key",
)
}
}
/**
* What the round-2 approval was said to protect against, and the reason it was
* never a person's to give: a combined result that is not the one every member
* contributed to never becomes anybody's key. ChillDKG catches it -- a member
* whose share it breaks refuses at round 2, and otherwise the confirmations
* disagree and no certificate can be made over them -- and the ceremony ends
* for everyone with nobody asked anything.
*
* Here the change is in transit, so the coordinator is honest and is the one
* that finds the confirmations disagree and says so.
*/
@Test
fun `a combined result that was tampered with becomes nobody's key`(): Unit =
runBlocking {
CeremonyNetwork.nip17(size = 3).use { network ->
network.tamper = { sender, _, event ->
if (sender === network.coordinator && event.kind == DkgRitualEvents.COORDINATOR_ROUND_1) {
Event(
id = event.id,
pubKey = event.pubKey,
createdAt = event.createdAt,
kind = event.kind,
tags = event.tags,
content = flipLastByte(event.content),
sig = "",
)
} else {
event
}
}
network.deliverUntilQuiet()
}
assertOneKey(network, session.id, network.devices)
val session = network.propose(threshold = 2)
network.deliverUntilQuiet()
joinAll(network, session.id, network.devices)
network.deliverUntilQuiet()
network.devices.forEach { device ->
val theirs = assertNotNull(network.session(device, session.id))
assertEquals(DkgRitualStage.FAILED, theirs.stage, "$device: the ceremony ended")
assertNull(theirs.thresholdPublicKey, "$device holds no key")
assertNull(theirs.secretShare, "$device keeps no share of one")
assertNull(network.pendingApproval(device, session.id), "$device was asked nothing")
}
// Which device notices depends on which bytes were changed. That
// somebody did, out loud, is what lets the rest stop waiting.
assertTrue(
network.devices.any { network.sent(it, DkgRitualEvents.FAILURE).isNotEmpty() },
"somebody told the group",
)
}
}
/** A round approval from a screen left open across the upgrade publishes nothing. */
@Test
fun `approving a round does nothing`(): Unit = runBlocking {
CeremonyNetwork.nip17(size = 3).use { network ->
val member = network.devices[1]
val session = network.propose(threshold = 2)
network.deliverUntilQuiet()
network.approve(member, session.id, DkgApprovalStep.ROUND_1)
network.approve(member, session.id, DkgApprovalStep.ROUND_2)
assertTrue(network.sent(member, DkgRitualEvents.HOST_KEY).isEmpty(), "it has not joined")
assertTrue(network.sent(member, DkgRitualEvents.ROUND_1).isEmpty())
assertEquals(DkgApprovalStep.HOST_KEY, network.pendingApproval(member, session.id))
}
}
@@ -90,20 +179,24 @@ class CeremonyAcrossDevicesJvmTest {
)
network.deliverUntilQuiet(random)
for (step in DkgApprovalStep.entries) {
picked.forEach { device ->
if (network.pendingApproval(device, session.id) == step) {
network.approve(device, session.id, step)
}
}
network.deliverUntilQuiet(random)
}
joinAll(network, session.id, picked)
network.deliverUntilQuiet(random)
assertOneKey(network, session.id, picked)
assertNull(network.session(outsider, session.id), "the member not picked records nothing")
}
}
private suspend fun joinAll(
network: CeremonyNetwork,
sessionId: String,
devices: List<CeremonyNetwork.Device>,
) = devices.forEach { device ->
if (network.pendingApproval(device, sessionId) == DkgApprovalStep.HOST_KEY) {
network.approve(device, sessionId, DkgApprovalStep.HOST_KEY)
}
}
private suspend fun assertOneKey(
network: CeremonyNetwork,
sessionId: String,
@@ -135,5 +228,11 @@ class CeremonyAcrossDevicesJvmTest {
threshold = 2
).thresholdPublicKey.value.toHex()
)
/** The same bytes with the last one changed: well-formed, and wrong. */
fun flipLastByte(hex: String): String {
val last = hex.takeLast(2).toInt(16) xor 0x01
return hex.dropLast(2) + last.toString(16).padStart(2, '0')
}
}
}
@@ -59,6 +59,18 @@ class CeremonyNetwork private constructor(
/** Which messages each device has already been handed, by device and event id. */
private val delivered = mutableSetOf<Pair<HexKey, HexKey>>()
/**
* What the relay does to a message on its way to one receiver: the identity by
* default. A test standing in for a dishonest sender rewrites it here, which is
* the same as the sender having written it that way -- nothing on the path
* checks a rumor's id against its content.
*/
var tamper: (sender: Device, receiver: Device, event: Event) -> Event = { _, _, event -> event }
/** Everything [device] has queued for its room, of [kind]. */
suspend fun sent(device: Device, kind: Int): List<Event> =
outboundOf(device).filter { it.kind == kind }
val coordinator: Device get() = devices.first()
/** The device's own copy of the room, read fresh: the ritual rewrites it. */
@@ -116,11 +128,13 @@ class CeremonyNetwork private constructor(
devices
.filter { it !== sender }
.filter { (it.publicKey to event.id) !in delivered }
.map { receiver -> receiver to event }
.map { receiver -> Triple(sender, receiver, event) }
}.let { if (random != null) it.shuffled(random) else it }
handings.forEach { (receiver, event) ->
delivered += receiver.publicKey to event.id
handings.forEach { (sender, receiver, sent) ->
delivered += receiver.publicKey to sent.id
val event = tamper(sender, receiver, sent)
store(receiver, event)
ChillDkgRitualManager.processRitualPayload(
database = receiver.db,