From b27ed2a05fa9f20add94e98ec7ce533fbe50c490 Mon Sep 17 00:00:00 2001 From: Kgothatso Ngako Date: Wed, 18 Nov 2026 16:15:13 +0200 Subject: [PATCH] docs: retire the wallet notes, and guard against a wallet coming back (wallet removal, Phase 8) The 23 wallet notes move to docs/retired/ with a banner; every link between notes is rewritten for the move and checked. The index lists them as one Retired paragraph, and seven kept notes carry a line on what changed. The README and CLAUDE.md describe a Giza with no wallet. brand-audit.sh loses its "bennu/ exception: every such tag was a wallet's, so one now is a wallet coming back. wallet-audit.sh --check, in check and in CI, fails on a retired kind in the app's code, a lightning-kmp import, a file named for a wallet's pieces, or sats in a string. Co-Authored-By: Claude Opus 5.5 --- .../workflows/material-design-conformance.yml | 6 +- CLAUDE.md | 32 ++++-- README.md | 39 +++---- composeApp/build.gradle.kts | 44 +++++++- .../compose/nostr/frost/FrostSigningEvents.kt | 4 +- .../mobi/giza/compose/text/ProposedEvent.kt | 2 +- .../compose/managers/ForkCompatibilityTest.kt | 18 ++-- docs/README.md | 101 +++--------------- docs/frost-batch-signing.md | 2 + docs/giza-rebrand.md | 4 +- docs/giza-wallet-removal.md | 5 +- docs/jvm-target.md | 2 + docs/multiple-profiles.md | 2 + docs/nsec-sign-in.md | 4 +- docs/{ => retired}/group-chain-wallet.md | 12 ++- .../group-lightning-liquidity.md | 2 + .../group-lightning-transcript.md | 34 +++--- docs/{ => retired}/group-lightning-wallet.md | 4 +- docs/{ => retired}/group-send-an-amount.md | 4 +- docs/{ => retired}/group-wallet-addresses.md | 4 +- docs/{ => retired}/group-wallet-guardians.md | 10 +- .../guarded-wallet-forwarding.md | 6 +- docs/{ => retired}/guarded-wallet-funding.md | 4 +- docs/{ => retired}/guardian-delay.md | 4 +- docs/{ => retired}/lightning/README.md | 2 + .../lightning/first-commitment-policy.md | 2 + .../force-close-revoked-commitment.md | 2 + .../lightning/griefing-surface.md | 2 + .../lightning/mutual-close-amount.md | 2 + .../lightning/node-seed-in-flight-exposure.md | 2 + .../lightning/restored-device-marks.md | 2 + .../{ => retired}/lightning/signer-hygiene.md | 2 + docs/{ => retired}/member-guarded-wallets.md | 14 +-- docs/{ => retired}/member-wallet-delay.md | 4 +- .../member-wallet-guarding-group.md | 4 +- docs/{ => retired}/standalone-electrum.md | 16 +-- docs/{ => retired}/subgroup-wallet-policy.md | 8 +- docs/scripts/brand-audit.sh | 33 +++--- docs/scripts/wallet-audit.sh | 66 ++++++++++++ docs/shared-key-derivation.md | 2 + docs/subgroups.md | 8 +- 41 files changed, 313 insertions(+), 207 deletions(-) rename docs/{ => retired}/group-chain-wallet.md (98%) rename docs/{ => retired}/group-lightning-liquidity.md (99%) rename docs/{ => retired}/group-lightning-transcript.md (84%) rename docs/{ => retired}/group-lightning-wallet.md (99%) rename docs/{ => retired}/group-send-an-amount.md (98%) rename docs/{ => retired}/group-wallet-addresses.md (98%) rename docs/{ => retired}/group-wallet-guardians.md (97%) rename docs/{ => retired}/guarded-wallet-forwarding.md (98%) rename docs/{ => retired}/guarded-wallet-funding.md (98%) rename docs/{ => retired}/guardian-delay.md (98%) rename docs/{ => retired}/lightning/README.md (95%) rename docs/{ => retired}/lightning/first-commitment-policy.md (98%) rename docs/{ => retired}/lightning/force-close-revoked-commitment.md (98%) rename docs/{ => retired}/lightning/griefing-surface.md (98%) rename docs/{ => retired}/lightning/mutual-close-amount.md (98%) rename docs/{ => retired}/lightning/node-seed-in-flight-exposure.md (98%) rename docs/{ => retired}/lightning/restored-device-marks.md (98%) rename docs/{ => retired}/lightning/signer-hygiene.md (99%) rename docs/{ => retired}/member-guarded-wallets.md (98%) rename docs/{ => retired}/member-wallet-delay.md (99%) rename docs/{ => retired}/member-wallet-guarding-group.md (98%) rename docs/{ => retired}/standalone-electrum.md (93%) rename docs/{ => retired}/subgroup-wallet-policy.md (98%) create mode 100755 docs/scripts/wallet-audit.sh diff --git a/.gitea/workflows/material-design-conformance.yml b/.gitea/workflows/material-design-conformance.yml index afd91a59..db8afc35 100644 --- a/.gitea/workflows/material-design-conformance.yml +++ b/.gitea/workflows/material-design-conformance.yml @@ -30,10 +30,14 @@ jobs: run: docs/scripts/m3-audit.sh --check # Not Material Design, but the same kind of check: grep, no gradle. Bennu may only be - # named in comments and derivation tags (docs/giza-rebrand.md, Phase 6). + # named in comments (docs/giza-rebrand.md, Phase 6; docs/giza-wallet-removal.md). - name: Check where Bennu is still named run: docs/scripts/brand-audit.sh --check + # And that the wallets stay removed (docs/giza-wallet-removal.md, Phase 8). + - name: Check that no wallet has come back + run: docs/scripts/wallet-audit.sh --check + # The assertions that need a compiler. Much heavier than the job above: the composite # build reaches four levels of submodule and cross-compiles secp256k1's C sources, so a # cold run is minutes rather than seconds. Split out so a runner can be pointed at diff --git a/CLAUDE.md b/CLAUDE.md index 21c68b9c..8a9158d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # Conventions for UI code -Eight phases of work brought this app's 43 screens onto Material Design 3; the full +Eight phases of work brought what were then this app's 43 screens onto Material Design 3; the full account, with the numbers and the reasoning, is in [docs/material-design-conformance.md](docs/material-design-conformance.md). What follows is the short version — the rules a new screen has to follow, in the place they are needed, @@ -193,19 +193,33 @@ tween(300) // no Giza is a fork of Bennu ([docs/giza-rebrand.md](docs/giza-rebrand.md)). Name the app Giza everywhere a person reads it, and never name Bennu outside a comment. -The exception is the derivation tags -- `mantra/…` and `bennu/…` -- which look like brand -strings and are hash inputs. Renaming one derives different keys from the same seed, cuts -Giza off from every Bennu peer and moves a group's coins. Leave them spelled as they are. +The derivation tags -- `mantra/…` -- look like brand strings and are hash inputs. Renaming one +derives different keys from the same seed and cuts Giza off from every Bennu peer. Leave them +spelled as they are. ```kotlin -private const val TAG = "bennu/group-lightning/basepoints/v1" // yes, protocol -Text("Open Bennu") // no +private const val TWEAK_TAG = "mantra/shared-key/tweak/v1" // yes, protocol +Text("Open Bennu") // no ``` `./gradlew check` runs `docs/scripts/brand-audit.sh --check`, which fails on Bennu anywhere -in `composeApp`, `iosApp` or `testing` but a comment or a `"bennu/` tag. A merge from Bennu -goes through `docs/scripts/giza-rename.sh` first; the audit catches the strings it cannot -rename. +in `composeApp` or `iosApp` but a comment. There used to be `bennu/…` tags too; every one was +a wallet's, so one appearing now is a wallet coming back, and fails. + +## Giza keeps no wallet + +The wallets Giza inherited from Bennu are gone ([docs/giza-wallet-removal.md](docs/giza-wallet-removal.md)). +Bennu still has them, and a Bennu member can put one to a group Giza is in, so: + +- A proposal Giza cannot check -- a wallet's kind, a transaction, a certificate with wallet + tags -- is *declined*, out loud, through `WalletRefusal`. Never dropped silently, which the + group cannot tell from a phone in a pocket, and never signed. +- The wallet's kind numbers (`RetiredKinds`) stay Bennu's. Nothing new goes on them. +- A recovery phrase is a key backup. `PhraseKeys` derives the npub and the profile id, and + both are pinned in `ForkCompatibilityTest`. + +`./gradlew check` runs `docs/scripts/wallet-audit.sh --check`, which fails on a retired kind in +the app's code, a lightning-kmp import, a file named for a wallet's pieces, or sats in a string. ## Checking your work diff --git a/README.md b/README.md index 74551a69..d0e0138e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,10 @@ # Giza -Giza is a group chat app where the group holds bitcoin together. Groups talk over +Giza is a group chat app where the group can speak as one. Groups talk over [nostr](https://github.com/nostr-protocol/nips) using the Marmot protocol's MLS encryption. A group can also run a key ceremony that gives it a threshold key, which no -single member holds. The group uses that key to sign as one and to keep on-chain and Lightning -wallets that need a quorum of members to spend. +single member holds. The group uses that key to sign as one: what it decides, who it makes a +subgroup of, what it says about itself, each signed by a quorum of its members. Giza keeps no +wallet ([docs/giza-wallet-removal.md](docs/giza-wallet-removal.md)). It is a Kotlin Multiplatform app with a Compose Multiplatform UI, built for Android, iOS and desktop (JVM). @@ -12,11 +13,12 @@ desktop (JVM). Giza is a fork of [Bennu](https://code.sigidli.com/machankura/bennu-kmp), and the two still speak the same protocol. A group can have members on both apps, and a Bennu recovery phrase -restored in Giza opens the same profile and the same wallets. The two install side by side as -separate apps (`mobi.giza.android` and `mobi.giza.ios`), each with its own data. +restored in Giza opens the same profile. The two install side by side as separate apps +(`mobi.giza.android` and `mobi.giza.ios`), each with its own data. -Restoring a phrase in Giza is the same as restoring it on a new device. Once it is restored, stop -using it in Bennu: one Lightning wallet running in two apps at once can lose funds. +Bennu keeps wallets and Giza does not. A Bennu phrase restored in Giza brings back the profile +and nothing else, and a Bennu member who puts a wallet to a group Giza is in sees Giza's members +decline to sign for it. [docs/giza-rebrand.md](docs/giza-rebrand.md) explains what the fork changed, what it left alone and why. @@ -26,20 +28,10 @@ and why. inside a group or one to one. - **A key for the group.** A ChillDKG ceremony, run in the chat, gives the group a threshold key. Members then approve and sign the group's events with FROST, several at a time if needed. -- **An on-chain group wallet.** A taproot wallet held by the group's key. Every member who signs - a spend checks it first. -- **Subgroups and guardians.** A group can create subgroups. A parent can keep a guardian leaf in - a subgroup's wallet, or in a wallet it keeps for one member, and take the coins back after a - delay the parent chooses. -- **A group Lightning wallet.** Channels whose funding key is an Iceberg threshold key. One - elected operator's node runs them, and co-signers check every payment, close and splice. The - group can authorise buying inbound liquidity from its LSP. -- **A wallet of your own.** Each profile can have a personal Lightning and on-chain wallet, built - on [lightning-kmp-app](https://github.com/kngako/lightning-kmp-app), a fork of the shared code - from ACINQ's Phoenix. -- **Profiles.** Create a profile, sign in with an existing nsec (without a wallet), preview one - from an npub, or keep several profiles on one device. A profile can reach the network over Tor - and use its own Electrum server. +- **Subgroups.** A group can create subgroups, each with a key of its own, certified by its + parent's quorum. +- **Profiles.** Create a profile from a recovery phrase, sign in with an existing nsec or a + phrase, preview one from an npub, or keep several profiles on one device. The reasoning behind each of these, including the protocol details and the failure modes, is in [docs/](docs/README.md). @@ -101,8 +93,9 @@ lists the UI conventions the audit enforces. - [composeApp](./composeApp/src) is the shared app. `commonMain` holds most of the code, and `androidMain`, `iosMain` and `jvmMain` hold each platform's own parts. - [iosApp](./iosApp) is the iOS entry point. -- [lightning-kmp-app](https://github.com/kngako/lightning-kmp-app) is the wallet library, a - submodule. +- [lightning-kmp-app](https://github.com/kngako/lightning-kmp-app) is a submodule. Giza takes + only its key and preference storage from it, and the threshold crypto (FROST, ChillDKG) from + the bitcoin-kmp fork it carries. - [docs](docs/README.md) holds the design notes. ## License diff --git a/composeApp/build.gradle.kts b/composeApp/build.gradle.kts index 9e04875f..6ae33003 100644 --- a/composeApp/build.gradle.kts +++ b/composeApp/build.gradle.kts @@ -351,16 +351,17 @@ val m3Audit = tasks.register("m3Audit") { tasks.named("check") { dependsOn(m3Audit) } /** - * Bennu named only in comments and in the `bennu/` derivation tags, which Giza shares with - * it as protocol (docs/giza-rebrand.md, Phase 6). Anything else is a leftover of the fork, - * or a Bennu string that came in with a merge from Bennu, and fails `check` before it ships. + * Bennu named only in comments (docs/giza-rebrand.md, Phase 6). The `bennu/` derivation tags + * that were also allowed were all the wallets', and went with them (docs/giza-wallet-removal.md). + * Anything else is a leftover of the fork, or a Bennu string that came in with a fix taken + * from Bennu, and fails `check` before it ships. * * Reads tracked files with git grep, so it has no inputs gradle could track; it is cheap * enough to run every time. */ val brandAudit = tasks.register("brandAudit") { group = "verification" - description = "Checks that the pre-fork name appears only in comments and derivation tags." + description = "Checks that the pre-fork name appears only in comments." val script = rootProject.layout.projectDirectory.file("docs/scripts/brand-audit.sh").asFile val projectDirectory = rootProject.layout.projectDirectory.asFile @@ -378,13 +379,46 @@ val brandAudit = tasks.register("brandAudit") { } logger.lifecycle(result.standardOutput.asText.get()) if (result.result.get().exitValue != 0) { - throw GradleException("The pre-fork name appears outside a comment or a derivation tag. See the report above.") + throw GradleException("The pre-fork name appears outside a comment. See the report above.") } } } tasks.named("check") { dependsOn(brandAudit) } +/** + * That the wallets stay removed (docs/giza-wallet-removal.md, Phase 8): no retired wallet + * kind in the app's code, no lightning-kmp import, no file named for a wallet's pieces, and + * no amount in sats in the strings. A fix taken from Bennu that brings a wallet back fails + * `check` before it ships, as a Bennu string does under [brandAudit]. + */ +val walletAudit = tasks.register("walletAudit") { + group = "verification" + description = "Checks that no wallet has come back." + + val script = rootProject.layout.projectDirectory.file("docs/scripts/wallet-audit.sh").asFile + val projectDirectory = rootProject.layout.projectDirectory.asFile + + doLast { + val bash = listOf("/bin/bash", "/usr/bin/bash").firstOrNull { File(it).canExecute() } + if (bash == null) { + logger.warn("walletAudit: no bash found, skipping. Run docs/scripts/wallet-audit.sh --check by hand.") + return@doLast + } + val result = providers.exec { + commandLine(bash, script.absolutePath, "--check") + workingDir = projectDirectory + isIgnoreExitValue = true + } + logger.lifecycle(result.standardOutput.asText.get()) + if (result.result.get().exitValue != 0) { + throw GradleException("A wallet has come back. See the report above.") + } + } +} + +tasks.named("check") { dependsOn(walletAudit) } + compose.desktop { application { mainClass = "mobi.giza.desktop.MainKt" diff --git a/composeApp/src/commonMain/kotlin/mobi/giza/compose/nostr/frost/FrostSigningEvents.kt b/composeApp/src/commonMain/kotlin/mobi/giza/compose/nostr/frost/FrostSigningEvents.kt index 575a9dda..5bd8bbe9 100644 --- a/composeApp/src/commonMain/kotlin/mobi/giza/compose/nostr/frost/FrostSigningEvents.kt +++ b/composeApp/src/commonMain/kotlin/mobi/giza/compose/nostr/frost/FrostSigningEvents.kt @@ -1,5 +1,7 @@ package mobi.giza.compose.nostr.frost +import mobi.giza.compose.nostr.RetiredKinds + import com.vitorpamplona.quartz.nip01Core.core.Event import com.vitorpamplona.quartz.nip01Core.core.HexKey import com.vitorpamplona.quartz.nip01Core.core.Kind @@ -108,7 +110,7 @@ object FrostSigningEvents { * cannot tell from a phone in a pocket (docs/giza-wallet-removal.md). The * number is Bennu's and stays retired -- see `RetiredKinds`. */ - val TRANSACTION_PROPOSAL: Kind = 30332 + val TRANSACTION_PROPOSAL: Kind = RetiredKinds.TRANSACTION_PROPOSAL /** Every kind above, for filtering inbound payloads in one check. */ val ALL: Set = setOf( diff --git a/composeApp/src/commonMain/kotlin/mobi/giza/compose/text/ProposedEvent.kt b/composeApp/src/commonMain/kotlin/mobi/giza/compose/text/ProposedEvent.kt index 1896cfe4..8e8c39de 100644 --- a/composeApp/src/commonMain/kotlin/mobi/giza/compose/text/ProposedEvent.kt +++ b/composeApp/src/commonMain/kotlin/mobi/giza/compose/text/ProposedEvent.kt @@ -12,7 +12,7 @@ import mobi.giza.compose.nostr.subgroup.SubgroupBirthCertificateEvent * An event a group is being asked to sign, said in words. * * Shown as the thing rather than as an event: a member deciding whether to sign - * is deciding about a wallet or a subgroup, and "kind 30331" answers a question + * is deciding about a subgroup or a key, and "kind 30329" answers a question * nobody asked. The raw kind stays for anything not recognised, since * refusing to describe an event is better than describing it wrongly. * diff --git a/composeApp/src/commonTest/kotlin/mobi/giza/compose/managers/ForkCompatibilityTest.kt b/composeApp/src/commonTest/kotlin/mobi/giza/compose/managers/ForkCompatibilityTest.kt index 7992e517..1d73bb75 100644 --- a/composeApp/src/commonTest/kotlin/mobi/giza/compose/managers/ForkCompatibilityTest.kt +++ b/composeApp/src/commonTest/kotlin/mobi/giza/compose/managers/ForkCompatibilityTest.kt @@ -11,18 +11,18 @@ import kotlin.test.assertEquals /** * Giza derives what Bennu derives (docs/giza-rebrand.md, Phase 8). * - * The fork kept every derivation tag it found -- `mantra/` and the twelve `bennu/` -- - * because a Bennu peer and a Giza peer have to land on the same keys: in one group, in one - * key ceremony, and for a Bennu seed restored in Giza. Those tags look like brand strings, - * and the next sweep for a name is how they would change. Each one is pinned here, through - * the public function that hashes it, so that a renamed tag fails a test instead of - * silently moving a group's coins. + * The fork kept every derivation tag it found, because a Bennu peer and a Giza peer have + * to land on the same keys: in one group, in one key ceremony, and for a Bennu seed + * restored in Giza. Those tags look like brand strings, and the next sweep for a name is + * how they would change. Each one is pinned here, through the public function that hashes + * it, so that a renamed tag fails a test instead of silently cutting Giza off. + * + * Two are left: `mantra/`, for the DKG host key and the shared-key tweak. The twelve + * `bennu/` tags were all the wallets', and went with them (docs/giza-wallet-removal.md). + * The recovery phrase's own derivation is pinned beside them on NIP-06's test vector. * * The vectors were computed by this tree, whose derivation code is Bennu's at `4e106fb5` * line for line (the fork changed packages and comments in those files, nothing else). - * Some are also pinned elsewhere -- GroupWalletDerivationTest and GuardianDerivationTest - * freeze their own tags -- and this file is the one place that says why every one of - * them must also match Bennu. */ class ForkCompatibilityTest { private fun key(seed: Long): PrivateKey = diff --git a/docs/README.md b/docs/README.md index 02385751..7e217371 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,8 +6,9 @@ silent, or a decision that looked arbitrary and was not. Most of them were written while the app was Bennu, before the fork, and they say so where it matters: a decision taken in Bennu was taken in Bennu. Source paths in them point at -`mobi/giza`. Strings spelled `bennu/…` in their formulas are derivation tags that the fork kept -on purpose ([giza-rebrand.md](./giza-rebrand.md)). +`mobi/giza`. Strings spelled `bennu/…` in their formulas were derivation tags the fork kept on +purpose ([giza-rebrand.md](./giza-rebrand.md)); every one was a wallet's, and they appear only in +the [retired](./retired/) notes now. | document | covers | |---|---| @@ -16,17 +17,6 @@ on purpose ([giza-rebrand.md](./giza-rebrand.md)). | [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 | | [ceremony-creation.md](./ceremony-creation.md) | one place to start a key ceremony — how joining a subgroup's ceremony opened a second one for the parent room, the screen that showed a ceremony and offered to start one in the same button, and the removal of the nip30303 documents, whose kinds collided with the ceremony's, leaving the member chronicle with nothing to carry and nothing to say | | [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 | -| [group-wallet-guardians.md](./group-wallet-guardians.md) | letting an ancestor group spend from a subgroup's wallet through a taproot leaf — why the parent signs the guardian keys into the child's certificate, why every inherited key is derived one step further per child, and why every ancestor waits 12 blocks | -| [subgroup-wallet-policy.md](./subgroup-wallet-policy.md) | the parent deciding, at a subgroup's birth, whether its wallet is guarded or unguarded — why the choice is signed three times, why *unguarded* means no keys in the certificate, why a guarded group's subgroups are all guarded, and why the rule is every honest client's rather than the chain's | -| [member-wallet-delay.md](./member-wallet-delay.md) | a group deciding whether it guards members' wallets, at what delay, and closing again -- why a group-signed event of its own rather than the birth certificate, why no event means not offered, why the request carries the policy it was built under, and why closing never releases a wallet already guarded | -| [guardian-delay.md](./guardian-delay.md) | a parent choosing how long a coin waits before a guardian can take it, from 6 blocks to BIP68's 65,535 -- why each ancestor keeps the delay it chose as its key goes down the tree, what a long delay gives the child, and how a number of blocks is said in time | -| [member-guarded-wallets.md](./member-guarded-wallets.md) | a guarded wallet a group keeps for one member — why the member makes the key and the leaves before asking, why the group signs a certificate of its own kind rather than a birth certificate, and why a member's wallet shows as `@name` and opens their profile | -| [guarded-wallet-forwarding.md](./guarded-wallet-forwarding.md) | telling the groups above about a guarded wallet without anybody pressing *Share* — why it goes upward only, why one device sends at once and the rest catch up, and the two bugs in the button it fixes on the way | -| [member-wallet-guarding-group.md](./member-wallet-guarding-group.md) | naming the group that directly guards each member wallet in an ancestor's list, and gathering a person's wallets under them -- why the direct guardian is the certificate's signer, why the founding name comes before the live one, and why the forwarding notice carries the guardian's birth certificate as a tag | -| [guarded-wallet-funding.md](./guarded-wallet-funding.md) | a group paying into a descendant's guarded wallet — why the address is the first unreserved one from `current + 2`, why the claim rides in the PSBT output's derivation and every signer rederives it, and how the guarded wallet row makes room for *Fund* beside *Spend* | -| [group-wallet-addresses.md](./group-wallet-addresses.md) | listing the group wallet's receive addresses as Phoenix lists its swap-in ones — why the list stops at the current address plus two, why a paid address past that still shows, and why a used address can be copied but never shown as a QR code | | [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 | @@ -35,18 +25,13 @@ on purpose ([giza-rebrand.md](./giza-rebrand.md)). | [long-running-sync.md](./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](./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](./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 | -| [standalone-electrum.md](./standalone-electrum.md) | a profile with no node watching the chain — why only a nodeless profile gets its own client, why it connects at start rather than on first look, and why Tor on still means no clearnet fallback | | [npub-sign-in.md](./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](./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](./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](./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](./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 | -| [group-lightning-wallet.md](./group-lightning-wallet.md) | a Lightning wallet whose channels the group holds with an Iceberg threshold key, run by one elected operator. Covers why Iceberg needs its own ceremony and a DKG of its own, why every payment needs `2t-1` devices to answer, the echo rule that keeps a hostile operator from reusing a nonce label, and why a closing channel must pay the group's key rather than the node's | -| [group-lightning-transcript.md](./group-lightning-transcript.md) | the group Lightning wallet in a room's chat, phased — why every Lightning kind but the three the group signs became a raw-JSON bubble, the standing notice the Iceberg ceremony never got, and which of the operator's messages earn a line and which never should | -| [group-lightning-liquidity.md](./group-lightning-liquidity.md) | buying inbound liquidity for the group's Lightning wallet as Phoenix does, phased — why a purchase is a splice every co-signer refuses today, why the group decides it with an authorisation rather than the operator with a tap, the same group key at every funding index, and the rule that lets a device that missed a splice follow the channel to its new output | -| [lightning/README.md](./lightning/README.md) | the remediation plans for the review of the group Lightning wallet — seven findings, one phased plan each, and the order to build them in | | [marmot-v2.md](./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, nine phases from reading both profiles to publishing before applying, and the one fork the library cannot yet settle | -| [giza-wallet-removal.md](./giza-wallet-removal.md) | taking every wallet out of Giza, phased and not yet built. Covers why a Giza member declines a Bennu peer's wallet proposal instead of ignoring or signing it, why the wallet's kinds are retired rather than freed, why a recovery phrase stays as a key backup that has to derive the same npub and id byte for byte, and why the threshold crypto keeps the build tied to the wallet library until the last phase | +| [giza-wallet-removal.md](./giza-wallet-removal.md) | taking every wallet out of Giza, phased and built but for moving off the wallet library (7b). Covers why a Giza member declines a Bennu peer's wallet proposal instead of ignoring or signing it, why the wallet's kinds are retired rather than freed, why a recovery phrase stays as a key backup that has to derive the same npub and id byte for byte, and why the threshold crypto keeps the build tied to the wallet library until the last phase | | [giza-rebrand.md](./giza-rebrand.md) | forking Bennu as Giza under `mobi.giza` — what carries the name, what must not be renamed and why, why the desktop data directory changes first, and how the fork keeps merging from Bennu | Start with the ceremony if you are new to this area; the Marmot notes all assume it. @@ -65,44 +50,6 @@ 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 group-wallet-addresses note is a phased plan that has been built, and is the -group-chain-wallet note's Phase 5 taken one screen further: read that note's -Phases 4 and 5 first, and its own table of where the build chose differently -before the code. -The group-wallet-guardians note is a phased plan that has been built; it assumes the subgroups and group-chain-wallet notes, and changes one sentence in -each. -The member-guarded-wallets note is a phased plan that has been built. It -takes the guardians note's derivation unchanged and gives the key path to one -person: read that note and the policy note's D2 first, then this note's table -of why a birth certificate will not do, its Phase 0, and its table of where the -build chose differently before the code. -The member-wallet-guarding-group note is a phased plan that has been built, -and changes what the member-guarded-wallets note's Phases 10 and 11 draw, not -what they verify: read those two phases first. -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 guardian-delay note is a phased plan that has been built. It changes -the guardians note's *Why 12, and why for everybody* and reuses the -wallet-policy note's plumbing one field further: read both, then its table of -what is already per leaf, then its Phase 0, and its table of where the build -chose differently before the code. -The member-wallet-delay note is a phased plan that has been built. It -reads as the guardian-delay note's last build-table row answered: read the -member-wallets note and the guardian-delay note first, then its table of where -the delay should live, then its Phase 0, and its table of where the build chose -differently before the code. -The guarded-wallet-forwarding note is a phased plan that has been built. -It changes who sends a 30333 notice and when, and no format: read the guardians -note's *How an ancestor finds the coins* and the member-guarded-wallets note's -Phase 10 first, then its two bugs, its Phase 0, and its table of where the build -chose differently before the code. -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, 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. @@ -125,11 +72,6 @@ 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 group chain wallet note is a phased plan that has been built. It assumes -both shared-key notes and the batch-signing note, and reads as the derivation -note's one rule with money behind it; read its derivation section before any -phase, since every phase after the first is built on that path, and its table of -where the build chose differently before any of the code. The Marmot v2 note is a phased plan that has 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 @@ -138,34 +80,23 @@ of nine rules and its two constraints before any phase, and its table of where t build chose differently before any of the code -- its first row, that a room's profile picks its pipeline, is the shape of everything that follows, and its last is the one fork the library cannot yet settle. -The group send-an-amount note is a phased plan that has been built, and reads -as the third gate of the group chain wallet note's Phase 10: why that gate -could not lift as written, and what stands in for it now that it is gone. Read -its list of what the gated code got wrong before its phases. The ceremony-creation note is a phased plan that has been built. It reads as the subgroups note's Phase 10 followed through to the screens: read it after that phase, and its table of findings before any phase. Its second half removes the nip30303 documents and leaves the member chronicle built but carrying no kinds, so read it before building on the chronicle note. -The group Lightning wallet note is a phased plan that has been built, except -for splicing out, and run end to end on regtest. It assumes the group chain -wallet note and the ceremony note, and reads as the lightning-kmp fork's -`FEATURE-PARITY.md` taken past its "out of scope" line: read its eight -constraints and its decision table before any phase, its trust table before -arguing with either, and its two tables of what the build found before -changing anything it describes. +The wallet-removal note is a phased plan that has been built but for its Phase 7b. +It is how Giza came to keep no wallet: read its constraints and its decisions +before any phase, and its table of where the build chose differently before the +code. It reads as the rebrand note's D1 and D2 tested: one network shared with +Bennu, whose members still bring wallets into rooms Giza is in. -The group Lightning liquidity note is a phased plan that has been built, but for -its Phase 9, and is on, on mainnet, by decision ahead of its own mainnet check. -It is the group Lightning wallet note's check 8 built for one kind of splice: -read that note's D6, Phase 9 and Phase 13 first, and the lightning -remediation README's step 2, which this plan waits for, then its six -constraints and eight decisions before any phase, and its table of what -Phase 0 found against eclair before the code: the minute eclair allows a whole -splice is what every group signature in it has to fit inside. +## Retired -The standalone-electrum note is a phased plan that has been built, and is the -group chain wallet note's *An identity without a node* answered: read that -paragraph and the nsec sign-in note's *The constraint* first, then its seven -decisions, and its table of where the build chose differently before the code. +[retired/](./retired/) holds the notes on Bennu's wallets -- the group's on-chain +wallet, its guardians and the subgroup wallet policy, members' guarded wallets, the +standalone Electrum client and the group Lightning wallet with its remediation +plans. Giza removed all of them ([giza-wallet-removal.md](./giza-wallet-removal.md)). +They are kept because they are the only account of what a Bennu member in a shared +group is doing, and of the kinds Giza now declines. diff --git a/docs/frost-batch-signing.md b/docs/frost-batch-signing.md index e92556b2..ea38b68c 100644 --- a/docs/frost-batch-signing.md +++ b/docs/frost-batch-signing.md @@ -1,5 +1,7 @@ # Batch signing with FROST +> **Since [giza-wallet-removal.md](./giza-wallet-removal.md):** The transaction half of this note -- a spend as a batch of inputs -- is gone from Giza: a transaction proposal is filed declined on arrival, unread, and only events are signed. + How to have a group sign several events in one ceremony instead of one at a time, phased, with the cryptographic constraint that shapes every phase stated first. diff --git a/docs/giza-rebrand.md b/docs/giza-rebrand.md index 83b670da..f01eeaa8 100644 --- a/docs/giza-rebrand.md +++ b/docs/giza-rebrand.md @@ -1,5 +1,7 @@ # Forking Bennu as Giza +> **Since [giza-wallet-removal.md](./giza-wallet-removal.md):** Constraint 2's danger -- one seed's node running in two apps -- no longer applies to Giza, which runs no node. The `bennu/` tags this note keeps were all the wallets', and went with them. D1's merging is recommended to become cherry-picking (W1 there), and Phase 8's mixed group wallet check is replaced by that note's Phase 9. + Giza is a fork of Bennu under a new name and a new reverse-DNS root, `mobi.giza`. The Kotlin packages move from `com.machankura.bennu.{compose,android,desktop}` to `mobi.giza.{compose,android,desktop}`. The Android application id becomes `mobi.giza.android` @@ -19,7 +21,7 @@ spellings throughout: it describes the tree as it was before the fork, and - `b75d4b42`, *Rebrand Curare to Bennu under com.machankura.bennu*. It is the precedent: 975 files, a package move, and a list of names it left alone on purpose. Every name on that list stays alone here too, for the same reasons. -- [lightning/restored-device-marks.md](./lightning/restored-device-marks.md). Moving from Bennu +- [lightning/restored-device-marks.md](./retired/lightning/restored-device-marks.md). Moving from Bennu to Giza is a seed restore on a new device, and that document describes what such a restore costs. - [material-design-conformance.md](./material-design-conformance.md). The audit it enforces diff --git a/docs/giza-wallet-removal.md b/docs/giza-wallet-removal.md index a7871636..31e88e0a 100644 --- a/docs/giza-wallet-removal.md +++ b/docs/giza-wallet-removal.md @@ -27,7 +27,8 @@ written against `caf1fb18`. | 5 | built: `MIGRATION_35_36` drops the sixteen tables, the three columns, the wallets' 32 line types and every signing session over a transaction or a sweep, with their items and messages; `schemas/…/36.json` is committed. The line-type constants and the transcript's arms for them go with the rows. `RemoveWalletsMigrationJvmTest` checks the shape against Room's v36 and the rows kept and deleted. `jvmTest` 1,150 run, 0 failed | | 6 | built. `PhraseKeys` derives a phrase's nostr key and profile id with bitcoin-kmp's `DeterministicWallet` and lands on Phase 0's pins unchanged; `StoredIdentity` and `IdentityWriter` use it. No node starts for any profile: `Identity.business`, `startupNode`, the start-state machine, `platformStartupLogic`, `schedulePlatformLogic`, `updateBusinessActiveInUI` and `stopPlatformBusiness` go, with `LightningApplication`, `BusinessManager.initialize`, the NFC hooks and `POST_NOTIFICATIONS`. Copy that promised funds is reworded, and the switcher's *Wallet* badge says *Recovery phrase*. Android compiles; **the two iOS actuals were edited without an iOS build**. `jvmTest` 1,149 run, 0 failed but the `IdentitySwitchJvmTest` timeout seen in Phase 3 (passes alone) | | 7a | built: **`composeApp` imports nothing from lightning-kmp.** W3: a Lightning invoice in a note is a card that opens a `lightning:` link in the device's own wallet app, undecoded; the never-wired pay and zap hooks go. `Lightning.randomBytes` becomes quartz's `RandomInstance`, the tests' `LocalKeyManager` becomes `PhraseKeys`, and `NodeParamsManager.chain` becomes `PROFILE_CHAIN`, the constant mainnet that names every profile's preference files. `jvmTest` 1,149 run, 0 failed | -| 7b | **not built.** Vendoring the storage classes into `composeApp` and re-pointing the build at the bitcoin-kmp fork. It is a rewrite rather than a move -- `UserPrefs` is built on lightning-kmp types, `PhoenixGlobal` builds a node's managers and an app database, the keystore has an actual per platform -- and a wrong preference key or keychain detail silently loses people's profiles. Its own checks are an iOS build and an Android install over a Phase 6 build with the same profiles opening, neither of which this tree can run. Left for its own branch, as the plan already said of this phase | Paths below are under +| 7b | **not built.** Vendoring the storage classes into `composeApp` and re-pointing the build at the bitcoin-kmp fork. It is a rewrite rather than a move -- `UserPrefs` is built on lightning-kmp types, `PhoenixGlobal` builds a node's managers and an app database, the keystore has an actual per platform -- and a wrong preference key or keychain detail silently loses people's profiles. Its own checks are an iOS build and an Android install over a Phase 6 build with the same profiles opening, neither of which this tree can run. Left for its own branch, as the plan already said of this phase | +| 8 | built. The 23 wallet notes are in `docs/retired/`, each with a banner, every link between notes rewritten and checked; the index lists them as one *Retired* paragraph; seven kept notes carry a *Since* line. README and `CLAUDE.md` describe a Giza with no wallet. `brand-audit.sh` loses its `"bennu/` exception, and `wallet-audit.sh --check` runs in `check` and in CI. `jvmTest` 1,149 run, 0 failed | Paths below are under `composeApp/src/commonMain/kotlin/mobi/giza/compose/` unless they say otherwise. Line numbers were right at that commit; confirm them with a grep before using them. @@ -61,6 +62,8 @@ Where the build chose differently from the phases as written: | `WalletAttached` gives way: forgetting a phrase profile removes its `seed.dat` entry too, behind a stronger confirmation | **not built.** The refusal stays, renamed `PhraseAttached` for what it now means: the phrase would derive the key again. No screen offers to forget a phrase profile, so making it possible is new UI rather than removal, and is left as a follow-up | | `KeyRecoveryScreen`'s cloud backup and emergency kit placeholders go, as wallet backups | they stay. They are placeholders for backing up the *profile*; only the copy under them promised coins, and that is reworded | | the library keeps deriving nothing after Phase 6 | `SeedManager.loadAndDecrypt` in the library still builds a `LocalKeyManager` to name each seed's id while listing. It lands on the same id; Phase 7, which moves `SeedManager` into the app, moves it onto `PhraseKeys` | +| the wallet guard bans files named `*Wallet*`, `*Lightning*`, `*Iceberg*` or `*Guardian*`, but for `widgets/wallet/` and `WalletId` | it bans the wallets' own stems -- `GroupWallet`, `GroupLightning`, `Iceberg`, `Guardian`, `MemberWallet`, `GroupSpend`, `GroupTransaction`, `StandaloneElectrum` and the rest. A blanket `*Wallet*` would also catch the `SovereignWallet*` profile startup, `WalletRefusal` and `RemoveWalletsMigration`, which are about declining one | +| the screen count in `CLAUDE.md` and `material-design-conformance.md` is updated | marked as a count *then* in `CLAUDE.md`; the conformance note is a dated account, and its numbers stay as they were measured | | a retired kind's arm becomes one line or none | the arms the wallet kinds already have keep writing their own lines until their phases delete them; the fallback catches each kind as its arm goes. `ProtocolKindDispatchJvmTest` asserts no retired kind is ever `unsupported`, at every phase | ## What the wallets are, measured diff --git a/docs/jvm-target.md b/docs/jvm-target.md index 8cb9a852..ef9a2ab5 100644 --- a/docs/jvm-target.md +++ b/docs/jvm-target.md @@ -1,5 +1,7 @@ # Bringing up the JVM target +> **Since [giza-wallet-removal.md](./giza-wallet-removal.md):** The Lightning node this note ported to the jvm no longer runs in Giza. The key store it describes still holds every profile. + What it would actually take to build Curare for desktop, phased, with the blocking work separated from the mechanical work. diff --git a/docs/multiple-profiles.md b/docs/multiple-profiles.md index 81825a75..e11aaab1 100644 --- a/docs/multiple-profiles.md +++ b/docs/multiple-profiles.md @@ -1,5 +1,7 @@ # More than one profile on a device +> **Since [giza-wallet-removal.md](./giza-wallet-removal.md):** No profile has a wallet attached any more: a phrase profile is a key with a recovery phrase behind it, a switch has no node to stop, and the refusal to forget one is now `PhraseAttached`. + How a user holds several profiles on one device, moves between them, and adds another by signing in or by creating one — why a profile is a credential and a wallet is a thing attached to one, and why the switch has to be a restart of the diff --git a/docs/nsec-sign-in.md b/docs/nsec-sign-in.md index d05fb781..5b4cd3e8 100644 --- a/docs/nsec-sign-in.md +++ b/docs/nsec-sign-in.md @@ -1,5 +1,7 @@ # Signing in with an nsec +> **Since [giza-wallet-removal.md](./giza-wallet-removal.md):** No profile has a node behind it any more, and a recovery phrase derives its key through `PhraseKeys` rather than the node's key manager. Where this note says a seed is a wallet, read it as history. + How a user who already has a nostr key gets it onto this device, why that key can never have a wallet behind it, and the ten call sites that make the whole thing smaller than it looks. @@ -944,7 +946,7 @@ found. up and every recovery screen in this plan has to say which. Its own plan. *Watching* the chain without a wallet of its own is built: an nsec profile sees its groups' balances on an Electrum client of its own — - [standalone-electrum.md](./standalone-electrum.md). + [standalone-electrum.md](./retired/standalone-electrum.md). - **Starting the node lazily for mnemonic identities.** Recommended, separable, and made small by Phase 1. See [The one decision](#the-one-decision-to-make-first). - **`npub` sign-in (read only).** The skeleton parses it, and `signInToProfile` diff --git a/docs/group-chain-wallet.md b/docs/retired/group-chain-wallet.md similarity index 98% rename from docs/group-chain-wallet.md rename to docs/retired/group-chain-wallet.md index 9ebfcefd..52f704dd 100644 --- a/docs/group-chain-wallet.md +++ b/docs/retired/group-chain-wallet.md @@ -1,5 +1,7 @@ # A group chain wallet +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + An on-chain bitcoin wallet that belongs to a group: its addresses are derived from the group's ChillDKG threshold key, its spends are signed by the FROST signing ceremony the app already runs, and nobody — not the coordinator, not any member, @@ -8,9 +10,9 @@ not any `t - 1` of them — can move a coin alone. It is modelled on Phoenix's channels, and this note says where it follows that wallet and the three places it cannot. -Read [shared-key-derivation.md](./shared-key-derivation.md) first, for the rule a +Read [shared-key-derivation.md](../shared-key-derivation.md) first, for the rule a wallet makes more expensive to break, and -[frost-batch-signing.md](./frost-batch-signing.md) second, because a transaction +[frost-batch-signing.md](../frost-batch-signing.md) second, because a transaction with `k` inputs is a batch of `k` and that note's nonce rule is the one this plan is built around too. @@ -88,7 +90,7 @@ Three things cannot carry over, and each is a constraint rather than a choice: output a FROST key can spend is a taproot one. 2. **`m/84'/…` is out, and so is `m/86'/…`.** Hardened derivation needs the parent *private* key, which exists only as shares — see - [Why not BIP32](./shared-key-derivation.md#why-not-bip32). No member and no + [Why not BIP32](../shared-key-derivation.md#why-not-bip32). No member and no quorum short of reconstructing the secret can walk a `'`. 3. **Signing is not a function call.** `FinalWallet.signTransaction` returns a signed transaction synchronously. Here a spend is a proposal that a quorum of @@ -133,7 +135,7 @@ has one share. Do what those helpers do, by hand, through `TweakCache` and | a member can check, alone, that no script path is hidden in the address | otherwise one member can propose an address with a back door and nobody can tell | | addresses rotate, and change is told apart from payment | address reuse is a privacy leak for a treasury, and a signer has to see where the money goes | | a watch-only tool can follow the wallet | a treasurer, an auditor or a member's Sparrow should not need Giza to see the balance | -| everything is a pure function of what every member already holds | [Rederive rather than persist](./shared-key-derivation.md#what-it-produces) | +| everything is a pure function of what every member already holds | [Rederive rather than persist](../shared-key-derivation.md#what-it-produces) | ### The path @@ -343,7 +345,7 @@ cache. `cache.tweakedPublicKey == Q` and `Bitcoin.computeBIP86Address(K_ci, chainHash) == address` are `require`s, not tests, because they are the only things standing between a parity mistake in the cache and a wallet whose signatures do not verify — the failure the -[derivation note](./shared-key-derivation.md#what-it-produces) calls "tedious to +[derivation note](../shared-key-derivation.md#what-it-produces) calls "tedious to diagnose from the outside, because the signature is valid — just not for the key you expected". Here it is worse: the coins are already at `Q`. diff --git a/docs/group-lightning-liquidity.md b/docs/retired/group-lightning-liquidity.md similarity index 99% rename from docs/group-lightning-liquidity.md rename to docs/retired/group-lightning-liquidity.md index 194e3b38..1d50aaaa 100644 --- a/docs/group-lightning-liquidity.md +++ b/docs/retired/group-lightning-liquidity.md @@ -1,5 +1,7 @@ # Requesting inbound liquidity for the group's Lightning wallet +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Phoenix lets its owner buy inbound liquidity ahead of need: pick an amount, see the fee, confirm, and the LSP splices that much of its own money into the channel. This plan gives the group's Lightning wallet the same button. The difference is who presses it. In Phoenix one diff --git a/docs/group-lightning-transcript.md b/docs/retired/group-lightning-transcript.md similarity index 84% rename from docs/group-lightning-transcript.md rename to docs/retired/group-lightning-transcript.md index 8f10df16..2aaa6069 100644 --- a/docs/group-lightning-transcript.md +++ b/docs/retired/group-lightning-transcript.md @@ -1,5 +1,7 @@ # The group Lightning wallet in the chat +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + How the group Lightning wallet comes to read, in a room's transcript, the way every other piece of group business already does: its key ceremony as a ladder of lines and a standing ask above the composer, and the operator's traffic as @@ -40,9 +42,9 @@ reached the recipient with the fee beside it. A look at a room on a device has n Read [group-lightning-wallet.md](./group-lightning-wallet.md) for the wallet itself and -[shared-key-ceremony.md](./shared-key-ceremony.md) for the transcript conventions +[shared-key-ceremony.md](../shared-key-ceremony.md) for the transcript conventions this plan holds the Lightning wallet to. The UI rules in -[CLAUDE.md](../CLAUDE.md) apply to every phase. +[CLAUDE.md](../../CLAUDE.md) apply to every phase. The headline: **the Lightning wallet's ceremony lines already exist and already render. What a member sees instead is raw JSON, because fourteen of the wallet's @@ -57,20 +59,20 @@ the standing notice above the composer, and lines for what the operator says.** | fact | where | what it means here | |---|---|---| -| A Marmot inner event is held back from the transcript only if its kind is in `DkgRitualEvents.ALL` or `FrostSigningEvents.ALL` | [ChatMessage.kt:946](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) `isProtocolMessage` | `GroupLightningEvents` is in neither, so every Lightning kind goes on to `applyInnerEvent` | -| `applyInnerEvent` handles the three group-signed kinds (30355, 30356, 30363) and sends everything else to `unsupported()`, a bubble of `event.toJson()` | [ChatMessage.kt:1224, 1530](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) | the ceremony's 30350–30354, the co-signing 30358–30361 and the wallet traffic 30357, 30362, 30364–30366 each leave a raw-JSON bubble, attributed to whoever sent it | -| The same events are *also* acted on, after the line is written | [NostrDao.kt:1585–1648](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/dao/NostrDao.kt) | the managers already work; only the transcript is wrong. A ceremony therefore shows its readable lines *and* a JSON bubble beside each | -| `IcebergRitualManager` writes `TYPE_ICEBERG_*` lines, request lines included, and `ChatTranscript` renders them as `RitualNotice`s that open `IcebergCeremonyScreen` | [IcebergRitualManager.kt:464–506](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [ChatTranscript.kt:285](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | the readable half of the ceremony is built; it is buried, not missing | -| The co-signing traffic is high-volume: a nonce batch per pool window per member, an echo per member per signing request, a share per member per label | [GroupIcebergTransport.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupIcebergTransport.kt), [GroupLightningCoSigner.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupLightningCoSigner.kt) | a room with a running node fills with JSON faster than anyone talks in it, and the room list's preview reads the newest row's `content` (`ChatRoomDao`), so it shows JSON too | -| `ProtocolKindDispatchJvmTest` asserts "no chat line" for `DkgRitualEvents.ALL` and `FrostSigningEvents.ALL` only | [ProtocolKindDispatchJvmTest.kt:120, 169](../composeApp/src/jvmTest/kotlin/mobi/giza/compose/database/model/ProtocolKindDispatchJvmTest.kt) | nothing caught this. The third family needs the same test | -| `MIGRATION_26_27` deleted the `unsupported` rows written for the ChillDKG kinds, found by the kind of the inner event behind them | [RemoveDocumentsMigration.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/migrations/RemoveDocumentsMigration.kt) | the exact precedent for cleaning rooms that already hold the bubbles. The schema is at 32 | -| The standing notice above the composer is fed by `ceremoniesAwaitingYou`, which observes `dkgRepository` only, and its card always calls `onOpenSharedKey` | [ChatMessageListViewModel.kt:112–140, 267–291](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/view/model/ChatMessageListViewModel.kt), [ChatTranscript.kt:203, 613](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | an Iceberg gate never reaches it. The member has to scroll to the request line, which the JSON is burying | -| `IcebergRitualManager.pendingApproval` and `GroupLightningRepository.pendingApproval` / `observeCeremonies` / `hasUnusedKey` exist | [IcebergRitualManager.kt:402](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [GroupLightningRepository.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/repository/GroupLightningRepository.kt) | everything the notice needs is already exposed, the same way the ChillDKG notice reads `pendingApproval` | -| No Lightning manager writes a chat line. A co-signer's refusal and an operator's equivocation are `logger` calls | [GroupLightningCoSigner.kt:193, 232](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupLightningCoSigner.kt) | the wallet doc promises both as transcript lines ("A person only sees a refusal, as a transcript line"); neither is | -| The operator line says "The group chose who runs its Lightning wallet" without saying who | [ChatMessage.kt:1464–1483](../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) | the one fact the line exists for is missing. The member-wallet lines already name people with `memberName` | -| A ceremony abandoned by somebody else is recorded as `"Abandoned by ${sender.take(8)}: ${content}"`, and a local fault as the exception's message; the screen shows `failureReason` verbatim | [IcebergRitualManager.kt:280, 365](../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [IcebergCeremonyScreen.kt:200](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/IcebergCeremonyScreen.kt) | a key prefix and an exception string where ChillDKG shows a name and a sentence | -| The Iceberg gates are an inline card on the ceremony screen; ChillDKG's each have a screen of their own on `DkgApprovalScaffold` | [IcebergCeremonyScreen.kt:210–233](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/IcebergCeremonyScreen.kt), [DkgApprovalScaffold.kt](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/DkgApprovalScaffold.kt) | a difference in shape, not a defect. Decision D5 | -| `RitualNotice`'s chevron says "Open the shared key ceremony" for every family it draws, signing lines and Lightning lines included | [ChatTranscript.kt:972](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | a screen reader is told the wrong destination | +| A Marmot inner event is held back from the transcript only if its kind is in `DkgRitualEvents.ALL` or `FrostSigningEvents.ALL` | [ChatMessage.kt:946](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) `isProtocolMessage` | `GroupLightningEvents` is in neither, so every Lightning kind goes on to `applyInnerEvent` | +| `applyInnerEvent` handles the three group-signed kinds (30355, 30356, 30363) and sends everything else to `unsupported()`, a bubble of `event.toJson()` | [ChatMessage.kt:1224, 1530](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) | the ceremony's 30350–30354, the co-signing 30358–30361 and the wallet traffic 30357, 30362, 30364–30366 each leave a raw-JSON bubble, attributed to whoever sent it | +| The same events are *also* acted on, after the line is written | [NostrDao.kt:1585–1648](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/dao/NostrDao.kt) | the managers already work; only the transcript is wrong. A ceremony therefore shows its readable lines *and* a JSON bubble beside each | +| `IcebergRitualManager` writes `TYPE_ICEBERG_*` lines, request lines included, and `ChatTranscript` renders them as `RitualNotice`s that open `IcebergCeremonyScreen` | [IcebergRitualManager.kt:464–506](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [ChatTranscript.kt:285](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | the readable half of the ceremony is built; it is buried, not missing | +| The co-signing traffic is high-volume: a nonce batch per pool window per member, an echo per member per signing request, a share per member per label | [GroupIcebergTransport.kt](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupIcebergTransport.kt), [GroupLightningCoSigner.kt](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupLightningCoSigner.kt) | a room with a running node fills with JSON faster than anyone talks in it, and the room list's preview reads the newest row's `content` (`ChatRoomDao`), so it shows JSON too | +| `ProtocolKindDispatchJvmTest` asserts "no chat line" for `DkgRitualEvents.ALL` and `FrostSigningEvents.ALL` only | [ProtocolKindDispatchJvmTest.kt:120, 169](../../composeApp/src/jvmTest/kotlin/mobi/giza/compose/database/model/ProtocolKindDispatchJvmTest.kt) | nothing caught this. The third family needs the same test | +| `MIGRATION_26_27` deleted the `unsupported` rows written for the ChillDKG kinds, found by the kind of the inner event behind them | [RemoveDocumentsMigration.kt](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/migrations/RemoveDocumentsMigration.kt) | the exact precedent for cleaning rooms that already hold the bubbles. The schema is at 32 | +| The standing notice above the composer is fed by `ceremoniesAwaitingYou`, which observes `dkgRepository` only, and its card always calls `onOpenSharedKey` | [ChatMessageListViewModel.kt:112–140, 267–291](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/view/model/ChatMessageListViewModel.kt), [ChatTranscript.kt:203, 613](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | an Iceberg gate never reaches it. The member has to scroll to the request line, which the JSON is burying | +| `IcebergRitualManager.pendingApproval` and `GroupLightningRepository.pendingApproval` / `observeCeremonies` / `hasUnusedKey` exist | [IcebergRitualManager.kt:402](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [GroupLightningRepository.kt](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/repository/GroupLightningRepository.kt) | everything the notice needs is already exposed, the same way the ChillDKG notice reads `pendingApproval` | +| No Lightning manager writes a chat line. A co-signer's refusal and an operator's equivocation are `logger` calls | [GroupLightningCoSigner.kt:193, 232](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/GroupLightningCoSigner.kt) | the wallet doc promises both as transcript lines ("A person only sees a refusal, as a transcript line"); neither is | +| The operator line says "The group chose who runs its Lightning wallet" without saying who | [ChatMessage.kt:1464–1483](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/database/model/ChatMessage.kt) | the one fact the line exists for is missing. The member-wallet lines already name people with `memberName` | +| A ceremony abandoned by somebody else is recorded as `"Abandoned by ${sender.take(8)}: ${content}"`, and a local fault as the exception's message; the screen shows `failureReason` verbatim | [IcebergRitualManager.kt:280, 365](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/managers/IcebergRitualManager.kt), [IcebergCeremonyScreen.kt:200](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/IcebergCeremonyScreen.kt) | a key prefix and an exception string where ChillDKG shows a name and a sentence | +| The Iceberg gates are an inline card on the ceremony screen; ChillDKG's each have a screen of their own on `DkgApprovalScaffold` | [IcebergCeremonyScreen.kt:210–233](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/IcebergCeremonyScreen.kt), [DkgApprovalScaffold.kt](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/DkgApprovalScaffold.kt) | a difference in shape, not a defect. Decision D5 | +| `RitualNotice`'s chevron says "Open the shared key ceremony" for every family it draws, signing lines and Lightning lines included | [ChatTranscript.kt:972](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/widgets/chat/ChatTranscript.kt) | a screen reader is told the wrong destination | ## Decisions diff --git a/docs/group-lightning-wallet.md b/docs/retired/group-lightning-wallet.md similarity index 99% rename from docs/group-lightning-wallet.md rename to docs/retired/group-lightning-wallet.md index 8bd697c5..28efdad3 100644 --- a/docs/group-lightning-wallet.md +++ b/docs/retired/group-lightning-wallet.md @@ -1,5 +1,7 @@ # A group Lightning wallet +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + A Lightning wallet that belongs to a group. Its channels' funding key is an Iceberg threshold key, which no member, no operator and no `t - 1` of them hold alone. One member at a time, the **operator**, runs the lightning-kmp node on @@ -14,7 +16,7 @@ first: - [group-chain-wallet.md](./group-chain-wallet.md): every phase here assumes the onchain wallet, its derivation and its spend checks. -- [shared-key-ceremony.md](./shared-key-ceremony.md): the Iceberg ceremony in +- [shared-key-ceremony.md](../shared-key-ceremony.md): the Iceberg ceremony in Phase 5 is modelled on it. - `lightning-kmp-app/experimental/lightning-kmp/FEATURE-PARITY.md`: how the fork put Iceberg behind lightning-kmp's `FundingSigner` seam, and what that port diff --git a/docs/group-send-an-amount.md b/docs/retired/group-send-an-amount.md similarity index 98% rename from docs/group-send-an-amount.md rename to docs/retired/group-send-an-amount.md index 7ddec67e..85f7d679 100644 --- a/docs/group-send-an-amount.md +++ b/docs/retired/group-send-an-amount.md @@ -1,5 +1,7 @@ # Sending an amount from the group's wallet +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + *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 @@ -365,7 +367,7 @@ building. Each step, and the automated test that comes closest: | 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](./README.md) with the plan. +[README.md](../README.md) with the plan. --- diff --git a/docs/group-wallet-addresses.md b/docs/retired/group-wallet-addresses.md similarity index 98% rename from docs/group-wallet-addresses.md rename to docs/retired/group-wallet-addresses.md index 433d21ad..5eac9d71 100644 --- a/docs/group-wallet-addresses.md +++ b/docs/retired/group-wallet-addresses.md @@ -1,5 +1,7 @@ # The group wallet's addresses +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + A screen that lists the group wallet's receive addresses: every one that has been paid, the one the wallet is handing out now, and the next two after it. It is modelled on Phoenix's *Swap-in addresses* screen, and this note says where it @@ -357,7 +359,7 @@ the same function as Phase 1's, over `change` and with the bound set to - This note's status line becomes **Built**, with a table of where the build chose differently, as every built plan here has. -- A row in [README.md](./README.md)'s table, and a sentence in its reading order +- A row in [README.md](../README.md)'s table, and a sentence in its reading order that places it after the group-chain-wallet note. - In [group-chain-wallet.md](./group-chain-wallet.md)'s Phase 4, the sentence "two members can show the same next address" gains a pointer here: that is the diff --git a/docs/group-wallet-guardians.md b/docs/retired/group-wallet-guardians.md similarity index 97% rename from docs/group-wallet-guardians.md rename to docs/retired/group-wallet-guardians.md index e869537d..2ff9a55e 100644 --- a/docs/group-wallet-guardians.md +++ b/docs/retired/group-wallet-guardians.md @@ -1,12 +1,14 @@ # Guardians: an ancestor group's leaf in a subgroup's wallet +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + A subgroup's onchain wallet can carry its ancestry in its addresses: one taproot leaf per ancestor group, each spendable by that ancestor's quorum, so the root of a hierarchy can move the coins of any group beneath it. The child's own spends stay on the key path, look like any single-key taproot spend, and never reveal that the tree exists. -Read [subgroups.md](./subgroups.md) and [group-chain-wallet.md](./group-chain-wallet.md) +Read [subgroups.md](../subgroups.md) and [group-chain-wallet.md](./group-chain-wallet.md) first. This builds on the birth certificate from the first and the account derivation from the second, and it changes one sentence in each. @@ -50,7 +52,7 @@ under plain tweaks of its own threshold key. ## What this reverses, and whose choice it is -[subgroups.md](./subgroups.md#what-this-does-not-do) says: +[subgroups.md](../subgroups.md#what-this-does-not-do) says: > A subgroup cannot sign for its parent, and the parent cannot sign for it. […] > If delegation is ever wanted it is a different mechanism and it should not be @@ -285,7 +287,7 @@ exactly the certificate's entries with the delay this build writes, rebuilds the tree, and compares the descriptors. The statement stays *a record that the group agreed, not a source of keys*. Carrying the certificate makes it self-contained: a member welcomed into the child after its birth, who holds no key state, can -still check every address — the gap [subgroups.md](./subgroups.md#what-this-does-not-do) +still check every address — the gap [subgroups.md](../subgroups.md#what-this-does-not-do) names, closed for the wallet. Three rules, each closing a way to lose coins: @@ -483,7 +485,7 @@ a guarded wallet is [guarded-wallet-funding.md](./guarded-wallet-funding.md). | idea | why not | |---|---| -| derive the child's key from the parent's | the child is then the parent wearing a different hat — [subgroups.md](./subgroups.md#why-the-key-is-fresh-rather-than-derived) | +| derive the child's key from the parent's | the child is then the parent wearing a different hat — [subgroups.md](../subgroups.md#why-the-key-is-fresh-rather-than-derived) | | the ancestor's room key as the leaf key, tweaked by the child's chain code | the parent never agrees to anything, the child has to find every ancestor's room key itself, and the first tweak has to be x-only to agree on parity. A key the parent signs into the certificate fixes all three | | the ancestor's threshold key `K_A` | the child does not have it, and handing it over gives every child member the ancestor's whole wallet and room identity | | a `k`-of-`n` `OP_CHECKSIGADD` over the ancestor's admins' own keys | it reveals the admins onchain, changes with every membership change, and bypasses the quorum the ancestor's FROST key already is | diff --git a/docs/guarded-wallet-forwarding.md b/docs/retired/guarded-wallet-forwarding.md similarity index 98% rename from docs/guarded-wallet-forwarding.md rename to docs/retired/guarded-wallet-forwarding.md index 4e058dcd..32b36e2e 100644 --- a/docs/guarded-wallet-forwarding.md +++ b/docs/retired/guarded-wallet-forwarding.md @@ -1,5 +1,7 @@ # Forwarding guarded wallets upward, without anybody pressing a button +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + 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 @@ -127,7 +129,7 @@ carrying it, or a `GroupSignedEvent` with its id. 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](./mls-skipped-keys.md) +at once. A burst like that is the shape [mls-skipped-keys.md](../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 @@ -341,7 +343,7 @@ The snackbar the button shows today stays as it is. rooms, with the button as a fallback. - [member-guarded-wallets.md](./member-guarded-wallets.md), Phase 10: a member's wallet reaches the groups above without anybody sharing it. -- [README.md](./README.md): this note's row. +- [README.md](../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` diff --git a/docs/guarded-wallet-funding.md b/docs/retired/guarded-wallet-funding.md similarity index 98% rename from docs/guarded-wallet-funding.md rename to docs/retired/guarded-wallet-funding.md index 4269b4bb..89d1e059 100644 --- a/docs/guarded-wallet-funding.md +++ b/docs/retired/guarded-wallet-funding.md @@ -1,5 +1,7 @@ # Funding a guarded wallet: a group paying into a descendant's wallet +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + An ancestor group can already *take* from a descendant's guarded wallet. This plan is about the other direction: **the group pays coins from its own wallet into the descendant's guarded wallet, using an address its own devices derive @@ -461,7 +463,7 @@ compact width and at 200% text. - This note becomes **Built**, with a table of where the build chose differently. -- A row in [README.md](./README.md), and a sentence in its reading order after +- A row in [README.md](../README.md), and a sentence in its reading order after the guardians and policy notes. - [group-wallet-guardians.md](./group-wallet-guardians.md)'s *What this does not do* says guardians cannot constrain where coins go. It gains a line pointing diff --git a/docs/guardian-delay.md b/docs/retired/guardian-delay.md similarity index 98% rename from docs/guardian-delay.md rename to docs/retired/guardian-delay.md index 1fe22f82..26d7434c 100644 --- a/docs/guardian-delay.md +++ b/docs/retired/guardian-delay.md @@ -1,5 +1,7 @@ # The parent sets the delay: how long a coin waits before a guardian can take it +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Today every leaf in a guarded wallet is ` OP_CHECKSIGVERIFY 12 OP_CHECKSEQUENCEVERIFY`: any ancestor can take a coin once it has 12 confirmations, about two hours. Twelve is one constant, @@ -562,7 +564,7 @@ first's reach and not the second's. ``. - [subgroup-wallet-policy.md](./subgroup-wallet-policy.md): the guarded row on the picker gains the delay, one sentence. -- [README.md](./README.md): this note's row and a sentence on reading order. +- [README.md](../README.md): this note's row and a sentence on reading order. - This note: *Built*, and the table of where the build chose differently. By hand, regtest, three emulators: diff --git a/docs/lightning/README.md b/docs/retired/lightning/README.md similarity index 95% rename from docs/lightning/README.md rename to docs/retired/lightning/README.md index 552b37bf..f2ce90b9 100644 --- a/docs/lightning/README.md +++ b/docs/retired/lightning/README.md @@ -1,5 +1,7 @@ # lightning docs +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Remediation plans for the findings of the October 2026 review of the group Lightning wallet — the review asked whether the wallet's operator can spend lightning funds without `t - 1` other key share holders, and found the core diff --git a/docs/lightning/first-commitment-policy.md b/docs/retired/lightning/first-commitment-policy.md similarity index 98% rename from docs/lightning/first-commitment-policy.md rename to docs/retired/lightning/first-commitment-policy.md index ed49b8b4..f20077f8 100644 --- a/docs/lightning/first-commitment-policy.md +++ b/docs/retired/lightning/first-commitment-policy.md @@ -1,5 +1,7 @@ # The first commitment must pass the co-signer policy +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + A remediation plan for finding 3 of the security review: the first remote commitment a device signs for a channel skips every value rule in `CoSignerPolicy`. It interacts with [group-lightning-wallet.md](../group-lightning-wallet.md) diff --git a/docs/lightning/force-close-revoked-commitment.md b/docs/retired/lightning/force-close-revoked-commitment.md similarity index 98% rename from docs/lightning/force-close-revoked-commitment.md rename to docs/retired/lightning/force-close-revoked-commitment.md index 81981b43..9208697b 100644 --- a/docs/lightning/force-close-revoked-commitment.md +++ b/docs/retired/lightning/force-close-revoked-commitment.md @@ -1,5 +1,7 @@ # Force close: the fence admits an already-revoked commitment +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Remediation plan for the most serious finding of the group Lightning wallet review: the co-signers' force-close fence lets the operator get a revoked local commitment signed, and publishing it hands the LSP's penalty the entire channel balance. Read diff --git a/docs/lightning/griefing-surface.md b/docs/retired/lightning/griefing-surface.md similarity index 98% rename from docs/lightning/griefing-surface.md rename to docs/retired/lightning/griefing-surface.md index 16267aea..94e47329 100644 --- a/docs/lightning/griefing-surface.md +++ b/docs/retired/lightning/griefing-surface.md @@ -1,5 +1,7 @@ # The griefing surface: four liveness holes in the co-signing path +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + The security review found four ways one member, or the operator acting alone, can stall the group Lightning wallet without ever touching its money. None of them steals anything; all of them contradict the trust table in diff --git a/docs/lightning/mutual-close-amount.md b/docs/retired/lightning/mutual-close-amount.md similarity index 98% rename from docs/lightning/mutual-close-amount.md rename to docs/retired/lightning/mutual-close-amount.md index 59113367..c61969d4 100644 --- a/docs/lightning/mutual-close-amount.md +++ b/docs/retired/lightning/mutual-close-amount.md @@ -1,5 +1,7 @@ # The mutual-close amount check trusts the operator's spec, not the co-signer's own ledger +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Finding 4 of the security review. The fix keeps `checkClosing`'s shape — output-by-output, no rebuild — but anchors what the group must be paid to the channel ledger the device already keeps, instead of to a number the operator supplies. About five days, all in the diff --git a/docs/lightning/node-seed-in-flight-exposure.md b/docs/retired/lightning/node-seed-in-flight-exposure.md similarity index 98% rename from docs/lightning/node-seed-in-flight-exposure.md rename to docs/retired/lightning/node-seed-in-flight-exposure.md index e267e696..b31dfadd 100644 --- a/docs/lightning/node-seed-in-flight-exposure.md +++ b/docs/retired/lightning/node-seed-in-flight-exposure.md @@ -1,5 +1,7 @@ # The node seed's real worth: in-flight incoming HTLCs +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + The design doc says the statement's in-flight cap "is the most the node seed can ever be worth" (`docs/group-lightning-wallet.md:333-337`). That is wrong by the whole incoming side of the channel: HTLCs the counterparty offers the group are claimable from the counterparty's diff --git a/docs/lightning/restored-device-marks.md b/docs/retired/lightning/restored-device-marks.md similarity index 98% rename from docs/lightning/restored-device-marks.md rename to docs/retired/lightning/restored-device-marks.md index 13dd32e1..186d1e7e 100644 --- a/docs/lightning/restored-device-marks.md +++ b/docs/retired/lightning/restored-device-marks.md @@ -1,5 +1,7 @@ # A restored device asks for high-water marks, and the share repair gets wired +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Remediation for one security-review finding, against the group Lightning wallet in [../group-lightning-wallet.md](../group-lightning-wallet.md) (Phase 9's co-signer, and Phase 1's repair). Two halves: **(A)** the restored-device diff --git a/docs/lightning/signer-hygiene.md b/docs/retired/lightning/signer-hygiene.md similarity index 99% rename from docs/lightning/signer-hygiene.md rename to docs/retired/lightning/signer-hygiene.md index b50de9e6..5901e539 100644 --- a/docs/lightning/signer-hygiene.md +++ b/docs/retired/lightning/signer-hygiene.md @@ -1,5 +1,7 @@ # Signer hygiene: five small findings and their fixes +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Five small things the review found around the Iceberg ceremony and the co-signing path of the [group Lightning wallet](../group-lightning-wallet.md). None of them moves money on its own; each one erodes a property the design states. They share diff --git a/docs/member-guarded-wallets.md b/docs/retired/member-guarded-wallets.md similarity index 98% rename from docs/member-guarded-wallets.md rename to docs/retired/member-guarded-wallets.md index 938cdcff..eeb779f3 100644 --- a/docs/member-guarded-wallets.md +++ b/docs/retired/member-guarded-wallets.md @@ -1,5 +1,7 @@ # Member wallets: a guarded wallet a group keeps for one person +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Today a guarded wallet belongs to a group. A subgroup's quorum holds the key path, and every ancestor holds a leaf that can take any coin 12 blocks after it confirmed. This plan gives the same shape to **one member**. The key path is a @@ -16,7 +18,7 @@ this key for this person. That certificate is what the member's device opens the wallet on, what every guardian watches, and what is forwarded upward so the groups above can find the coins. -Read [subgroups.md](./subgroups.md), +Read [subgroups.md](../subgroups.md), [group-wallet-guardians.md](./group-wallet-guardians.md) and [subgroup-wallet-policy.md](./subgroup-wallet-policy.md) first. This plan reuses the guardian derivation from the second without changing it. It reuses the @@ -150,7 +152,7 @@ is good for nothing else: behind NIP-55 cannot apply taproot tweaks in any case. And a wallet key equal to an npub would tie the chain to the relay graph; - **not a key from the profile's seed.** An nsec or npub profile has no seed - ([nsec-sign-in.md](./nsec-sign-in.md)). This is the first wallet such a profile + ([nsec-sign-in.md](../nsec-sign-in.md)). This is the first wallet such a profile could hold. One key gives one wallet, on one network, at account 0. A second wallet is a @@ -282,7 +284,7 @@ gone, and an nsec profile may ask. The grant needs `K_G` and the guardian keys in `G`'s own certificate. Today both are read off `G`'s verified key state, and only ceremony participants hold one. A member welcomed after the founding has neither. That is -[subgroups.md](./subgroups.md#what-this-does-not-do)'s gap, and it would leave +[subgroups.md](../subgroups.md#what-this-does-not-do)'s gap, and it would leave most ordinary members unable to ask. **Recommended: Phase 2, a key notice.** A member's device that holds no key state @@ -657,7 +659,7 @@ can guard its members. guards a wallet for @alice*. Without these arms, both kinds fall to `else ->` and show raw JSON. That is the - failure mode [member-chronicle.md](./member-chronicle.md) names, and it is + failure mode [member-chronicle.md](../member-chronicle.md) names, and it is avoidable here. **Tests**, jvmTest, in the shape of `SubgroupManagerJvmTest`: a certificate whose @@ -885,9 +887,9 @@ guardian rooms for one npub. - [group-wallet-guardians.md](./group-wallet-guardians.md): *What this does not do* gets a pointer here. *How an ancestor finds the coins* says the forwarded thing may be a member certificate. -- [subgroups.md](./subgroups.md): one line under the certificate's tag table +- [subgroups.md](../subgroups.md): one line under the certificate's tag table saying a member wallet is not a subgroup and has its own kind. -- [README.md](./README.md): the row, and a sentence on reading order. +- [README.md](../README.md): the row, and a sentence on reading order. - This note: *Built*, and a table of where the build chose differently. By hand, signet, three emulators, a root `R`, its guarded subgroup `M`, and Alice diff --git a/docs/member-wallet-delay.md b/docs/retired/member-wallet-delay.md similarity index 99% rename from docs/member-wallet-delay.md rename to docs/retired/member-wallet-delay.md index 3a5bc9b2..f77de791 100644 --- a/docs/member-wallet-delay.md +++ b/docs/retired/member-wallet-delay.md @@ -1,5 +1,7 @@ # The group decides whether it guards members' wallets, and at what delay +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + A member's guarded wallet carries one leaf for the group that guards it and one for every group above it. Since [guardian-delay.md](./guardian-delay.md), each ancestor's leaf keeps the delay that ancestor chose when it made the group below @@ -480,7 +482,7 @@ group, and proposes a closed policy. *and only of a group that has opened*. The request's tag list gains the policy. - [guardian-delay.md](./guardian-delay.md): its build table's member-wallet row ("a group still cannot choose…") points here. -- [README.md](./README.md): this note's row. +- [README.md](../README.md): this note's row. - This note: *Built*, and a table of where the build chose differently. By hand, regtest, three emulators: Alice (a signer), Bob (a signer), and Carol, diff --git a/docs/member-wallet-guarding-group.md b/docs/retired/member-wallet-guarding-group.md similarity index 98% rename from docs/member-wallet-guarding-group.md rename to docs/retired/member-wallet-guarding-group.md index 7c60f8b4..2d64cf10 100644 --- a/docs/member-wallet-guarding-group.md +++ b/docs/retired/member-wallet-guarding-group.md @@ -1,5 +1,7 @@ # Which group guards a member's wallet, as the groups above see it +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + An ancestor's *Guarded wallets* list shows `@alice` with no word about where her wallet sits. Suppose Alice is in two groups of one tree and each guards a wallet for her. The root then sees two rows that read the same, and nothing on the screen @@ -440,7 +442,7 @@ a dimension. `readableContent()` is already on the list's root. holder now appears on the holder's own line. - [group-wallet-guardians.md](./group-wallet-guardians.md): under *How an ancestor finds the coins*, a sentence on the notice's `certificate` tag. -- [README.md](./README.md): the row. +- [README.md](../README.md): the row. ```bash ./gradlew :composeApp:m3Audit diff --git a/docs/standalone-electrum.md b/docs/retired/standalone-electrum.md similarity index 93% rename from docs/standalone-electrum.md rename to docs/retired/standalone-electrum.md index 7259f90b..c77bf80d 100644 --- a/docs/standalone-electrum.md +++ b/docs/retired/standalone-electrum.md @@ -1,11 +1,13 @@ # An Electrum client for a profile with no node +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + How an nsec or npub profile comes to watch the chain: the group wallets it can already sign for, the member wallets it can already hold, and the spends the group has already signed. Today none of them can, because the only Electrum client in the app belongs to the Lightning node, and only a mnemonic profile starts one. -Read [nsec-sign-in.md](./nsec-sign-in.md)'s *The constraint* for why an nsec has +Read [nsec-sign-in.md](../nsec-sign-in.md)'s *The constraint* for why an nsec has no node, and [group-chain-wallet.md](./group-chain-wallet.md)'s *An identity without a node*, which named this plan as its follow-up. Neither changes: an nsec still cannot have a Lightning wallet. This plan gives it eyes on the chain, not a @@ -45,16 +47,16 @@ Five of them lose one.** | fact | where | what it means here | |---|---|---| -| `GroupOnchainWallets`, `GroupOnchainWallet` and `GroupTransactionWatcher` take an `IElectrumClient`, not a `PhoenixBusiness` | [wallet/](../composeApp/src/commonMain/kotlin/mobi/giza/compose/wallet/) | nothing below the nav host knows where the client came from | -| both are made from `activeIdentity?.business?.electrumClient` and are null without it | [GizaNavHost.kt:246](../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/navigation/GizaNavHost.kt) | the one place the null enters | +| `GroupOnchainWallets`, `GroupOnchainWallet` and `GroupTransactionWatcher` take an `IElectrumClient`, not a `PhoenixBusiness` | [wallet/](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/wallet/) | nothing below the nav host knows where the client came from | +| both are made from `activeIdentity?.business?.electrumClient` and are null without it | [GizaNavHost.kt:246](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/ui/composable/navigation/GizaNavHost.kt) | the one place the null enters | | every `canWatch` is `wallets != null`, and `CannotWatch` / `CANNOT_WATCH` are the same test | `GroupWalletViewModel:124`, `MemberWalletViewModel:71`, `GroupWalletAddressesViewModel:65`, `GizaNavHost:1222` | with a client for everyone, the condition never holds | -| an nsec or npub identity's preferences already carry Tor and a custom Electrum server, *"saved anyway"* | [IdentityWriter.kt:64](../composeApp/src/commonMain/kotlin/mobi/giza/compose/identity/IdentityWriter.kt) `prepareIdentity` | the configuration exists and nothing reads it yet | +| an nsec or npub identity's preferences already carry Tor and a custom Electrum server, *"saved anyway"* | [IdentityWriter.kt:64](../../composeApp/src/commonMain/kotlin/mobi/giza/compose/identity/IdentityWriter.kt) `prepareIdentity` | the configuration exists and nothing reads it yet | | the server lists are public top-level vals, and `platformElectrumRegtestConf` is a public `expect fun` | `lightning-kmp-app/.../data/ElectrumServers.kt` | a random server can be picked without an `AppConfigurationManager`, which needs a business | | `AppConnectionsDaemon` is the only reconnect loop, and its constructor takes a `PhoenixBusiness` | `lightning-kmp-app/.../managers/AppConnectionsDaemon.kt:241` | it cannot be reused. Its Electrum branch is what gets ported | | `ElectrumClient.connect` returns after one attempt; reconnecting is the caller's job | `lightning-kmp/.../ElectrumClient.kt:75` | the loop is not optional | | `ElectrumClient.stop()` is final: *"the client cannot be used after it has been closed"* | `ElectrumClient.kt:296` | one client per identity, made anew on a switch | | `NetworkMonitor` lives on `PhoenixGlobal`, not the business, and `start()` is idempotent on every platform | `PhoenixGlobal.kt:38`, the three `NetworkMonitor.*.kt` | available without a node, and safe to start from a second place | -| `FakeElectrum` implements `IElectrumClient` for the wallet tests | [FakeElectrum.kt](../composeApp/src/jvmTest/kotlin/mobi/giza/compose/wallet/FakeElectrum.kt) | the downstream tests need nothing new | +| `FakeElectrum` implements `IElectrumClient` for the wallet tests | [FakeElectrum.kt](../../composeApp/src/jvmTest/kotlin/mobi/giza/compose/wallet/FakeElectrum.kt) | the downstream tests need nothing new | ## Decisions @@ -204,7 +206,7 @@ The tests that drove these with `wallets = null` are rewritten against **An hour.** -- [nsec-sign-in.md](./nsec-sign-in.md): the *Out of scope* bullet keeps "a wallet +- [nsec-sign-in.md](../nsec-sign-in.md): the *Out of scope* bullet keeps "a wallet for an nsec identity", and gains a line that watching shipped here. - [group-chain-wallet.md](./group-chain-wallet.md): *An identity without a node* and the follow-up at the end point here and say it is built. Its @@ -235,7 +237,7 @@ on Android and on desktop: ## Out of scope - **A Lightning wallet for an nsec profile.** Unchanged from - [nsec-sign-in.md](./nsec-sign-in.md): it needs a seed, which is a second secret. + [nsec-sign-in.md](../nsec-sign-in.md): it needs a seed, which is a second secret. - **A Tor transport.** The fork has none for the node either (D4). When one exists it is a `TcpSocket.Builder`, and Phase 1's connect seam is where it goes. - **One client for every profile, mnemonic included.** This is what starting the node diff --git a/docs/subgroup-wallet-policy.md b/docs/retired/subgroup-wallet-policy.md similarity index 98% rename from docs/subgroup-wallet-policy.md rename to docs/retired/subgroup-wallet-policy.md index be6fc25e..3ffd471c 100644 --- a/docs/subgroup-wallet-policy.md +++ b/docs/retired/subgroup-wallet-policy.md @@ -1,5 +1,7 @@ # The parent decides: a subgroup's wallet policy, fixed at birth +> **Retired.** This note describes one of Bennu's wallets, which Giza removed. Giza keeps no wallet and declines to sign for one; see [giza-wallet-removal.md](../giza-wallet-removal.md). It is kept as the account of what a Bennu member in a shared group is doing. + Today a subgroup's parent agrees to *guard* it — it signs guardian keys into the child's birth certificate — and the child decides whether to use them: its wallet screen offers a guarded wallet and a plain one beside it, and whichever statement @@ -10,7 +12,7 @@ choice into the birth certificate, the child's admins agree to it by joining, an every honest device thereafter offers, signs, derives and watches only the wallet the certificate allows.** -Read [subgroups.md](./subgroups.md) and +Read [subgroups.md](../subgroups.md) and [group-wallet-guardians.md](./group-wallet-guardians.md) first. This builds on the certificate from the first and the guardian keys from the second, and it reverses one section of the second — [*whose choice it is*](./group-wallet-guardians.md#what-this-reverses-and-whose-choice-it-is). @@ -589,10 +591,10 @@ Small, and the reason the parent's members can see what they decided: child agrees by joining, and the paragraph saying "the parent cannot impose this" keeps its cryptographic half and loses its policy half. Its *What this does not do* gains a pointer here. -- [subgroups.md](./subgroups.md): the certificate's tag list gains `wallet`, and +- [subgroups.md](../subgroups.md): the certificate's tag list gains `wallet`, and the consent section's paragraph on the threshold gains the policy as the second value the coordinator picks for other people. -- [README.md](./README.md): this note's row and a sentence on reading order. +- [README.md](../README.md): this note's row and a sentence on reading order. - This note: *Built*, and a table of where the build chose differently. By hand, regtest, three emulators. The root makes two subgroups: a **guarded** diff --git a/docs/scripts/brand-audit.sh b/docs/scripts/brand-audit.sh index f6a9a8e9..c5badde2 100755 --- a/docs/scripts/brand-audit.sh +++ b/docs/scripts/brand-audit.sh @@ -5,15 +5,18 @@ # docs/scripts/brand-audit.sh lists the lines that break the rule # docs/scripts/brand-audit.sh --check and exits 1 if there are any # -# The rule, in the parts that build or ship (composeApp, iosApp, testing and the gradle -# scripts): Bennu may be named in a comment, and in a `bennu/` derivation tag, -# and nowhere else. The tags are hash inputs Giza shares with Bennu, so they stay spelled -# as they are (giza-rebrand.md, "What does not carry the name"). A comment can explain the -# fork. Anything else -- a string a person reads, a client tag, an identifier, a package -- -# is a leftover. +# The rule, in the parts that build or ship (composeApp, iosApp and the gradle scripts): +# Bennu may be named in a comment, and nowhere else. A comment can explain the fork. +# Anything else -- a string a person reads, a client tag, an identifier, a package, a +# derivation tag -- is a leftover. # -# Prose (README.md, CLAUDE.md, docs/ and the Markdown under testing/) is not checked: it -# explains the fork, and docs/ records decisions taken while the app was Bennu. +# There used to be a second exception, for the twelve `bennu/` derivation tags, which are +# hash inputs Giza shared with Bennu. Every one of them was a wallet's, and they went with +# the wallets (docs/giza-wallet-removal.md). The tags that stay are `mantra/`. So a +# `bennu/` tag in the code now is a wallet coming back, and fails like any other leftover. +# +# Prose (README.md, CLAUDE.md and docs/) is not checked: it explains the fork, and docs/ +# records decisions taken while the app was Bennu. # # Why it exists: a merge from Bennu (Phase 9) brings Bennu's new strings with it, and # docs/scripts/giza-rename.sh renames code, not words. This is what fails the build when @@ -30,7 +33,7 @@ CHECK=0 violations=$( git grep -niI 'bennu' -- \ - composeApp iosApp testing settings.gradle.kts build.gradle.kts \ + composeApp iosApp settings.gradle.kts build.gradle.kts \ | awk ' { # path:line:text -- the text may itself contain colons. @@ -38,14 +41,10 @@ violations=$( text = $0; sub(/^[^:]*:[^:]*:/, "", text) code = text; sub(/^[ \t]+/, "", code) } - # A derivation tag: the one place the name is protocol. - text ~ /"bennu\// { next } # Comments in Kotlin and Gradle scripts: //, /* and KDoc continuation lines. path ~ /\.(kt|kts)$/ && (code ~ /^\/\// || code ~ /^\/\*/ || code ~ /^\*/) { next } - # Comments in YAML, shell and HOCON (the regtest stack). - path ~ /\.(yml|yaml|sh|conf)$/ && code ~ /^#/ { next } - # Markdown under testing/ -- the regtest README -- is prose, like docs/. - path ~ /\.md$/ { next } + # Comments in YAML and shell. + path ~ /\.(yml|yaml|sh)$/ && code ~ /^#/ { next } { print } ' ) @@ -53,13 +52,13 @@ violations=$( count=0 [[ -n "$violations" ]] && count=$(printf '%s\n' "$violations" | wc -l) -echo "Bennu outside comments and derivation tags: $count" +echo "Bennu outside comments: $count" if (( count > 0 )); then printf '%s\n' "$violations" | sed 's/^/ /' fi if (( CHECK && count > 0 )); then - echo "Name it Giza, or, if it is protocol shared with Bennu, say so in a comment." >&2 + echo "Name it Giza. A bennu/ derivation tag is a wallet coming back: see docs/giza-wallet-removal.md." >&2 exit 1 fi exit 0 diff --git a/docs/scripts/wallet-audit.sh b/docs/scripts/wallet-audit.sh new file mode 100755 index 00000000..02ce9ff0 --- /dev/null +++ b/docs/scripts/wallet-audit.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash +# +# That the wallets stay removed: docs/giza-wallet-removal.md, Phase 8. +# +# docs/scripts/wallet-audit.sh lists the lines that break a rule +# docs/scripts/wallet-audit.sh --check and exits 1 if there are any +# +# Giza keeps no wallet, and Bennu, which it takes fixes from, keeps several. Four rules +# catch one coming back: +# +# 1. a retired kind's number (30331-30337, 30350-30366) in the app's own code. They +# are Bennu's and stay reserved -- RetiredKinds.kt says why. Allowed in that file, +# in the migrations (which have to keep meaning what they meant) and in tests, which +# assert that Giza declines them; +# 2. an import of lightning-kmp (`fr.acinq.lightning`). Nothing in the app needs it; +# 3. a source file named for one of the wallets' own pieces -- the group wallet, the +# Lightning wallet, Iceberg, guardians, member and guarded wallets, spends, +# transactions, Electrum. Named rather than every *Wallet*: the profile pickers under +# widgets/wallet/ and the SovereignWallet* startup kept Phoenix-era names, and the +# files that decline a wallet (WalletRefusal, RemoveWalletsMigration) are about one; +# 4. an amount in sats in a string a person reads. +# +# Needs only bash and git, like the other two audits, so the CI budgets job can run it. + +set -uo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/../.." || exit 1 + +CHECK=0 +[[ "${1:-}" == "--check" ]] && CHECK=1 + +MAIN=(composeApp/src/commonMain composeApp/src/androidMain composeApp/src/jvmMain composeApp/src/iosMain) + +kinds=$( + git grep -nE '\b303(3[1-7]|5[0-9]|6[0-6])\b' -- "${MAIN[@]}" \ + ':!*/nostr/RetiredKinds.kt' ':!*/database/migrations/*' +) + +lightning=$(git grep -nE '^import fr\.acinq\.lightning' -- composeApp) + +files=$( + git ls-files composeApp/src \ + | grep -E '/(GroupWallet|GroupLightning|Iceberg|Guardian|GuardedWallet|MemberWallet|MemberSend|GroupSend|GroupSpend|GroupTransaction|GroupOnchain|GroupChainClients|StandaloneElectrum|IdentityElectrum|ProposedSpend)[A-Za-z]*\.kt$' +) + +sats=$(git grep -niE '>[^<]*\b(sats?|satoshis?)\b' -- composeApp/src/commonMain/composeResources) + +report() { + local title=$1 lines=$2 n=0 + [[ -n "$lines" ]] && n=$(printf '%s\n' "$lines" | wc -l) + echo "$title: $n" + [[ -n "$lines" ]] && printf '%s\n' "$lines" | sed 's/^/ /' + total=$((total + n)) +} + +total=0 +report "Retired wallet kinds in the app's code" "$kinds" +report "lightning-kmp imports" "$lightning" +report "Files named for a wallet's pieces" "$files" +report "Amounts in sats in the strings" "$sats" + +if (( CHECK && total > 0 )); then + echo "Giza keeps no wallet. See docs/giza-wallet-removal.md before bringing one back." >&2 + exit 1 +fi +exit 0 diff --git a/docs/shared-key-derivation.md b/docs/shared-key-derivation.md index 24895e5c..aa27c100 100644 --- a/docs/shared-key-derivation.md +++ b/docs/shared-key-derivation.md @@ -1,5 +1,7 @@ # Deriving keys from a group's shared key +> **Since [giza-wallet-removal.md](./giza-wallet-removal.md):** The wallet derivations that were built on this note's rule are gone from Giza. The rule itself, and the room-key derivation it protects, are unchanged. + `SharedKeyDerivation` turns a group's ChillDKG threshold key into further keys the group can sign with, at paths that look like BIP32 but deliberately are not. diff --git a/docs/subgroups.md b/docs/subgroups.md index 25b6fd2d..9d026cf8 100644 --- a/docs/subgroups.md +++ b/docs/subgroups.md @@ -1,5 +1,7 @@ # Subgroups +> **Since [giza-wallet-removal.md](./giza-wallet-removal.md):** Giza certifies plain subgroups only. The wallet policy and guardian keys a certificate can carry are Bennu's: Giza writes neither, does not offer a subgroup under a parent whose certificate says `wallet=guarded`, and does not join a guarded subgroup's ceremony. + A group makes another group, and the child can prove where it came from. This is how the four ceremonies fit together, what the parent's signature actually covers, and the one thing a subgroup cannot inherit. @@ -170,7 +172,7 @@ tags: A member's guarded wallet is not a subgroup and never a 30329: every reader of this kind assumes a room. It has its own certificate, 30334 -- -[member-guarded-wallets.md](./member-guarded-wallets.md). +[member-guarded-wallets.md](./retired/member-guarded-wallets.md). With those, a parent admin's device can check the thing that actually matters before it signs — `marmotGroupId(subgroup_key, frost_path) == content` — and @@ -809,7 +811,7 @@ The subgroup's wallet policy, *guarded* or *unguarded*, is the second value the coordinator picks for other people, and it is agreed to the same way: it rides on the proposal, the join gate shows it, the parent's quorum signs it into the certificate, and the child's quorum refuses a key state whose certificate says -otherwise. See [subgroup-wallet-policy.md](./subgroup-wallet-policy.md). +otherwise. See [subgroup-wallet-policy.md](./retired/subgroup-wallet-policy.md). Confirm stays disabled below two selections, and below a threshold outside the range, with the reason stated rather than left to be guessed. @@ -1039,7 +1041,7 @@ is wanted, is the button. Two independent keys, two independent quorums. The certificate is a claim about lineage, not a delegation of authority, and nothing in this design lets one group act as the other. Delegation is a different mechanism, and it was built as one: -[group-wallet-guardians.md](./group-wallet-guardians.md) lets a parent guard a +[group-wallet-guardians.md](./retired/group-wallet-guardians.md) lets a parent guard a child's wallet, but only when the parent's quorum signs guardian keys into the certificate *and* the child's quorum opens a guarded wallet naming them. The certificate on its own still delegates nothing.