fixup! Use ldk-node payment pagination

Expose the claimable amount so subscribers can validate held payments.
Document event delivery limits, claim deadlines, and the current amount
check. Share channel count calculations and event acknowledgements.

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.
@@ -252,13 +267,22 @@ Hodl invoices allow you to inspect and conditionally accept incoming payments:
 3. **Handle each payment:** Save the payment ID from each `PaymentClaimable` event. A payer can pay
    the same invoice more than once. Each payment has a separate event and payment ID.
 4. **Decide before `claim_deadline`:**
-    - **Accept an expected payment:** Call `Bolt11ClaimForId` with its payment ID and preimage.
+    - **Accept an expected payment:** Check the event's `claimable_amount_msat` against the amount
+      you expect. Call `Bolt11ClaimForId` with its payment ID, preimage, and the event's claimable
+      amount.
     - **Reject an unexpected payment:** Call `Bolt11FailForId` with its payment ID. Reject duplicate
       and late payments instead of ignoring or claiming them.
 
-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 claim request's optional amount is passed to LDK Node for a lower-bound check against its
+stored payment amount, less any skimmed fee. It is not an exact amount check or a request to claim
+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 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-cli/src/main.rs

@@ -172,7 +172,7 @@ enum Commands {
 		#[arg(
 			short,
 			long,
-			help = "The claimable amount, e.g. 50sat or 50000msat, only used for verifying we are claiming the expected amount"
+			help = "The amount from PaymentClaimable, e.g. 50sat or 50000msat. Used for a lower-bound check, not an exact amount check; validate the event amount before claiming"
 		)]
 		claimable_amount: Option<Amount>,
 	},

ldk-server-grpc/src/api.rs

@@ -256,8 +256,11 @@ pub struct Bolt11ClaimForIdRequest {
 	/// The hex-encoded 32-byte payment ID from `PaymentClaimable`.
 	#[prost(string, tag = "1")]
 	pub payment_id: ::prost::alloc::string::String,
-	/// The amount in millisatoshi that is claimable.
-	/// If not provided, skips amount verification.
+	/// The claimable amount in millisatoshis from the PaymentClaimable event.
+	/// LDK Node rejects a value below its stored payment amount, less any skimmed fee.
+	/// A larger value passes this check. This is not an exact amount check or a request
+	/// to claim that many millisatoshis. Validate the event's amount before claiming.
+	/// If not provided, skips this amount check.
 	#[prost(uint64, optional, tag = "2")]
 	pub claimable_amount_msat: ::core::option::Option<u64>,
 	/// The hex-encoded 32-byte payment preimage.
@@ -1419,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))]
@@ -262,6 +265,10 @@ pub struct PaymentClaimable {
 	/// The block height by which this payment must be claimed before it is failed back.
 	#[prost(uint32, optional, tag = "4")]
 	pub claim_deadline: ::core::option::Option<u32>,
+	/// The amount in millisatoshis that is claimable. Validate this against the amount you expect
+	/// before calling Bolt11ClaimForId, and pass this value as its claimable_amount_msat.
+	#[prost(uint64, tag = "5")]
+	pub claimable_amount_msat: u64,
 }
 /// PaymentForwarded indicates a payment was forwarded through the node.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

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

@@ -200,8 +200,11 @@ message Bolt11ClaimForIdRequest {
   // The hex-encoded 32-byte payment ID from `PaymentClaimable`.
   string payment_id = 1;
 
-  // The amount in millisatoshi that is claimable.
-  // If not provided, skips amount verification.
+  // The claimable amount in millisatoshis from the PaymentClaimable event.
+  // LDK Node rejects a value below its stored payment amount, less any skimmed fee.
+  // A larger value passes this check. This is not an exact amount check or a request
+  // to claim that many millisatoshis. Validate the event's amount before claiming.
+  // If not provided, skips this amount check.
   optional uint64 claimable_amount_msat = 2;
 
   // The hex-encoded 32-byte payment preimage.
@@ -1018,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;
@@ -193,6 +196,9 @@ message PaymentClaimable {
   repeated types.CustomTlvRecord custom_records = 3;
   // The block height by which this payment must be claimed before it is failed back.
   optional uint32 claim_deadline = 4;
+  // The amount in millisatoshis that is claimable. Validate this against the amount you expect
+  // before calling Bolt11ClaimForId, and pass this value as its claimable_amount_msat.
+  uint64 claimable_amount_msat = 5;
 }
 
 // PaymentForwarded indicates a payment was forwarded through the node.

ldk-server/src/main.rs

@@ -560,7 +560,7 @@ fn main() {
 								&event_sender);
 
 						},
-						Event::PaymentClaimable { payment_id, custom_records, claim_deadline, .. } => {
+						Event::PaymentClaimable { payment_id, custom_records, claim_deadline, claimable_amount_msat, .. } => {
 							send_payment_event(
 								&payment_id,
 								|payment| {
@@ -569,6 +569,7 @@ fn main() {
 											payment,
 											&custom_records,
 											claim_deadline,
+											claimable_amount_msat,
 											payment_id.to_string(),
 										),
 									)
@@ -776,24 +777,17 @@ 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}");
-			if let Err(e) = event_node.event_handled() {
-				error!("Failed to mark event as handled: {e}");
-			}
 		},
 		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}");
