AI-generated analysisPublished automatically and not human-verified. Validated context appears in community notes below.
← Watch feed
Informational 17 Bitcoin

lightningd: update graceful notifications when HTLC states change

Public commit record

What the developer wrote

Authored by Ken Sedgwick

91/100 · Strong
lightningd: update graceful notifications when HTLC states change

The graceful command notifies watchers about the closest-expiry HTLC,
including its state, whenever that message changes. But nothing
re-evaluated the message when an HTLC changed state: only HTLC
removal, peer disconnect and another graceful invocation re-ran the
check. If graceful was invoked while a commitment dance was in
flight, the initial notification named a transient state (e.g.
RCVD_ADD_REVOCATION) and no follow-up ever announced the settled
state.

test_graceful_htlc waits for exactly that follow-up (since 6994681ae
"flake: Fix test_graceful_htlc to be flexible for notifs"), so it
times out whenever graceful catches the dance mid-flight, which
valgrind CI runs make likely. In one CI failure graceful caught the
outgoing HTLC in RCVD_ADD_REVOCATION, the dance completed 600ms
later, and no notification followed for the remaining 180 seconds.

Re-check graceful progress in the handlers that advance HTLC states
(peer_sending_commitsig, peer_got_commitsig, peer_got_revoke). The
check is a no-op unless a graceful command is outstanding, and
identical messages are already deduplicated.

The dance now generates transient-state notifications, so rewrite the
test to match expected notifications as an ordered subsequence
instead of by exact index. That also removes two accidents the old
indexing depended on: the RCVD_ADD_REVOCATION special case (the
settled state now always notifies), and the wait for a notification
after l1's disconnect, which was really satisfied by the graceful(1)
call's own initial notification arriving on the shared rpc socket --
the disconnect itself never notifies, since the message text
describes the still-connected peer l3 and does not change.

Fixes: https://github.com/ElementsProject/lightning/issues/9219
Changelog-Fixed: JSON-RPC: `graceful` notifications now update when a pending HTLC changes state.
✓ Specific, descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context✓ Mentions testing or verification✓ Links an issue, advisory, or supporting reference
The short version

What changed, and why it matters

This commit fixes a notification bug in Core Lightning's `graceful` JSON-RPC command. The `graceful` command tells users about the next pending payment (HTLC) that is closest to expiring, including its current state. Previously, if a user ran `graceful` while a channel update was in progress, the notification could show a temporary state (like RCVD_ADD_REVOCATION) and never update again when the HTLC reached its final settled state. The fix re-checks and sends updated notifications whenever HTLC states advance during the normal commitment dance. There is no security vulnerability here; it is a correctness and test-flakiness fix for user-facing status notifications.

Recommended action

No security action required. Treat as a normal bug fix / reliability improvement. Reviewers may verify that the added `check_graceful_shutdown` calls do not introduce performance concerns or unintended notification spam; the existing deduplication logic appears to mitigate this.

Security signals we found

01

No memory safety, authentication, authorization, or cryptographic issues present in diff

02

Change is purely a notification/state-update correctness fix

03

No input parsing or external data handling changes

04

No privilege boundary crossed

Risk score

Why this scored 17/100

Our methodology →
Potential impact 2/30
Exploitability 0/25
Stealth signal 0/15
Affected reach 2/15
Confidence 9/10
Evidence quality 4/5
Human-validated context

Community notes

Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.

No validated notes yet.

The AI analysis stands alone for now. Submit a note if you can add evidence or important context.