diff --git a/.gitea/workflows/material-design-conformance.yml b/.gitea/workflows/material-design-conformance.yml index 17f279d6..afd91a59 100644 --- a/.gitea/workflows/material-design-conformance.yml +++ b/.gitea/workflows/material-design-conformance.yml @@ -29,6 +29,11 @@ jobs: - name: Check the conformance budgets 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). + - name: Check where Bennu is still named + run: docs/scripts/brand-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 cbac2c8e..ac7371c1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -188,6 +188,25 @@ tween(300) // no `MaterialTheme.motionScheme` is the public surface. Honour `MaterialTheme.reducedMotion` — it means drop the movement, not the transition. +## The app is Giza; Bennu is only protocol + +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. + +```kotlin +private const val TAG = "bennu/group-lightning/basepoints/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. + ## Checking your work ```bash @@ -207,7 +226,7 @@ testing/regtest/regtest.sh up ``` ```bash -BENNU_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest' +GIZA_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest' ``` `docs/scripts/` also holds the tools each phase was done with — diff --git a/README.md b/README.md index 3819bd6a..24ec1a76 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # Giza -Giza is a fork of [Bennu](https://code.sigidli.com/machankura/bennu-kmp). - -Bennu is a group chat app where the group holds bitcoin together. Groups talk over +Giza is a group chat app where the group holds bitcoin together. 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. @@ -10,6 +8,18 @@ wallets that need a quorum of members to spend. It is a Kotlin Multiplatform app with a Compose Multiplatform UI, built for Android, iOS and desktop (JVM). +## Giza and Bennu + +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. + +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. +[docs/giza-rebrand.md](docs/giza-rebrand.md) explains what the fork changed, what it left alone +and why. + ## What it does - **Group chat.** End-to-end encrypted groups on Marmot, with direct messages between members, @@ -42,7 +52,7 @@ Clone with submodules. The app builds against `lightning-kmp-app` as a composite repository nests its own builds down to `secp256k1-kmp`: ```bash -git clone --recursive https://code.sigidli.com/machankura/bennu-kmp.git +git clone --recursive https://code.sigidli.com/machankura/giza-kmp.git ``` In an existing clone, or in a git worktree, which does not get submodules automatically: diff --git a/composeApp/build.gradle.kts b/composeApp/build.gradle.kts index eb84f847..04e85766 100644 --- a/composeApp/build.gradle.kts +++ b/composeApp/build.gradle.kts @@ -326,11 +326,46 @@ val m3Audit = tasks.register("m3Audit") { tasks.named("check") { dependsOn(m3Audit) } -// The group Lightning wallet's regtest run (testing/regtest/README.md) runs only when BENNU_REGTEST=1. +/** + * 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. + * + * 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." + + val script = rootProject.layout.projectDirectory.file("docs/scripts/brand-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("brandAudit: no bash found, skipping. Run docs/scripts/brand-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("The pre-fork name appears outside a comment or a derivation tag. See the report above.") + } + } +} + +tasks.named("check") { dependsOn(brandAudit) } + +// The group Lightning wallet's regtest run (testing/regtest/README.md) runs only when GIZA_REGTEST=1. // An environment variable is not a task input, so without this a skipped run would leave jvmTest up to // date, and asking for the run afterwards would replay the skip. tasks.withType().configureEach { - inputs.property("bennuRegtest", providers.environmentVariable("BENNU_REGTEST").orElse("")) + inputs.property("gizaRegtest", providers.environmentVariable("GIZA_REGTEST").orElse("")) } compose.desktop { diff --git a/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/GroupLightningRegtestJvmTest.kt b/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/GroupLightningRegtestJvmTest.kt index 626dd607..1e723c75 100644 --- a/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/GroupLightningRegtestJvmTest.kt +++ b/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/GroupLightningRegtestJvmTest.kt @@ -76,10 +76,10 @@ import kotlin.time.Duration.Companion.seconds * Every message between the devices goes through the same managers the inbound path uses, pumped in the * background; the node's signatures are the group's, made by Iceberg co-signing in the room. * - * Skipped unless `BENNU_REGTEST=1`, because it needs the docker network. + * Skipped unless `GIZA_REGTEST=1`, because it needs the docker network. */ class GroupLightningRegtestJvmTest { - private val enabled = System.getenv("BENNU_REGTEST") == "1" + private val enabled = System.getenv("GIZA_REGTEST") == "1" private val fixture = GroupLightningFixture(chain = Chain.Regtest) private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) private val loggerFactory = LoggerFactory(StaticConfig(Severity.Info, listOf(platformLogWriter()))) @@ -220,7 +220,7 @@ class GroupLightningRegtestJvmTest { @Test fun `four devices open, receive, pay, close and sweep on regtest`() = runBlocking { - assumeTrue("set BENNU_REGTEST=1 with testing/regtest up", enabled) + assumeTrue("set GIZA_REGTEST=1 with testing/regtest up", enabled) requireNetwork() val lspId = lsp("getinfo").jsonObject["nodeId"]!!.jsonPrimitive.content diff --git a/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/LiquidityPurchaseRegtestJvmTest.kt b/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/LiquidityPurchaseRegtestJvmTest.kt index b6b81a36..dad8374d 100644 --- a/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/LiquidityPurchaseRegtestJvmTest.kt +++ b/composeApp/src/jvmTest/kotlin/mobi/giza/compose/managers/LiquidityPurchaseRegtestJvmTest.kt @@ -82,15 +82,15 @@ import kotlin.time.TimeSource * 2. how long eclair waits for our signatures inside a splice, by delaying each one (step 3); * 3. how long two commitments stay live, from the purchase's answer to the splice locking (step 4). * - * Skipped unless `BENNU_REGTEST=1`. `BENNU_SPLICE_DELAYS` takes the delays to try, in seconds, + * Skipped unless `GIZA_REGTEST=1`. `GIZA_SPLICE_DELAYS` takes the delays to try, in seconds, * comma-separated; by default 0, 10 and 25. A purchase needs two signatures, the first commitment on the * new output and the shared input, and eclair allows a splice `channel.quiescence-timeout`, one minute by * default, from quiescence: at 30 seconds a signature it disconnects as the second arrives (the run of * 2026-11-01, recorded in the plan's Phase 0). */ class LiquidityPurchaseRegtestJvmTest { - private val enabled = System.getenv("BENNU_REGTEST") == "1" - private val delays = (System.getenv("BENNU_SPLICE_DELAYS") ?: "0,10,25").split(",").map { it.trim().toInt().seconds } + private val enabled = System.getenv("GIZA_REGTEST") == "1" + private val delays = (System.getenv("GIZA_SPLICE_DELAYS") ?: "0,10,25").split(",").map { it.trim().toInt().seconds } private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default) private val loggerFactory = LoggerFactory(StaticConfig(Severity.Warn, listOf(platformLogWriter()))) private val http = HttpClient.newHttpClient() @@ -178,7 +178,7 @@ class LiquidityPurchaseRegtestJvmTest { @Test fun `a node that keeps its funding key buys liquidity from eclair, and how long eclair waits`() = runBlocking { - assumeTrue("set BENNU_REGTEST=1 with testing/regtest up", enabled) + assumeTrue("set GIZA_REGTEST=1 with testing/regtest up", enabled) val lspId = PublicKey.fromHex(lsp("getinfo").jsonObject["nodeId"]!!.jsonPrimitive.content) var signingDelay = Duration.ZERO diff --git a/docs/README.md b/docs/README.md index f68891c0..19115f5e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,14 @@ -# curare docs +# Giza docs Notes on the parts of this app whose behaviour is not recoverable by reading the code alone — where the reasoning lives in a protocol, a failure mode that is 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)). + | document | covers | |---|---| | [shared-key-ceremony.md](./shared-key-ceremony.md) | ChillDKG over NIP-17: the rounds, the approval gates, the chat transcript, participant ordering | diff --git a/docs/giza-rebrand.md b/docs/giza-rebrand.md index 6c05e810..dd962122 100644 --- a/docs/giza-rebrand.md +++ b/docs/giza-rebrand.md @@ -50,6 +50,7 @@ one more: Giza has to stay interoperable with Bennu. |---|---| | `mantra/chilldkg/host-key/v1`, `mantra/shared-key/tweak/v1` | They are inputs to a hash. Renaming them derives a different DKG host key and different tweaks from the same seed. A Bennu seed restored in Giza would then lose every group key it holds. | | `MARMOT_ADMIN_GROUP_PATH` (`9420/0/0`) | Same reason. It is part of the derivation. | +| the twelve `bennu/…` tags: `bennu/group-wallet/account/v1`, `…/guardian/v1`, `…/guardian/child/v1`, `bennu/group-lightning/basepoints/v1`, the five `bennu/iceberg-dkg/…/v1`, `bennu/iceberg/pool/v1`, `bennu/member-wallet/id/v1` and `…/possession/v1` | **Missed when this plan was first written, and found while building Phase 4.** They are hash and HMAC inputs, exactly like `mantra/`: every group wallet address, guardian leaf, group Lightning basepoint, Iceberg ceremony and member wallet id is derived through one of them. They look like brand strings and are not. Phase 4 adds a note beside each so that a later sweep for "bennu" leaves them alone, and Phase 6's guard allowlists them. | | nostr kinds, tag names, `d`-tag schemes | They are the protocol. A Giza member and a Bennu member have to read each other's events. | | `wss://ephemeral.mantra.press` | It is a running relay, not a brand string. It is replaced when a Giza relay exists (see Phase 6). | | `aux.db`, Phoenix's `*.preferences_pb` names | They are internal to each app's sandbox and nobody reads them. Renaming them would only add to every merge from Bennu. | diff --git a/docs/group-chain-wallet.md b/docs/group-chain-wallet.md index f4ee645f..9ebfcefd 100644 --- a/docs/group-chain-wallet.md +++ b/docs/group-chain-wallet.md @@ -132,7 +132,7 @@ has one share. Do what those helpers do, by hand, through `TweakCache` and | more than one wallet per group is possible later | BIP44's `account'` | | 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 Bennu to see the balance | +| 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) | ### The path diff --git a/docs/group-lightning-wallet.md b/docs/group-lightning-wallet.md index 3501157b..8bd697c5 100644 --- a/docs/group-lightning-wallet.md +++ b/docs/group-lightning-wallet.md @@ -157,7 +157,7 @@ testing/regtest/regtest.sh up ``` ```bash -BENNU_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest' +GIZA_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest' ``` | step | what happens | result | diff --git a/docs/lightning/force-close-revoked-commitment.md b/docs/lightning/force-close-revoked-commitment.md index 49d052ec..81981b43 100644 --- a/docs/lightning/force-close-revoked-commitment.md +++ b/docs/lightning/force-close-revoked-commitment.md @@ -216,7 +216,7 @@ old proposer are impossible, which is the safe direction. **About a day, plus the measurement.** - The regtest run (`testing/regtest/regtest.sh up`, then - `BENNU_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest'`) re-runs + `GIZA_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest'`) re-runs end to end; its force-close step now exercises the deferred revocation against a real eclair. - The app's JVM suite and the fork's suite pass. - **Measure how long ACINQ's LSP waits for `revoke_and_ack`** before this ships to a real group: diff --git a/docs/scripts/brand-audit.sh b/docs/scripts/brand-audit.sh new file mode 100755 index 00000000..f6a9a8e9 --- /dev/null +++ b/docs/scripts/brand-audit.sh @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +# +# Where the name Bennu may still appear in Giza: docs/giza-rebrand.md, Phase 6. +# +# 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. +# +# 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. +# +# 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 +# one of them would otherwise ship. +# +# Needs only bash and git, like m3-audit.sh, so the CI budgets job can run it. + +set -uo pipefail + +cd "$(dirname "${BASH_SOURCE[0]}")/../.." || exit 1 + +CHECK=0 +[[ "${1:-}" == "--check" ]] && CHECK=1 + +violations=$( + git grep -niI 'bennu' -- \ + composeApp iosApp testing settings.gradle.kts build.gradle.kts \ + | awk ' + { + # path:line:text -- the text may itself contain colons. + path = $0; sub(/:.*/, "", path) + 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 } + { print } + ' +) + +count=0 +[[ -n "$violations" ]] && count=$(printf '%s\n' "$violations" | wc -l) + +echo "Bennu outside comments and derivation tags: $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 + exit 1 +fi +exit 0 diff --git a/settings.gradle.kts b/settings.gradle.kts index 2675dfca..450e3c04 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -1,4 +1,4 @@ -rootProject.name = "Bennu" +rootProject.name = "Giza" enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") pluginManagement { diff --git a/testing/regtest/README.md b/testing/regtest/README.md index 7b9bb9e7..664dd8f3 100644 --- a/testing/regtest/README.md +++ b/testing/regtest/README.md @@ -10,7 +10,7 @@ LSP. What the run checks, what it found, and why each LSP setting is there is in funding key buys inbound liquidity from the LSP, with its signatures delayed, to see what eclair accepts and how long it waits. The group run buys liquidity too, between receiving and paying. -The run is **not** part of `./gradlew check` or CI. Without `BENNU_REGTEST=1` the test is reported as +The run is **not** part of `./gradlew check` or CI. Without `GIZA_REGTEST=1` the test is reported as skipped, so a green `jvmTest` says nothing about it. ## Prerequisites @@ -49,7 +49,7 @@ finishes by printing the LSP's node id. Allow a minute the first time, after the From the repository root: ```bash -BENNU_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest' +GIZA_REGTEST=1 ./gradlew :composeApp:jvmTest --tests '*GroupLightningRegtestJvmTest' ``` It takes about thirty seconds. It can be run again on the same network as often as you like. Each @@ -90,7 +90,7 @@ call eclair's API, for example `./regtest.sh lsp channels` or `./regtest.sh paye | what you see | what it means | |---|---| -| the test is reported as skipped | `BENNU_REGTEST=1` was not set in the environment Gradle runs the test in | +| the test is reported as skipped | `GIZA_REGTEST=1` was not set in the environment Gradle runs the test in | | `The regtest network is not running: nothing answers for … on 127.0.0.1:…` | that service is down. Run `./regtest.sh up`, or check it with `docker compose ps -a` and its logs | | `the payer has no open channel to the LSP` | `up` stopped part way through. Run `./regtest.sh down`, then `up` again | | `up` prints `timed out waiting for: …` | a container exited: `docker compose ps -a` shows which, and its log says why | diff --git a/testing/regtest/lsp.conf b/testing/regtest/lsp.conf index 3350faab..3a24b22d 100644 --- a/testing/regtest/lsp.conf +++ b/testing/regtest/lsp.conf @@ -3,7 +3,7 @@ // made, so the run mines the funding transaction instead. eclair { chain = "regtest" - node-alias = "bennu-lsp" + node-alias = "giza-lsp" server.binding-ip = "0.0.0.0" api { enabled = true diff --git a/testing/regtest/payer.conf b/testing/regtest/payer.conf index cf039058..19db61d1 100644 --- a/testing/regtest/payer.conf +++ b/testing/regtest/payer.conf @@ -1,7 +1,7 @@ // Somebody else on the network: pays the group through the LSP, and is paid by it. eclair { chain = "regtest" - node-alias = "bennu-payer" + node-alias = "giza-payer" server.binding-ip = "0.0.0.0" api { enabled = true