What changed, and why it matters
This commit only adds documentation to the release notes. It describes a previously merged code change (PR 11555) about how LND handles invoice finality, but the commit itself contains no code, bug fixes, or behavior changes. There is nothing in this commit that introduces or fixes a security issue directly.
No action needed for this documentation commit. Review the actual implementation in PR 11555 separately if a security assessment of the invoice finality change is required.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The commit adds an 87-line markdown file under docs/release-notes/unreleased/11555.md. It documents invoice collection finality semantics, RPC state changes, breaking changes, and database behavior related to PR 11555. The diff is purely documentation; no source code, configuration, or executable logic is modified.
Changed components
docs/release-notes/unreleased/11555.mdInspect captured patch +87 / −0
### docs/release-notes/unreleased/11555.md
@@ -0,0 +1,87 @@
+# Bug Fixes
+
+* [Ordinary invoices](https://github.com/lightningnetwork/lnd/pull/11555), including MPP, keysend and hold invoices, now wait for
+ final HTLC outcomes before reporting settlement.
+ Releasing the preimage moves the invoice and its HTLCs to `PENDING_SETTLE`.
+ The invoice stays pending until every released payment HTLC is final,
+ including any on-chain claim. It becomes `SETTLED` only if all were
+ collected. If any failed, it becomes `CANCELED` while retaining the amount
+ actually received; cancellation does not refund successful HTLCs. Attempts
+ canceled before preimage release do not prevent a later payment from
+ settling. Automatic startup cleanup and the canceled-invoice deletion RPC
+ preserve ordinary release history, even when all released HTLCs failed and
+ no funds were collected.
+ AMP retains its existing release-time set settlement semantics;
+ AMP finality is deferred.
+
+# Improvements
+
+## RPC Updates
+
+* The [invoice and HTLC state enums](https://github.com/lightningnetwork/lnd/pull/11555) expose `PENDING_SETTLE` for ordinary
+ preimage releases.
+ Single-invoice subscriptions report this intermediate state, while
+ `SubscribeInvoices` waits for the first final settlement. The settlement
+ index is assigned at finalization. Pending HTLCs have no RPC resolution
+ timestamp. Applications must distinguish released preimages from final
+ payment credit and check the final paid amount.
+
+* [Released collection failures](https://github.com/lightningnetwork/lnd/pull/11555)
+ are exposed as HTLC `FAILED`, separately from pre-release `CANCELED`.
+ The output-only `preimage_released` flag derives the release decision from
+ existing ordinary invoice and HTLC states, including failed collection.
+ A known `r_preimage` alone does not establish release. The flag is not
+ supported for AMP invoices and is false for them.
+
+* An [already-settled ordinary invoice](https://github.com/lightningnetwork/lnd/pull/11555) can receive later
+ duplicate HTLCs
+ that are pending settlement.
+ Its parent stays `SETTLED`, and finalizing those children preserves the
+ original settlement index. A settled parent therefore does not imply that
+ every later child is final. Its paid amount includes pending children until
+ their outcomes are known and excludes children that fail.
+
+## Breaking Changes
+
+* An [ordinary invoice](https://github.com/lightningnetwork/lnd/pull/11555)
+ can now become `CANCELED` after its preimage was
+ released if collection failed. Clients must check `preimage_released` and
+ HTLC outcomes; cancellation alone must not trigger a counterpart refund or
+ hash reuse on the assumption that the secret stayed private. The release
+ flag records lnd's decision, not proof that the payer received the secret;
+ false does not guarantee the secret is unknown elsewhere.
+
+* [Upgrading](https://github.com/lightningnetwork/lnd/pull/11555) does not require settling existing invoices first.
+ Existing
+ `OPEN` and `ACCEPTED` invoices, including hold invoices, continue normally;
+ preimages released after the upgrade use `PENDING_SETTLE`. Payments an older
+ version already released and marked `SETTLED` retain their old state and
+ remain claimable on chain. Their finality is not retroactively reconciled,
+ and historical outcome records that were never stored are not recreated.
+
+* Before [downgrading](https://github.com/lightningnetwork/lnd/pull/11555) to a version without the pending states,
+ ensure that no ordinary
+ invoice or HTLC remains `PENDING_SETTLE`. List all invoices across every
+ parent state and follow pagination using `last_index_offset` until all
+ records have been inspected. Check each invoice's HTLC states as well as its
+ parent state. `listinvoices --pending_only` is insufficient because it omits
+ pending duplicate children beneath settled parents. Wait for pending work
+ to finalize before downgrading. A failed released HTLC is persisted with
+ the new internal `HtlcStateFailed` value, exposed as `FAILED` over RPC.
+ Downgrade to a binary without that state is unsupported once such a failure
+ has been stored, even if its parent is terminal. Include failed children in
+ the paginated inspection; a terminal parent alone does not establish
+ downgrade safety.
+
+# Technical and Architectural Updates
+
+## Database
+
+* [On-chain final HTLC outcomes](https://github.com/lightningnetwork/lnd/pull/11555) are persisted regardless of
+ `--store-final-htlc-resolutions`
+ so restart recovery can distinguish a reclaim from success. Off-chain
+ outcome storage remains controlled by that option. Ordinary recovery uses
+ recorded outcomes before channel inference, rechecks records after a scan,
+ and periodically retries unresolved channel evidence. The existing processed
+ forwarding-package marker is persisted before an exit-hop callback can
+ release a preimage, preserving the replay path across restart.Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.