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:
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
|
||||
|
||||
@@ -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 —
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 {
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
|
||||
+4
-4
@@ -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
@@ -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 |
|
||||
|
||||
@@ -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. |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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:
|
||||
|
||||
Executable
+65
@@ -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
@@ -1,4 +1,4 @@
|
||||
rootProject.name = "Bennu"
|
||||
rootProject.name = "Giza"
|
||||
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
|
||||
|
||||
pluginManagement {
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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,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
|
||||
|
||||
Reference in new issue
Block a user