19 KiB
Giza docs
Notes on the parts of this app whose behaviour is not recoverable by reading the code alone — where the reasoning lives in a protocol, a failure mode that is silent, or a decision that looked arbitrary and was not.
Most of them were written while the app was Bennu, before the fork, and they say so where it
matters: a decision taken in Bennu was taken in Bennu. Source paths in them point at
mobi/giza. Strings spelled bennu/… in their formulas were derivation tags the fork kept on
purpose (giza-rebrand.md); every one was a wallet's, and they appear only in
the retired notes now.
| document | covers |
|---|---|
| shared-key-ceremony.md | ChillDKG over NIP-17: the rounds, the approval gates, the chat transcript, participant ordering |
| shared-key-derivation.md | deriving further keys from the group's threshold key with FROST tweaks — why not BIP32, why no chain code, and the one rule that must not be broken |
| subgroups.md | a group making another group — the four ceremonies, what the parent's signature actually covers, and why the child's key is fresh rather than derived |
| automatic-key-ceremony.md | joining is the only approval: a phased plan, built but for its device session, that makes a key ceremony run by itself after a member joins. Covers why contributing and confirming were never decisions a person could add to, the resume sweep that replaces the tap, the coordinator's follow-up steps and the one key state a device can sign without asking, and why abandon stays |
| ceremony-creation.md | one place to start a key ceremony — how joining a subgroup's ceremony opened a second one for the parent room, the screen that showed a ceremony and offered to start one in the same button, and the removal of the nip30303 documents, whose kinds collided with the ceremony's, leaving the member chronicle with nothing to carry and nothing to say |
| frost-batch-signing.md | signing several events in one ceremony — why one nonce can never cover two messages, and the phased schema, wire and UI work that follows from it |
| frost-session-resend.md | asking the members who never got a signing proposal to look again — why a proposer can repeat only what it wrote, why a member's availability signal needs no repeating, and the one half that has to come from the silent member's own device |
| frost-share-refresh.md | giving every member a new share of the same group key, phased and built behind a flag that is off in release — why enrollment cannot rotate a share, the zero-sum refresh that can, what a rotation protects against and the two things it never can, and re-enrollment as the repair that brings back the members a refresh left out |
| rotate-shares-single-approval.md | taking part is the only approval: a phased plan, built but for its device session, that makes a share rotation run by itself after a member agrees to take part. Covers the three asks a recipient gets today, why storing the new share was never a decision, the one key state for a new generation a device can sign without asking, and the abandon a member loses once nothing is left to approve |
| marmot-membership.md | how members join an MLS group, and the epoch race that makes a missing member look like a successful invite |
| member-chronicle.md | handing a member added after the work was done the group's signed record — why the events are not on the wire at all, and why the room's id is enough to verify them |
| marmot-direct-messages.md | a one-to-one message inside a group as a stock NIP-59 gift wrap — what its MIP-03 carve-out costs, why the sender cannot read their own, and the one query that would broadcast it |
| mls-skipped-keys.md | why a group event that arrives a moment late was dropped for good, which flows triggered it, the fix as it landed in mls-kmp, and the one word of the diagnosis that was wrong |
| long-running-sync.md | the chat subscriptions that stay open instead of pulling once per screen — why the request queue could not simply hold one, and how the group filter follows the room list |
| dead-code.md | code in the sync and relay stack that nothing calls, why each piece is still there, and which of it is a bug rather than a leftover |
| nsec-sign-in.md | signing in with an existing nostr key — why an nsec can never have a wallet behind it, the ten call sites that make it small, and the sign-in machine that was already built and unreachable |
| npub-sign-in.md | signing in with only a public key — what a key that cannot sign can still see here, why that is a preview rather than a browser, and the four decisions the word settles |
| multiple-profiles.md | several profiles on one device — why a profile is a credential and a seed is a wallet attached to one, why a switch is a restart rather than a swap, the two entrances the app lacks, and the inbox a switch would silently lose |
| jvm-target.md | what desktop support cost, phased — why the native chain was already done, why an empty source set in our phoenix fork was the real blocker, and why DAO tests need none of it |
| npub-profile-preview.md | showing the person before a direct message is started from a pasted npub — why the preview is a screen keyed by public key, what "found" means when a row can be a placeholder, and the phase that makes the button honest about a key package that never comes |
| material-design-conformance.md | what the M3 foundations actually require, measured against all 43 screens — the colour pairing that renders the app's own proposals invisible, and eight phases that put the decisions back in the theme |
| marmot-v2.md | bringing the group layer onto the Marmot current profile after the quartz 1.15.2 bump — the nine rules that reach this app, why the room's id and the routing id have to become two values, nine phases from reading both profiles to publishing before applying, the rollout that put new rooms on the current profile and retired the legacy KeyPackage slot, and the one fork the library cannot yet settle |
| marmot-kmp.md | moving the group layer off quartz's engine and onto marmot-kmp, mls-kmp and crypto-kmp — why staying on quartz 1.15.2 is staying on an engine that left, the 228 import lines and the one rule that places all but two of them, the group state on a device that must still open afterwards, nine phases that put the swap in one commit and the evidence around it, how often this app persists a group once a sent message no longer rewrites it, and the schema change that followed, opened from the version the app ships |
| quartz-mls-marmot-update.md | moving quartz, mls-kmp, marmot-kmp and crypto-kmp to their newest releases, phased and built but for a mac and mls-kmp 1.4.0's release — why almost nothing the app calls has changed while the way the build reaches them has (Nostr + Blossom through Magpie, none of it on Maven Central), the go/no-go that is the owner's, marmot's own pins first and the newest second, and the lock that has to be written on a mac before it can be frozen |
| dependency-update.md | moving everything else in the catalogue to its newest stable release, phased and built but for a mac, devices and pushing the submodule branches — why the libraries go first and need no newer Kotlin, why AGP and Kotlin can only move down the whole submodule chain at once, the material3 alpha that was built for an older Compose than the app's, and what has to keep opening on a device afterwards |
| giza-wallet-removal.md | taking every wallet out of Giza, phased and built but for moving off the wallet library (7b). Covers why a Giza member declines a Bennu peer's wallet proposal instead of ignoring or signing it, why the wallet's kinds are retired rather than freed, why a recovery phrase stays as a key backup that has to derive the same npub and id byte for byte, and why the threshold crypto keeps the build tied to the wallet library until the last phase |
| giza-app-icon.md | the sphinx icon on iOS, desktop and in the app, phased and built but for the checks on a mac, a phone and Windows — one master SVG and one generator for every raster, why the iOS light icon must carry no alpha channel, why its dark icon is transparent and its tinted one grayscale, the desktop installers and window that show Java's icon today, and why the mark's cutouts need no fill rule |
| member-admin-promotion.md | making a member an admin and back, phased and built, promotion with a share and demotion with a refresh under the experimental enrollment, under three rules: every admin holds a share, every commit in a keyed room is a proposal until the group's threshold signature is on it, and a robust group keeps at least three admins. Covers why the commit rides inside the group's signature and the rule inside the group's state, which lets every device refuse an unsigned commit with the libraries as they are, why a member's own leave stays exempt, and why a removed admin comes back as an admin when re-invited today |
| admin-change-rotation.md | an admin change carries its rotation with it: a phased plan, built but for its device session, in which the rotation that follows removing an admin, and the one before a first promotion, asks nobody, because the group's signature on the change already decided who is withheld, and in which admin changes and rotations take turns. Covers the five ways the two overlap today, a removed admin who keeps a live share among them, and the one check a device makes to take part unasked |
| member-row-actions.md | every member row but your own offers every action that applies to that member, and an action you can't take now opens a screen saying what stands in the way and what would change it — phased and built. Covers the twelve reasons an action is refused today, why an unavailable item is marked rather than disabled, and why the explanation screen recomputes its reason instead of carrying it |
| giza-rebrand.md | forking Bennu as Giza under mobi.giza — what carries the name, what must not be renamed and why, why the desktop data directory changes first, and how the fork keeps merging from Bennu |
| robust-group-admins.md | making every founding member of a robust group an admin of its room, on every device -- phased and built. Covers why the ceremony's participants are the founding set, the Welcome that flags no admins, the joiner's check against the ceremony it took part in (since removed), and finishing an invite that partly failed |
| remove-convenient-groups.md | every group a member makes is robust -- phased and built. Covers why a one-to-one chat is not a group yet takes no new members, why the three-member floor moves to the member picker rather than down to 2-of-2, the quorum rules that outlive ChatRoomType, and why a Bennu peer's convenient group is still joined |
| remove-founding-admins-card.md | taking out the "Founding members aren't admins" card, its repair and the Welcome line behind it -- phased and built. Covers why a founder missing from the policy stopped meaning a fault once admins could be demoted, why the check cannot be taught the difference, and why the retired caption type stays |
Start with the ceremony if you are new to this area; the Marmot notes all assume it.
Read the skipped-keys note before debugging any "the other device never got it"
report — it is silent, and it looks like every other kind of delivery failure. The
resend note is the recovery for it on a signing session, and says which delivery
failures a resend repairs and which heal on their own. The
sync note stands alone, and the dead-code inventory reads as a follow-up to it. The
batch-signing note is a phased plan that has been built: read it after the
derivation note, whose one rule is the same one it is built around. The member
chronicle note is a phased plan that has been built and now carries nothing --
the document kinds it was for are gone -- and reads as the membership note's
unanswered half: what a member who joins late can be given, and the one thing
they cannot. The
jvm-target note is unrelated to all of them: it is a build and packaging story.
The subgroups note is a phased plan that has been built; it assumes both
shared-key notes and reads as the ceremony's second half — what a group does
once it has a key, and what it can say about a group that does not yet.
The Material Design note is a phased plan that has not been built, and is the
only one about what the app looks like rather than what it does; read the
jvm-target note first if you want to know why its adaptive-layout phase exists.
The nsec sign-in note is a phased plan that has been built; it inherits the
key-storage decision from the jvm-target note and drives the navigation state
machine NavigationViewModel.processLocalAccount implements, so read it with the
code open, and read its table of where the build chose differently first.
The npub sign-in note is a phased plan that has been built, and reads as that
plan's out-of-scope note answered: it takes the Identity type and the sign-in
machine as given and asks what an identity with no secret is for, before it asks
how to build one; read its table of where the build chose differently first.
The multiple-profiles note is a phased plan that has been built, and reads as the
third of the sign-in notes: it asks what happens when the device holds two
identities, and its first phase changes one rule the other two share — a seed's
key becomes a credential like any other — so read it with StoredIdentity.merge,
SovereignWalletViewModel.switchToIdentity and the startup screen open, and read
its table of where the build chose differently first.
The npub profile preview note is a phased plan that has been built, and is the
smallest of the plans: it changes the entrance to the direct-message flow and
nothing past it, so read it with StartDirectMessageToNpubOrNip05Dialog and
ChatRoomMessagingViewModel.initiateNewChat open, its four decisions before its
four phases, and its table of where the build chose differently first.
The Marmot v2 note is a phased plan that has been built, and is the largest of
them: it assumes the membership and derivation notes, takes the quartz 1.15.2 bump
as its Phase 0, and is ordered so that the phases that reach other clients come
before the ones that make the app's forks settle the way theirs do; read its table
of nine rules and its two constraints before any phase, and its table of where the
build chose differently before any of the code -- its first row, that a room's
profile picks its pipeline, is the shape of everything that follows, and its last
is the one fork the library cannot yet settle.
The marmot-kmp note is a phased plan that has been built, phases 0 to 9, and reads
as the Marmot v2 note's Phase 0 come round again: quartz took the engine out, so
the version the v2 work was built on is the last one that has it. Read the v2 note
first — this plan happens entirely on the current-profile side of its first row —
and read this one's two constraints before any phase: the group state already on
devices is what decides whether the move can ship at all, and Phase 4 is where it
is measured rather than argued. Phases 8 and 9 were not in the plan as written and
are the pair to read if you are changing when a group is saved or what the database
holds: 8 is where a sent message stopped rewriting the whole state, where the
ordering that decision hangs on is spelled out, and where the skipped-keys note's
diagnosis is corrected; 9 is the schema change 8 made necessary, opened from a
database at the version the app ships. What they do not claim is in the status note:
no manual upgrade of a profile with rooms that have real histories has been done, and
that is still the last check before a release.
The quartz-mls-marmot-update note is that plan's D2 come due, and is built but for a
mac and a release. Phases 0 to 5a and the Linux half of 6 and 7 are done. mls-kmp 1.4.0
(5b) waits for a release, Phase 6's iOS lock lines and the freeze wait for a mac, and
Phase 8 is the manual checks. Read it after the marmot-kmp note. Its headline is that the
code barely moved and the distribution did: the libraries are on Nostr + Blossom through
Magpie, and gradle/magpie.lock is now as much a part of the build as the catalogue.
Read its "What Magpie is" before touching either. Its Phase 3 has the one correction worth
knowing before reading a library's commit log as its release: mls-kmp drafted an epoch-0
repair and removed it before 1.3.1 shipped.
The ceremony-creation note is a phased plan that has been built. It reads as
the subgroups note's Phase 10 followed through to the screens: read it after
that phase, and its table of findings before any phase. Its second half
removes the nip30303 documents and leaves the member chronicle built but
carrying no kinds, so read it before building on the chronicle note.
The member-admin-promotion note is a phased plan built but for a keyed room's admin leaving; its share work (Phases 8 and 9) is behind the experimental enrollment. It reads as the Marmot v2 note's Phase 7 finished, and as the share-refresh note put to work: a promotion is an enrollment and a demotion is a refresh. Read its three rules and its headline before any phase. Its headline is the one idea the keyed-room half stands on -- the commit travels inside the group's signature -- and its ship order says which half can go out before enrollment leaves experimental.
The wallet-removal note is a phased plan that has been built but for its Phase 7b. It is how Giza came to keep no wallet: read its constraints and its decisions before any phase, and its table of where the build chose differently before the code. It reads as the rebrand note's D1 and D2 tested: one network shared with Bennu, whose members still bring wallets into rooms Giza is in.
Retired
retired/ holds the notes on Bennu's wallets -- the group's on-chain wallet, its guardians and the subgroup wallet policy, members' guarded wallets, the standalone Electrum client and the group Lightning wallet with its remediation plans. Giza removed all of them (giza-wallet-removal.md). They are kept because they are the only account of what a Bennu member in a shared group is doing, and of the kinds Giza now declines.