sdk: Add event streaming

Cargo.toml

@@ -30,6 +30,7 @@ env_logger = "0.10"
 cln-grpc = "0.4"
 cln-rpc = "0.4"
 cln-plugin = "0.4"
+tonic = "0.11"
 
 vls-core = "^0.14"
 vls-persist = "^0.14"

libs/gl-client-py/glclient/__init__.py

@@ -448,21 +448,22 @@ def stream_log(self):
                 break
             yield nodepb.LogEntry.FromString(bytes(n))
 
-    def stream_incoming(self):
-        stream = self.inner.stream_incoming(b"")
+    def stream_custommsg(self):
+        stream = self.inner.stream_custommsg(b"")
         while True:
             n = stream.next()
             if n is None:
                 break
-            yield nodepb.IncomingPayment.FromString(bytes(n))
+            yield nodepb.Custommsg.FromString(bytes(n))
 
-    def stream_custommsg(self):
-        stream = self.inner.stream_custommsg(b"")
+    def stream_node_events(self):
+        """Stream node events (invoice payments, peer changes, etc.) as they occur."""
+        stream = self.inner.stream_node_events(b"")
         while True:
             n = stream.next()
             if n is None:
                 break
-            yield nodepb.Custommsg.FromString(bytes(n))
+            yield nodepb.NodeEvent.FromString(bytes(n))
 
     def send_custommsg(self, node_id: str, msg: bytes) -> clnpb.SendcustommsgResponse:
         uri = "/cln.Node/SendCustomMsg"

libs/gl-client-py/glclient/greenlight.proto

@@ -25,7 +25,6 @@ service Node {
 	//
 	// Currently includes off-chain payments received matching an
 	// invoice or spontaneus paymens through keysend.
-	rpc StreamIncoming(StreamIncomingFilter) returns (stream IncomingPayment) {}
 
 	// Stream the logs as they are produced by the node
 	//
@@ -43,6 +42,14 @@ service Node {
 	// replayed if the stream is interrupted.
 	rpc StreamCustommsg(StreamCustommsgRequest) returns (stream Custommsg) {}
 
+	// Stream node events in real-time.
+	//
+	// This is a unified event stream that delivers various node events
+	// as they occur, including invoice updates, peer changes, channel
+	// state changes, and balance updates. Events are not persisted and
+	// will not be replayed if the stream is interrupted.
+	rpc StreamNodeEvents(NodeEventsRequest) returns (stream NodeEvent) {}
+
 	//////////////////////////////// HSM Messages ////////////////////////
 	//
 	// The following messages are related to communicating HSM
@@ -113,9 +120,6 @@ message Amount {
 	}
 }
 
-// Options to stream_incoming to specify what to stream.
-message StreamIncomingFilter {
-}
 
 message TlvField {
 	uint64 type = 1;
@@ -243,3 +247,38 @@ message LspInvoiceResponse {
   bytes payment_hash = 4;
   bytes payment_secret = 5;
 }
+
+// Request for streaming node events. Currently empty but defined as
+// its own message type to allow adding filters in the future (e.g.,
+// filter by event type, invoice label, etc.)
+message NodeEventsRequest {
+}
+
+// A real-time event from the node. Uses oneof to discriminate between
+// different event types.
+message NodeEvent {
+  oneof event {
+    InvoicePaid invoice_paid = 1;
+    // Future event types:
+    // PeerConnected peer_connected = 2;
+    // PeerDisconnected peer_disconnected = 3;
+    // ChannelStateChanged channel_state_changed = 4;
+    // BalanceChanged balance_changed = 5;
+  }
+}
+
+// Event emitted when an invoice is paid.
+message InvoicePaid {
+  // The payment hash of the paid invoice.
+  bytes payment_hash = 1;
+  // The bolt11 invoice string.
+  string bolt11 = 2;
+  // The preimage that proves payment.
+  bytes preimage = 3;
+  // The label assigned to the invoice.
+  string label = 4;
+  // Amount received in millisatoshis.
+  uint64 amount_msat = 5;
+  // Extra TLV fields included in the payment.
+  repeated TlvField extratlvs = 6;
+}