Files
giza-kmp/docs/confederation-without-coordinator.md
T
Kgothatso NgakoandClaude Opus 5.5 5c5243e6da Merge branch 'giza' into claude/confederation-coordinator-logic-6ad9f4
Notifications took schema 48 first, so the confederation's statements
between inboxes are schema 49, AutoMigration(48, 49).

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

59 KiB
Raw Blame History

A confederation with no coordinator

A plan to take the one person out of the middle of a confederation. Today a confederation (confederation.md) is proposed by a member of group A, and that member becomes the coordinator: every other group's admin list is encrypted to them alone, only their device can tell that the proposal is ready to form, only they can open the key ceremony, the ceremony waits on their broadcast, and only their device makes the confederation's room. If their phone is lost, the proposal lapses.

The groups can now write to each other. A group with an inbox (group-inbox.md) has announced a NIP-4E key in a signed kind 10044 that every one of its admins holds, so a NIP-17 message sealed to that key is read by exactly that group's admins, and a message the group signs is the group's own word. So:

  1. The ConfederationProposalEvent is sent as a NIP-17 message from the proposing group to every invited group that has a NIP-4E key: one conversation whose members are the groups' npubs. This plan calls it the supergroup.
  2. Each invited group answers in the supergroup, with a message its quorum signed.
  3. Everything a coordinator used to decide is either something a group signed or something every device derives from what the groups signed. Nobody coordinates.

Read confederation.md first: this plan changes its Part A and its Part B, and keeps its reasoning wherever it does not say otherwise. Then group-inbox.md, whose seals, wraps, manifest and refusals this plan reuses for a new kind of message. group-threshold-ecdh.md is the other way a group can be written to, and is mentioned where it would fit.

Written against 064ca2c4, on 2026-11-22. Built, Phases 0 to 8, behind ExperimentalFeatures.confederation and ExperimentalFeatures.groupInbox, both off in release; the device run (Phase 9) has not been done. Each phase says under it what was built and where it differs from what it planned. Paths starting K/ are under composeApp/src/commonMain/kotlin/mobi/giza/compose/.

phase commit result
0 f78bd16b, b2f22f2c the plan, and four premises as tests. The broadcast needs no coordinator; the room id is the set of its people; one group's inbox seal opens in another's. A statement grows with the square of the groups: twelve fit, sixteen do not, so a confederation names at most 12 groups, not 64. A welcome for a room a device holds is ignored, which Phase 8 had to handle
1 e2de3fa8 two coordinator behaviours pinned beside the two already pinned
2 c3d70776 the statements as rumors, the attestation, ceremony id and seed, admin lists version 2 -- beside version 1
3 to 5, 7 f64f1619 one commit: statements sealed to every group's inbox and signed by the quorum, read by every admin of every group; the refusals; the ceremony nobody opens, its id from the proposal, its seed from everyone, its broadcast computed everywhere. Schema 48
6 66932a84 the form looks for every group's inbox and stops at twelve; a heard proposal asks after every group's inbox; Try again
8 bad5d122 an order of who makes the room, an hour a place; a welcome from earlier in the order wins
9 this commit the record. No device run

Merged into giza after the notifications work (notifications-and-background-sync.md), which had taken schema 48 for its read marks and ledger first. This plan's storage is therefore v49, AutoMigration(48, 49) with the same spec; every "schema 48" below is that one, as it was numbered while it was built. A relay test this plan added was moved to the subscription manager's new holdConnections parameter. After the merge, full jvmTest 1,845, all passing, with the audits at budget and compileDebugKotlinAndroid building.

Full jvmTest 1,786 at the end, all passing (from 1,776 at Phase 5), with m3Audit, brandAudit and walletAudit at their budgets and compileDebugKotlinAndroid building. Two of the seven full runs along the way died on a segfault in the bundled SQLite driver, inside a background write (UnsignedNostrEvent, under NostrDao.commitPublishedNostrEvent) in a test fork running the identity and database tests, none of which this work touches; each rerun was clean. It is the crash rotate-shares-single-approval.md recorded: a test leaving a write running against an in-memory database it has closed. Not investigated here either.


The two questions, answered first

Can a group be the coordinator of the confederation's DKG?

Yes, and it does not need to be. In upstream's protocol (doc/confederation-protocol.md §7, zkp c68e2384), the coordinator is defined by what it computes, not by who it is:

  • It has no key. Nothing the coordinator sends is signed by it. Every role checks the coordinator's broadcast against dealer records signed by host keys, and a broadcast that does not match is a COORDINATOR fault. The protocol never needs to know who the coordinator is.
  • It holds no secret. It never sees a plaintext share (§7.4: "The coordinator does not see plaintext leaf shares").
  • Its steps are deterministic. ConfederationDkg.coordinatorStep1(roster, sessionSeed, dealings) and coordinatorFinalize(keyState, authorizations, acknowledgments) take no randomness and no secret. Phase 11 of confederation.md already has every device run coordinatorFinalize itself, "so nobody can hand one over".
  • It chooses exactly one thing: the 32-byte session_seed, "fresh random" at session start (§7.1).

So "a group as coordinator" can mean two things, and only one is worth building:

meaning verdict
the group's FROST key signs each coordinator message: the opening, the broadcast no. Every such message would be a quorum signing session, with t_g people asked and the ceremony waiting on them, to put a signature on a value every participant can recompute and must check anyway. The signature adds nothing a role can use
the group makes the coordinator's choices, by signing them yes. Which groups, T, the name and the expiry are already in the proposal the proposing group signs. The session seed becomes a value derived from every participant's contribution (D9). There is nothing else to choose

After that, nothing is left for a coordinator to do. The broadcast is computed by every device from the dealings it holds, as the genesis certificate already is (D8). The confederation's signing (Part C) went the same way in Phase 14: "the transcript, the certificate, every group's partial and the signature take no secret, so every device computes them". This plan finishes the job for the DKG.

Can the admin pubkeys stop being an encrypted payload?

Yes. The admin lists are encrypted today only because one person, the coordinator, had to read them and nobody else could be written to: no group could be encrypted to, so each acceptance was NIP-44-sealed to the coordinator's key with an ephemeral key every signer could recompute (confederation.md D5), and the coordinator later disclosed one conversation key per acceptance so every participant could open them (D7).

