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>
73 KiB
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:
- 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. - The signed proposal is broadcast. Each invited group answers by signing either a
ConfederationProposalAcceptanceEventor aConfederationProposalRejectionEvent. - 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.
- 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.
- 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).
entityIdis 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.
ConfederationSealis 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
tadmins' 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:
- builds the plaintext from its own view of the group:
RoomAdmins.of(...)for the admins, and the threshold its active share generation signs with fort_g; - recomputes
E,nonce, the conversation key and the ciphertext; - compares the ciphertext with the event's content byte for byte, and
Ewith theepktag.
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:
- 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.
- NIP-44 with a fixed nonce (D5). Confirmed above:
Nip44v2.encryptWithNonceandgetConversationKeyare public in quartz 2.20.1. Write down the version, because a quartz bump that hides them breaks the seal. - 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, besideConfederationReachableJvmTest. It runsConfederation.dkgLocalover a 2-of-(3 × 2-of-3) roster, thensignLocal(tweaks = SharedKeyDerivation's tweaks for m/9420/0/0), and checks the signature againstmarmotGroupId(X)withCrypto.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 reachesisAwaitingApprovaland 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), andisWellFormed. Also aProposaldata class carryinggroups,coordinator,threshold,name,expiresAtandrelayHints.ConfederationProposalAcceptanceEvent:assemble,parse, andseal(e, proposal, plaintext), which returns the content and theepk.open(convKey, event): AdminList?andconversationKey(coordinatorSecret, event)serve D7.ConfederationAdminList: the canonical plaintext.encode()is byte-stable anddecode()is strict: it refuses unknown keys, unsorted or duplicate admins, andv != 1.ConfederationProposalRejectionEvent:assemble,parse.ConfederationResponse.of(proposal, events): the D8 state machine, pure.- Tag classes in
nostr/confederation/tags/, inFrostDerivationPathTag's shape. FrostSigningEvents.assembleTagsgains an optionalconfederationSeal, 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.encodeis 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.coordinatormust equal the session's proposer and be inRoomAdmins.offor this room.Nmust be in2..64andTin2..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.
LiveSubscriptionManagerholds one more filter while the flag is on: kinds 9430 to 9433 with#pset to every keyed Marmot room on the device (each room's id), plus kinds 9431 to 9433 with#eset to every proposal the device stores that is stillOPEN. It follows the room list the way the#hfilter 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 fromFrostSigningManager.completebesideGovernanceManager.onSigned. It sends toRelays.eventPublishRelaySetplus the hints for every listed group, throughEventPublishTransport. It then ingests its own events, so the proposer's device does not depend on its relays echoing them back. - Broadcast screen.
BROADCASTABLE_KINDSgains 9430 to 9433, anddefaultRelaysForadds the proposal's hints for these kinds.BroadcastLeavesNoRowJvmTestgains 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 opensConfederationsScreen, which lists invitations, proposals the group made, and (after Part B) confederations it belongs to. Each list has its ownEmptyStatemessage. 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.
Tis chosen with a stepper over2..N. It starts atQuorum.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
OPENand 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 freshe. 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 anACCEPTEDproposal it:- decrypts each acceptance;
- checks that each plaintext's
proposalandgroupmatch the event, and that2 ≤ 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
entityIdmakes the overlap visible toaccess().
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:
-
ConfederationCeremonyandConfederationCeremonyMessageentities store inputs (dealer seed, recovery nonce, received messages), never protocol state.advancerecomputes 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, everyt_gand 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, onCeremonyAcrossDevicesJvmTest'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
Confederationentity 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.fromDatavalidates 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 afterkhours with none; a welcome from earlier in the order replaces the room a device holds.
MarmotGroupCreation.createForConfederation(confederation), besidecreateFor: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 ofCeremonyFollowThrough: from aFORMEDceremony 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 checkGroupKeyStateManager.adoptmakes 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.
ConfederationSignerSelectionneeds at leastTgroups and at leastt_gadmins 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
GroupNostrProfileandGroupPost, 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,Reshareand 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.