Add proto definition for ListForwardedPayments API.

Author: G8XSU

ldk-server-protos/src/api.rs

@@ -337,6 +337,44 @@ pub struct ListPaymentsResponse {
 	#[prost(message, repeated, tag = "1")]
 	pub payments: ::prost::alloc::vec::Vec<super::types::Payment>,
 }
+/// Retrieves list of all forwarded payments.
+/// See more: <https://docs.rs/ldk-node/latest/ldk_node/enum.Event.html#variant.PaymentForwarded>
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct ListForwardedPaymentsRequest {
+	/// `page_token` is a pagination token.
+	///
+	/// To query for the first page, `page_token` must not be specified.
+	///
+	/// For subsequent pages, use the value that was returned as `next_page_token` in the previous
+	/// page's response.
+	#[prost(message, optional, tag = "1")]
+	pub page_token: ::core::option::Option<super::types::PageToken>,
+}
+/// The response `content` for the `ListForwardedPayments` API, when HttpStatusCode is OK (200).
+/// When HttpStatusCode is not OK (non-200), the response `content` contains a serialized `ErrorResponse`.
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct ListForwardedPaymentsResponse {
+	/// List of forwarded payments.
+	#[prost(message, repeated, tag = "1")]
+	pub forwarded_payments: ::prost::alloc::vec::Vec<super::types::ForwardedPayment>,
+	/// `next_page_token` is a pagination token, used to retrieve the next page of results.
+	/// Use this value to query for next-page of paginated operation, by specifying
+	/// this value as the `page_token` in the next request.
+	///
+	/// If `next_page_token` is `None`, then the "last page" of results has been processed and
+	/// there is no more data to be retrieved.
+	///
+	/// If `next_page_token` is not `None`, it does not necessarily mean that there is more data in the
+	/// result set. The only way to know when you have reached the end of the result set is when
+	/// `next_page_token` is `None`.
+	///
+	/// **Caution**: Clients must not assume a specific number of records to be present in a page for
+	/// paginated response.
+	#[prost(message, optional, tag = "2")]
+	pub next_page_token: ::core::option::Option<super::types::PageToken>,
+}
 /// Retrieves an overview of all known balances.
 /// See more: <https://docs.rs/ldk-node/latest/ldk_node/struct.Node.html#method.list_balances>
 #[allow(clippy::derive_partial_eq_without_eq)]

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

@@ -319,6 +319,40 @@ message ListPaymentsResponse {
   repeated types.Payment payments = 1;
 }
 
+// Retrieves list of all forwarded payments.
+// See more: https://docs.rs/ldk-node/latest/ldk_node/enum.Event.html#variant.PaymentForwarded
+message ListForwardedPaymentsRequest {
+  // `page_token` is a pagination token.
+  //
+  // To query for the first page, `page_token` must not be specified.
+  //
+  // For subsequent pages, use the value that was returned as `next_page_token` in the previous
+  // page's response.
+  optional types.PageToken page_token = 1;
+}
+
+// The response `content` for the `ListForwardedPayments` API, when HttpStatusCode is OK (200).
+// When HttpStatusCode is not OK (non-200), the response `content` contains a serialized `ErrorResponse`.
+message ListForwardedPaymentsResponse {
+  // List of forwarded payments.
+  repeated types.ForwardedPayment forwarded_payments = 1;
+
+  // `next_page_token` is a pagination token, used to retrieve the next page of results.
+  // Use this value to query for next-page of paginated operation, by specifying
+  // this value as the `page_token` in the next request.
+  //
+  // If `next_page_token` is `None`, then the "last page" of results has been processed and
+  // there is no more data to be retrieved.
+  //
+  // If `next_page_token` is not `None`, it does not necessarily mean that there is more data in the
+  // result set. The only way to know when you have reached the end of the result set is when
+  // `next_page_token` is `None`.
+  //
+  // **Caution**: Clients must not assume a specific number of records to be present in a page for
+  // paginated response.
+  optional types.PageToken next_page_token = 2;
+}
+
 // Retrieves an overview of all known balances.
 // See more: https://docs.rs/ldk-node/latest/ldk_node/struct.Node.html#method.list_balances
 message GetBalancesRequest {}

ldk-server-protos/src/proto/types.proto

@@ -161,6 +161,51 @@ enum PaymentStatus {
   FAILED = 2;
 }
 
