Define best-effort payment event delivery

Acknowledge payment events when no subscriber is connected or required
payment details cannot be read, so the node event queue can continue.
Skip payment lookups when no subscriber is connected.

Document live delivery limits, state reconciliation, unrecoverable
payer-proof inputs, and automatic failure of unclaimed hold payments
at their claim deadline.

AI assistance: OpenAI Codex was used for this change.

Author: benthecarman

docs/api-guide.md

@@ -216,8 +216,21 @@ See [Pagination](#pagination) below for how to page through results.
 | `SpliceNegotiated` | A channel splice was negotiated and the funding transaction is pending confirmation |
 | `SpliceNegotiationFailed` | A channel splice negotiation round failed                       |
 
-Events are broadcast to all connected subscribers. The server uses a bounded broadcast channel
-(capacity 1024). A slow subscriber that falls behind will miss events.
+> [!WARNING]
+> `SubscribeEvents` is a best-effort stream of new events. Events are not persisted for
+> subscribers, cannot be replayed after reconnecting, and have no client acknowledgement.
+> Acceptance by the server's broadcast channel does not guarantee that a client received or
+> processed an event.
+
+Events are broadcast to all currently connected subscribers. The server uses a bounded broadcast
+channel (capacity 1024), so a slow subscriber that falls behind will miss events. Disconnected
+clients also miss events and receive only new events after reconnecting. If the server cannot read
+data required to construct a payment event, it logs the error and skips that event so the event
+queue can continue processing.
+
+Use events as notifications. After reconnecting, reconcile recoverable state with APIs such as
+`GetPaymentDetails`, `ListPayments`, `ListForwardedPayments`, and `ListChannels`. Some event fields
+cannot be recovered through these APIs.
 
 ### Metrics
 
@@ -236,7 +249,9 @@ Subscribe with `SubscribeEvents` before you send a BOLT 12 payment. Events are n
 
 When `PaymentSuccessful` arrives, retain its `payment_id`, `payment_preimage`, and
 `bolt12_invoice`. Pass these values to `Bolt12CreatePayerProof`. The request can also select the
-optional invoice fields that the proof discloses.
+optional invoice fields that the proof discloses. Payment history APIs cannot recover all the
+inputs required to create a proof if this event is missed. Save these values before processing
+other events.
 
 The `bolt12_invoice` field is absent for static-invoice payments. These asynchronous payments
 cannot produce payer proofs.
@@ -263,9 +278,11 @@ stored payment amount, less any skimmed fee. It is not an exact amount check or
 that many millisatoshis. A larger supplied amount passes this check; omitting it skips the check.
 Always validate the event's amount before you claim the payment.
 
-The payment is held in a pending state until you explicitly claim or fail it. **You must
-always handle each event.** If you do not, the HTLC will eventually time out. This can cause a
-force-closure of the channel.
+The payment is held in a pending state until you claim it, fail it, or its `claim_deadline` is
+reached. `PaymentClaimable` notifications are best-effort and are not replayed. If you miss the
+event or do not act before the deadline, LDK Node automatically fails the HTLC backward and the
+payment can no longer be claimed. Keep the subscriber healthy and resolve reported persistence
+errors before accepting further payments.
 
 ## Pagination
 

ldk-server-grpc/src/api.rs

@@ -1422,7 +1422,15 @@ pub struct DecodeOfferResponse {
 	#[prost(bool, tag = "12")]
 	pub is_expired: bool,
 }
-/// Subscribe to a stream of server events.
+/// Subscribe to a best-effort stream of new server events.
+///
+/// Events are not persisted for subscribers or replayed after reconnecting, and the server does not
+/// wait for client acknowledgement. Slow or disconnected subscribers may miss events. Reconcile
+/// recoverable state with the listing and detail APIs after reconnecting. Some event fields,
+/// including inputs required for payer proofs, cannot be recovered through these APIs.
+///
+/// If a PaymentClaimable event is missed and the payment is not otherwise claimed or failed, LDK
+/// Node automatically fails the HTLC backward at its claim_deadline.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 #[cfg_attr(feature = "serde", serde(default))]

ldk-server-grpc/src/events.rs

@@ -244,6 +244,9 @@ pub struct PaymentFailed {
 /// This event is only emitted for payments created via `Bolt11ReceiveForHash`.
 /// Handle every event by its payment ID before `claim_deadline`.
 /// The same invoice can produce more than one event. Fail unexpected duplicate or late payments.
+/// Delivery through SubscribeEvents is best-effort and is not replayed. If the event is missed and
+/// the payment is not otherwise claimed or failed, LDK Node automatically fails the HTLC backward at
+/// claim_deadline.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 #[cfg_attr(feature = "serde", serde(default))]

ldk-server-grpc/src/proto/api.proto

@@ -1021,7 +1021,15 @@ message DecodeOfferResponse {
   bool is_expired = 12;
 }
 
-// Subscribe to a stream of server events.
+// Subscribe to a best-effort stream of new server events.
+//
+// Events are not persisted for subscribers or replayed after reconnecting, and the server does not
+// wait for client acknowledgement. Slow or disconnected subscribers may miss events. Reconcile
+// recoverable state with the listing and detail APIs after reconnecting. Some event fields,
+// including inputs required for payer proofs, cannot be recovered through these APIs.
+//
+// If a PaymentClaimable event is missed and the payment is not otherwise claimed or failed, LDK
+// Node automatically fails the HTLC backward at its claim_deadline.
 message SubscribeEventsRequest {}
 
 service LightningNode {

ldk-server-grpc/src/proto/events.proto

@@ -184,6 +184,9 @@ message PaymentFailed {
 // This event is only emitted for payments created via `Bolt11ReceiveForHash`.
 // Handle every event by its payment ID before `claim_deadline`.
 // The same invoice can produce more than one event. Fail unexpected duplicate or late payments.
+// Delivery through SubscribeEvents is best-effort and is not replayed. If the event is missed and
+// the payment is not otherwise claimed or failed, LDK Node automatically fails the HTLC backward at
+// claim_deadline.
 message PaymentClaimable {
   // The local identifier used to track the payment, in hex-encoded form.
   string payment_id = 1;

ldk-server/src/main.rs

@@ -760,6 +760,14 @@ fn send_payment_event(
 	payment_id: &PaymentId, payment_to_event: impl FnOnce(&Payment) -> event_envelope::Event,
 	event_node: &Node, event_sender: &broadcast::Sender<EventEnvelope>,
 ) {
+	if event_sender.receiver_count() == 0 {
+		debug!("No event subscribers connected, skipping payment event");
+		if let Err(e) = event_node.event_handled() {
+			error!("Failed to mark event as handled: {e}");
+		}
+		return;
+	}
+
 	match event_node.payment(payment_id) {
 		Ok(Some(payment_details)) => {
 			let payment = payment_to_proto(payment_details);
@@ -768,13 +776,16 @@ fn send_payment_event(
 			if let Err(e) = event_sender.send(EventEnvelope { event: Some(event) }) {
 				debug!("No event subscribers connected, skipping event: {e}");
 			}
-
-			if let Err(e) = event_node.event_handled() {
-				error!("Failed to mark event as handled: {e}");
-			}
 		},
-		Ok(None) => error!("Unable to find payment with payment ID: {payment_id}"),
-		Err(e) => error!("Failed to retrieve payment with payment ID {payment_id}: {e}"),
+		Ok(None) => {
+			error!("Unable to find payment with payment ID: {payment_id}");
+		},
+		Err(e) => {
+			error!("Failed to retrieve payment with payment ID {payment_id}: {e}");
+		},
+	}
+	if let Err(e) = event_node.event_handled() {
+		error!("Failed to mark event as handled: {e}");
 	}
 }