Files
giza-kmp/docs
Kgothatso NgakoandClaude Opus 5 3cdce6a908 feat(marmot): send the canonical app payload, and an envelope for direct messages (v2 Phase 2)
What goes into MLS is now the Marmot app event the spec defines: six members and
no `sig`. The rumor serialised as an Event carried `"sig":""`, which a conformant
decoder refuses outright -- a payload with a signature would be a standalone relay
event, republishable as a signed statement by its author. The id does not move,
because NIP-01 never hashed the signature, so every row filed under an inner
event's id stays valid; and the build already in the field reads the new shape,
because Event.fromJsonOrNull defaults a missing signature. This switch alone needs
no gating and is made everywhere at once. The `encoding` tag comes off the
application kind:445 while here -- transports/nostr.md forbids it on every shape.
docs/marmot-v2.md, Phase 2.

A direct message could not make that switch as it was. Its payload is a NIP-59
wrap signed by a throwaway key, which a conformant peer refuses twice over: for
the sig member and for an author that is not the MLS sender. In a current-profile
room the wrap now travels inside an envelope -- an unsigned app event of kind
30330 authored by the sender, one `p` tag for the recipient, the wrap's JSON as
content. The envelope passes the author check like any payload, so the carve-out
in mip03Rejection that admitted bare wraps is confined to legacy rooms by a new
`legacyRoom` flag: in a current-profile room a bare kind:1059 is refused as every
other conformant client refuses it. Every property the throwaway key was chosen
for survives -- the envelope is unsigned and so a claim rather than a proof, the
wrap inside is still signed by nobody, and the seal-to-leaf binding in classify
still decides who wrote the words. The line for a message this device cannot read
now hangs off the row the payload was filed under (the envelope's id in a
current-profile room), which ChatMessage's foreign key requires.

The envelope is gated, and the gate is the room's profile: an old build renders
it as a raw-JSON bubble, so a legacy room keeps sending the bare wrap, and a
current-profile room -- which admits only leaves carrying an identity proof,
which only a build past Phase 3 can make -- never holds an old build. That is the
flag for every wire change after this one.

A conformant decoder bounds the whole app payload at 64 KiB, and a chronicle page
rides inside one as JSON-escaped content. The new bounds test caught what the
arithmetic missed: dense JSON payloads escape to half again their size, so a 48
KiB page became a 70 KiB app event. The packer now measures a page by
ChronicleEvent.escapedByteSize -- the bytes it will occupy inside the envelope --
against MAX_PAGE_BYTES, lowered from 64 to 48 KiB, and MAX_PAGE_EVENTS drops from
128 to 96 so the count cap still binds under it, as the comment on the two caps
insists. The receiver's raw-bytes check is unchanged and now holds by
construction.

Tests: MarmotMip03CarveOutTest becomes the test that the exemption is confined to
legacy rooms and that an envelope passes the ordinary check; MarmotDirectMessageTest
round-trips the envelope through the strict decoder and opens the wrap inside;
MarmotPayloadBoundsTest asserts the largest chronicle pages and an envelope are
conformant app events, including the dense-content page measured the way the
packer measures it. The ingest test's tamper case flips a decoded byte rather
than the base64 tail, which could change nothing but padding. Full JVM suite:
1,148 tests pass. The direct-message and chronicle notes record the changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-13 22:32:30 +02:00
..

curare 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.

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
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
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 is dropped for good, which flows trigger it, the quartz fix, and the partial mitigation in this app
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, and nine phases from reading both profiles to publishing before applying

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 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 not been built, 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 not 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.