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>
59 KiB
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:
- The
ConfederationProposalEventis 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. - Each invited group answers in the supergroup, with a message its quorum signed.
- 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
COORDINATORfault. 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)andcoordinatorFinalize(keyState, authorizations, acknowledgments)take no randomness and no secret. Phase 11 of confederation.md already has every device runcoordinatorFinalizeitself, "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_refis 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:
- 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;
- 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; - checks the rumor: its kind, its
ptags exactly the other listed groups, its pubkey this room, itscreated_atwithin ten minutes of now; - for a 9430:
Nin2..64,Tin2..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 fromRoomAdmins.ofand the threshold its active share generation signs with; - 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;
- for a 9432: the same invitation check, and this group has not answered;
- for a 9433: this room wrote the proposal, and it is not yet
ACCEPTEDon 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
kin the order makes the room only if no welcome for it has arrivedkhours 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:
- The session seed (D9). Ask upstream whether a
session_seedfixed 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.mdsection 21). Until answered, build D9's fallback-ready: the seed function takes the contributions as an optional input. - The broadcast is deterministic. A jvmTest on
ConfederationReachableJvmTest's three groups:coordinatorStep1over the same dealings, in any input order, gives the same bytes; andparticipantStep2accepts a broadcast computed on the participant's own device. - The room id.
createNip17ChatRoomover the same people, called by two different users, gives the sameChatRoom.id, and the inbound path files a ceremony message into that room on a device that has not made it yet. - 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
Ncomes down and D5's picker says so. - 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.receiveon B's admins' devices, opened with the seal'sntag, 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. - 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
outcomereturns 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
coordinatoris 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, withv: 2content and nocoordinatortag.ConfederationProposalEvent.Proposallosescoordinatorand gains the proposing group'sConfederationAdminList.ConfederationAdminListatv: 2, strict, withproposalabsent on a 9430.ConfederationSupergroup: the recipient set (every listed group), and the supergroup's key (the proposal rumor id).ConfederationAttestation: D8'sattestation_refand ceremony id, D9's seed.ConfederationRitualEvents: dropOPENINGandBROADCAST; 30381 gainsseed,attestation_refand the rumor ids; 30384 gainsoperation_session_id; anattempttag on every ceremony message.- Delete
ConfederationSeal,ConfederationEphemeralKeyTag,ConfederationSealTagandConfederationCoordinatorTag.
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.buildintoInboxMessages.build(roomId, rumor, recipients, inboxSecret, generation), which takes a rumor instead of text.InboxRepliescalls it with its kind 14, so the reply path is byte-identical (its tests pin it). ConfederationManager.proposeConfederation,proposeAcceptance,proposeRejectionandproposeWithdrawalbuild the rumor (Phase 2), resolve every listed group toInboxReplies.Recipientthrough 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 throughGroupInboxPublication, asInboxReplies.wrapAndOwedoes, and files its own statement at once. Send again works on any admin's device that holds the session's manifest.ProposedEventsummarises a confederation seal batch fromconfederation_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_rumorpresent → 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.openhands a rumor of a confederation kind toConfederationManager.recordRumorwith 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.recordRumorchecks 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-confederationnarrows to charters (D12). Statements need no new subscription.ConfederationStatusreads 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; onceACCEPTED, 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:
openandacceptOpeningare replaced byplanFor(proposalId), the implicit opening, andjoin, which makes the room (D8) if it is not here and sends this person's 30381.eligibilitykeeps every check but the coordinator's: the statements verify, the state isACCEPTEDhere, the room is exactly the roster's people, and each of this device's groups still has the admins it accepted with.advancestep 1 sendsseedandattestation_ref; a mismatchingattestation_reffails out naming the group. Step 3 runscoordinatorStep1on this device and keeps the broadcast in the ceremony row; there is no 30383. Step 4's 30384 carries theoperation_session_id; a mismatch fails out naming the dealer whose dealings differ.describe'sCOORDINATORandROLE_OR_COORDINATORlines are reworded for a coordinator that is this device.- Attempts (D10).
ConfederationManager.outcomeloses 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.takeNextStepcreates the room on the device whose owner is first in the order, ork-th afterkhours 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:
- A proposes; A's quorum signs; B's and C's admins see the invitation, and nothing is on public relays but wraps.
- B and C accept; every admin's device in every group shows Join at once.
- Close the phone of the admin who proposed. The ceremony still forms, and the room is made.
- Abandon one attempt, try again, and form in the second.
- 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
tof 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.