feat: channel events

Author: anon

docs/api-guide.md

@@ -188,7 +188,7 @@ See [Pagination](#pagination) below for how to page through results.
 
 | RPC               | Description                                                 |
 |-------------------|-------------------------------------------------------------|
-| `SubscribeEvents` | **Server-streaming.** Subscribe to real-time payment events |
+| `SubscribeEvents` | **Server-streaming.** Subscribe to real-time payment and channel events |
 
 `SubscribeEvents` returns a stream of `EventEnvelope` messages. Each envelope contains one of:
 
@@ -199,6 +199,7 @@ See [Pagination](#pagination) below for how to page through results.
 | `PaymentFailed`     | An outbound payment failed                                            |
 | `PaymentClaimable`  | A hodl invoice payment arrived and is waiting to be claimed or failed |
 | `PaymentForwarded`  | A payment was routed through this node                                |
+| `ChannelStateChanged` | A channel changed state (pending, ready, open failed, closed)      |
 
 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.

ldk-server-client/README.md

@@ -34,7 +34,7 @@ The client handles HMAC-SHA256 authentication automatically. Pass the hex-encode
 
 ## Event Streaming
 
-Subscribe to real-time payment events:
+Subscribe to real-time payment and channel events:
 
 ```rust,no_run
 # use ldk_server_client::client::LdkServerClient;
@@ -52,6 +52,39 @@ while let Some(result) = stream.next_message().await {
 # }
 ```
 
+Pattern-match channel state changes:
+
+```rust,no_run
+# use ldk_server_client::client::LdkServerClient;
+# use ldk_server_client::ldk_server_grpc::events::{event_envelope, ChannelState};
+# #[tokio::main]
+# async fn main() {
+# let cert_pem = std::fs::read("/path/to/tls.crt").unwrap();
+# let client = LdkServerClient::new("localhost:3536".to_string(), "key".to_string(), &cert_pem).unwrap();
+let mut stream = client.subscribe_events().await.unwrap();
+while let Some(result) = stream.next_message().await {
+    match result {
+        Ok(event) => {
+            if let Some(event_envelope::Event::ChannelStateChanged(channel_event)) = event.event {
+                let state = ChannelState::from_i32(channel_event.state)
+                    .unwrap_or(ChannelState::Unspecified);
+                println!(
+                    "channel {} -> {}",
+                    channel_event.channel_id,
+                    state.as_str_name()
+                );
+
+                if let Some(reason) = channel_event.reason {
+                    println!("reason: {}", reason.message);
+                }
+            }
+        }
+        Err(e) => eprintln!("Error: {}", e),
+    }
+}
+# }
+```
+
 ## Features
 
 - **`serde`**: Enables `serde::Serialize` and `serde::Deserialize` on all proto types

ldk-server-grpc/src/events.rs

@@ -13,7 +13,7 @@
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct EventEnvelope {
-	#[prost(oneof = "event_envelope::Event", tags = "2, 3, 4, 6, 7")]
+	#[prost(oneof = "event_envelope::Event", tags = "2, 3, 4, 6, 7, 8")]
 	pub event: ::core::option::Option<event_envelope::Event>,
 }
 /// Nested message and enum types in `EventEnvelope`.
@@ -33,8 +33,105 @@ pub mod event_envelope {
 		PaymentForwarded(super::PaymentForwarded),
 		#[prost(message, tag = "7")]
 		PaymentClaimable(super::PaymentClaimable),
+		#[prost(message, tag = "8")]
+		ChannelStateChanged(super::ChannelStateChanged),
 	}
 }
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct CounterpartyForceClosedDetails {
+	#[prost(string, tag = "1")]
+	pub peer_msg: ::prost::alloc::string::String,
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct HolderForceClosedDetails {
+	#[prost(bool, optional, tag = "1")]
+	pub broadcasted_latest_txn: ::core::option::Option<bool>,
+	#[prost(string, tag = "2")]
+	pub message: ::prost::alloc::string::String,
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct ProcessingErrorDetails {
+	#[prost(string, tag = "1")]
+	pub err: ::prost::alloc::string::String,
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct HtlcsTimedOutDetails {
+	#[prost(string, optional, tag = "1")]
+	pub payment_hash: ::core::option::Option<::prost::alloc::string::String>,
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct PeerFeerateTooLowDetails {
+	#[prost(uint32, tag = "1")]
+	pub peer_feerate_sat_per_kw: u32,
+	#[prost(uint32, tag = "2")]
+	pub required_feerate_sat_per_kw: u32,
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct ChannelStateChangeReason {
+	#[prost(enumeration = "ChannelStateChangeReasonKind", tag = "1")]
+	pub kind: i32,
+	#[prost(string, tag = "2")]
+	pub message: ::prost::alloc::string::String,
+	#[prost(oneof = "channel_state_change_reason::Details", tags = "3, 4, 5, 6, 7")]
+	pub details: ::core::option::Option<channel_state_change_reason::Details>,
+}
+/// Nested message and enum types in `ChannelStateChangeReason`.
+pub mod channel_state_change_reason {
+	#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+	#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+	#[allow(clippy::derive_partial_eq_without_eq)]
+	#[derive(Clone, PartialEq, ::prost::Oneof)]
+	pub enum Details {
+		#[prost(message, tag = "3")]
+		CounterpartyForceClosed(super::CounterpartyForceClosedDetails),
+		#[prost(message, tag = "4")]
+		HolderForceClosed(super::HolderForceClosedDetails),
+		#[prost(message, tag = "5")]
+		ProcessingError(super::ProcessingErrorDetails),
+		#[prost(message, tag = "6")]
+		HtlcsTimedOut(super::HtlcsTimedOutDetails),
+		#[prost(message, tag = "7")]
+		PeerFeerateTooLow(super::PeerFeerateTooLowDetails),
+	}
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct ChannelStateChanged {
+	#[prost(string, tag = "1")]
+	pub channel_id: ::prost::alloc::string::String,
+	#[prost(string, tag = "2")]
+	pub user_channel_id: ::prost::alloc::string::String,
+	#[prost(string, optional, tag = "3")]
+	pub counterparty_node_id: ::core::option::Option<::prost::alloc::string::String>,
+	#[prost(enumeration = "ChannelState", tag = "4")]
+	pub state: i32,
+	#[prost(string, optional, tag = "5")]
+	pub funding_txo: ::core::option::Option<::prost::alloc::string::String>,
+	#[prost(message, optional, tag = "6")]
+	pub reason: ::core::option::Option<ChannelStateChangeReason>,
+	#[prost(enumeration = "ChannelClosureInitiator", tag = "7")]
+	pub closure_initiator: i32,
+}
 /// PaymentReceived indicates a payment has been received.
 #[cfg_attr(feature = "serde", derive(serde::Serialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
@@ -85,3 +182,196 @@ pub struct PaymentForwarded {
 	#[prost(message, optional, tag = "1")]
 	pub forwarded_payment: ::core::option::Option<super::types::ForwardedPayment>,
 }
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
+#[repr(i32)]
+pub enum ChannelState {
+	Unspecified = 0,
+	Pending = 1,
+	Ready = 2,
+	OpenFailed = 3,
+	Closed = 4,
+}
+impl ChannelState {
+	/// String value of the enum field names used in the ProtoBuf definition.
+	///
+	/// The values are not transformed in any way and thus are considered stable
+	/// (if the ProtoBuf definition does not change) and safe for programmatic use.
+	pub fn as_str_name(&self) -> &'static str {
+		match self {
+			ChannelState::Unspecified => "CHANNEL_STATE_UNSPECIFIED",
+			ChannelState::Pending => "CHANNEL_STATE_PENDING",
+			ChannelState::Ready => "CHANNEL_STATE_READY",
+			ChannelState::OpenFailed => "CHANNEL_STATE_OPEN_FAILED",
+			ChannelState::Closed => "CHANNEL_STATE_CLOSED",
+		}
+	}
+	/// Creates an enum from field names used in the ProtoBuf definition.
+	pub fn from_str_name(value: &str) -> ::core::option::Option<Self> {
+		match value {
+			"CHANNEL_STATE_UNSPECIFIED" => Some(Self::Unspecified),
+			"CHANNEL_STATE_PENDING" => Some(Self::Pending),
+			"CHANNEL_STATE_READY" => Some(Self::Ready),
+			"CHANNEL_STATE_OPEN_FAILED" => Some(Self::OpenFailed),
+			"CHANNEL_STATE_CLOSED" => Some(Self::Closed),
+			_ => None,
+		}
+	}
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
+#[repr(i32)]
+pub enum ChannelClosureInitiator {
+	Unspecified = 0,
+	Local = 1,
+	Remote = 2,
+	Unknown = 3,
+}
+impl ChannelClosureInitiator {
+	/// String value of the enum field names used in the ProtoBuf definition.
+	///
+	/// The values are not transformed in any way and thus are considered stable
+	/// (if the ProtoBuf definition does not change) and safe for programmatic use.
+	pub fn as_str_name(&self) -> &'static str {
+		match self {
+			ChannelClosureInitiator::Unspecified => "CHANNEL_CLOSURE_INITIATOR_UNSPECIFIED",
+			ChannelClosureInitiator::Local => "CHANNEL_CLOSURE_INITIATOR_LOCAL",
+			ChannelClosureInitiator::Remote => "CHANNEL_CLOSURE_INITIATOR_REMOTE",
+			ChannelClosureInitiator::Unknown => "CHANNEL_CLOSURE_INITIATOR_UNKNOWN",
+		}
+	}
+	/// Creates an enum from field names used in the ProtoBuf definition.
+	pub fn from_str_name(value: &str) -> ::core::option::Option<Self> {
+		match value {
+			"CHANNEL_CLOSURE_INITIATOR_UNSPECIFIED" => Some(Self::Unspecified),
+			"CHANNEL_CLOSURE_INITIATOR_LOCAL" => Some(Self::Local),
+			"CHANNEL_CLOSURE_INITIATOR_REMOTE" => Some(Self::Remote),
+			"CHANNEL_CLOSURE_INITIATOR_UNKNOWN" => Some(Self::Unknown),
+			_ => None,
+		}
+	}
+}
+#[cfg_attr(feature = "serde", derive(serde::Serialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
+#[repr(i32)]
+pub enum ChannelStateChangeReasonKind {
+	Unspecified = 0,
+	CounterpartyForceClosed = 1,
+	HolderForceClosed = 2,
+	LegacyCooperativeClosure = 3,
+	CounterpartyInitiatedCooperativeClosure = 4,
+	LocallyInitiatedCooperativeClosure = 5,
+	CommitmentTxConfirmed = 6,
+	FundingTimedOut = 7,
+	ProcessingError = 8,
+	DisconnectedPeer = 9,
+	OutdatedChannelManager = 10,
+	CounterpartyCoopClosedUnfundedChannel = 11,
+	LocallyCoopClosedUnfundedChannel = 12,
+	FundingBatchClosure = 13,
+	HtlcsTimedOut = 14,
+	PeerFeerateTooLow = 15,
+}
+impl ChannelStateChangeReasonKind {
+	/// String value of the enum field names used in the ProtoBuf definition.
+	///
+	/// The values are not transformed in any way and thus are considered stable
+	/// (if the ProtoBuf definition does not change) and safe for programmatic use.
+	pub fn as_str_name(&self) -> &'static str {
+		match self {
+			ChannelStateChangeReasonKind::Unspecified => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_UNSPECIFIED"
+			},
+			ChannelStateChangeReasonKind::CounterpartyForceClosed => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_COUNTERPARTY_FORCE_CLOSED"
+			},
+			ChannelStateChangeReasonKind::HolderForceClosed => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_HOLDER_FORCE_CLOSED"
+			},
+			ChannelStateChangeReasonKind::LegacyCooperativeClosure => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_LEGACY_COOPERATIVE_CLOSURE"
+			},
+			ChannelStateChangeReasonKind::CounterpartyInitiatedCooperativeClosure => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_COUNTERPARTY_INITIATED_COOPERATIVE_CLOSURE"
+			},
+			ChannelStateChangeReasonKind::LocallyInitiatedCooperativeClosure => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_LOCALLY_INITIATED_COOPERATIVE_CLOSURE"
+			},
+			ChannelStateChangeReasonKind::CommitmentTxConfirmed => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_COMMITMENT_TX_CONFIRMED"
+			},
+			ChannelStateChangeReasonKind::FundingTimedOut => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_FUNDING_TIMED_OUT"
+			},
+			ChannelStateChangeReasonKind::ProcessingError => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_PROCESSING_ERROR"
+			},
+			ChannelStateChangeReasonKind::DisconnectedPeer => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_DISCONNECTED_PEER"
+			},
+			ChannelStateChangeReasonKind::OutdatedChannelManager => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_OUTDATED_CHANNEL_MANAGER"
+			},
+			ChannelStateChangeReasonKind::CounterpartyCoopClosedUnfundedChannel => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_COUNTERPARTY_COOP_CLOSED_UNFUNDED_CHANNEL"
+			},
+			ChannelStateChangeReasonKind::LocallyCoopClosedUnfundedChannel => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_LOCALLY_COOP_CLOSED_UNFUNDED_CHANNEL"
+			},
+			ChannelStateChangeReasonKind::FundingBatchClosure => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_FUNDING_BATCH_CLOSURE"
+			},
+			ChannelStateChangeReasonKind::HtlcsTimedOut => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_HTLCS_TIMED_OUT"
+			},
+			ChannelStateChangeReasonKind::PeerFeerateTooLow => {
+				"CHANNEL_STATE_CHANGE_REASON_KIND_PEER_FEERATE_TOO_LOW"
+			},
+		}
+	}
+	/// Creates an enum from field names used in the ProtoBuf definition.
+	pub fn from_str_name(value: &str) -> ::core::option::Option<Self> {
+		match value {
+			"CHANNEL_STATE_CHANGE_REASON_KIND_UNSPECIFIED" => Some(Self::Unspecified),
+			"CHANNEL_STATE_CHANGE_REASON_KIND_COUNTERPARTY_FORCE_CLOSED" => {
+				Some(Self::CounterpartyForceClosed)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_HOLDER_FORCE_CLOSED" => Some(Self::HolderForceClosed),
+			"CHANNEL_STATE_CHANGE_REASON_KIND_LEGACY_COOPERATIVE_CLOSURE" => {
+				Some(Self::LegacyCooperativeClosure)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_COUNTERPARTY_INITIATED_COOPERATIVE_CLOSURE" => {
+				Some(Self::CounterpartyInitiatedCooperativeClosure)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_LOCALLY_INITIATED_COOPERATIVE_CLOSURE" => {
+				Some(Self::LocallyInitiatedCooperativeClosure)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_COMMITMENT_TX_CONFIRMED" => {
+				Some(Self::CommitmentTxConfirmed)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_FUNDING_TIMED_OUT" => Some(Self::FundingTimedOut),
+			"CHANNEL_STATE_CHANGE_REASON_KIND_PROCESSING_ERROR" => Some(Self::ProcessingError),
+			"CHANNEL_STATE_CHANGE_REASON_KIND_DISCONNECTED_PEER" => Some(Self::DisconnectedPeer),
+			"CHANNEL_STATE_CHANGE_REASON_KIND_OUTDATED_CHANNEL_MANAGER" => {
+				Some(Self::OutdatedChannelManager)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_COUNTERPARTY_COOP_CLOSED_UNFUNDED_CHANNEL" => {
+				Some(Self::CounterpartyCoopClosedUnfundedChannel)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_LOCALLY_COOP_CLOSED_UNFUNDED_CHANNEL" => {
+				Some(Self::LocallyCoopClosedUnfundedChannel)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_FUNDING_BATCH_CLOSURE" => {
+				Some(Self::FundingBatchClosure)
+			},
+			"CHANNEL_STATE_CHANGE_REASON_KIND_HTLCS_TIMED_OUT" => Some(Self::HtlcsTimedOut),
+			"CHANNEL_STATE_CHANGE_REASON_KIND_PEER_FEERATE_TOO_LOW" => {
+				Some(Self::PeerFeerateTooLow)
+			},
+			_ => None,
+		}
+	}
+}