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.
23 KiB
The node seed's real worth: in-flight incoming HTLCs
The design doc says the statement's in-flight cap "is the most the node seed can ever be
worth" (docs/group-lightning-wallet.md:333-337). That is wrong by the whole incoming side
of the channel: HTLCs the counterparty offers the group are claimable from the counterparty's
commitment by anyone holding the node seed, to an address of the claimant's choosing, and no
policy caps them. This plan corrects the claim, makes the exposure visible, bounds it, and
sets up the decision on eliminating it. Phases 1 and 2 are the work; Phase 3 is a spike with
an explicit go/no-go, because the honest answer may be that elimination costs more than the
exposure does.
The finding
In a force close that publishes the counterparty's commitment, two transaction types
spend its HTLC outputs, and both sign with commitKeys.ourHtlcKey — a per-commitment tweak
of the HTLC basepoint, which withGroupBasepoints leaves derived from the node seed
(KeyManager.kt:227-228,241,264; only the payment and delayed-payment basepoints are group
keys, KeyManager.kt:207,215):
ClaimHtlcSuccessTx, an incoming HTLC claimed with its preimage (Transactions.kt:592-620; the signature is at:615). Its output payslocalFinalScriptPubKey, a free parameter ofcreateUnsignedTx(:639,:652), and its fee is baked into the output amount (:648).ClaimHtlcTimeoutTx, an offered HTLC refunded after its CLTV (Transactions.kt:664-690; signature at:686, free final script at:710,:722).
The shipped, honest node passes the group's onchain wallet address as that final script
(Helpers.kt:835,:886, with GroupNodeKeyManager.kt:25 overriding
defaultFinalScriptPubKey). Nothing in the protocol requires it: the output script is
committed only by the claim's own signature, which the seed's key alone produces. A modified
operator node — or a hand-built transaction from any seed holder — pays any address.
The statement's cap never covered this. CoSignerPolicy.checkRemoteCommitment caps only the
HTLCs the group offers (CoSignerPolicy.kt:105-106), and the code comment says why
incoming HTLCs are exempt (:103-104): "an HTLC offered to it is the counterparty's to add,
and refusing to sign over one would stall the channel rather than protect anything". The doc
says the same (docs/group-lightning-wallet.md:105). The real bound on the incoming side is
the channel's capacity, which every co-signer holds to MAINNET_CHANNEL_CAP = 1,000,000 sats
(GroupLightningRollout.kt:38, enforced at GroupLightningCoSigner.kt:374-377).
The attack, step by step.
- The group has a channel with the LSP. Someone pays a group invoice for, say, 600,000 sats. The LSP adds the HTLC to its commitment; the co-signers sign it — correctly, since incoming HTLCs are uncapped and the group's balance has not moved.
- The attacker sends the LSP an
errornaming the channel. Impersonating the node takes only the seed, which every participant holds (D4), including removed members (docs/group-lightning-wallet.md:329). No group signature is involved. - The LSP force-closes, publishing its commitment — the one carrying the incoming HTLC as an offered output.
- The attacker builds
ClaimHtlcSuccessTxby hand: input the HTLC output, witness the preimage and the seed-derived HTLC key's signature, output to the attacker's own address. - This races the honest node's claim to the group's address (
Helpers.kt:829-841). Both spends are valid; the claim tx has no anchor (taproot channels publish none, per the doc's table), so the race is first-seen plus RBF fee, and the attacker can spend up to the whole output on fees. The attacker has the edge whenever the honest operator is offline — and is not racing anyone when the attacker is the operator. - The payer sees their preimage revealed and counts the payment settled. The group never receives the balance. Repeat per in-flight incoming HTLC; the take is bounded only by the channel cap.
Who can actually run it — narrower than "any seed holder", and worth stating precisely.
Claiming needs the preimage, and the preimage of a group invoice is generated by the node
that created the invoice (GroupLightningNode.kt:567-568,
peer.createInvoice(Lightning.randomBytes32(), …)) and lives in that device's payments
database. So the realistic attackers are: the current operator, who holds every current
invoice's preimage; and past operators and removed members, who keep the seed and the
preimages of any still-unpaid invoices from their term. A seed holder who never operated has
no preimages for in-flight HTLCs, and cannot get a new incoming HTLC into a signed commitment
without being the current operator (co-signer check 1, GroupLightningCoSigner.kt:183-187).
That is a narrower set than the finding states — but it includes every ex-operator and every
removed member forever, which is bad enough.
The doc repeats the false bound in three places: the trust-table afterword
(docs/group-lightning-wallet.md:333-337), the risks table ("a removed member keeps the
seed — griefing, plus in-flight HTLCs up to the cap", :1041), and the Policy docstring
("inFlightCapSat is the most that can be in HTLCs at once, which is the most the node seed
is ever worth", GroupLightningWalletStatementEvent.kt:34-36).
Root cause
D5 group-keyed the payment and delayed-payment basepoints and deliberately left the HTLC
basepoint on the seed, because claiming on chain is time-critical and a FROST session "is the
wrong tool for it" (docs/group-lightning-wallet.md:333-335; the deviation table's
HtlcDelayedTx row, :61, says the same). That choice was then justified post hoc by the
in-flight cap — but the cap was designed against the offered side (Phase 12's send path), and
the incoming side was exempted on the reasoning that refusing to sign over a
counterparty-added HTLC "stalls the channel without protecting anything"
(CoSignerPolicy.kt:103-104). That reasoning was written when the exposure was believed
capped, and was never revisited: under this finding the exemption is the exposure, and a
refusal protects exactly the stealable excess, because an HTLC in no signed commitment can
never be claimed on chain. Two doc sentences then promoted the design choice into a false
security bound.
One mitigating fact the review surfaced: NodeParams.maxHtlcValueInFlightMsat exists
upstream as a protocol-level bound on what the counterparty may offer us
(NodeParams.kt:136,167), enforced when the peer's update_add_htlc would exceed it
(Commitments.kt:542-544) and advertised to the LSP in accept_channel
(WaitForOpenChannel.kt:65), which BOLT 2 binds the LSP to respect. The group node never
sets it: GroupLightningNode.lightningKmpPeers copies only zeroConfPeers and
liquidityPolicy (GroupLightningNode.kt:479-493), so it sits at lightning-kmp's default of
20,000,000,000 msat = 20M sats (NodeParams.kt:246) — twenty times the channel cap, inert.
The fix, in phases
Phase 1 — correct the documents, and show the group its exposure
About 2 days. No schema, no wire-kind, no fork changes; an additive snapshot field.
Goal: nobody downstream of the doc's sentence trusts the cap as the seed's worth, and every member can see the live number at risk.
- The design doc. Rewrite the trust-table afterword
(
docs/group-lightning-wallet.md:333-337): the cap bounds only what the group offers; the seed is additionally worth all in-flight incoming HTLC value on the counterparty's commitment, up to the channel cap, claimable by the operator, any past operator, and any removed member, to any address. Fix the risks-table row at:1041the same way. - The code docstrings that repeat the claim:
GroupLightningWalletStatementEvent.kt:34-36(thePolicyKDoc) and the cap's rationale comment atCoSignerPolicy.kt:103-104, which stays true for offered HTLCs but must stop implying incoming value is safe. - The snapshot carries it.
WalletWire.ChannelViewgainsincomingInFlightMsat: Long? = nullandofferedInFlightMsat: Long? = null, summed fromlocalCommit.spec.htlcsinPeerHandle.channels()(GroupLightningNode.kt:552-565:IncomingHtlcamounts are on their way to the group). Nullable with a null default, so an old snapshot and an old build both read as not reported rather than zero —CommonJsonhasignoreUnknownKeys(CommonJson.kt:7), so the field is backward compatible in both directions and no schema migration is needed (the snapshot row stores the JSON blob). - The cross-check comes free. Every co-signer's ledger already records incoming HTLCs by
id with amounts (
CoSignerPolicy.Ledger.incoming,CoSignerPolicy.kt:39). Add a DAO read besideGroupLightningCoSigner.signedOursMsatand extendGroupLightningReports.ChannelCheck(GroupLightningReports.kt:36-39,104-108) so the snapshot's incoming figure is checked against what this device last signed, exactly the pattern the balance check already uses. A mismatch means the operator is lying or stale — the screen already has the vocabulary for that. - The screen. On
GroupLightningWalletScreen.kt(balance at:352, channel rows at:382): under the balance, a line in the style of the existing mismatch copy — N sats on their way in — until they settle, anyone holding the node seed could take them — shown only while the figure is non-zero, with amounts as format arguments perCLAUDE.md. The opening screen's unreviewed-scheme sentence (GroupLightningRollout.kt:24-28lists the stated bounds) names this exposure beside the cap.
Tests (existing suites, no new harness):
GroupLightningReportsJvmTest.kt: a snapshot with the new fields round-trips; an old snapshot without them reads as not reported; aChannelCheckwhose snapshot incoming figure differs from the device's ledger flags a mismatch.GroupLightningNodeJvmTest.kt:channels()sums incoming and offered in-flight from a fake peer's spec.GroupLightningCoSigningJvmTest.ktalready populates ledgers with incoming HTLCs; add a case asserting the ledger'sincomingsum the screen will read.
Deployment realism: visibility is per-device; a member on an old build sees the old screen and loses nothing. The doc corrections are what the group's understanding relies on, so the release notes say the old sentence was wrong.
Phase 2 — bound the incoming side to the statement's cap
About 4 days. App only: no wire-kind, schema, or fork changes — deliberately, see the table. A co-signer behaviour change, so the rollout rule below applies.
Goal: the seed's worth is bounded by a number the group signed, on both directions of in-flight value, enforced even against a modified operator node.
| decision | why | |
|---|---|---|
| where the bound lives | both the node's NodeParams.maxHtlcValueInFlightMsat and a co-signer check |
the node param fails a too-big receive cleanly at update_add_htlc and binds an honest LSP over the wire, but it is operator-local and a modified node ignores it; the co-signer check survives a hostile operator but its failure mode is a refused commitment. Neither alone is enough |
| which value | the statement's existing inFlightCapSat, applied to incoming totals too |
a fourth value in the policy tag is silently ignored by old builds — read accepts any tag of size ≥ 4 and reads only p[1..3] (GroupLightningWalletStatementEvent.kt:89-91) — so the group would believe in a bound that un-upgraded co-signers do not enforce. Reusing the existing field changes no wire format. A dedicated incoming cap waits for the statement's next change, with the deployment rule below |
| what a refusal costs | a wedge, then either recovery or an LSP force close — accepted | a refused commitment means the oversized HTLC never enters any signed commitment and can never be claimed on chain. The recovery path exists: a later commitment with the HTLC failed back passes the policy (incoming shrank, nothing else moved), so an honest operator unwedges the channel. A hostile operator can choose the force close instead — which it could have caused anyway, and D5 still sends the proceeds to the group. The doc's "stalls without protecting anything" is wrong under this finding: the refusal protects exactly the stealable excess |
Changes, by file and function:
GroupLightningNode.lightningKmpPeers(GroupLightningNode.kt:479-493): the copiedNodeParamssetsmaxHtlcValueInFlightMsat = statement.policy.inFlightCapSat * 1000. This is advertised inaccept_channel(WaitForOpenChannel.kt:65) and enforced on receipt (Commitments.kt:542-544), so with an honest operator a too-big incoming payment fails back to the payer instead of wedging anything. (maxAcceptedHtlcs, 19 atNodeParams.kt:247, bounds count, not value; leave it.)CoSignerPolicy.checkRemoteCommitment(CoSignerPolicy.kt:70-106): after the offered-side cap check, mirror it for the incoming side — refuse when incoming HTLCs were added and their new total exceedsinFlightCapMsat. Theadded.isNotEmpty()guard matters: a commitment that merely carries an already-in-flight HTLC forward must not be refused, or a group that raises the policy later would wedge every live channel.- The first commitment is a hole here.
checkRemotereturns early onpinned == null(GroupLightningCoSigner.kt:399), and on-the-fly funding puts the channel's first incoming HTLC in exactly that commitment. So the incoming cap must also run inCoSignerPolicy.open(CoSignerPolicy.kt:58-62), or incheckRemotebefore the early return. This is the same exemptionfirst-commitment-policy.mdremoves wholesale; if that plan lands first, this phase adds one line to its fixed path. Either way, do not ship this phase with the exemption intact — the biggest single receive a channel ever sees is its first one. - The receive screen says the most one payment can be (the cap), and any-amount invoice requests and offer payments that would exceed it are refused by the node before the invoice is created — the honest path never reaches the co-signer refusal.
Tests:
CoSignerPolicyTest.kt: incoming added over the cap is refused; at the cap it signs; incoming carried forward unchanged past a lowered cap signs; the cap holds inopen.GroupLightningCoSigningJvmTest.kt(four devices): a remote commitment carrying an oversized incoming HTLC is refused by every member; the follow-up commitment with the HTLC failed back is signed (the recovery path).GroupLightningCoSigningMainnetJvmTest.ktre-runs both.GroupLightningNodeJvmTest.kt: the builtNodeParamscarries the statement's cap, not lightning-kmp's 20M-sat default.
Deployment realism: this is a co-signer behaviour change with no format change, so old builds
still sign — and any quorum drawn entirely from old-build devices signs an over-cap
commitment. For 2-of-4, that is any three un-upgraded devices (the echo gate is n-t+1).
The bound holds as a group property only once every participant's device runs the new build —
the doc's own Phase 15 rule (docs/group-lightning-wallet.md:977-981) — and the proposal
screen should say so when a wallet's members run mixed builds, as the ceremony screen already
does for unanswered devices.
Phase 3 — elimination: a spike with an explicit go/no-go
About 3 days of research and a regtest measurement; the fix itself, if go, is an estimated 2-3 weeks across the fork and the sweep machinery. No code in this phase beyond the spike.
Goal: decide, with numbers, whether the HTLC basepoint moves to a group key — the only real elimination — or the group lives with Phase 2's bound.
Pre-signing claims at commitment-signing time: evaluated and rejected. A
ClaimHtlcSuccessTx commits to its output amount, which is the input minus a feerate-baked
fee (Transactions.kt:648), to a locktime (0 for success, the HTLC's CLTV for timeout,
:723), and to the input outpoint — the counterparty commitment's output, which changes with
every commitment. So pre-signed claims die with each new commitment, the feerate is right
only by luck at claim time (days later), and the claim tx has no anchor to bump it — RBF
means a new signature, i.e. the quorum again, at the worst moment. Pre-signing at a spread of
feerates multiplies Iceberg sessions per HTLC per commitment for a transaction that will
likely never be used. This is not the way; the spike should not reopen it.
A group-keyed HTLC basepoint: the real candidate. The doc rejected it for
time-criticality (docs/group-lightning-wallet.md:333-335), but the numbers have changed
since that sentence was written: the sweep machinery it would have needed did not exist then
and does now (Phase 13), and the deadline is not minutes — it is the HTLC's CLTV, at minimum
minFinalCltvExpiryDelta = 144 blocks ≈ a day (NodeParams.kt:252), with lightning-kmp
starting its claims fulfillSafetyBeforeTimeoutBlocks = 12 blocks early (:253). A FROST
session inside a day-long window is the same shape as the CSV-delayed sweeps the app already
does. And the failure mode flips the right way: if the group cannot convene in the window,
the LSP times the HTLC out and takes it back — the group loses a payment it was owed, which
is a liveness failure, where today's equivalent failure is theft. What it costs:
- Fork:
withGroupBasepointsgains the HTLC basepoint,htlcBaseSecretbecomes a poison pill and per-commitmentourHtlcKeynullable (KeyManager.kt:227-228,241,252,264), and the four claim/HTLC constructors guard on null exactly as the existing four group-output guards do (Helpers.kt:531,697,787,1011).HtlcSuccessTx/HtlcTimeoutTxfrom our own commitment become group-keyed too (Transactions.kt:436,485), so every force close with in-flight HTLCs — not just attack scenarios — needs per-HTLC FROST sessions inside the CLTV window. The claims are built and signed at claim time, so the feerate is fresh; each pays the group's onchain wallet. - App:
GroupLightningDerivationgains child index 2 besidePAYMENT/DELAYED_PAYMENT(GroupLightningDerivation.kt:50-51,80-87); the sweep machinery (GroupSweep, the FROSTSWEEPsubject) gains the offered/received HTLC leaves, rebuilt by each member from its own basepoints with the tweak carried in the proposal, as the existing leaves are; the preimage travels with the claim proposal — it is revealed on chain anyway. - Deployment: a channel's basepoints are fixed in
open_channel, so this applies only to channels opened after the change. Existing channels keep the exposure until closed; the natural vehicle is the next wallet rotation (docs/group-lightning-wallet.md, Phase 14), and every device needs the new build before the group opens the new channel — the Phase 15 rule again.
Go/no-go. Go requires all of: (1) a regtest run with an HTLC in flight at a force close —
the current run has none (docs/group-lightning-wallet.md:190-191) — showing the group claim
completing well inside the 144-block window; (2) measured FROST session latency from the
sweep path, showing 2t-1 devices convene in hours, not days, for realistic groups; (3) a fork
diff that stays behind the basepoints seam, per the parity plan's rule for surviving upstream
bumps. No-go leaves Phase 2's bound as the standing mitigation and records the decision in
the design doc's appendix. Recommendation: run the spike only after Phases 1-2 have shipped
and the bound has been lived with; the exposure is then capped at a group-signed number, and
elimination is a liveness-versus-theft trade that a real group should make with measurements
in hand.
What this does not fix
- Phase 2 bounds the exposure at the statement's cap; it does not remove it. Until Phase 3
lands a go, a current or past operator can still take up to that much of in-flight incoming
value.
signer-hygiene.mdis the plan for the seed's handling at rest. - The griefing that triggers the attack — sending
errorto force the LSP to close — is unchanged; it isgriefing-surface.md's subject. This plan only caps what the close pays the attacker. ClaimHtlcTimeoutTx(refunds of offered HTLCs) shares the free-final-script mechanism (Transactions.kt:722); those amounts are already inside the statement cap, and Phase 3 would cover them incidentally.- The adjacent review findings are their own plans: the force-close fence signing a revoked
commitment (
force-close-revoked-commitment.md), the first-commitment policy exemption this phase depends on (first-commitment-policy.md), the mutual-close amount anchored to the operator's claim (mutual-close-amount.md), and the restored device's empty ledger — which also empties theincomingmap Phase 1's cross-check reads (restored-device-marks.md). - A successful theft is detected only after the fact: Phase 1's screen shows the exposure, and the payments list would show a settled payment whose balance never arrived. Nothing here raises an alarm in time to stop it; the bound is the mitigation, not detection.
Risks and open questions
| risk | why it matters | what to do |
|---|---|---|
| mixed-build groups during Phase 2 | any echo quorum drawn from old builds still signs over-cap commitments; for 2-of-4 that is any three devices | the proposal screen names un-upgraded members, as the ceremony screen names non-answerers; the group treats the bound as real only once every device is upgraded |
reusing inFlightCapSat couples send and receive |
a group that wants a 600,000-sat receive must raise the cap, raising the offered-side bound with it | stated on the proposal screen; a dedicated incoming cap is the follow-up when the statement's format next changes, deployed with the Phase 15 rule |
| any-amount invoices and offer payments over the cap fail | a receive the group wanted dies at update_add_htlc, looking like an LSP error |
the receive screen shows the cap before the invoice, as it already shows the liquidity fee |
| a co-signer refusal wedges the channel if the operator is hostile | the unwedge needs the operator to ask for the failing commitment; a hostile one can prefer the force close | accepted: the force close pays the group under D5, and the refusal is what kept the excess out of every signed commitment |
| Phase 3 trades theft for a liveness requirement | a group that cannot convene 2t-1 devices inside the CLTV window after a force close loses incoming payments it was owed | the go/no-go measurements; the honest failure mode is still better than today's, but it is new, and the doc's time-criticality sentence was written about exactly this |
| an ex-operator's old unpaid invoices | their preimages outlive their term, so the exposure survives handovers until the invoices expire | invoices have an expiry (NodeParams.kt:174-175); the residual window is the invoice lifetime, and Phase 14's re-key with a new seed closes it at rotation |
| two devices running one node id | the impersonation step of the attack may interact with the LSP's peer storage and data-loss protection in ways not yet traced | open question, recorded for the Phase 3 spike; out of scope here because the claim path needs no channel state at all |