-			}
 		},
 	}
+	if let Err(e) = event_node.event_handled() {
+		error!("Failed to mark event as handled: {e}");
+	}
 }
 
 fn send_channel_state_event(
@@ -1012,7 +1006,7 @@ fn load_or_generate_api_key(storage_dir: &Path) -> std::io::Result<String> {
 
 fn build_payment_claimable_proto(
 	payment: Payment, custom_records: &[CustomTlvRecord], claim_deadline: Option<u32>,
-	payment_id: String,
+	claimable_amount_msat: u64, payment_id: String,
 ) -> events::PaymentClaimable {
 	let proto_custom_records: Vec<_> =
 		custom_records.iter().map(node_to_proto_custom_tlv).collect();
@@ -1021,6 +1015,7 @@ fn build_payment_claimable_proto(
 		payment: Some(payment),
 		custom_records: proto_custom_records,
 		claim_deadline,
+		claimable_amount_msat,
 	}
 }
 
@@ -1143,14 +1138,24 @@ mod tests {
 	}
 
 	#[test]
-	fn payment_claimable_proto_contains_custom_records() {
+	fn payment_claimable_proto_preserves_event_fields() {
 		let payment = ldk_server_grpc::types::Payment::default();
 		let records = vec![
 			CustomTlvRecord { type_num: 65537, value: vec![1, 2, 3] },
 			CustomTlvRecord { type_num: 65538, value: Vec::new() },
 		];
-		let proto = build_payment_claimable_proto(payment, &records, None, "abc123".to_string());
+		let proto = build_payment_claimable_proto(
+			payment,
+			&records,
+			Some(800_000),
+			42_123,
+			"abc123".to_string(),
+		);
+		let encoded = proto.encode_to_vec();
+		let proto = events::PaymentClaimable::decode(encoded.as_slice()).unwrap();
 		assert_eq!(proto.payment_id, "abc123");
+		assert_eq!(proto.claim_deadline, Some(800_000));
+		assert_eq!(proto.claimable_amount_msat, 42_123);
 		assert_eq!(proto.custom_records.len(), 2);
 		assert_eq!(proto.custom_records[0].type_num, 65537);
 		assert_eq!(proto.custom_records[0].value.to_vec(), vec![1, 2, 3]);

ldk-server/src/util/metrics.rs

@@ -26,7 +26,7 @@
 use std::sync::atomic::{AtomicI64, AtomicU64, Ordering};
 
 use ldk_node::payment::PaymentStatus;
-use ldk_node::{Node, NodeError};
+use ldk_node::{ChannelDetails, Node, NodeError};
 use log::error;
 
 #[derive(Default)]
@@ -123,20 +123,19 @@ impl Metrics {
 		let all_channels = node.list_channels();
 		self.total_channels_count.store(all_channels.len() as i64, Ordering::Relaxed);
 
-		let public_channels_count =
-			all_channels.iter().filter(|channel_details| channel_details.is_announced).count()
-				as i64;
-		self.total_public_channels_count.store(public_channels_count, Ordering::Relaxed);
-
-		let private_channels_count =
-			all_channels.iter().filter(|channel_details| !channel_details.is_announced).count()
-				as i64;
-		self.total_private_channels_count.store(private_channels_count, Ordering::Relaxed);
+		self.update_channel_visibility_counts(&all_channels);
 
 		self.update_peer_count(node);
 		self.update_all_balances(node);
 	}
 
+	fn update_channel_visibility_counts(&self, channels: &[ChannelDetails]) {
+		let public_count = channels.iter().filter(|channel| channel.is_announced).count();
+		let private_count = channels.len() - public_count;
+		self.total_public_channels_count.store(public_count as i64, Ordering::Relaxed);
+		self.total_private_channels_count.store(private_count as i64, Ordering::Relaxed);
+	}
+
 	pub fn update_all_balances(&self, node: &Node) {
 		let all_balances = node.list_balances();
 		self.total_onchain_balance_sats
@@ -160,15 +159,7 @@ impl Metrics {
 			Err(e) => error!("Failed to update payment metrics: {e}"),
 		}
 
-		let public_channels_count =
-			all_channels.iter().filter(|channel_details| channel_details.is_announced).count()
-				as i64;
-		self.total_public_channels_count.store(public_channels_count, Ordering::Relaxed);
-
-		let private_channels_count =
-			all_channels.iter().filter(|channel_details| !channel_details.is_announced).count()
-				as i64;
-		self.total_private_channels_count.store(private_channels_count, Ordering::Relaxed);
+		self.update_channel_visibility_counts(&all_channels);
 
 		self.update_peer_count(node);
 		self.update_all_balances(node);