[shaavan]

Overview

This PR adds receiver-side tracking for recurring BOLT 12 payments to LDK Node, based on lightning/bolts#1240.

rust-lightning handles the recurrence protocol and provides the offer terms and invoice timing through payment events. LDK Node saves each offer-and-payer relationship, decides whether an incoming payment can be accepted, and records its outcome.

This prevents different payments from claiming the same counter and lets applications inspect recurrence state.

Scope

• Persistent state: Save recurrence terms, timing, status, pending reservations, and completed payments separately from individual payment records.
• Payment acceptance: Reserve the expected counter before claiming funds. Reject competing payments and new payments for cancelled recurrences. Leave invoice-request window checks to LDK.
• Successful payments and replay: Record success only on PaymentClaimed. Recognize repeated confirmations without advancing twice or changing newer progress and reservations. Return ReplayEvent when a write fails.
• Cancellation: Persist cancellation under the same lock as acceptance. Block new payments while allowing an already accepted payment to finish without clearing the cancelled status.
• Lookup and listing: Expose saved recurrence details through Rust APIs that return copies without allowing applications to change stored state.
• Tests: Add focused coverage for storage, APIs, acceptance, payment progress, replay, concurrent claims, and cancellation in separate test commits.

Deferred work

The following work is deferred to follow-up PRs.

• Restart reconciliation: Recover unfinished reservations when no event is available to replay. This requires reconciling recurrence records, payment records, and restored LDK state.
• Failed-payment reservation release: Allow another attempt only after the whole inbound payment is known to have failed. A single failed HTLC is not enough proof to release its counter.
• Missed-window tracking: Add scheduling to mark recurrences missed when their payment window closes.
• Preventing future invoice issuance: Integrate cancellation with LDK’s earlier invoice-request handling. The current implementation controls payment acceptance after an invoice has been issued.
• UniFFI exposure: Add language bindings as part of the shared bindings work.

[ldk-reviews-bot]

I've assigned @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.