diff --git a/composeApp/src/commonMain/composeResources/values/strings.xml b/composeApp/src/commonMain/composeResources/values/strings.xml index bcd1ef4a..0eb11cab 100644 --- a/composeApp/src/commonMain/composeResources/values/strings.xml +++ b/composeApp/src/commonMain/composeResources/values/strings.xml @@ -654,6 +654,9 @@ The group has nothing confirmed to spend yet. The group doesn't have that much confirmed, after the fee. That is too little to send: the network won't relay an output that small. + Sats are whole numbers: there is nothing smaller than a sat to send. + That is more sats than there will ever be. + That isn't an amount in sats. Couldn't ask the group to send. Sending needs a share of the group's key, and a wallet of your own on this profile to see the group's coins with. Nothing leaves the wallet until a quorum of members has seen this spend and signed it. diff --git a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/text/Sats.kt b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/text/Sats.kt index e1d4063a..0692979e 100644 --- a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/text/Sats.kt +++ b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/text/Sats.kt @@ -1,5 +1,7 @@ package com.machankura.bennu.compose.text +import androidx.compose.foundation.text.input.OutputTransformation +import androidx.compose.foundation.text.input.insert import fr.acinq.bitcoin.Satoshi /** @@ -14,3 +16,84 @@ fun Satoshi.grouped(): String { val grouped = digits.reversed().chunked(3).joinToString(",").reversed() return if (sat < 0) "-$grouped" else grouped } + +/** What a member typed as an amount in sats, read -- or the reason it cannot be. */ +sealed interface SatsInput { + data object Empty : SatsInput + data class Sats(val amount: Satoshi) : SatsInput + /** A decimal separator: a sat is the smallest thing there is to send. */ + data object NotWhole : SatsInput + /** More than 21,000,000 bitcoin. */ + data object TooLarge : SatsInput + /** Letters, or grouping that groups nothing: `40,0000`, `4 0`. */ + data object Unreadable : SatsInput +} + +/** Every sat there will ever be: 21,000,000 bitcoin. */ +val MAX_SATS: Satoshi = Satoshi(2_100_000_000_000_000) + +/** + * Thousands separators people paste: a comma, a space and its two no-break + * forms -- the last is how a South African locale groups -- an apostrophe and + * an underscore. + */ +private val GROUPING = setOf(',', ' ', ' ', ' ', '\'', '_') + +/** + * [text] as sats, refusing anything it would have to guess at. + * + * Separators are dropped only where they group thousands. A `.` is a decimal + * point and refused, and so is a comma with one or two digits after it, + * because `40,5` is forty and a half where commas are decimal points. Dropping + * either is how `21000.5` used to become 210,005 sats. + */ +fun parseSats(text: CharSequence): SatsInput { + val trimmed = text.trim() + if (trimmed.isEmpty()) return SatsInput.Empty + if ('.' in trimmed) return SatsInput.NotWhole + // Ascii digits only: `isDigit` admits every script's digits, and so does the JVM's `toLong`. + if (trimmed.any { it !in '0'..'9' && it !in GROUPING }) return SatsInput.Unreadable + + val groups = mutableListOf(StringBuilder()) + val separators = mutableListOf() + for (c in trimmed) { + if (c in '0'..'9') { + groups.last().append(c) + } else { + separators += c + groups += StringBuilder() + } + } + + if (groups.size > 1) { + val leading = groups.dropLast(1) + if (separators.last() == ',' && groups.last().length in 1..2 && leading.all { it.isNotEmpty() }) { + return SatsInput.NotWhole + } + if (groups.first().length !in 1..3 || groups.drop(1).any { it.length != 3 }) return SatsInput.Unreadable + } + + // Counted before it is a number, so a long paste is "too large" rather than an overflow. + val significant = groups.joinToString("").trimStart('0') + if (significant.length > MAX_SATS.sat.toString().length) return SatsInput.TooLarge + val sats = Satoshi(significant.ifEmpty { "0" }.toLong()) + return if (sats > MAX_SATS) SatsInput.TooLarge else SatsInput.Sats(sats) +} + +/** + * An amount field's digits shown grouped as [grouped] writes them, so what is + * typed reads the way the preview and the approval screen will say it. + * + * Display only: the field holds what was typed. Anything but plain digits is + * shown as it is, for [parseSats] to accept or refuse -- regrouping `40,5` + * would show it as a number it is not. + */ +val GroupedSats: OutputTransformation = OutputTransformation { + if (length > 3 && asCharSequence().all { it in '0'..'9' }) { + var index = length - 3 + while (index > 0) { + insert(index, ",") + index -= 3 + } + } +} diff --git a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/composable/GroupSendScreen.kt b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/composable/GroupSendScreen.kt index 1651fe61..5bb5195c 100644 --- a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/composable/GroupSendScreen.kt +++ b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/composable/GroupSendScreen.kt @@ -56,6 +56,11 @@ import bennu.composeapp.generated.resources.the_group_has_nothing_confirmed_to_s import com.machankura.bennu.compose.nostr.wallet.GroupWalletStatementEvent import com.machankura.bennu.compose.repository.ChatRepository import com.machankura.bennu.compose.repository.FrostSigningRepository +import bennu.composeapp.generated.resources.sats_are_whole_numbers +import bennu.composeapp.generated.resources.that_is_more_sats_than_there_will_ever_be +import bennu.composeapp.generated.resources.that_isn_t_an_amount_in_sats +import com.machankura.bennu.compose.text.GroupedSats +import com.machankura.bennu.compose.text.SatsInput import com.machankura.bennu.compose.text.grouped import com.machankura.bennu.compose.ui.composable.navigation.routes.FrostSigningRoute import com.machankura.bennu.compose.ui.composable.navigation.routes.Route @@ -188,6 +193,7 @@ fun GroupSendScreen( OutlinedTextField( modifier = Modifier.fillMaxWidth(), state = groupSendViewModel.amountField, + outputTransformation = GroupedSats, lineLimits = TextFieldLineLimits.SingleLine, keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number), label = { Text(stringResource(Res.string.amount_in_sats)) }, @@ -269,6 +275,11 @@ private fun SendPreview(result: GroupSpendBuilder.Result, chain: Chain) { GroupSpendBuilder.Result.NothingToSpend -> stringResource(Res.string.the_group_has_nothing_confirmed_to_spend) GroupSpendBuilder.Result.NotEnough -> stringResource(Res.string.the_group_doesn_t_have_that_much_confirmed) is GroupSpendBuilder.Result.OverCap -> stringResource(Res.string.while_the_wallet_is_new_at_most_s_sats, result.cap.grouped()) + is GroupSpendBuilder.Result.InvalidAmount -> when (result.input) { + SatsInput.NotWhole -> stringResource(Res.string.sats_are_whole_numbers) + SatsInput.TooLarge -> stringResource(Res.string.that_is_more_sats_than_there_will_ever_be) + else -> stringResource(Res.string.that_isn_t_an_amount_in_sats) + } else -> stringResource(Res.string.that_is_too_little_to_send) }, style = MaterialTheme.typography.bodyMedium, diff --git a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModel.kt b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModel.kt index 53f2392d..b77982c1 100644 --- a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModel.kt +++ b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModel.kt @@ -15,12 +15,13 @@ import androidx.lifecycle.viewmodel.viewModelFactory import co.touchlab.kermit.Logger import com.machankura.bennu.compose.repository.ChatRepository import com.machankura.bennu.compose.repository.FrostSigningRepository +import com.machankura.bennu.compose.text.SatsInput +import com.machankura.bennu.compose.text.parseSats import com.machankura.bennu.compose.ui.view.state.GroupSendUIState import com.machankura.bennu.compose.wallet.GroupOnchainWallets import com.machankura.bennu.compose.wallet.GroupSpendBuilder import com.vitorpamplona.quartz.nip01Core.core.HexKey import fr.acinq.bitcoin.Chain -import fr.acinq.bitcoin.Satoshi import kotlinx.coroutines.Dispatchers import kotlinx.coroutines.Job import kotlinx.coroutines.launch @@ -94,21 +95,35 @@ class GroupSendViewModel( } } + /** What the amount field says, read the one way everything that reads it does. */ + fun amount(): SatsInput = parseSats(amountField.text) + /** * The spend the form describes right now, or null while it is incomplete -- - * no wallet state yet, no feerate, no amount. + * no wallet state yet, no feerate, no amount. An amount that is not one is + * not incomplete, and says so before the rest of the form is filled in. */ fun preview(): GroupSpendBuilder.Result? { val state = groupSendUIState as? GroupSendUIState.Ready ?: return null val walletState = state.walletState ?: return null + + val amount = if (sendEverything.value || !GroupWalletRollout.SEND_AN_AMOUNT) { + null + } else { + when (val input = amount()) { + SatsInput.Empty -> return null + is SatsInput.Sats -> input.amount + else -> return GroupSpendBuilder.Result.InvalidAmount(input) + } + } + val feerate = feerateField.text.toString().trim().toLongOrNull()?.takeIf { it > 0 } ?: return null val address = addressField.text.toString().trim().takeIf { it.isNotEmpty() } ?: return null - val built = if (sendEverything.value || !GroupWalletRollout.SEND_AN_AMOUNT) { + val built = if (amount == null) { GroupSpendBuilder.sendAll(walletState, address, feerate, state.reserved) } else { - val amount = amountField.text.toString().filter { it.isDigit() }.toLongOrNull() ?: return null - GroupSpendBuilder.send(walletState, address, Satoshi(amount), feerate, state.reserved) + GroupSpendBuilder.send(walletState, address, amount, feerate, state.reserved) } return GroupSpendBuilder.capped(built, GroupWalletRollout.capFor(chain)) } diff --git a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/wallet/GroupSpendBuilder.kt b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/wallet/GroupSpendBuilder.kt index d320df96..f0e3babf 100644 --- a/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/wallet/GroupSpendBuilder.kt +++ b/composeApp/src/commonMain/kotlin/com/machankura/bennu/compose/wallet/GroupSpendBuilder.kt @@ -1,6 +1,7 @@ package com.machankura.bennu.compose.wallet import com.machankura.bennu.compose.managers.GroupWalletDerivation +import com.machankura.bennu.compose.text.SatsInput import fr.acinq.bitcoin.Bitcoin import fr.acinq.bitcoin.ByteVector import fr.acinq.bitcoin.ByteVector64 @@ -36,6 +37,8 @@ object GroupSpendBuilder { data object NotHigher : Result /** More than [GroupWalletRollout.capFor] lets one spend send. */ data class OverCap(val cap: Satoshi) : Result + /** The amount typed is not a number of sats; [input] says why. */ + data class InvalidAmount(val input: SatsInput) : Result } /** diff --git a/composeApp/src/commonTest/kotlin/com/machankura/bennu/compose/text/SatsTest.kt b/composeApp/src/commonTest/kotlin/com/machankura/bennu/compose/text/SatsTest.kt new file mode 100644 index 00000000..d201e31f --- /dev/null +++ b/composeApp/src/commonTest/kotlin/com/machankura/bennu/compose/text/SatsTest.kt @@ -0,0 +1,81 @@ +package com.machankura.bennu.compose.text + +import androidx.compose.foundation.text.input.TextFieldState +import fr.acinq.bitcoin.Satoshi +import kotlin.test.Test +import kotlin.test.assertEquals + +/** + * An amount typed in sats: read when it can only mean one number, refused when + * it could mean two. The cases that matter are the decimals -- a reader that + * drops the separator multiplies the amount by ten for every digit after it. + */ +class SatsTest { + private fun sats(amount: Long) = SatsInput.Sats(Satoshi(amount)) + + @Test + fun `grouped and ungrouped amounts read the same`() { + assertEquals(sats(40_000), parseSats("40000")) + assertEquals(sats(40_000), parseSats("40,000")) + assertEquals(sats(40_000), parseSats("40 000")) + assertEquals(sats(40_000), parseSats("40 000")) + assertEquals(sats(40_000), parseSats("40 000")) + assertEquals(sats(40_000), parseSats("40'000")) + assertEquals(sats(40_000), parseSats("40_000")) + assertEquals(sats(1_250_000), parseSats(" 1,250,000 ")) + assertEquals(sats(7), parseSats("007")) + assertEquals(sats(0), parseSats("0")) + } + + @Test + fun `a decimal is refused rather than dropped`() { + assertEquals(SatsInput.NotWhole, parseSats("21000.5"), "not 210,005") + assertEquals(SatsInput.NotWhole, parseSats("0.0005"), "a bitcoin amount, not 5 sats") + assertEquals(SatsInput.NotWhole, parseSats("40,5"), "forty and a half where a comma is the decimal point") + assertEquals(SatsInput.NotWhole, parseSats("40,50")) + assertEquals(SatsInput.NotWhole, parseSats("1 000,5")) + } + + @Test + fun `grouping that groups nothing, and letters, are unreadable`() { + assertEquals(SatsInput.Unreadable, parseSats("40,0000")) + assertEquals(SatsInput.Unreadable, parseSats("4 0")) + assertEquals(SatsInput.Unreadable, parseSats("1234,567")) + assertEquals(SatsInput.Unreadable, parseSats("40,,000")) + assertEquals(SatsInput.Unreadable, parseSats(",500")) + assertEquals(SatsInput.Unreadable, parseSats("40k")) + assertEquals(SatsInput.Unreadable, parseSats("-40")) + assertEquals(SatsInput.Unreadable, parseSats("٤٠"), "digits, but not ones the amount can be written in") + } + + @Test + fun `nothing typed is empty, not zero`() { + assertEquals(SatsInput.Empty, parseSats("")) + assertEquals(SatsInput.Empty, parseSats(" ")) + } + + @Test + fun `there are only so many sats`() { + assertEquals(sats(MAX_SATS.sat), parseSats("2,100,000,000,000,000")) + assertEquals(SatsInput.TooLarge, parseSats("2100000000000001")) + assertEquals(SatsInput.TooLarge, parseSats("9".repeat(40)), "past a Long, without overflowing") + assertEquals(sats(5), parseSats("0".repeat(40) + "5"), "leading zeros are not digits that count") + } + + private fun shown(typed: String): String { + val state = TextFieldState(typed) + state.edit { with(GroupedSats) { transformOutput() } } + return state.text.toString() + } + + @Test + fun `the field shows plain digits grouped, and anything else as it was typed`() { + assertEquals("400", shown("400")) + assertEquals("4,000", shown("4000")) + assertEquals("40,000", shown("40000")) + assertEquals("1,250,000", shown("1250000")) + assertEquals("40,5", shown("40,5"), "regrouping would show a number it is not") + assertEquals("21000.5", shown("21000.5")) + assertEquals("", shown("")) + } +} diff --git a/composeApp/src/jvmTest/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModelJvmTest.kt b/composeApp/src/jvmTest/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModelJvmTest.kt index 355597ee..4d21377c 100644 --- a/composeApp/src/jvmTest/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModelJvmTest.kt +++ b/composeApp/src/jvmTest/kotlin/com/machankura/bennu/compose/ui/view/model/GroupSendViewModelJvmTest.kt @@ -10,6 +10,7 @@ import com.machankura.bennu.compose.nostr.wallet.GroupWallet import com.machankura.bennu.compose.nostr.wallet.GroupWalletStatementEvent import com.machankura.bennu.compose.repository.ChatRepository import com.machankura.bennu.compose.repository.FrostSigningRepository +import com.machankura.bennu.compose.text.SatsInput import com.machankura.bennu.compose.ui.view.state.GroupSendUIState import com.machankura.bennu.compose.wallet.GroupSpend import com.machankura.bennu.compose.wallet.GroupSpendBuilder @@ -42,6 +43,7 @@ import kotlin.test.BeforeTest import kotlin.test.Test import kotlin.test.assertEquals import kotlin.test.assertIs +import kotlin.test.assertNotEquals import kotlin.test.assertNotNull import kotlin.test.assertNull import kotlin.time.Instant @@ -137,6 +139,21 @@ class GroupSendViewModelJvmTest { assertIs(GroupSpend.check(signing.proposed!!, account), "the other members would accept it") } + @Test + fun `a decimal amount is refused, never sent ten times over`() { + val model = viewModel(GroupSendUIState.Ready(localChatRoom, wallet, walletState, reserved = emptySet())) + model.addressField.setTextAndPlaceCursorAtEnd("bcrt1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080") + model.feerateField.setTextAndPlaceCursorAtEnd("4") + model.amountField.setTextAndPlaceCursorAtEnd("21000.5") + + assertEquals(SatsInput.NotWhole, model.amount()) + val preview = model.preview() + assertNotEquals(Satoshi(210_005), (preview as? GroupSpendBuilder.Result.Built)?.amount) + if (GroupWalletRollout.SEND_AN_AMOUNT) { + assertEquals(GroupSpendBuilder.Result.InvalidAmount(SatsInput.NotWhole), preview) + } + } + @Test fun `send everything ignores the amount`() { val model = viewModel(GroupSendUIState.Ready(localChatRoom, wallet, walletState, reserved = emptySet())) diff --git a/docs/README.md b/docs/README.md index 295442de..efffe61a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,6 +11,7 @@ silent, or a decision that looked arbitrary and was not. | [subgroups.md](./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](./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 | | [group-chain-wallet.md](./group-chain-wallet.md) | an on-chain wallet the group's threshold key holds, modelled on Phoenix's final wallet — why the path is BIP86's unhardened tail under a public account step, why each input is a batch item with its own cache, and the seven checks a member makes before signing a spend | +| [group-send-an-amount.md](./group-send-an-amount.md) | sending an amount in sats from the group's wallet, with change — why the gate as written could never lift and is removed in favour of the mainnet cap, the decimal point the gated form multiplies by ten, and change addresses reserved like coins | | [frost-session-resend.md](./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 | | [marmot-membership.md](./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](./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 | diff --git a/docs/group-send-an-amount.md b/docs/group-send-an-amount.md new file mode 100644 index 00000000..d3286a9a --- /dev/null +++ b/docs/group-send-an-amount.md @@ -0,0 +1,412 @@ +# 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](./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`. + +**Phase 1 built; Phases 2-7 not.** Written against `GroupSendScreen`, `GroupSendViewModel`, +`GroupSpendBuilder`, `GroupSpend` and `GroupWalletRollout` as they are at that +commit. + +--- + +## 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: + +1. **A decimal is silently multiplied.** `preview()` reads the amount with + `filter { it.isDigit() }`. Someone who types `21000.5` gets 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. +2. **An amount too long for a `Long` disappears.** `toLongOrNull()` returns null, + `preview()` returns null, and the button stays disabled with no reason given. +3. **Two open spends with change pick the same change address.** + `nextChangeIndex` is 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. +4. **"Nothing to spend" is shown when the change branch has not loaded.** + `send` returns `NothingToSpend` when `nextChangeIndex` is null. That happens + before Electrum has answered for the change branch, while the group may hold + plenty. +5. **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. + +1. **Where the gate opens first.** **Decided: on every network at once, relying + on the mainnet cap.** `MAINNET_CAP` already 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 way `capFor` treats + 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. +2. **Whole sats only.** No bitcoin unit, no fiat, no decimal point. `Sats.kt` + already 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. +3. **"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 builds `sendAll`, 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: + +```kotlin +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 paste `40,000` and `40 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,000` is + 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 under + `NotWhole`. +- **ASCII digits only.** Kotlin's `isDigit` accepts the digits of every script, + and so does the JVM's `toLong`. +- **At most `MAX_SATS`**, 2,100,000,000,000,000. Significant digits are counted + before `toLong()`, so a forty-digit paste is `TooLarge`, 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.** 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_AMOUNT` is deleted**, and its kdoc goes with it. + `ENABLED` and `MAINNET_CAP` stay. 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. In + `GroupSendViewModel.preview()`, the condition becomes `sendEverything.value` + alone. +- **The send-all sentence goes.** `for_now_a_spend_sends_everything` has no + reader once the `else` branch is gone. Remove it from `strings.xml`, so the + catalogue holds no text that the app never shows. +- **`GroupSendViewModelJvmTest` stops branching.** `the preview waits for the + form, and what it builds is what is proposed` asserts the amount-with-change + case outright: 40,000 sats sent, change not null, and `GroupSpend.check` + accepting 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.Mainnet` where an amount + over 100,000 sats previews as `OverCap`. `GroupSpendBuilderTest` already + 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 loses its *send-all only* row, and its "built" +table's `SEND_AN_AMOUNT` row says the gate was removed, why, and which commit +removed it (Phase 6). + +--- + +## Phase 3: change goes to an address the group can find + +**One and a half days.** This fixes problems 3 and 4 above. It is the only phase +that touches the builder's choices, so it is the one that needs the most tests. + +- **Change indices are reserved like coins.** Next to + `FrostSigningManager.reservedOutPoints`, add `reservedChangeIndices(database, + chatRoomId): Set`. It decodes the PSBT of every `GroupTransaction` whose + session is not `FAILED`, and collects each output's change derivation. It + covers the same sessions as `reservedOutPoints`, for the same reason. Expose + it on `FrostSigningRepository`, and carry it on `GroupSendUIState.Ready` next + to `reserved`. +- **`GroupWalletState.nextChangeIndex(reserved: Set)`** returns the first + change index that is unused and not reserved. `GroupSpendBuilder.send` takes + that set and calls this. +- **Inside the watched window, or refused.** `CHANGE_LOOKAHEAD` is 3, and its + comment says *"change addresses are only ever chosen by a spend, one at a + time"*, which reservation makes untrue. The change wallet watches three + addresses past the first unused one. So a fifth open spend with change would + pay an address that Electrum is not watching. That is not a loss, because the + address derives, but the change would be missing from the balance until the + window moves. Two changes: + 1. raise `CHANGE_LOOKAHEAD` to 10, the same as receive, since several members + can now each hold an open spend with change; + 2. when the next free index is past the watched window, `send` returns a new + `Result.TooManyOpen`. The screen says to wait for an open spend to + settle, or to send everything. + + Check the window against `ElectrumMiniWallet`'s generator before trusting + either number. The wallet note's comment says the look-ahead counts past the + first *unused* address, and this phase depends on that being right. +- **The change branch not loaded yet is "still finding", not "nothing".** When + the change `WalletState` has no addresses yet, `send` returns a new + `Result.FindingChange`, and the form shows it with the same indicator as + `walletState == null` (*Finding the group's coins*), not as an error. +- **Dust change shows up in the preview.** Add `absorbed: Satoshi` to + `Result.Built`: what the build added to the fee because the change would have + been dust. It is zero for `sendAll`, for a build with change, and for a bump. + +**Tests**, extending `GroupSpendBuilderTest`: + +- with change index 0 reserved, `send` pays change to index 1, and `GroupSpend.check` + labels it change; +- reserving every index in the watched window gives `TooManyOpen`; +- an empty change branch gives `FindingChange`, not `NothingToSpend`; +- the dust case's `absorbed` plus the fee at the rate equals its fee. + +And extending `GroupWalletSpendRoundTest` with **the end-to-end case the removed +gate was waiting for**: two devices, an amount with change, signed to `COMPLETE`. +Assert that the change output is labelled change on the device that did not +propose it, and that once the change coin is in the wallet state it counts in +`confirmedBalance`. That is the test version of "nobody reported a mislabelled +change output", and with no test-network release before mainnet, it is the +only version there is before the feature ships. + +`reservedChangeIndices` gets its own jvmTest next to whatever tests +`reservedOutPoints`. A `FAILED` session releases its index, and a `COMPLETE` +one keeps it until Electrum reports the address used. + +--- + +## Phase 4: the form + +**Two days.** Everything the screen draws, under the CLAUDE.md rules. + +Order, top to bottom: + +1. **Address.** Unchanged. +2. **Send everything.** The row, not only the switch, toggles it: + `Modifier.toggleable(role = Role.Switch)` on the `Row`, the `Switch` taking + `onCheckedChange = null`, and `minimumInteractiveComponentSize()`. That is one + 48dp target with one name, rather than a small switch beside a label that + does nothing when tapped. +3. **Amount in sats**, shown when the switch is off: + - `keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number, + imeAction = ImeAction.Next)`, with Phase 1's transformations; + - `suffix = { Text(stringResource(Res.string.sats)) }`, so the unit is part of + the field and not only its label; + - `supportingText` holds **how much can be spent**: *"120,000 sats confirmed + and free to spend"*. That is the sum of what `GroupSpendBuilder.spendable` + returns. The function is private today; make it public, so the screen + and the builder count the same coins. It is less than the wallet screen's + balance by whatever open spends hold, and the line says *free to spend* + because of that difference. On mainnet, while the cap holds, a second line + says *"At most 100,000 sats in one spend while the wallet is new."* + - `isError` and `supportingText` show **amount errors at the field**: + `NotWhole`, `TooLarge`, `NotEnough`, `BelowDust`, `OverCap`. Address and + fee problems stay in the preview below, so each error appears next to the + field it is about. +4. **Fee rate.** Unchanged. +5. **Preview.** As today, plus one line when `absorbed > 0`: *"%1$s sats left + over are too few to come back as change, and go to the fee."* The other + addition is `TooManyOpen`. +6. **Nothing leaves until a quorum signs** and the button. Unchanged. + +When the switch is turned on and off again, the amount typed is kept. The field +is hidden, not cleared, and `amountField` already outlives the composition. + +**Strings**, sentence case, format arguments, in `strings.xml`: +`sats`, `s_sats_confirmed_and_free_to_spend`, +`at_most_s_sats_in_one_spend_while_the_wallet_is_new`, +`sats_are_whole_numbers`, `that_is_more_sats_than_there_are`, +`s_sats_left_over_go_to_the_fee`, `too_many_spends_are_open_with_change`. +(`for_now_a_spend_sends_everything` was removed in Phase 2.) The existing `while_the_wallet_is_new_at_most_s_sats` may be reworded and reused +rather than duplicated. + +**Budgets that must not move:** 0 spacing `.dp` literals, 0 hardcoded colours, +0 unguarded `.clickable`, 0 untriaged `contentDescription = null`. The amount +field adds no icon. + +**Test**, `jvmTest/…/ui/composable/GroupSendScreenJvmTest.kt`, in the style of +`ProposeGroupEventScreenJvmTest`, with a `Ready` state on regtest: + +- typing `40000` shows `40,000` in the field and *Sends 40,000 sats* in the + preview, and the button is enabled; +- typing `0.5` shows the whole-numbers error on the field, and the button is + disabled; +- tapping the *Send everything* row hides the field, and tapping it again + brings the field back with `40,000`; +- on mainnet, the field is shown with the cap line under it, and `150000` + shows the cap error on the field. + +--- + +## Phase 5: what the other members see + +**Half a day, mostly reading.** The approval side has been built since Phase 8. +This phase checks that each place a spend is described says the payment and +not the total. + +| place | reads | expected with change | +|---|---|---| +| `FrostSigningScreen.WhatIsBeingSpent` | every output, `isChange` | payment row, change row labelled *back to the group as change*, fee | +| `ProposedSpend.summarize` | the one payment's amount | *Send 40,000 sats to bcrt1…*, not the inputs' total | +| `FrostSigningManager`'s completion and confirmation lines | `amountSent` | the payment only: `amountSent` already excludes change | +| `GroupWalletScreen`'s spend rows | check | the payment, not payment plus change | + +Add one test per row whose behaviour is not already tested: build a spend with +change through `GroupSpendBuilder.send`, check it, and assert the words. The +`GroupWalletScreen` row is the one not yet read for this plan. If it shows +anything but `amountSent`, fixing it belongs in this phase. + +--- + +## Phase 6: checked, and opened + +**Half a day.** + +```bash +./gradlew :composeApp:m3Audit +``` + +```bash +./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest +``` + +Then by hand, on regtest, with two devices in a group with an opened wallet: + +1. fund it with two coins; +2. send an amount that needs one coin, and check that the preview's change + matches the approval screen's change on the other device; +3. while the first spend is open, send a second amount, and check that it + picks the other coin and a different change address; +4. sign both, confirm both, and check that both change coins appear in the + wallet's confirmed balance; +5. send an amount that leaves dust change, and check the *go to the fee* line. + +Then update [group-chain-wallet.md](./group-chain-wallet.md): remove the Phase +10 table's *send-all only* row, and make the "built" table's `SEND_AN_AMOUNT` +row say the gate was removed and that the mainnet cap stands in for it. This +note is already in [README.md](./README.md). + +--- + +## 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.** `ProposedSpend` already 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 | — |