chore: tooling, docs and a guard for the name (fork, Phase 6)

- rootProject.name is Giza. Res is pinned, so no import moves.
- Regtest: GIZA_REGTEST, GIZA_SPLICE_DELAYS and the gizaRegtest task input;
  node aliases giza-lsp and giza-payer.
- README describes Giza and says what it shares with Bennu: one network, one
  derivation, and a recovery phrase that must not run in both apps at once.
  The clone URL is the planned giza-kmp repository, which does not exist yet.
- docs/README.md is titled Giza docs and says how to read the documents
  written while the app was Bennu.
- CLAUDE.md gains the rule: name the app Giza, never name Bennu outside a
  comment, and never rename a mantra/ or bennu/ derivation tag.
- docs/scripts/brand-audit.sh --check, run by check (brandAudit) and by the CI
  budgets job, fails on Bennu anywhere in composeApp, iosApp, testing or the
  gradle scripts except in a comment or a "bennu/ tag. It catches the strings
  a merge from Bennu brings in, which giza-rename.sh cannot word.
- The plan gains the twelve bennu/ tags, missed when it was written.

jvmTest: 1643 run, 0 failed, 2 skipped. compileDebugKotlinAndroid, m3Audit and
brandAudit pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kgothatso NgakoandClaude Opus 5.5 committed 2026-11-18 10:53:17 +02:00
1 parent 4f3f0da3ca
commit 5b92b83869
16 files changed
+164 -24

No files matched your search

@@ -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
+20 -1
View File
@@ -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 —
+14 -4
View File
@@ -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:
+37 -2
View File
@@ -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<Test>().configureEach {
inputs.property("bennuRegtest", providers.environmentVariable("BENNU_REGTEST").orElse(""))
inputs.property("gizaRegtest", providers.environmentVariable("GIZA_REGTEST").orElse(""))
}
compose.desktop {
@@ -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<Unit> {
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
@@ -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<Unit> {
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
+6 -1
View File
@@ -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 |
+1
View File
@@ -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. |
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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 |
@@ -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:
+65
View File
@@ -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
+1 -1
View File
@@ -1,4 +1,4 @@
rootProject.name = "Bennu"
rootProject.name = "Giza"
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
pluginManagement {
+3 -3
View File
@@ -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 |
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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