Files
giza-kmp/docs/lightning
Kgothatso NgakoandClaude Opus 5.5 5b92b83869 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>
2026-11-18 10:53:17 +02:00
..

lightning docs

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 claim intact with seven exceptions. Each finding has its own phased plan, written against the code it changes. The parent design doc is group-lightning-wallet.md; read its constraints, decision table and trust table before any of these.

document finding severity lands in
force-close-revoked-commitment.md the force-close fence at GroupLightningCoSigner.kt:345 admits an already-revoked commitment: the operator can turn a routine force-close authorisation into the LSP's penalty taking the whole channel critical — total channel loss, no LSP collusion needed app, then the fork
node-seed-in-flight-exposure.md in-flight incoming HTLCs are claimable by any seed holder (every participant, every ex-operator, every removed member) to an address of their choosing; the statement's in-flight cap covers only offered HTLCs, so the real bound is the channel cap high — theft, bounded by 1M sats a channel app; elimination is a spike
first-commitment-policy.md the first commitment a device signs skips rule 2, the in-flight cap and the floor (GroupLightningCoSigner.kt:399), and the floor-start then defends the outcome medium — needs a colluding LSP app only
mutual-close-amount.md checkClosing prices the group's output off the operator's spec, not the device's own ledger; an understated spec disables the check medium — needs a colluding LSP app only
restored-device-marks.md a restored co-signer has an empty label ledger and silently regains every spent budget; the planned high-water-mark collection and the tested-but-unwired share repair do not exist medium — bounded by the echo rule, compounds the other pinned == null holes app; new kinds 30367-30370, schema 33
griefing-surface.md four liveness holes: one member burning pool labels, the operator burning budgets at echo time and wedging a channel, a ceremony killed by a non-participant, one bad share wedging a request unattributed low — no theft, but the trust table overpromises app only
signer-hygiene.md five small items: a failure broadcast that can carry decrypted contribution bytes, the label assignment persisted after hand-out against its contract, fullySignedCommitTx's .right!! crashing the Peer's run loop, two missing negative tests, the unmeasured 60-second signing deadline low, except the crash path app and the fork

The order to build them in

The plans were written together and cross-reference each other; the order below is the one that keeps the co-signer consistent at every step.

  1. The cheap correctness fixes first. signer-hygiene.md Phases 1, 2 and 4 (failure-broadcast vocabulary, eager label reservation, the two negative tests) and griefing-surface.md Phase 1 (the ceremony-failure participant check). No wire or schema changes; each is a day or two.
  2. The co-signer core, in one release. force-close-revoked-commitment.md Phases 1-2, first-commitment-policy.md, mutual-close-amount.md Phases 1-2, and griefing-surface.md Phases 2-4 all rewrite parts of GroupLightningCoSigner / CoSignerPolicy and two of them change what the channel ledger's commitIndex means (griefing-surface.md Phase 4 is explicit that it must land together with the force-close fence). They share schema 33 and one test-suite pass. The fork half of the force-close plan (Phase 2, holding revoke_and_ack until the group signature completes) makes the signing deadline load-bearing for revocation too, so signer-hygiene.md Phase 5's measurement becomes blocking here.
  3. Recovery. restored-device-marks.md — its marks gate is the recovery path the Phase-2 refusals above rely on (pinned == null becomes a refusal in three of them), so it can follow them but the group is incomplete until it lands. New kinds 30367-30370; every device needs the build before a group relies on marks.
  4. The exposure narrative. node-seed-in-flight-exposure.md Phases 1-2 (doc correction, on-screen exposure, the incoming-side cap — which depends on first-commitment-policy.md having landed), then its Phase 3 spike decides whether group-keyed HTLC claims are ever built.
  5. The fork's crash path and the measurement. signer-hygiene.md Phases 3 and 5, on the claude/group-lightning-wallet branch.

Two things every plan assumes

  • The operator is hostile. No fix may rest on the operator's node behaving; each plan says which device enforces its rule, and it is never the operator's.
  • A group is only as covered as its slowest device. Co-signer rules are per-device: a refusal rule protects the wallet once at most n - t devices still run the old build, because every echo quorum of n - t + 1 then contains an upgraded device that refuses. Until then, mixed builds fail safe (refusals stall, they do not sign). Each plan states its own rollout moment.