In the supergroup, every message is already read by exactly the admins of every participating group, and nobody else. That is exactly the set of people the ceremony will put in one room, and D7 already concluded that "nothing is disclosed that the room would not disclose". So the admin list goes in the clear inside the rumor, and NIP-17's own layers keep it from everyone else. What goes away:

today after this plan
the acceptance's content is a NIP-44 payload to the coordinator the rumor's content is ConfederationAdminList's canonical JSON
the epk tag and an ephemeral key per acceptance gone
["confederation_seal", e] riding the FROST proposal, so each signer recomputes the ciphertext byte for byte gone. A signer compares its own view of the admins with the plaintext it is asked to sign
D7: the opening discloses one conversation key per acceptance gone. Every participant already read every acceptance
ConfederationSeal, ConfederationEphemeralKeyTag, ConfederationSealTag deleted

The admin pubkeys still have to be shared: the roster needs them, and every participant must be able to check every other group's segment before joining, or a group could slip an extra role into the roster. What changes is that they are shared directly with the people who need them, at the moment the group accepts, instead of through one person.


What changes, in one table

today (confederation.md) this plan
who proposes a member of A, who becomes the coordinator group A. The member who pressed the button is only the proposer of A's signing session
how statements travel public regular events, kinds 9430–9433, on relays rumors of the same kinds, in the supergroup, each sealed by its group's quorum. Nothing about the proposal is public until the charter (9434)
who can take part a group with a public kind:0 a group with a public kind:0, a 10044 and a 10050 (an inbox)
who reads the admin lists the coordinator, then every participant through D7 every admin of every invited group, as each group accepts
who sees the proposal is ready the coordinator's device every admin's device in every group
who opens the ceremony the coordinator, by a button nobody. Every admin is offered Join once every group has accepted
the ceremony's room a NIP-17 room the coordinator makes the same room, whose id every device derives from the roster's people
the session seed random, from the coordinator derived from a random contribution in every person's first message
the broadcast (30383) sent by the coordinator computed by every device; not sent
the confederation's Marmot room made by the coordinator's device made by the first role holder in a fixed order who is able to, with a fallback
if one person's phone is lost the proposal lapses at expiry nothing; any admin of any group carries on

Decisions

D1. The supergroup is one NIP-17 conversation whose members are the groups

A NIP-17 chat is the set of the rumor's author and its p tags. A rumor authored by group A, p-tagged with every other invited group, belongs to the conversation of all the invited groups, and every group's reply to it, tagged the same way, lands in the same conversation. That is the supergroup. It has no id of its own beyond the set; this plan files it under the proposal's rumor id, which is unique.

Each message is the inbox's reply shape (group-inbox.md D10), with the group as the author and the other groups as recipients:

rumor   kind 9430 | 9431 | 9432 | 9433, pubkey = the sending group's npub, unsigned
        tags: ["p", <every other invited group>] …, and for an answer ["e", <proposal rumor id>]
        content: canonical JSON (D4)