+// A forwarded payment through our node.
+// See more: https://docs.rs/ldk-node/latest/ldk_node/enum.Event.html#variant.PaymentForwarded
+message ForwardedPayment{
+  // The channel id of the incoming channel between the previous node and us.
+  string prev_channel_id = 1;
+
+  // The channel id of the outgoing channel between the next node and us.
+  string next_channel_id = 2;
+
+  // The `user_channel_id` of the incoming channel between the previous node and us.
+  string prev_user_channel_id = 3;
+
+  // The `user_channel_id` of the outgoing channel between the next node and us.
+  // This will be `None` if the payment was settled via an on-chain transaction.
+  // See the caveat described for the `total_fee_earned_msat` field.
+  optional string next_user_channel_id = 4;
+
+  // The total fee, in milli-satoshis, which was earned as a result of the payment.
+  //
+  // Note that if we force-closed the channel over which we forwarded an HTLC while the HTLC was pending, the amount the
+  // next hop claimed will have been rounded down to the nearest whole satoshi. Thus, the fee calculated here may be
+  // higher than expected as we still claimed the full value in millisatoshis from the source.
+  // In this case, `claim_from_onchain_tx` will be set.
+  //
+  // If the channel which sent us the payment has been force-closed, we will claim the funds via an on-chain transaction.
+  // In that case we do not yet know the on-chain transaction fees which we will spend and will instead set this to `None`.
+  optional uint64 total_fee_earned_msat = 5;
+
+  // The share of the total fee, in milli-satoshis, which was withheld in addition to the forwarding fee.
+  // This will only be set if we forwarded an intercepted HTLC with less than the expected amount. This means our
+  // counterparty accepted to receive less than the invoice amount.
+  //
+  // The caveat described above the `total_fee_earned_msat` field applies here as well.
+  optional uint64 skimmed_fee_msat = 6;
+
+  // If this is true, the forwarded HTLC was claimed by our counterparty via an on-chain transaction.
+  bool claim_from_onchain_tx = 7;
+
+  // The final amount forwarded, in milli-satoshis, after the fee is deducted.
+  //
+  // The caveat described above the `total_fee_earned_msat` field applies here as well.
+  optional uint64 outbound_amount_forwarded_msat = 8;
+
+}
+
 message Channel {
   // The channel ID (prior to funding transaction generation, this is a random 32-byte
   // identifier, afterwards this is the transaction ID of the funding transaction XOR the
@@ -579,3 +624,9 @@ message AwaitingThresholdConfirmations {
   // The amount, in satoshis, of the output being swept.
   uint64 amount_satoshis = 5;
 }
+
+// Token used to determine start of next page in paginated APIs.
+message PageToken {
+  string token = 1;
+  int64 index = 2;
+}

ldk-server-protos/src/types.rs

@@ -165,6 +165,52 @@ pub struct LspFeeLimits {
 	#[prost(uint64, optional, tag = "2")]
 	pub max_proportional_opening_fee_ppm_msat: ::core::option::Option<u64>,
 }
+/// A forwarded payment through our node.
+/// See more: <https://docs.rs/ldk-node/latest/ldk_node/enum.Event.html#variant.PaymentForwarded>
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct ForwardedPayment {
+	/// The channel id of the incoming channel between the previous node and us.
+	#[prost(string, tag = "1")]
+	pub prev_channel_id: ::prost::alloc::string::String,
+	/// The channel id of the outgoing channel between the next node and us.
+	#[prost(string, tag = "2")]
+	pub next_channel_id: ::prost::alloc::string::String,
+	/// The `user_channel_id` of the incoming channel between the previous node and us.
+	#[prost(string, tag = "3")]
+	pub prev_user_channel_id: ::prost::alloc::string::String,
+	/// The `user_channel_id` of the outgoing channel between the next node and us.
+	/// This will be `None` if the payment was settled via an on-chain transaction.
+	/// See the caveat described for the `total_fee_earned_msat` field.
+	#[prost(string, optional, tag = "4")]
+	pub next_user_channel_id: ::core::option::Option<::prost::alloc::string::String>,
+	/// The total fee, in milli-satoshis, which was earned as a result of the payment.
+	///
+	/// Note that if we force-closed the channel over which we forwarded an HTLC while the HTLC was pending, the amount the
+	/// next hop claimed will have been rounded down to the nearest whole satoshi. Thus, the fee calculated here may be
+	/// higher than expected as we still claimed the full value in millisatoshis from the source.
+	/// In this case, `claim_from_onchain_tx` will be set.
+	///
+	/// If the channel which sent us the payment has been force-closed, we will claim the funds via an on-chain transaction.
+	/// In that case we do not yet know the on-chain transaction fees which we will spend and will instead set this to `None`.
+	#[prost(uint64, optional, tag = "5")]
+	pub total_fee_earned_msat: ::core::option::Option<u64>,
+	/// The share of the total fee, in milli-satoshis, which was withheld in addition to the forwarding fee.
+	/// This will only be set if we forwarded an intercepted HTLC with less than the expected amount. This means our
+	/// counterparty accepted to receive less than the invoice amount.
+	///
+	/// The caveat described above the `total_fee_earned_msat` field applies here as well.
+	#[prost(uint64, optional, tag = "6")]
+	pub skimmed_fee_msat: ::core::option::Option<u64>,
+	/// If this is true, the forwarded HTLC was claimed by our counterparty via an on-chain transaction.
+	#[prost(bool, tag = "7")]
+	pub claim_from_onchain_tx: bool,
+	/// The final amount forwarded, in milli-satoshis, after the fee is deducted.
+	///
+	/// The caveat described above the `total_fee_earned_msat` field applies here as well.
+	#[prost(uint64, optional, tag = "8")]
+	pub outbound_amount_forwarded_msat: ::core::option::Option<u64>,
+}
 #[allow(clippy::derive_partial_eq_without_eq)]
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Channel {
@@ -647,6 +693,15 @@ pub struct AwaitingThresholdConfirmations {
 	#[prost(uint64, tag = "5")]
 	pub amount_satoshis: u64,
 }
+/// Token used to determine start of next page in paginated APIs.
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct PageToken {
+	#[prost(string, tag = "1")]
+	pub token: ::prost::alloc::string::String,
+	#[prost(int64, tag = "2")]
+	pub index: i64,
+}
 /// Represents the direction of a payment.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
 #[repr(i32)]