SubscribeEvents: support resuming from an event index for reliable at-least-once delivery #245

Motivation

SubscribeEvents is currently best-effort: events are fanned out over a bounded broadcast channel, so a subscriber that is disconnected, restarting, or too slow misses events with no way to recover them from the stream (the API guide documents this: "A slow subscriber that falls behind will miss events").

For payment-critical consumers this is hard to build on. A daemon driving hodl invoices via Bolt11ReceiveForHash must not miss PaymentClaimable or PaymentSuccessful; accounting and forwarding-analytics consumers need every event exactly because they don't know in advance which payment ids matter, so reconciling via ListPayments/GetPaymentDetails after a gap is either racy or a full rescan.

Proposed API

Two additive proto changes, no new RPC:

message EventEnvelope {
  // Globally monotonic index assigned to every event, across all event kinds.
  uint64 event_index = 1;

  oneof event { ... }  // unchanged
}

message SubscribeEventsRequest {
  // If set, first replays all events with event_index greater than this
  // value, in order, then continues with live events on the same stream.
  // If unset, the stream starts from now (current behavior).
  optional uint64 resume_after_index = 1;
}

Semantics:

• One server stream, one ordered sequence: replayed events first, then live events, indistinguishable to the client.
• Delivery is at-least-once. The client persists the last processed event_index and, on any disconnect or error, simply resubscribes with it. Duplicate delivery at the seam is allowed; clients dedup by index.
• A single global sequence covering all event kinds (payments, forwards, channel state), so one cursor per subscriber is sufficient. Multiple independent subscribers each hold their own cursor; the server keeps no per-subscriber state.
• If the server bounds how much history it retains, a defined error for a too-old cursor lets the client detect that it must fall back to a full resync — this contract should be part of the API even though retention itself is an implementation choice.

Relevance to ldk-node

The same API shape would arguably be practical for ldk-node itself.