for each invited group g, the sender included:
  seal  kind 13, pubkey = the sending group's npub
        tags:    [["n", <the sender's announced inbox key>]]
        content: nip44(rumor, conv(sender's inbox secret, g's announced inbox key))
        created_at: now minus up to two days, at random (NIP-59)

  wrap  kind 1059, a fresh key, p = g's npub, to g's 10050 relays

The sender's own copy is how its other admins see what it said, as for a reply. Every recipient's admins open their seal with their own inbox key, check the seal's FROST signature, and check the rumor's pubkey is the seal's.

Why the groups must have an inbox, and not merely a 10050. A group that has opened its messages by threshold ECDH (group-threshold-ecdh.md) can also be written to at its npub, and could be a member of a supergroup. It costs t admins' apps per message to read, and the confederation's messages arrive in bursts that every admin needs at once. This plan requires NIP-4E, as asked, and lists threshold ECDH as an extension.

Why rumors of the confederation's own kinds, and not kind 14. Nobody reads a group's inbox with a stock NIP-17 client: the inbox secret is only ever on Giza devices. So there is no reader a kind 14 would help, and the kinds keep ConfederationProposalEvent.parse and its siblings. A v field in the content (D4) tells them from the public events of today.

D2. The proposing group proposes. No person is named

The proposal's coordinator tag is dropped, and with it D4 of confederation.md: the check that the coordinator is the session's proposer and a current admin. What a signer of A checks instead is that this device's member, if it is signing, is a current admin who holds A's inbox key (D6).

The member who pressed Propose is visible to A's members as the proposer of A's signing session, and to every other group only as one of A's admins. Their phone matters until A's quorum signs, and not after.

D3. Statements are rumors, made binding by the group's signed seal

A rumor is unsigned. What makes it the group's word is the seal: a kind 13 authored by the group's npub and signed by its quorum through FROST, whose content opens to the rumor, with the rumor's pubkey equal to the seal's. That is the same guarantee a recipient has for any NIP-17 message, and the one group-inbox.md relies on for replies.

What a seal is not is transferable: B can check A's seal to B, but cannot show it to C without handing over the conversation key. So no device relies on another group's copy. Each group receives its own sealed copy of every statement, and checks that copy. Two questions follow:

  • Can a group say different things to different groups? Its honest signers will not sign it: every signer opens every seal in the batch and declines unless they all hold the same rumor, byte for byte (group-inbox.md D12, step 4). A dishonest quorum could. Then two groups hold different rumor ids for the same group's statement.
  • What catches that? The roster. Its attestation_ref is a hash over the proposal's rumor id and every acceptance's, in roster order (D8), so two devices that hold different statements build different rosters and the ceremony cannot finish. D8 also puts the reference in every person's first ceremony message, so the split is found before anyone deals, and named by group.

The public events had one property this loses: anyone could see, on relays, which groups were invited and how each answered. confederation.md listed that as a cost ("The proposal is public metadata"). This plan turns it into a choice the confederation makes later, by signing its charter.

D4. The proposal carries the proposing group's own acceptance, and the lists travel in the clear

One rumor, not two. confederation.md D3 signed the proposal and the proposer's acceptance as a batch of two, so that a proposal never exists without its proposer's admin list. In the supergroup each statement costs one seal per group, and a batch holds at most FrostSigningManager.MAX_BATCH_SIZE = 64 events. Two statements would be 2N seals, more than 64 above 32 groups. So the proposal's content is the proposing group's admin list, and a proposal is its proposer's acceptance by construction:

9430 rumor, content:
{"v":2,"group":"<A's npub>","threshold":<t_A>,"admins":["<hex>", …]}     admins sorted bytewise
tags:
  ["p", <each other invited group>] …
  ["threshold", "<T>"]
  ["name", <the confederation's name>]
  ["nonce", <32 random bytes, hex>]
  ["expiration", "<unix seconds>"]

9431 rumor, content:
{"v":2,"proposal":"<proposal rumor id>","group":"<B's npub>","threshold":<t_B>,"admins":[…]}
tags: ["p", …], ["e", <proposal rumor id>]

9432 rumor, content: an optional reason, plain text      tags: ["p", …], ["e", <proposal rumor id>]
9433 rumor, content: an optional reason, plain text      tags: ["p", …], ["e", <proposal rumor id>]

ConfederationAdminList keeps its strict decoder, at v: 2, with proposal absent on a 9430 (it is the rumor's own id, which the content cannot contain). The group field is kept even though the rumor's pubkey says the same, so the list read on its own still says whose it is.

When the lists are seen. Each group's admins are seen by every invited group's admins at the moment it accepts, including any group that goes on to reject. Today only the coordinator sees them before every group has accepted. The approval screen of an acceptance says so, naming the groups: "Accepting shows the admins of this group to the admins of Ekklesia, Agora and Polis." A commit-then-reveal exchange would hide them until every group has accepted, at the price of a second signing session per group; it is in the appendix, not planned.

D5. A group's inbox is a precondition, checked at three points

confederation.md D2 required "a public nostr profile". This plan keeps that, for the name, and adds the inbox:

where check if it fails
proposing, for every listed group, the proposer's own included a valid kind:0, a valid 10044 naming one key and a valid 10050, each authored by the group's npub, fetched from relays that group cannot be added; the picker says which is missing
proposing, for the proposer's own group this device holds the inbox key A has announced Propose is disabled: "Set up the group's inbox first"
answering the same for this group, and a 10044 for every other listed group refused (D6): the answer could not be delivered to every group

A group that rotates its inbox key while a proposal is open (an admin change does, group-inbox.md D14) keeps reading with its old key, which is kept for reading only. Its admins have changed, so its acceptance no longer matches its admins and the ceremony refuses to start over it, which is today's rule ("The admins of … have changed since it accepted"). The proposal is made again.

D6. One signing session per statement, and every signer reads what it signs

A statement is proposed through proposeSigningBatch: the N seals (one per invited group, own copy included), with two hidden tags in the MLS-encrypted proposal:

["inbox_manifest", …]            group-inbox D11, unchanged: each seal's recipient, key and 10044
["confederation_rumor", <the rumor's JSON>]
["confederation_invitation", <the signed seal that delivered the proposal to this group>]   answers only

confederation_rumor is in the clear, inside the room's encryption, on purpose: every member of the group, admin or not, sees what the group is being asked to say about a confederation, which today they see on relays. Only the other groups' lists stay with the admins. confederation_invitation does for an answer what today's confederation_proposal tag does: a signer does not depend on its own inbox having received the proposal. It opens the carried seal with its own inbox key and checks A's signature on it.

ConfederationRefusal gains a seal arm, in the four places it already sits. The batch is routed to it, and not to InboxRefusal's reply checks, by the confederation_rumor tag: a batch of kind 13s with that tag is the confederation's, and one without is a reply or a threshold-ECDH message, as today (GroupSealRoutingJvmTest gains a case). A signer:

  1. declines unless this device holds the group's announced inbox key ("This device can't read what the group would be sending"). That is a share-holder who is not a current admin;
  2. opens the manifest and every seal, and declines unless every seal holds the rumor in confederation_rumor, byte for byte, and the seals are exactly one per listed group, each to the key that group's carried 10044 names;
  3. checks the rumor: its kind, its p tags exactly the other listed groups, its pubkey this room, its created_at within ten minutes of now;
  4. for a 9430: N in 2..64, T in 2..N, the expiry in the future and at most 30 days away, this room listed, and the content equal to the admin list this device builds from RoomAdmins.of and the threshold its active share generation signs with;
  5. for a 9431: the carried invitation opens with this device's inbox key to a 9430 from its author, that lists this room, and is not expired, withdrawn or rejected on this device; this group has not answered; the content matches this device's own admin list, as for a 9430;
  6. for a 9432: the same invitation check, and this group has not answered;
  7. for a 9433: this room wrote the proposal, and it is not yet ACCEPTED on this device.

Warnings, shown and not refused, as confederation.md D6 drew the line: a listed group whose kind:0 cannot be found right now; a listed group this device has never seen; an expiry within a day; and, on an acceptance, the sentence of D4 naming who will see the list.

D7. Every admin of every group holds every statement, and computes the state

Statements arrive through the inbox pipeline (GroupInboxManager), which already subscribes to wraps addressed to every group this device holds an inbox key for. A rumor of a confederation kind is handed to ConfederationManager instead of being filed as an inbox message, and is stored with the seal that delivered it, as evidence (Phase 5).

ConfederationStatus is unchanged in substance: OPEN, ACCEPTED, REJECTED, EXPIRED, WITHDRAWN, computed from stored statements whenever it is read, with an answer counting only if its rumor's created_at is by the expiry, and a rejection beating an acceptance. The rumor's created_at is the group's: its quorum signed the seal over it, and every signer checked it was now (D6, step 3).

What changes is who can compute ACCEPTED: every admin of every invited group, because each holds every statement. So every one of them is shown Join the key ceremony at the same moment, with no one opening it (D8).

Members who are not admins see a line in their group's room when their group signs a statement, from the signing session, as today. They do not see other groups' statements. That is less than the public events gave them, and the charter is still how they learn the confederation exists.

D8. The ceremony has no coordinator

The ceremony's rounds are unchanged but for the two that had a sender with authority:

kind today this plan
30380 opening the coordinator's: the 9430, every 9431, D7's keys, the session seed not sent. Every device builds the same opening from the statements it holds
30381 host keys each person, one key per role each person, one key per role, plus a 32-byte random seed and the attestation_ref this device built
30382 dealings each person each person, under the derived seed (D9)
30383 broadcast the coordinator's, checked byte for byte not sent. Every device runs coordinatorStep1 over the dealings it holds
30384 authorizations each person each person, plus the operation_session_id this device computed
30385 acknowledgments each person unchanged
30387 failure anyone unchanged

The implicit opening. Once a device holds an ACCEPTED proposal it builds the plan as ConfederationRitualManager.planFrom does today, from the statements instead of an opening:

groups            = the proposal's group npubs, sorted bytewise
admin lists       = the proposing group's from the 9430's content, every other group's from its 9431
attestation_ref   = TaggedHash("mantra/confederation/attestation/v2",
                               proposal rumor id || each other group's acceptance rumor id,
                               in groupId order, the proposal's id standing for the proposing group)
ceremony id       = TaggedHash("mantra/confederation/ceremony/v1", attestation_ref || attempt as u32)
the room          = createNip17ChatRoom over the roster's people: id deriveChatRoomId(people),
                    the same on every device whoever makes it

ConfederationRosterBuilder is otherwise unchanged; the host-key derivation keeps its tag, and the attestation tag moves to v2 because its inputs are rumor ids now. The mantra/… spelling is the house rule for protocol tags (CLAUDE.md).

Joining is still the only approval. Each admin is asked once, on the proposal's screen. Joining sends this person's 30381. A message that arrives before this device has every statement, or before its owner joins, is stored and replayed, as replayStoredMessages does today for messages that beat the opening.

Splits are found before dealing. A device that receives a 30381 whose attestation_ref is not its own fails the ceremony out loud, naming the group whose statement differs. It can name it because the 30381 also carries the rumor ids it was built from. That is D3's equivocation, caught at the first message, before anyone has dealt.

The broadcast on every device. coordinatorStep1 is a pure function of the roster, the seed and every role's dealing, all of which every device holds once the dealings are in. Each device computes it and goes on to participantStep2 with its own result. Two devices that received different dealings from one dealer (a dealer that sent different gift wraps to different people) compute different broadcasts, sign different transitions, and the authorizations do not verify. The operation_session_id in each 30384 is what lets a device say so plainly ("Ekklesia's and Agora's admins received different dealings") instead of failing on a signature.

Blame narrows. Upstream's ROLE_OR_COORDINATOR fault ("either they or the coordinator, who relayed it") cannot point at a coordinator that is this device itself, so it reads as the dealer's, with the caveat that a recipient's claim of a bad share is still only its claim. Every device holds every dealer's evaluation vector, which is what upstream's investigation needs; running it locally is an extension (Out of scope), as investigation is today.

D9. The session seed is everyone's

Upstream asks for a "fresh random 32-byte session_seed", that each role rejects if it has seen it before. With no coordinator to choose it:

session_seed = TaggedHash("mantra/confederation/session-seed/v1",
                          attestation_ref || attempt as u32 || every person's 30381 seed, in roster person order)

It is computed once every 30381 is in, before anybody deals, which is where the coordinator's seed was used first. It is unique as long as one person's seed is fresh, and nobody can know it in advance unless every person colludes. Phase 0 asks upstream to confirm that a seed fixed after the host keys, rather than before, meets §7.1. If upstream needs it earlier, the fallback is the seed without the contributions, which is unique (the proposal's nonce and the attempt make it so) but known in advance.

D10. A retry is a new attempt, which anyone may start

A ceremony that fails, or is abandoned, can be tried again over the same roster: the same statements, a new attempt number, so a new ceremony id and a new seed, and every person asked to join again. Any person in the roster may press Try again, which joins attempt k + 1 and sends its 30381 for it. A device moves to k + 1 only once attempt k has failed or been abandoned there, so two people pressing at once land in the same attempt. An attempt number more than one past the newest this device knows is held until the one before it ends.

D11. The confederation's room: a fixed order of who makes it, and a fallback

confederation.md Phase 13 had the coordinator's device make the Marmot room. MLS needs one creator, so the role is kept, but no single person holds it:

  • The order is the roster's people sorted bytewise. The first is the creator.
  • The fallback. Person k in the order makes the room only if no welcome for it has arrived k hours after the ceremony completed on their device. One person away delays the room by an hour, not forever.
  • A tie. Two people who both create it (a clock skew, a welcome that has not yet arrived) make two MLS groups with the same group id. A device that receives a welcome for a room it already created, or two welcomes, keeps the one whose creator sorts first and leaves the other. Phase 0 checks what Marmot does when this happens before this rule is written down as final.

The room is otherwise what Phase 13 made: id marmotGroupId(02‖X), every role holder a member and an admin, governed by Quorum.minimumAdmins(T).

D12. Part A's public wire goes, but for the charter

Kinds 9430–9433 stop being sent to relays. The live-confederation subscription keeps only what is still public: the charter (9434), #p-tagged to each group, which is how members who are not admins learn of a formed confederation. ConfederationPublisher keeps sending charters; the statements are owed through GroupInboxPublication, the inbox's one table for what it owes relays.

Nothing here has shipped in a release: ExperimentalFeatures.confederation is off in release, so there is no peer to stay compatible with. A development build's stored v1 statements and ceremonies are dropped by the migration (Phase 2), with a line in each room they were filed in.

D13. Behind both flags

A confederation needs ExperimentalFeatures.confederation and ExperimentalFeatures.groupInbox. With either off, the entry point is hidden and every refusal still runs, as every refusal does: a release build declines a peer's confederation seal batch out loud rather than signing it blind.


Who is asked what

step who is asked what they decide automatic after that
propose one admin of A the groups, T, the name and expiry building the rumor, the seals and the manifest
A signs A's quorum that A proposes this, with these admins wrapping and sending to every group's 10050 (proposer's device)
invitation arrives nobody — every admin's device in every invited group files it and writes a line
B answers one admin of B, then B's quorum accept or reject wrapping and sending
all accepted nobody — every admin's device shows Join
ceremony each admin of each group to join every round after the join; the seed; the broadcast
a retry any person in the roster to try again, which is their join as above
room nobody — made by the first person in the order who can, with the fallback

Phases

One commit per phase, in the repository's style (feat: … (confederation-without-coordinator, Phase n)). Every phase leaves ./gradlew :composeApp:jvmTest and :composeApp:m3Audit green, and check's brand and wallet audits at budget.

Phase 0: this document, and six checks

This document and its row in README.md. Then, before code:

  1. The session seed (D9). Ask upstream whether a session_seed fixed after the host keys and derived from every role's contribution meets §7.1, and record the answer here. Raise it beside the open review (doc/confederation-review.md section 21). Until answered, build D9's fallback-ready: the seed function takes the contributions as an optional input.
  2. The broadcast is deterministic. A jvmTest on ConfederationReachableJvmTest's three groups: coordinatorStep1 over the same dealings, in any input order, gives the same bytes; and participantStep2 accepts a broadcast computed on the participant's own device.
  3. The room id. createNip17ChatRoom over the same people, called by two different users, gives the same ChatRoom.id, and the inbound path files a ceremony message into that room on a device that has not made it yet.
  4. A batch of 64 seals. On the inbox's harness, a statement to 64 groups proposes, signs and wraps; record the FROST proposal's size with the manifest and both confederation tags against the MLS message limit the app uses. If it does not fit, the maximum N comes down and D5's picker says so.
  5. Group to group. A seal from group A's inbox key to group B's announced key, wrapped to B's npub, is filed by GroupInboxManager.receive on B's admins' devices, opened with the seal's n tag, and the seal verifies as A's room. Today it would land in B's inbox as a message this screen cannot show; the test pins that, and Phase 5 flips it.
  6. Two creators (D11). What Marmot does with two welcomes for one group id, and with a welcome for a group this device created. The answer decides D11's tie rule.

Done when all six are recorded here, and checks 2, 3 and 5 are tests.

Done, on 2026-11-22. ConfederationWithoutCoordinatorPremiseJvmTest keeps checks 2 to 5:

check result
1. the session seed asked, not answered. §7.1 asks only that a seed be fresh and never reused within a role; nothing in §7 needs it before the host keys exist, since the host keys do not take it. D9 is built as written, with the contributions as an input that can be dropped
2. the broadcast holds. coordinatorStep1 gives the same bytes over the same dealings in any order, and every role going on with the broadcast it computed itself reaches the same key
3. the room id holds. Two people calling createNip17ChatRoom over the same people get the same ChatRoom.id
4. size D4's ceiling is wrong. The bytes a statement's FROST proposal carries grow with the square of the groups (each seal holds a rumor naming every group): 5 KB for 2 groups, 28 KB for 8, 44 KB for 12, 65 KB for 16, 609 KB for 64, at five admins a group. So a confederation in the supergroup is held to 12 groups (ConfederationKinds.MAX_SUPERGROUP_GROUPS), and every statement is checked against 60,000 bytes when it is proposed (MAX_STATEMENT_BYTES), since an admin list of 128 adds about 8 KB a seal. The one-rumor proposal of D4 is still right: two would halve the ceiling again
5. group to group holds. A seal from A's inbox key to B's announced key, wrapped to B's npub, is opened by B's admin with the seal's n tag and verifies as A's. Today it is filed as an inbox message of kind 9430; Phase 5 flips that
6. two creators a welcome for a room id the device already holds is ignored (NostrDao's welcome branch joins only when findChatRoomById is null). So with two creators each device keeps whichever welcome reached it first, and the room splits. D11's tie rule needs code in the welcome path: for a confederation's room, a welcome from a creator who sorts before the one this device joined under replaces it. Phase 8

Phase 1: pin today

ConfederationCoordinatorTodayJvmTest, written to pass now and flipped on purpose:

  • an acceptance is a NIP-44 payload only the coordinator's key opens, and outcome returns null on any other device (Phase 7 flips it: every admin's device computes the outcome);
  • an opening from someone other than the proposal's coordinator is refused (Phase 7 removes the opening);
  • a ceremony waits on the coordinator's 30383 (Phase 7 flips it);
  • only the coordinator's device makes the confederation's room (Phase 8 flips it).

Done. Two of the four were pinned already: ConfederationNetworkJvmTest's "the coordinator's device says what forming it would take, and nobody else's says anything" (outcome is null on every other device) and ConfederationCeremonyJvmTest's "a member's key package missing holds the room back, and nobody else's device makes it". The other two are new tests in ConfederationCeremonyJvmTest rather than a file of their own, since they need its devices: "today an opening sent by anyone but the coordinator is refused" and "today every device waits on the coordinator's broadcast".

Phase 2: the wire, and the storage

K/nostr/confederation/:

  • ConfederationStatements: builds and parses the four rumors of D4, with v: 2 content and no coordinator tag. ConfederationProposalEvent.Proposal loses coordinator and gains the proposing group's ConfederationAdminList.
  • ConfederationAdminList at v: 2, strict, with proposal absent on a 9430.
  • ConfederationSupergroup: the recipient set (every listed group), and the supergroup's key (the proposal rumor id).
  • ConfederationAttestation: D8's attestation_ref and ceremony id, D9's seed.
  • ConfederationRitualEvents: drop OPENING and BROADCAST; 30381 gains seed, attestation_ref and the rumor ids; 30384 gains operation_session_id; an attempt tag on every ceremony message.
  • Delete ConfederationSeal, ConfederationEphemeralKeyTag, ConfederationSealTag and ConfederationCoordinatorTag.

Storage, schema 47 → 48:

table change
ConfederationEvent holds rumors: rumorJson, sealJson (the seal that delivered it here, as evidence), inboxRoomId (whose inbox opened it); publishedAt and ownSessionId go, since the inbox's publication table owes wraps
ConfederationSigning sealSecret goes; invitationSealJson replaces proposalJson
ConfederationCeremony coordinatorPublicKey and openingJson go; attempt, attestationRef and seedContribution come

The migration is a manual one, not an AutoMigration: it drops every v1 row (D12) and writes one transcript line per room that held one. ShippedProfileUpgradeJvmTest's current moves to 48.

Tests (ConfederationStatementsTest, pure; ConfederationStorageJvmTest): round trips; the admin list's bytes are the same in any input order; attestation_ref is the same for the same statements in any order and different for any one rumor id changed; the seed changes with any contribution and any attempt; the migration leaves no v1 row.

Built, as the wire alone. ConfederationStatements (the four rumors, built and parsed all or nothing, with Proposal and Answer), ConfederationAttestation (D8's reference and ceremony id, D9's seed) and ConfederationAdminList version 2 (a proposal's own list carries no proposal and is bound to the rumor's id when parsed) sit beside version 1, so every commit between here and the switch builds and passes. ConfederationSupergroup was not needed: a statement's recipients are Proposal.othersThan, and the conversation is filed under the proposal's id. ConfederationKinds.MAX_SUPERGROUP_GROUPS (12) and MAX_STATEMENT_BYTES (60,000) carry Phase 0's check 4. ConfederationStatementsTest 10/10. Storage moved to Phases 3 to 5, with the code that writes it: dropping version 1's rows makes sense only once nothing writes them.

Phase 3: sending into the supergroup

  • Lift InboxReplies.build into InboxMessages.build(roomId, rumor, recipients, inboxSecret, generation), which takes a rumor instead of text. InboxReplies calls it with its kind 14, so the reply path is byte-identical (its tests pin it).
  • ConfederationManager.proposeConfederation, proposeAcceptance, proposeRejection and proposeWithdrawal build the rumor (Phase 2), resolve every listed group to InboxReplies.Recipient through its 10044, and propose the seals with D6's three tags.
  • ConfederationManager.onSigned, on the proposer's device, wraps every seal and owes it to its group's 10050 relays through GroupInboxPublication, as InboxReplies.wrapAndOwe does, and files its own statement at once. Send again works on any admin's device that holds the session's manifest.
  • ProposedEvent summarises a confederation seal batch from confederation_rumor: "Propose a confederation, Atlas, with Ekklesia, Agora and Polis, 2 of 3 to act", and so on. A member who is not an admin reads the same sentence.

Tests (ConfederationSupergroupSendJvmTest, on the inbox's harness with three groups): a proposal from A reaches B's and C's admins' inboxes as seals that open with their own keys; A's own copy opens on A's other admins' devices; nothing is published bare to relays.

Phase 4: the refusals (D6)

  • ConfederationRefusal's seal arm, with D6's seven checks, in the four places.
  • FrostSigningManager's routing of kind 13 batches: confederation_rumor present → the confederation; otherwise the inbox or threshold ECDH, as today.
  • The signing screen shows D6's notes: the groups by name, T, the admin list being shown and to whom, and the warnings.

Tests (ConfederationDeclineJvmTest, rewritten on the seal path): each refusal on its own, each declined with its reason and the decline shown on the proposer's device: a share-holder without the inbox key; seals holding different rumors; a seal to a key that is not the group's announced one; a missing or extra group; an admin list that is not this device's; a second answer; an expired, withdrawn or rejected proposal; an invitation that does not open or is not A's. GroupSealRoutingJvmTest gains the confederation case.

Phase 5: receiving (D7)

  • GroupInboxManager.open hands a rumor of a confederation kind to ConfederationManager.recordRumor with its seal and room, and does not file it as an inbox message. It keeps the wrap in the inbox's ledger as opened, so redelivery is a no-op.
  • recordRumor checks the seal is signed by the rumor's author, the author is a listed group (or, for a 9430, lists this room), and files it. Transcript lines as today, written by every admin's device in each of its own rooms the proposal names, once per statement.
  • live-confederation narrows to charters (D12). Statements need no new subscription.
  • ConfederationStatus reads rumors.

Tests (ConfederationNetworkJvmTest, rewritten): three groups of three on nine devices, each with an inbox; A proposes, B accepts, C rejects, and every admin's device in A, B and C computes REJECTED; then a second proposal that B and C accept reaches ACCEPTED on every admin's device, with no device singled out. A member who is not an admin files nothing from the supergroup. The Phase 0 check 5 pin flips.

Phase 6: the screens

  • ProposeConfederationScreen: each group resolves to its kind:0, 10044 and 10050 (D5); Propose is disabled until this group has announced an inbox this device holds. No coordinator is shown.
  • ConfederationProposalScreen: the proposing group, every group's answer, T, the expiry, the state; for an admin, the admin lists already received; once ACCEPTED, Join the key ceremony for every admin of every group. The coordinator's outcome card goes.
  • ConfederationRitualScreen: the ladder names who it waits on, grouped by group, as today; Try again on a failed or abandoned attempt (D10).
  • Strings in the catalogue, sentence case, no "coordinator", no "NIP-4E" and no "supergroup" said to a person: "the groups' private conversation" where it has to be named.

Tests (ConfederationScreensJvmTest): the join offered on every admin's device once accepted; the propose button's reasons; no coordinator line anywhere.

Built. The form asks the relays for each group's kind:0, 10044 and 10050 in one request (DirectMessagePeerSync.GROUP_KINDS) and shows a group with a profile and no inbox as out of reach (Lookup.NoInbox); Propose waits on this group's own announced inbox key; a thirteenth group is refused (MAX_SUPERGROUP_GROUPS). Two things the phase did not list: a device that hears a proposal in its inbox asks the relays about every named group whose inbox it has not heard (ConfederationManager.askAboutGroups), since answering seals to every group's announced key; and Try again sits on the ceremony screen under a failed attempt, calling the same join. The admin lists already received are not listed on the proposal screen: the outcome's role count and overlaps say what matters, and the ceremony screen lists every group's admins. The join and the coordinator's removal from every screen landed with Phases 3 to 5 and 7, since the code would not compile without them. ConfederationScreensJvmTest 15/15, ProposeConfederationViewModelJvmTest 12/12, ConfederationStorageJvmTest 10/10. Full jvmTest 1,784, all passing; m3Audit, brand and wallet audits at budget.

Phase 7: the ceremony without a coordinator (D8, D9, D10)

ConfederationRitualManager:

  • open and acceptOpening are replaced by planFor(proposalId), the implicit opening, and join, which makes the room (D8) if it is not here and sends this person's 30381.
  • eligibility keeps every check but the coordinator's: the statements verify, the state is ACCEPTED here, the room is exactly the roster's people, and each of this device's groups still has the admins it accepted with.
  • advance step 1 sends seed and attestation_ref; a mismatching attestation_ref fails out naming the group. Step 3 runs coordinatorStep1 on this device and keeps the broadcast in the ceremony row; there is no 30383. Step 4's 30384 carries the operation_session_id; a mismatch fails out naming the dealer whose dealings differ.
  • describe's COORDINATOR and ROLE_OR_COORDINATOR lines are reworded for a coordinator that is this device.
  • Attempts (D10).
  • ConfederationManager.outcome loses its coordinator key and runs on every admin's device.

Tests (ConfederationCeremonyJvmTest, rewritten): three groups of three on nine devices reach one key that signs as the room, with no device opening anything, whichever admin joins first; one person in two groups; a group that equivocated (different 9431s to B and C) fails at the 30381, naming it; a dealer who sent different dealings to two people fails at the 30384, naming them; a holdout and abandon, then Try again reaching a key in attempt 2 with a different seed; admins changed; a restart mid-round. The Phase 1 pins on the opening and the broadcast flip.

Phases 3, 4, 5 and 7 built, in one commit, with schema 48 from Phase 2. They could not be split: a statement is an unsigned rumor, so a coordinator's opening that carried statements would have held nothing a participant could check, and the ceremony had to stop being opened in the same change that stopped Part A being public. Where the build chose differently from the phases above:

what the plan said what it turned out to be
D8: ceremony id from attestation_ref and the attempt from the proposal's id and the attempt. Built as planned, a group that told two groups different things gave their admins different ceremony ids, so each side waited in a ceremony of its own for people who never came, and the attestation check in the 30381 never ran. With the id from the proposal, every device meets in one ceremony and the first message names the group
D8: the room every device derives as planned; and a device replays a ceremony's waiting messages from any room (GiftWrapPayloadDao.getByKinds), since a sender whose statements differ names other people, and so another room
Phase 7: planFor(proposalId) basisFor, planFrom(basis) and planOf(ceremony). The basis (the proposal and every acceptance, as rumors) is kept on the ceremony as basisJson, the renamed openingJson
Phase 7: join makes the room if it is not here and the ceremony row itself: nothing is made on a device until its owner joins. Messages that came before are replayed; a missed abandonment ends a late joiner's attempt at once
D10: Try again join after a failed or abandoned attempt joins the next one, so the screen needs no second button
Phase 2: ConfederationEvent loses publishedAt and ownSessionId kept: the charter is still owed to public relays by ConfederationPublisher. A statement's wraps are owed through GroupInboxPublication, by InboxReplies.onSigned as for a reply
Phase 2: a manual migration an AutoMigration(47, 48) with a spec: @DeleteColumn and @RenameColumn, and onPostMigrate dropping version 1's statements and every ceremony and confederation built on them
Phase 3: InboxMessages.build InboxReplies.sealRumor, which InboxReplies.build now calls; and InboxRefusal.readSealed, the reply's checks for any rumor kind, which the confederation's refusal calls
D6: a statement's confederation_invitation the seal that brought the proposal to this group, from the store; none for the proposing group's own statements
D6: a 9433 withdrawal built with any group as its author, so a group that tries to withdraw another's proposal is declined by its own signers (NOT_PROPOSER) rather than refused by the builder
Phase 8: Phase 13's room made, for now, by the first of the roster's people, sorted (ConfederationFollowThrough.creatorOf). The fallback and the tie are Phase 8
outcome: a group with no profile on this device stops the ceremony a note, not a problem: every device computes it now, and a lookup that has not come back on one device would have stopped only that device's join

Tests, all passing: ConfederationNetworkJvmTest 7/7 on a harness of three groups of three, each with a real inbox ceremony (ConfederationTestGroups, now a harness, over a GroupInboxHarness that takes its dealer key and room name); ConfederationDeclineJvmTest 15/15 on the same; ConfederationCeremonyJvmTest 13/13 and ConfederationSigningJvmTest 7/7 on ConfederationPeople (every admin of every group with every statement filed beside its seal, from ConfederationStatementFixture); ConfederationStorageJvmTest 9/9; ConfederationStatusTest 11/11 in place of the version 1 ConfederationEventsTest; ConfederationRelayTest 6/6, now only charters. ConfederationSealPremiseJvmTest went with the seal. Not tested: a member who is not an admin filing nothing from the supergroup is the inbox's own test (GroupInboxReadJvmTest), not repeated here; and a restart mid-round is covered only by every step being a function of stored messages, as before.

Full jvmTest 1,776, all passing; m3Audit, brandAudit and walletAudit at their budgets; compileDebugKotlinAndroid builds. One earlier run of the suite ended in a segfault inside the bundled SQLite driver, during an UnsignedNostrEvent upsert on a background coroutine -- code this change does not touch, and it did not happen again.

Phase 8: the room (D11)

  • ConfederationFollowThrough.takeNextStep creates the room on the device whose owner is first in the order, or k-th after k hours with no welcome; Phase 0 check 6's tie rule on welcome.
  • The proposal screen and the room's card say who is making the room and since when, by name.

Tests: the first person makes it; with the first away, the second does after the delay; two creators end in one room on every device. The Phase 1 room pin flips.

Built. ConfederationFollowThrough.takeNextStep takes a clock and lets the person at place k in the order make the room k hours after the confederation formed on their device, with no room here; the follow-through looks again every ten minutes as well as on every key package, since a wait running out is not an event. A confederation records whose group this device holds as its room (Confederation.roomCreator, folded into schema 48): its own when it makes it, the welcome's sender when it joins. NostrDao's welcome branch now joins a room it already holds when ConfederationFollowThrough.welcomeReplaces says so: a confederation's room, a welcome from one of its people, earlier in the order than the creator it holds. Never any other room. ConfederationCeremonyJvmTest 15/15: the first person's device makes it and records itself; the second makes it after an hour and not before, and the third waits two; a welcome from earlier in the order wins, from later or from an outsider does not, and no other room is touched. Not tested: two welcomes for one id through the real MLS welcome path on one device. The harness makes no welcomes a device can open (its key packages keep no private half), so the tie is tested at the decision, not through the join. Full jvmTest 1,786, all passing; m3Audit, brand and wallet audits at budget; compileDebugKotlinAndroid builds.

Phase 9: the record, and devices

The record done; the device run not. Nothing here has run across real devices, relays or an iOS build: no statement has crossed real inboxes, no ceremony has formed with nobody opening it on more than one real device, and no confederation's room has been made by the second in the order.

  • Mark this plan built, with a what the plan said / what it turned out to be table, and update the README row. In confederation.md, a since note on D3, D4, D5, D7, Phase 11 and Phase 13 pointing here, and its What this does not do line on the coordinator struck.
  • Device run, three groups of three on at least five devices or emulators, each group with an inbox, one person an admin of two groups:
    1. A proposes; A's quorum signs; B's and C's admins see the invitation, and nothing is on public relays but wraps.
    2. B and C accept; every admin's device in every group shows Join at once.
    3. Close the phone of the admin who proposed. The ceremony still forms, and the room is made.
    4. Abandon one attempt, try again, and form in the second.
    5. Sign the confederation's kind:0 and charter, and see the charter reach a member of B who is not an admin.

What this does not do

  • It depends on NIP-4E. The confederation inherits the inbox's dependency on two open draft pull requests (nostr-protocol/nips#1647 and #2361), and the inbox's flag. A group without an inbox cannot take part.
  • It is less public. Who was invited and who answered how is no longer on relays. The charter is the confederation's one public statement, after it forms.
  • Members who are not admins see only their own group's statements, through its signing sessions, until the charter.
  • A stolen admin phone reads what the group is sent, including other groups' admin lists, until the group's inbox rotates (group-inbox.md D14). That is the inbox's own risk; the coordinator's phone was the same risk for every group at once.
  • A newly promoted admin cannot read the supergroup's history (group-inbox.md D15), and cannot check the statements. Their group's admins have changed, so the ceremony would refuse anyway: the proposal is made again.
  • Every admin of every group must still join (confederation.md D11).
  • Signing still has a proposer per attempt. Part C's selection is fixed by whoever proposes the attempt, and any role holder may. That is not a coordinator in the sense this plan removes, and is left as it is.
  • Not for value. Upstream's warning stands.

Risks

risk what to do
upstream says D9's late seed does not meet §7.1 the fallback seed without contributions: unique, known in advance, chosen by nobody (Phase 0, check 1)
a 64-group statement does not fit one proposal lower the maximum N and say so on the picker (Phase 0, check 4)
an admin's device misses a wrap (the inbox's live subscription has no catch-up past its limit) the proposal screen names the group whose statement this device lacks; any admin of that group can Send again. The answer's signing session carries the invitation, so signing never depends on it
two devices make the confederation's room D11's order, delay and tie rule; Phase 0 check 6 first
a group's quorum equivocates caught at the first ceremony message, by group (D3, D8)
a dealer equivocates caught at the authorizations, by dealer (D8)
a group's inbox rotates mid-proposal its admins changed, so the ceremony refuses, as today; the old key still reads what was sent
the supergroup's wraps are dropped by a group's 10050 relays the group chose them; the inbox setup fills in relays that take gift wraps

Out of scope

  • Threshold ECDH members. A group with a 10050 and no 10044, reached through group-threshold-ecdh.md. It would read each statement once t of its admins have answered.
  • Running upstream's investigation locally, now that every device holds every dealer's vector.
  • Commit-then-reveal admin lists (appendix).
  • Moving the ceremony's messages into the supergroup (appendix).
  • Governance of the confederation's room, as in confederation.md.

Appendix: considered and not chosen

idea why not
the proposing group's FROST key signs every coordinator message a quorum asked per message, to sign values every device recomputes and checks anyway (The two questions)
keep a coordinator, but a member chosen by rule (the first admin of A, say) it keeps the single point of failure, only moves it. Nothing the coordinator does needs one device
keep the public 9430–9433 and send only the admin lists through the supergroup two transports for one statement, and the public half keeps the metadata leak. The charter is the public statement
public acceptances carrying a hash of the admin list, the list itself in the supergroup transferable evidence nobody needs: every group checks its own sealed copy, and the roster catches a split (D3)
a 9430 and a separate 9431 from the proposer, as today 2N seals, more than one batch above 32 groups (D4)
commit-then-reveal: accept with a hash, reveal the list once every group has accepted hides each list from a group that goes on to reject, at the price of a second signing session per group and a second wait on every quorum. Worth building if disclosure to rejecting groups matters in practice
the ceremony's messages in the supergroup: each admin writing as themselves to every group's inbox key one seal per group rather than per person, and only the groups' relays to know. But it puts high-volume, person-to-person traffic into the groups' inboxes, couples the ceremony to every inbox's rotation state, and the NIP-17 room it would replace already works. Revisit if delivery to personal DM relays proves unreliable
the session seed from the proposal alone unique, but fixed before anyone joins and so known to all in advance; D9 makes it unpredictable for the cost of 32 bytes in a message already sent

Order and size

phase rough size depends on
0 scratch tests, this document, a question upstream —
1 ~150 test 0
2 ~500 main, ~400 test, a manual migration 1
3 ~450 main, ~300 test 2
4 ~350 main, ~450 test 3
5 ~300 main, ~400 test 3
6 ~500 main, ~200 test 5
7 ~500 main (net, after removals), ~600 test 5
8 ~200 main, ~250 test 7, and Phase 0 check 6
9 docs and a device session all

Phases 4 and 5 can be built side by side once 3 is in; so can 6 and 7. Everything else is in order: the wire before anything sends it, sending before receiving, and the ceremony after every device can hold every statement, because its implicit opening is built from them.

Checking the work

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

No new kind is added: 9430–9433 become rumor kinds, 13, 14 and 1059 are the inbox's, and 30380 and 30383 stop being sent. None is in RetiredKinds. The new tags are spelled mantra/…, as every protocol tag is, and Bennu is named nowhere but in comments.