Merge pull request #11555 from yyforyongyu/invoice-settlement-public
What changed, and why it matters
This large LND patch changes when an ordinary invoice is considered 'paid'. Previously, releasing the preimage (the secret that lets the payer claim the funds) immediately marked the invoice as settled. Now the invoice enters a new intermediate 'PENDING_SETTLE' state and only becomes 'SETTLED' once every released HTLC is finally resolved on-chain or off-chain. If a released HTLC is instead reclaimed by the payer on-chain, the invoice can become 'CANCELED' while keeping any funds that did arrive. The change also persists on-chain HTLC outcomes even when the optional final-resolution storage is disabled, so restart recovery can tell a successful claim from a reclaim. This is a defensive correctness fix: it prevents a merchant from treating a payment as complete before it is truly irreversible, which could lead to shipping goods for a payment that later fails.
Review RPC clients and accounting integrations that assume an invoice reaching SETTLED is permanent and that cancellation implies no preimage was released. Update them to handle ContractPendingSettle, the new HtlcStateFailed, and the preimage_released flag. Before downgrading, ensure no ordinary invoice or HTLC remains in PENDING_SETTLE and no HtlcStateFailed records exist. Operators should plan to run this or a later version rather than downgrade across the state change.
Security signals we found
New intermediate invoice/HTLC state prevents premature settlement reporting
On-chain HTLC outcomes persisted without opt-in to support restart recovery
Forwarding package marker persisted before preimage release to avoid replay rejection on restart
Tweakless data-loss close now records ChanStatusLocalDataLoss before archiving
Canceled-invoice deletion now preserves ordinary invoices with released HTLC history
RPC exposes new PENDING_SETTLE and FAILED states plus preimage_released flag
Evidence from the diff
The commit introduces a new invoice contract state ContractPendingSettle and HTLC states HtlcStatePendingSettle/HtlcStateFailed. When an ordinary invoice’s preimage is released, the invoice and its HTLCs move to PENDING_SETTLE instead of SETTLED. A new FinalHtlcSource (backed by the HTLC notifier and channel state DB) delivers final outcomes to the invoice registry; only after all released HTLCs are final does the invoice become SETTLED, and any failed released HTLC can push it to CANCELED while preserving AmtPaid from successful ones. On-chain final HTLC outcomes are now always persisted regardless of –store-final-htlc-resolutions, because invoice recovery depends on them. The forwarding-package processed marker is made durable before exit-hop callbacks can release a preimage, preventing replay rejection on restart. AMP invoices keep their existing release-time settlement semantics. The change is breaking for RPC clients because ordinary invoices can now be CANCELED after preimage release, and PENDING_SETTLE appears in subscriptions.
Changed components
invoices.InvoiceRegistryinvoices.InvoiceDB (KV and SQL backends)htlcswitch.channelLink exit-hop processingcontractcourt.chainWatcher tweakless close pathchanneldb.ChannelStateDB final HTLC outcome storagelnrpc invoice/HTLC state enums and swagger/proto definitionsInspect captured patch +4536 / −320
### channeldb/channel_test.go
@@ -1797,6 +1797,46 @@ func TestFinalHtlcs(t *testing.T) {
require.ErrorIs(t, err, ErrHtlcUnknown)
}
+// TestOnchainFinalHtlcsWithoutOptIn asserts that on-chain final htlc outcomes
+// are stored even if the user did not opt in to storing final resolutions,
+// because the invoice registry relies on them.
+func TestOnchainFinalHtlcsWithoutOptIn(t *testing.T) {
+ t.Parallel()
+
+ // Arrange: Use the default opt-out for final resolution history so
+ // recovery cannot depend on an operator enabling optional records.
+ fullDB, err := MakeTestDB(t)
+ require.NoError(t, err, "unable to make test database")
+
+ cdb := fullDB.ChannelStateDB()
+
+ chanID := lnwire.ShortChannelID{
+ BlockHeight: 1,
+ TxIndex: 2,
+ TxPosition: 3,
+ }
+
+ // Act: Persist both a successful claim and a payer reclaim through
+ // the on-chain path that must retain evidence for invoice recovery.
+ err = cdb.PutOnchainFinalHtlcOutcome(chanID, 1, true)
+ require.NoError(t, err)
+
+ err = cdb.PutOnchainFinalHtlcOutcome(chanID, 2, false)
+ require.NoError(t, err)
+
+ // Assert: Read each outcome back and distinguish its result and
+ // on-chain origin, including the failure that must prevent credit.
+ info, err := cdb.LookupFinalHtlc(chanID, 1)
+ require.NoError(t, err)
+ require.True(t, info.Settled)
+ require.False(t, info.Offchain)
+
+ info, err = cdb.LookupFinalHtlc(chanID, 2)
+ require.NoError(t, err)
+ require.False(t, info.Settled)
+ require.False(t, info.Offchain)
+}
+
// TestHTLCsExtraData tests serialization and deserialization of HTLCs
// combined with extra data.
func TestHTLCsExtraData(t *testing.T) {
### channeldb/db.go
@@ -2179,14 +2179,16 @@ func (c *ChannelStateDB) LookupFinalHtlc(chanID lnwire.ShortChannelID,
// PutOnchainFinalHtlcOutcome stores the final on-chain outcome of an htlc in
// the database.
+//
+// NOTE: Unlike off-chain outcomes, on-chain outcomes are stored even if the
+// user did not opt in to storing final resolutions. The invoice registry
+// relies on them to learn the final outcome of an htlc it released the
+// preimage for if it missed the notification, for example because lnd shut
+// down right after the htlc was resolved. On-chain resolutions are rare, so
+// the records don't add up the way off-chain ones would.
func (c *ChannelStateDB) PutOnchainFinalHtlcOutcome(
chanID lnwire.ShortChannelID, htlcID uint64, settled bool) error {
- // Skip if the user did not opt in to storing final resolutions.
- if !c.parent.storeFinalHtlcResolutions {
- return nil
- }
-
return kvdb.Update(c.backend, func(tx kvdb.RwTx) error {
finalHtlcsBucket, err := fetchFinalHtlcsBucketRw(tx, chanID)
if err != nil {
### channeldb/invoices.go
@@ -476,6 +476,33 @@ func fetchInvoiceNumByRef(invoiceIndex, payAddrIndex, setIDIndex kvdb.RBucket,
func (d *DB) FetchPendingInvoices(_ context.Context) (
map[lntypes.Hash]invpkg.Invoice, error) {
+ return d.fetchInvoices(func(invoice *invpkg.Invoice) bool {
+ return invoice.IsPending()
+ })
+}
+
+// FetchPendingSettleInvoices returns all invoices that contain at least one
+// htlc whose final outcome is still pending. The KV backend has no index over
+// htlc states, so it discovers them by scanning the invoice bucket.
+func (d *DB) FetchPendingSettleInvoices(_ context.Context) (
+ map[lntypes.Hash]invpkg.Invoice, error) {
+
+ return d.fetchInvoices(func(invoice *invpkg.Invoice) bool {
+ for _, htlc := range invoice.Htlcs {
+ if htlc.State == invpkg.HtlcStatePendingSettle {
+ return true
+ }
+ }
+
+ return false
+ })
+}
+
+// fetchInvoices returns all invoices matching the given predicate. The result
+// is keyed by payment hash.
+func (d *DB) fetchInvoices(predicate func(*invpkg.Invoice) bool) (
+ map[lntypes.Hash]invpkg.Invoice, error) {
+
result := make(map[lntypes.Hash]invpkg.Invoice)
err := kvdb.View(d, func(tx kvdb.RTx) error {
@@ -510,7 +537,7 @@ func (d *DB) FetchPendingInvoices(_ context.Context) (
return err
}
- if invoice.IsPending() {
+ if predicate(&invoice) {
var paymentHash lntypes.Hash
copy(paymentHash[:], k)
result[paymentHash] = invoice
@@ -878,6 +905,9 @@ func (k *kvInvoiceUpdater) Finalize(updateType invpkg.UpdateType) error {
// invoice. All HTLCs which were accepted are now canceled, so
// we persist this state.
return k.storeCancelHtlcsUpdate()
+
+ case invpkg.FinalizeHTLCsUpdate:
+ return k.storeFinalizeHtlcsUpdate()
}
return fmt.Errorf("unknown update type: %v", updateType)
@@ -925,18 +955,8 @@ func (k *kvInvoiceUpdater) storeAddHtlcsUpdate() error {
}
}
- // If this is a non-AMP invoice, then the state can eventually go to
- // ContractSettled, so we pass in nil value as part of
- // setSettleMetaFields.
- if !invoiceIsAMP && k.invoice.State == invpkg.ContractSettled {
- err := k.setSettleMetaFields(nil)
- if err != nil {
- return err
- }
- }
-
- // As we don't update the settle index above for AMP invoices, we'll do
- // it here for each sub-AMP invoice that was settled.
+ // Ordinary invoices allocate their index at finalization. AMP keeps
+ // allocating its existing per-set settlement index at preimage release.
for settledSetID := range k.settledSetIDs {
err := k.setSettleMetaFields(&settledSetID)
if err != nil {
@@ -960,11 +980,22 @@ func (k *kvInvoiceUpdater) storeAddHtlcsUpdate() error {
}
// storeSettleHodlInvoiceUpdate updates the invoice in the database after
-// settling a hodl invoice.
+// releasing a hodl preimage. Finalization assigns its settlement index.
func (k *kvInvoiceUpdater) storeSettleHodlInvoiceUpdate() error {
- err := k.setSettleMetaFields(nil)
- if err != nil {
- return err
+ return k.serializeAndStoreInvoice()
+}
+
+// storeFinalizeHtlcsUpdate persists final ordinary outcomes and assigns the
+// first settlement index only once. Later duplicate HTLCs retain the parent
+// index, and AMP keeps allocating its set metadata in storeAddHtlcsUpdate.
+func (k *kvInvoiceUpdater) storeFinalizeHtlcsUpdate() error {
+ if k.invoice.State == invpkg.ContractSettled &&
+ k.invoice.SettleIndex == 0 {
+
+ err := k.setSettleMetaFields(nil)
+ if err != nil {
+ return err
+ }
}
return k.serializeAndStoreInvoice()
@@ -2214,7 +2245,8 @@ func delAMPSettleIndex(invoiceNum []byte, invoices,
return nil
}
-// DeleteCanceledInvoices deletes all canceled invoices from the database.
+// DeleteCanceledInvoices deletes canceled invoices, preserving ordinary
+// invoices with settled or failed released HTLCs so release history survives.
func (d *DB) DeleteCanceledInvoices(_ context.Context) error {
return kvdb.Update(d, func(tx kvdb.RwTx) error {
invoices := tx.ReadWriteBucket(invoiceBucket)
@@ -2259,6 +2291,19 @@ func (d *DB) DeleteCanceledInvoices(_ context.Context) error {
return nil
}
+ // Failed collection does not undo release. Keep the
+ // history even when every released HTLC failed.
+ for _, htlc := range invoice.Htlcs {
+ if invoice.IsAMP() {
+ continue
+ }
+ if htlc.State == invpkg.HtlcStateSettled ||
+ htlc.State == invpkg.HtlcStateFailed {
+
+ return nil
+ }
+ }
+
// Delete the payment hash from the invoice index.
err = invoiceIndex.Delete(k)
if err != nil {
### contractcourt/chain_watcher.go
@@ -1257,6 +1257,17 @@ func (c *chainWatcher) handleUnknownRemoteState(
commitPoint.SerializeCompressed(),
c.cfg.chanState.FundingOutpoint)
} else {
+ // Tweakless recovery skips reestablishment, so it must record
+ // lost-state evidence itself before the close is archived. The
+ // legacy path obtains this marker with its commitment point.
+ err := c.cfg.chanState.ApplyChanStatus(
+ chanstate.ChanStatusLocalDataLoss,
+ )
+ if err != nil {
+ return false, fmt.Errorf("unable to mark local data "+
+ "loss: %w", err)
+ }
+
log.Infof("ChannelPoint(%v) is tweakless, "+
"moving to sweep directly on chain",
c.cfg.chanState.FundingOutpoint)
### contractcourt/chain_watcher_test.go
@@ -15,9 +15,11 @@ import (
"github.com/lightningnetwork/lnd/chanstate"
"github.com/lightningnetwork/lnd/fn/v2"
"github.com/lightningnetwork/lnd/input"
+ "github.com/lightningnetwork/lnd/kvdb"
lnmock "github.com/lightningnetwork/lnd/lntest/mock"
"github.com/lightningnetwork/lnd/lnwallet"
"github.com/lightningnetwork/lnd/lnwire"
+ "github.com/stretchr/testify/mock"
"github.com/stretchr/testify/require"
)
@@ -735,3 +737,107 @@ func TestChainWatcherLocalForceCloseDetect(t *testing.T) {
})
}
}
+
+// TestChainWatcherUnknownRemoteDataLoss checks that an unknown tweakless close
+// records lost-state evidence without prior channel reestablishment.
+func TestChainWatcherUnknownRemoteDataLoss(t *testing.T) {
+ tests := []struct {
+ name string
+ failWrite bool
+ }{
+ {
+ name: "without reestablishment",
+ },
+ {
+ name: "status write fails",
+ failWrite: true,
+ },
+ }
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ t.Parallel()
+
+ // Arrange: Keep an older real channel DB while the peer
+ // has a later tweakless commitment. Seed no lost-state
+ // marker or reestablishment commitment point.
+ alice, bob, err := lnwallet.CreateTestChannels(
+ t, channeldb.SingleFunderTweaklessBit,
+ )
+ require.NoError(t, err)
+ states, err := executeStateTransitions(
+ t, 1000, alice, bob, 2,
+ )
+ require.NoError(t, err)
+ state := states[1]
+ require.False(t, state.HasChanStatus(
+ chanstate.ChanStatusLocalDataLoss,
+ ))
+ _, err = state.DataLossCommitPoint()
+ require.ErrorIs(t, err, channeldb.ErrNoCommitPoint)
+
+ // Drive the confirmed-close handler synchronously; the
+ // constructor needs one spend registration. The close
+ // event can then be read without an observer goroutine.
+ notifier := &chainntnfs.MockChainNotifier{}
+ notifier.On("RegisterSpendNtfn", &state.FundingOutpoint,
+ mock.Anything, state.DeriveHeightHint()).Return(
+ &chainntnfs.SpendEvent{}, nil,
+ ).Once()
+ watcher, err := newChainWatcher(chainWatcherConfig{
+ chanState: state,
+ notifier: notifier,
+ signer: alice.Signer,
+ })
+ require.NoError(t, err)
+ events := watcher.SubscribeChannelEvents()
+ defer events.Cancel()
+ set, err := newChainSet(state)
+ require.NoError(t, err)
+ commit := bob.State().LocalCommitment
+ hash := commit.CommitTx.TxHash()
+ spend := &chainntnfs.SpendDetail{
+ SpenderTxHash: &hash,
+ SpendingTx: commit.CommitTx,
+ }
+ if test.failWrite {
+ require.NoError(t, testChannelStateDB(t, state).
+ GetParentDB().Close())
+ }
+
+ // Act: Handle the unknown remote commitment directly so
+ // its storage error and close event are observable.
+ handled, err := watcher.handleUnknownRemoteState(
+ spend, commit.CommitHeight, set,
+ )
+
+ // Assert: A failed write leaves the close unpublished.
+ // Success must persist the marker in a fresh DB read,
+ // proving it survives beyond the in-memory channel.
+ if test.failWrite {
+ require.ErrorIs(t, err, kvdb.ErrDatabaseNotOpen)
+ require.False(t, handled)
+ select {
+ case <-events.RemoteUnilateralClosure:
+ t.Fatal("close after failed write")
+ default:
+ }
+ } else {
+ require.NoError(t, err)
+ require.True(t, handled)
+ stored, err := state.Db.FetchChannel(
+ state.FundingOutpoint,
+ )
+ require.NoError(t, err)
+ require.True(t, stored.HasChanStatus(
+ chanstate.ChanStatusLocalDataLoss,
+ ))
+ select {
+ case <-events.RemoteUnilateralClosure:
+ default:
+ t.Fatal("close was not published")
+ }
+ }
+ notifier.AssertExpectations(t)
+ })
+ }
+}
### 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.
### final_htlc_source_test.go
@@ -0,0 +1,78 @@
+package lnd
+
+import (
+ "testing"
+ "time"
+
+ "github.com/lightningnetwork/lnd/channeldb"
+ "github.com/lightningnetwork/lnd/graph/db/models"
+ "github.com/lightningnetwork/lnd/htlcswitch"
+ "github.com/lightningnetwork/lnd/invoices"
+ "github.com/lightningnetwork/lnd/lnwire"
+ "github.com/stretchr/testify/require"
+)
+
+// TestFinalHtlcSourceSubscribe checks final-event filtering and the real
+// subscription's cancellation contract.
+func TestFinalHtlcSourceSubscribe(t *testing.T) {
+ t.Parallel()
+
+ // Arrange: Use the real notifier so forwarding and cancellation cover
+ // the source goroutine and its subscription lifecycle together.
+ notifier := htlcswitch.NewHtlcNotifier(time.Now)
+ require.NoError(t, notifier.Start())
+ t.Cleanup(func() {
+ require.NoError(t, notifier.Stop())
+ })
+
+ s := &server{
+ htlcNotifier: notifier,
+ }
+ source := invoices.NewFinalHtlcSource(nil, s.subscribeFinalInvoiceHtlcs)
+ outcomes, cancel, err := source.SubscribeFinalHtlcs()
+ require.NoError(t, err)
+ t.Cleanup(cancel)
+
+ key := models.CircuitKey{
+ ChanID: lnwire.NewShortChanIDFromInt(1),
+ HtlcID: 7,
+ }
+
+ // Act: Publish an intermediate settle before its final outcome; only
+ // the latter can be used to finalize the ordinary invoice payment.
+ notifier.NotifySettleEvent(
+ htlcswitch.HtlcKey{IncomingCircuit: key},
+ [32]byte{}, htlcswitch.HtlcEventTypeReceive,
+ )
+ notifier.NotifyFinalHtlcEvent(key, channeldb.FinalHtlcInfo{
+ Settled: true,
+ Offchain: true,
+ })
+
+ // Assert: Delivery includes the final result and its off-chain origin,
+ // while the intermediate settlement event is filtered out.
+ select {
+ case outcome := <-outcomes:
+ require.Equal(t, invoices.FinalHtlcOutcome{
+ Key: key,
+ Settled: true,
+ Offchain: true,
+ }, outcome)
+ case <-time.After(5 * time.Second):
+ t.Fatal("no final htlc outcome received")
+ }
+
+ // Act: Cancel twice to exercise idempotent shutdown. Cleanup owns the
+ // same cancellation if an earlier assertion fails.
+ cancel()
+ cancel()
+
+ // Assert: Cancellation waits for the producer to close its output, so
+ // stopping the consumer cannot leave a blocked event-forwarding sender.
+ select {
+ case _, ok := <-outcomes:
+ require.False(t, ok)
+ case <-time.After(5 * time.Second):
+ t.Fatal("outcome channel not closed")
+ }
+}
### htlcswitch/link.go
@@ -3159,6 +3159,11 @@ func (l *channelLink) processRemoteAdds(fwdPkg *channeldb.FwdPkg) {
var switchPackets []*htlcPacket
+ // Exit-hop callbacks may release preimages. Delay them until the
+ // existing processed marker is durable, so restart bypasses onion
+ // replay rejection for any HTLC whose preimage we have released.
+ var exitHopCallbacks []func() error
+
for i, update := range unackedAdds {
idx := update.index
sourceRef := fwdPkg.SourceRef(idx)
@@ -3300,17 +3305,14 @@ func (l *channelLink) processRemoteAdds(fwdPkg *channeldb.FwdPkg) {
switch {
case fwdInfo.IsExit():
- err := l.processExitHop(
- add, sourceRef, obfuscator, fwdInfo,
- heightNow, pld,
+ exitHopCallbacks = append(
+ exitHopCallbacks, func() error {
+ return l.processExitHop(
+ add, sourceRef, obfuscator,
+ fwdInfo, heightNow, pld,
+ )
+ },
)
- if err != nil {
- l.failf(LinkFailureError{
- code: ErrInternalError,
- }, "%v", err)
-
- return
- }
// There are additional channels left within this route. So
// we'll simply do some forwarding package book-keeping.
@@ -3487,6 +3489,19 @@ func (l *channelLink) processRemoteAdds(fwdPkg *channeldb.FwdPkg) {
}
}
+ // Run invoice callbacks synchronously in their original order, after
+ // the persistence barrier and before handing packets to the switch.
+ for _, callback := range exitHopCallbacks {
+ if err := callback(); err != nil {
+ l.failf(
+ LinkFailureError{code: ErrInternalError},
+ "%v", err,
+ )
+
+ return
+ }
+ }
+
if len(switchPackets) == 0 {
return
}
### htlcswitch/link_test.go
@@ -41,6 +41,7 @@ import (
"github.com/lightningnetwork/lnd/lnwire"
"github.com/lightningnetwork/lnd/ticker"
"github.com/lightningnetwork/lnd/tlv"
+ "github.com/stretchr/testify/mock"
"github.com/stretchr/testify/require"
)
@@ -1396,14 +1397,15 @@ func TestUpdateForwardingPolicy(t *testing.T) {
require.NoError(t, err, "unable to send payment")
// Carol's invoice should now be shown as settled as the payment
- // succeeded.
- invoice, err := n.carolServer.registry.LookupInvoice(
- t.Context(), payResp,
- )
- require.NoError(t, err, "unable to get invoice")
- if invoice.State != invpkg.ContractSettled {
- t.Fatal("carol invoice haven't been settled")
- }
+ // succeeded, once her settle is locked in.
+ require.Eventually(t, func() bool {
+ invoice, err := n.carolServer.registry.LookupInvoice(
+ t.Context(), payResp,
+ )
+
+ return err == nil && invoice.State == invpkg.ContractSettled
+ }, 5*time.Second, 10*time.Millisecond,
+ "carol invoice haven't been settled")
expectedAliceBandwidth := aliceBandwidthBefore - htlcAmt
if expectedAliceBandwidth != n.aliceChannelLink.Bandwidth() {
@@ -2235,17 +2237,19 @@ func newSingleLinkTestHarness(t *testing.T, chanAmt,
PendingCommitTicker: ticker.New(time.Minute),
// Make the BatchSize and Min/MaxUpdateTimeout large enough
// to not trigger commit updates automatically during tests.
- BatchSize: 10000,
- MinUpdateTimeout: 30 * time.Minute,
- MaxUpdateTimeout: 40 * time.Minute,
- MaxOutgoingCltvExpiry: DefaultMaxOutgoingCltvExpiry,
- MaxFeeAllocation: DefaultMaxLinkFeeAllocation,
- NotifyActiveLink: func(wire.OutPoint) {},
- NotifyActiveChannel: func(wire.OutPoint) {},
- NotifyChannelUpdate: func(*cstate.OpenChannel) {},
- NotifyInactiveChannel: func(wire.OutPoint) {},
- NotifyInactiveLinkEvent: func(wire.OutPoint) {},
- HtlcNotifier: aliceSwitch.cfg.HtlcNotifier,
+ BatchSize: 10000,
+ MinUpdateTimeout: 30 * time.Minute,
+ MaxUpdateTimeout: 40 * time.Minute,
+ MaxOutgoingCltvExpiry: DefaultMaxOutgoingCltvExpiry,
+ MaxFeeAllocation: DefaultMaxLinkFeeAllocation,
+ NotifyActiveLink: func(wire.OutPoint) {},
+ NotifyActiveChannel: func(wire.OutPoint) {},
+ NotifyChannelUpdate: func(*cstate.OpenChannel) {},
+ NotifyInactiveChannel: func(wire.OutPoint) {},
+ NotifyInactiveLinkEvent: func(wire.OutPoint) {},
+ HtlcNotifier: invoiceRegistry.htlcNotifier(
+ aliceSwitch.cfg.HtlcNotifier,
+ ),
GetAliases: getAliases,
ShouldFwdExpAccountability: func() bool { return true },
}
@@ -4046,6 +4050,9 @@ func TestChannelRetransmission(t *testing.T) {
n = newThreeHopNetwork(ct, channels.aliceToBob, channels.bobToAlice,
channels.bobToCarol, channels.carolToBob, testStartingHeight)
n.firstBobChannelLink.cfg.Registry = bobRegistry
+ bobNotifier := n.bobServer.htlcSwitch.cfg.HtlcNotifier
+ n.firstBobChannelLink.cfg.HtlcNotifier =
+ bobRegistry.htlcNotifier(bobNotifier)
n.aliceServer.intersect(aliceInterceptor)
n.bobServer.intersect(bobInterceptor)
@@ -7032,6 +7039,104 @@ func TestChannelLinkExitHopExpiryAtMaximum(t *testing.T) {
ctx.receiveCommitSigAliceToBob(0)
}
+// mockFwdFilterStore injects a forwarding-marker failure while keeping all
+// other channel storage operations on the real database.
+type mockFwdFilterStore struct {
+ cstate.Store
+ mock.Mock
+}
+
+// SetFwdFilter returns the arranged persistence failure before the marker
+// can make any exit-hop callback eligible to release a preimage.
+func (m *mockFwdFilterStore) SetFwdFilter(channel *cstate.OpenChannel,
+ height uint64, filter *cstate.PkgFilter) error {
+
+ args := m.Called(channel, height, filter)
+
+ return args.Error(0)
+}
+
+// Embedding the real store keeps the fault limited to the replay marker.
+var _ cstate.Store = (*mockFwdFilterStore)(nil)
+
+// TestChannelLinkExitSettlePersistence checks that a failed replay-marker
+// write cannot release an invoice preimage or send a fulfill to the peer.
+func TestChannelLinkExitSettlePersistence(t *testing.T) {
+ t.Parallel()
+
+ // Arrange a real invoice and channel, injecting a failure only in the
+ // incoming package marker write. All other storage operations still
+ // reach the actual channel database.
+ harness, err := newSingleLinkTestHarness(
+ t, btcutil.SatoshiPerBitcoin*5, 0,
+ )
+ require.NoError(t, err)
+ link, ok := harness.aliceLink.(*channelLink)
+ require.True(t, ok)
+ registry, ok := link.cfg.Registry.(*mockInvoiceRegistry)
+ require.True(t, ok)
+ peer, ok := link.cfg.Peer.(*mockPeer)
+ require.True(t, ok)
+ state := link.channel.State()
+ store := &mockFwdFilterStore{
+ Store: state.Db,
+ }
+ store.On("SetFwdFilter", state, uint64(1),
+ mock.AnythingOfType("*chanstate.PkgFilter")).
+ Return(fmt.Errorf("marker write failed")).Once()
+ state.Db = store
+ t.Cleanup(func() {
+ store.AssertExpectations(t)
+ })
+ failed := make(chan LinkFailureError, 1)
+ link.cfg.OnChannelFailure = func(_ lnwire.ChannelID,
+ _ lnwire.ShortChannelID, failure LinkFailureError) {
+
+ failed <- failure
+ }
+ htlc, invoice := generateHtlcAndInvoice(t, 0)
+ err = registry.AddInvoice(t.Context(), *invoice, htlc.PaymentHash)
+ require.NoError(t, err)
+ require.NoError(t, harness.start())
+ t.Cleanup(harness.aliceLink.Stop)
+ ctx := linkTestContext{
+ t: t,
+ aliceSwitch: harness.aliceSwitch,
+ aliceLink: harness.aliceLink,
+ aliceMsgs: peer.sentMsgs,
+ bobChannel: harness.bobChannel,
+ }
+
+ // Act by locking in the incoming HTLC through the normal commitment
+ // exchange, causing the link to process its forwarding package.
+ ctx.sendHtlcBobToAlice(htlc)
+ ctx.sendCommitSigBobToAlice(1)
+ ctx.receiveRevAndAckAliceToBob()
+ ctx.receiveCommitSigAliceToBob(1)
+ ctx.sendRevAndAckBobToAlice()
+
+ // Assert the persistence failure is observed before inspecting invoice
+ // state. Join the link before draining peer messages so a late fulfill
+ // cannot hide behind an immediate empty-channel observation.
+ select {
+ case failure := <-failed:
+ require.Equal(t, ErrInternalError, failure.code)
+ case <-time.After(wait.DefaultTimeout):
+ t.Fatal("missing marker failure")
+ }
+ harness.aliceLink.Stop()
+ for len(peer.sentMsgs) > 0 {
+ msg := <-peer.sentMsgs
+ _, fulfilled := msg.(*lnwire.UpdateFulfillHTLC)
+ require.False(t, fulfilled)
+ }
+ stored, err := registry.LookupInvoice(t.Context(), htlc.PaymentHash)
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractOpen, stored.State)
+ require.Empty(t, stored.Htlcs)
+ require.Zero(t, stored.AmtPaid)
+}
+
// TestChannelLinkRevocationWindowRegular asserts that htlcs paying to a regular
// invoice are settled even if the revocation window gets exhausted.
func TestChannelLinkRevocationWindowRegular(t *testing.T) {
### htlcswitch/mock.go
@@ -36,6 +36,8 @@ import (
"github.com/lightningnetwork/lnd/lnwire"
"github.com/lightningnetwork/lnd/ticker"
"github.com/lightningnetwork/lnd/tlv"
+ testifymock "github.com/stretchr/testify/mock"
+ "github.com/stretchr/testify/require"
)
func isAlias(scid lnwire.ShortChannelID) bool {
@@ -1018,6 +1020,85 @@ type mockInvoiceRegistry struct {
settleChan chan lntypes.Hash
registry *invoices.InvoiceRegistry
+
+ // finalHtlcs delivers the final htlc outcomes reported by links to
+ // the registry, so that invoices settle once their htlcs are final.
+ finalHtlcs chan invoices.FinalHtlcOutcome
+}
+
+// mockFinalHtlcSource supplies arranged evidence while the registry fixture
+// owns live outcomes, without duplicating the final-outcome store.
+type mockFinalHtlcSource struct {
+ testifymock.Mock
+}
+
+// SubscribeFinalHtlcs returns the arranged live stream and cancellation
+// callback so the fixture controls the source lifetime explicitly.
+func (m *mockFinalHtlcSource) SubscribeFinalHtlcs() (
+ <-chan invoices.FinalHtlcOutcome, func(), error) {
+
+ args := m.Called()
+ outcomes, _ := args.Get(0).(<-chan invoices.FinalHtlcOutcome)
+ cancel, _ := args.Get(1).(func())
+
+ return outcomes, cancel, args.Error(2)
+}
+
+// LookupFinalHtlcs returns configured durable evidence; link tests normally
+// deliver results live, so nil represents an outcome not recorded yet.
+func (m *mockFinalHtlcSource) LookupFinalHtlcs(keys []invoices.CircuitKey) (
+ map[invoices.CircuitKey]invoices.FinalHtlcOutcome, error) {
+
+ args := m.Called(keys)
+ res, _ :=
+ args.Get(0).(map[invoices.CircuitKey]invoices.FinalHtlcOutcome)
+
+ return res, args.Error(1)
+}
+
+// InferFinalHtlcs returns only arranged channel evidence; these fixtures
+// normally exercise real final notifications instead of recovery inference.
+func (m *mockFinalHtlcSource) InferFinalHtlcs(keys []invoices.CircuitKey) (
+ map[invoices.CircuitKey]invoices.FinalHtlcOutcome, error) {
+
+ args := m.Called(keys)
+ res, _ :=
+ args.Get(0).(map[invoices.CircuitKey]invoices.FinalHtlcOutcome)
+
+ return res, args.Error(1)
+}
+
+var _ invoices.FinalHtlcSource = (*mockFinalHtlcSource)(nil)
+
+// finalHtlcNotifier wraps an htlc notifier and also delivers final htlc
+// outcomes to the registry.
+type finalHtlcNotifier struct {
+ htlcNotifier
+
+ outcomes chan invoices.FinalHtlcOutcome
+}
+
+// NotifyFinalHtlcEvent forwards the final outcome to the wrapped notifier and
+// the registry.
+func (f *finalHtlcNotifier) NotifyFinalHtlcEvent(key models.CircuitKey,
+ info channeldb.FinalHtlcInfo) {
+
+ f.htlcNotifier.NotifyFinalHtlcEvent(key, info)
+
+ f.outcomes <- invoices.FinalHtlcOutcome{
+ Key: key,
+ Settled: info.Settled,
+ Offchain: info.Offchain,
+ }
+}
+
+// htlcNotifier wraps the given notifier so that the registry learns about
+// the final outcome of htlcs.
+func (i *mockInvoiceRegistry) htlcNotifier(n htlcNotifier) htlcNotifier {
+ return &finalHtlcNotifier{
+ htlcNotifier: n,
+ outcomes: i.finalHtlcs,
+ }
}
type mockChainNotifier struct {
@@ -1034,10 +1115,26 @@ func (m *mockChainNotifier) RegisterBlockEpochNtfn(*chainntnfs.BlockEpoch) (
}, nil
}
+// newMockRegistry owns a real registry and an event bridge so link tests
+// learn final outcomes before their shared database is cleaned up.
func newMockRegistry(t testing.TB) *mockInvoiceRegistry {
+ t.Helper()
+
cdb := channeldb.OpenForTesting(t, t.TempDir())
modifierMock := &invoices.MockHtlcModifier{}
+
+ // Buffer outcomes generously so that links never block on the
+ // registry.
+ finalHtlcs := make(chan invoices.FinalHtlcOutcome, 10_000)
+ source := &mockFinalHtlcSource{}
+ source.On("SubscribeFinalHtlcs").Return(
+ (<-chan invoices.FinalHtlcOutcome)(finalHtlcs), func() {}, nil,
+ ).Once()
+ source.On("LookupFinalHtlcs", testifymock.Anything).
+ Return(nil, nil).Maybe()
+ source.On("InferFinalHtlcs", testifymock.Anything).
+ Return(nil, nil).Maybe()
registry := invoices.NewRegistry(
cdb,
invoices.NewInvoiceExpiryWatcher(
@@ -1047,12 +1144,20 @@ func newMockRegistry(t testing.TB) *mockInvoiceRegistry {
&invoices.RegistryConfig{
FinalCltvRejectDelta: 5,
HtlcInterceptor: modifierMock,
+ FinalHtlcSource: source,
},
)
- registry.Start()
+ require.NoError(t, registry.Start())
+ t.Cleanup(func() {
+ // Stop consumers before this one expectation check and the
+ // earlier database cleanup closes their storage backend.
+ require.NoError(t, registry.Stop())
+ source.AssertExpectations(t)
+ })
return &mockInvoiceRegistry{
- registry: registry,
+ registry: registry,
+ finalHtlcs: finalHtlcs,
}
}
### htlcswitch/test_utils.go
@@ -1170,26 +1170,28 @@ func (h *hopNetwork) createChannelLink(server, peer *mockServer,
UpdateContractSignals: func(*contractcourt.ContractSignals) error {
return nil
},
- NotifyContractUpdate: notifyContractUpdate,
- ChainEvents: &contractcourt.ChainEventSubscription{},
- SyncStates: true,
- BatchSize: 10,
- BatchTicker: ticker.NewForce(testBatchTimeout),
- FwdPkgGCTicker: ticker.NewForce(fwdPkgTimeout),
- PendingCommitTicker: ticker.New(2 * time.Minute),
- MinUpdateTimeout: minFeeUpdateTimeout,
- MaxUpdateTimeout: maxFeeUpdateTimeout,
- OnChannelFailure: func(lnwire.ChannelID, lnwire.ShortChannelID, LinkFailureError) {},
- OutgoingCltvRejectDelta: 3,
- MaxOutgoingCltvExpiry: DefaultMaxOutgoingCltvExpiry,
- MaxFeeAllocation: DefaultMaxLinkFeeAllocation,
- MaxAnchorsCommitFeeRate: chainfee.SatPerKVByte(10 * 1000).FeePerKWeight(),
- NotifyActiveLink: func(wire.OutPoint) {},
- NotifyActiveChannel: func(wire.OutPoint) {},
- NotifyInactiveChannel: func(wire.OutPoint) {},
- NotifyInactiveLinkEvent: func(wire.OutPoint) {},
- NotifyChannelUpdate: func(*chanstate.OpenChannel) {},
- HtlcNotifier: server.htlcSwitch.cfg.HtlcNotifier,
+ NotifyContractUpdate: notifyContractUpdate,
+ ChainEvents: &contractcourt.ChainEventSubscription{},
+ SyncStates: true,
+ BatchSize: 10,
+ BatchTicker: ticker.NewForce(testBatchTimeout),
+ FwdPkgGCTicker: ticker.NewForce(fwdPkgTimeout),
+ PendingCommitTicker: ticker.New(2 * time.Minute),
+ MinUpdateTimeout: minFeeUpdateTimeout,
+ MaxUpdateTimeout: maxFeeUpdateTimeout,
+ OnChannelFailure: func(lnwire.ChannelID, lnwire.ShortChannelID, LinkFailureError) {},
+ OutgoingCltvRejectDelta: 3,
+ MaxOutgoingCltvExpiry: DefaultMaxOutgoingCltvExpiry,
+ MaxFeeAllocation: DefaultMaxLinkFeeAllocation,
+ MaxAnchorsCommitFeeRate: chainfee.SatPerKVByte(10 * 1000).FeePerKWeight(),
+ NotifyActiveLink: func(wire.OutPoint) {},
+ NotifyActiveChannel: func(wire.OutPoint) {},
+ NotifyInactiveChannel: func(wire.OutPoint) {},
+ NotifyInactiveLinkEvent: func(wire.OutPoint) {},
+ NotifyChannelUpdate: func(*chanstate.OpenChannel) {},
+ HtlcNotifier: server.registry.htlcNotifier(
+ server.htlcSwitch.cfg.HtlcNotifier,
+ ),
GetAliases: getAliases,
ShouldFwdExpAccountability: func() bool { return true },
},
### invoices/errors.go
@@ -32,6 +32,12 @@ var (
// an invoice while the invoice is not in the open state.
ErrInvoiceCannotAccept = errors.New("cannot accept invoice")
+ // ErrInvoiceCannotSettle is returned when an attempt is made to move an
+ // ordinary invoice to the settled state directly, rather than by
+ // finalizing its htlcs. AMP retains its existing settlement path.
+ ErrInvoiceCannotSettle = errors.New("invoice can only be settled " +
+ "by finalizing its htlcs")
+
// ErrInvoicePreimageMismatch is returned when the preimage doesn't
// match the invoice hash.
ErrInvoicePreimageMismatch = errors.New("preimage does not match")
### invoices/final_htlc_source.go
@@ -0,0 +1,270 @@
+package invoices
+
+import (
+ "errors"
+ "fmt"
+
+ "github.com/lightningnetwork/lnd/chanstate"
+ "github.com/lightningnetwork/lnd/lnwire"
+)
+
+// finalHtlcDB is the part of the channel state database that the final htlc
+// source reads from.
+type finalHtlcDB interface {
+ // HistoricalChannelStore retains channel status after closure, when
+ // summaries alone cannot distinguish restored commitment snapshots.
+ chanstate.HistoricalChannelStore
+
+ // LookupFinalHtlc returns the recorded final outcome of an htlc, or
+ // chanstate.ErrHtlcUnknown.
+ LookupFinalHtlc(chanID lnwire.ShortChannelID,
+ htlcIndex uint64) (*chanstate.FinalHtlcInfo, error)
+
+ // FetchAllChannels returns all channels that aren't closed yet.
+ FetchAllChannels() ([]*chanstate.OpenChannel, error)
+
+ // FetchClosedChannels returns the summaries of closed channels.
+ FetchClosedChannels(pendingOnly bool) ([]*chanstate.ChannelCloseSummary,
+ error)
+}
+
+// finalHtlcSource provides the invoice registry with the final outcome of the
+// htlcs it released the preimage for. Outcomes are delivered live through the
+// htlc notifier, and can be looked up from the channel state for outcomes the
+// registry missed.
+type finalHtlcSource struct {
+ subscribe func() (<-chan FinalHtlcOutcome, func(), error)
+ chanStateDB finalHtlcDB
+}
+
+// NewFinalHtlcSource connects channel evidence to the registry's final-outcome
+// subscription. The caller owns the providers; the subscription's cancel
+// function must stop delivery before returning.
+func NewFinalHtlcSource(db finalHtlcDB, subscribe func() (
+ <-chan FinalHtlcOutcome, func(), error)) FinalHtlcSource {
+
+ return &finalHtlcSource{
+ chanStateDB: db,
+ subscribe: subscribe,
+ }
+}
+
+// SubscribeFinalHtlcs delegates to the injected provider so the registry can
+// receive final outcomes without depending on switch event types.
+func (f *finalHtlcSource) SubscribeFinalHtlcs() (
+ <-chan FinalHtlcOutcome, func(), error) {
+
+ return f.subscribe()
+}
+
+// LookupFinalHtlcs returns the recorded final outcome of those of the given
+// htlcs that have one. On-chain outcomes are always recorded, off-chain ones
+// only if the user opted in to storing final resolutions.
+//
+// NOTE: Part of the FinalHtlcSource interface.
+func (f *finalHtlcSource) LookupFinalHtlcs(keys []CircuitKey) (
+ map[CircuitKey]FinalHtlcOutcome, error) {
+
+ result := make(map[CircuitKey]FinalHtlcOutcome)
+ for _, key := range keys {
+ info, err := f.chanStateDB.LookupFinalHtlc(
+ key.ChanID, key.HtlcID,
+ )
+ switch {
+ case errors.Is(err, chanstate.ErrHtlcUnknown):
+
+ case err != nil:
+ return nil, fmt.Errorf("unable to look up final htlc "+
+ "%v: %w", key, err)
+
+ default:
+ result[key] = FinalHtlcOutcome{
+ Key: key,
+ Settled: info.Settled,
+ Offchain: info.Offchain,
+ }
+ }
+ }
+
+ return result, nil
+}
+
+// InferFinalHtlcs derives the final outcome of those of the given incoming
+// htlcs whose outcome follows from the channel state. The htlcs must not have
+// a recorded outcome.
+//
+// NOTE: This must only be used for incoming htlcs that we decided to settle,
+// meaning that we released their preimage. Such an htlc can only leave the
+// channel through our settle, so an htlc that is no longer on any commitment
+// of an open channel was settled off chain. Similarly, the resolvers record
+// the outcome of every htlc that is on the confirmed commitment of a closed
+// channel, so an htlc of a fully resolved channel without a recorded outcome
+// wasn't on the confirmed commitment because we settled it before.
+//
+// Restored or data-loss channels have no trusted commitments, even after
+// closure, so missing HTLCs need a recorded outcome to prove payment.
+// Abandoned channels can still contain unresolved HTLCs; their archived
+// commitments must also show that the incoming HTLC is no longer present.
+// The local commitment's next incoming HTLC index must also exceed the
+// requested index: a snapshot that predates the HTLC cannot prove collection.
+// Remote force closes also require the remote snapshot to have seen the HTLC.
+//
+// The caller must re-read recorded outcomes after this scan, because a
+// resolver can persist failure while its channel becomes fully resolved.
+//
+// NOTE: Part of the FinalHtlcSource interface.
+func (f *finalHtlcSource) InferFinalHtlcs(keys []CircuitKey) (
+ map[CircuitKey]FinalHtlcOutcome, error) {
+
+ result := make(map[CircuitKey]FinalHtlcOutcome)
+ if len(keys) == 0 {
+ return result, nil
+ }
+
+ // This includes pending and waiting close channels, whose commitments
+ // are still in the database.
+ channels, err := f.chanStateDB.FetchAllChannels()
+ if err != nil {
+ return nil, fmt.Errorf("unable to fetch channels: %w", err)
+ }
+
+ openChannels := make(map[lnwire.ShortChannelID]*chanstate.OpenChannel)
+ for _, channel := range channels {
+ openChannels[channel.ShortChanID()] = channel
+
+ if channel.IsZeroConf() && channel.ZeroConfConfirmed() {
+ openChannels[channel.ZeroConfRealScid()] = channel
+ }
+ }
+
+ closedChannels, err := f.chanStateDB.FetchClosedChannels(false)
+ if err != nil {
+ return nil, fmt.Errorf("unable to fetch closed channels: %w",
+ err)
+ }
+
+ resolvedChannels := make(
+ map[lnwire.ShortChannelID]*chanstate.ChannelCloseSummary,
+ )
+ for _, summary := range closedChannels {
+ if !summary.IsPending {
+ resolvedChannels[summary.ShortChanID] = summary
+ }
+ }
+
+ for _, key := range keys {
+ if channel, ok := openChannels[key.ChanID]; ok {
+ // Restored or stale snapshots cannot prove collection
+ // from a missing HTLC.
+ if channel.HasChanStatus(
+ chanstate.ChanStatusRestored,
+ ) || channel.HasChanStatus(
+ chanstate.ChanStatusLocalDataLoss,
+ ) {
+
+ continue
+ }
+
+ // A missing HTLC only proves removal if this snapshot
+ // has already seen the requested incoming index.
+ if key.HtlcID >=
+ channel.LocalCommitment.RemoteHtlcIndex {
+
+ continue
+ }
+
+ if !incomingHtlcOnCommitment(channel, key.HtlcID) {
+ result[key] = FinalHtlcOutcome{
+ Key: key,
+ Settled: true,
+ Offchain: true,
+ }
+ }
+
+ continue
+ }
+
+ if summary, ok := resolvedChannels[key.ChanID]; ok {
+ // Closed summaries omit channel trust status. Read the
+ // archived channel only for this recovery candidate.
+ channel, err := f.chanStateDB.FetchHistoricalChannel(
+ &summary.ChanPoint,
+ )
+ if err != nil {
+ return nil, fmt.Errorf("unable to fetch "+
+ "historical channel %v: %w",
+ summary.ChanPoint, err)
+ }
+ if channel.HasChanStatus(
+ chanstate.ChanStatusRestored,
+ ) || channel.HasChanStatus(
+ chanstate.ChanStatusLocalDataLoss,
+ ) {
+
+ continue
+ }
+
+ // A resolved archive cannot prove collection of an
+ // incoming HTLC added after its snapshot.
+ if key.HtlcID >=
+ channel.LocalCommitment.RemoteHtlcIndex {
+
+ continue
+ }
+
+ // The local view may include an add that the remote
+ // commitment never saw, so it cannot prove collection.
+ remoteIndex := channel.RemoteCommitment.RemoteHtlcIndex
+ if summary.CloseType == chanstate.RemoteForceClose &&
+ key.HtlcID >= remoteIndex {
+
+ continue
+ }
+
+ // Abandonment closes records without resolving HTLCs.
+ // Archived incoming HTLCs therefore remain unknown.
+ if summary.CloseType == chanstate.Abandoned &&
+ incomingHtlcOnCommitment(channel, key.HtlcID) {
+
+ continue
+ }
+
+ result[key] = FinalHtlcOutcome{
+ Key: key,
+ Settled: true,
+ }
+ }
+ }
+
+ return result, nil
+}
+
+// incomingHtlcOnCommitment returns true if the incoming htlc with the given
+// index is on our current commitment or on the remote commitment that our peer
+// hasn't revoked yet.
+//
+// NOTE: We don't need to check the pending remote commitment, which we signed
+// but our peer didn't revoke the previous one for yet. An incoming htlc is
+// added to our commitment before it is added to theirs, and removed from
+// theirs before it is removed from ours, so it can only be on the pending
+// remote commitment if it is on one of the other two.
+func incomingHtlcOnCommitment(channel *chanstate.OpenChannel,
+ htlcIndex uint64) bool {
+
+ onCommit := func(commit *chanstate.ChannelCommitment) bool {
+ for _, htlc := range commit.Htlcs {
+ if htlc.Incoming && htlc.HtlcIndex == htlcIndex {
+ return true
+ }
+ }
+
+ return false
+ }
+
+ return onCommit(&channel.LocalCommitment) ||
+ onCommit(&channel.RemoteCommitment)
+}
+
+// A compile-time check to ensure finalHtlcSource implements the
+// FinalHtlcSource interface.
+var _ FinalHtlcSource = (*finalHtlcSource)(nil)
### invoices/final_htlc_source_test.go
@@ -0,0 +1,392 @@
+package invoices
+
+import (
+ "errors"
+ "maps"
+ "testing"
+
+ "github.com/btcsuite/btcd/wire/v2"
+ "github.com/lightningnetwork/lnd/chanstate"
+ "github.com/lightningnetwork/lnd/lnwire"
+ "github.com/stretchr/testify/mock"
+ "github.com/stretchr/testify/require"
+)
+
+// mockFinalHtlcDB arranges storage responses without duplicating the
+// production outcome store or its channel-lifecycle rules.
+type mockFinalHtlcDB struct {
+ mock.Mock
+}
+
+// newMockFinalHtlcDB verifies configured interactions once after the test.
+func newMockFinalHtlcDB(t *testing.T) *mockFinalHtlcDB {
+ t.Helper()
+
+ db := &mockFinalHtlcDB{}
+ t.Cleanup(func() {
+ db.AssertExpectations(t)
+ })
+
+ return db
+}
+
+// LookupFinalHtlc returns arranged point-lookup evidence, keeping a missing
+// record distinct from an actual success or failure.
+func (m *mockFinalHtlcDB) LookupFinalHtlc(chanID lnwire.ShortChannelID,
+ htlcIndex uint64) (*chanstate.FinalHtlcInfo, error) {
+
+ args := m.Called(chanID, htlcIndex)
+ info, _ := args.Get(0).(*chanstate.FinalHtlcInfo)
+
+ return info, args.Error(1)
+}
+
+// FetchAllChannels returns current commitments so incoming HTLCs still on
+// either side cannot be inferred settled prematurely.
+func (m *mockFinalHtlcDB) FetchAllChannels() ([]*chanstate.OpenChannel,
+ error) {
+
+ args := m.Called()
+ channels, _ := args.Get(0).([]*chanstate.OpenChannel)
+
+ return channels, args.Error(1)
+}
+
+// FetchClosedChannels returns arranged close summaries so pending closes
+// remain distinguishable from fully completed channel resolution.
+func (m *mockFinalHtlcDB) FetchClosedChannels(pendingOnly bool) (
+ []*chanstate.ChannelCloseSummary, error) {
+
+ args := m.Called(pendingOnly)
+ closes, _ := args.Get(0).([]*chanstate.ChannelCloseSummary)
+
+ return closes, args.Error(1)
+}
+
+// FetchHistoricalChannel supplies the archived status that a close summary
+// omits, so restored snapshots cannot be mistaken for payment evidence.
+func (m *mockFinalHtlcDB) FetchHistoricalChannel(outPoint *wire.OutPoint) (
+ *chanstate.OpenChannel, error) {
+
+ args := m.Called(outPoint)
+ channel, _ := args.Get(0).(*chanstate.OpenChannel)
+
+ return channel, args.Error(1)
+}
+
+// Keep the double aligned with the complete source-read contract.
+var _ finalHtlcDB = (*mockFinalHtlcDB)(nil)
+
+// TestFinalHtlcSourceLookup checks which recorded and channel-state evidence
+// can establish the final outcome of an incoming HTLC already released.
+func TestFinalHtlcSourceLookup(t *testing.T) {
+ t.Parallel()
+
+ // Arrange: Cover both current commitments, zero-conf identities and
+ // pending/resolved closes, untrusted snapshots and abandoned contracts.
+ // Recorded outcomes remain trusted despite these snapshot gaps.
+ var (
+ openScid = lnwire.NewShortChanIDFromInt(1)
+ zeroConfScid = lnwire.NewShortChanIDFromInt(2)
+ realScid = lnwire.NewShortChanIDFromInt(3)
+ closingScid = lnwire.NewShortChanIDFromInt(4)
+ resolvedScid = lnwire.NewShortChanIDFromInt(5)
+ unknownScid = lnwire.NewShortChanIDFromInt(6)
+ restoredOpen = lnwire.NewShortChanIDFromInt(7)
+ restoredEnd = lnwire.NewShortChanIDFromInt(8)
+ dataLossOpen = lnwire.NewShortChanIDFromInt(9)
+ dataLossEnd = lnwire.NewShortChanIDFromInt(10)
+ abandonScid = lnwire.NewShortChanIDFromInt(11)
+ remoteScid = lnwire.NewShortChanIDFromInt(12)
+ )
+
+ key := func(scid lnwire.ShortChannelID,
+ htlcID uint64) CircuitKey {
+
+ return CircuitKey{
+ ChanID: scid,
+ HtlcID: htlcID,
+ }
+ }
+ incoming := func(htlcID uint64) chanstate.HTLC {
+ return chanstate.HTLC{
+ HtlcIndex: htlcID,
+ Incoming: true,
+ }
+ }
+
+ // HTLCs 1 and 2 remain on opposite commitments. Outgoing HTLC 3
+ // must not mask an absent incoming HTLC with the same index. Index4
+ // is the next incoming HTLC, so this snapshot cannot prove its removal.
+ openChannel := &chanstate.OpenChannel{
+ ShortChannelID: openScid,
+ LocalCommitment: chanstate.ChannelCommitment{
+ RemoteHtlcIndex: 4,
+ Htlcs: []chanstate.HTLC{
+ incoming(1),
+ {
+ HtlcIndex: 3,
+ Incoming: false,
+ },
+ },
+ },
+ RemoteCommitment: chanstate.ChannelCommitment{
+ Htlcs: []chanstate.HTLC{
+ incoming(2),
+ },
+ },
+ }
+
+ // Both zero-conf identities refer to a snapshot that has seen index1.
+ zeroConfChannel := &chanstate.OpenChannel{
+ ShortChannelID: zeroConfScid,
+ ChanType: chanstate.ZeroConfBit,
+ LocalCommitment: chanstate.ChannelCommitment{
+ RemoteHtlcIndex: 2,
+ },
+ }
+ zeroConfChannel.SetConfirmedScidForStore(realScid)
+
+ // Restored status survives closure in historical channel data, but
+ // neither empty snapshot establishes that a released HTLC was paid.
+ // A seen index keeps the status guard independent of the counter check.
+ restoredChannel := &chanstate.OpenChannel{
+ ShortChannelID: restoredOpen,
+ LocalCommitment: chanstate.ChannelCommitment{
+ RemoteHtlcIndex: 2,
+ },
+ }
+ restoredChannel.SetChannelStatusForStore(chanstate.ChanStatusRestored)
+ resolvedSummary := &chanstate.ChannelCloseSummary{
+ ShortChanID: resolvedScid,
+ ChanPoint: wire.OutPoint{
+ Index: 1,
+ },
+ }
+ restoredSummary := &chanstate.ChannelCloseSummary{
+ ShortChanID: restoredEnd,
+ ChanPoint: wire.OutPoint{
+ Index: 2,
+ },
+ }
+
+ // A stale snapshot can omit a released incoming HTLC despite retaining
+ // other HTLCs. Only recorded evidence can establish its collection.
+ dataLossChannel := &chanstate.OpenChannel{
+ ShortChannelID: dataLossOpen,
+ LocalCommitment: openChannel.LocalCommitment,
+ RemoteCommitment: openChannel.RemoteCommitment,
+ }
+ dataLossChannel.SetChannelStatusForStore(
+ chanstate.ChanStatusLocalDataLoss,
+ )
+ dataLossSummary := &chanstate.ChannelCloseSummary{
+ ShortChanID: dataLossEnd,
+ ChanPoint: wire.OutPoint{
+ Index: 3,
+ },
+ }
+
+ // Abandonment archives incoming HTLCs without collecting them. Reuse
+ // both commitments to cover each side and the outgoing-only index.
+ abandonedChannel := &chanstate.OpenChannel{
+ ShortChannelID: abandonScid,
+ LocalCommitment: openChannel.LocalCommitment,
+ RemoteCommitment: openChannel.RemoteCommitment,
+ }
+ abandonedSummary := &chanstate.ChannelCloseSummary{
+ ShortChanID: abandonScid,
+ CloseType: chanstate.Abandoned,
+ ChanPoint: wire.OutPoint{
+ Index: 4,
+ },
+ }
+
+ // Local add1 can precede the remote commitment that closes. Index0
+ // was already removed from both; only its absence proves collection.
+ remoteSummary := &chanstate.ChannelCloseSummary{
+ ShortChanID: remoteScid,
+ CloseType: chanstate.RemoteForceClose,
+ ChanPoint: wire.OutPoint{
+ Index: 5,
+ },
+ }
+ remoteChannel := &chanstate.OpenChannel{
+ LocalCommitment: chanstate.ChannelCommitment{
+ RemoteHtlcIndex: 2,
+ Htlcs: []chanstate.HTLC{
+ incoming(1),
+ },
+ },
+ RemoteCommitment: chanstate.ChannelCommitment{
+ RemoteHtlcIndex: 1,
+ },
+ }
+
+ keys := []CircuitKey{
+ key(openScid, 1), key(openScid, 2), key(openScid, 3),
+ key(openScid, 4), key(openScid, 5), key(zeroConfScid, 1),
+ key(realScid, 1), key(closingScid, 1), key(resolvedScid, 1),
+ key(resolvedScid, 2), key(unknownScid, 1),
+ key(restoredOpen, 1), key(restoredOpen, 2),
+ key(restoredEnd, 1),
+ key(dataLossOpen, 3), key(dataLossEnd, 3),
+ key(abandonScid, 1), key(abandonScid, 2),
+ key(abandonScid, 3), key(remoteScid, 0), key(remoteScid, 1),
+ }
+ db := newMockFinalHtlcDB(t)
+ for _, k := range keys {
+ if k == key(openScid, 5) {
+ db.On("LookupFinalHtlc", k.ChanID, k.HtlcID).Return(
+ &chanstate.FinalHtlcInfo{
+ Settled: false,
+ Offchain: false,
+ }, nil,
+ ).Once()
+
+ continue
+ }
+
+ if k == key(restoredOpen, 2) {
+ db.On("LookupFinalHtlc", k.ChanID, k.HtlcID).Return(
+ &chanstate.FinalHtlcInfo{
+ Settled: true,
+ Offchain: true,
+ }, nil,
+ ).Once()
+
+ continue
+ }
+
+ db.On("LookupFinalHtlc", k.ChanID, k.HtlcID).Return(
+ nil, chanstate.ErrHtlcUnknown,
+ ).Once()
+ }
+ db.On("FetchAllChannels").Return([]*chanstate.OpenChannel{
+ openChannel,
+ zeroConfChannel,
+ restoredChannel,
+ dataLossChannel,
+ }, nil).Once()
+ db.On("FetchClosedChannels", false).Return(
+ []*chanstate.ChannelCloseSummary{
+ {
+ ShortChanID: closingScid,
+ IsPending: true,
+ },
+ resolvedSummary,
+ restoredSummary,
+ dataLossSummary,
+ abandonedSummary,
+ remoteSummary,
+ }, nil,
+ ).Once()
+
+ // The archived snapshot has seen index1, while index2 is still unseen.
+ db.On("FetchHistoricalChannel", &resolvedSummary.ChanPoint).Return(
+ &chanstate.OpenChannel{
+ LocalCommitment: chanstate.ChannelCommitment{
+ RemoteHtlcIndex: 2,
+ },
+ }, nil,
+ ).Times(2)
+ db.On("FetchHistoricalChannel", &restoredSummary.ChanPoint).Return(
+ restoredChannel, nil,
+ ).Once()
+ db.On("FetchHistoricalChannel", &dataLossSummary.ChanPoint).Return(
+ dataLossChannel, nil,
+ ).Once()
+ db.On("FetchHistoricalChannel", &abandonedSummary.ChanPoint).Return(
+ abandonedChannel, nil,
+ ).Times(3)
+ db.On("FetchHistoricalChannel", &remoteSummary.ChanPoint).Return(
+ remoteChannel, nil,
+ ).Times(2)
+ source := NewFinalHtlcSource(db, nil)
+
+ // Act: Read stored outcomes first, without treating a missing record
+ // as success or scanning channel state during these point lookups.
+ outcomes, err := source.LookupFinalHtlcs(keys)
+ require.NoError(t, err)
+
+ // Assert: The stored failure and restored-channel success are direct
+ // evidence; inference must neither overwrite nor discard these records.
+ require.Equal(t, map[CircuitKey]FinalHtlcOutcome{
+ key(openScid, 5): {
+ Key: key(openScid, 5),
+ },
+ key(restoredOpen, 2): {
+ Key: key(restoredOpen, 2),
+ Settled: true,
+ Offchain: true,
+ },
+ }, outcomes)
+
+ // Act: Infer only keys lacking a durable result, as missed-event
+ // recovery does, and combine that evidence with the recorded failure.
+ var remaining []CircuitKey
+ for _, k := range keys {
+ if _, ok := outcomes[k]; !ok {
+ remaining = append(remaining, k)
+ }
+ }
+ inferred, err := source.InferFinalHtlcs(remaining)
+ require.NoError(t, err)
+ maps.Copy(outcomes, inferred)
+
+ settledOffchain := func(
+ k CircuitKey) FinalHtlcOutcome {
+
+ return FinalHtlcOutcome{
+ Key: k,
+ Settled: true,
+ Offchain: true,
+ }
+ }
+
+ // Assert: Unresolved or untrusted snapshots add no inferred success.
+ // Recorded outcomes remain authoritative.
+ expected := map[CircuitKey]FinalHtlcOutcome{
+ key(openScid, 3): settledOffchain(key(openScid, 3)),
+ key(openScid, 5): {
+ Key: key(openScid, 5),
+ },
+ key(zeroConfScid, 1): settledOffchain(key(zeroConfScid, 1)),
+ key(realScid, 1): settledOffchain(key(realScid, 1)),
+ key(resolvedScid, 1): {
+ Key: key(resolvedScid, 1),
+ Settled: true,
+ },
+ key(restoredOpen, 2): settledOffchain(key(restoredOpen, 2)),
+ key(abandonScid, 3): {
+ Key: key(abandonScid, 3),
+ Settled: true,
+ },
+ key(remoteScid, 0): {
+ Key: key(remoteScid, 0),
+ Settled: true,
+ },
+ }
+ require.Equal(t, expected, outcomes)
+
+ // Arrange: A closed summary also becomes untrusted when its archived
+ // channel cannot be read, independently of a known restored shell.
+ historyErr := errors.New("historical channel unavailable")
+ db.On("FetchAllChannels").Return(nil, nil).Once()
+ db.On("FetchClosedChannels", false).Return(
+ []*chanstate.ChannelCloseSummary{resolvedSummary}, nil,
+ ).Once()
+ db.On("FetchHistoricalChannel", &resolvedSummary.ChanPoint).Return(
+ nil, historyErr,
+ ).Once()
+
+ // Act: Retry the resolved candidate without readable channel history.
+ inferred, err = source.InferFinalHtlcs(
+ []CircuitKey{key(resolvedScid, 1)},
+ )
+
+ // Assert: Preserve the storage cause and leave payment unknown instead
+ // of accepting the fully closed summary as evidence of collection.
+ require.ErrorIs(t, err, historyErr)
+ require.Empty(t, inferred)
+}
### invoices/interface.go
@@ -48,6 +48,11 @@ type InvoiceDB interface {
FetchPendingInvoices(ctx context.Context) (map[lntypes.Hash]Invoice,
error)
+ // FetchPendingSettleInvoices returns all invoices that contain at least
+ // one htlc whose final outcome is still pending.
+ FetchPendingSettleInvoices(ctx context.Context) (
+ map[lntypes.Hash]Invoice, error)
+
// QueryInvoices allows a caller to query the invoice database for
// invoices within the specified add index range.
QueryInvoices(ctx context.Context, q InvoiceQuery) (InvoiceSlice, error)
@@ -88,8 +93,8 @@ type InvoiceDB interface {
DeleteInvoice(ctx context.Context,
invoicesToDelete []InvoiceDeleteRef) error
- // DeleteCanceledInvoices removes all canceled invoices from the
- // database.
+ // DeleteCanceledInvoices removes canceled invoices, preserving ordinary
+ // release history for both collected and failed HTLCs.
DeleteCanceledInvoices(ctx context.Context) error
}
### invoices/invoiceregistry.go
@@ -4,6 +4,7 @@ import (
"context"
"errors"
"fmt"
+ "maps"
"sync"
"sync/atomic"
"time"
@@ -79,6 +80,14 @@ type RegistryConfig struct {
// HtlcInterceptor is an interface that allows the invoice registry to
// let clients intercept invoices before they are settled.
HtlcInterceptor HtlcInterceptor
+
+ // FinalHtlcSource supplies final outcomes for ordinary invoices after
+ // their preimages were released, including missed live notifications.
+ FinalHtlcSource FinalHtlcSource
+
+ // SettleReconcileInterval retries pending outcome discovery. Zero
+ // uses DefaultSettleReconcileInterval, and idle passes skip scans.
+ SettleReconcileInterval time.Duration
}
// htlcReleaseEvent describes an htlc auto-release event. It is used to release
@@ -154,6 +163,10 @@ type InvoiceRegistry struct {
expiryWatcher *InvoiceExpiryWatcher
+ // pendingSettles maps ordinary pending circuits to their invoice hash.
+ // The registry lock protects it through preimage release/finalization.
+ pendingSettles map[CircuitKey]lntypes.Hash
+
wg sync.WaitGroup
quit chan struct{}
}
@@ -181,19 +194,30 @@ func NewRegistry(idb InvoiceDB, expiryWatcher *InvoiceExpiryWatcher,
cfg: cfg,
htlcAutoReleaseChan: make(chan *htlcReleaseEvent),
expiryWatcher: expiryWatcher,
+ pendingSettles: make(map[CircuitKey]lntypes.Hash),
quit: make(chan struct{}),
}
}
// scanInvoicesOnStart will scan all invoices on start and add active invoices
// to the invoice expiry watcher while also attempting to delete all canceled
-// invoices.
+// invoices. It also restores ordinary HTLCs awaiting their final outcomes.
func (i *InvoiceRegistry) scanInvoicesOnStart(ctx context.Context) error {
pendingInvoices, err := i.idb.FetchPendingInvoices(ctx)
if err != nil {
return err
}
+ // Parent state alone misses duplicate payments whose invoice was
+ // already settled before a later HTLC awaited its final outcome.
+ pendingSettle, err := i.idb.FetchPendingSettleInvoices(ctx)
+ if err != nil {
+ return err
+ }
+ if err := i.startSettleFinalizer(ctx, pendingSettle); err != nil {
+ return err
+ }
+
var pending []invoiceExpiry
for paymentHash, invoice := range pendingInvoices {
expiryRef := makeInvoiceExpiry(paymentHash, &invoice)
@@ -324,7 +348,8 @@ func (i *InvoiceRegistry) invoiceEventLoop() {
// invoice subscribers of cancel and accept events.
state := event.invoice.State
if state != ContractCanceled &&
- state != ContractAccepted {
+ state != ContractAccepted &&
+ state != ContractPendingSettle {
i.dispatchToClients(event)
}
@@ -1300,6 +1325,13 @@ func (i *InvoiceRegistry) notifyExitHopHtlcLocked(
log.Tracef("Settlement resolution: %T %v", resolution, resolution)
+ // Wait for the final outcome of all htlcs we released the preimage
+ // for. We hold the registry lock until the links learn the
+ // resolutions below, so no outcome can arrive before this.
+ if _, ok := resolution.(*HtlcSettleResolution); ok {
+ i.trackPendingSettles(ctx.hash, invoice)
+ }
+
switch res := resolution.(type) {
case *HtlcFailResolution:
// Inspect latest htlc state on the invoice. If it is found,
@@ -1343,11 +1375,13 @@ func (i *InvoiceRegistry) notifyExitHopHtlcLocked(
"outcome: %v, at accept height: %v",
res.Outcome, res.AcceptHeight))
- // Also settle any previously accepted htlcs. If a htlc is
- // marked as settled, we should follow now and settle the htlc
- // with our peer.
+ // Also settle any previously accepted htlcs. If we released
+ // the preimage of an htlc, we should follow now and settle the
+ // htlc with our peer.
setID := ctx.setID()
- settledHtlcSet := invoice.HTLCSet(setID, HtlcStateSettled)
+ settledHtlcSet := invoice.HTLCSet(setID, HtlcStatePendingSettle)
+ finalHtlcSet := invoice.HTLCSet(setID, HtlcStateSettled)
+ maps.Copy(settledHtlcSet, finalHtlcSet)
for key, htlc := range settledHtlcSet {
preimage := res.Preimage
if htlc.AMP != nil && htlc.AMP.Preimage != nil {
@@ -1467,14 +1501,14 @@ func (i *InvoiceRegistry) SettleHodlInvoice(ctx context.Context,
case ContractCanceled:
return nil, ErrInvoiceAlreadyCanceled
- case ContractSettled:
+ case ContractSettled, ContractPendingSettle:
return nil, ErrInvoiceAlreadySettled
}
return &InvoiceUpdateDesc{
UpdateType: SettleHodlInvoiceUpdate,
State: &InvoiceStateUpdateDesc{
- NewState: ContractSettled,
+ NewState: ContractPendingSettle,
Preimage: &preimage,
},
}, nil
@@ -1501,14 +1535,19 @@ func (i *InvoiceRegistry) SettleHodlInvoice(ctx context.Context,
log.Debugf("Invoice%v: settled with preimage %v", invoiceRef,
invoice.Terms.PaymentPreimage)
- // In the callback, we marked the invoice as settled. UpdateInvoice will
- // have seen this and should have moved all htlcs that were accepted to
- // the settled state. In the loop below, we go through all of these and
- // notify links and resolvers that are waiting for resolution. Any htlcs
- // that were already settled before, will be notified again. This isn't
- // necessary but doesn't hurt either.
+ // Wait for the final outcome of the htlcs before the links and
+ // resolvers learn the preimage.
+ i.trackPendingSettles(hash, invoice)
+
+ // In the callback, we marked the invoice as pending settle.
+ // UpdateInvoice will have seen this and should have moved all htlcs
+ // that were accepted to the pending settle state. In the loop below,
+ // we go through all of these and notify links and resolvers that are
+ // waiting for resolution. Any htlcs that were already settled before,
+ // will be notified again. This isn't necessary but doesn't hurt
+ // either.
for key, htlc := range invoice.Htlcs {
- if htlc.State != HtlcStateSettled {
+ if !htlc.State.PreimageReleased() {
continue
}
### invoices/invoiceregistry_test.go
@@ -477,6 +477,30 @@ func TestInvoiceRegistry(t *testing.T) {
name: "SettleInvoice",
test: testSettleInvoice,
},
+ {
+ name: "PendingSettleOnChainLoss",
+ test: testPendingSettleOnChainLoss,
+ },
+ {
+ name: "PendingSettleMixedRecovery",
+ test: testPendingSettleMixedRecovery,
+ },
+ {
+ name: "PendingSettleDuplicateReconcileOnStart",
+ test: testPendingSettleDuplicateReconcileOnStart,
+ },
+ {
+ name: "PendingSettleRetryFailedWrite",
+ test: testPendingSettleRetryFailedWrite,
+ },
+ {
+ name: "PendingSettleInferOnTick",
+ test: testPendingSettleInferOnTick,
+ },
+ {
+ name: "PendingSettleRecordedOutcomeWins",
+ test: testPendingSettleRecordedOutcomeWins,
+ },
{
name: "CancelInvoice",
test: testCancelInvoice,
@@ -1188,6 +1212,9 @@ func testSettleInvoice(t *testing.T,
t.Parallel()
+ // Arrange: Prepare both notification forms and an open invoice so
+ // release and final settlement can be observed independently.
+
ctx := newTestContext(t, nil, makeDB)
ctxb := t.Context()
@@ -1244,7 +1271,9 @@ func testSettleInvoice(t *testing.T,
hodlChan := make(chan interface{}, 1)
- // Try to settle invoice with an htlc that expires too soon.
+ // Try to settle invoice with an htlc that expires too soon. Act: Try an
+ // unseen expired child before releasing a valid payment; final outcomes
+ // are delivered separately below.
resolution, err := ctx.registry.NotifyExitHopHtlc(
testInvoicePaymentHash, testInvoice.Terms.Value,
uint32(testCurrentHeight)+testInvoiceCltvDelta-1,
@@ -1260,6 +1289,16 @@ func testSettleInvoice(t *testing.T,
)
require.Equal(t, testCurrentHeight, failResolution.AcceptHeight)
+ // Rejecting an unseen expired HTLC must not create a stored child or
+ // release the invoice. Keep this assertion beside the existing expiry
+ // case instead of duplicating its setup in a separate height test.
+ unpaid, err := ctx.registry.LookupInvoice(
+ ctxb, testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractOpen, unpaid.State)
+ require.Empty(t, unpaid.Htlcs)
+
// Settle invoice with a slightly higher amount.
amtPaid := lnwire.MilliSatoshi(100500)
resolution, err = ctx.registry.NotifyExitHopHtlc(
@@ -1271,39 +1310,35 @@ func testSettleInvoice(t *testing.T,
t.Fatal(err)
}
require.NotNil(t, resolution)
+ // Assert expiry leaves the invoice open and unrecorded, release reports
+ // pending, and final events establish the settled amount and index.
settleResolution := checkSettleResolution(
t, resolution, testInvoicePreimage,
)
require.Equal(t, invpkg.ResultSettled, settleResolution.Outcome)
- // We expect the settled state to be sent to the single invoice
- // subscriber.
+ // We released the preimage, but the htlc isn't irrevocably settled
+ // yet. We expect the pending settle state to be sent to the single
+ // invoice subscriber.
select {
case update := <-subscription.Updates:
- if update.State != invpkg.ContractSettled {
- t.Fatalf("expected state ContractOpen, but got %v",
- update.State)
- }
- if update.AmtPaid != amtPaid {
- t.Fatal("invoice AmtPaid incorrect")
- }
+ require.Equal(t, invpkg.ContractPendingSettle, update.State)
+ require.Equal(t, amtPaid, update.AmtPaid)
+ require.Zero(t, update.SettleIndex)
case <-time.After(testTimeout):
t.Fatal("no update received")
}
- // We expect a settled notification to be sent out.
+ // Subscribers to all invoices must not see the invoice as settled
+ // yet.
select {
case settledInvoice := <-allSubscriptions.SettledInvoices:
- if settledInvoice.State != invpkg.ContractSettled {
- t.Fatalf("expected state ContractOpen, but got %v",
- settledInvoice.State)
- }
- case <-time.After(testTimeout):
- t.Fatal("no update received")
+ t.Fatalf("unexpected settled invoice: %v", settledInvoice)
+ case <-time.After(100 * time.Millisecond):
}
// Try to settle again with the same htlc id. We need this idempotent
- // behaviour after a restart.
+ // behaviour after a restart, also while the settlement is pending.
resolution, err = ctx.registry.NotifyExitHopHtlc(
testInvoicePaymentHash, amtPaid, testHtlcExpiry,
testCurrentHeight, getCircuitKey(0), hodlChan,
@@ -1316,6 +1351,37 @@ func testSettleInvoice(t *testing.T,
)
require.Equal(t, invpkg.ResultReplayToSettled, settleResolution.Outcome)
+ // The preimage is out, so the invoice can no longer be canceled.
+ err = ctx.registry.CancelInvoice(ctxb, testInvoicePaymentHash)
+ require.ErrorIs(t, err, invpkg.ErrInvoiceAlreadySettled)
+
+ // The link reports that the settle is locked in.
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ ctx.finalizeHtlc(ref, getCircuitKey(0), true)
+
+ // We expect the settled state to be sent to the single invoice
+ // subscriber.
+ select {
+ case update := <-subscription.Updates:
+ require.Equal(t, invpkg.ContractSettled, update.State)
+ require.Equal(t, amtPaid, update.AmtPaid)
+ require.Equal(
+ t, invpkg.HtlcStateSettled,
+ update.Htlcs[getCircuitKey(0)].State,
+ )
+ case <-time.After(testTimeout):
+ t.Fatal("no update received")
+ }
+
+ // We expect a settled notification to be sent out.
+ select {
+ case settledInvoice := <-allSubscriptions.SettledInvoices:
+ require.Equal(t, invpkg.ContractSettled, settledInvoice.State)
+ require.EqualValues(t, 1, settledInvoice.SettleIndex)
+ case <-time.After(testTimeout):
+ t.Fatal("no update received")
+ }
+
// Try to settle again with a new higher-valued htlc. This payment
// should also be accepted, to prevent any change in behaviour for a
// paid invoice that may open up a probe vector.
@@ -1355,6 +1421,14 @@ func testSettleInvoice(t *testing.T,
amtPaid+amtPaid+600, inv.AmtPaid)
}
+ // The duplicate htlc is pending settlement, while the invoice remains
+ // settled.
+ require.Equal(t, invpkg.ContractSettled, inv.State)
+ require.Equal(
+ t, invpkg.HtlcStatePendingSettle,
+ inv.Htlcs[getCircuitKey(1)].State,
+ )
+
// Try to cancel.
err = ctx.registry.CancelInvoice(ctxb, testInvoicePaymentHash)
require.ErrorIs(t, err, invpkg.ErrInvoiceAlreadySettled)
@@ -1528,10 +1602,12 @@ func testSettleHoldInvoice(t *testing.T,
idb, clock := makeDB(t)
// Instantiate and start the invoice ctx.registry.
+ finalHtlcs := newMockFinalHtlcSource(t)
cfg := invpkg.RegistryConfig{
FinalCltvRejectDelta: testFinalCltvRejectDelta,
Clock: clock,
HtlcInterceptor: &invpkg.MockHtlcModifier{},
+ FinalHtlcSource: finalHtlcs,
}
expiryWatcher := invpkg.NewInvoiceExpiryWatcher(
@@ -1541,7 +1617,11 @@ func testSettleHoldInvoice(t *testing.T,
err := registry.Start()
require.NoError(t, err)
- defer registry.Stop()
+ // Stop the registry before database cleanup and surface any failure
+ // to finish the finality subscription's shutdown.
+ defer func() {
+ require.NoError(t, registry.Stop())
+ }()
ctxb := t.Context()
allSubscriptions, err := registry.SubscribeNotifications(ctxb, 0, 0)
@@ -1652,12 +1732,36 @@ func testSettleHoldInvoice(t *testing.T,
htlcResolution, _ := (<-hodlChan).(invpkg.HtlcResolution)
require.NotNil(t, htlcResolution)
+ // Assert explicit hold release reports pending; the final outcome then
+ // establishes settlement and its first index.
settleResolution := checkSettleResolution(
t, htlcResolution, testInvoicePreimage,
)
require.Equal(t, testCurrentHeight, settleResolution.AcceptHeight)
require.Equal(t, invpkg.ResultSettled, settleResolution.Outcome)
+ // The single invoice subscriber learns that the settlement is pending.
+ update = <-subscription.Updates
+ require.Equal(t, invpkg.ContractPendingSettle, update.State)
+ require.Equal(
+ t, invpkg.HtlcStatePendingSettle,
+ update.Htlcs[getCircuitKey(0)].State,
+ )
+
+ // Settling again is idempotent while pending, and canceling fails.
+ err = registry.SettleHodlInvoice(ctxb, testInvoicePreimage)
+ require.ErrorIs(t, err, invpkg.ErrInvoiceAlreadySettled)
+
+ err = registry.CancelInvoice(ctxb, testInvoicePaymentHash)
+ require.ErrorIs(t, err, invpkg.ErrInvoiceAlreadySettled)
+
+ // The settle is locked in.
+ finalHtlcs.outcomes <- invpkg.FinalHtlcOutcome{
+ Key: getCircuitKey(0),
+ Settled: true,
+ Offchain: true,
+ }
+
// We expect a settled notification to be sent out for both all and
// single invoice subscribers.
settledInvoice := <-allSubscriptions.SettledInvoices
@@ -1817,6 +1921,9 @@ func testKeySendImpl(t *testing.T, keySendEnabled bool,
cfg := defaultRegistryConfig()
cfg.AcceptKeySend = keySendEnabled
+ // Arrange: Configure keysend support and its preimage record so
+ // spontaneous invoice creation follows the normal registry path.
+
ctx := newTestContext(t, &cfg, makeDB)
allSubscriptions, err := ctx.registry.SubscribeNotifications(
@@ -1841,6 +1948,8 @@ func testKeySendImpl(t *testing.T, keySendEnabled bool,
},
}
+ // Act: Notify the registry of the keysend child before delivering any
+ // final channel result.
resolution, err := ctx.registry.NotifyExitHopHtlc(
hash, amt, expiry,
testCurrentHeight, getCircuitKey(10), hodlChan,
@@ -1878,18 +1987,24 @@ func testKeySendImpl(t *testing.T, keySendEnabled bool,
return
}
- checkSubscription := func() {
+ checkSubscription := func(hash lntypes.Hash, key invpkg.CircuitKey) {
// We expect a new invoice notification to be sent out.
newInvoice := <-allSubscriptions.NewInvoices
require.Equal(t, newInvoice.State, invpkg.ContractOpen)
+ // The invoice is settled once the htlc is final.
+ ctx.finalizeHtlc(invpkg.InvoiceRefByHash(hash), key, true)
+
// We expect a settled notification to be sent out.
settledInvoice := <-allSubscriptions.SettledInvoices
require.Equal(t, settledInvoice.State, invpkg.ContractSettled)
}
+ // Assert enabled keysend releases a preimage before final settlement,
+ // while disabled or invalid keysend follows its existing rejection
+ // path.
checkSettleResolution(t, resolution, preimage)
- checkSubscription()
+ checkSubscription(hash, getCircuitKey(10))
// Replay the same keysend payment. We expect an identical resolution,
// but no event should be generated.
@@ -1924,7 +2039,7 @@ func testKeySendImpl(t *testing.T, keySendEnabled bool,
require.Nil(t, err)
checkSettleResolution(t, resolution, preimage2)
- checkSubscription()
+ checkSubscription(hash2, getCircuitKey(20))
}
// testHoldKeysend tests receiving a spontaneous payment that is held.
@@ -1953,6 +2068,9 @@ func testHoldKeysendImpl(t *testing.T, timeoutKeysend bool,
cfg := defaultRegistryConfig()
cfg.AcceptKeySend = true
cfg.KeysendHoldTime = holdDuration
+ // Arrange: Configure the existing hold timer and keysend payload so
+ // timeout and explicit release share the same registry lifecycle.
+
ctx := newTestContext(t, &cfg, makeDB)
ctxb := t.Context()
@@ -1976,6 +2094,8 @@ func testHoldKeysendImpl(t *testing.T, timeoutKeysend bool,
},
}
+ // Act: Submit the held keysend payment and allow the selected release
+ // path to run before finalization.
resolution, err := ctx.registry.NotifyExitHopHtlc(
hash, amt, expiry, testCurrentHeight, getCircuitKey(10),
hodlChan, nil, keysendPayload,
@@ -2028,6 +2148,12 @@ func testHoldKeysendImpl(t *testing.T, timeoutKeysend bool,
ctxb, *newInvoice.Terms.PaymentPreimage,
))
+ // The invoice is settled once the htlc is final.
+ payHash := newInvoice.Terms.PaymentPreimage.Hash()
+ ctx.finalizeHtlc(
+ invpkg.InvoiceRefByHash(payHash), getCircuitKey(10), true,
+ )
+
// We expect a settled notification to be sent out.
settledInvoice := <-allSubscriptions.SettledInvoices
require.Equal(t, settledInvoice.State, invpkg.ContractSettled)
@@ -2042,6 +2168,9 @@ func testMppPayment(t *testing.T,
t.Parallel()
defer timeout()()
+ // Arrange: Create an ordinary invoice and MPP payload so neither
+ // partial shard can release a preimage by itself.
+
ctx := newTestContext(t, nil, makeDB)
ctxb := t.Context()
@@ -2058,6 +2187,8 @@ func testMppPayment(t *testing.T,
// Send htlc 1.
hodlChan1 := make(chan interface{}, 1)
+ // Act: Deliver the two shards through NotifyExitHopHtlc, then supply
+ // their final results independently.
resolution, err := ctx.registry.NotifyExitHopHtlc(
testInvoicePaymentHash, testInvoice.Terms.Value/2,
testHtlcExpiry, testCurrentHeight, getCircuitKey(10),
@@ -2118,9 +2249,23 @@ func testMppPayment(t *testing.T,
settleResolution.Outcome)
}
+ // The invoice waits for both htlcs to be final.
+ inv, err := ctx.registry.LookupInvoice(ctxb, testInvoicePaymentHash)
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractPendingSettle, inv.State)
+
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ ctx.finalizeHtlc(ref, getCircuitKey(11), true)
+
+ inv, err = ctx.registry.LookupInvoice(ctxb, testInvoicePaymentHash)
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractPendingSettle, inv.State)
+
+ ctx.finalizeHtlc(ref, getCircuitKey(12), true)
+
// Check that settled amount is equal to the sum of values of the htlcs
// 2 and 3.
- inv, err := ctx.registry.LookupInvoice(ctxb, testInvoicePaymentHash)
+ inv, err = ctx.registry.LookupInvoice(ctxb, testInvoicePaymentHash)
require.NoError(t, err)
if inv.State != invpkg.ContractSettled {
t.Fatal("expected invoice to be settled")
@@ -2141,6 +2286,8 @@ func testMppPaymentWithOverpayment(t *testing.T,
ctxb := t.Context()
f := func(overpaymentRand uint64) bool {
+ // Arrange a fresh invoice for each generated overpayment so
+ // samples cannot share payment state.
ctx := newTestContext(t, nil, makeDB)
// Add the invoice.
@@ -2159,6 +2306,8 @@ func testMppPaymentWithOverpayment(t *testing.T,
// Send htlc 1.
hodlChan1 := make(chan interface{}, 1)
+ // Act: Complete the set through the registry and provide final
+ // outcomes after the preimages are released.
resolution, err := ctx.registry.NotifyExitHopHtlc(
testInvoicePaymentHash, testInvoice.Terms.Value/2,
testHtlcExpiry, testCurrentHeight, getCircuitKey(11),
@@ -2193,17 +2342,36 @@ func testMppPaymentWithOverpayment(t *testing.T,
settleResolution.Outcome)
}
- // Check that settled amount is equal to the sum of values of
- // the htlcs 1 and 2.
+ // Both htlcs count towards the amount paid while the invoice
+ // waits for them to be final.
inv, err := ctx.registry.LookupInvoice(
ctxb, testInvoicePaymentHash,
)
require.NoError(t, err)
+ require.Equal(t, invpkg.ContractPendingSettle, inv.State)
+ require.Equal(
+ t, testInvoice.Terms.Value+overpayment, inv.AmtPaid,
+ )
+
+ // Finalize both shards to preserve the overpayment property
+ // without multiplying the separately tested failed-shard path.
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ ctx.finalizeHtlc(ref, getCircuitKey(11), true)
+ ctx.finalizeHtlc(ref, getCircuitKey(12), true)
+
+ // Assert the complete overpayment survives finalization of both
+ // shards, independently of their initially provisional credit.
+ inv, err = ctx.registry.LookupInvoice(
+ ctxb, testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
if inv.State != invpkg.ContractSettled {
t.Fatal("expected invoice to be settled")
}
- return inv.AmtPaid == testInvoice.Terms.Value+overpayment
+ expectedAmt := testInvoice.Terms.Value + overpayment
+
+ return inv.AmtPaid == expectedAmt
}
if err := quick.Check(f, nil); err != nil {
t.Fatalf("amount incorrect: %v", err)
@@ -2320,12 +2488,16 @@ func testInvoiceExpiryWithRegistry(t *testing.T,
require.NoError(t, registry.Stop(), "failed to stop invoice registry")
}
-// testOldInvoiceRemovalOnStart tests that we'll attempt to remove old canceled
-// invoices upon start while keeping all settled ones.
+// testOldInvoiceRemovalOnStart checks that startup cleanup preserves released
+// payment records, including failed collection, and removes unreleased cancels.
func testOldInvoiceRemovalOnStart(t *testing.T,
makeDB func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock)) {
t.Parallel()
+
+ // Arrange expired invoices with settled, unreleased canceled, mixed and
+ // all-failed outcomes so cleanup must preserve release history, even
+ // when the released payment collected no value.
idb, testClock := makeDB(t)
cfg := invpkg.RegistryConfig{
@@ -2341,30 +2513,102 @@ func testOldInvoiceRemovalOnStart(t *testing.T,
registry := invpkg.NewRegistry(idb, expiryWatcher, &cfg)
// First prefill the Channel DB with some pre-existing expired invoices.
- const numExpired = 5
+ const numExpired = 6
const numPending = 0
existingInvoices := generateInvoiceExpiryTestData(
t, testTime, 0, numExpired, numPending,
)
ctxb := t.Context()
+ var unpaidAddIndex uint64
i := 0
for paymentHash, invoice := range existingInvoices.expiredInvoices {
- // Mark half of the invoices as settled, the other half as
- // canceled.
- if i%2 == 0 {
+ partialPayment := i == 1
+ failedPayment := i == 3
+
+ // Leave the mixed and all-failed fixtures open to release their
+ // actual HTLCs; other fixtures retain the cleanup controls.
+ switch {
+ case partialPayment || failedPayment:
+ invoice.State = invpkg.ContractOpen
+
+ case i%2 == 0:
invoice.State = invpkg.ContractSettled
- } else {
+
+ default:
invoice.State = invpkg.ContractCanceled
}
- _, err := idb.AddInvoice(ctxb, invoice, paymentHash)
+ addIndex, err := idb.AddInvoice(ctxb, invoice, paymentHash)
require.NoError(t, err)
+ if i == numExpired-1 {
+ unpaidAddIndex = addIndex
+ }
+
i++
+ if !partialPayment && !failedPayment {
+ continue
+ }
+
+ // Persist released outcomes through the database update API.
+ // Unique keys prevent the two payment fixtures from sharing an
+ // HTLC identity, including in the SQL backend's global index.
+ ref := invpkg.InvoiceRefByHash(paymentHash)
+ keys := []invpkg.CircuitKey{
+ getCircuitKey(uint64(2 * i)),
+ getCircuitKey(uint64(2*i + 1)),
+ }
+ release := func(inv *invpkg.Invoice) (
+ *invpkg.InvoiceUpdateDesc, error) {
+
+ htlcs := make(
+ map[invpkg.CircuitKey]*invpkg.HtlcAcceptDesc,
+ )
+ amount := inv.Terms.Value / 2
+ for _, key := range keys {
+ htlcs[key] = &invpkg.HtlcAcceptDesc{
+ Amt: amount,
+ CustomRecords: record.CustomSet{},
+ }
+ }
+
+ state := &invpkg.InvoiceStateUpdateDesc{
+ NewState: invpkg.ContractPendingSettle,
+ Preimage: inv.Terms.PaymentPreimage,
+ }
+
+ return &invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.AddHTLCsUpdate,
+ AddHtlcs: htlcs,
+ State: state,
+ }, nil
+ }
+ _, err = idb.UpdateInvoice(
+ ctxb, ref, nil, release,
+ )
+ require.NoError(t, err)
+ _, err = idb.UpdateInvoice(
+ ctxb, ref, nil, getFinalizeHtlcs(
+ !failedPayment, keys[0],
+ ),
+ )
+ require.NoError(t, err)
+ final, err := idb.UpdateInvoice(
+ ctxb, ref, nil,
+ getFinalizeHtlcs(false, keys[1]),
+ )
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractCanceled, final.State)
+ expectedPaid := invoice.Terms.Value / 2
+ if failedPayment {
+ expectedPaid = 0
+ }
+ require.Equal(t, expectedPaid, final.AmtPaid)
}
+ require.NotZero(t, unpaidAddIndex)
- // Collect all settled invoices for our expectation set.
+ // Collect retained payment records for our expectation set.
var expected []invpkg.Invoice
// Perform a scan query to collect all invoices.
@@ -2376,24 +2620,29 @@ func testOldInvoiceRemovalOnStart(t *testing.T,
response, err := idb.QueryInvoices(ctxb, query)
require.NoError(t, err)
- // Save all settled invoices for our expectation set.
+ // Only the unreleased canceled fixture may disappear. Select it by
+ // its known add index instead of duplicating the retention predicate;
+ // full snapshots preserve credit, preimages and final HTLC states.
for _, invoice := range response.Invoices {
- if invoice.State == invpkg.ContractSettled {
+ if invoice.AddIndex != unpaidAddIndex {
expected = append(expected, invoice)
}
}
- // Start the registry which should collect and delete all canceled
- // invoices upon start.
+ // Act by starting the registry with automatic cleanup enabled, using
+ // the same persisted invoices and each backend's real deletion path.
err = registry.Start()
require.NoError(t, err, "cannot start the registry")
+ t.Cleanup(func() {
+ require.NoError(t, registry.Stop())
+ })
// Perform a scan query to collect all invoices.
response, err = idb.QueryInvoices(ctxb, query)
require.NoError(t, err)
- // Check that we really only kept the settled invoices after the
- // registry start.
+ // Assert the unreleased cancellation disappears while all released
+ // history, including the zero-credit failed payment, stays unchanged.
require.Equal(t, expected, response.Invoices)
}
@@ -2429,6 +2678,9 @@ func testHeightExpiryWithRegistryImpl(t *testing.T, numParts int, settle bool,
t.Parallel()
defer timeout()()
+ // Arrange: Prepare the existing expiry watcher and selected invoice
+ // shape to compare held expiry with an already-released payment.
+
ctx := newTestContext(t, nil, makeDB)
require.Greater(t, numParts, 0, "test requires at least one part")
@@ -2454,11 +2706,13 @@ func testHeightExpiryWithRegistryImpl(t *testing.T, numParts int, settle bool,
htlcAmt := testInvoice.Terms.Value / lnwire.MilliSatoshi(numParts)
hodlChan := make(chan interface{}, numParts)
- for i := 0; i < numParts; i++ {
+ for i := range numParts {
// We bump our expiry height for each htlc so that we can test
// that the lowest expiry height is used.
expiry := testHtlcExpiry + uint32(i)
+ // Act: Submit the payment parts through the registry before
+ // advancing height or finalizing the released children.
resolution, err := ctx.registry.NotifyExitHopHtlc(
testInvoicePaymentHash, htlcAmt, expiry,
testCurrentHeight, getCircuitKey(uint64(i)), hodlChan,
@@ -2498,9 +2752,12 @@ func testHeightExpiryWithRegistryImpl(t *testing.T, numParts int, settle bool,
err = ctx.registry.SettleHodlInvoice(ctxb, testInvoicePreimage)
require.NoError(t, err)
- for i := 0; i < numParts; i++ {
+ for range numParts {
resolution, _ := (<-hodlChan).(invpkg.HtlcResolution)
require.NotNil(t, resolution)
+ // Assert an unreleased payment expires, while released
+ // preimages cannot be canceled and their outcomes
+ // establish final settlement.
settleResolution := checkSettleResolution(
t, resolution, testInvoicePreimage,
)
@@ -2515,8 +2772,9 @@ func testHeightExpiryWithRegistryImpl(t *testing.T, numParts int, settle bool,
}
// If we did not settle the invoice before its expiry, we now expect
- // a cancellation.
- expectedState := invpkg.ContractSettled
+ // a cancellation. Otherwise the invoice must not be canceled while its
+ // settlement is pending.
+ expectedState := invpkg.ContractPendingSettle
if !settle {
expectedState = invpkg.ContractCanceled
@@ -2533,6 +2791,21 @@ func testHeightExpiryWithRegistryImpl(t *testing.T, numParts int, settle bool,
require.NoError(t, err)
require.Equal(t, expectedState, inv.State, "expected "+
"hold invoice: %v, got: %v", expectedState, inv.State)
+
+ if !settle {
+ return
+ }
+
+ // Once all htlcs are final, the invoice is settled.
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ for i := range numParts {
+ ctx.finalizeHtlc(ref, getCircuitKey(uint64(i)), true)
+ }
+
+ inv, err = ctx.registry.LookupInvoice(ctxb, testInvoicePaymentHash)
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractSettled, inv.State)
+ require.Equal(t, testInvoice.Terms.Value, inv.AmtPaid)
}
// testMultipleSetHeightExpiry pays a hold invoice with two mpp sets, testing
@@ -2733,6 +3006,9 @@ func testSettleInvoicePaymentAddrRequiredOptionalGrace(t *testing.T,
t.Parallel()
+ // Arrange: Prepare the payment-address feature variants and grace-
+ // period input using the existing invoice fixture.
+
ctx := newTestContext(t, nil, makeDB)
ctxb := t.Context()
@@ -2799,6 +3075,8 @@ func testSettleInvoicePaymentAddrRequiredOptionalGrace(t *testing.T,
// We'll now attempt to settle the invoice as normal, this should work
// no problem as we should allow these existing invoices to be settled.
hodlChan := make(chan interface{}, 1)
+ // Act: Submit the payment during the configured grace period before
+ // delivering its final channel result.
resolution, err := ctx.registry.NotifyExitHopHtlc(
testInvoicePaymentHash, testInvoiceAmount, testHtlcExpiry,
testCurrentHeight, getCircuitKey(10), hodlChan,
@@ -2813,12 +3091,26 @@ func testSettleInvoicePaymentAddrRequiredOptionalGrace(t *testing.T,
}
require.Equal(t, settleResolution.Outcome, invpkg.ResultSettled)
+ // We expect the pending settle state to be sent to the single invoice
+ // subscriber.
+ select {
+ case update := <-subscription.Updates:
+ require.Equal(t, invpkg.ContractPendingSettle, update.State)
+ case <-time.After(testTimeout):
+ t.Fatal("no update received")
+ }
+
+ ctx.finalizeHtlc(
+ invpkg.InvoiceRefByHash(testInvoicePaymentHash),
+ getCircuitKey(10), true,
+ )
+
// We expect the settled state to be sent to the single invoice
// subscriber.
select {
case update := <-subscription.Updates:
if update.State != invpkg.ContractSettled {
- t.Fatalf("expected state ContractOpen, but got %v",
+ t.Fatalf("expected state ContractSettled, but got %v",
update.State)
}
if update.AmtPaid != invoice.Terms.Value {
@@ -3040,7 +3332,7 @@ func testSpontaneousAmpPaymentImpl(
// Record the hodl channels of all HTLCs but the last one, which
// received its resolution directly from NotifyExitHopHtlc.
hodlChans := make(map[lntypes.Preimage]chan interface{})
- for i := 0; i < numShards; i++ {
+ for i := range numShards {
isFinalShard := i == numShards-1
hodlChan := make(chan interface{}, 1)
@@ -3086,6 +3378,7 @@ func testSpontaneousAmpPaymentImpl(
checkFailResolution(
t, resolution, invpkg.ResultInvoiceNotFound,
)
+
continue
}
@@ -3720,3 +4013,459 @@ func testAmpReconstructionFailCancelsSetOnly(t *testing.T,
t, invpkg.HtlcStateSettled, inv.AMPState[setIDA].State,
)
}
+
+// testPendingSettleOnChainLoss asserts that an invoice whose only htlc the
+// payer reclaims on chain after we released the preimage is canceled rather
+// than reported as paid.
+func testPendingSettleOnChainLoss(t *testing.T,
+ makeDB func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock)) {
+
+ t.Parallel()
+ defer timeout()()
+
+ // Arrange an ordinary invoice and both subscription forms so a lost
+ // released HTLC cannot leak a successful settlement notification.
+ ctx := newTestContext(t, nil, makeDB)
+ ctxb := t.Context()
+
+ allSubscriptions, err := ctx.registry.SubscribeNotifications(ctxb, 0, 0)
+ require.NoError(t, err)
+ defer allSubscriptions.Cancel()
+
+ testInvoice := newInvoice(t, false, false)
+ _, err = ctx.registry.AddInvoice(
+ ctxb, testInvoice, testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ <-allSubscriptions.NewInvoices
+
+ subscription, err := ctx.registry.SubscribeSingleInvoice(
+ ctxb, testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ defer subscription.Cancel()
+
+ update := <-subscription.Updates
+ require.Equal(t, invpkg.ContractOpen, update.State)
+
+ // Act by releasing its preimage, then deliver the payer's final reclaim
+ // below through the same outcome channel used by the link and resolver.
+ resolution, err := ctx.registry.NotifyExitHopHtlc(
+ testInvoicePaymentHash, testInvoiceAmount, testHtlcExpiry,
+ testCurrentHeight, getCircuitKey(0), nil, nil, testPayload,
+ )
+ require.NoError(t, err)
+ checkSettleResolution(t, resolution, testInvoicePreimage)
+
+ // The subscription was registered after the invoice was added, so it
+ // can receive the add event in addition to its backlog. Skip any
+ // further open updates.
+ update = <-subscription.Updates
+ for update.State == invpkg.ContractOpen {
+ update = <-subscription.Updates
+ }
+ require.Equal(t, invpkg.ContractPendingSettle, update.State)
+
+ // The payer reclaims the htlc on chain.
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ ctx.finalizeHtlc(ref, getCircuitKey(0), false)
+
+ // Assert cancellation removes provisional credit and allocates no
+ // index, keeping failed releases out of paid notifications.
+ update = <-subscription.Updates
+ require.Equal(t, invpkg.ContractCanceled, update.State)
+ require.Zero(t, update.AmtPaid)
+ require.Zero(t, update.SettleIndex)
+ require.Equal(
+ t, invpkg.HtlcStateFailed,
+ update.Htlcs[getCircuitKey(0)].State,
+ )
+
+ // Subscribers to all invoices never see the invoice as settled.
+ select {
+ case inv := <-allSubscriptions.SettledInvoices:
+ t.Fatalf("unexpected settled invoice: %v", inv)
+ case <-time.After(100 * time.Millisecond):
+ }
+}
+
+// testPendingSettleDuplicateReconcileOnStart checks that recovery discovers
+// pending duplicates beneath a settled parent without allocating another index.
+func testPendingSettleDuplicateReconcileOnStart(t *testing.T,
+ makeDB func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock)) {
+
+ t.Parallel()
+
+ // Arrange an already-paid invoice with a later released duplicate.
+ // Only the duplicate's failure becomes known while the registry is off.
+ db, testClock := makeDB(t)
+ invoice := newInvoice(t, false, false)
+ _, err := db.AddInvoice(t.Context(), invoice, testInvoicePaymentHash)
+ require.NoError(t, err)
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ _, err = settleInvoice(db, ref, 0, testInvoiceAmount)
+ require.NoError(t, err)
+ key := invpkg.CircuitKey{HtlcID: 1}
+ htlcs := map[invpkg.CircuitKey]*invpkg.HtlcAcceptDesc{
+ key: {
+ Amt: testInvoiceAmount,
+ CustomRecords: make(record.CustomSet),
+ },
+ }
+ _, err = db.UpdateInvoice(t.Context(), ref, nil,
+ func(*invpkg.Invoice) (*invpkg.InvoiceUpdateDesc, error) {
+ return &invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.AddHTLCsUpdate,
+ AddHtlcs: htlcs,
+ }, nil
+ },
+ )
+ require.NoError(t, err)
+ // The ordinary pending query excludes a paid parent, while recovery
+ // must still discover its later child awaiting a final outcome.
+ pending, err := db.FetchPendingInvoices(t.Context())
+ require.NoError(t, err)
+ require.NotContains(t, pending, testInvoicePaymentHash)
+ released, err := db.FetchPendingSettleInvoices(t.Context())
+ require.NoError(t, err)
+ require.Contains(t, released, testInvoicePaymentHash)
+
+ source := newMockFinalHtlcSource(t)
+ source.On("LookupFinalHtlcs", mock.Anything).Unset()
+ source.On("LookupFinalHtlcs", []invpkg.CircuitKey{key}).Return(
+ map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome{
+ key: {
+ Key: key,
+ Settled: false,
+ },
+ }, nil,
+ ).Once()
+ cfg := defaultRegistryConfig()
+ cfg.FinalHtlcSource = source
+
+ // Act by starting the registry, which must discover pending children
+ // even though the ordinary pending-invoice query excludes their parent.
+ ctx := newTestContext(t, &cfg,
+ func(*testing.T) (invpkg.InvoiceDB, *clock.TestClock) {
+ return db, testClock
+ },
+ )
+
+ // Assert that only the duplicate loses credit; the original payment
+ // and its first settlement index survive the recovery unchanged.
+ stored, err := ctx.registry.LookupInvoice(
+ t.Context(), testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractSettled, stored.State)
+ require.Equal(t, testInvoiceAmount, stored.AmtPaid)
+ require.EqualValues(t, 1, stored.SettleIndex)
+ require.Equal(t, invpkg.HtlcStateFailed, stored.Htlcs[key].State)
+}
+
+// failingFinalizeDB arranges transient write failures while delegating all
+// successful operations to the actual backend under test.
+type failingFinalizeDB struct {
+ invpkg.InvoiceDB
+ mock.Mock
+}
+
+// UpdateInvoice returns the arranged error before touching storage, or runs
+// the actual invoice transaction so the test exercises real finalization.
+func (f *failingFinalizeDB) UpdateInvoice(ctx context.Context,
+ ref invpkg.InvoiceRef, setID *invpkg.SetID,
+ callback invpkg.InvoiceUpdateCallback) (*invpkg.Invoice, error) {
+
+ args := f.Called(ctx, ref, setID, callback)
+ if err := args.Error(0); err != nil {
+ return nil, err
+ }
+
+ return f.InvoiceDB.UpdateInvoice(ctx, ref, setID, callback)
+}
+
+// Embedding the backend keeps failure injection local to invoice writes.
+var _ invpkg.InvoiceDB = (*failingFinalizeDB)(nil)
+
+// testPendingSettleRetryFailedWrite checks that a single delivered outcome
+// survives transient invoice-write failures without waiting for a channel scan.
+func testPendingSettleRetryFailedWrite(t *testing.T,
+ makeDB func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock)) {
+
+ t.Parallel()
+
+ // Arrange a successful release, one failed finalization write, and
+ // one successful retry on the real backend. A long reconciliation
+ // interval ensures that the live-event retry provides the recovery.
+ cfg := defaultRegistryConfig()
+ cfg.SettleReconcileInterval = time.Hour
+ ctx := newTestContext(t, &cfg,
+ func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock) {
+ db, testClock := makeDB(t)
+ faultDB := &failingFinalizeDB{
+ InvoiceDB: db,
+ }
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ args := []interface{}{
+ mock.Anything, ref, (*invpkg.SetID)(nil),
+ mock.Anything,
+ }
+ faultDB.On("UpdateInvoice", args...).Return(nil).Once()
+ faultDB.On("UpdateInvoice", args...).Return(
+ errors.New("invoice write unavailable"),
+ ).Once()
+ faultDB.On("UpdateInvoice", args...).Return(nil).Once()
+ t.Cleanup(func() {
+ faultDB.AssertExpectations(t)
+ })
+
+ return faultDB, testClock
+ },
+ )
+ invoice := newInvoice(t, false, false)
+ _, err := ctx.registry.AddInvoice(
+ t.Context(), invoice, testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ resolution, err := ctx.registry.NotifyExitHopHtlc(
+ testInvoicePaymentHash, testInvoiceAmount, testHtlcExpiry,
+ testCurrentHeight, getCircuitKey(0), nil, nil, testPayload,
+ )
+ require.NoError(t, err)
+ checkSettleResolution(t, resolution, testInvoicePreimage)
+
+ // Act by delivering the outcome exactly once. The fixture waits for
+ // the actual stored child to become final rather than counting calls.
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ ctx.finalizeHtlc(ref, getCircuitKey(0), true)
+
+ // Assert that retries produce final credit with only one index.
+ stored, err := ctx.registry.LookupInvoice(
+ t.Context(), testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractSettled, stored.State)
+ require.Equal(t, testInvoiceAmount, stored.AmtPaid)
+ require.EqualValues(t, 1, stored.SettleIndex)
+}
+
+// testPendingSettleInferOnTick checks that channel-only completion is picked
+// up while running, without requiring a second registry restart.
+func testPendingSettleInferOnTick(t *testing.T,
+ makeDB func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock)) {
+
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ startupErr error
+ }{
+ {
+ name: "empty startup evidence",
+ },
+ {
+ name: "failed startup evidence",
+ startupErr: errors.New("channel source unavailable"),
+ },
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ t.Parallel()
+
+ // Arrange either empty or failed startup evidence. Gate
+ // next scan to observe pending state before supplying
+ // channel completion without a live outcome event.
+ db, testClock := makeDB(t)
+ invoice := newInvoice(t, false, false)
+ _, err := db.AddInvoice(
+ t.Context(), invoice, testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ _, err = db.UpdateInvoice(t.Context(), ref, nil,
+ getUpdateInvoice(0, testInvoiceAmount))
+ require.NoError(t, err)
+ key := invpkg.CircuitKey{HtlcID: 0}
+ source := newMockFinalHtlcSource(t)
+ source.On("InferFinalHtlcs", mock.Anything).Unset()
+ source.On("InferFinalHtlcs", []invpkg.CircuitKey{key}).
+ Return(nil, test.startupErr).Once()
+ entered := make(chan struct{})
+ release := make(chan struct{})
+ source.On(
+ "InferFinalHtlcs", []invpkg.CircuitKey{key},
+ ).Run(
+ func(mock.Arguments) {
+ close(entered)
+ <-release
+ },
+ ).Return(map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome{
+ key: {
+ Key: key,
+ Settled: true,
+ },
+ }, nil).Once()
+ cfg := defaultRegistryConfig()
+ cfg.FinalHtlcSource = source
+ cfg.SettleReconcileInterval = 10 * time.Millisecond
+ ctx := newTestContext(t, &cfg,
+ func(*testing.T) (invpkg.InvoiceDB,
+ *clock.TestClock) {
+
+ return db, testClock
+ },
+ )
+ t.Cleanup(func() {
+ close(release)
+ })
+
+ // Act by waiting for the existing periodic scan. Before
+ // it finishes, confirm unresolved evidence has not
+ // credited the invoice.
+ select {
+ case <-entered:
+ case <-time.After(testTimeout):
+ t.Fatal("periodic channel scan did not run")
+ }
+ stored, err := ctx.registry.LookupInvoice(
+ t.Context(), testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ require.Equal(
+ t, invpkg.ContractPendingSettle, stored.State,
+ )
+ require.Zero(t, stored.SettleIndex)
+ release <- struct{}{}
+ ctx.waitHtlcFinal(ref, key)
+
+ // Assert completion on this registry using only channel
+ // evidence and the timer/subscription lifecycle.
+ stored, err = ctx.registry.LookupInvoice(
+ t.Context(), testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractSettled, stored.State)
+ require.Equal(t, testInvoiceAmount, stored.AmtPaid)
+ require.EqualValues(t, 1, stored.SettleIndex)
+ })
+ }
+}
+
+// testPendingSettleRecordedOutcomeWins checks immediate startup inference,
+// concurrent durable failures and read errors without false payment credit.
+func testPendingSettleRecordedOutcomeWins(t *testing.T,
+ makeDB func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock)) {
+
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ recheckErr error
+ recordFailure bool
+ wantIndex uint64
+ wantHtlcState invpkg.HtlcState
+ wantState invpkg.ContractState
+ wantAmount lnwire.MilliSatoshi
+ }{
+ {
+ name: "failure recorded during scan",
+ recordFailure: true,
+ wantHtlcState: invpkg.HtlcStateFailed,
+ wantState: invpkg.ContractCanceled,
+ },
+ {
+ name: "record recheck fails",
+ recordFailure: true,
+ wantHtlcState: invpkg.HtlcStatePendingSettle,
+ recheckErr: errors.New("outcome store unavailable"),
+ wantState: invpkg.ContractPendingSettle,
+ wantAmount: testInvoiceAmount,
+ },
+ {
+ name: "no recorded outcome",
+ wantState: invpkg.ContractSettled,
+ wantAmount: testInvoiceAmount,
+ wantIndex: 1,
+ wantHtlcState: invpkg.HtlcStateSettled,
+ },
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ t.Parallel()
+
+ // Arrange a released HTLC with no initial record. The
+ // channel scan then infers success; the following read
+ // reveals a concurrent failure, fails, or confirms that
+ // no recorded result overrides inferred success.
+ db, testClock := makeDB(t)
+ invoice := newInvoice(t, false, false)
+ _, err := db.AddInvoice(
+ t.Context(), invoice, testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ _, err = db.UpdateInvoice(t.Context(), ref, nil,
+ getUpdateInvoice(0, testInvoiceAmount))
+ require.NoError(t, err)
+ key := invpkg.CircuitKey{HtlcID: 0}
+ keys := []invpkg.CircuitKey{key}
+ source := newMockFinalHtlcSource(t)
+ source.On("LookupFinalHtlcs", mock.Anything).Unset()
+ source.On("InferFinalHtlcs", mock.Anything).Unset()
+ source.On("LookupFinalHtlcs", keys).
+ Return(nil, nil).Once()
+ source.On("InferFinalHtlcs", keys).Return(
+ map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome{
+ key: {
+ Key: key,
+ Settled: true,
+ },
+ }, nil,
+ ).Once()
+ // Negative rows acquire a durable failure during
+ // inference. The positive row keeps immediate startup
+ // success when the second lookup still has no record.
+ recorded := make(
+ map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome,
+ )
+ if test.recordFailure {
+ recorded[key] = invpkg.FinalHtlcOutcome{
+ Key: key,
+ Settled: false,
+ }
+ }
+ source.On("LookupFinalHtlcs", keys).
+ Return(recorded, test.recheckErr).Once()
+ cfg := defaultRegistryConfig()
+ cfg.FinalHtlcSource = source
+ cfg.SettleReconcileInterval = time.Hour
+
+ // Act through startup, which executes the controlled
+ // record/scan/recheck sequence before accepting
+ // traffic.
+ ctx := newTestContext(t, &cfg,
+ func(*testing.T) (invpkg.InvoiceDB,
+ *clock.TestClock) {
+
+ return db, testClock
+ },
+ )
+
+ // Assert failure removes credit and a read error leaves
+ // work pending. Only the no-record row receives
+ // credit and its first settlement index.
+ stored, err := ctx.registry.LookupInvoice(
+ t.Context(), testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ require.Equal(t, test.wantState, stored.State)
+ require.Equal(t, test.wantAmount, stored.AmtPaid)
+ require.Equal(t, test.wantIndex, stored.SettleIndex)
+ require.Equal(
+ t, test.wantHtlcState, stored.Htlcs[key].State,
+ )
+ })
+ }
+}
### invoices/invoices.go
@@ -222,16 +222,28 @@ const (
// ContractOpen means the invoice has only been created.
ContractOpen ContractState = 0
- // ContractSettled means the htlc is settled and the invoice has been
- // paid.
+ // ContractSettled means an ordinary invoice collected every released
+ // payment HTLC. A later duplicate HTLC can still await its own final
+ // outcome while the parent stays settled.
ContractSettled ContractState = 1
- // ContractCanceled means the invoice has been canceled.
+ // ContractCanceled means the invoice has been canceled. If a released
+ // HTLC failed, AmtPaid retains the funds collected from other HTLCs.
ContractCanceled ContractState = 2
// ContractAccepted means the HTLC has been accepted but not settled
// yet.
ContractAccepted ContractState = 3
+
+ // ContractPendingSettle means we decided to settle an ordinary invoice
+ // released the preimage, but at least one of its htlcs has not been
+ // irrevocably settled yet. Until then the payer can still recover an
+ // htlc on chain, so the invoice must not be reported as paid. The
+ // invoice cannot be manually canceled. Once every outcome is known,
+ // it moves to ContractSettled only if all released HTLCs settled, or
+ // ContractCanceled if any failed. AMP invoices retain their existing
+ // set-level settlement behavior and do not enter this state.
+ ContractPendingSettle ContractState = 4
)
// String returns a human readable identifier for the ContractState type.
@@ -248,6 +260,9 @@ func (c ContractState) String() string {
case ContractAccepted:
return "Accepted"
+
+ case ContractPendingSettle:
+ return "PendingSettle"
}
return "Unknown"
@@ -258,6 +273,12 @@ func (c ContractState) IsFinal() bool {
return c == ContractSettled || c == ContractCanceled
}
+// PreimageReleased returns true if we have decided to settle the invoice and
+// may have revealed its preimage, whether or not the htlcs are final yet.
+func (c ContractState) PreimageReleased() bool {
+ return c == ContractSettled || c == ContractPendingSettle
+}
+
// ContractTerm is a companion struct to the Invoice struct. This struct houses
// the necessary conditions required before the invoice can be considered fully
// settled by the payee.
@@ -535,10 +556,54 @@ const (
// sender.
HtlcStateCanceled
- // HtlcStateSettled indicates the htlc is settled.
+ // HtlcStateSettled indicates the htlc is settled. For ordinary HTLCs
+ // its outcome is irrevocable; AMP retains release-time settlement.
HtlcStateSettled
+
+ // HtlcStatePendingSettle indicates that we released the preimage for
+ // an ordinary htlc, but its settlement is not irrevocable yet. It moves
+ // to HtlcStateSettled once the settle is locked in off chain or the
+ // htlc is swept on chain, and to HtlcStateFailed if the payer
+ // reclaims it on chain instead.
+ HtlcStatePendingSettle
+
+ // HtlcStateFailed indicates a final failure after an ordinary HTLC's
+ // preimage was released. Unlike an attempt canceled before release,
+ // this prevents a pending invoice from completing successfully.
+ HtlcStateFailed
)
+// String identifies the HTLC state in logs, distinguishing preimage release
+// from final settlement while keeping unknown persisted values visible.
+func (h HtlcState) String() string {
+ switch h {
+ case HtlcStateAccepted:
+ return "Accepted"
+
+ case HtlcStateCanceled:
+ return "Canceled"
+
+ case HtlcStateSettled:
+ return "Settled"
+
+ case HtlcStatePendingSettle:
+ return "PendingSettle"
+
+ case HtlcStateFailed:
+ return "Failed"
+ }
+
+ return "Unknown"
+}
+
+// PreimageReleased returns true if we decided to settle the htlc and may have
+// revealed its preimage to our peer, whether or not the settle is final yet.
+// The preimage of such an htlc must stay available so that it can be claimed
+// on chain. A final failure no longer has an outstanding claim.
+func (h HtlcState) PreimageReleased() bool {
+ return h == HtlcStateSettled || h == HtlcStatePendingSettle
+}
+
// InvoiceHTLC contains details about an htlc paying to this invoice.
type InvoiceHTLC struct {
// Amt is the amount that is carried by this htlc.
@@ -720,6 +785,10 @@ const (
// CancelInvoiceUpdate indicates that this update is trying to cancel
// an invoice.
CancelInvoiceUpdate
+
+ // FinalizeHTLCsUpdate records final outcomes of one or more ordinary
+ // htlcs in HtlcStatePendingSettle, without changing AMP settlement.
+ FinalizeHTLCsUpdate
)
// String returns a human readable string for the UpdateType.
@@ -737,6 +806,9 @@ func (u UpdateType) String() string {
case CancelInvoiceUpdate:
return "CancelInvoiceUpdate"
+ case FinalizeHTLCsUpdate:
+ return "FinalizeHTLCsUpdate"
+
default:
return fmt.Sprintf("unknown invoice update type: %d", u)
}
@@ -756,6 +828,11 @@ type InvoiceUpdateDesc struct {
// the invoice.
AddHtlcs map[CircuitKey]*HtlcAcceptDesc
+ // FinalizeHtlcs maps ordinary htlcs in HtlcStatePendingSettle to their
+ // outcome: true if the htlc was irrevocably settled, false if the
+ // payer reclaimed it on chain.
+ FinalizeHtlcs map[CircuitKey]bool
+
// SetID is an optional set ID for AMP invoices that allows operations
// to be more efficient by ensuring we don't need to read out the
// entire HTLC set each timee an HTLC is to be cancelled.
@@ -839,9 +916,12 @@ func (i *Invoice) requiresPreimage() bool {
return true
}
-// IsPending returns true if the invoice is in ContractOpen state.
+// IsPending returns true if the invoice has not reached a final state yet,
+// meaning it is open, accepted or waiting for its settled htlcs to become
+// final.
func (i *Invoice) IsPending() bool {
- return i.State == ContractOpen || i.State == ContractAccepted
+ return i.State == ContractOpen || i.State == ContractAccepted ||
+ i.State == ContractPendingSettle
}
// copySlice allocates a new slice and copies the source into it.
### invoices/invoices_test.go
@@ -1,6 +1,7 @@
package invoices_test
import (
+ "context"
"crypto/rand"
"database/sql"
"fmt"
@@ -214,6 +215,14 @@ func TestInvoices(t *testing.T) {
name: "AddInvoiceInvalidFeatureDeps",
test: testAddInvoiceInvalidFeatureDeps,
},
+ {
+ name: "FinalizeHtlcs",
+ test: testFinalizeHtlcs,
+ },
+ {
+ name: "SettleCollection",
+ test: testSettleCollection,
+ },
}
makeKeyValueDB := func(t *testing.T) invpkg.InvoiceDB {
@@ -281,28 +290,51 @@ func TestInvoices(t *testing.T) {
}
}
-// TestInvoiceIsPending tests that pending invoices are those which are either
-// in ContractOpen or in ContractAccepted state.
+// TestInvoiceIsPending checks the public parent-state classification used
+// when discovering invoices that still need processing after a restart.
func TestInvoiceIsPending(t *testing.T) {
t.Parallel()
- contractStates := []invpkg.ContractState{
- invpkg.ContractOpen, invpkg.ContractSettled,
- invpkg.ContractCanceled, invpkg.ContractAccepted,
+ // Arrange: Specify the expected result for each persisted parent state
+ // so released ordinary payments remain discoverable before finality.
+ tests := []struct {
+ state invpkg.ContractState
+ pending bool
+ }{
+ {
+ state: invpkg.ContractOpen,
+ pending: true,
+ },
+ {
+ state: invpkg.ContractSettled,
+ pending: false,
+ },
+ {
+ state: invpkg.ContractCanceled,
+ pending: false,
+ },
+ {
+ state: invpkg.ContractAccepted,
+ pending: true,
+ },
+ {
+ state: invpkg.ContractPendingSettle,
+ pending: true,
+ },
}
- for _, state := range contractStates {
+ for _, test := range tests {
invoice := invpkg.Invoice{
- State: state,
+ State: test.state,
}
- // We expect that an invoice is pending if it's either in
- // ContractOpen or ContractAccepted state.
- open := invpkg.ContractOpen
- accepted := invpkg.ContractAccepted
- pending := (state == open || state == accepted)
+ // Act: Query the public classification from just the invoice
+ // state, as callers selecting pending parents do.
+ pending := invoice.IsPending()
- require.Equal(t, pending, invoice.IsPending())
+ // Assert: Compare with the explicit contract instead of
+ // deriving the expectation from the same predicate as the code.
+ require.Equal(t, test.pending, pending, "state %v", test.state)
}
}
@@ -408,7 +440,7 @@ func testInvoiceWorkflowImpl(t *testing.T, test invWorkflowTest,
// now have the settled bit toggle to true and a non-default
// SettledDate
payAmt := fakeInvoice.Terms.Value * 2
- _, err = db.UpdateInvoice(ctxb, ref, nil, getUpdateInvoice(0, payAmt))
+ _, err = settleInvoice(db, ref, 0, payAmt)
require.NoError(t, err, "unable to settle invoice")
dbInvoice2, err := db.LookupInvoice(ctxb, ref)
require.NoError(t, err, "unable to fetch invoice")
@@ -989,11 +1021,7 @@ func testInvoiceAddTimeSeries(t *testing.T,
paymentHash := invoice.Terms.PaymentPreimage.Hash()
ref := invpkg.InvoiceRefByHash(paymentHash)
- _, err := db.UpdateInvoice(
- ctxb, ref, nil, getUpdateInvoice(
- htlcID, invoice.Terms.Value,
- ),
- )
+ _, err := settleInvoice(db, ref, htlcID, invoice.Terms.Value)
if err != nil {
t.Fatalf("unable to settle invoice: %v", err)
}
@@ -1274,9 +1302,7 @@ func testFetchPendingInvoices(t *testing.T,
}
ref := invpkg.InvoiceRefByHash(paymentHash)
- _, err = db.UpdateInvoice(
- ctxb, ref, nil, getUpdateInvoice(htlcID, amt),
- )
+ _, err = settleInvoice(db, ref, htlcID, amt)
require.NoError(t, err)
settleTestInvoice(invoice, htlcID, settleIndex)
@@ -1352,10 +1378,7 @@ func testFetchPendingInvoicesAccepted(t *testing.T,
settledHash := settledInvoice.Terms.PaymentPreimage.Hash()
_, err = db.AddInvoice(ctxb, settledInvoice, settledHash)
require.NoError(t, err)
- _, err = db.UpdateInvoice(
- ctxb, invpkg.InvoiceRefByHash(settledHash), nil,
- getUpdateInvoice(2, amt),
- )
+ _, err = settleInvoice(db, invpkg.InvoiceRefByHash(settledHash), 2, amt)
require.NoError(t, err)
// Add a canceled invoice – it must also NOT appear in the pending
@@ -1422,9 +1445,7 @@ func testDuplicateSettleInvoice(t *testing.T,
// With the invoice in the DB, we'll now attempt to settle the invoice.
ref := invpkg.InvoiceRefByHash(payHash)
- dbInvoice, err := db.UpdateInvoice(
- ctxb, ref, nil, getUpdateInvoice(0, amt),
- )
+ dbInvoice, err := settleInvoice(db, ref, 0, amt)
require.NoError(t, err, "unable to settle invoice")
// We'll update what we expect the settle invoice to be so that our
@@ -1504,9 +1525,7 @@ func testQueryInvoices(t *testing.T,
// We'll only settle half of all invoices created.
if i%2 == 0 {
ref := invpkg.InvoiceRefByHash(paymentHash)
- _, err := db.UpdateInvoice(
- ctxb, ref, nil, getUpdateInvoice(htlcID, amt),
- )
+ _, err := settleInvoice(db, ref, htlcID, amt)
if err != nil {
t.Fatalf("unable to settle invoice: %v", err)
}
@@ -1879,7 +1898,7 @@ func getUpdateInvoice(htlcID uint64,
return func(invoice *invpkg.Invoice) (*invpkg.InvoiceUpdateDesc,
error) {
- if invoice.State == invpkg.ContractSettled {
+ if invoice.State.PreimageReleased() {
return nil, invpkg.ErrInvoiceAlreadySettled
}
@@ -1894,7 +1913,7 @@ func getUpdateInvoice(htlcID uint64,
UpdateType: invpkg.AddHTLCsUpdate,
State: &invpkg.InvoiceStateUpdateDesc{
Preimage: invoice.Terms.PaymentPreimage,
- NewState: invpkg.ContractSettled,
+ NewState: invpkg.ContractPendingSettle,
},
AddHtlcs: htlcs,
}
@@ -1903,6 +1922,46 @@ func getUpdateInvoice(htlcID uint64,
}
}
+// getFinalizeHtlcs returns an invoice update callback that records the final
+// outcome of the given htlcs, which must be pending settlement.
+func getFinalizeHtlcs(settled bool,
+ keys ...models.CircuitKey) invpkg.InvoiceUpdateCallback {
+
+ return func(invoice *invpkg.Invoice) (*invpkg.InvoiceUpdateDesc,
+ error) {
+
+ finalize := make(map[models.CircuitKey]bool, len(keys))
+ for _, key := range keys {
+ finalize[key] = settled
+ }
+
+ return &invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.FinalizeHTLCsUpdate,
+ FinalizeHtlcs: finalize,
+ }, nil
+ }
+}
+
+// settleInvoice settles the invoice with a single htlc, and then records that
+// the htlc is irrevocably settled, as the registry does once it learns the
+// final outcome of the htlc.
+func settleInvoice(db invpkg.InvoiceDB, ref invpkg.InvoiceRef, htlcID uint64,
+ amt lnwire.MilliSatoshi) (*invpkg.Invoice, error) {
+
+ ctxb := context.Background()
+ inv, err := db.UpdateInvoice(
+ ctxb, ref, nil, getUpdateInvoice(htlcID, amt),
+ )
+ if err != nil {
+ return inv, err
+ }
+
+ return db.UpdateInvoice(
+ ctxb, ref, nil,
+ getFinalizeHtlcs(true, models.CircuitKey{HtlcID: htlcID}),
+ )
+}
+
// testCustomRecords tests that custom records are properly recorded in the
// invoice database.
func testCustomRecords(t *testing.T,
@@ -2714,11 +2773,9 @@ func testDeleteInvoices(t *testing.T,
// Settle the second invoice.
if i == 1 {
- invoice, err = db.UpdateInvoice(
- ctxb, invpkg.InvoiceRefByHash(paymentHash), nil,
- getUpdateInvoice(
- uint64(i), invoice.Terms.Value,
- ),
+ invoice, err = settleInvoice(
+ db, invpkg.InvoiceRefByHash(paymentHash),
+ uint64(i), invoice.Terms.Value,
)
require.NoError(t, err, "unable to settle invoice")
}
@@ -2864,3 +2921,134 @@ func testAddInvoiceInvalidFeatureDeps(t *testing.T,
lnwire.PaymentAddrOptional,
))
}
+
+// testFinalizeHtlcs asserts that an invoice waits for every final outcome,
+// then cancels on partial collection while preserving the received funds.
+func testFinalizeHtlcs(t *testing.T,
+ makeDB func(t *testing.T) invpkg.InvoiceDB) {
+
+ t.Parallel()
+
+ // Arrange an ordinary invoice with two released shards so final
+ // outcome accounting is exercised through the actual database.
+ db := makeDB(t)
+ ctxb := t.Context()
+
+ amt := lnwire.NewMSatFromSatoshis(1000)
+ invoice, err := randInvoice(amt)
+ require.NoError(t, err)
+
+ payHash := invoice.Terms.PaymentPreimage.Hash()
+ _, err = db.AddInvoice(ctxb, invoice, payHash)
+ require.NoError(t, err)
+
+ // Act by releasing both preimages in one invoice transaction, before
+ // either child has a final outcome from the channel or resolver.
+ htlc0 := models.CircuitKey{HtlcID: 0}
+ htlc1 := models.CircuitKey{HtlcID: 1}
+ ref := invpkg.InvoiceRefByHash(payHash)
+ dbInvoice, err := db.UpdateInvoice(ctxb, ref, nil,
+ func(inv *invpkg.Invoice) (*invpkg.InvoiceUpdateDesc, error) {
+ htlcs := make(
+ map[models.CircuitKey]*invpkg.HtlcAcceptDesc,
+ )
+ for _, key := range []models.CircuitKey{htlc0, htlc1} {
+ htlcs[key] = &invpkg.HtlcAcceptDesc{
+ Amt: amt / 2,
+ CustomRecords: make(record.CustomSet),
+ }
+ }
+
+ return &invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.AddHTLCsUpdate,
+ AddHtlcs: htlcs,
+ State: &invpkg.InvoiceStateUpdateDesc{
+ NewState: invpkg.ContractPendingSettle,
+ Preimage: inv.Terms.PaymentPreimage,
+ },
+ }, nil
+ },
+ )
+ require.NoError(t, err)
+
+ // Assert provisional credit without a final settlement index or date.
+ // Both discovery queries must retain the unresolved payment.
+ require.Equal(t, invpkg.ContractPendingSettle, dbInvoice.State)
+ require.Equal(t, amt, dbInvoice.AmtPaid)
+ require.Zero(t, dbInvoice.SettleIndex)
+ require.True(t, dbInvoice.SettleDate.IsZero())
+ for _, htlc := range dbInvoice.Htlcs {
+ require.Equal(t, invpkg.HtlcStatePendingSettle, htlc.State)
+ }
+
+ pending, err := db.FetchPendingInvoices(ctxb)
+ require.NoError(t, err)
+ require.Contains(t, pending, payHash)
+
+ pendingSettle, err := db.FetchPendingSettleInvoices(ctxb)
+ require.NoError(t, err)
+ require.Contains(t, pendingSettle, payHash)
+
+ // An invoice can't be settled directly.
+ _, err = db.UpdateInvoice(ctxb, ref, nil,
+ func(inv *invpkg.Invoice) (*invpkg.InvoiceUpdateDesc, error) {
+ return &invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.AddHTLCsUpdate,
+ State: &invpkg.InvoiceStateUpdateDesc{
+ NewState: invpkg.ContractSettled,
+ Preimage: inv.Terms.PaymentPreimage,
+ },
+ }, nil
+ },
+ )
+ require.ErrorIs(t, err, invpkg.ErrInvoiceCannotSettle)
+
+ // The first htlc settles. The invoice keeps waiting for the second.
+ dbInvoice, err = db.UpdateInvoice(
+ ctxb, ref, nil, getFinalizeHtlcs(true, htlc0),
+ )
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractPendingSettle, dbInvoice.State)
+ require.Equal(t, amt, dbInvoice.AmtPaid)
+ require.Equal(
+ t, invpkg.HtlcStateSettled, dbInvoice.Htlcs[htlc0].State,
+ )
+
+ // Repeating a final success must identify the duplicate, rather than
+ // allowing an unrelated database error to satisfy this rejection.
+ _, err = db.UpdateInvoice(
+ ctxb, ref, nil, getFinalizeHtlcs(true, htlc0),
+ )
+ require.ErrorIs(t, err, invpkg.ErrHTLCAlreadySettled)
+
+ // The payer reclaims the second htlc on chain. The invoice is canceled
+ // but retains the amount collected from the first htlc.
+ dbInvoice, err = db.UpdateInvoice(
+ ctxb, ref, nil, getFinalizeHtlcs(false, htlc1),
+ )
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractCanceled, dbInvoice.State)
+ require.Equal(t, amt/2, dbInvoice.AmtPaid)
+ require.Zero(t, dbInvoice.SettleIndex)
+ require.True(t, dbInvoice.SettleDate.IsZero())
+ require.Equal(
+ t, invpkg.HtlcStateFailed, dbInvoice.Htlcs[htlc1].State,
+ )
+
+ // The stored invoice matches.
+ stored, err := db.LookupInvoice(ctxb, ref)
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractCanceled, stored.State)
+ require.Equal(t, amt/2, stored.AmtPaid)
+ require.Zero(t, stored.SettleIndex)
+ require.Equal(t, invpkg.HtlcStateSettled, stored.Htlcs[htlc0].State)
+ require.Equal(t, invpkg.HtlcStateFailed, stored.Htlcs[htlc1].State)
+
+ pending, err = db.FetchPendingInvoices(ctxb)
+ require.NoError(t, err)
+ require.NotContains(t, pending, payHash)
+
+ pendingSettle, err = db.FetchPendingSettleInvoices(ctxb)
+ require.NoError(t, err)
+ require.NotContains(t, pendingSettle, payHash)
+}
### invoices/mock.go
@@ -56,6 +56,15 @@ func (m *MockInvoiceDB) FetchPendingInvoices(ctx context.Context) (
return args.Get(0).(map[lntypes.Hash]Invoice), args.Error(1)
}
+// FetchPendingSettleInvoices returns the configured recovery candidates so
+// startup tests can distinguish child-state discovery from pending parents.
+func (m *MockInvoiceDB) FetchPendingSettleInvoices(ctx context.Context) (
+ map[lntypes.Hash]Invoice, error) {
+
+ args := m.Called(ctx)
+ return args.Get(0).(map[lntypes.Hash]Invoice), args.Error(1)
+}
+
func (m *MockInvoiceDB) QueryInvoices(q InvoiceQuery) (InvoiceSlice, error) {
args := m.Called(q)
invoiceSlice, _ := args.Get(0).(InvoiceSlice)
### invoices/settle_collection_registry_test.go
@@ -0,0 +1,130 @@
+package invoices_test
+
+import (
+ "testing"
+ "time"
+
+ "github.com/lightningnetwork/lnd/clock"
+ invpkg "github.com/lightningnetwork/lnd/invoices"
+ "github.com/lightningnetwork/lnd/record"
+ "github.com/stretchr/testify/require"
+)
+
+// testPendingSettleMixedRecovery checks that a released failure survives a
+// registry restart without prematurely canceling or crediting the payment.
+func testPendingSettleMixedRecovery(t *testing.T,
+ makeDB func(t *testing.T) (invpkg.InvoiceDB, *clock.TestClock)) {
+
+ t.Parallel()
+
+ // Arrange a released two-shard payment on the real selected backend,
+ // keeping its database and clock across a later registry restart.
+ db, testClock := makeDB(t)
+ invoice := newInvoice(t, false, false)
+ _, err := db.AddInvoice(t.Context(), invoice, testInvoicePaymentHash)
+ require.NoError(t, err)
+ ref := invpkg.InvoiceRefByHash(testInvoicePaymentHash)
+ failedKey, successKey := getCircuitKey(0), getCircuitKey(1)
+ htlcs := make(map[invpkg.CircuitKey]*invpkg.HtlcAcceptDesc)
+ for _, key := range []invpkg.CircuitKey{failedKey, successKey} {
+ htlcs[key] = &invpkg.HtlcAcceptDesc{
+ Amt: testInvoiceAmount / 2,
+ CustomRecords: make(record.CustomSet),
+ }
+ }
+ _, err = db.UpdateInvoice(t.Context(), ref, nil,
+ func(inv *invpkg.Invoice) (*invpkg.InvoiceUpdateDesc, error) {
+ return &invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.AddHTLCsUpdate,
+ AddHtlcs: htlcs,
+ State: &invpkg.InvoiceStateUpdateDesc{
+ NewState: invpkg.ContractPendingSettle,
+ Preimage: inv.Terms.PaymentPreimage,
+ },
+ }, nil
+ },
+ )
+ require.NoError(t, err)
+
+ // makeRegistryDB reuses persistent invoice state after the registry
+ // restarts, so recovery reads the actual stored failure.
+ makeRegistryDB := func(*testing.T) (invpkg.InvoiceDB,
+ *clock.TestClock) {
+
+ return db, testClock
+ }
+ // Act by persisting the first released failure before starting a new
+ // registry; its sibling still needs a final collection outcome.
+ _, err = db.UpdateInvoice(
+ t.Context(), ref, nil, getFinalizeHtlcs(false, failedKey),
+ )
+ require.NoError(t, err)
+
+ // Assert that one failure cannot finish a payment while another shard
+ // can still be claimed, and that failure evidence survives in storage.
+ stored, err := db.LookupInvoice(t.Context(), ref)
+ require.NoError(t, err)
+ require.Equal(t, invpkg.ContractPendingSettle, stored.State)
+ require.Equal(t, invpkg.HtlcStateFailed, stored.Htlcs[failedKey].State)
+ require.Equal(t, testInvoiceAmount/2, stored.AmtPaid)
+ require.Zero(t, stored.SettleIndex)
+
+ // Arrange fresh subscriptions after restart so the recovered pending
+ // invoice and any later paid event are observed independently.
+ ctx := newTestContext(t, nil, makeRegistryDB)
+ all, err := ctx.registry.SubscribeNotifications(
+ t.Context(), stored.AddIndex, 0,
+ )
+ require.NoError(t, err)
+ defer all.Cancel()
+ single, err := ctx.registry.SubscribeSingleInvoice(
+ t.Context(), testInvoicePaymentHash,
+ )
+ require.NoError(t, err)
+ defer single.Cancel()
+ var update *invpkg.Invoice
+ select {
+ case update = <-single.Updates:
+ case <-time.After(testTimeout):
+ t.Fatal("missing initial invoice update")
+ }
+ require.Equal(t, invpkg.ContractPendingSettle, update.State)
+
+ // Act by delivering the remaining success after restart; the stored
+ // failure must still prevent successful completion of the payment.
+ ctx.finalizeHtlc(ref, successKey, true)
+ for update.State == invpkg.ContractPendingSettle {
+ select {
+ case update = <-single.Updates:
+ case <-time.After(testTimeout):
+ t.Fatal("missing mixed-outcome invoice update")
+ }
+ }
+ // Assert that cancellation preserves the collected funds and both final
+ // outcomes without allocating settlement metadata or issuing paid
+ // events.
+ require.Equal(t, invpkg.ContractCanceled, update.State)
+ require.Equal(t, testInvoiceAmount/2, update.AmtPaid)
+ require.Equal(
+ t, invpkg.HtlcStateSettled, update.Htlcs[successKey].State,
+ )
+ require.Equal(t, invpkg.HtlcStateFailed, update.Htlcs[failedKey].State)
+ require.Zero(t, update.SettleIndex)
+ require.True(t, update.SettleDate.IsZero())
+ select {
+ case inv := <-all.SettledInvoices:
+ t.Fatalf("partial collection reported as paid: %v", inv)
+ case <-time.After(100 * time.Millisecond):
+ }
+
+ // Act by replaying the failed circuit through off-chain admission;
+ // the final failure must remain a normal invoice rejection.
+ resolution, err := ctx.registry.NotifyExitHopHtlc(
+ testInvoicePaymentHash, testInvoiceAmount/2, testHtlcExpiry,
+ testCurrentHeight, failedKey, nil, nil, testPayload,
+ )
+ require.NoError(t, err)
+ // Assert the stored final failure returns a normal HTLC rejection,
+ // preserving the canceled payment rather than reviving its preimage.
+ checkFailResolution(t, resolution, invpkg.ResultReplayToCanceled)
+}
### invoices/settle_collection_test.go
@@ -0,0 +1,227 @@
+package invoices_test
+
+import (
+ "testing"
+
+ "github.com/lightningnetwork/lnd/graph/db/models"
+ invpkg "github.com/lightningnetwork/lnd/invoices"
+ "github.com/lightningnetwork/lnd/lnwire"
+ "github.com/lightningnetwork/lnd/record"
+ "github.com/stretchr/testify/require"
+)
+
+// testSettleCollection checks persisted collection outcomes through each
+// invoice database backend, including failures followed by later successes.
+func testSettleCollection(t *testing.T,
+ makeDB func(t *testing.T) invpkg.InvoiceDB) {
+
+ t.Parallel()
+
+ const value = lnwire.MilliSatoshi(1_000_000)
+ tests := []struct {
+ name string
+ outcomes [2]bool
+ batch bool
+ preCanceled bool
+ perHTLC lnwire.MilliSatoshi
+ wantState invpkg.ContractState
+ }{
+ {
+ name: "failure first",
+ outcomes: [2]bool{false, true},
+ perHTLC: value / 2,
+ wantState: invpkg.ContractCanceled,
+ },
+ {
+ name: "all success",
+ outcomes: [2]bool{true, true},
+ perHTLC: value / 2,
+ wantState: invpkg.ContractSettled,
+ },
+ {
+ name: "all failed",
+ outcomes: [2]bool{false, false},
+ perHTLC: value / 2,
+ wantState: invpkg.ContractCanceled,
+ },
+ {
+ name: "mixed batch",
+ outcomes: [2]bool{true, false},
+ batch: true,
+ perHTLC: value / 2,
+ wantState: invpkg.ContractCanceled,
+ },
+ {
+ name: "overpayment with loss",
+ outcomes: [2]bool{true, false},
+ batch: true,
+ perHTLC: 3 * value / 2,
+ wantState: invpkg.ContractCanceled,
+ },
+ {
+ name: "prior canceled attempt",
+ outcomes: [2]bool{true, true},
+ preCanceled: true,
+ perHTLC: value / 2,
+ wantState: invpkg.ContractSettled,
+ },
+ }
+
+ for _, test := range tests {
+ t.Run(test.name, func(t *testing.T) {
+ t.Parallel()
+
+ // Arrange: Persist a two-shard payment awaiting
+ // final outcomes. Optionally precede it with a
+ // canceled attempt to check later collections.
+ ctx := t.Context()
+ db := makeDB(t)
+ invoice, err := randInvoice(value)
+ require.NoError(t, err)
+ payHash := invoice.Terms.PaymentPreimage.Hash()
+ _, err = db.AddInvoice(ctx, invoice, payHash)
+ require.NoError(t, err)
+ ref := invpkg.InvoiceRefByHash(payHash)
+ apply := func(update *invpkg.InvoiceUpdateDesc) {
+ callback := func(*invpkg.Invoice) (
+ *invpkg.InvoiceUpdateDesc, error) {
+
+ return update, nil
+ }
+ _, err := db.UpdateInvoice(
+ ctx, ref, nil, callback,
+ )
+ require.NoError(t, err)
+ }
+
+ canceledKey := models.CircuitKey{HtlcID: 0}
+ keys := [2]models.CircuitKey{{HtlcID: 1}, {HtlcID: 2}}
+ accepts := make(
+ map[models.CircuitKey]*invpkg.HtlcAcceptDesc,
+ )
+ for _, key := range append(keys[:], canceledKey) {
+ accepts[key] = &invpkg.HtlcAcceptDesc{
+ Amt: test.perHTLC,
+ CustomRecords: make(record.CustomSet),
+ }
+ }
+
+ // A timed-out attempt must not poison a later payment.
+ prior := make(
+ map[models.CircuitKey]*invpkg.HtlcAcceptDesc,
+ )
+ if test.preCanceled {
+ prior[canceledKey] = accepts[canceledKey]
+ apply(&invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.AddHTLCsUpdate,
+ AddHtlcs: prior,
+ })
+ cancels := map[models.CircuitKey]struct{}{
+ canceledKey: {},
+ }
+ apply(&invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.CancelHTLCsUpdate,
+ CancelHtlcs: cancels,
+ })
+ }
+ delete(accepts, canceledKey)
+ state := &invpkg.InvoiceStateUpdateDesc{
+ NewState: invpkg.ContractPendingSettle,
+ Preimage: invoice.Terms.PaymentPreimage,
+ }
+ apply(&invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.AddHTLCsUpdate,
+ AddHtlcs: accepts,
+ State: state,
+ })
+
+ // Act: Apply single outcomes in order; batch cases
+ // defer the update until both outcomes are ready.
+ var collected lnwire.MilliSatoshi
+ for n, success := range test.outcomes {
+ if success {
+ collected += test.perHTLC
+ }
+ if test.batch {
+ continue
+ }
+
+ _, err = db.UpdateInvoice(ctx, ref, nil,
+ getFinalizeHtlcs(success, keys[n]),
+ )
+ require.NoError(t, err)
+
+ // Assert: Reload before the remaining shard
+ // finishes; the invoice must stay pending.
+ stored, err := db.LookupInvoice(ctx, ref)
+ require.NoError(t, err)
+ htlcState := stored.Htlcs[keys[n]].State
+ if n == 0 {
+ require.Equal(
+ t, invpkg.ContractPendingSettle,
+ stored.State,
+ )
+ require.Equal(t, collected+test.perHTLC,
+ stored.AmtPaid)
+ require.Zero(t, stored.SettleIndex)
+ require.True(
+ t, stored.SettleDate.IsZero(),
+ )
+ want := invpkg.HtlcStateFailed
+ if success {
+ want = invpkg.HtlcStateSettled
+ }
+ require.Equal(t, want, htlcState)
+ }
+ }
+
+ if test.batch {
+ // Act: Submit both outcomes together to check
+ // collection within a single database update.
+ finalize := map[models.CircuitKey]bool{
+ keys[0]: test.outcomes[0],
+ keys[1]: test.outcomes[1],
+ }
+ update := &invpkg.InvoiceUpdateDesc{
+ UpdateType: invpkg.
+ FinalizeHTLCsUpdate,
+ FinalizeHtlcs: finalize,
+ }
+ callback := func(*invpkg.Invoice) (
+ *invpkg.InvoiceUpdateDesc, error) {
+
+ return update, nil
+ }
+ _, err = db.UpdateInvoice(
+ ctx, ref, nil, callback,
+ )
+ require.NoError(t, err)
+ }
+
+ // Assert: Reload to check final state, receipts,
+ // settlement metadata and stored HTLC outcomes.
+ stored, err := db.LookupInvoice(ctx, ref)
+ require.NoError(t, err)
+ require.Equal(t, test.wantState, stored.State)
+ require.Equal(t, collected, stored.AmtPaid)
+ if test.wantState == invpkg.ContractSettled {
+ require.NotZero(t, stored.SettleIndex)
+ require.False(t, stored.SettleDate.IsZero())
+ } else {
+ require.Zero(t, stored.SettleIndex)
+ require.True(t, stored.SettleDate.IsZero())
+ }
+ for n, key := range keys {
+ want := invpkg.HtlcStateFailed
+ if test.outcomes[n] {
+ want = invpkg.HtlcStateSettled
+ }
+ require.Equal(t, want, stored.Htlcs[key].State)
+ }
+ if test.preCanceled {
+ require.Equal(t, invpkg.HtlcStateCanceled,
+ stored.Htlcs[canceledKey].State)
+ }
+ })
+ }
+}
### invoices/settle_finality.go
@@ -0,0 +1,346 @@
+package invoices
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "maps"
+ "time"
+
+ "github.com/lightningnetwork/lnd/lntypes"
+)
+
+// DefaultSettleReconcileInterval is the default interval at which the
+// registry checks whether htlcs in HtlcStatePendingSettle reached a final
+// outcome that it wasn't notified of.
+const DefaultSettleReconcileInterval = 5 * time.Minute
+
+const (
+ // minFinalizeRetryDelay is the delay before the first retry of an
+ // outcome that couldn't be written to the invoice database.
+ minFinalizeRetryDelay = time.Second
+
+ // maxFinalizeRetryDelay caps the backoff between retries of outcomes
+ // that couldn't be written to the invoice database.
+ maxFinalizeRetryDelay = time.Minute
+)
+
+// FinalHtlcOutcome describes the final outcome of an htlc.
+type FinalHtlcOutcome struct {
+ // Key identifies the htlc.
+ Key CircuitKey
+
+ // Settled is true if the htlc was settled, and false if it was failed
+ // back or reclaimed by the payer on chain.
+ Settled bool
+
+ // Offchain is true if the htlc was resolved off chain.
+ Offchain bool
+}
+
+// FinalHtlcSource provides channel outcomes used to finalize ordinary invoice
+// payments. Their preimages are released before settlement is irrevocable,
+// so the registry needs this evidence before reporting final credit.
+type FinalHtlcSource interface {
+ // SubscribeFinalHtlcs returns a channel that delivers the final
+ // outcome of htlcs as they become known, and a function to cancel the
+ // subscription. Outcomes that became known before the subscription
+ // was established are not delivered.
+ SubscribeFinalHtlcs() (<-chan FinalHtlcOutcome, func(), error)
+
+ // LookupFinalHtlcs returns the recorded final outcome of those of the
+ // given htlcs that have one. Htlcs without a recorded outcome are
+ // omitted from the result. This is a cheap point lookup per htlc.
+ LookupFinalHtlcs(keys []CircuitKey) (map[CircuitKey]FinalHtlcOutcome,
+ error)
+
+ // InferFinalHtlcs derives the final outcome of those of the given
+ // htlcs whose outcome follows from the channel state, for htlcs
+ // without a recorded outcome. This reads all channels during startup
+ // and nonempty periodic passes to recover channel-only completion.
+ InferFinalHtlcs(keys []CircuitKey) (map[CircuitKey]FinalHtlcOutcome,
+ error)
+}
+
+// trackPendingSettles adds all htlcs of the invoice that are in
+// HtlcStatePendingSettle to the set of htlcs that wait for their final
+// outcome.
+//
+// NOTE: Must be called with the registry lock held.
+func (i *InvoiceRegistry) trackPendingSettles(hash lntypes.Hash,
+ invoice *Invoice) {
+
+ for key, htlc := range invoice.Htlcs {
+ if htlc.State != HtlcStatePendingSettle {
+ continue
+ }
+
+ i.pendingSettles[key] = hash
+ }
+}
+
+// finalizeHtlc records the final outcome of an htlc in HtlcStatePendingSettle.
+// Outcomes of htlcs that aren't pending are ignored, which includes htlcs that
+// don't pay to an invoice.
+func (i *InvoiceRegistry) finalizeHtlc(ctx context.Context,
+ outcome FinalHtlcOutcome) error {
+
+ // Most outcomes are for forwarded htlcs, so check without blocking
+ // invoice processing first.
+ i.RLock()
+ _, ok := i.pendingSettles[outcome.Key]
+ i.RUnlock()
+ if !ok {
+ return nil
+ }
+
+ i.Lock()
+ defer i.Unlock()
+
+ hash, ok := i.pendingSettles[outcome.Key]
+ if !ok {
+ return nil
+ }
+
+ ref := InvoiceRefByHash(hash)
+
+ var finalized bool
+ invoice, err := i.idb.UpdateInvoice(
+ ctx, ref, nil,
+ func(inv *Invoice) (*InvoiceUpdateDesc, error) {
+ htlc, ok := inv.Htlcs[outcome.Key]
+ if !ok {
+ return nil, fmt.Errorf("htlc %v not found on "+
+ "invoice %v", outcome.Key, ref)
+ }
+
+ // The htlc may have been finalized already, for
+ // example if its outcome was delivered twice.
+ if htlc.State != HtlcStatePendingSettle {
+ return nil, nil
+ }
+ finalized = true
+
+ return &InvoiceUpdateDesc{
+ UpdateType: FinalizeHTLCsUpdate,
+ FinalizeHtlcs: map[CircuitKey]bool{
+ outcome.Key: outcome.Settled,
+ },
+ }, nil
+ },
+ )
+ if err != nil {
+ return fmt.Errorf("unable to finalize htlc %v on invoice %v: "+
+ "%w", outcome.Key, ref, err)
+ }
+
+ delete(i.pendingSettles, outcome.Key)
+
+ if !finalized {
+ return nil
+ }
+
+ if !outcome.Settled {
+ log.Warnf("Invoice%v: htlc %v released its preimage but was "+
+ "not settled (offchain=%v), invoice state is now %v, "+
+ "amt_paid=%v", ref, outcome.Key,
+ outcome.Offchain, invoice.State, invoice.AmtPaid)
+ } else {
+ log.Debugf("Invoice%v: htlc %v settled (offchain=%v), "+
+ "invoice state is now %v", ref, outcome.Key,
+ outcome.Offchain, invoice.State)
+ }
+
+ i.notifyClients(hash, invoice, nil)
+
+ return nil
+}
+
+// reconcilePendingSettles recovers ordinary outcomes missed by the live
+// subscription. A completed channel is only fallback evidence: re-read the
+// records after scanning so a concurrent durable failure overrides inferred
+// success before any invoice is credited.
+func (i *InvoiceRegistry) reconcilePendingSettles(ctx context.Context) error {
+ i.RLock()
+ keys := make([]CircuitKey, 0, len(i.pendingSettles))
+ for key := range i.pendingSettles {
+ keys = append(keys, key)
+ }
+ i.RUnlock()
+
+ // Most ticks have no pending work, so avoid channel scans while idle.
+ if len(keys) == 0 {
+ return nil
+ }
+
+ source := i.cfg.FinalHtlcSource
+ recorded, err := source.LookupFinalHtlcs(keys)
+ if err != nil {
+ return err
+ }
+
+ // Own the merged result even when a source has no recorded outcomes.
+ outcomes := make(map[CircuitKey]FinalHtlcOutcome, len(recorded))
+ maps.Copy(outcomes, recorded)
+
+ var remaining []CircuitKey
+ for _, key := range keys {
+ if _, ok := outcomes[key]; !ok {
+ remaining = append(remaining, key)
+ }
+ }
+
+ if len(remaining) > 0 {
+ inferred, err := source.InferFinalHtlcs(remaining)
+ if err != nil {
+ return err
+ }
+
+ // A resolver persists its outcome before closing the channel.
+ // If that happened during the scan, the record is stronger
+ // evidence than the now-resolved channel summary. On a read
+ // failure, leave every candidate pending instead of crediting
+ // it.
+ recorded, err := source.LookupFinalHtlcs(remaining)
+ if err != nil {
+ return err
+ }
+
+ maps.Copy(outcomes, inferred)
+ maps.Copy(outcomes, recorded)
+ }
+
+ log.Debugf("Reconciled %d of %d htlcs pending settlement",
+ len(outcomes), len(keys))
+
+ // A failed invoice write must not hold up other outcomes. The failed
+ // key remains tracked and will be retried by the next reconciliation.
+ var errs []error
+ for _, outcome := range outcomes {
+ if err := i.finalizeHtlc(ctx, outcome); err != nil {
+ errs = append(errs, err)
+ }
+ }
+
+ return errors.Join(errs...)
+}
+
+// startSettleFinalizer subscribes to final htlc outcomes, loads all htlcs
+// that wait for their final outcome and reconciles them. The subscription is
+// established before the lookup, so that no outcome can be missed in between.
+//
+// A failure to reconcile on start doesn't fail the start of the registry.
+// Pending work is retried periodically, including channel-only completion
+// that becomes inferable after startup without a per-HTLC notification.
+func (i *InvoiceRegistry) startSettleFinalizer(ctx context.Context,
+ pendingInvoices map[lntypes.Hash]Invoice) error {
+
+ if i.cfg.FinalHtlcSource == nil {
+ log.Warnf("No final htlc source configured, invoices will " +
+ "remain in PendingSettle")
+
+ return nil
+ }
+
+ outcomes, cancel, err := i.cfg.FinalHtlcSource.SubscribeFinalHtlcs()
+ if err != nil {
+ return fmt.Errorf("unable to subscribe to final htlc "+
+ "outcomes: %w", err)
+ }
+
+ i.Lock()
+ for hash, invoice := range pendingInvoices {
+ i.trackPendingSettles(hash, &invoice)
+ }
+ i.Unlock()
+
+ interval := i.cfg.SettleReconcileInterval
+ if interval == 0 {
+ interval = DefaultSettleReconcileInterval
+ }
+
+ i.wg.Add(1)
+ go func() {
+ defer i.wg.Done()
+ defer cancel()
+
+ ticker := time.NewTicker(interval)
+ defer ticker.Stop()
+
+ // Outcomes that couldn't be written, for example because the
+ // invoice database was unavailable, are retried with backoff
+ // rather than waiting for the next reconciliation.
+ retries := make(map[CircuitKey]FinalHtlcOutcome)
+ retryDelay := minFinalizeRetryDelay
+ var retryTimer <-chan time.Time
+
+ finalize := func(outcome FinalHtlcOutcome) {
+ err := i.finalizeHtlc(ctx, outcome)
+ if err == nil {
+ delete(retries, outcome.Key)
+ return
+ }
+
+ log.Errorf("Unable to finalize htlc, retrying in %v: "+
+ "%v", retryDelay, err)
+
+ retries[outcome.Key] = outcome
+ if retryTimer == nil {
+ retryTimer = time.After(retryDelay)
+ }
+ }
+
+ for {
+ select {
+ case outcome, ok := <-outcomes:
+ if !ok {
+ log.Errorf("Final htlc outcome " +
+ "subscription closed")
+
+ return
+ }
+
+ finalize(outcome)
+
+ case <-retryTimer:
+ retryTimer = nil
+ pending := maps.Clone(retries)
+ for _, outcome := range pending {
+ finalize(outcome)
+ }
+
+ // Back off while writes keep failing.
+ if len(retries) == 0 {
+ retryDelay = minFinalizeRetryDelay
+ } else {
+ retryDelay = min(
+ 2*retryDelay,
+ maxFinalizeRetryDelay,
+ )
+ }
+
+ // Live events and failed-write retries cover normal
+ // delivery. Channel-only completions, including breach
+ // cleanup, also need inference after an otherwise
+ // successful startup.
+ case <-ticker.C:
+ err := i.reconcilePendingSettles(ctx)
+ if err != nil {
+ log.Errorf("Unable to reconcile htlcs "+
+ "pending settlement: %v", err)
+ }
+
+ case <-i.quit:
+ return
+ }
+ }
+ }()
+
+ err = i.reconcilePendingSettles(ctx)
+ if err != nil {
+ log.Errorf("Unable to reconcile htlcs pending settlement on "+
+ "start, retrying every %v: %v", interval, err)
+ }
+
+ return nil
+}
### invoices/sql_migration_test.go
@@ -109,8 +109,17 @@ func randHTLCRapid(t *rapid.T, invoice *Invoice, amt lnwire.MilliSatoshi) (
htlc.State = HtlcStateSettled
htlc.ResolveTime = randInvoiceTime(invoice)
+ case ContractPendingSettle:
+ htlc.State = HtlcStatePendingSettle
+ htlc.ResolveTime = randInvoiceTime(invoice)
+
case ContractCanceled:
htlc.State = HtlcStateCanceled
+ if !invoice.IsAMP() {
+ htlc.State = rapid.SampledFrom([]HtlcState{
+ HtlcStateCanceled, HtlcStateFailed,
+ }).Draw(t, "canceledHtlcState")
+ }
htlc.ResolveTime = randInvoiceTime(invoice)
case ContractAccepted:
@@ -696,10 +705,16 @@ func generateTestInvoiceRapid(t *rapid.T, mpp bool, amp bool) *Invoice {
created := randTime()
- const maxContractState = 3
+ const maxContractState = 4
state := ContractState(
rapid.IntRange(0, maxContractState).Draw(t, "ContractState"),
)
+
+ // AMP keeps its existing settled fixtures; only ordinary invoices
+ // produce the new pending state in this change.
+ if amp && state == ContractPendingSettle {
+ state = ContractSettled
+ }
var (
settled time.Time
settleIndex uint64
@@ -733,7 +748,7 @@ func generateTestInvoiceRapid(t *rapid.T, mpp bool, amp bool) *Invoice {
}
for _, htlc := range invoice.Htlcs {
- if htlc.State == HtlcStateSettled {
+ if htlc.State.PreimageReleased() {
invoice.AmtPaid += htlc.Amt
}
}
### invoices/sql_store.go
@@ -73,6 +73,12 @@ type SQLInvoiceQueries interface { //nolint:interfacebloat
FetchPendingInvoices(ctx context.Context,
arg sqlc.FetchPendingInvoicesParams) ([]sqlc.Invoice, error)
+ // FetchPendingSettleInvoices returns invoices containing at least one
+ // pending-settle HTLC, ordered by id ascending.
+ FetchPendingSettleInvoices(ctx context.Context,
+ arg sqlc.FetchPendingSettleInvoicesParams) ([]sqlc.Invoice,
+ error)
+
// FilterInvoicesBySettleIndex returns settled invoices whose
// settle_index is >= the given bound, ordered by id ascending. The
// caller must always supply a concrete lower bound so the planner can
@@ -761,9 +767,8 @@ func (i *SQLStore) LookupInvoice(ctx context.Context,
return *invoice, nil
}
-// FetchPendingInvoices returns all the invoices that are currently in a
-// "pending" state. An invoice is pending if it has been created but not yet
-// settled or canceled.
+// FetchPendingInvoices returns all invoices that are currently in a pending
+// state.
func (i *SQLStore) FetchPendingInvoices(ctx context.Context) (
map[lntypes.Hash]Invoice, error) {
@@ -813,6 +818,56 @@ func (i *SQLStore) FetchPendingInvoices(ctx context.Context) (
return invoices, nil
}
+// FetchPendingSettleInvoices returns all invoices containing at least one htlc
+// whose final outcome is still pending.
+func (i *SQLStore) FetchPendingSettleInvoices(ctx context.Context) (
+ map[lntypes.Hash]Invoice, error) {
+
+ var invoices map[lntypes.Hash]Invoice
+
+ readTxOpt := sqldb.ReadTxOpt()
+ err := i.db.ExecTx(ctx, readTxOpt, func(db SQLInvoiceQueries) error {
+ var cursor int64
+ limit := int32(i.opts.paginationLimit)
+ for {
+ params := sqlc.FetchPendingSettleInvoicesParams{
+ IDCursor: cursor,
+ NumLimit: limit,
+ }
+
+ rows, err := db.FetchPendingSettleInvoices(ctx, params)
+ if err != nil && !errors.Is(err, sql.ErrNoRows) {
+ return fmt.Errorf("unable to get pending-"+
+ "settle invoices from db: %w", err)
+ }
+
+ for _, row := range rows {
+ hash, invoice, err := fetchInvoiceData(
+ ctx, db, row, nil, true,
+ )
+ if err != nil {
+ return err
+ }
+
+ invoices[*hash] = *invoice
+ cursor = row.ID
+ }
+
+ if int32(len(rows)) < limit {
+ return nil
+ }
+ }
+ }, func() {
+ invoices = make(map[lntypes.Hash]Invoice)
+ })
+ if err != nil {
+ return nil, fmt.Errorf("unable to fetch pending-settle "+
+ "invoices: %w", err)
+ }
+
+ return invoices, nil
+}
+
// InvoicesSettledSince can be used by callers to catch up any settled invoices
// they missed within the settled invoice time series. We'll return all known
// settled invoice that have a settle index higher than the passed idx.
@@ -1655,7 +1710,8 @@ func (i *SQLStore) DeleteInvoice(ctx context.Context,
return nil
}
-// DeleteCanceledInvoices removes all canceled invoices from the database.
+// DeleteCanceledInvoices removes canceled invoices, preserving ordinary
+// invoices with settled or failed released HTLCs and their release history.
func (i *SQLStore) DeleteCanceledInvoices(ctx context.Context) error {
writeTxOpt := sqldb.WriteTxOpt()
err := i.db.ExecTx(ctx, writeTxOpt, func(db SQLInvoiceQueries) error {
### invoices/test_utils_test.go
@@ -22,6 +22,7 @@ import (
"github.com/lightningnetwork/lnd/lnwire"
"github.com/lightningnetwork/lnd/record"
"github.com/lightningnetwork/lnd/zpay32"
+ "github.com/stretchr/testify/mock"
"github.com/stretchr/testify/require"
)
@@ -139,14 +140,84 @@ var (
)
type testContext struct {
- idb invpkg.InvoiceDB
- registry *invpkg.InvoiceRegistry
- notifier *mockChainNotifier
- clock *clock.TestClock
+ idb invpkg.InvoiceDB
+ registry *invpkg.InvoiceRegistry
+ notifier *mockChainNotifier
+ clock *clock.TestClock
+ finalHtlcs *mockFinalHtlcSource
t *testing.T
}
+// mockFinalHtlcSource supplies arranged recovery evidence and a test-owned
+// live channel without implementing a second final-outcome store.
+type mockFinalHtlcSource struct {
+ mock.Mock
+
+ outcomes chan invpkg.FinalHtlcOutcome
+}
+
+// newMockFinalHtlcSource arranges one subscription and optional empty lookups
+// for ordinary fixture use. Regression tests replace those optional calls in
+// Arrange when they need specific recovery evidence or ordering.
+func newMockFinalHtlcSource(t *testing.T) *mockFinalHtlcSource {
+ t.Helper()
+
+ source := &mockFinalHtlcSource{
+ outcomes: make(chan invpkg.FinalHtlcOutcome),
+ }
+ source.On("SubscribeFinalHtlcs").Return(
+ (<-chan invpkg.FinalHtlcOutcome)(source.outcomes),
+ func() {}, nil,
+ ).Once()
+ source.On("LookupFinalHtlcs", mock.Anything).Return(nil, nil).Maybe()
+ source.On("InferFinalHtlcs", mock.Anything).Return(nil, nil).Maybe()
+
+ // Fixtures register Stop later, so LIFO cleanup stops all consumers
+ // before this single expectation verification reads the mock.
+ t.Cleanup(func() {
+ source.AssertExpectations(t)
+ })
+
+ return source
+}
+
+// SubscribeFinalHtlcs returns the arranged test-owned event channel and its
+// cancellation callback so subscription ownership matches the real source.
+func (m *mockFinalHtlcSource) SubscribeFinalHtlcs() (
+ <-chan invpkg.FinalHtlcOutcome, func(), error) {
+
+ args := m.Called()
+ outcomes, _ := args.Get(0).(<-chan invpkg.FinalHtlcOutcome)
+ cancel, _ := args.Get(1).(func())
+
+ return outcomes, cancel, args.Error(2)
+}
+
+// LookupFinalHtlcs returns only the durable evidence arranged for these keys;
+// nil represents a source that has not recorded any of their outcomes.
+func (m *mockFinalHtlcSource) LookupFinalHtlcs(keys []invpkg.CircuitKey) (
+ map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome, error) {
+
+ args := m.Called(keys)
+ res, _ := args.Get(0).(map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome)
+
+ return res, args.Error(1)
+}
+
+// InferFinalHtlcs returns arranged channel evidence independently of recorded
+// outcomes so tests can control the real reconciliation boundary.
+func (m *mockFinalHtlcSource) InferFinalHtlcs(keys []invpkg.CircuitKey) (
+ map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome, error) {
+
+ args := m.Called(keys)
+ res, _ := args.Get(0).(map[invpkg.CircuitKey]invpkg.FinalHtlcOutcome)
+
+ return res, args.Error(1)
+}
+
+var _ invpkg.FinalHtlcSource = (*mockFinalHtlcSource)(nil)
+
func defaultRegistryConfig() invpkg.RegistryConfig {
return invpkg.RegistryConfig{
FinalCltvRejectDelta: testFinalCltvRejectDelta,
@@ -155,6 +226,8 @@ func defaultRegistryConfig() invpkg.RegistryConfig {
}
}
+// newTestContext owns a registry backed by the selected real database and a
+// controlled finality source, stopping consumers before verifying the mock.
func newTestContext(t *testing.T,
registryCfg *invpkg.RegistryConfig,
makeDB func(t *testing.T) (invpkg.InvoiceDB,
@@ -175,6 +248,12 @@ func newTestContext(t *testing.T,
}
cfg.Clock = clock
+ finalHtlcs, ok := cfg.FinalHtlcSource.(*mockFinalHtlcSource)
+ if !ok {
+ finalHtlcs = newMockFinalHtlcSource(t)
+ cfg.FinalHtlcSource = finalHtlcs
+ }
+
// Instantiate and start the invoice ctx.registry.
registry := invpkg.NewRegistry(idb, expiryWatcher, &cfg)
@@ -184,16 +263,69 @@ func newTestContext(t *testing.T,
})
ctx := testContext{
- idb: idb,
- registry: registry,
- notifier: notifier,
- clock: clock,
- t: t,
+ idb: idb,
+ registry: registry,
+ notifier: notifier,
+ clock: clock,
+ finalHtlcs: finalHtlcs,
+ t: t,
}
return &ctx
}
+// finalizeHtlc delivers the final outcome of an htlc to the registry, like
+// the link or the contract court would, and waits until the registry recorded
+// it on the invoice identified by ref.
+func (c *testContext) finalizeHtlc(ref invpkg.InvoiceRef,
+ key invpkg.CircuitKey, settled bool) {
+
+ c.t.Helper()
+
+ outcome := invpkg.FinalHtlcOutcome{
+ Key: key,
+ Settled: settled,
+ Offchain: true,
+ }
+
+ select {
+ case c.finalHtlcs.outcomes <- outcome:
+ case <-time.After(testTimeout):
+ c.t.Fatalf("registry didn't receive final outcome of %v", key)
+ }
+
+ c.waitHtlcFinal(ref, key)
+}
+
+// waitHtlcFinal waits until the htlc on the invoice identified by ref is no
+// longer pending settlement.
+func (c *testContext) waitHtlcFinal(ref invpkg.InvoiceRef,
+ key invpkg.CircuitKey) {
+
+ c.t.Helper()
+
+ isFinal := func() bool {
+ inv, err := c.registry.LookupInvoiceByRef(
+ c.t.Context(), ref,
+ )
+ if err != nil {
+ return false
+ }
+
+ htlc, ok := inv.Htlcs[key]
+
+ return ok && htlc.State != invpkg.HtlcStatePendingSettle
+ }
+
+ // The outcome is usually recorded right away, so avoid waiting for the
+ // first tick.
+ if isFinal() {
+ return
+ }
+
+ require.Eventually(c.t, isFinal, testTimeout, 5*time.Millisecond)
+}
+
func getCircuitKey(htlcID uint64) invpkg.CircuitKey {
return invpkg.CircuitKey{
ChanID: lnwire.ShortChannelID{
### invoices/update.go
@@ -121,13 +121,15 @@ func resolveReplayedHtlc(ctx *invoiceUpdateCtx, inv *Invoice) (bool,
}
switch htlc.State {
- case HtlcStateCanceled:
+ case HtlcStateCanceled, HtlcStateFailed:
return true, ctx.failRes(ResultReplayToCanceled), nil
case HtlcStateAccepted:
return true, ctx.acceptRes(resultReplayToAccepted), nil
- case HtlcStateSettled:
+ // A replayed htlc whose settle isn't final yet must be settled again,
+ // otherwise we could withhold a preimage our peer already learned.
+ case HtlcStateSettled, HtlcStatePendingSettle:
var preimage *lntypes.Preimage
switch {
// AMP invoices store a separate preimage on each HTLC.
@@ -276,6 +278,12 @@ func updateMpp(ctx *invoiceUpdateCtx, inv *Invoice) (*InvoiceUpdateDesc,
htlcSet := inv.HTLCSet(setID, HtlcStateAccepted)
+ // AMP invoices remain open after a set settles. Reject fresh shards
+ // for that set before their update can fail the link carrying them.
+ if len(inv.HTLCSet(setID, HtlcStateSettled)) > 0 {
+ return nil, ctx.failRes(ResultInvoiceNotOpen), nil
+ }
+
// Check whether total amt matches other HTLCs in the set.
var newSetTotal lnwire.MilliSatoshi
for _, htlc := range htlcSet {
@@ -368,8 +376,14 @@ func updateMpp(ctx *invoiceUpdateCtx, inv *Invoice) (*InvoiceUpdateDesc,
htlcPreimage = *inv.Terms.PaymentPreimage
}
+ // Ordinary invoices wait for final outcomes. AMP keeps its existing
+ // release-time set settlement until its finality work is introduced.
+ newState := ContractPendingSettle
+ if ctx.amp != nil {
+ newState = ContractSettled
+ }
update.State = &InvoiceStateUpdateDesc{
- NewState: ContractSettled,
+ NewState: newState,
Preimage: inv.Terms.PaymentPreimage,
HTLCPreimages: htlcPreimages,
SetID: setID,
@@ -555,7 +569,7 @@ func updateLegacy(ctx *invoiceUpdateCtx,
case ContractAccepted:
return &update, ctx.acceptRes(resultDuplicateToAccepted), nil
- case ContractSettled:
+ case ContractSettled, ContractPendingSettle:
// Legacy settlement uses the invoice-level payment preimage.
preimage := inv.Terms.PaymentPreimage
if preimage == nil {
@@ -586,7 +600,7 @@ func updateLegacy(ctx *invoiceUpdateCtx,
}
update.State = &InvoiceStateUpdateDesc{
- NewState: ContractSettled,
+ NewState: ContractPendingSettle,
Preimage: preimage,
}
### invoices/update_invoice.go
@@ -144,6 +144,12 @@ func UpdateInvoice(hash *lntypes.Hash, invoice *Invoice,
return nil, err
}
+ case FinalizeHTLCsUpdate:
+ err := finalizeHTLCs(invoice, updateTime, update, updater)
+ if err != nil {
+ return nil, err
+ }
+
default:
return nil, fmt.Errorf("unknown update type: %s",
update.UpdateType)
@@ -366,7 +372,7 @@ func addHTLCs(invoice *Invoice, hash *lntypes.Hash, updateTime time.Time,
}
accepted := htlc.State == HtlcStateAccepted
- settled := htlc.State == HtlcStateSettled
+ settled := htlc.State.PreimageReleased()
invoiceStateReady := accepted || settled
if !invoiceIsAMP {
@@ -446,13 +452,14 @@ func settleHodlInvoice(invoice *Invoice, hash *lntypes.Hash,
"not a hodl invoice", invoice.AddIndex)
}
- // TODO(positiveblue): because NewState can only be ContractSettled we
- // can remove it from the API and set it here directly.
+ // TODO(positiveblue): because NewState can only be
+ // ContractPendingSettle we can remove it from the API and set it here
+ // directly.
switch {
case update == nil:
fallthrough
- case update.NewState != ContractSettled:
+ case update.NewState != ContractPendingSettle:
return fmt.Errorf("unable to settle hodl invoice: "+
"not valid InvoiceUpdateDesc.State: %v", update)
@@ -468,34 +475,35 @@ func settleHodlInvoice(invoice *Invoice, hash *lntypes.Hash,
return err
}
- if newState == nil || *newState != ContractSettled {
+ if newState == nil || *newState != ContractPendingSettle {
return fmt.Errorf("unable to settle hodl invoice: "+
- "new computed state is not settled: %s", newState)
+ "new computed state is not pending settle: %s",
+ newState)
}
err = updater.UpdateInvoiceState(
- ContractSettled, update.Preimage,
+ ContractPendingSettle, update.Preimage,
)
if err != nil {
return err
}
- invoice.State = ContractSettled
+ invoice.State = ContractPendingSettle
invoice.Terms.PaymentPreimage = update.Preimage
// TODO(positiveblue): this logic can be further simplified.
var amtPaid lnwire.MilliSatoshi
for key, htlc := range invoice.Htlcs {
settled, _, err := getUpdatedHtlcState(
- htlc, ContractSettled, nil,
+ htlc, ContractPendingSettle, nil,
)
if err != nil {
return err
}
if settled {
err = resolveHtlc(
- key, htlc, HtlcStateSettled, updateTime,
+ key, htlc, HtlcStatePendingSettle, updateTime,
updater,
)
if err != nil {
@@ -589,6 +597,77 @@ func cancelInvoice(invoice *Invoice, hash *lntypes.Hash,
return nil
}
+// finalizeHTLCs applies final ordinary HTLC outcomes within the invoice
+// transaction. Failed value is removed from the paid amount; the parent
+// completes after its pending HTLCs do, while an already-settled parent keeps
+// its terminal state when a later duplicate finishes.
+func finalizeHTLCs(invoice *Invoice, updateTime time.Time,
+ update *InvoiceUpdateDesc, updater InvoiceUpdater) error {
+
+ if len(update.FinalizeHtlcs) == 0 {
+ return errors.New("no htlcs to finalize")
+ }
+
+ for key, settled := range update.FinalizeHtlcs {
+ htlc, ok := invoice.Htlcs[key]
+ if !ok {
+ return fmt.Errorf("finalize of non-existent htlc %v",
+ key)
+ }
+
+ // Identify a repeated success so callers can distinguish this
+ // state rejection from an unrelated storage failure.
+ if htlc.State == HtlcStateSettled {
+ return fmt.Errorf("htlc %v: %w", key,
+ ErrHTLCAlreadySettled)
+ }
+
+ if htlc.State != HtlcStatePendingSettle {
+ return fmt.Errorf("htlc %v finalized in state %v", key,
+ htlc.State)
+ }
+
+ newState := HtlcStateSettled
+ if !settled {
+ newState = HtlcStateFailed
+ }
+
+ err := resolveHtlc(key, htlc, newState, updateTime, updater)
+ if err != nil {
+ return err
+ }
+ }
+
+ // The amount paid only counts htlcs that settled or may still settle.
+ var amtPaid lnwire.MilliSatoshi
+ var pending, failed bool
+ for _, htlc := range invoice.Htlcs {
+ if htlc.State.PreimageReleased() {
+ amtPaid += htlc.Amt
+ }
+
+ pending = pending || htlc.State == HtlcStatePendingSettle
+ failed = failed || htlc.State == HtlcStateFailed
+ }
+
+ if invoice.State == ContractPendingSettle && !pending {
+ newState := ContractSettled
+ // Only a lost released HTLC prevents collection. Earlier
+ // canceled attempts never released a preimage and don't count.
+ if failed {
+ newState = ContractCanceled
+ }
+
+ err := updater.UpdateInvoiceState(newState, nil)
+ if err != nil {
+ return err
+ }
+ invoice.State = newState
+ }
+
+ return updateInvoiceAmtPaid(invoice, amtPaid, updater)
+}
+
// getUpdatedInvoiceState validates and processes an invoice state update. The
// new state to transition to is returned, so the caller is able to select
// exactly how the invoice state is updated. Note that for AMP invoices this
@@ -602,6 +681,12 @@ func getUpdatedInvoiceState(invoice *Invoice, hash *lntypes.Hash,
return nil, ErrInvoiceCannotOpen
}
+ // Ordinary invoices settle only through final outcomes. AMP keeps its
+ // existing set settlement updates while its parent invoice stays open.
+ if !invoice.IsAMP() && update.NewState == ContractSettled {
+ return nil, ErrInvoiceCannotSettle
+ }
+
switch invoice.State {
// Once a contract is accepted, we can only transition to settled or
// canceled. Forbid transitioning back into this state. Otherwise this
@@ -660,14 +745,19 @@ func getUpdatedInvoiceState(invoice *Invoice, hash *lntypes.Hash,
// Fail if we still don't have a preimage when transitioning to
// settle the non-AMP invoice.
- case update.NewState == ContractSettled &&
+ case update.NewState == ContractPendingSettle &&
invoice.Terms.PaymentPreimage == nil:
return nil, errors.New("unknown preimage")
}
return &update.NewState, nil
+ // Once we released the preimage, the invoice can neither be canceled
+ // nor settled again. It only moves on through a FinalizeHTLCsUpdate.
+ case ContractPendingSettle:
+ return nil, ErrInvoiceAlreadySettled
+
// Once settled, we are in a terminal state.
case ContractSettled:
return nil, ErrInvoiceAlreadySettled
@@ -794,28 +884,30 @@ func getUpdatedHtlcState(htlc *InvoiceHTLC,
settled = true
}
- // Only persist the changes if the invoice is moving to the
- // settled state, and we're actually updating the state to
- // settled.
+ // Ordinary preimage release waits for a final outcome. AMP
+ // retains its current release-time HTLC settlement behavior.
newState := htlc.State
if settled {
newState = HtlcStateSettled
+ if htlc.AMP == nil {
+ newState = HtlcStatePendingSettle
+ }
}
return persist && settled, newState, nil
}
- if invoiceState == ContractSettled {
+ if invoiceState.PreimageReleased() {
// Check that we can settle the HTLCs. For legacy and MPP HTLCs
// this will be a NOP, but for AMP HTLCs this asserts that we
// have a valid hash/preimage pair. Passing true permits the
- // method to update the HTLC to HtlcStateSettled.
+ // method to persist the ordinary pending or AMP settled state.
return trySettle(true)
}
- // We should never find a settled HTLC on an invoice that isn't in
- // ContractSettled.
- if htlc.State == HtlcStateSettled {
+ // We should never find an HTLC we released the preimage for on an
+ // invoice that we didn't settle.
+ if htlc.State.PreimageReleased() {
return false, htlc.State, ErrHTLCAlreadySettled
}
### invoices/update_invoice_test.go
@@ -24,6 +24,8 @@ type updateHTLCTest struct {
func TestUpdateHTLC(t *testing.T) {
t.Parallel()
+ // Arrange accepted, released and final children with fixed timestamps
+ // so the cases distinguish preimage release from a final resolution.
testNow := time.Now()
setID := [32]byte{0x01}
ampRecord := record.NewAMP([32]byte{0x02}, setID, 3)
@@ -130,7 +132,7 @@ func TestUpdateHTLC(t *testing.T) {
AcceptTime: testNow,
ResolveTime: testNow,
Expiry: 40,
- State: HtlcStateSettled,
+ State: HtlcStatePendingSettle,
CustomRecords: make(record.CustomSet),
WireCustomRecords: make(lnwire.CustomRecords),
AMP: nil,
@@ -743,15 +745,23 @@ func TestUpdateHTLC(t *testing.T) {
},
}
+ // Act on each independent child; the helper applies the returned
+ // transition and asserts the complete child and any expected error.
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
testUpdateHTLC(t, test, testNow)
})
}
}
+// testUpdateHTLC applies one transition to a copy, preserving the table's
+// original child while checking both its resulting state and timestamp.
func testUpdateHTLC(t *testing.T, test updateHTLCTest, now time.Time) {
+ // Arrange an isolated child so another case cannot inherit mutations.
htlc := test.input.Copy()
+
+ // Act through the shared state selector, applying only changes it
+ // requests, as the invoice updater does when storing a resolution.
stateChanged, state, err := getUpdatedHtlcState(
htlc, test.invState, test.setID,
)
@@ -760,6 +770,8 @@ func testUpdateHTLC(t *testing.T, test updateHTLCTest, now time.Time) {
htlc.ResolveTime = now
}
+ // Assert the full returned state and error, including preservation of
+ // a released child's timestamp when no transition is permitted.
require.Equal(t, test.expErr, err)
require.Equal(t, test.output, *htlc)
}
@@ -864,6 +876,8 @@ func TestResolveReplayedHtlcSettled(t *testing.T) {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
+ // Arrange an existing final child and its recorded
+ // preimage, checking the stored replay evidence.
circuitKey := CircuitKey{HtlcID: 1}
ctx := &invoiceUpdateCtx{
hash: test.paymentHash,
@@ -882,9 +896,15 @@ func TestResolveReplayedHtlcSettled(t *testing.T) {
},
}
+ // Act through replay resolution before new-shard
+ // checks.
replayed, resolution, err := resolveReplayedHtlc(
ctx, invoice,
)
+
+ // Assert replay is recognized and returns the
+ // appropriate preimage or validation error without
+ // creating a new HTLC.
require.True(t, replayed)
switch {
@@ -1113,12 +1133,17 @@ func TestUpdateLegacyRejectsNilPreimageSettle(t *testing.T) {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
+ // Arrange the open/paid paths without a preimage
+ // so neither can produce a fulfill for a new circuit.
ctx, invoice := newLegacyUpdateTestContext(
t, test.state,
)
invoice.Terms.PaymentPreimage = nil
+ // Act through legacy admission rather than replay.
update, resolution, err := updateLegacy(ctx, invoice)
+ // Assert normal rejection without an update or an
+ // internal error that would fail the link.
require.NoError(t, err)
require.Nil(t, update)
requireFailResolution(
@@ -1206,6 +1231,49 @@ func TestUpdateLegacyValidatesKeysendRecord(t *testing.T) {
}
}
+// TestUpdateMppRejectsSettledAmpSet checks that a fresh shard for a paid AMP
+// set is rejected without an updater error that would fail the channel link.
+func TestUpdateMppRejectsSettledAmpSet(t *testing.T) {
+ t.Parallel()
+
+ // Arrange a reusable AMP invoice with one paid set and a fresh circuit
+ // for that same set. A partial amount avoids preimage reconstruction,
+ // isolating the closed-set admission guard.
+ settledSetID := [32]byte{1}
+ ctx, invoice := newLegacyUpdateTestContext(t, ContractOpen)
+ ctx.circuitKey = CircuitKey{HtlcID: 2}
+ ctx.amtPaid = 400
+ ctx.mpp = record.NewMPP(1000, invoice.Terms.PaymentAddr)
+ ctx.amp = record.NewAMP([32]byte{3}, settledSetID, 1)
+ invoice.Terms.PaymentPreimage = nil
+ invoice.Terms.Features = lnwire.NewFeatureVector(
+ lnwire.NewRawFeatureVector(lnwire.AMPRequired), lnwire.Features,
+ )
+ invoice.AmtPaid = 1000
+ invoice.Htlcs[CircuitKey{HtlcID: 1}] = &InvoiceHTLC{
+ Amt: 1000,
+ MppTotalAmt: 1000,
+ State: HtlcStateSettled,
+ AMP: &InvoiceHtlcAMPData{
+ Record: *record.NewAMP([32]byte{4}, settledSetID, 0),
+ },
+ }
+
+ // Act through new-shard admission so rejection must be a normal HTLC
+ // resolution rather than an updater error that fails its channel link.
+ update, resolution, err := updateInvoice(ctx, invoice)
+
+ // Assert rejection preserves the paid set and its accounting, while
+ // returning no invoice update and no internal error to the link.
+ require.NoError(t, err)
+ require.Nil(t, update)
+ requireFailResolution(t, resolution, ResultInvoiceNotOpen)
+ require.Equal(t, ContractOpen, invoice.State)
+ require.Equal(t, lnwire.MilliSatoshi(1000), invoice.AmtPaid)
+ require.Zero(t, invoice.SettleIndex)
+ require.Len(t, invoice.Htlcs, 1)
+}
+
// newLegacyUpdateTestContext creates a minimal legacy invoice and update
// context for exercising update selection and settlement outcomes.
func newLegacyUpdateTestContext(t *testing.T,
### itest/list_on_test.go
@@ -443,6 +443,10 @@ var allTestCases = []*lntest.TestCase{
Name: "send multi path payment",
TestFunc: testSendMultiPathPayment,
},
+ {
+ Name: "MPP released sibling restart",
+ TestFunc: testMPPReleasedSiblingRestart,
+ },
{
Name: "sendpayment amp invoice",
TestFunc: testSendPaymentAMPInvoice,
### itest/lnd_mpp_test.go
@@ -6,8 +6,10 @@ import (
"time"
"github.com/btcsuite/btcd/btcutil/v2"
+ "github.com/lightningnetwork/lnd/amp"
"github.com/lightningnetwork/lnd/chainreg"
"github.com/lightningnetwork/lnd/lnrpc"
+ "github.com/lightningnetwork/lnd/lnrpc/invoicesrpc"
"github.com/lightningnetwork/lnd/lnrpc/routerrpc"
"github.com/lightningnetwork/lnd/lntest"
"github.com/lightningnetwork/lnd/lntest/node"
@@ -89,7 +91,9 @@ func testSendMultiPathPayment(ht *lntest.HarnessTest) {
require.GreaterOrEqual(ht, succeeded, minExpectedShards,
"expected shards not reached")
- // Make sure Bob show the invoice as settled for the full amount.
+ // The payer can finish before Bob locks in the settle. Wait through
+ // the existing address-based assertion before checking final credit.
+ ht.AssertInvoiceSettled(mts.bob, invoices[0].PaymentAddr)
inv := mts.bob.RPC.LookupInvoice(rHash)
require.EqualValues(ht, paymentAmt, inv.AmtPaidSat,
@@ -240,6 +244,146 @@ func testSendToRouteMultiPath(ht *lntest.HarnessTest) {
mts.closeChannels()
}
+// testMPPReleasedSiblingRestart checks ordinary MPP recovery when the same
+// channel also receives a fresh shard for an already-settled AMP set.
+func testMPPReleasedSiblingRestart(ht *lntest.HarnessTest) {
+ const (
+ ampAmount = btcutil.Amount(1000)
+ mppAmount = btcutil.Amount(2000)
+ )
+
+ // Arrange one real channel and onion router. A long commit interval
+ // batches the ordinary shards with the closed-set shard. First pay an
+ // AMP set normally, retaining the parent's existing AMP semantics.
+ points, nodes := ht.CreateSimpleNetwork(
+ [][]string{
+ {
+ "--channel-commit-interval=5s",
+ },
+ nil,
+ },
+ lntest.OpenChannelParams{
+ Amt: 100_000,
+ },
+ )
+ alice, bob := nodes[0], nodes[1]
+ scenario := &mppTestScenario{
+ ht: ht,
+ }
+ ampInvoice := bob.RPC.AddInvoice(&lnrpc.Invoice{
+ Value: int64(ampAmount),
+ IsAmp: true,
+ })
+ setID := ht.Random32Bytes()
+ sharer, err := amp.NewSeedSharer()
+ require.NoError(ht, err)
+ child := sharer.Child(0)
+ ampRoute := scenario.buildRoute(
+ ampAmount, alice, []*node.HarnessNode{bob},
+ )
+ finalHop := ampRoute.Hops[len(ampRoute.Hops)-1]
+ finalHop.TlvPayload = true
+ finalHop.MppRecord = &lnrpc.MPPRecord{
+ PaymentAddr: ampInvoice.PaymentAddr,
+ TotalAmtMsat: int64(ampAmount * 1000),
+ }
+ finalHop.AmpRecord = &lnrpc.AMPRecord{
+ RootShare: child.Share[:],
+ SetId: setID,
+ ChildIndex: child.Index,
+ }
+ paidSet := alice.RPC.SendToRouteV2(&routerrpc.SendToRouteRequest{
+ PaymentHash: child.Hash[:],
+ Route: ampRoute,
+ })
+ require.Nil(ht, paidSet.Failure)
+ ht.AssertInvoiceSettled(bob, ampInvoice.PaymentAddr)
+ ht.AssertNumActiveHtlcs(alice, 0)
+ ht.AssertNumActiveHtlcs(bob, 0)
+
+ // Clear the payer's completed record so its local set-ID duplicate
+ // check does not stop the fresh onion before it reaches the receiver.
+ // Bob must still reject the set using his persisted invoice state.
+ alice.RPC.DeleteAllPayments()
+
+ // Holding the ordinary invoice lets us disconnect its payer before
+ // releasing the preimage, making the pending/restart window explicit
+ // instead of racing a fast settle acknowledgement.
+ preimage := lntypes.Preimage(ht.Random32Bytes())
+ hash := preimage.Hash()
+ invoice := bob.RPC.AddHoldInvoice(&invoicesrpc.AddHoldInvoiceRequest{
+ Hash: hash[:],
+ Value: int64(mppAmount),
+ })
+ invoiceStream := bob.RPC.SubscribeSingleInvoice(hash[:])
+ stream := alice.RPC.SendPayment(&routerrpc.SendPaymentRequest{
+ PaymentRequest: invoice.PaymentRequest,
+ MaxParts: 2,
+ MaxShardSizeMsat: uint64(mppAmount * 1000 / 2),
+ FeeLimitMsat: noFeeLimitMsat,
+ })
+ ht.AssertPaymentStatusFromStream(stream, lnrpc.Payment_IN_FLIGHT)
+
+ // Act by sending a distinct child to the closed set alongside the MPP
+ // shards. Its partial amount follows the previously failing updater
+ // path; it must return a normal invoice rejection without failing the
+ // channel that carries the ordinary payment.
+ lateChild := sharer.Child(1)
+ lateRoute := scenario.buildRoute(
+ ampAmount/2, alice, []*node.HarnessNode{bob},
+ )
+ lateHop := lateRoute.Hops[len(lateRoute.Hops)-1]
+ lateHop.TlvPayload = true
+ lateHop.MppRecord = &lnrpc.MPPRecord{
+ PaymentAddr: ampInvoice.PaymentAddr,
+ TotalAmtMsat: int64(ampAmount * 1000),
+ }
+ lateHop.AmpRecord = &lnrpc.AMPRecord{
+ RootShare: lateChild.Share[:],
+ SetId: setID,
+ ChildIndex: lateChild.Index,
+ }
+ rejected := alice.RPC.SendToRouteV2(&routerrpc.SendToRouteRequest{
+ PaymentHash: lateChild.Hash[:],
+ Route: lateRoute,
+ })
+ require.NotNil(ht, rejected.Failure)
+ require.Equal(ht, lnrpc.Failure_INCORRECT_OR_UNKNOWN_PAYMENT_DETAILS,
+ rejected.Failure.Code)
+ ht.AssertInvoiceState(invoiceStream, lnrpc.Invoice_ACCEPTED)
+
+ restartAlice := ht.SuspendNode(alice)
+ bob.RPC.SettleInvoice(preimage[:])
+ pending := ht.AssertInvoiceState(
+ invoiceStream, lnrpc.Invoice_PENDING_SETTLE,
+ )
+ require.Len(ht, pending.Htlcs, 2)
+ require.Zero(ht, pending.SettleIndex)
+ ht.RestartNode(bob)
+ stillPending := bob.RPC.LookupInvoice(hash[:])
+ require.Equal(ht, lnrpc.Invoice_PENDING_SETTLE, stillPending.State)
+
+ // Assert that reconnect uses the persistent replay log's processed path
+ // to recover both released children. Only the actual successful MPP and
+ // initial AMP set may contribute to final invoice/channel value.
+ require.NoError(ht, restartAlice())
+ ht.EnsureConnected(alice, bob)
+ ht.AssertPaymentStatus(alice, hash, lnrpc.Payment_SUCCEEDED)
+ ht.AssertInvoiceSettled(bob, pending.PaymentAddr)
+ settled := bob.RPC.LookupInvoice(hash[:])
+ require.EqualValues(ht, mppAmount, settled.AmtPaidSat)
+ require.NotZero(ht, settled.SettleIndex)
+ for _, htlc := range settled.Htlcs {
+ require.Equal(ht, lnrpc.InvoiceHTLCState_SETTLED, htlc.State)
+ }
+ ht.AssertNumActiveHtlcs(alice, 0)
+ ht.AssertNumActiveHtlcs(bob, 0)
+ totalPaid := int64(ampAmount + mppAmount)
+ ht.AssertAmountPaid("ordinary and AMP", alice, points[0], totalPaid, 0)
+ ht.AssertAmountPaid("ordinary and AMP", bob, points[0], 0, totalPaid)
+ ht.AssertChannelLocalBalance(bob, points[0], totalPaid)
+}
+
// mppTestScenario defines a test scenario used for testing MPP-related tests.
// It has two standby nodes, alice and bob, and three new nodes, carol, dave,
// and eve.
### itest/lnd_route_blinding_test.go
@@ -1078,6 +1078,7 @@ func testMPPToSingleBlindedPath(ht *lntest.HarnessTest) {
"expected shards not reached")
// Make sure Dave show the invoice as settled for the full amount.
+ ht.AssertInvoiceSettled(dave, invoiceResp.PaymentAddr)
inv := dave.RPC.LookupInvoice(invoiceResp.RHash)
require.EqualValues(ht, paymentAmt, inv.AmtPaidSat,
@@ -1212,8 +1213,7 @@ func testBlindedRouteDummyHops(ht *lntest.HarnessTest) {
)
// Make sure Dave show the invoice as settled.
- inv := dave.RPC.LookupInvoice(invoiceResp.RHash)
- require.Equal(ht, lnrpc.Invoice_SETTLED, inv.State)
+ ht.AssertInvoiceSettled(dave, invoiceResp.PaymentAddr)
// Let's also test the case where Dave is not the introduction node.
// We restart Carol so that she supports route blinding.
@@ -1254,8 +1254,7 @@ func testBlindedRouteDummyHops(ht *lntest.HarnessTest) {
)
// Make sure Dave show the invoice as settled.
- inv = dave.RPC.LookupInvoice(invoiceResp.RHash)
- require.Equal(ht, lnrpc.Invoice_SETTLED, inv.State)
+ ht.AssertInvoiceSettled(dave, invoiceResp.PaymentAddr)
}
// testMPPToMultipleBlindedPaths tests that a two-shard MPP payment can be sent
@@ -1394,6 +1393,7 @@ func testMPPToMultipleBlindedPaths(ht *lntest.HarnessTest) {
"expected shards not reached")
// Make sure Dave show the invoice as settled for the full amount.
+ ht.AssertInvoiceSettled(dave, invoiceResp.PaymentAddr)
inv := dave.RPC.LookupInvoice(invoiceResp.RHash)
require.EqualValues(ht, paymentAmt, inv.AmtPaidSat,
### itest/lnd_routing_test.go
@@ -792,8 +792,7 @@ func testScidAliasRoutingHints(ht *lntest.HarnessTest) {
// Check that Dave's invoice appears as settled.
invoices := dave.RPC.ListInvoices(&lnrpc.ListInvoiceRequest{})
require.Len(ht, invoices.Invoices, 1, "expected one invoice")
- require.Equal(ht, invoices.Invoices[0].State, lnrpc.Invoice_SETTLED,
- "expected settled invoice")
+ ht.AssertInvoiceSettled(dave, invoices.Invoices[0].PaymentAddr)
// We'll now delete the alias again, but only on Carol's end. That
// should be enough to make the payment fail, since she doesn't know
### itest/lnd_single_hop_invoice_test.go
@@ -48,9 +48,7 @@ func testSingleHopInvoice(ht *lntest.HarnessTest) {
ht.CompletePaymentRequests(alice, []string{invoiceResp.PaymentRequest})
// Bob's invoice should now be found and marked as settled.
- dbInvoice := bob.RPC.LookupInvoice(invoiceResp.RHash)
- require.Equal(ht, lnrpc.Invoice_SETTLED, dbInvoice.State,
- "bob's invoice should be marked as settled")
+ ht.AssertInvoiceSettled(bob, invoiceResp.PaymentAddr)
// With the payment completed all balance related stats should be
// properly updated.
### itest/lnd_sweep_test.go
@@ -1909,9 +1909,10 @@ func testFeeReplacement(ht *lntest.HarnessTest) {
// Suspend Bob so he won't get the preimage from Carol.
restartBob := ht.SuspendNode(bob)
- // Carol settles the first invoice.
+ // Carol settles the first invoice. Since Bob is offline, the settle
+ // can't be locked in, so the invoice is pending settlement.
carol.RPC.SettleInvoice(preimages[0])
- ht.AssertInvoiceState(streams[0], lnrpc.Invoice_SETTLED)
+ ht.AssertInvoiceState(streams[0], lnrpc.Invoice_PENDING_SETTLE)
// Carol goes offline so the preimage won't be sent to Bob.
restartCarol := ht.SuspendNode(carol)
### lnrpc/invoicesrpc/addinvoice_test.go
@@ -4,13 +4,16 @@ import (
"encoding/hex"
"fmt"
"testing"
+ "time"
"github.com/btcsuite/btcd/btcec/v2"
"github.com/btcsuite/btcd/chainhash/v2"
"github.com/btcsuite/btcd/wire/v2"
"github.com/lightningnetwork/lnd/chanstate"
"github.com/lightningnetwork/lnd/graph/db/models"
"github.com/lightningnetwork/lnd/invoices"
+ "github.com/lightningnetwork/lnd/lnrpc"
+ "github.com/lightningnetwork/lnd/lntypes"
"github.com/lightningnetwork/lnd/lnwire"
"github.com/lightningnetwork/lnd/routing/route"
"github.com/lightningnetwork/lnd/zpay32"
@@ -28,6 +31,149 @@ var (
pubkey = btcec.NewPublicKey(new(btcec.FieldVal).SetInt(4), pubKeyY)
)
+// TestCreateRPCInvoiceFinalHtlcOutcomes verifies that RPC callers see pending
+// releases without final timestamps and can distinguish released collection
+// failures from cancellations that did not release the invoice preimage.
+func TestCreateRPCInvoiceFinalHtlcOutcomes(t *testing.T) {
+ t.Parallel()
+
+ // Arrange snapshots with known preimages so release history must come
+ // from payment outcomes rather than secret availability. Stored times
+ // also distinguish final outcomes from provisional pending timestamps.
+ const amount = lnwire.MilliSatoshi(1000)
+ resolvedAt := time.Unix(10, 0)
+ preimage := lntypes.Preimage{1}
+ testCases := []struct {
+ name string
+ state invoices.ContractState
+ htlcStates []invoices.HtlcState
+ rpcState lnrpc.Invoice_InvoiceState
+ rpcHtlcState []lnrpc.InvoiceHTLCState
+ amtPaid lnwire.MilliSatoshi
+ resolveTime int64
+ released bool
+ }{
+ {
+ name: "pending outcomes",
+ state: invoices.ContractPendingSettle,
+ htlcStates: []invoices.HtlcState{
+ invoices.HtlcStatePendingSettle,
+ invoices.HtlcStatePendingSettle,
+ },
+ rpcState: lnrpc.Invoice_PENDING_SETTLE,
+ rpcHtlcState: []lnrpc.InvoiceHTLCState{
+ lnrpc.InvoiceHTLCState_PENDING_SETTLE,
+ lnrpc.InvoiceHTLCState_PENDING_SETTLE,
+ },
+ amtPaid: amount,
+ resolveTime: 0,
+ released: true,
+ },
+ {
+ name: "mixed final outcomes",
+ state: invoices.ContractCanceled,
+ htlcStates: []invoices.HtlcState{
+ invoices.HtlcStateSettled,
+ invoices.HtlcStateFailed,
+ },
+ rpcState: lnrpc.Invoice_CANCELED,
+ rpcHtlcState: []lnrpc.InvoiceHTLCState{
+ lnrpc.InvoiceHTLCState_SETTLED,
+ lnrpc.InvoiceHTLCState_FAILED,
+ },
+ amtPaid: amount / 2,
+ resolveTime: resolvedAt.Unix(),
+ released: true,
+ },
+ {
+ name: "canceled before release",
+ state: invoices.ContractCanceled,
+ htlcStates: []invoices.HtlcState{
+ invoices.HtlcStateCanceled,
+ },
+ rpcState: lnrpc.Invoice_CANCELED,
+ rpcHtlcState: []lnrpc.InvoiceHTLCState{
+ lnrpc.InvoiceHTLCState_CANCELED,
+ },
+ resolveTime: resolvedAt.Unix(),
+ },
+ {
+ name: "all released HTLCs failed",
+ state: invoices.ContractCanceled,
+ htlcStates: []invoices.HtlcState{
+ invoices.HtlcStateFailed,
+ },
+ rpcState: lnrpc.Invoice_CANCELED,
+ rpcHtlcState: []lnrpc.InvoiceHTLCState{
+ lnrpc.InvoiceHTLCState_FAILED,
+ },
+ resolveTime: resolvedAt.Unix(),
+ released: true,
+ },
+ {
+ name: "legacy settled without HTLCs",
+ state: invoices.ContractSettled,
+ rpcState: lnrpc.Invoice_SETTLED,
+ amtPaid: amount,
+ released: true,
+ },
+ }
+
+ for _, tc := range testCases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ // Arrange invoice fields without request parsing.
+ // Circuit IDs distinguish children in the ordered
+ // RPC response without involving a backend.
+ invoice := &invoices.Invoice{
+ State: tc.state,
+ AmtPaid: tc.amtPaid,
+ Terms: invoices.ContractTerm{
+ Value: amount,
+ PaymentPreimage: &preimage,
+ },
+ }
+ invoice.Htlcs = make(
+ map[models.CircuitKey]*invoices.InvoiceHTLC,
+ )
+ for n, state := range tc.htlcStates {
+ key := models.CircuitKey{
+ HtlcID: uint64(n),
+ }
+ invoice.Htlcs[key] = &invoices.InvoiceHTLC{
+ State: state,
+ Amt: amount / 2,
+ ResolveTime: resolvedAt,
+ }
+ }
+
+ // Act through the mapper used by invoice responses
+ // and subscriptions, without involving storage.
+ rpcInvoice, err := CreateRPCInvoice(invoice, nil)
+
+ // Assert states, release history and credit at the RPC
+ // boundary. Pending children hide provisional times;
+ // final children expose their actual resolution time.
+ require.NoError(t, err)
+ require.Equal(t, tc.rpcState, rpcInvoice.State)
+ require.Equal(
+ t, tc.released, rpcInvoice.PreimageReleased,
+ )
+ require.EqualValues(
+ t, tc.amtPaid, rpcInvoice.AmtPaidMsat,
+ )
+ require.Len(t, rpcInvoice.Htlcs, len(tc.rpcHtlcState))
+ for n, htlc := range rpcInvoice.Htlcs {
+ require.Equal(t, tc.rpcHtlcState[n], htlc.State)
+ require.Equal(
+ t, tc.resolveTime, htlc.ResolveTime,
+ )
+ }
+ })
+ }
+}
+
// TestAddInvoiceRejectsCltvAboveMaxIncoming asserts that invoice creation
// rejects final CLTV deltas above the supported maximum.
func TestAddInvoiceRejectsCltvAboveMaxIncoming(t *testing.T) {
### lnrpc/invoicesrpc/invoices.swagger.json
@@ -268,9 +268,11 @@
"OPEN",
"SETTLED",
"CANCELED",
- "ACCEPTED"
+ "ACCEPTED",
+ "PENDING_SETTLE"
],
- "default": "OPEN"
+ "default": "OPEN",
+ "description": " - SETTLED: An ordinary invoice collected every released payment HTLC. A later\nduplicate HTLC can still be pending or fail while the parent stays\nSETTLED. Check the relevant finalized successful HTLC amounts before\ncrediting. AMP retains its existing set-level settlement semantics;\nthis state does not add an AMP-finality guarantee.\n - CANCELED: The invoice was canceled, possibly after releasing its preimage if\ncollection failed. For ordinary invoices, check preimage_released;\nCANCELED alone does not mean the secret was never released. The amount\nactually collected is retained; cancellation does not refund successful\nHTLCs.\n - PENDING_SETTLE: An ordinary invoice released its preimage, but at least one HTLC still\nawaits its final outcome. The payer may reclaim a pending HTLC on\nchain, so its value must not yet be credited. Once every outcome is\nknown the invoice becomes SETTLED only if every released payment HTLC\nsucceeded. Otherwise it becomes CANCELED and retains the amount\ncollected from successful HTLCs. AMP invoices do not enter this state."
},
"invoicesrpcAddHoldInvoiceRequest": {
"type": "object",
@@ -684,12 +686,12 @@
"amt_paid_sat": {
"type": "string",
"format": "int64",
- "description": "The amount that was accepted for this invoice, in satoshis. This will ONLY\nbe set if this invoice has been settled or accepted. We provide this field\nas if the invoice was created with a zero value, then we need to record what\namount was ultimately accepted. Additionally, it's possible that the sender\npaid MORE that was specified in the original invoice. So we'll record that\nhere as well.\nNote: Output only, don't specify for creating an invoice."
+ "description": "The amount accepted for this invoice, in satoshis. It can differ from the\nrequested amount, including for zero-value invoices and overpayments.\nFor ordinary invoices this aggregate can include accepted or PENDING_SETTLE\nHTLCs. Even a SETTLED parent can contain a later pending duplicate HTLC.\nCredit only the successful value of the relevant SETTLED HTLCs, rather than\nthe requested amount or this aggregate alone. AMP retains its existing\nrelease-time accounting semantics.\nNote: Output only, don't specify for creating an invoice."
},
"amt_paid_msat": {
"type": "string",
"format": "int64",
- "description": "The amount that was accepted for this invoice, in millisatoshis. This will\nONLY be set if this invoice has been settled or accepted. We provide this\nfield as if the invoice was created with a zero value, then we need to\nrecord what amount was ultimately accepted. Additionally, it's possible that\nthe sender paid MORE that was specified in the original invoice. So we'll\nrecord that here as well.\nNote: Output only, don't specify for creating an invoice."
+ "description": "The amount accepted for this invoice, in millisatoshis. It has the same\npending-value and retained-funds semantics as amt_paid_sat. For ordinary\ninvoices, use the amounts and states of the relevant finalized successful\nHTLCs before crediting, including when the parent already reports SETTLED.\nNote: Output only, don't specify for creating an invoice."
},
"state": {
"$ref": "#/definitions/InvoiceInvoiceState",
@@ -738,6 +740,10 @@
"blinded_path_config": {
"$ref": "#/definitions/lnrpcBlindedPathConfig",
"description": "Config values to use when creating blinded paths for this invoice. These\ncan be used to override the defaults config values provided in by the\nglobal config. This field is only used if is_blinded is true."
+ },
+ "preimage_released": {
+ "type": "boolean",
+ "description": "Whether lnd committed to releasing the preimage for this ordinary invoice,\nincluding when collection later failed. This is derived from the invoice\nand HTLC states, not from whether lnd knows the preimage. It does not prove\nthe payer received the preimage, and false does not guarantee the secret\nis unknown elsewhere. Clients must not infer preimage privacy from\nCANCELED alone when refunding a counterpart payment or reusing a hash.\nThis field is not supported for AMP invoices and is false for them.\nNote: Output only, don't specify for creating an invoice."
}
}
},
@@ -813,9 +819,12 @@
"enum": [
"ACCEPTED",
"SETTLED",
- "CANCELED"
+ "CANCELED",
+ "PENDING_SETTLE",
+ "FAILED"
],
- "default": "ACCEPTED"
+ "default": "ACCEPTED",
+ "description": " - SETTLED: An ordinary HTLC settled irrevocably. AMP retains its existing\npreimage-release settlement semantics.\n - PENDING_SETTLE: An ordinary HTLC released its preimage but its outcome is not final yet.\nIt becomes SETTLED on final success or FAILED if the payer reclaims it.\n - FAILED: An ordinary HTLC whose preimage was released but was not collected. This\ndiffers from CANCELED, which failed before preimage release."
},
"lnrpcRouteHint": {
"type": "object",
### lnrpc/invoicesrpc/utils.go
@@ -80,6 +80,12 @@ func CreateRPCInvoice(invoice *invoices.Invoice,
satAmtPaid := invoice.AmtPaid.ToSatoshis()
isSettled := invoice.State == invoices.ContractSettled
+ isAMP := invoice.IsAMP()
+
+ // State records the release decision, unlike a known preimage, which
+ // ordinary invoices can have before payment. Preserve legacy settled
+ // headers even when their original HTLC records are unavailable.
+ preimageReleased := !isAMP && invoice.State.PreimageReleased()
var state lnrpc.Invoice_InvoiceState
switch invoice.State {
@@ -95,6 +101,9 @@ func CreateRPCInvoice(invoice *invoices.Invoice,
case invoices.ContractAccepted:
state = lnrpc.Invoice_ACCEPTED
+ case invoices.ContractPendingSettle:
+ state = lnrpc.Invoice_PENDING_SETTLE
+
default:
return nil, fmt.Errorf("unknown invoice state %v",
invoice.State)
@@ -110,10 +119,23 @@ func CreateRPCInvoice(invoice *invoices.Invoice,
state = lnrpc.InvoiceHTLCState_SETTLED
case invoices.HtlcStateCanceled:
state = lnrpc.InvoiceHTLCState_CANCELED
+ case invoices.HtlcStateFailed:
+ state = lnrpc.InvoiceHTLCState_FAILED
+ case invoices.HtlcStatePendingSettle:
+ state = lnrpc.InvoiceHTLCState_PENDING_SETTLE
default:
return nil, fmt.Errorf("unknown state %v", htlc.State)
}
+ // A canceled parent can still carry release history after every
+ // released child failed. Keep this separate from the predicate
+ // used for active claims and paid-value accounting.
+ if !isAMP && (htlc.State.PreimageReleased() ||
+ htlc.State == invoices.HtlcStateFailed) {
+
+ preimageReleased = true
+ }
+
rpcHtlc := lnrpc.InvoiceHTLC{
ChanId: key.ChanID.ToUint64(),
HtlcIndex: key.HtlcID,
@@ -155,8 +177,13 @@ func CreateRPCInvoice(invoice *invoices.Invoice,
}
}
- // Only report resolved times if htlc is resolved.
- if htlc.State != invoices.HtlcStateAccepted {
+ // Preimage release records a timestamp internally, but a
+ // pending HTLC has no final resolution time to expose to RPC
+ // callers.
+ if htlc.State == invoices.HtlcStateSettled ||
+ htlc.State == invoices.HtlcStateCanceled ||
+ htlc.State == invoices.HtlcStateFailed {
+
rpcHtlc.ResolveTime = htlc.ResolveTime.Unix()
}
@@ -195,9 +222,10 @@ func CreateRPCInvoice(invoice *invoices.Invoice,
Features: CreateRPCFeatures(invoice.Terms.Features),
IsKeysend: invoice.IsKeysend(),
PaymentAddr: invoice.Terms.PaymentAddr[:],
- IsAmp: invoice.IsAMP(),
+ IsAmp: isAMP,
IsBlinded: invoice.IsBlinded(),
}
+ rpcInvoice.PreimageReleased = preimageReleased
rpcInvoice.AmpInvoiceState = make(map[string]*lnrpc.AMPInvoiceState)
for setID, ampState := range invoice.AMPState {
### lnrpc/lightning.pb.go
@@ -606,8 +606,19 @@ type InvoiceHTLCState int32
const (
InvoiceHTLCState_ACCEPTED InvoiceHTLCState = 0
+ //
+ //An ordinary HTLC settled irrevocably. AMP retains its existing
+ //preimage-release settlement semantics.
InvoiceHTLCState_SETTLED InvoiceHTLCState = 1
InvoiceHTLCState_CANCELED InvoiceHTLCState = 2
+ //
+ //An ordinary HTLC released its preimage but its outcome is not final yet.
+ //It becomes SETTLED on final success or FAILED if the payer reclaims it.
+ InvoiceHTLCState_PENDING_SETTLE InvoiceHTLCState = 3
+ //
+ //An ordinary HTLC whose preimage was released but was not collected. This
+ //differs from CANCELED, which failed before preimage release.
+ InvoiceHTLCState_FAILED InvoiceHTLCState = 4
)
// Enum value maps for InvoiceHTLCState.
@@ -616,11 +627,15 @@ var (
0: "ACCEPTED",
1: "SETTLED",
2: "CANCELED",
+ 3: "PENDING_SETTLE",
+ 4: "FAILED",
}
InvoiceHTLCState_value = map[string]int32{
- "ACCEPTED": 0,
- "SETTLED": 1,
- "CANCELED": 2,
+ "ACCEPTED": 0,
+ "SETTLED": 1,
+ "CANCELED": 2,
+ "PENDING_SETTLE": 3,
+ "FAILED": 4,
}
)
@@ -1190,10 +1205,30 @@ func (ChannelEventUpdate_UpdateType) EnumDescriptor() ([]byte, []int) {
type Invoice_InvoiceState int32
const (
- Invoice_OPEN Invoice_InvoiceState = 0
- Invoice_SETTLED Invoice_InvoiceState = 1
+ Invoice_OPEN Invoice_InvoiceState = 0
+ //
+ //An ordinary invoice collected every released payment HTLC. A later
+ //duplicate HTLC can still be pending or fail while the parent stays
+ //SETTLED. Check the relevant finalized successful HTLC amounts before
+ //crediting. AMP retains its existing set-level settlement semantics;
+ //this state does not add an AMP-finality guarantee.
+ Invoice_SETTLED Invoice_InvoiceState = 1
+ //
+ //The invoice was canceled, possibly after releasing its preimage if
+ //collection failed. For ordinary invoices, check preimage_released;
+ //CANCELED alone does not mean the secret was never released. The amount
+ //actually collected is retained; cancellation does not refund successful
+ //HTLCs.
Invoice_CANCELED Invoice_InvoiceState = 2
Invoice_ACCEPTED Invoice_InvoiceState = 3
+ //
+ //An ordinary invoice released its preimage, but at least one HTLC still
+ //awaits its final outcome. The payer may reclaim a pending HTLC on
+ //chain, so its value must not yet be credited. Once every outcome is
+ //known the invoice becomes SETTLED only if every released payment HTLC
+ //succeeded. Otherwise it becomes CANCELED and retains the amount
+ //collected from successful HTLCs. AMP invoices do not enter this state.
+ Invoice_PENDING_SETTLE Invoice_InvoiceState = 4
)
// Enum value maps for Invoice_InvoiceState.
@@ -1203,12 +1238,14 @@ var (
1: "SETTLED",
2: "CANCELED",
3: "ACCEPTED",
+ 4: "PENDING_SETTLE",
}
Invoice_InvoiceState_value = map[string]int32{
- "OPEN": 0,
- "SETTLED": 1,
- "CANCELED": 2,
- "ACCEPTED": 3,
+ "OPEN": 0,
+ "SETTLED": 1,
+ "CANCELED": 2,
+ "ACCEPTED": 3,
+ "PENDING_SETTLE": 4,
}
)
@@ -12898,21 +12935,20 @@ type Invoice struct {
// Deprecated: Marked as deprecated in lightning.proto.
AmtPaid int64 `protobuf:"varint,18,opt,name=amt_paid,json=amtPaid,proto3" json:"amt_paid,omitempty"`
//
- //The amount that was accepted for this invoice, in satoshis. This will ONLY
- //be set if this invoice has been settled or accepted. We provide this field
- //as if the invoice was created with a zero value, then we need to record what
- //amount was ultimately accepted. Additionally, it's possible that the sender
- //paid MORE that was specified in the original invoice. So we'll record that
- //here as well.
+ //The amount accepted for this invoice, in satoshis. It can differ from the
+ //requested amount, including for zero-value invoices and overpayments.
+ //For ordinary invoices this aggregate can include accepted or PENDING_SETTLE
+ //HTLCs. Even a SETTLED parent can contain a later pending duplicate HTLC.
+ //Credit only the successful value of the relevant SETTLED HTLCs, rather than
+ //the requested amount or this aggregate alone. AMP retains its existing
+ //release-time accounting semantics.
//Note: Output only, don't specify for creating an invoice.
AmtPaidSat int64 `protobuf:"varint,19,opt,name=amt_paid_sat,json=amtPaidSat,proto3" json:"amt_paid_sat,omitempty"`
//
- //The amount that was accepted for this invoice, in millisatoshis. This will
- //ONLY be set if this invoice has been settled or accepted. We provide this
- //field as if the invoice was created with a zero value, then we need to
- //record what amount was ultimately accepted. Additionally, it's possible that
- //the sender paid MORE that was specified in the original invoice. So we'll
- //record that here as well.
+ //The amount accepted for this invoice, in millisatoshis. It has the same
+ //pending-value and retained-funds semantics as amt_paid_sat. For ordinary
+ //invoices, use the amounts and states of the relevant finalized successful
+ //HTLCs before crediting, including when the parent already reports SETTLED.
//Note: Output only, don't specify for creating an invoice.
AmtPaidMsat int64 `protobuf:"varint,20,opt,name=amt_paid_msat,json=amtPaidMsat,proto3" json:"amt_paid_msat,omitempty"`
//
@@ -12960,8 +12996,18 @@ type Invoice struct {
//can be used to override the defaults config values provided in by the
//global config. This field is only used if is_blinded is true.
BlindedPathConfig *BlindedPathConfig `protobuf:"bytes,30,opt,name=blinded_path_config,json=blindedPathConfig,proto3" json:"blinded_path_config,omitempty"`
- unknownFields protoimpl.UnknownFields
- sizeCache protoimpl.SizeCache
+ //
+ //Whether lnd committed to releasing the preimage for this ordinary invoice,
+ //including when collection later failed. This is derived from the invoice
+ //and HTLC states, not from whether lnd knows the preimage. It does not prove
+ //the payer received the preimage, and false does not guarantee the secret
+ //is unknown elsewhere. Clients must not infer preimage privacy from
+ //CANCELED alone when refunding a counterpart payment or reusing a hash.
+ //This field is not supported for AMP invoices and is false for them.
+ //Note: Output only, don't specify for creating an invoice.
+ PreimageReleased bool `protobuf:"varint,31,opt,name=preimage_released,json=preimageReleased,proto3" json:"preimage_released,omitempty"`
+ unknownFields protoimpl.UnknownFields
+ sizeCache protoimpl.SizeCache
}
func (x *Invoice) Reset() {
@@ -13199,6 +13245,13 @@ func (x *Invoice) GetBlindedPathConfig() *BlindedPathConfig {
return nil
}
+func (x *Invoice) GetPreimageReleased() bool {
+ if x != nil {
+ return x.PreimageReleased
+ }
+ return false
+}
+
type BlindedPathConfig struct {
state protoimpl.MessageState `protogen:"open.v1"`
//
@@ -19908,7 +19961,7 @@ const file_lightning_proto_rawDesc = "" +
"\fsettle_index\x18\x02 \x01(\x04R\vsettleIndex\x12\x1f\n" +
"\vsettle_time\x18\x03 \x01(\x03R\n" +
"settleTime\x12\"\n" +
- "\ramt_paid_msat\x18\x05 \x01(\x03R\vamtPaidMsat\"\xac\n" +
+ "\ramt_paid_msat\x18\x05 \x01(\x03R\vamtPaidMsat\"\xed\n" +
"\n" +
"\aInvoice\x12\x12\n" +
"\x04memo\x18\x01 \x01(\tR\x04memo\x12\x1d\n" +
@@ -19948,18 +20001,20 @@ const file_lightning_proto_rawDesc = "" +
"\x11amp_invoice_state\x18\x1c \x03(\v2#.lnrpc.Invoice.AmpInvoiceStateEntryR\x0fampInvoiceState\x12\x1d\n" +
"\n" +
"is_blinded\x18\x1d \x01(\bR\tisBlinded\x12H\n" +
- "\x13blinded_path_config\x18\x1e \x01(\v2\x18.lnrpc.BlindedPathConfigR\x11blindedPathConfig\x1aK\n" +
+ "\x13blinded_path_config\x18\x1e \x01(\v2\x18.lnrpc.BlindedPathConfigR\x11blindedPathConfig\x12+\n" +
+ "\x11preimage_released\x18\x1f \x01(\bR\x10preimageReleased\x1aK\n" +
"\rFeaturesEntry\x12\x10\n" +
"\x03key\x18\x01 \x01(\rR\x03key\x12$\n" +
"\x05value\x18\x02 \x01(\v2\x0e.lnrpc.FeatureR\x05value:\x028\x01\x1aZ\n" +
"\x14AmpInvoiceStateEntry\x12\x10\n" +
"\x03key\x18\x01 \x01(\tR\x03key\x12,\n" +
- "\x05value\x18\x02 \x01(\v2\x16.lnrpc.AMPInvoiceStateR\x05value:\x028\x01\"A\n" +
+ "\x05value\x18\x02 \x01(\v2\x16.lnrpc.AMPInvoiceStateR\x05value:\x028\x01\"U\n" +
"\fInvoiceState\x12\b\n" +
"\x04OPEN\x10\x00\x12\v\n" +
"\aSETTLED\x10\x01\x12\f\n" +
"\bCANCELED\x10\x02\x12\f\n" +
- "\bACCEPTED\x10\x03J\x04\b\x02\x10\x03\"\xa3\x02\n" +
+ "\bACCEPTED\x10\x03\x12\x12\n" +
+ "\x0ePENDING_SETTLE\x10\x04J\x04\b\x02\x10\x03\"\xa3\x02\n" +
"\x11BlindedPathConfig\x12.\n" +
"\x11min_num_real_hops\x18\x01 \x01(\rH\x00R\x0eminNumRealHops\x88\x01\x01\x12\x1e\n" +
"\bnum_hops\x18\x02 \x01(\rH\x01R\anumHops\x88\x01\x01\x12'\n" +
@@ -20440,11 +20495,14 @@ const file_lightning_proto_rawDesc = "" +
"\x19GRAPH_CACHE_STATUS_FAILED\x10\x03*9\n" +
"\x0eNodeMetricType\x12\v\n" +
"\aUNKNOWN\x10\x00\x12\x1a\n" +
- "\x16BETWEENNESS_CENTRALITY\x10\x01*;\n" +
+ "\x16BETWEENNESS_CENTRALITY\x10\x01*[\n" +
"\x10InvoiceHTLCState\x12\f\n" +
"\bACCEPTED\x10\x00\x12\v\n" +
"\aSETTLED\x10\x01\x12\f\n" +
- "\bCANCELED\x10\x02*\xf6\x01\n" +
+ "\bCANCELED\x10\x02\x12\x12\n" +
+ "\x0ePENDING_SETTLE\x10\x03\x12\n" +
+ "\n" +
+ "\x06FAILED\x10\x04*\xf6\x01\n" +
"\x14PaymentFailureReason\x12\x17\n" +
"\x13FAILURE_REASON_NONE\x10\x00\x12\x1a\n" +
"\x16FAILURE_REASON_TIMEOUT\x10\x01\x12\x1b\n" +
### lnrpc/lightning.proto
@@ -302,7 +302,9 @@ service Lightning {
/* lncli: `deletecanceledinvoice`
DeleteCanceledInvoice removes a canceled invoice from the database. If the
- invoice is not in the canceled state, an error will be returned.
+ invoice is not in the canceled state, an error will be returned. Ordinary
+ invoices whose preimage was released cannot be deleted, even if no funds
+ were collected, so their release history is retained.
*/
rpc DeleteCanceledInvoice (DelCanceledInvoiceReq)
returns (DelCanceledInvoiceResp);
@@ -3977,32 +3979,57 @@ message Invoice {
int64 amt_paid = 18 [deprecated = true];
/*
- The amount that was accepted for this invoice, in satoshis. This will ONLY
- be set if this invoice has been settled or accepted. We provide this field
- as if the invoice was created with a zero value, then we need to record what
- amount was ultimately accepted. Additionally, it's possible that the sender
- paid MORE that was specified in the original invoice. So we'll record that
- here as well.
+ The amount accepted for this invoice, in satoshis. It can differ from the
+ requested amount, including for zero-value invoices and overpayments.
+ For ordinary invoices this aggregate can include accepted or PENDING_SETTLE
+ HTLCs. Even a SETTLED parent can contain a later pending duplicate HTLC.
+ Credit only the successful value of the relevant SETTLED HTLCs, rather than
+ the requested amount or this aggregate alone. AMP retains its existing
+ release-time accounting semantics.
Note: Output only, don't specify for creating an invoice.
*/
int64 amt_paid_sat = 19;
/*
- The amount that was accepted for this invoice, in millisatoshis. This will
- ONLY be set if this invoice has been settled or accepted. We provide this
- field as if the invoice was created with a zero value, then we need to
- record what amount was ultimately accepted. Additionally, it's possible that
- the sender paid MORE that was specified in the original invoice. So we'll
- record that here as well.
+ The amount accepted for this invoice, in millisatoshis. It has the same
+ pending-value and retained-funds semantics as amt_paid_sat. For ordinary
+ invoices, use the amounts and states of the relevant finalized successful
+ HTLCs before crediting, including when the parent already reports SETTLED.
Note: Output only, don't specify for creating an invoice.
*/
int64 amt_paid_msat = 20;
enum InvoiceState {
OPEN = 0;
+
+ /*
+ An ordinary invoice collected every released payment HTLC. A later
+ duplicate HTLC can still be pending or fail while the parent stays
+ SETTLED. Check the relevant finalized successful HTLC amounts before
+ crediting. AMP retains its existing set-level settlement semantics;
+ this state does not add an AMP-finality guarantee.
+ */
SETTLED = 1;
+
+ /*
+ The invoice was canceled, possibly after releasing its preimage if
+ collection failed. For ordinary invoices, check preimage_released;
+ CANCELED alone does not mean the secret was never released. The amount
+ actually collected is retained; cancellation does not refund successful
+ HTLCs.
+ */
CANCELED = 2;
ACCEPTED = 3;
+
+ /*
+ An ordinary invoice released its preimage, but at least one HTLC still
+ awaits its final outcome. The payer may reclaim a pending HTLC on
+ chain, so its value must not yet be credited. Once every outcome is
+ known the invoice becomes SETTLED only if every released payment HTLC
+ succeeded. Otherwise it becomes CANCELED and retains the amount
+ collected from successful HTLCs. AMP invoices do not enter this state.
+ */
+ PENDING_SETTLE = 4;
}
/*
@@ -4067,6 +4094,18 @@ message Invoice {
global config. This field is only used if is_blinded is true.
*/
BlindedPathConfig blinded_path_config = 30;
+
+ /*
+ Whether lnd committed to releasing the preimage for this ordinary invoice,
+ including when collection later failed. This is derived from the invoice
+ and HTLC states, not from whether lnd knows the preimage. It does not prove
+ the payer received the preimage, and false does not guarantee the secret
+ is unknown elsewhere. Clients must not infer preimage privacy from
+ CANCELED alone when refunding a counterpart payment or reusing a hash.
+ This field is not supported for AMP invoices and is false for them.
+ Note: Output only, don't specify for creating an invoice.
+ */
+ bool preimage_released = 31;
}
message BlindedPathConfig {
@@ -4106,8 +4145,26 @@ message BlindedPathConfig {
enum InvoiceHTLCState {
ACCEPTED = 0;
+
+ /*
+ An ordinary HTLC settled irrevocably. AMP retains its existing
+ preimage-release settlement semantics.
+ */
SETTLED = 1;
+
CANCELED = 2;
+
+ /*
+ An ordinary HTLC released its preimage but its outcome is not final yet.
+ It becomes SETTLED on final success or FAILED if the payer reclaims it.
+ */
+ PENDING_SETTLE = 3;
+
+ /*
+ An ordinary HTLC whose preimage was released but was not collected. This
+ differs from CANCELED, which failed before preimage release.
+ */
+ FAILED = 4;
}
// Details of an HTLC that paid to an invoice
### lnrpc/lightning.swagger.json
@@ -1762,7 +1762,7 @@
]
},
"delete": {
- "summary": "lncli: `deletecanceledinvoice`\nDeleteCanceledInvoice removes a canceled invoice from the database. If the\ninvoice is not in the canceled state, an error will be returned.",
+ "summary": "lncli: `deletecanceledinvoice`\nDeleteCanceledInvoice removes a canceled invoice from the database. If the\ninvoice is not in the canceled state, an error will be returned. Ordinary\ninvoices whose preimage was released cannot be deleted, even if no funds\nwere collected, so their release history is retained.",
"operationId": "Lightning_DeleteCanceledInvoice",
"responses": {
"200": {
@@ -3099,9 +3099,11 @@
"OPEN",
"SETTLED",
"CANCELED",
- "ACCEPTED"
+ "ACCEPTED",
+ "PENDING_SETTLE"
],
- "default": "OPEN"
+ "default": "OPEN",
+ "description": " - SETTLED: An ordinary invoice collected every released payment HTLC. A later\nduplicate HTLC can still be pending or fail while the parent stays\nSETTLED. Check the relevant finalized successful HTLC amounts before\ncrediting. AMP retains its existing set-level settlement semantics;\nthis state does not add an AMP-finality guarantee.\n - CANCELED: The invoice was canceled, possibly after releasing its preimage if\ncollection failed. For ordinary invoices, check preimage_released;\nCANCELED alone does not mean the secret was never released. The amount\nactually collected is retained; cancellation does not refund successful\nHTLCs.\n - PENDING_SETTLE: An ordinary invoice released its preimage, but at least one HTLC still\nawaits its final outcome. The payer may reclaim a pending HTLC on\nchain, so its value must not yet be credited. Once every outcome is\nknown the invoice becomes SETTLED only if every released payment HTLC\nsucceeded. Otherwise it becomes CANCELED and retains the amount\ncollected from successful HTLCs. AMP invoices do not enter this state."
},
"PaymentPaymentStatus": {
"type": "string",
@@ -5885,12 +5887,12 @@
"amt_paid_sat": {
"type": "string",
"format": "int64",
- "description": "The amount that was accepted for this invoice, in satoshis. This will ONLY\nbe set if this invoice has been settled or accepted. We provide this field\nas if the invoice was created with a zero value, then we need to record what\namount was ultimately accepted. Additionally, it's possible that the sender\npaid MORE that was specified in the original invoice. So we'll record that\nhere as well.\nNote: Output only, don't specify for creating an invoice."
+ "description": "The amount accepted for this invoice, in satoshis. It can differ from the\nrequested amount, including for zero-value invoices and overpayments.\nFor ordinary invoices this aggregate can include accepted or PENDING_SETTLE\nHTLCs. Even a SETTLED parent can contain a later pending duplicate HTLC.\nCredit only the successful value of the relevant SETTLED HTLCs, rather than\nthe requested amount or this aggregate alone. AMP retains its existing\nrelease-time accounting semantics.\nNote: Output only, don't specify for creating an invoice."
},
"amt_paid_msat": {
"type": "string",
"format": "int64",
- "description": "The amount that was accepted for this invoice, in millisatoshis. This will\nONLY be set if this invoice has been settled or accepted. We provide this\nfield as if the invoice was created with a zero value, then we need to\nrecord what amount was ultimately accepted. Additionally, it's possible that\nthe sender paid MORE that was specified in the original invoice. So we'll\nrecord that here as well.\nNote: Output only, don't specify for creating an invoice."
+ "description": "The amount accepted for this invoice, in millisatoshis. It has the same\npending-value and retained-funds semantics as amt_paid_sat. For ordinary\ninvoices, use the amounts and states of the relevant finalized successful\nHTLCs before crediting, including when the parent already reports SETTLED.\nNote: Output only, don't specify for creating an invoice."
},
"state": {
"$ref": "#/definitions/InvoiceInvoiceState",
@@ -5939,6 +5941,10 @@
"blinded_path_config": {
"$ref": "#/definitions/lnrpcBlindedPathConfig",
"description": "Config values to use when creating blinded paths for this invoice. These\ncan be used to override the defaults config values provided in by the\nglobal config. This field is only used if is_blinded is true."
+ },
+ "preimage_released": {
+ "type": "boolean",
+ "description": "Whether lnd committed to releasing the preimage for this ordinary invoice,\nincluding when collection later failed. This is derived from the invoice\nand HTLC states, not from whether lnd knows the preimage. It does not prove\nthe payer received the preimage, and false does not guarantee the secret\nis unknown elsewhere. Clients must not infer preimage privacy from\nCANCELED alone when refunding a counterpart payment or reusing a hash.\nThis field is not supported for AMP invoices and is false for them.\nNote: Output only, don't specify for creating an invoice."
}
}
},
@@ -6014,9 +6020,12 @@
"enum": [
"ACCEPTED",
"SETTLED",
- "CANCELED"
+ "CANCELED",
+ "PENDING_SETTLE",
+ "FAILED"
],
- "default": "ACCEPTED"
+ "default": "ACCEPTED",
+ "description": " - SETTLED: An ordinary HTLC settled irrevocably. AMP retains its existing\npreimage-release settlement semantics.\n - PENDING_SETTLE: An ordinary HTLC released its preimage but its outcome is not final yet.\nIt becomes SETTLED on final success or FAILED if the payer reclaims it.\n - FAILED: An ordinary HTLC whose preimage was released but was not collected. This\ndiffers from CANCELED, which failed before preimage release."
},
"lnrpcKeyDescriptor": {
"type": "object",
### lnrpc/lightning_grpc.pb.go
@@ -223,7 +223,9 @@ type LightningClient interface {
SubscribeInvoices(ctx context.Context, in *InvoiceSubscription, opts ...grpc.CallOption) (Lightning_SubscribeInvoicesClient, error)
// lncli: `deletecanceledinvoice`
//DeleteCanceledInvoice removes a canceled invoice from the database. If the
- //invoice is not in the canceled state, an error will be returned.
+ //invoice is not in the canceled state, an error will be returned. Ordinary
+ //invoices whose preimage was released cannot be deleted, even if no funds
+ //were collected, so their release history is retained.
DeleteCanceledInvoice(ctx context.Context, in *DelCanceledInvoiceReq, opts ...grpc.CallOption) (*DelCanceledInvoiceResp, error)
// lncli: `decodepayreq`
//DecodePayReq takes an encoded payment request string and attempts to decode
@@ -1512,7 +1514,9 @@ type LightningServer interface {
SubscribeInvoices(*InvoiceSubscription, Lightning_SubscribeInvoicesServer) error
// lncli: `deletecanceledinvoice`
//DeleteCanceledInvoice removes a canceled invoice from the database. If the
- //invoice is not in the canceled state, an error will be returned.
+ //invoice is not in the canceled state, an error will be returned. Ordinary
+ //invoices whose preimage was released cannot be deleted, even if no funds
+ //were collected, so their release history is retained.
DeleteCanceledInvoice(context.Context, *DelCanceledInvoiceReq) (*DelCanceledInvoiceResp, error)
// lncli: `decodepayreq`
//DecodePayReq takes an encoded payment request string and attempts to decode
### rpcserver.go
@@ -7101,7 +7101,8 @@ func (r *rpcServer) ListPayments(ctx context.Context,
return paymentsResp, nil
}
-// DeleteCanceledInvoice remove a canceled invoice from the database.
+// DeleteCanceledInvoice removes a canceled invoice unless it carries ordinary
+// preimage-release history, which must survive even if collection failed.
func (r *rpcServer) DeleteCanceledInvoice(ctx context.Context,
req *lnrpc.DelCanceledInvoiceReq) (*lnrpc.DelCanceledInvoiceResp,
error) {
@@ -7124,6 +7125,22 @@ func (r *rpcServer) DeleteCanceledInvoice(ctx context.Context,
return nil, invoices.ErrInvoiceNotCanceled
}
+ // Cancellation after release is a collection failure, not evidence the
+ // secret stayed private. Keep the record even when nothing was paid.
+ if !invoice.IsAMP() {
+ for _, htlc := range invoice.Htlcs {
+ if htlc.State == invoices.HtlcStateSettled ||
+ htlc.State == invoices.HtlcStateFailed {
+
+ return nil, status.Error(
+ codes.FailedPrecondition,
+ "cannot delete invoice after "+
+ "preimage release",
+ )
+ }
+ }
+ }
+
err = r.server.invoicesDB.DeleteInvoice(ctx,
[]invoices.InvoiceDeleteRef{
{
### rpcserver_test.go
@@ -1,21 +1,177 @@
package lnd
import (
+ "context"
"fmt"
"testing"
"time"
"github.com/lightningnetwork/lnd/channeldb"
"github.com/lightningnetwork/lnd/fn/v2"
"github.com/lightningnetwork/lnd/graph/db/models"
+ "github.com/lightningnetwork/lnd/invoices"
"github.com/lightningnetwork/lnd/lnrpc"
+ "github.com/lightningnetwork/lnd/lntypes"
"github.com/lightningnetwork/lnd/lnwire"
"github.com/lightningnetwork/lnd/signal"
"github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/mock"
"github.com/stretchr/testify/require"
+ "google.golang.org/grpc/codes"
+ "google.golang.org/grpc/status"
"google.golang.org/protobuf/proto"
)
+// canceledInvoiceDBMock supplies only the database operations used by the
+// canceled-invoice RPC, leaving the concrete registry's lookup path intact.
+type canceledInvoiceDBMock struct {
+ invoices.InvoiceDB
+ mock.Mock
+}
+
+// Assert the embedded interface and overridden operations satisfy the registry
+// and RPC database contract without implementing unrelated storage methods.
+var _ invoices.InvoiceDB = (*canceledInvoiceDBMock)(nil)
+
+// LookupInvoice returns the arranged snapshot through the registry's normal
+// lookup path so deletion policy is tested at the RPC boundary.
+func (m *canceledInvoiceDBMock) LookupInvoice(ctx context.Context,
+ ref invoices.InvoiceRef) (invoices.Invoice, error) {
+
+ args := m.Called(ctx, ref)
+ invoice, _ := args.Get(0).(invoices.Invoice)
+ return invoice, args.Error(1)
+}
+
+// DeleteInvoice requires an explicit expectation so any deletion of a released
+// payment record fails the test rather than silently discarding its history.
+func (m *canceledInvoiceDBMock) DeleteInvoice(ctx context.Context,
+ refs []invoices.InvoiceDeleteRef) error {
+
+ args := m.Called(ctx, refs)
+ return args.Error(0)
+}
+
+// TestDeleteCanceledInvoiceReleaseHistory checks that canceled-invoice deletion
+// preserves ordinary release history even when all released HTLCs failed.
+func TestDeleteCanceledInvoiceReleaseHistory(t *testing.T) {
+ t.Parallel()
+
+ // Arrange canceled snapshots with a known preimage in every case.
+ // Only the HTLC evidence distinguishes an unreleased cancellation
+ // from released collection failures, including zero received credit.
+ preimage := lntypes.Preimage{1}
+ hash := preimage.Hash()
+ testCases := []struct {
+ name string
+ htlcStates []invoices.HtlcState
+ amtPaid lnwire.MilliSatoshi
+ allowDelete bool
+ }{
+ {
+ name: "unreleased cancellation",
+ htlcStates: []invoices.HtlcState{
+ invoices.HtlcStateCanceled,
+ },
+ allowDelete: true,
+ },
+ {
+ name: "all released HTLCs failed",
+ htlcStates: []invoices.HtlcState{
+ invoices.HtlcStateFailed,
+ },
+ },
+ {
+ name: "partially collected payment",
+ htlcStates: []invoices.HtlcState{
+ invoices.HtlcStateSettled,
+ invoices.HtlcStateFailed,
+ },
+ amtPaid: 500,
+ },
+ }
+ for _, tc := range testCases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ // Arrange the registry's lookup; require one delete
+ // only for the unreleased fixture. The
+ // unstarted registry performs lookup without workers.
+ ctx := t.Context()
+ htlcs := make(
+ map[models.CircuitKey]*invoices.InvoiceHTLC,
+ )
+ invoice := invoices.Invoice{
+ State: invoices.ContractCanceled,
+ AddIndex: 1,
+ AmtPaid: tc.amtPaid,
+ Terms: invoices.ContractTerm{
+ PaymentPreimage: &preimage,
+ },
+ Htlcs: htlcs,
+ }
+ for n, state := range tc.htlcStates {
+ invoice.Htlcs[models.CircuitKey{
+ HtlcID: uint64(n),
+ }] = &invoices.InvoiceHTLC{
+ State: state,
+ }
+ }
+ idb := &canceledInvoiceDBMock{}
+ idb.Test(t)
+ t.Cleanup(func() {
+ idb.AssertExpectations(t)
+ })
+ idb.On(
+ "LookupInvoice", ctx,
+ invoices.InvoiceRefByHash(hash),
+ ).Return(invoice, nil).Once()
+ if tc.allowDelete {
+ refs := []invoices.InvoiceDeleteRef{
+ {
+ PayHash: hash,
+ AddIndex: invoice.AddIndex,
+ },
+ }
+ idb.On(
+ "DeleteInvoice", ctx, refs,
+ ).Return(nil).Once()
+ }
+ r := &rpcServer{
+ server: &server{
+ invoicesDB: idb,
+ invoices: invoices.NewRegistry(
+ idb, nil,
+ &invoices.RegistryConfig{},
+ ),
+ },
+ }
+
+ // Act through the public canceled-only deletion method;
+ // released records must not reach database deletion.
+ resp, err := r.DeleteCanceledInvoice(
+ ctx, &lnrpc.DelCanceledInvoiceReq{
+ InvoiceHash: hash.String(),
+ },
+ )
+
+ // Assert unreleased cancellations remain deletable;
+ // both released failures return the documented status
+ // without a response; cleanup verifies database calls.
+ if tc.allowDelete {
+ require.NoError(t, err)
+ require.NotNil(t, resp)
+ } else {
+ require.Equal(
+ t, codes.FailedPrecondition,
+ status.Code(err),
+ )
+ require.Nil(t, resp)
+ }
+ })
+ }
+}
+
func TestGetAllPermissions(t *testing.T) {
perms := GetAllPermissions()
### server.go
@@ -679,6 +679,70 @@ func noiseDial(idKey keychain.SingleKeyECDH,
}
}
+// subscribeFinalInvoiceHtlcs converts final switch events into invoice
+// outcomes. Cancellation joins the forwarder so registry shutdown cannot
+// leave a sender blocked on the invoice consumer.
+func (s *server) subscribeFinalInvoiceHtlcs() (
+ <-chan invoices.FinalHtlcOutcome, func(), error) {
+
+ client, err := s.htlcNotifier.SubscribeHtlcEvents()
+ if err != nil {
+ return nil, nil, err
+ }
+
+ outcomes := make(chan invoices.FinalHtlcOutcome)
+ quit := make(chan struct{})
+
+ var wg sync.WaitGroup
+ wg.Add(1)
+ go func() {
+ defer wg.Done()
+ defer close(outcomes)
+
+ for {
+ var update interface{}
+ select {
+ case u, ok := <-client.Updates():
+ if !ok {
+ return
+ }
+ update = u
+
+ case <-quit:
+ return
+ }
+
+ event, ok := update.(*htlcswitch.FinalHtlcEvent)
+ if !ok {
+ continue
+ }
+
+ outcome := invoices.FinalHtlcOutcome{
+ Key: event.CircuitKey,
+ Settled: event.Settled,
+ Offchain: event.Offchain,
+ }
+
+ select {
+ case outcomes <- outcome:
+ case <-quit:
+ return
+ }
+ }
+ }()
+
+ var once sync.Once
+ cancel := func() {
+ once.Do(func() {
+ close(quit)
+ client.Cancel()
+ wg.Wait()
+ })
+ }
+
+ return outcomes, cancel, nil
+}
+
// newServer creates a new instance of the server which is to listen using the
// passed listener address.
//
@@ -894,6 +958,15 @@ func newServer(ctx context.Context, cfg *Config, listenAddrs []net.Addr,
clock.NewDefaultClock(), cfg.Invoices.HoldExpiryDelta,
uint32(currentHeight), currentHash, cc.ChainNotifier,
)
+
+ s.htlcNotifier = htlcswitch.NewHtlcNotifier(time.Now)
+
+ // The registry learns from the final htlc outcomes when an invoice it
+ // released the preimage for is irrevocably settled.
+ registryConfig.FinalHtlcSource = invoices.NewFinalHtlcSource(
+ chanStateDB, s.subscribeFinalInvoiceHtlcs,
+ )
+
s.invoices = invoices.NewRegistry(
dbs.InvoiceDB, expiryWatcher, ®istryConfig,
)
@@ -918,8 +991,6 @@ func newServer(ctx context.Context, cfg *Config, listenAddrs []net.Addr,
}
}
- s.htlcNotifier = htlcswitch.NewHtlcNotifier(time.Now)
-
thresholdSats := btcutil.Amount(cfg.MaxFeeExposure)
thresholdMSats := lnwire.NewMSatFromSatoshis(thresholdSats)
### sqldb/sqlc/invoices.sql.go
@@ -24,6 +24,13 @@ const deleteCanceledInvoices = `-- name: DeleteCanceledInvoices :execresult
DELETE
FROM invoices
WHERE state = 2
+ -- Keep ordinary release history even when every released HTLC failed.
+ AND (is_amp OR NOT EXISTS (
+ SELECT 1
+ FROM invoice_htlcs
+ WHERE invoice_id = invoices.id
+ AND state IN (2, 4) -- HtlcStateSettled, HtlcStateFailed
+ ))
`
func (q *Queries) DeleteCanceledInvoices(ctx context.Context) (sql.Result, error) {
@@ -68,7 +75,7 @@ const fetchPendingInvoices = `-- name: FetchPendingInvoices :many
SELECT
invoices.id, invoices.hash, invoices.preimage, invoices.settle_index, invoices.settled_at, invoices.memo, invoices.amount_msat, invoices.cltv_delta, invoices.expiry, invoices.payment_addr, invoices.payment_request, invoices.payment_request_hash, invoices.state, invoices.amount_paid_msat, invoices.is_amp, invoices.is_hodl, invoices.is_keysend, invoices.created_at
FROM invoices
-WHERE state IN (0, 3) -- 0 = ContractOpen, 3 = ContractAccepted
+WHERE state IN (0, 3, 4) -- 0 = ContractOpen, 3 = ContractAccepted, 4 = ContractPendingSettle
AND id > $1
ORDER BY id ASC
LIMIT $2
@@ -79,11 +86,11 @@ type FetchPendingInvoicesParams struct {
NumLimit int32
}
-// FetchPendingInvoices returns all invoices in a pending state (open or
-// accepted). The invoices_state_idx index on the state column makes this a
-// fast index scan rather than a full table scan. id_cursor is an exclusive
-// lower bound on the primary key used for cursor-based pagination; the caller
-// must supply 0 when starting from the beginning.
+// FetchPendingInvoices returns all invoices in a pending state (open,
+// accepted or pending settle). The invoices_state_idx index on the state column
+// makes this a fast index scan rather than a full table scan. id_cursor is an
+// exclusive lower bound on the primary key used for cursor-based pagination;
+// the caller must supply 0 when starting from the beginning.
func (q *Queries) FetchPendingInvoices(ctx context.Context, arg FetchPendingInvoicesParams) ([]Invoice, error) {
rows, err := q.db.QueryContext(ctx, fetchPendingInvoices, arg.IDCursor, arg.NumLimit)
if err != nil {
@@ -126,6 +133,71 @@ func (q *Queries) FetchPendingInvoices(ctx context.Context, arg FetchPendingInvo
return items, nil
}
+const fetchPendingSettleInvoices = `-- name: FetchPendingSettleInvoices :many
+SELECT
+ invoices.id, invoices.hash, invoices.preimage, invoices.settle_index, invoices.settled_at, invoices.memo, invoices.amount_msat, invoices.cltv_delta, invoices.expiry, invoices.payment_addr, invoices.payment_request, invoices.payment_request_hash, invoices.state, invoices.amount_paid_msat, invoices.is_amp, invoices.is_hodl, invoices.is_keysend, invoices.created_at
+FROM invoices
+INNER JOIN (
+ SELECT DISTINCT invoice_id
+ FROM invoice_htlcs
+ WHERE state = 3 -- HtlcStatePendingSettle
+) pending_settle ON pending_settle.invoice_id = invoices.id
+WHERE invoices.id > $1
+ORDER BY invoices.id ASC
+LIMIT $2
+`
+
+type FetchPendingSettleInvoicesParams struct {
+ IDCursor int64
+ NumLimit int32
+}
+
+// FetchPendingSettleInvoices returns all invoices containing at least one HTLC
+// whose final outcome is still pending, including children of settled parents.
+// The parent-state pending filter cannot recover those duplicate payments.
+// id_cursor is an exclusive lower bound for cursor-based pagination.
+func (q *Queries) FetchPendingSettleInvoices(ctx context.Context, arg FetchPendingSettleInvoicesParams) ([]Invoice, error) {
+ rows, err := q.db.QueryContext(ctx, fetchPendingSettleInvoices, arg.IDCursor, arg.NumLimit)
+ if err != nil {
+ return nil, err
+ }
+ defer rows.Close()
+ var items []Invoice
+ for rows.Next() {
+ var i Invoice
+ if err := rows.Scan(
+ &i.ID,
+ &i.Hash,
+ &i.Preimage,
+ &i.SettleIndex,
+ &i.SettledAt,
+ &i.Memo,
+ &i.AmountMsat,
+ &i.CltvDelta,
+ &i.Expiry,
+ &i.PaymentAddr,
+ &i.PaymentRequest,
+ &i.PaymentRequestHash,
+ &i.State,
+ &i.AmountPaidMsat,
+ &i.IsAmp,
+ &i.IsHodl,
+ &i.IsKeysend,
+ &i.CreatedAt,
+ ); err != nil {
+ return nil, err
+ }
+ items = append(items, i)
+ }
+ if err := rows.Close(); err != nil {
+ return nil, err
+ }
+ if err := rows.Err(); err != nil {
+ return nil, err
+ }
+ return items, nil
+}
+
const filterInvoicesByAddIndex = `-- name: FilterInvoicesByAddIndex :many
SELECT
invoices.id, invoices.hash, invoices.preimage, invoices.settle_index, invoices.settled_at, invoices.memo, invoices.amount_msat, invoices.cltv_delta, invoices.expiry, invoices.payment_addr, invoices.payment_request, invoices.payment_request_hash, invoices.state, invoices.amount_paid_msat, invoices.is_amp, invoices.is_hodl, invoices.is_keysend, invoices.created_at
@@ -256,7 +328,7 @@ SELECT
invoices.id, invoices.hash, invoices.preimage, invoices.settle_index, invoices.settled_at, invoices.memo, invoices.amount_msat, invoices.cltv_delta, invoices.expiry, invoices.payment_addr, invoices.payment_request, invoices.payment_request_hash, invoices.state, invoices.amount_paid_msat, invoices.is_amp, invoices.is_hodl, invoices.is_keysend, invoices.created_at
FROM invoices
WHERE id >= $1
- AND (NOT $2 OR state IN (0, 3)) -- 0 = ContractOpen, 3 = ContractAccepted
+ AND (NOT $2 OR state IN (0, 3, 4)) -- 0 = ContractOpen, 3 = ContractAccepted, 4 = ContractPendingSettle
AND created_at >= $3
AND created_at < $4
ORDER BY id ASC
@@ -334,7 +406,7 @@ SELECT
invoices.id, invoices.hash, invoices.preimage, invoices.settle_index, invoices.settled_at, invoices.memo, invoices.amount_msat, invoices.cltv_delta, invoices.expiry, invoices.payment_addr, invoices.payment_request, invoices.payment_request_hash, invoices.state, invoices.amount_paid_msat, invoices.is_amp, invoices.is_hodl, invoices.is_keysend, invoices.created_at
FROM invoices
WHERE id <= $1
- AND (NOT $2 OR state IN (0, 3)) -- 0 = ContractOpen, 3 = ContractAccepted
+ AND (NOT $2 OR state IN (0, 3, 4)) -- 0 = ContractOpen, 3 = ContractAccepted, 4 = ContractPendingSettle
AND created_at >= $3
AND created_at < $4
ORDER BY id DESC
### sqldb/sqlc/querier.go
@@ -63,12 +63,17 @@ type Querier interface {
// Migration-specific batch fetch that returns payment data along with HTLC
// attempt counts for structural validation during KV to SQL migration.
FetchPaymentsByIDsMig(ctx context.Context, paymentIds []int64) ([]FetchPaymentsByIDsMigRow, error)
- // FetchPendingInvoices returns all invoices in a pending state (open or
- // accepted). The invoices_state_idx index on the state column makes this a
- // fast index scan rather than a full table scan. id_cursor is an exclusive
- // lower bound on the primary key used for cursor-based pagination; the caller
- // must supply 0 when starting from the beginning.
+ // FetchPendingInvoices returns all invoices in a pending state (open,
+ // accepted or pending settle). The invoices_state_idx index on the state column
+ // makes this a fast index scan rather than a full table scan. id_cursor is an
+ // exclusive lower bound on the primary key used for cursor-based pagination;
+ // the caller must supply 0 when starting from the beginning.
FetchPendingInvoices(ctx context.Context, arg FetchPendingInvoicesParams) ([]Invoice, error)
+ // FetchPendingSettleInvoices returns all invoices containing at least one HTLC
+ // whose final outcome is still pending, including children of settled parents.
+ // The parent-state pending filter cannot recover those duplicate payments.
+ // id_cursor is an exclusive lower bound for cursor-based pagination.
+ FetchPendingSettleInvoices(ctx context.Context, arg FetchPendingSettleInvoicesParams) ([]Invoice, error)
FetchRouteLevelFirstHopCustomRecords(ctx context.Context, htlcAttemptIndices []int64) ([]PaymentAttemptFirstHopCustomRecord, error)
FetchSettledAMPSubInvoices(ctx context.Context, arg FetchSettledAMPSubInvoicesParams) ([]FetchSettledAMPSubInvoicesRow, error)
// FilterInvoicesByAddIndex returns invoices whose add_index (primary key id)
### sqldb/sqlc/queries/invoices.sql
@@ -48,19 +48,36 @@ INNER JOIN amp_sub_invoices a
ON i.id = a.invoice_id AND a.set_id = $1;
-- name: FetchPendingInvoices :many
--- FetchPendingInvoices returns all invoices in a pending state (open or
--- accepted). The invoices_state_idx index on the state column makes this a
--- fast index scan rather than a full table scan. id_cursor is an exclusive
--- lower bound on the primary key used for cursor-based pagination; the caller
--- must supply 0 when starting from the beginning.
+-- FetchPendingInvoices returns all invoices in a pending state (open,
+-- accepted or pending settle). The invoices_state_idx index on the state column
+-- makes this a fast index scan rather than a full table scan. id_cursor is an
+-- exclusive lower bound on the primary key used for cursor-based pagination;
+-- the caller must supply 0 when starting from the beginning.
SELECT
invoices.*
FROM invoices
-WHERE state IN (0, 3) -- 0 = ContractOpen, 3 = ContractAccepted
+WHERE state IN (0, 3, 4) -- 0 = ContractOpen, 3 = ContractAccepted, 4 = ContractPendingSettle
AND id > @id_cursor
ORDER BY id ASC
LIMIT @num_limit;
+-- name: FetchPendingSettleInvoices :many
+-- FetchPendingSettleInvoices returns all invoices containing at least one HTLC
+-- whose final outcome is still pending, including children of settled parents.
+-- The parent-state pending filter cannot recover those duplicate payments.
+-- id_cursor is an exclusive lower bound for cursor-based pagination.
+SELECT
+ invoices.*
+FROM invoices
+INNER JOIN (
+ SELECT DISTINCT invoice_id
+ FROM invoice_htlcs
+ WHERE state = 3 -- HtlcStatePendingSettle
+) pending_settle ON pending_settle.invoice_id = invoices.id
+WHERE invoices.id > @id_cursor
+ORDER BY invoices.id ASC
+LIMIT @num_limit;
+
-- name: FilterInvoicesBySettleIndex :many
-- FilterInvoicesBySettleIndex returns settled invoices whose settle_index is
-- greater than or equal to the given value, ordered by id. The caller must
@@ -103,7 +120,7 @@ SELECT
invoices.*
FROM invoices
WHERE id >= @add_index_get
- AND (NOT @pending_only OR state IN (0, 3)) -- 0 = ContractOpen, 3 = ContractAccepted
+ AND (NOT @pending_only OR state IN (0, 3, 4)) -- 0 = ContractOpen, 3 = ContractAccepted, 4 = ContractPendingSettle
AND created_at >= @created_after
AND created_at < @created_before
ORDER BY id ASC
@@ -119,7 +136,7 @@ SELECT
invoices.*
FROM invoices
WHERE id <= @add_index_let
- AND (NOT @pending_only OR state IN (0, 3)) -- 0 = ContractOpen, 3 = ContractAccepted
+ AND (NOT @pending_only OR state IN (0, 3, 4)) -- 0 = ContractOpen, 3 = ContractAccepted, 4 = ContractPendingSettle
AND created_at >= @created_after
AND created_at < @created_before
ORDER BY id DESC
@@ -163,7 +180,14 @@ WHERE (
-- name: DeleteCanceledInvoices :execresult
DELETE
FROM invoices
-WHERE state = 2;
+WHERE state = 2
+ -- Keep ordinary release history even when every released HTLC failed.
+ AND (is_amp OR NOT EXISTS (
+ SELECT 1
+ FROM invoice_htlcs
+ WHERE invoice_id = invoices.id
+ AND state IN (2, 4) -- HtlcStateSettled, HtlcStateFailed
+ ));
-- name: InsertInvoiceHTLC :one
INSERT INTO invoice_htlcs (Why this scored 68/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.