The plan is marked built, with a table of the nine places the build chose differently -- the forwarder's own line written by share so the button writes it too, a notice carried on by any device that believes it whether or not it holds the room's key, one explanatory line under the fallback section rather than one per row, and the signet run still to make. The guardians and member-guarded-wallets notes say forwarding no longer waits on a tap, and the README that it has been built. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
21 KiB
Forwarding guarded wallets upward, without anybody pressing a button
A guarded wallet carries a leaf for every group above it, but a group above can use its leaf only once it has been told about the wallet. Today that telling is a button. A member who sits in both rooms opens the lower group's wallet screen, finds Tell the groups above, and taps Share for each wallet. One tap carries one wallet one generation up. Nobody is prompted to do it. A root whose grandchildren's wallets nobody shared has a leaf in every address and no way to find a single coin.
This plan makes the telling automatic. Whenever a device files a guarded wallet it believes -- a subgroup's own guarded statement, a member wallet certificate its group signed, or a notice forwarded to it from below -- and it sits in a group above that has not been told, it tells that group. The same check runs again each time a group's room or wallet screen is opened, which catches up on everything filed before this existed or missed while offline. The button stays, for the case a notice was lost on the wire.
Read group-wallet-guardians.md, How an ancestor
finds the coins, and member-guarded-wallets.md,
Phase 10, first. This plan changes no format: the notice is the 30333
GuardedWalletNoticeEvent it has always been, and everything an ancestor checks
before believing one is unchanged. What changes is who sends it, when, and to
which groups.
Built, phases 1-7, one commit each, written against the code as it stood at
263a25a7, schema v30; the build changes no schema and no format.
GuardianManager.believable, upwardOf, forward, forwardOnArrival and
forwardAll are the entry points, and GroupWalletRollout.FORWARDS_GUARDED_WALLETS
is the switch. The phases below are kept as written; where the build chose
differently the table says so.
| what the plan said | what it turned out to be |
|---|---|
| Phase 1's tests are in commonTest | jvmTest, GuardedWalletForwardingRulesJvmTest: believable is tested against certificates a real quorum signed, and FROST runs on the JVM |
Phase 2: forward writes the forwarder's own line |
share writes it, so the button writes it too -- the forwarder never seeing its own line was the button's gap as much as the automation's (Phase 5) |
Phase 3: the notice arm forwards after describeNotice believes it |
before, and whether or not it does. describeNotice needs this room's key to make the ancestor's walk; forwarding needs only believable, so a device in a middle group that holds no key state for it still carries a notice on up |
| Phase 3: a test with the switch off | not written: the switch is a const, and a test cannot turn it. Each trigger reads it in one line, forwardOnArrival and forwardAll |
| Phase 3's notice test arrives through the inbound path | through GuardianManager.forwardOnArrival, which the inbound path calls: the 30333 arm sits inside MLS decryption, which a jvmTest does not drive. The certificate and statement arms are driven through ChatMessage.applyInnerEvent itself |
Phase 4: ChatRepository.forwardGuardedWallets |
with a default body, so every fake repository in the tests needed no change |
| Phase 5: nothing else changes | two older tests described a notice under an id other than the one they filed. Under the one-line rule that is a second notice, and silent; they now describe the notice they filed |
| Phase 6: each row's supporting line explains the fallback | one line under the section's heading says it, and each row keeps Not yet shared with the groups above that you're in: the same sentence on every row was the same sentence N times |
| Phase 7: the three-device run | not made |
Still to do by hand: Phase 7's run on signet.
What is there, and the two things wrong with it
GuardianManager.shareableFrom(chatRoomId, chain) lists what a device could
tell from a room. That is the room's own guarded wallet, if it has one, plus
every guarded wallet the room holds: those it was told about, and those of its
members it signed itself. Each comes with the guarding rooms this device is in
and has not told yet (targetsFor). GuardianManager.share posts one notice
per room. GroupWalletViewModel.share is the only caller, behind the button.
Read as the basis for doing this without a person, two of its rules are wrong.
1. It tells groups below as well as above. targetsFor takes every room
the statement's guardian list names, except the room it is in. The list names
all the wallet's guardians, nearest first. So from a middle group M, the
targets of a grandchild C's statement include the root R, which is right,
and nothing below M. But from the root R, holding the same statement, the
targets include M, which already holds it. Each tap there tells a group
something it was told first. By hand that is a wasted tap. Automatically it is
a notice into M from every device in both rooms, every time R is opened.
2. A guarding group's own certificate never counts as told. alreadyTold
reads the target room's 30333 notice rows. A member wallet certificate is held
in the group that signed it as a GroupSignedEvent and never as a notice. So
R holding a member's wallet that G signed would tell G again, for the
same reason as above.
Both are fixed by one rule: a statement is told upward only, to the guardian rooms after the room it is in. A room that holds the statement in any form, signed or as a notice, has been told.
Phase 0 — decisions, before any code
D1. Which statements are forwarded
Recommended: exactly what shareableFrom lists today, from a room this
device is in:
| statement | held in the room as | forwarded to |
|---|---|---|
| the room's own guarded wallet statement (30331) | a GroupSignedEvent the room's quorum signed |
every guardian it names |
| a member wallet certificate (30334) the room signed | a GroupSignedEvent |
the guardians after the room, which is guardian 0 |
| a statement or certificate a notice carried here (30333) | a MarmotInnerEvent row |
the guardians after the room in the statement's list |
A plain (unguarded) wallet statement is never forwarded: it names nobody.
D2. What the forwarder believes first
The forwarder vouches for nothing. Every device in the target room runs
GuardianManager.verify on what arrives, including the walk down from its own
guardian root. But the forwarder should not pass on what it cannot believe
itself, or a single bad notice is copied into every group above.
Recommended: everything verify checks except the ancestor's own walk,
which only a device holding that ancestor's key can make:
- a 30331 statement: signed by its room, guarded, carrying a certificate whose
key makes that room, and with every value rederiving from it
(
Reading.verifiedAgainst); - a 30334 certificate:
MemberWalletCertificateEvent.verify(certificate, certificate.pubKey).
This is GuardianManager.believable(statement), split out of verify so the
two cannot drift. verify becomes believable plus the walk.
D3. Which groups count as "above"
Decided by the bug above: upward only. In room X, a statement's targets are
the guardians listed after X's own position in its guardian list, nearest
first. A room not in the list at all is the wallet's own room (a subgroup's own
statement), and gets every guardian. For a member's wallet signed by G, G is
guardian 0, so the targets start at G's parent.
A target counts as told when it holds the statement in any form: a 30333 row
carrying it, or a GroupSignedEvent with its id.
D4. Who sends it, when several devices could
Every device in both the lower group and the upper one could send the notice.
When a member wallet certificate completes, every device in G files it within
seconds of the others. Each of them that is also in P would then post into P
at once. A burst like that is the shape mls-skipped-keys.md
warns of: one of two group events arriving back to back can be dropped for good.
Recommended: one sender is elected for the immediate send, and every device is a fallback for the catch-up.
- The elected device is the one whose profile's key sorts lowest among the members of both rooms, as this device's participant lists have them. It forwards on arrival.
- Every other device forwards only in the catch-up pass (D5). By then the elected device's notice has usually arrived, and the target counts as told.
- Devices disagreeing about the participant lists can elect two senders. The cost is one duplicate notice, which D6 keeps out of the transcript.
The alternative, everybody sending at once, is simpler and correct, since
guardedWalletsOf already collapses duplicates. It is rejected for the burst,
not for the duplicates.
D5. When the catch-up runs
Recommended: when a Marmot room's chat is opened, and when a group's wallet
screen is opened, for that room. That is ChatMessageListViewModel.initiate,
beside askForGroupHistory, and GroupWalletViewModel.initiate, which already
reads shareableGuardedWallets.
That covers:
- certificates and statements signed before this ships;
- a device that was offline when the elected one should have sent;
- an elected device that never sent.
A pass over every room at launch would cover more, and would put a notice burst on every room at once, on every launch. It is rejected for now and named under what this does not do.
D6. What the transcript says
Today each notice writes a Shared @alice's guarded wallet with this group line, attributed to the member who forwarded it. The forwarder never sees its own line: a sender is not handed its own MLS message back.
Recommended:
- a line only for the first notice of a statement in a room. A notice whose statement this room already holds, in any form, writes none;
- the forwarding device writes the same line into the target room on its own side as it sends, so it sees what it did, as the button's snackbar did.
D7. Which profile sends
One database holds every profile on the device. A room row's userPublicKey is
the profile that is in it.
Recommended: the notice is sent as the target room's own profile, and only when
that is the source room's profile too. The arrival path that files a 30334 or
a 30331 (ChatMessage.applyInnerEvent) has no active key to hand. The room row
has it, and a device must never post into a room as a profile that is not the
one in it.
D8. A way to turn it off
Recommended: GroupWalletRollout.FORWARDS_GUARDED_WALLETS = true, read by the
arrival triggers and the catch-up, not by the button. It is a behaviour that
sends messages without a person, so it gets one switch, in the same place as the
other wallet gates, for the release where it first ships.
Phase 1 — the rules, pure
New in GuardianManager (or a small GuardianForwarding beside it, if it reads
better):
/** [statement] believed on its own merits: everything [verify] checks except the ancestor's own walk. D2. */
fun believable(statement: Event): Believable? // the guardians, the descendant id, the chain
/** The guardian rooms [statement] is forwarded to from [chatRoomId]: those after it in the list, nearest first. D3. */
fun upwardOf(guardians: List<GuardianDerivation.Guardian>, chatRoomId: String): List<String>
/** Who sends at once, of [candidates] -- the members of both rooms: the lowest key. D4. */
fun electedSender(candidates: Set<HexKey>): HexKey?
verify is rewritten as believable(statement) plus the walk, with its kdoc's
four rules unchanged.
Tests, commonTest:
upwardOffor a grandchild's statement: from the grandchild's own room, both guardians; from the middle group, the root alone; from the root, nothing;upwardOffor a member wallet from its guarding group, two levels up: the parent and the root;believableaccepts whatverifyaccepts and refuses each mutationverify's tests refuse, apart from the walk;electedSenderis the lowest key and is null for an empty set.
Phase 2 — telling, as a function a trigger can call
/**
* Tells every group above [chatRoomId] that this device's profile is in, and that has
* not been told, about [statement]. [whenElected] restricts it to the targets this
* device is the elected sender for (D4); the catch-up passes false.
* Returns the rooms told.
*/
suspend fun forward(database: BennuDatabase, statement: Event, chatRoomId: String, whenElected: Boolean): List<LocalChatRoom>
believable(statement), or nothing;- targets:
upwardOf(guardians, chatRoomId)→ rooms on this device that are Marmot rooms, belong to the source room's profile (D7), and have not been told in either form (D3); - with
whenElected, keep a target only if this profile iselectedSender(participants(source) ∩ participants(target)); shareinto each, as that profile, and write the forwarder's own line (D6).
shareableFrom and targetsFor move onto the same upward rule and the same
told check, so the button and the automation cannot disagree about what is
left to share. That fixes both bugs above for the button too.
Tests, jvmTest, in the shape of MemberWalletGuardianJvmTest:
- a member wallet certificate in
G, this device inGandP:forwardtellsPand notG; - the same from
Pholding the forwarded certificate: tellsR, notG; - a target holding the statement as a
GroupSignedEventcounts as told; - a target belonging to another profile on the device is never told;
whenElectedwith a lower-keyed member in both rooms tells nobody, and without it tellsP;- a statement that is not
believableis forwarded nowhere.
Phase 3 — the triggers on arrival
Three places, each after the statement has been believed and filed, so the row the told check reads already exists:
| arrival | where | forwards |
|---|---|---|
a member wallet certificate is filed in G |
ChatMessage.applyInnerEvent's 30334 arm, reached from FrostSigningManager.applySignedEvent on every device that followed the session |
the certificate, from G, whenElected = true |
| a guarded wallet statement is filed in a subgroup | the 30331 arm, when wallet.account.isGuarded |
the statement, from the subgroup's room |
| a notice arrives in a group | the 30333 intercept in ChatMessage's inbound path, after describeNotice believes it |
the statement inside, from this group, onward |
Each call is wrapped so a failure to forward is logged and never stops the line being written. Forwarding is an extra, and the arrival is the thing.
All three read GroupWalletRollout.FORWARDS_GUARDED_WALLETS (D8).
Tests, jvmTest: a three-level hierarchy on one device -- root R, middle
M, grandchild C, this device a member of all three and the elected sender
throughout:
C's guarded statement filed inCends with notices inMand inR, with nobody callingshare;- a member wallet certificate filed in
CreachesMandRthe same way; - the notice
Mreceives does not travel back down intoC; - with the switch off, nothing is sent.
Phase 4 — the catch-up
GuardianManager.forwardAll(database, chatRoomId): every statement
shareableFrom would list from the room, on every chain, through forward with
whenElected = false. Called from:
ChatMessageListViewModel.initiate, besideaskForGroupHistory, for a Marmot room;GroupWalletViewModel.initiate, beforeshareableGuardedWalletsis read, so the Tell the groups above section shows only what is truly left.
Both go through ChatRepository.forwardGuardedWallets(chatRoomId), so the view
models still talk to repositories.
Tests: a certificate signed before this existed -- filed with no trigger -- is forwarded the first time its group's room is opened, and not again the second time. A non-elected device forwards in the catch-up what the elected one never sent.
Phase 5 — the transcript
- The 30333 intercept writes its line only when no other stored notice in the
room carries the same statement id, and the room does not hold the statement as
a
GroupSignedEvent. A duplicate is filed and silent. forwardwrites the forwarder's own line into each room it tells, typedTYPE_GUARDED_WALLET_SHARED,isUserMessage = true, with the words the receivers' devices write.
Tests: two notices for one statement from two forwarders give one line; the forwarder's own device shows its line in the room it told.
Phase 6 — the screen
The Tell the groups above section on GroupWalletScreen stays, now as the
fallback, and lists only what the catch-up could not send. In practice that
means a notice lost on the wire, or a group above in which this device holds no
row. Its supporting line becomes This device shares these on its own when it
can. Share now if a group above has not heard. The strings go in
strings.xml, in sentence case.
The snackbar the button shows today stays as it is.
Phase 7 — docs, and checking it on the emulators
- group-wallet-guardians.md, How an ancestor finds the coins: forwarding is automatic, one generation per device in both rooms, with the button as a fallback.
- member-guarded-wallets.md, Phase 10: a member's wallet reaches the groups above without anybody sharing it.
- README.md: this note's row.
- This note: Built, and a table of where the build chose differently.
By hand, signet, three devices. R is the root, M its guarded subgroup, G
M's guarded subgroup, and Alice is in G. Device 1 is in G and M, device
2 in M and R.
- Alice asks
Gto guard a wallet, andGsigns. With nobody touching device 1,M's wallet screen lists@alicewithin a minute. - With nobody touching device 2,
R's does too, andR's transcript has one Shared @alice's guarded wallet line. G's transcript has no line about its own member's wallet coming back down.- Device 2 offline while
Gsigns a second wallet: it appears inRthe first time device 2 opensM. Rmakes a guardian spend from Alice's wallet through its leaf.
./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
./gradlew :composeApp:m3Audit
Order and size
| phase | touches | ships |
|---|---|---|
| 1 | GuardianManager, pure |
dark |
| 2 | forward, and the button's rules |
fixes both bugs in the button |
| 3 | three arrival arms | the switch: nothing sends without a person before this |
| 4 | two view models, ChatRepository |
with 3 |
| 5 | the 30333 intercept, forward's own line |
with 3 |
| 6 | GroupWalletScreen |
any time after 4 |
| 7 | docs and the run | last |
Phase 2 is worth landing alone. It is a fix to the button that stands without the automation.
What this does not do
It does not reach a group nobody sits in. Forwarding needs a device in both rooms, one generation at a time. A group above that shares no member with the group below still cannot be told, and the remedy is the one the guardians note gives: a member in common.
It does not tell a member welcomed into a group above after the notice.
Notices are not chroniclable, so a device that joins R later holds none of the
notices R was sent, and lists none of the wallets. The catch-up does not help
it: the forwarder's device already holds its own copy of the notice and counts
R as told. Telling late joiners is the chronicle's job, and this plan does not
take it on.
It does not sweep every room at launch. The catch-up runs per room as the room or its wallet screen is opened (D5). A device that never opens the lower group never forwards in the catch-up, though it still forwards on arrival when it is the elected sender.
It does not make a notice reliable on the wire. A notice lost to the skipped-keys bug stays lost until a catch-up on another device sends one again, or somebody taps Share.
It does not change what a group above can do with what it is told. It finds the wallet, watches it and can spend through its leaf after the delay. All of that is unchanged; only the finding no longer waits on a tap.
Appendix — what was considered and rejected
| idea | why not |
|---|---|
| every device sends at once | correct, since duplicates collapse, but it puts a burst of group events into every group above at the moment a certificate completes, the one shape mls-skipped-keys.md says loses messages (D4) |
| the member's own device forwards their wallet | the member is in G and seldom in the groups above, and a subgroup's statement has no single owner; the device in both rooms is the one that can |
| a pass over every room at launch | catches the most, and sends the most at once, on every launch (D5) |
| removing the button | a notice lost on the wire has no other way back until somebody opens the right room on the right device |
| a new kind for an automatic notice | the 30333 notice already says everything, and every build that reads it today reads these |