Files
giza-kmp/docs/confederation.md
T
Kgothatso NgakoandClaude Opus 5.5 d1513ef2d0 docs: the record of a confederation with no coordinator (confederation-without-coordinator, Phase 9)
Phases 0 to 8 built, with what each turned out to be; since-notes in
confederation.md where its coordinator, seal and opening no longer describe
the app. The device run has not been done.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 14:14:17 +02:00

73 KiB
Raw Blame History

Confederation: a group made of groups

A plan for several Giza groups to agree, in public, to form a confederation, and then to hold one key between them. It also covers getting a Marmot room for the confederation whose id is derived from that key, and having the confederation sign as itself.

The flow, as asked for:

  1. A member of group A proposes that A sign a ConfederationProposalEvent. The event lists the npubs of every group invited (A's included) and the npub of the member who proposed it. That member becomes the coordinator of the confederation's key ceremony.
  2. The signed proposal is broadcast. Each invited group answers by signing either a ConfederationProposalAcceptanceEvent or a ConfederationProposalRejectionEvent.
  3. An acceptance carries the group's admin pubkeys, encrypted so that only the coordinator can read them. Every member who signs off on an acceptance first computes the same ciphertext on their own device and checks it byte for byte.
  4. Once every invited group has accepted, the coordinator opens a NIP-17 room with every admin of every group and runs the confederation's DKG there.
  5. When the DKG finishes, the confederation gets a Marmot room whose id is derived from the confederation's key, and it can sign events as that key.

Only groups with a public nostr profile can take part.

Read these first:

  • shared-key-ceremony.md. The confederation's DKG copies its shape: inputs are stored rather than state, joining is the only approval, and faults are values.
  • subgroups.md. It is the closest precedent: one group's quorum signs a statement about another group, and a ceremony runs over a set of people that is not one room's membership.
  • group-nostr-profile-and-posts.md. It defines what a group's public profile is, and how a group-signed event reaches relays.
  • confederation-submodule-update.md. It describes the cryptography this plan ends on, and why that cryptography cannot run across devices yet.

Written against c9e6f07c on 2026-11-21. Parts A, B and C are built, behind ExperimentalFeatures.confederation, one commit per phase: Part A (phases 0 to 8) on claude/confederation-implementation-plan-a24dc6, Phase 9 upstream (confederation-upstream.md), Part B (phases 10 to 13) on claude/confederation-part-b and Part C (phases 14 and 15) on claude/confederation-part-c. Phase 16's device run is what is left. jvmTest went from 1,569 to 1,630, all passing, and ./gradlew check passes: m3Audit, brandAudit and walletAudit are at their budgets, and compileDebugKotlinAndroid builds.

Not done: nothing here has run on a device. No proposal has crossed real relays between real groups, no ceremony or signing attempt has run on more than one real device, and no iOS build has been made. The confederation's room cannot yet change its members: admin changes signed by the confederation are not built. Upstream's independent review of the step interface is still pending (doc/confederation-review.md section 21), which is why the flag stays off in release. 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
D4: canSign means admin not while refresh is experimental: a demoted admin keeps a share. The coordinator is also checked against RoomAdmins.of, on the form and on every signer (Phase 0)
Phase 3, then Phase 4 4 first. A refusal has to outlive the proposal's arrival (approval checks again, the decline says why, a resend carries the seal), so it needed somewhere to live
Phase 4: ConfederationProposal and ConfederationAnswer tables, a ConfederationGroup cache one ConfederationEvent table for every kind, ConfederationInvitee to find proposals by group, and ConfederationSigning per signing session. No cache: D2's lookups land in the Profile rows the profile preview already writes
D5: the seal's secret rides the FROST proposal and so does the proposal an answer answers (confederation_proposal), signed and verified like a relay's copy, so a signer does not depend on its relays having delivered it
D8: an expiry passed before ACCEPTED an answer counts only if its own created_at is by the expiry, so whether a proposal was accepted in time does not depend on when a device heard of it
D9: frostSigningSessionId on the proposal row ownSessionId and publishedAt on every ConfederationEvent, set by onSigned on the coordinating device and drained by ConfederationPublisher with backoff
Phase 5: subscribe on the bootstrap relays and the hints on the publish set, where the publisher sends. Hints add targets when publishing
Phase 6: relay hints on the proposal's p tags written empty. The profile lookup does not say which relay answered
Phase 6: an …_EXPIRED line none. Nothing happens at an expiry to write one from; the state says it
Phase 6: the form's state as a Compose state a MutableStateFlow updated atomically. A lookup settling on an IO thread and a group added on the main one lost updates under the full suite
Phase 7: invitations feed observeProposalsAwaitingYou not done. That feed is shaped around FROST sessions; the transcript line is the notice
Phase 7: the run on SignedGroupKeyStateTest's harness ConfederationNetworkJvmTest, its own three groups of three devices each, with real FROST signatures and relays as copies. It found an answer filed before its proposal losing its line; a proposal now writes the lines for answers already held
Phase 8: the coordinator decrypts with the active identity's own key, so an npub-only identity that coordinated (it cannot, since it cannot propose) would see nothing
Phase 10: hash inputs only ConfederationRosterBuilder also writes the roster's bytes: upstream has fromData and no builder
Phase 11: one host key message per role one message per person per step, a value per role keyed by group, so a person in two groups joins once
Phase 11: 30386, the coordinator's certificate not sent. Every device assembles the certified genesis itself from evidence it already holds, so nobody can hand one over
Phase 11: investigation (30388) not built. A decryption fault names "a participant or the coordinator" and ends the ceremony
Phase 11: the coordinator's device opens it on its own a button on the proposal screen once the outcome is ready; opening is the coordinator's join
Phase 11: a group's admins checked through its sealed list the admins compared on their own, so a member without a share (and so without the threshold) still checks; the threshold where it can be read
Phase 12: ConfederationKeyStateEvent (30389) not built. Every founding member holds the record; ConfederationFormation.verifies checks it. A member added later needs one, and that waits for Part C's governance
Phase 12: a line posted into each group's room by the coordinator a line each admin's own device writes in its own group rooms, sending nothing
Phase 13: MarmotGroupCreation.createForConfederation ConfederationFollowThrough calling MarmotGroupCreation.create directly, as subgroups do
Phase 14: a group coordinator per group, the outer coordinator aggregating only the selection is coordinated. The transcript, the certificate, every group's partial and the signature take no secret, so every device computes them and checks the signature against the room's id
Phase 14: kinds 30390 to 30399 30390 to 30395 and 30399; the rest unused
Phase 14: the selection "in the order approvals arrive" the first T groups in roster order with t_g yeses, the lowest admins first, so the selection does not depend on delivery order once enough have said yes
Phase 15: the confederation's kind:0 and kind:1 through GroupNostrProfile and GroupPost the same editors and readers, with ChatRepository.canSignAsConfederation and proposeAsConfederation deciding which signer a room's statements go to
Phase 15: a charter that each group's members find on relays as planned, kind 9434, carried by Part A's publisher and subscription; a device signs only one naming exactly the confederation's groups
Phase 15: governance of the room through GovernanceManager not built: the room stays fixed at its founding members

Progress

phase result
0 done. 9430–9433 appear in neither the NIP README's kind table (nothing between 9321 and 9734), quartz 2.20.1, Curare nor Bennu. Nip44v2.getConversationKey and encryptWithNonce are public in quartz 2.20.1. A demoted admin can still hold a share of the active generation while refresh is experimental, so canSign does not imply admin: D4 now checks it
1 done. ConfederationRoomKeyJvmTest 3/3: replaying SharedKeyDerivation.Derived.tweaks (new; the scalars derive applies) as x-only ConfederationTweaks signs as marmotGroupId(02‖X), and the event verifies through isSignedByRoom, so D10 stands. ConfederationKindsTodayJvmTest pins 9430–9432 reaching the member as "Event of kind N". ConfederationSealPremiseJvmTest 3/3 against quartz's Nip44v2. ConfederationFixture and SigningProposalHarness lifted for the phases after
2 done. nostr/confederation/: ConfederationKinds, the proposal, acceptance, rejection and withdrawal events, ConfederationAdminList (decodes only its own encoding), ConfederationSeal, ConfederationStatus, five tag classes. ConfederationEventsTest 27/27; RetiredKindsTest checks the family is nobody else's and regular. An answer counts only if made by the proposal's expiry, so ACCEPTED does not depend on when a device heard. The seal tag rides the FROST proposal through ConfederationSealTag rather than FrostSigningEvents.assembleTags
3 done. ConfederationRefusal in all four places in FrostSigningManager: on arrival, again at approval (the admins can change while a member decides), as the decline's reason, and in the resend, which carries the seal again. Two tags ride the FROST proposal: confederation_seal and, for an answer, confederation_proposal, the signed 9430 it answers, so a signer does not depend on its relays (verified and filed like a relay's copy). proposeSigningBatch takes proposalTags. ConfederationManager.proposeConfederation, proposeAcceptance, proposeRejection and proposeWithdrawal build them. ProposedEvent summarises the four kinds. ConfederationDeclineJvmTest 16/16 replaces the Phase 1 pin. The warnings half of D6 waits for the approval screen (Phase 7). Full jvmTest 1,569, all passing once ShippedProfileUpgradeJvmTest was moved to 43
4 done, before 3, because the refusals need somewhere to keep the seal and the reason past arrival. Schema 43: ConfederationEvent (every kind in one table, keyed by event id, indexed by the proposal it is about), ConfederationInvitee (which proposals name a group) and ConfederationSigning (per signing session: the seal secret, the carried proposal, the refusal). No ConfederationGroup cache: D2's lookups land in the existing Profile rows. ConfederationManager.record verifies the author's signature and files; status computes D8 from the rows. The repository waits for Phase 6, its first caller. ConfederationStorageJvmTest 5/5
5 done. ExperimentalFeatures.confederation, on in development builds. LiveSubscriptionManager holds live-confederation on the publish set while it is on: every confederation kind #p-tagged to one of our Marmot rooms, and every answer #e-tagged to a proposal not yet expired, re-sent when either changes. What arrives goes to ConfederationRepository.record, never saveNostrEvent. FrostSigningManager.complete calls ConfederationManager.onSigned, which files the signed events on every device and, on the coordinator's, marks them owed (ConfederationEvent.ownSessionId, publishedAt, folded into schema 43 since it has not shipped). ConfederationPublisher, run by SynchronizationViewModel, sends owed events to the publish set and the proposal's hints and backs off from a minute to half an hour until a relay takes each. BROADCASTABLE_KINDS gains 9430–9433. ChatMessage.applyInnerEvent draws nothing for these kinds rather than a raw-JSON bubble. ConfederationRelayTest 6/6, ConfederationStorageJvmTest 7/7
6 done. Four system lines (TYPE_CONFEDERATION_PROPOSED, …_ACCEPTED, …_REJECTED, …_WITHDRAWN) written by ConfederationManager.record in every local room the proposal names, once per event because the event row is written once. No line for an expiry: nothing happens at an expiry to write one from. A "Confederations" row on the group's screen while the flag is on, for every member of a Marmot room. ConfederationsScreen watches every proposal naming the group. ProposeConfederationScreen looks every group up on the relays, this one included, and its button waits on a name, an admin, a share, a group that can take part and every group found. Relay hints are not written yet: the profile lookup does not say which relay answered. Its view model's state is a MutableStateFlow updated atomically, because a lookup settling on an IO thread and a group added on the main one lost updates under the full suite. ConfederationRepository.NO_OP_CONFEDERATION_REPOSITORY for fakes. ProposeConfederationViewModelJvmTest 8/8, ConfederationScreensJvmTest 4/4, ConfederationStorageJvmTest 9/9. jvmTest 1,591, m3Audit, brand and wallet audits clean
7 done but for the badge. ConfederationProposalScreen, opened from each card: the proposal, its coordinator, every group's answer, and for a member with a share either both answers (in an invited group that has not answered) or withdrawal (in the proposing group), giving way to a pending answer's session. The approval screen shows D6's notes: the groups by name, T, the coordinator, what an acceptance discloses, and each listed group with no public profile on this device, as a warning. ConfederationNetworkJvmTest 3/3 is the plan's three-group run: real FROST signatures per group, relays as copies, every device on every group agreeing on REJECTED and then on ACCEPTED, and the coordinator opening each group's admins. It found answers filed before their proposal losing their line, since a proposal and its proposer's acceptance share a second and relay order is by id; a proposal now writes the lines for answers already held. Not done: invitations do not feed observeProposalsAwaitingYou, which is FROST-session shaped; the transcript line is the notice. jvmTest 1,598
8 done. ConfederationManager.outcome on the coordinator's device opens each acceptance with the active identity's key, checks each list names its group and proposal, counts roles (refusing more than 128, noting more than 16), names any listed group with no public profile on this device as what stands in the way, and lists admins who sit in more than one group. The proposal screen shows it once every group has accepted, ending on "the confederation's key ceremony is not available in this version yet". Withdrawal was built with the answers in Phases 3 and 7. ConfederationNetworkJvmTest 5/5, ConfederationStorageJvmTest 11/11
10 done. ConfederationRosterBuilder writes upstream's RPD bytes itself, since ConfederationRoster has only fromData: big-endian, a 96-byte header, 20 bytes a group, 69 a role. plan refuses rather than repairs (a list for another group or proposal, a missing acceptance, more than 128 roles). Host keys are sha256(HOST_KEY_TAG ‖ nsec ‖ group ‖ proposal id), so one person holds a different key per role and per confederation. ConfederationRosterBuilderJvmTest 7/7: the roster parses, is byte-identical under any input order, and its dkgLocal key signs as the room's id
11 done. ConfederationRitualManager over upstream's ConfederationDkg, in a NIP-17 room the coordinator opens over every admin (with placeholder profiles for members this device has none for). Kinds 30380 (opening), 30381 (host keys), 30382 (dealings), 30383 (roster and broadcast), 30384 (authorizations), 30385 (acknowledgments), 30387 (failure). One message per person per step, one value per role, keyed by group. No 30386: every device assembles the certified genesis itself from evidence it already holds, so nobody can hand one over. No investigation (30388): a decryption fault names "a participant or the coordinator" and ends the ceremony. Before joining, a device checks the proposal and acceptances are their groups' own, every acceptance opens with its disclosed key, the room is exactly the roster's people, and each group it is in still has the admins it accepted with, compared on their own so a member without a share still checks. Joining is the only approval; dealer seeds are erased once dealt; every role derives its key state itself and the coordinator's roster must match byte for byte. Schema 44. The coordinator opens it by a button on the proposal screen rather than on its own. ConfederationRitualScreen, with a join, each step's named waits and abandon. ConfederationCeremonyJvmTest 7/7: three groups of three on nine devices reach one key that signs as the room once each recovery package is opened; one person in two groups; a holdout and abandon; a disclosed key that does not open; a substituted roster; admins changed; messages before the opening. jvmTest 1,619
12 done. ConfederationFormation.onComplete files a Confederation (room id, X, roster, key state, genesis, the (configSeq, rpdHash, ksdHash) triple, this device's recovery packages) and ConfederationMember rows, folded into schema 44 since it has not shipped. The genesis is verified against the key state before anything is written. A line goes into each of this device's own member groups' rooms; nothing is sent to them. No 30389 key-state event: every founding member of the room took part and holds the record, so ConfederationFormation.verifies checks the stored descriptors instead; a member added later needs one, which waits for Part C's governance. A formed confederation reads "Formed" on the group's list. ConfederationCeremonyJvmTest now also checks every device files the same verified confederation under the room its key derives
13 done. ConfederationFollowThrough on the coordinator's device makes the room once every member's key package is in, retrying when one arrives, through MarmotGroupCreation.create rather than a new createForConfederation: id marmotGroupId(02‖X), a random routing address, every role holder a member and an admin, #name, born governed with Quorum.minimumAdmins(T). A record that no longer verifies, or a device holding no role, makes no room. Adoption needs no new check: every founding member holds the Confederation row under the room's id, and confederationOfRoom reads it only if it verifies. The room's screen says whose room it is and that its members are fixed until the confederation can sign. ConfederationCeremonyJvmTest 9/9. ./gradlew check passes, jvmTest 1,621
14 done. ConfederationSigningManager over upstream's ConfederationSigning, in the confederation's Marmot room. Kinds 30390 (proposal), 30391 (each person's yes or no per role), 30392 (the proposer's selection and D_sign), 30393 (nonces), 30394 (confirmations), 30395 (partials), 30399 (failure). Only the selection is coordinated: the first T groups in roster order with t_g yeses, the lowest admins first. The transcript, the certificate, every group's partial and the signature take no secret, so every device computes them itself and checks the signature against the room's id before keeping it: no group coordinator and no outer coordinator message. Signer state is held in memory only; a device that restarts after sending a nonce ends the attempt out loud on its next step, and resumeRunning does it on start. A confederation signs kinds 0 and 1 only, with Part A's statement refusals; anything else is declined out loud. A signed event lands in GroupSignedEvent under the room, so the existing profile, posts and broadcast screens read it. Schema 45. ConfederationSigningJvmTest 5/5 on nine devices: a profile signed and read back on every device; two groups of two admins enough; a restart between nonces and confirmations failing it everywhere; too many declines; refused kinds. jvmTest 1,626
15 done but for governance. Profile and posts: the existing editors work in a confederation's room. ChatRepository.canSignAsConfederation opens them to a role holder, and proposeAsConfederation sends the proposal through ConfederationSigningManager instead of FROST; the signed event lands where the profile and posts screens and the broadcast screen already read. Charter (9434): the confederation's own public statement naming its groups, proposed from its room's card. A device signs only a charter naming exactly the confederation's groups under its name. Once signed it is filed as Part A's events are and owed to relays by the proposer's device, and every member group's devices hear it through the existing #p filter and write a line in the group's room. That is how members who are not admins learn of it. ConfederationSigningScreen approves or declines for every role a person holds and lists who has answered, opened from the line in the room's transcript (the line carries the attempt id) or after proposing. Not done: admin changes in the confederation's room signed by the confederation; the room stays fixed at its founders. ConfederationSigningJvmTest 7/7, ConfederationScreensJvmTest 12/12. ./gradlew check passes, jvmTest 1,630
16 the record done; the device run not. No ceremony or signing attempt has run across real devices, relays or an iOS build

The constraint that shapes the plan

The cryptography exists, but only in one process. bitcoin-kmp's fr.acinq.bitcoin.crypto.confederation offers Confederation.dkgLocal and signLocal. Both take a host secret key and a share for every role in the roster. Its KDoc calls them "a simulation and test harness, not a distributed protocol". The round-by-round functions exist only as static functions in zkp's src/modules/confederation/. zkp's own doc/confederation-implementation-plan.md §3.7 plans public participant and coordinator step APIs, but they are not public yet. The module is also marked "experimental research code … must not be used in production or to protect value".

So the plan has three parts, and only the first can be built now:

part phases what it delivers blocked on
A. Agreeing to form 0–8 the three public events, the checks each device makes before signing them, relays, screens. The coordinator ends holding every group's verified admin list nothing
B. Forming 9–13 the confederation's DKG across devices in a NIP-17 room, then its Marmot room zkp publishing the DKG step API, bound in secp256k1-kmp and wrapped in bitcoin-kmp
C. Acting 14–16 confederation-signed events, its profile, governance of its room the same for nested signing ("Option A")

Part A is useful on its own. Its output is exactly what Part B needs as input: a set of groups, each of which has committed with a quorum signature to a list of admins and an inner threshold, and a coordinator who can read all of it. Part A is built so that Part B adds to it without changing it.

Everything here goes behind ExperimentalFeatures.confederation, a new flag beside shareRefresh that is off in release, until upstream drops the experimental label.


What the cryptography expects

The facts below come from bitcoin-kmp 0c34097 and zkp c68e2384 (doc/confederation-protocol.md, doc/nested-dkg.md). Many decisions follow from them.

The DKG makes fresh shares. It does not reuse the groups' FROST keys. It is a single joint-Feldman ceremony. Every admin of every group is both a dealer and a recipient. It produces a confederation key X, a per-group constant Y_g, and a new share for each admin. A group's own threshold key takes no part. nested-dkg.md §3 explains why: a group's FROST key cannot be an outer host key, because "there is no single group host secret". So a group's quorum signature in Part A is what ties the group to its admins in the roster. Nothing in the cryptography does that.

The roster (RPD) has no group public keys. A group is a groupId from 0 to N-1. A role is (adminId, entityId, hostPubkey).

  • entityId is 32 bytes of "externally attested metadata".
  • The roster carries one attestationRef, a 32-byte hash that refers to evidence outside the roster.

The application decides what goes in both. This plan sets entityId to the admin's nostr pubkey, and attestationRef to a hash over the proposal and the acceptances (Phase 10).

The limits.

limit value
outer threshold T (how many groups must take part in a signature) 2 ≤ T ≤ N
inner threshold t_g (how many admins of group g must take part) 2 ≤ t_g ≤ n_g
groups at most 64
roles, across all groups at most 128
access() analysis at most 16 roles

A host key is per role, not per person. The roster refuses a host key that appears twice anywhere. So an admin who sits in two of the groups needs two host keys. The host key signs dealer records, transition authorizations and signing confirmations, derives the transport pads, and keys the recovery package. "Compromising a host key exposes that role's shares in every epoch where the key was registered."

Nested signing (Option A) has two coordinators. Each group's partial signatures are aggregated by a group coordinator, then an outer coordinator aggregates across groups. The result is an ordinary BIP 340 signature under X, optionally tweaked. Up to 64 x-only tweaks are allowed, so Giza's room-key derivation is expressible (Phase 1 proves this). Nonce state must stay in memory only, be used once, and be erased on abort. That is the opposite of FrostSigningManager, which stores its nonce randomness so it can resume after a restart (Phase 14).


Decisions

D1. The public events are regular nostr events, with new kinds

The proposal, acceptance and rejection have to cross from one group to another, and the groups share no room. They go to relays as ordinary signed events, each authored by a group's npub, which is its room id (shared-key-derivation.md).

They use regular kinds (1000–9999), not the 303xx range. Every 303xx kind in this app is a rumor that never leaves an encryption, so relay semantics never mattered for them. These are public, and 30000–39999 is NIP-01's addressable range, where a relay keeps only the newest event per (kind, pubkey, d). A group that signed a second event at the same address would make the one every acceptance points at disappear from relays. Regular events are kept, and are referred to by id.

class kind author content
ConfederationProposalEvent 9430 the proposing group a sentence for other clients
ConfederationProposalAcceptanceEvent 9431 an invited group NIP-44 ciphertext for the coordinator
ConfederationProposalRejectionEvent 9432 an invited group an optional reason, in plain text
ConfederationProposalWithdrawalEvent 9433 the proposing group an optional reason (Phase 8, optional)

The numbers are provisional. Phase 0 checks them against the NIP kind registry, and against the kinds Bennu and Curare use, before any code is written. RetiredKindsTest's map of live kind sets gets the new family, as FrostSigningEvents' KDoc asks of any new family.

D2. "A public nostr profile" means relays return a kind:0 authored by the group's npub

Today "has a profile" means only that this device holds a verified group-signed kind:0 (GroupNostrProfile.of over GroupSignedEvent). Broadcasting is a separate, manual step, and nothing records it (D7 of the profile note). A profile the group signed and never sent is not public, so the local row is not enough.

The rule, applied at three points:

where check if it fails
proposing, for every listed group, the proposer's own included a kind:0 whose author is the group's npub, fetched from relays, with a valid signature that group cannot be added to the proposal; the picker says why
signing an acceptance, for one's own group the same fetch for this group's npub the approval screen warns that the device could not find the group's public profile. It does not decline (see D6)
the coordinator, before opening the ceremony room the same fetch for every accepted group the ceremony is not opened; the coordinator's screen names the group

The fetch reuses DirectMessagePeerSync.profileRequests and the profile preview's askTheRelays, against the bootstrap relays plus any relay hint the proposal carries.

What a kind:0 cannot prove is that the npub is a group. A FROST key and a single person's key look the same on the wire (see What this does not do).

D3. The proposal is signed together with the proposer's own acceptance, in one session

Since confederation-without-coordinator.md: a proposal is its proposer's acceptance: its rumor carries the proposing group's own admin list, since two statements, each sealed to every group, would halve how many groups fit in one signing proposal.

The proposing group is a participant like any other, so it has to commit to its own admin list too. The proposal's id is known before it is signed, since it is the hash of the unsigned fields. So the proposer's device builds both events and proposes them as one batch of two through FrostSigningManager.proposeSigningBatch (frost-batch-signing.md):

[ ConfederationProposalEvent,
  ConfederationProposalAcceptanceEvent  (e-tags the proposal's id) ]

One quorum, one approval, and a proposal never exists without its proposer's acceptance. A device refuses a 9430 that arrives without its acceptance in the same batch (Phase 3).

D4. The coordinator is the member who proposes, and in practice that member is an admin

Since confederation-without-coordinator.md: there is no coordinator. The proposing group proposes, and nobody is named. The statements travel between the groups' inboxes as rumors sealed by each group's quorum, every admin of every group reads the admin lists, and the ceremony computes the coordinator's steps on every device. D4, D5 and D7 below are the reasoning for what was built first, and no longer describe the app.

The proposal names the coordinator in a coordinator tag. Every signer checks that this pubkey is the signing session's proposer. A member cannot volunteer someone else, and cannot be volunteered.

Proposing a group signature needs a share of the group's key (canSign, the gate GroupStatementCapability already applies). Every admin holds a share (member-admin-promotion.md), but the converse does not hold while share refresh is experimental: a demoted admin keeps a share of the active generation until a refresh runs (Phase 0). So the coordinator also has to be one of the proposing group's current admins, by RoomAdmins.of. That is checked on the proposer's screen and refused on every signer's device (Phase 3). With it, the coordinator always holds a role in the confederation, as the ChillDKG coordinator is always a participant.

The coordinator is trusted with exactly what the request gives them: reading every group's admin list. ChillDKG and the confederation DKG both treat a coordinator as untrusted for everything else, and D7 makes sure they cannot substitute a roster.

D5. Encrypting the admin list: a seal every signer can recompute

Since confederation-without-coordinator.md: no seal. An admin list travels in the clear inside a NIP-17 rumor sealed to every group's inbox key, so the admins of every group read it and nobody else does, and a signer compares it with its own view of the group directly. ConfederationSeal is gone.

Since group-inbox.md: something can now be encrypted to a group, through the inbox key its admins make and its quorum announces (NIP-4E), and from one, by sealing with that key and signing the seal as the group. Only for a group that has set up an inbox, and the seal below is unchanged. Whether a confederation should use the inbox is its own question.

Nobody holds a group's secret key. So an acceptance cannot be NIP-44-encrypted from the group in the usual way, because NIP-44's conversation key is an ECDH between the sender's secret and the recipient's pubkey. For the same reason, nothing can be gift-wrapped to a group's npub.

Since group-threshold-ecdh.md: a group can now be written to at its npub, through its admins' shares computing the ECDH together, where it has opened its messages (signed a kind 10050). That needs t admins' apps to answer, and a device multiplies only by a key whose owner signed something it can check, so it is no use to this seal: the coordinator's key is not one the group could compute for in a signing session. D5's seal stays as it is.

The acceptance uses an ephemeral sender key instead, and makes everything about the encryption reproducible by the group's members and by nobody else:

plaintext  = canonical JSON (below), UTF-8, no whitespace, fixed key order
e          = 32 random bytes, chosen by the acceptance's proposer
E          = e·G                                   -> ["epk", hex(E)] tag
nonce      = TaggedHash("mantra/confederation/seal-nonce/v1", e || proposal id)
convKey    = Nip44v2.getConversationKey(e, coordinator pubkey)
content    = Nip44v2.encryptWithNonce(plaintext, convKey, nonce).encodePayload()

plaintext:
{"v":1,"proposal":"<proposal id>","group":"<this group's npub hex>",
 "threshold":<t_g>,"admins":["<admin pubkey hex>", …]}       admins sorted bytewise

e travels to the group's members inside the FROST signing proposal (the 30320 rumor), as an extra tag ["confederation_seal", hex(e)]. That rumor is MLS-encrypted, so only the group's members ever see e. Each signer then:

  1. builds the plaintext from its own view of the group: RoomAdmins.of(...) for the admins, and the threshold its active share generation signs with for t_g;
  2. recomputes E, nonce, the conversation key and the ciphertext;
  3. compares the ciphertext with the event's content byte for byte, and E with the epk tag.

A proposer who encrypted a different admin list (with an extra admin, a missing one, or another threshold) produces a ciphertext no honest device reproduces, and the acceptance is declined (D6). The coordinator decrypts with ECDH(coordinator secret, E).

This is what "each member computes the same encrypted payload" requires. It is possible only because the randomness is fixed and shared inside the group. quartz 2.20.1's Nip44v2 exposes getConversationKey and encryptWithNonce publicly (checked), so no NIP-44 code is written here.

What e costs: any member of the group can decrypt the acceptance. They already know the admin list, because MLS admin policy is visible to every member. Nobody outside the group and the coordinator can decrypt it. A member who leaks e leaks what they could have leaked anyway.

Alternatives considered are in the appendix: an e derived from public data, which anyone could recompute, and an e derived from the MLS exporter secret, which depends on the epoch.

D6. Refuse what is wrong, and warn about what cannot be checked

Giza's rule is that a proposal a device cannot check is declined out loud, never signed and never dropped (giza-wallet-removal.md). A new kind needs its own refusal or it reaches the approval prompt as "Event of kind 9431": there is no allowlist. ConfederationRefusal joins WalletRefusal, GroupStatementRefusal and GovernanceManager.refusalOf in all four places: acceptProposal, the approve backstop, publishDecline's reason, and the unshowable-session check.

automatic-key-ceremony.md Phase 7 drew a line that applies here: "Failing a check is not a reason to decline. It means the device cannot vouch for the statement, so a person has to." So the checks split in two:

refuse (declined out loud, with a reason) warn (shown on the approval screen; the member decides)
the batch shape is wrong (D3); a field is malformed a listed group's kind:0 cannot be found on relays right now
this room is not among the listed groups the proposal expires within a day
T is outside 2..N, or N is outside 2..64 a listed group is one this device has never seen
the coordinator is not the session's proposer, or not a current admin of the proposing group
the seal does not reproduce (D5), or the admin list or t_g disagrees with this device's
this group has already answered this proposal
the proposal has expired, or names an expiry more than 30 days away

D7. The coordinator shows every participant the admin lists they were sent

Since confederation-without-coordinator.md: nothing to show. Every participant has read every list from its own group's inbox before the ceremony starts.

Part A leaves only the coordinator able to read the acceptances. In Part B, every participant has to check the roster before contributing to the DKG. Otherwise a coordinator could put an extra role into group B's segment (for example a key they control) and no one outside B would notice.

The fix costs nothing. The coordinator's first message in the ceremony room carries, for each acceptance, the NIP-44 conversation key ECDH(coordinator secret, E). This key is unique to that acceptance: it reveals nothing else of the coordinator's, and it decrypts exactly one ciphertext. Every participant decrypts every acceptance with it, checks each plaintext against the group-signed event, and rederives the roster from those plaintexts. They are going to be in a room with each other anyway, so nothing is disclosed that the room would not disclose. A coordinator who substitutes a roster produces one that no participant can rederive, and nobody joins.

D8. Answers are final. One rejection ends the proposal

Each group answers at most once. A device refuses to sign a second answer from its own group (D6). If, despite that, a group has both an acceptance and a rejection on relays (an older build, or a Bennu-derived client), the rejection wins. The proposal is:

state when
OPEN not every listed group has answered, and none has rejected
ACCEPTED every listed group has a valid acceptance and none has a rejection
REJECTED any listed group has a valid rejection
EXPIRED the expiration tag (NIP-40) has passed before ACCEPTED
WITHDRAWN the proposing group signed a 9433 before ACCEPTED (Phase 8, optional)
FORMING, FORMED, FAILED Part B, from the ceremony

The state is computed from stored events every time it is read, so every device that holds the same events agrees, and none is stored.

D9. A confederation event is published as soon as it is signed, by the device that proposed it

Signing publishes nothing today, except for one precedent: GovernanceManager.onSigned publishes the governance statement the proposer's device was waiting for. A confederation event exists only to be read on relays, so the quorum approving it is the decision to send it. ConfederationManager.onSigned follows the same pattern. It runs on every device that completes the session, and acts only on the device that holds the proposal row for that session.

The broadcast screen's BROADCASTABLE_KINDS gains 9430 to 9433, so any member can send a signed answer again by hand. That is the repair for a proposer whose phone died between signing and sending. As with kinds 0 and 1, broadcasting writes no NostrEvent row.

D10. The confederation's room id is derived from its key in the usual way

"The confederation shared key is the Marmot group id" is read as Giza reads it for every keyed room: ChatRoom.id = SharedKeyDerivation.marmotGroupId(X, m/9420/0/0), and the room signs as that id. Using X raw would make the confederation the one room in the app whose id is not derive(key, path). Every reader of a group-signed event (isSignedByRoom, GroupSignedEvent.verifies, signingPath) would need a case for it. Marmot v2's routing id is random, as for every room (MarmotGroupFactory).

This depends on the confederation's ConfederationTweak list reproducing SharedKeyDerivation's x-only tweaks exactly. Phase 1 proves this with signLocal before anything else relies on it.

D11. Every admin is a role, and t_g is the group's own threshold

The request says an acceptance carries "the group's admin pubkeys", so the roster's group segment is all of the group's admins at the time of acceptance, and t_g is the threshold the group signs with today. A group that wants fewer representatives would need a different acceptance shape. That is noted as an extension, not built.

The consequence that matters most: the DKG cannot finish unless every admin of every group takes part. Joint-Feldman needs every dealer, and that is the single biggest practical cost, just as it is for a subgroup. The ceremony screen names who it is waiting on, by group and by admin, and offers abandon.


Who is asked what

step who is asked what they decide automatic after that
propose one admin of A to propose the confederation, its groups, T, its name and expiry building the batch, the seal, the signing session
A signs A's quorum that A proposes this, and accepts with these admins publishing (D9)
invitation arrives nobody — storing it, a transcript line in each invited group, an invitation row on the detail screen
B answers one admin of B, then B's quorum accept or reject the seal checks; publishing
all accepted nobody — the coordinator's device decrypts, checks profiles, opens the ceremony room (Part B)
ceremony each admin of each group to join, which enrols them in the confederation's signing set for good every round after the join
room nobody — the coordinator creates it; members are welcomed

The join stays a question, as it does for a group's own ceremony. A group's quorum agreeing to join does not commit an admin who was not in that quorum to holding a share.


Part A: agreeing to form

Phase 0: this document, and three checks

No code. The decisions above rest on three things that can be checked in a day:

  1. The kind numbers (D1). Search the NIP kind registry, and Bennu's and Curare's sources, for 9430 to 9433. If any is taken, move the family and update this note.
  2. NIP-44 with a fixed nonce (D5). Confirmed above: Nip44v2.encryptWithNonce and getConversationKey are public in quartz 2.20.1. Write down the version, because a quartz bump that hides them breaks the seal.
  3. Who holds a share. Confirm on the current code that a member who is not an admin never holds a share of a keyed room's key (D4). If one can, D4 has to say what happens when that member proposes.

Phase 1: the premises, as tests

Before any feature code, pin what the plan assumes and what the app does today.

  • ConfederationRoomKeyJvmTest, beside ConfederationReachableJvmTest. It runs Confederation.dkgLocal over a 2-of-(3 × 2-of-3) roster, then signLocal(tweaks = SharedKeyDerivation's tweaks for m/9420/0/0), and checks the signature against marmotGroupId(X) with Crypto.verifySignatureSchnorr. This is D10's premise. If it fails, stop. The room id decision changes before Part B can be built.
  • ConfederationKindsTodayJvmTest. It pins that a FROST proposal of kind 9430, 9431 or 9432 today reaches isAwaitingApproval and is summarised as "Event of kind N". Phase 3 flips this test.
  • A pure test that two NIP-44 encryptions with the same e, nonce and plaintext produce identical payloads, and that the coordinator's key decrypts them. This is D5's premise, against quartz's real code.

Done when all three pass, the first two describing today's behaviour.

Phase 2: the wire format

New package nostr/confederation/, pure, no database, in the same shape as SubgroupBirthCertificateEvent.

kind:    9430                                        ConfederationProposalEvent
pubkey:  <proposing group's npub>                    (set by the signing session)
content: "<group name> proposes a confederation, <name>, with <n> groups"   human text, unverified
tags:
  ["p", <group npub>, <relay hint>, "group"]         one per group, the proposer's included
  ["coordinator", <coordinator pubkey>]
  ["threshold", "<T>"]
  ["name", <the confederation's name>]
  ["nonce", <32 random bytes, hex>]                  two identical proposals still differ
  ["expiration", "<unix seconds>"]                   NIP-40
  ["alt", "A proposal to form a confederation of nostr groups"]   NIP-31
kind:    9431                                        ConfederationProposalAcceptanceEvent
pubkey:  <accepting group's npub>
content: <NIP-44 v2 payload, D5>
tags:
  ["e", <proposal id>, <relay hint>]
  ["p", <proposing group's npub>]
  ["p", <coordinator pubkey>]
  ["epk", <E, hex>]
  ["alt", "An acceptance of a confederation proposal"]
kind:    9432                                        ConfederationProposalRejectionEvent
pubkey:  <rejecting group's npub>
content: <optional reason, plain text>
tags:
  ["e", <proposal id>, <relay hint>]
  ["p", <proposing group's npub>]
  ["alt", "A rejection of a confederation proposal"]

Objects:

  • ConfederationProposalEvent: assemble(...), parse(event): Proposal? (all fields or none), and isWellFormed. Also a Proposal data class carrying groups, coordinator, threshold, name, expiresAt and relayHints.
  • ConfederationProposalAcceptanceEvent: assemble, parse, and seal(e, proposal, plaintext), which returns the content and the epk. open(convKey, event): AdminList? and conversationKey(coordinatorSecret, event) serve D7.
  • ConfederationAdminList: the canonical plaintext. encode() is byte-stable and decode() is strict: it refuses unknown keys, unsorted or duplicate admins, and v != 1.
  • ConfederationProposalRejectionEvent: assemble, parse.
  • ConfederationResponse.of(proposal, events): the D8 state machine, pure.
  • Tag classes in nostr/confederation/tags/, in FrostDerivationPathTag's shape.
  • FrostSigningEvents.assembleTags gains an optional confederationSeal, emitted only when it is passed, so every existing proposal is byte-identical.

Tests (commonTest):

  • round trips;
  • a seal that reproduces, and one that does not for each of: another admin, one admin fewer, another t_g, another coordinator, another proposal id;
  • ConfederationAdminList.encode is the same bytes regardless of input order;
  • the D8 table, case by case, including "accepted and rejected → rejected" and "expired with every answer in → expired";
  • the kinds added to RetiredKindsTest's live map.

Phase 3: the refusals (D6)

managers/ConfederationRefusal.kt:

object ConfederationRefusal {
    const val REASON = "…"                         // one per refusal; the decline shows it
    suspend fun of(database, localChatRoom, session, events: List<Event>, seal: ByteArray?): String?
    suspend fun warnings(database, localChatRoom, events): List<ConfederationWarning>
}

Wired in the four places listed in D6, beside GroupStatementRefusal:

  • A batch containing a 9430 must be exactly [9430, 9431], with the 9431 e-tagging the 9430's id. The 9430 must list this room. coordinator must equal the session's proposer and be in RoomAdmins.of for this room. N must be in 2..64 and T in 2..N. The expiry must be in the future and at most 30 days ahead. The 9431 must pass the acceptance checks below against that 9430.
  • A lone 9431 must e-tag a proposal this device holds (Phase 4), and that proposal must list this room. The group must not have answered already. The seal tag must be present on the FROST proposal and must reproduce (D5).
  • A 9432 must e-tag a proposal this device holds that lists this room, and the group must not have answered already.
  • A 9433 must be signed by the proposing group, about a proposal it signed, that is not yet ACCEPTED.
  • A confederation kind batched with any other kind is refused.

Then flip ConfederationKindsTodayJvmTest: each broken case is declined with its reason, and the proposer's device shows the decline. Add ConfederationDeclineJvmTest on GroupStatementDeclineJvmTest's harness, so a real proposal crosses the inbound path.

ProposedEvent.summarize gets three real summaries in place of "Event of kind N", for example: "Propose a confederation, Atlas, with Ekklesia, Agora and Polis, 2 of 3 to act." FrostSigningScreen.WhatIsBeingSigned shows the groups by their kind:0 names, the coordinator, T, and for an acceptance the admin list being disclosed. Showing that list matters: it is the thing the group is consenting to reveal.

Phase 4: storage, schema 42 → 43

Two tables and an AutoMigration. Neither has a foreign key to ChatRoom. A proposal can concern rooms this device is not in, so dangling references are normal, the same argument as parentChatRoomId in subgroups.md.

table key columns
ConfederationProposal id (the 9430's event id) eventJson, proposingGroup, coordinator, threshold, name, expiresAt, receivedAt, frostSigningSessionId? (set on the device that proposed it, for D9)
ConfederationAnswer eventId proposalId (indexed), groupPublicKey, kind, eventJson, receivedAt
ConfederationGroup (proposalId, groupPublicKey) profileFoundAt?, profileName?, relayHint?. Caches D2 lookups for the screens; never trusted for a check

Rows are written only after the event's signature verifies against its author and the event parses. Nothing is written to NostrEvent or Profile, for the same reason as D7 of the profile note: a group's confederation event would otherwise appear in the home feed and make a Profile row for the group.

DAO reads: observeForGroup(groupPublicKey) (as proposer or invitee), observeById, answersFor(proposalId), observeOpenAsCoordinator(userPublicKey).

ConfederationRepository / DatabaseConfederationRepository, in the existing interface-plus-database shape.

Phase 5: relays

  • Subscribe. LiveSubscriptionManager holds one more filter while the flag is on: kinds 9430 to 9433 with #p set to every keyed Marmot room on the device (each room's id), plus kinds 9431 to 9433 with #e set to every proposal the device stores that is still OPEN. It follows the room list the way the #h filter does (long-running-sync.md). Relays are the bootstrap set plus each stored proposal's hints.
  • Ingest. ConfederationManager.ingest(event) verifies the signature, parses, and writes the row. It writes a transcript line (Phase 6) into every local room the event concerns. It is idempotent by event id, because relays redeliver.
  • Publish (D9). ConfederationManager.onSigned(signedEvents) is called from FrostSigningManager.complete beside GovernanceManager.onSigned. It sends to Relays.eventPublishRelaySet plus the hints for every listed group, through EventPublishTransport. It then ingests its own events, so the proposer's device does not depend on its relays echoing them back.
  • Broadcast screen. BROADCASTABLE_KINDS gains 9430 to 9433, and defaultRelaysFor adds the proposal's hints for these kinds. BroadcastLeavesNoRowJvmTest gains a confederation case.

Tests. ConfederationRelayJvmTest uses the in-memory relay the sync tests use. A signed proposal reaches a device in an invited group. An event with a bad signature writes nothing. A redelivered event writes one row and one transcript line.

Phase 6: proposing

  • Transcript. New message types: TYPE_CONFEDERATION_PROPOSED, …_ACCEPTED, …_REJECTED, …_WITHDRAWN, …_EXPIRED. They are system lines, written by each device from events it holds, in the way shared-key-ceremony.md describes. They are guarded against a second write by reading the row first. Example: "Agora was invited to a confederation, Atlas, by Ekklesia."
  • Entry point. A "Confederations" row on ChatRoomDetailScreen, shown in a keyed Marmot room while the flag is on, in the same group as the profile and posts rows. It opens ConfederationsScreen, which lists invitations, proposals the group made, and (after Part B) confederations it belongs to. Each list has its own EmptyState message.
  • ProposeConfederationScreen, reached by navigation (NavigateBackButton):
    • Groups are added by npub or NIP-05, each resolved through D2 into a row showing the group's kind:0 name and picture. A group whose profile cannot be found is shown with the reason and cannot be added. This group is the first row, and is checked the same way.
    • T is chosen with a stepper over 2..N. It starts at Quorum.default(N), a majority, the same rule a group's quorum starts on.
    • The confederation's name, and an expiry with a default of 7 days and a maximum of 30.
    • The submit button proposes the D3 batch, with the seal tag (D5), and is disabled with a reason until every row is resolved.
    • The gate is GroupStatementCapability.roomIsOpen && canSign && LocalCanSign, as for a profile edit.
  • M3 rules apply as each screen lands: strings in the catalogue, sentence case, spacing from the scale, readableContent(), and the four states.

Tests. ProposeConfederationViewModelJvmTest covers: the batch is built with the seal; a group without a profile cannot be added; N < 2 cannot submit. Also ProposeConfederationScreenJvmTest.

Phase 7: answering

  • ConfederationProposalScreen, keyed by proposal id. It shows the proposing group, the listed groups with their answers (accepted, rejected, waiting), T, the coordinator, the expiry, and the state (D8).
  • In an invited room, while the state is OPEN and this group has not answered, it offers Propose accepting and Propose rejecting, under the same gate as Phase 6. Accepting builds the 9431 with a fresh e. Rejecting offers an optional reason.
  • A pending answer (a signing session in this room for this proposal that has not finished) replaces both buttons with "Waiting for the group to sign", so two members do not open competing sessions. If two sessions do open anyway, the second one to reach a device is declined by D6's "already answered" check once the first is signed.
  • Invitations awaiting an answer feed observeProposalsAwaitingYou, the same badge signing proposals use.

Tests. ConfederationAnswerJvmTest runs three groups on the multi-device harness from SignedGroupKeyStateTest. A proposes. B accepts, and its seal is checked by B's other signer. C rejects. Every device in A, B and C computes REJECTED. Then a second proposal, which B and C both accept, reaches ACCEPTED everywhere.

Phase 8: the outcome on the coordinator's device, and withdrawal

  • ConfederationManager.outcome(proposalId), on the coordinator's device only. For an ACCEPTED proposal it:

    • decrypts each acceptance;
    • checks that each plaintext's proposal and group match the event, and that 2 ≤ t_g ≤ n_g;
    • counts the roles (at most 128, and more than 16 is noted, because access() cannot analyse it);
    • re-runs D2 for every group;
    • flags any admin who appears in more than one group. That is allowed, but each such admin will need two host keys, and the shared entityId makes the overlap visible to access().

    It stores nothing new: every input is already stored, and the result is recomputed.

  • The coordinator's proposal screen then shows "Every group accepted", with the role count, any overlaps, and (until Part B exists) "The confederation's key ceremony is not available yet". That last line is the honest end of Part A.

  • Withdrawal (optional). The proposing group can sign a 9433 while the state is OPEN. It is a group statement like any other, gated and refused like the rest.

  • Docs: the README row; mark Part A built, with a what the plan said / what it turned out to be table.

Done when three groups on three or more devices can propose, accept, reject, expire and withdraw, and the coordinator's device ends holding three verified admin lists.


Part B: forming

Phase 9: the upstream prerequisite

Planned in detail, level by level, in confederation-upstream.md.

Done, and pushed. zkp exports the DKG and signing steps; secp256k1-kmp binds them; bitcoin-kmp wraps them as ConfederationDkg and ConfederationSigning; the chain is bumped up to Giza. ConfederationReachableJvmTest runs three groups through both, one role at a time, and signs as the room's id. The commits, and what checked each, are in that plan's "Status". Parts B and C can start.

Not Giza work, but Part B cannot start without it. Giza needs these to be public in zkp, bound in secp256k1-kmp, and wrapped in bitcoin-kmp. The names are from zkp's static functions:

step role function
dealer record and per-recipient ciphertexts each role dkg_participant_step1
combine records and ciphertexts; the broadcast's hash is the operation session id coordinator dkg_coordinator_step1
verify the broadcast, own record and summed share; derive the KSD each role dkg_recipient_verify, dkg_derive_ksd
prepare and sign the genesis transition each role dkg_genesis_prepare, transition_evidence_sign
verify authorizations; assemble the certificate coordinator dkg_verify_authorizations, dkg_coordinator_finalize
install the state; issue recovery each role dkg_participant_finalize, Confederation.issueRecovery
blame anyone dkg_investigation_response, dkg_investigate

Each step must take and return serialisable inputs and outputs, the way ChillDKG's Kotlin API does. ChillDkgRitualManager resumes after a restart because it stores inputs and recomputes, and the confederation ritual needs the same property. Raise this upstream if the step API keeps opaque native state between calls.

Then a submodule bump following confederation-submodule-update.md's procedure, with its Phase 0 FROST-unchanged check.

Phase 10: the roster, derived the same way on every device

Every participant derives the RPD independently, and it must come out byte-identical (as host-key ordering must in shared-key-ceremony.md):

version, config_seq = 1, outer_epoch = 1, previous_rpd_hash = 0^32       genesis
outer_threshold   = proposal T
groups            = the proposal's group npubs, sorted bytewise; groupId = index
  share_epoch_g   = 1
  inner threshold = acceptance plaintext's threshold
  roles           = acceptance plaintext's admins, sorted bytewise; adminId = index
    entity_id     = the admin's nostr pubkey (x-only)
    host_pubkey   = from the ceremony (Phase 11)
attestation_ref   = TaggedHash("mantra/confederation/attestation/v1",
                               proposal id || acceptance ids, in groupId order)

Host keys. One per role (D11), derived the way ChillDKG's are, with the group in the input so that one person in two groups gets two keys:

hostSecret = sha256("mantra/confederation/host-key/v1" || nsec || group npub || proposal id)

The mantra/… spelling follows the house rule for protocol tags (CLAUDE.md). These are hash inputs, not brand strings. Deriving from the nsec means a share's recovery package can be reopened from the member's own backup and nobody else's, which is the property ChillDKG shares have.

ConfederationRosterBuilder (pure) and ConfederationRosterBuilderTest, checked against dkgLocal: a roster built here, run through dkgLocal, signs. Shuffled inputs give identical bytes. An admin in two groups gets two distinct host keys. 129 roles is refused.

Phase 11: the ceremony

Since confederation-without-coordinator.md: nobody opens it. Every admin joins from the statements their device holds; the room's id is the set of its people, the ceremony's id comes from the proposal and the attempt, the session seed from a contribution in every person's 30381, and every device computes the broadcast. 30380 and 30383 are not sent. A failed attempt is tried again as the next.

The room. The coordinator's device creates a NIP-17 room over the coordinator and every admin in the roster: createNip17ChatRoom, with id deriveChatRoomId(members), exactly as group creation does. An admin who is in two groups is one member of the room and two roles. The room's subject is the confederation's name.

Why NIP-17 and not a Marmot room. The participants share no Marmot room, and creating one needs every member's key package and a commit before the ceremony can start. subgroups.md moved a subgroup's ceremony into a Marmot room because one already existed. Here none does, and a NIP-17 room is what a group's own first ceremony uses.

Kinds (rumors, in the private range, the next free block):

kind from carries
30380 coordinator ceremony proposal: the 9430, every 9431, D7's conversation keys, the session seed
30381 each role host public key, for (group, admin)
30382 each role dealer record and ciphertext vector
30383 coordinator coordinator broadcast
30384 each role genesis authorization
30385 each role acknowledgment: share and recovery stored
30386 coordinator genesis transition certificate
30387 anyone failure: abort and blame
30388 anyone investigation request or response

ConfederationRitualManager, modelled on ChillDkgRitualManager:

  • ConfederationCeremony and ConfederationCeremonyMessage entities store inputs (dealer seed, recovery nonce, received messages), never protocol state. advance recomputes from them, so a restart resumes on the next message.

  • On receiving 30380, before anything is published, a participant's device:

    • verifies the 9430 and every 9431 as group-signed events;
    • checks the proposal is ACCEPTED (D8);
    • decrypts every acceptance with D7's keys;
    • checks its own group's plaintext against its current admin list. If the group's admins changed since acceptance, it fails the ceremony with a reason that says so;
    • rederives the roster minus host keys;
    • re-runs D2.

    Any failure is a 30387 with the reason. Passing all of them makes the ceremony eligible. It does not join.

  • Joining is the only approval. The member is asked once, on a screen that shows the groups, the roles, T, every t_g and who else is in it. Approving publishes the host keys (one per role this member holds). Everything after that runs by itself, as in automatic-key-ceremony.md.

  • Once every host key is in, every device completes the roster and checks the coordinator's copy of it (sent in 30383) byte for byte.

  • Faults are values. A fault names the role, and the role is shown by group name and admin name.

  • Abandon is offered after a day without a new message, to any participant, as for ChillDKG.

ConfederationRitualScreen has a ladder that names who it is waiting on, grouped by group, rather than "17 of 21".

Tests.

  • ConfederationCeremonyAcrossDevicesJvmTest, on CeremonyAcrossDevicesJvmTest's network: three groups of three admins each, T = 2. It reaches genesis and every device installs the same KSD.
  • Separately:
    • a coordinator who adds a role to one group's segment (nobody joins);
    • a coordinator whose D7 key does not open an acceptance (failure with reason);
    • one admin who never joins (waits, then abandon works);
    • a restart mid-round (resumes);
    • an admin in two groups (two roles, one person, one join).

Phase 12: completion

  • Each role stores its recovery package (269 bytes, keyed by the host key), never the raw share: "A share has no canonical encoding". The RPD, KSD and genesis transition are stored as their canonical bytes on a Confederation entity with (configSeq, rpdHash, ksdHash), which upstream says applications must persist so that only direct successors are accepted.
  • ConfederationKeyStateEvent (30389, a rumor) carries the RPD, KSD, genesis certificate, the 9430 and the 9431s. It is self-verifying: ConfederationTransition.fromData validates every role's host signature over the genesis, so no confederation signature is needed to trust it. That is why the room (Phase 13) does not wait for Part C.
  • Each participating group's detail screen lists the confederation, on its admins' devices. A group's members who are not admins learn of it only through the transcript line the coordinator's device posts into each group's own room. That line is a claim by a member, not a statement by the group, and is labelled as such. See What this does not do.

Phase 13: the confederation's room

Since confederation-without-coordinator.md: the first of the roster's people, sorted, makes the room, and the k-th after k hours with none; a welcome from earlier in the order replaces the room a device holds.

  • MarmotGroupCreation.createForConfederation(confederation), beside createFor:
    • groupId = marmotGroupId(02 || X, m/9420/0/0) (D10);
    • the routing id is random;
    • the members and admins are every role holder;
    • the description carries the derivation sentence and the Room id: line;
    • the name comes from MarmotGroupName.of(name).
  • ConfederationFollowThrough, on the coordinator's device, in the shape of CeremonyFollowThrough: from a FORMED ceremony with no room, it creates the room. If the room is blocked on key packages, it waits and retries on the sweep. The ladder's last rung becomes Open the room.
  • A joiner adopts the room only if the confederation key state verifies and the room id rederives from X, the check GroupKeyStateManager.adopt makes for a group.
  • Governance until Part C. The room is keyed, so member-admin-promotion.md's rule says every commit is a proposal until the key signs it. Until confederation signing exists, nothing can sign, so the room is fixed at its founding members. That is acceptable for a first version and is said on its detail screen.

Part C: acting

Phase 14: nested signing across devices

The same prerequisite as Phase 9, for sign_session_init, signer_nonce_gen, the nonce transcript, signer_confirm and the confirmation certificate, signer_partial, group_partial_aggregate and outer_aggregate.

ConfederationSigningManager runs in the confederation's room. It is modelled on FrostSigningManager (proposal, approval, rounds, completion), with three differences:

  • Two levels of coordinator. The session's proposer is the outer coordinator. Each group has a group coordinator: the selected admin of that group with the lowest adminId.
  • The selection is explicit. ConfederationSignerSelection needs at least T groups and at least t_g admins in each. It is chosen from the admins who approved, per group, in the order approvals arrive, and is fixed in the confirmation round.
  • Nonces live in memory only, as upstream requires. A restart mid-attempt fails the attempt (30397), and the proposer starts a fresh one with a new session id. This is deliberately different from FROST, and the KDoc says why.

Kinds 30390 to 30399 are reserved for this phase now, so nothing else takes them.

Phase 15: what the confederation signs

  • Its kind:0 and kind:1, reusing GroupNostrProfile and GroupPost, with the confederation's room as the room.
  • A charter: a public, confederation-signed event naming its member groups, that each group's members can find on relays with #p = their group's npub. This is the fix for Phase 12's members who are not admins, and the one public statement that the confederation exists.
  • Governance of its room: admin changes signed by the confederation, through GovernanceManager.

Phase 16: the record, and devices

  • Mark this plan built, with the what the plan said table.
  • Device run: three groups of three on at least five devices or emulators. Admins overlap on one person across two groups. Propose, answer, form, create the room, and sign a confederation kind:0 that a public nostr client shows under the room's npub.

What this does not do

  • It cannot tell a group from a person. A FROST key and a single key look the same on relays. An npub controlled by one person can accept with any admin list it likes. The checks in D7 and Phase 11 make that admin list visible to every other participant before anyone joins, which is the most that can be done. A signed "this is a Giza group" marker in the kind:0 would still be self-asserted.
  • The proposal is public metadata. Anyone can see which groups were invited, who answered how, and who coordinates. Only the admin lists are encrypted.
  • Membership is fixed at genesis. Adding or removing a group, or an admin within one, is upstream's AdminEnroll, OuterEnroll, Reshare and the rest, which are not public. An admin removed from group B after genesis keeps their confederation share. A group that wants to leave cannot.
  • Every admin of every group must join (D11). One absent admin stalls the ceremony.
  • Members of a group who are not admins learn little until Part C's charter.
  • The coordinator cannot be replaced -- there is no coordinator any more (confederation-without-coordinator.md). A lost phone is one admin's, and the proposal, the ceremony and the room go on without it.
  • Not for value. Upstream's warning stands, and the flag stays off in release.

Appendix: considered and rejected

idea why not
gift-wrap the proposal to each group's npub no one holds a group's secret key, so no one could open it
encrypt the acceptance "from" the group with NIP-44 the same reason: the conversation key needs the sender's secret
derive e from public data (proposal id, group id) so no secret needs sharing anyone could recompute e and decrypt the admin list
derive e from the MLS exporter secret members at different epochs derive different keys, and an epoch change mid-signing makes every honest device refuse
let the proposer's ciphertext stand, as signers do today for any content the request requires each member to check it. Without the check a proposer can disclose a list the group never agreed to
one flat ChillDKG over every admin of every group it loses the per-group thresholds: three admins of one group could sign without any other group
MuSig2 over the groups' existing FROST keys (nested-dkg.md's suggestion when every group must sign) it needs no new DKG and keeps each group's key, but it allows only T = N, and it needs FROST-inside-MuSig signing (Prefractal), which Giza does not have. Worth revisiting if T = N turns out to be the common case
dkgLocal on one device it holds every role's secrets: a trusted dealer under another name
the confederation's raw X as the room id see D10
addressable kinds for the public events see D1

Order and size

phase rough size depends on
0 a day, no code —
1 ~250 lines of test 0
2 ~500 main, ~600 test 1
3 ~300 main, ~400 test 2
4 ~250 main, ~150 test 2
5 ~400 main, ~300 test 3, 4
6 ~900 main, ~350 test 5
7 ~700 main, ~400 test 6
8 ~300 main, ~200 test, docs 7
9 upstream, and a submodule bump —
10 ~250 main, ~250 test 9
11 ~1,800 main, ~1,000 test 10
12 ~400 main, ~250 test 11
13 ~400 main, ~300 test 12
14 ~2,000 main, ~1,000 test upstream signing, 13
15 ~500 main, ~300 test 14
16 docs and a device session all

Phases 3 and 4 can run side by side. Phase 10 can be written against dkgLocal before Phase 9 lands, since the roster does not depend on the step API. Everything else runs in order.

Checking the work

./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
./gradlew :composeApp:m3Audit
./gradlew check

None of the new kinds is in RetiredKinds, and no file name here matches the wallet audit's patterns. Bennu is named in this note only as a peer, and never in code.