The audit and the JVM suite ran after every phase. The two-device regtest walkthrough has not been done; the note lists each of its steps beside the automated test that comes closest and what that test cannot show. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
23 KiB
Sending an amount from the group's wallet
Send from the group's wallet today sends everything the group has confirmed, to one address, less the fee. This note plans the other half: a member types an amount in sats, the rest comes back to the group as change, and the other members can see that the change is the group's before they sign.
Read group-chain-wallet.md first, Phases 8 and 10 in
particular. This plan is that note's third rollout gate, and it starts from the
code as it stands at 96055da5.
Built, Phases 1-6, except Phase 6's by-hand walkthrough on regtest; Phase 7
is the first release. Written against GroupSendScreen, GroupSendViewModel,
GroupSpendBuilder, GroupSpend and GroupWalletRollout as they were at that
commit, and each phase says where the build chose differently. Phase 3 was
committed before Phase 2, as Phase 2 asks.
What is already there
Most of this feature has been built and switched off. The plan is mostly about why it is off and what has to be true before it can be switched on, not about a new screen.
| piece | where | state |
|---|---|---|
| an amount, largest coin first, change to the next unused change address, dust change goes to the fee | GroupSpendBuilder.send |
built, tested in GroupSpendBuilderTest |
| change counts as change only if its claimed derivation reproduces its script | GroupSpend.check, check 5 |
built, runs on every member's device before signing |
| the approval screen shows every output, with change labelled as change | FrostSigningScreen.WhatIsBeingSpent |
built |
| Send everything switch, Amount in sats field | GroupSendScreen, GroupSendViewModel.amountField / sendEverything |
built, behind the gate |
| the gate | GroupWalletRollout.SEND_AN_AMOUNT = false |
closed |
| the preview says how much change comes back | SendPreview |
built |
The gate's own kdoc gives the lift condition: "send-an-amount has had a release
with nobody reporting a mislabelled change output." While the gate is a single
const that is false on every network, nobody can send an amount, so nobody can
report anything. The condition cannot be met as the gate is written. Phase 0
settles it by opening the gate on every network at once, and Phase 2 removes it.
Reading the gated code turned up five things to fix before the field is shown to anyone:
- A decimal is silently multiplied.
preview()reads the amount withfilter { it.isDigit() }. Someone who types21000.5gets 210,005 sats, and someone who types a bitcoin amount,0.0005, gets 5 sats. The first is a tenfold overpayment that the preview shows only as a number. - An amount too long for a
Longdisappears.toLongOrNull()returns null,preview()returns null, and the button stays disabled with no reason given. - Two open spends with change pick the same change address.
nextChangeIndexis the first change address Electrum has not seen used, and a proposal waiting for signatures has not used it yet. Both proposals pay change to…/1/0. Nothing is lost, but the address is reused, and change is exactly the output whose job is to not be linked to anything. - "Nothing to spend" is shown when the change branch has not loaded.
sendreturnsNothingToSpendwhennextChangeIndexis null. That happens before Electrum has answered for the change branch, while the group may hold plenty. - Dust change becomes fee without a word. Phase 8 of the wallet note said "the remainder goes to fee, and the screen says so". The builder does it and the screen does not: the preview shows a fee a few hundred sats higher than the fee rate implies, and no reason.
Phase 0: three decisions, before any code
Half a day. They change what Phases 2 and 4 build, so they come first.
- Where the gate opens first. Decided: on every network at once, relying
on the mainnet cap.
MAINNET_CAPalready holds any one spend proposed from this device to 100,000 sats, and that limit does not depend on the gate, so the most a mislabelled change output can put at risk on mainnet is one capped spend. Three things stand where the gate stood. The cap bounds the amount. Check 5 runs on every signer's device. And Phase 3's end-to-end test is the lab version of the report the gate was waiting for. The other option was test networks first and mainnet after a release, the waycapFortreats networks. It was turned down because it delays mainnet by a release and buys less than it looks, since the cap already makes the first mainnet spends small. - Whole sats only. No bitcoin unit, no fiat, no decimal point.
Sats.ktalready gives the reason for the wallet: comparing two integers is easier than reading a decimal point eight places in. An input that contains a decimal separator is refused with a message, never rounded or stripped. - "Send everything" stays a switch, not a Max button. A Max button
would fill the amount with
total − fee. That value changes when the fee rate changes, and it gives the group change it does not want when a coin confirms between typing and pressing. The switch buildssendAll, which has no change at all. That is the one difference between the two paths, and it should stay visible in the form.
Phase 1: the amount is sats, or says why not
One day. Built.
A parser and an output transformation in text/Sats.kt, next to grouped(),
so that reading and writing an amount are in one file:
sealed interface SatsInput {
data object Empty : SatsInput
data class Sats(val amount: Satoshi) : SatsInput
data object NotWhole : SatsInput // a decimal separator
data object TooLarge : SatsInput // more than 21,000,000 bitcoin
data object Unreadable : SatsInput // letters, or grouping that groups nothing
}
fun parseSats(text: CharSequence): SatsInput
val GroupedSats: OutputTransformation
- Grouping separators are allowed and dropped:
,, space, no-break space, narrow no-break space,',_. People paste40,000and40 000, and the second is how a South African locale groups thousands. .is refused, and so is,followed by one or two final digits (40,5,40,50), because in that locale those are decimals.40,000is grouping.- Grouping has to group. The first group has one to three digits and every
later group exactly three, or the input is
Unreadable:40,0000,4 0,1234,567. Guessing is how the bug above got in, and a reason that is not about decimals deserved its own case rather than being filed underNotWhole. - ASCII digits only. Kotlin's
isDigitaccepts the digits of every script, and so does the JVM'stoLong. - At most
MAX_SATS, 2,100,000,000,000,000. Significant digits are counted beforetoLong(), so a forty-digit paste isTooLarge, not an overflow.
On the field, display only. The plan said an inputTransformation would
store only digits. Built that way, a pasted 40,5 would have its comma
stripped and become 405, which is the same bug moved to the keyboard. So the
field holds exactly what was typed, parseSats is the only thing that reads
it, and GroupedSats, an outputTransformation, shows the text grouped as
grouped() writes it, but only when the text is plain digits. Anything else
is shown as it was typed, because regrouping 40,5 would show a number it is
not.
GroupSendViewModel.amount() is parseSats(amountField.text), and preview()
returns GroupSpendBuilder.Result.InvalidAmount(input) for anything that is
neither Sats nor Empty. It does this before it checks for an address or a
fee rate, because a wrong amount is not an incomplete form. Until Phase 4
moves amount errors onto the field, SendPreview shows the three reasons in
the preview line.
Tests: commonTest/…/text/SatsTest.kt covers every separator, the decimal
cases, the unreadable ones, empty versus zero, MAX_SATS and its overflow,
and what GroupedSats shows. In GroupSendViewModelJvmTest, typing
21000.5 reads as NotWhole and never builds a spend of 210,005.
Phase 2: the gate comes out
Half a day. Built. Phase 0 opened the gate on every network, so what is left is
removing it, not turning it into a per-network switch. A const that is
always true is a branch the compiler keeps and a reader still has to follow.
GroupWalletRollout.SEND_AN_AMOUNTis deleted, and its kdoc goes with it.ENABLEDandMAINNET_CAPstay. The object's own kdoc keeps its rule, that a gate decides what this device offers, never what a quorum may decide, and now names two gates.- Its three reads go. In
GroupSendScreen, the Send everything row is always drawn and the amount field depends only on the switch. InGroupSendViewModel.preview(), the condition becomessendEverything.valuealone. - The send-all sentence goes.
for_now_a_spend_sends_everythinghas no reader once theelsebranch is gone. Remove it fromstrings.xml, so the catalogue holds no text that the app never shows. GroupSendViewModelJvmTeststops branching.the preview waits for the form, and what it builds is what is proposedasserts the amount-with-change case outright: 40,000 sats sent, change not null, andGroupSpend.checkaccepting the proposed PSBT. A test whose assertions depended on a constant was testing whichever branch was compiled in.- The mainnet cap is now what stands between a member and a large mistake
sent as an amount. Add a view model test on
Chain.Mainnetwhere an amount over 100,000 sats previews asOverCap.GroupSpendBuilderTestalready covers the cap for send-all. This test covers it for an amount, which is the path the cap now protects. - Order the commit after Phase 3. With the gate gone, two spends with change from one group can be open at once, so change-address reservation needs to be in the same release. Phases 1 and 3 can land behind the closed gate in any order. This phase is the one that makes them reachable.
The wallet note's Phase 10 table has lost its send-all only row, and its "built" table says the gate was removed and why. That was done in this phase rather than Phase 6, so the note never describes a gate the code no longer has.
Phase 3: change goes to an address the group can find
One and a half days. Built. This fixes problems 3 and 4 above, and the silent dust in 5. It is the only phase that changes what the builder chooses.
- Change indices are reserved like coins.
FrostSigningManager.reservedChangeIndices(database, chatRoomId, account)sits next toreservedOutPoints, and both read one privateopenSpends: the PSBT of everyGroupTransactionwhose session has notFAILED. The indices come fromGroupSpend.claimedChangeIndices, which reads each output's claimed path under the account's fingerprint. It reads claims, not checked derivations, because holding an index too many costs nothing. The account is a parameter because the plan's(database, chatRoomId)signature could not tell one account's change from another's. The value is exposed onFrostSigningRepositoryand carried onGroupSendUIState.ReadyasreservedChange. GroupWalletState.nextChangeIndex(reserved)is now a function. It returns the lowest change index the wallet watches that is unused and not reserved. The oldnextChangeIndexproperty was the first unused index, andchangeKnownseparates "no answer yet" from "all held".- The window, checked. The plan read
CHANGE_LOOKAHEADas "watched past the first unused address".ElectrumMiniWallet.maybeGenerateNextactually keepslastDerived ≥ firstUnused + lookAhead − 1, solookAheadcounts the first unused address itself: at 3, three change addresses in all. Rather than depend on that arithmetic,nextChangeIndexchooses only among the addresses the wallet has actually generated, which is the watched set by definition. So change can never be sent to an address nobody is watching, whatever the look-ahead is.CHANGE_LOOKAHEADis raised to 10, so a group can have ten spends with change open at once. Past that,sendreturnsTooManyOpen, and the preview says to wait for one to settle or to send everything. Send-all never needs a change address, so it is never refused this way. - Still finding is not nothing. When there are no coins, the result is
NothingToSpendas before. When there are coins but no change address has been answered for, the result isFindingChange, and the form shows the Finding the group's coins indicator instead of an error. - Dust change is shown.
Result.Built.absorbedis what the fee holds beyond the fee rate. It is zero forsendAll, for a build with change, and for a bump. When it is positive, the preview adds "N sats left over are too few to come back as change, and go to the fee." This line was meant for Phase 4, but the new result cases meantSendPreviewhad to change in this phase, so it went in now.
Tests. GroupSpendBuilderTest adds three:
- with index 0 held, change goes to 1, and the built PSBT claims 1;
- with every watched index held, the result is
TooManyOpen, while send-all still builds; - with no change branch yet, the result is
FindingChange, while no coins is stillNothingToSpend.
The dust test now asserts that absorbed plus the fee at the fee rate is the
fee. GroupOnchainWalletJvmTest asserts that the change window is
CHANGE_LOOKAHEAD addresses, all subscribed, and that holding all of them
leaves null.
The end-to-end case the removed gate was waiting for is in
GroupSpendSigningJvmTest, not GroupWalletSpendRoundTest as planned: the
round test has no database or manager, and this case needs both. One spend is
left open, holding change index 0. Then GroupSpendBuilder.send builds a
second spend from a fresh coin, and two devices sign it to COMPLETE. The
test asserts:
- the device that did not build it labels index 1 as change;
- both devices' transactions pass
correctlySpends; - once confirmed, the change coin counts in
confirmedBalance, andderivationOffinds it.
The same file's reservation test now also asserts that a failed session releases its change index.
Phase 4: the form
Two days. Built. Everything the screen draws, under the CLAUDE.md rules.
Top to bottom:
- Address. Unchanged.
- Send everything. The whole row is the control:
Modifier.toggleable(role = Role.Switch)andminimumInteractiveComponentSize()on theRow, with theSwitchtakingonCheckedChange = null. That makes one 48dp target with one name, instead of a small switch beside a label that does nothing when tapped. - Amount in sats, shown when the switch is off:
- the number keyboard with
ImeAction.Next, and Phase 1'sGroupedSats; suffixsats, so the unit is part of the field and not only its label;supportingTextsays how much can be spent: "100,000 sats confirmed and free to spend". That isGroupSpendBuilder.spendableBalance, built onspendable, which is now public so the screen and the builder count the same coins. On mainnet a second line gives the cap, using the existingwhile_the_wallet_is_new_at_most_s_satsrather than a reworded copy, so the warning before the cap is hit and the error when it is hit are the same sentence;- amount problems go to the field, as
isErrorplus the supporting text:InvalidAmount,NotEnough,BelowDustandOverCap. The decision isGroupSendViewModel.isAboutTheAmount, which is always false while sending everything, because then there is no field to put them on. While the field shows a problem, the preview below shows nothing, so the problem is said once.
- the number keyboard with
- Fee rate. Unchanged.
- Preview. Built, or the reason it cannot be: address, nothing to spend,
TooManyOpen. The go to the fee line andTooManyOpenlanded in Phase 3. The wording of every reason is now one function,problemWith, shared by the field and the preview. - Nothing leaves until a quorum signs and the button. Unchanged.
Turning Send everything on hides the amount field without clearing it, so turning it off again finds the amount typed.
Strings: sats and s_sats_confirmed_and_free_to_spend are new here. The
rest came in earlier phases. sats_are_whole_numbers,
that_is_more_sats_than_there_will_ever_be and that_isn_t_an_amount_in_sats
came in Phase 1, and s_sats_left_over_go_to_the_fee and
too_many_spends_are_open_with_change in Phase 3.
Budgets: the audit's budgets are all met. The amount field adds no icon,
and the switch row is a toggleable with a minimum size, not a .clickable.
Test, jvmTest/…/ui/composable/GroupSendScreenJvmTest.kt, five cases, on
regtest unless stated:
- typing
40000shows40,000, Sends 40,000 sats, and change, and the button is enabled; - the amount is shown as free to spend, and off mainnet there is no cap line;
0.5puts the whole-numbers error on the field, which is in its error state, with no preview and a disabled button;- the Send everything row hides the field and the change, and tapping it
again brings back
40,000and its preview; - on mainnet, the cap line shows before typing, and
150000puts the field in its error state with the button disabled.
Phase 5: what the other members see
Half a day, mostly reading. Built: tests only, nothing needed fixing. The approval side has been built since the wallet note's Phase 8. This phase checked that every place a spend is described reports the payment, not the payment plus change.
| place | reads | with change, it says | tested by |
|---|---|---|---|
FrostSigningScreen.WhatIsBeingSpent |
every output and its isChange |
a payment row, a change row labelled back to the group as change, the fee | GroupSpendSigningJvmTest: the other device's checkedSpend labels exactly the change output |
ProposedSpend.summarize, which the proposal list and the wallet screen's spend rows both use |
the single payment's amount | Send 30,000 sats to bcrt1… | ProposedSpendTest, new |
GroupWalletScreen's spend rows |
ProposedSpend.summarize(row.spend) |
the same as the row above | the same test: the plan had not read this row, and it turned out to reuse the summary, not compute its own amount |
the signed line (TYPE_FROST_COMPLETE) and the confirmed line (TYPE_GROUP_TRANSACTION_CONFIRMED) |
amountSent, which excludes change |
sending 30000 sats and 30000 sats sent | GroupSpendSigningJvmTest's end-to-end case, which now runs recordConfirmed and reads both lines off the other device's transcript |
Phase 6: checked, and opened
Half a day. The automated checks are done; the by-hand walkthrough is not.
./gradlew :composeApp:m3Audit
./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
Both ran after every phase, and every phase was committed only once they passed. At the end: 1,348 JVM tests passing, the Android compile clean, and every audit budget and floor met.
Still to do, by hand, on regtest, with two devices in a group with an opened wallet. This needs two devices with nodes, so it was not done while building. Each step, and the automated test that comes closest:
| step | closest automated cover | what it cannot show |
|---|---|---|
| 1. fund it with two coins | — | |
| 2. send an amount that needs one coin, and check the preview's change matches the approval screen's on the other device | GroupSpendSigningJvmTest's end-to-end case: the builder's change equals the other device's checked change output |
the two screens drawn side by side |
| 3. with the first spend open, send a second, and check it picks the other coin and a different change address | the same test, with an open spend holding index 0 and the second paying index 1 | reservations read through the real repository after a real round of messages |
| 4. sign both, confirm both, and check that both change coins are in the confirmed balance | the same test's confirmedBalance, and GroupOnchainWalletJvmTest's change coin over a fake Electrum |
a real Electrum server reporting the change address |
| 5. send an amount that leaves dust change, and check the go to the fee line | GroupSpendBuilderTest's dust case for absorbed |
the line itself on screen: no screen test produces dust change |
The wallet note's tables were updated in Phase 2, and this note was added to README.md with the plan.
Phase 7: the first release
No code. Mainnet gets send-an-amount in the same release as every other network, so the first real reports come from both at once. The 100,000 sat cap stays in force. It lifts on its own condition, which is about aggregation and confirmation, not change, and lifting it is a separate decision from this plan.
What to watch, and what each would mean:
- A change output shown as a payment on the approval screen. Check 5 refused to label it, so its claimed derivation did not reproduce its script. That is a builder bug. Members are shown a payment that is really the group's own money, and anyone reading the approval screen closely sees an output to an unfamiliar address and declines. Fix it in the builder. Nothing needs to be put back behind a gate.
- Change that never shows in the balance. The change address is outside the watched window, which Phase 3 was meant to prevent. The coins are not lost, because the address derives, but the window or the reservation is wrong.
- The same change address in two confirmed spends. Reservation missed a session.
If either of the first two turns out to be widespread, the response is the
cap, not a new gate. Lowering MAINNET_CAP bounds the harm at once without
taking away the send-everything path that already works.
What this does not do
- Units other than sats. No bitcoin, no fiat, no toggle (Phase 0, decision 2).
- Several recipients.
ProposedSpendalready describes a spend to several addresses, so the approval side would cope. The form, the cap and coin selection would each need rethinking. - Choosing coins. Largest first, as built. Coin control is a disclosure on a form that most members never open.
- Subtracting the fee from the amount. The amount is what arrives. A member who wants "everything but some" sends an amount.
| phase | what | days |
|---|---|---|
| 0 | decisions | ½ |
| 1 | parseSats, field transformations |
1 |
| 2 | the gate comes out, committed after Phase 3 | ½ |
| 3 | reserved change, window, FindingChange, absorbed |
1½ |
| 4 | the form | 2 |
| 5 | what the other members see | ½ |
| 6 | checks, regtest by hand, docs | ½ |
| 7 | watching the first release | — |