Files
giza-kmp/docs/lightning/README.md
T
Kgothatso Ngako 1f9c9ef131 docs: the group Lightning wallet's review findings, as seven phased plans
The review asked whether the wallet's operator can spend lightning funds
without t-1 other share holders. The core claim holds; the seven exceptions
each get a phased plan under docs/lightning/, with an index giving the
severity table and the build order.
2026-10-27 09:21:36 +02:00

5.3 KiB

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.