diff --git a/docs/README.md b/docs/README.md index 192e7ccf..c7fcf62c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -58,10 +58,11 @@ The subgroup-wallet-policy note is a phased plan that has been built. It reads as the guardians note's *whose choice it is* reversed: read that section, then this note's Phase 0, whose five decisions shape every phase after it, and its table of where the build chose differently before the code. -The guarded-wallet-funding note is a phased plan that has not been built. It +The guarded-wallet-funding note is a phased plan that has been built. It reads as the guardians note run the other way, coins in rather than out: read that note and the address note's *Why `+ 2`* first, then its seven decisions -before its phases. +before its phases, and its table of where the build chose differently before +the code. 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. diff --git a/docs/group-wallet-addresses.md b/docs/group-wallet-addresses.md index 44f4e207..2ff4b332 100644 --- a/docs/group-wallet-addresses.md +++ b/docs/group-wallet-addresses.md @@ -90,7 +90,9 @@ wallet to two payers in the same hour hand out the same address, and the group reuses it. Offering `current + 1` and `current + 2` beside it gives a second and third member something else to hand out. Both are already watched, because the look-ahead keeps the wallet subscribed to `current … current + 9`, so a payment -to either is seen the moment it reaches the mempool. +to either is seen the moment it reaches the mempool. An ancestor funding a +guarded wallet starts at the top of that window, `current + 2`, and goes up, so +it stays out of the members' way -- [guarded-wallet-funding.md](./guarded-wallet-funding.md), D2. **Why `highest used`.** `firstUnusedDerivedAddress` takes the *lowest* unused index, so a payment above `current` does not move `current`. If `/0/3` is diff --git a/docs/group-wallet-guardians.md b/docs/group-wallet-guardians.md index 074c1126..651b104b 100644 --- a/docs/group-wallet-guardians.md +++ b/docs/group-wallet-guardians.md @@ -442,7 +442,8 @@ the group does not un-know a key*, inherited one level down. **It does not tell the child before it happens**, and it does not constrain where the coins go. "Only back into the child, at a new address" is a covenant, and there is none on mainnet to write it with (`OP_CHECKTEMPLATEVERIFY`, -`OP_VAULT`). +`OP_VAULT`). The other direction is supported: an ancestor paying coins *into* +a guarded wallet is [guarded-wallet-funding.md](./guarded-wallet-funding.md). ## Appendix — what was considered and rejected diff --git a/docs/guarded-wallet-funding.md b/docs/guarded-wallet-funding.md index 46a0ee3c..4269b4bb 100644 --- a/docs/guarded-wallet-funding.md +++ b/docs/guarded-wallet-funding.md @@ -17,8 +17,27 @@ the forwarded statement from the first, the send form and its reservations from the second, and the "current plus two" rule from the third. It changes no format, no derivation and no schema. -**Not built.** Written against the code as it stood at `8cb6f04e`, schema v29, -with the `lightning-kmp-app` submodule at `e0d2b82`. +**Built**, phases 1-6, one commit each, written against the code as it stood +at `8cb6f04e`, schema v29, with the `lightning-kmp-app` submodule at `e0d2b82`; +the build changes no schema. `GroupWalletState.fundingAddress`, +`GroupSpendBuilder.Destination.Funding`, `GroupSpend.fundingsOf` and +`GroupSendRoute.fundChatRoomId` are the entry points. 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 tests `claimedFundingIndices` | Phase 2 does: until the builder writes a claim there is no PSBT to read one from. Phase 1's watched-window test also counts the slots, eight, so the bound and the look-ahead cannot drift apart unnoticed | +| Phase 2: `send` and `sendAll` take a destination rather than an address string | both, as overloads: the string versions build a `Destination.Address` and call through, so the thirty-odd existing call sites, most of them tests, did not change. The claim always goes on output 0, where both builders put the payment | +| Phase 3: the check runs in `acceptSpendProposal` and `checkedSpend` | and in `proposeSpend` and `proposeGuardianSpend`, so a proposal every other device would refuse is refused before it is sent. It is one extension, `GroupSpend.Result.withFundings`, and a spend none of whose payments claims anything reads no guarded wallets at all | +| nothing about bumping | `GroupSpendBuilder.bump` rebuilt the PSBT without the claim, so a bumped funding would have read as a payment to a bare address and released its index. It carries `Checked.fundings` across | +| Phase 3's test is in the shape of `GuardianSpendRoundTest` | it is three tests in `GuardianSigningJvmTest`, which already holds an ancestor, a guarded child and the forwarding. The refusal test has the lie proposed by a device never told about the wallet -- the realistic way one arrives, since a device that holds the wallet refuses to propose it | +| Phase 4: the card says *To* and then the wallet's name | *To* and then *Savings's guarded wallet*. The title already says *Fund …*, and the card repeating it read twice. The index uses the address list's own *Address %1$s* | +| Phase 4: `MiddleEllipsis` on the address | as written, and on the desktop target it ellipsises at the end, as the address list does there | +| Phase 5: the name stays on one line | two: at 200% text a one-line name was cut to a word, and the name is what says which wallet the buttons act on | +| Phase 5: a `GroupWalletViewModelJvmTest` case for `arriving` | `GuardedWalletRowTest` in commonTest, since `arriving` is a property of the row and needs no view model; and `GuardedWalletCardJvmTest` renders the card, including at twice the text size | + +Still to do by hand: the signet funding between two real devices that the end +of Phase 6 asks for. The headline: **the group already watches every guarded wallet below it, so its devices already know which of that wallet's receive addresses are unused. A