Add event handling and other functions to ffi

Author: benthecarman

orange-sdk/src/ffi/orange/mod.rs

@@ -1,6 +1,8 @@
 use crate::bitcoin::hashes::Hash;
 use crate::ffi::bitcoin_payment_instructions::Amount;
-use crate::{PaymentId as OrangePaymentId, Transaction as OrangeTransaction};
+use crate::{
+	PaymentId as OrangePaymentId, Transaction as OrangeTransaction, event::Event as OrangeEvent,
+};
 use crate::{impl_from_core_type, impl_into_core_type};
 use std::sync::Arc;
 
@@ -153,3 +155,200 @@ impl From<crate::store::PaymentType> for PaymentType {
 		}
 	}
 }
+
+/// An event emitted by [`Wallet`], which should be handled by the user.
+///
+/// [`Wallet`]: [`crate::Wallet`]
+#[derive(Debug, Clone, Eq, PartialEq, uniffi::Enum)]
+pub enum Event {
+	/// An outgoing payment was successful.
+	PaymentSuccessful {
+		/// A local identifier used to track the payment.
+		payment_id: Arc<PaymentId>,
+		/// The hash of the payment.
+		payment_hash: Vec<u8>,
+		/// The preimage to the `payment_hash`.
+		///
+		/// Note that this serves as a payment receipt.
+		payment_preimage: Vec<u8>,
+		/// The total fee which was spent at intermediate hops in this payment.
+		fee_paid_msat: Option<u64>,
+	},
+	/// An outgoing payment has failed.
+	PaymentFailed {
+		/// A local identifier used to track the payment.
+		payment_id: Arc<PaymentId>,
+		/// The hash of the payment.
+		///
+		/// This will be `None` if the payment failed before receiving an invoice when paying a
+		/// BOLT12 [`Offer`].
+		///
+		/// [`Offer`]: ldk_node::lightning::offers::offer::Offer
+		payment_hash: Option<Vec<u8>>,
+		/// The reason why the payment failed.
+		///
+		/// Will be `None` if the failure reason is not known.
+		reason: Option<String>,
+	},
+	/// A payment has been received.
+	PaymentReceived {
+		/// A local identifier used to track the payment.
+		payment_id: Arc<PaymentId>,
+		/// The hash of the payment.
+		payment_hash: Vec<u8>,
+		/// The value, in msats, that has been received.
+		amount_msat: u64,
+		/// Custom TLV records received on the payment
+		custom_records: Vec<Vec<u8>>,
+		/// The value, in msats, that was skimmed off of this payment as an extra fee taken by LSP.
+		/// Typically, this is only present for payments that result in opening a channel.
+		lsp_fee_msats: Option<u64>,
+	},
+	/// A payment has been received.
+	OnchainPaymentReceived {
+		/// A local identifier used to track the payment.
+		payment_id: Arc<PaymentId>,
+		/// The transaction ID.
+		txid: Vec<u8>,
+		/// The value, in sats, that has been received.
+		amount_sat: u64,
+	},
+	/// A channel is ready to be used.
+	ChannelOpened {
+		/// The `channel_id` of the channel.
+		channel_id: Vec<u8>,
+		/// The `user_channel_id` of the channel.
+		user_channel_id: Vec<u8>,
+		/// The `node_id` of the channel counterparty.
+		counterparty_node_id: Vec<u8>,
+		/// The outpoint of the channel's funding transaction.
+		funding_txo: String,
+	},
+	/// A channel has been closed.
+	///
+	/// When a channel is closed, we will disable automatic rebalancing
+	/// so new channels will not be opened until it is explicitly enabled again.
+	ChannelClosed {
+		/// The `channel_id` of the channel.
+		channel_id: Vec<u8>,
+		/// The `user_channel_id` of the channel.
+		user_channel_id: Vec<u8>,
+		/// The `node_id` of the channel counterparty.
+		counterparty_node_id: Vec<u8>,
+		/// Why the channel was closed.
+		///
+		/// Will be `None` if the closure reason is not known.
+		reason: Option<String>,
+	},
+	/// A rebalance from our trusted wallet has been initiated.
+	RebalanceInitiated {
+		/// The `payment_id` of the transaction that triggered the rebalance.
+		trigger_payment_id: Arc<PaymentId>,
+		/// The `payment_id` of the rebalance payment sent from the trusted wallet.
+		trusted_rebalance_payment_id: Vec<u8>,
+		/// The amount, in msats, of the rebalance payment.
+		amount_msat: u64,
+	},
+	/// A rebalance from our trusted wallet was successful.
+	RebalanceSuccessful {
+		/// The `payment_id` of the transaction that triggered the rebalance.
+		trigger_payment_id: Arc<PaymentId>,
+		/// The `payment_id` of the rebalance payment sent from the trusted wallet.
+		trusted_rebalance_payment_id: Vec<u8>,
+		/// The `payment_id` of the rebalance payment sent to the LN wallet.
+		ln_rebalance_payment_id: Vec<u8>,
+		/// The amount, in msats, of the rebalance payment.
+		amount_msat: u64,
+		/// The fee paid, in msats, for the rebalance payment.
+		fee_msat: u64,
+	},
+}
+
+impl From<OrangeEvent> for Event {
+	fn from(value: OrangeEvent) -> Self {
+		match value {
+			OrangeEvent::PaymentSuccessful {
+				payment_id,
+				payment_hash,
+				payment_preimage,
+				fee_paid_msat,
+			} => Event::PaymentSuccessful {
+				payment_id: Arc::new(payment_id.into()),
+				payment_hash: payment_hash.0.to_vec(),
+				payment_preimage: payment_preimage.0.to_vec(),
+				fee_paid_msat,
+			},
+			OrangeEvent::PaymentFailed { payment_id, payment_hash, reason } => {
+				Event::PaymentFailed {
+					payment_id: Arc::new(payment_id.into()),
+					payment_hash: payment_hash.map(|h| h.0.to_vec()),
+					reason: reason.map(|r| format!("{:?}", r)),
+				}
+			},
+			OrangeEvent::PaymentReceived {
+				payment_id,
+				payment_hash,
+				amount_msat,
+				custom_records,
+				lsp_fee_msats,
+			} => Event::PaymentReceived {
+				payment_id: Arc::new(payment_id.into()),
+				payment_hash: payment_hash.0.to_vec(),
+				amount_msat,
+				custom_records: custom_records.into_iter().map(|r| r.value).collect(),
+				lsp_fee_msats,
+			},
+			OrangeEvent::OnchainPaymentReceived { payment_id, txid, amount_sat, status: _ } => {
+				Event::OnchainPaymentReceived {
+					payment_id: Arc::new(payment_id.into()),
+					txid: txid.to_byte_array().to_vec(),
+					amount_sat,
+				}
+			},
+			OrangeEvent::ChannelOpened {
+				channel_id,
+				user_channel_id,
+				counterparty_node_id,
+				funding_txo,
+			} => Event::ChannelOpened {
+				channel_id: channel_id.0.to_vec(),
+				user_channel_id: user_channel_id.0.to_be_bytes().to_vec(),
+				counterparty_node_id: counterparty_node_id.serialize().to_vec(),
+				funding_txo: funding_txo.to_string(),
+			},
+			OrangeEvent::ChannelClosed {
+				channel_id,
+				user_channel_id,
+				counterparty_node_id,
+				reason,
+			} => Event::ChannelClosed {
+				channel_id: channel_id.0.to_vec(),
+				user_channel_id: user_channel_id.0.to_be_bytes().to_vec(),
+				counterparty_node_id: counterparty_node_id.serialize().to_vec(),
+				reason: reason.map(|r| format!("{:?}", r)),
+			},
+			OrangeEvent::RebalanceInitiated {
+				trigger_payment_id,
+				trusted_rebalance_payment_id,
+				amount_msat,
+			} => Event::RebalanceInitiated {
+				trigger_payment_id: Arc::new(trigger_payment_id.into()),
+				trusted_rebalance_payment_id: trusted_rebalance_payment_id.to_vec(),
+				amount_msat,
+			},
+			OrangeEvent::RebalanceSuccessful {
+				trigger_payment_id,
+				trusted_rebalance_payment_id,
+				ln_rebalance_payment_id,
+				amount_msat,
+				fee_msat,
+			} => Event::RebalanceSuccessful {
+				trigger_payment_id: Arc::new(trigger_payment_id.into()),
+				trusted_rebalance_payment_id: trusted_rebalance_payment_id.to_vec(),
+				ln_rebalance_payment_id: ln_rebalance_payment_id.to_vec(),
+				amount_msat,
+				fee_msat,
+			},
+		}
+	}
+}

orange-sdk/src/ffi/orange/wallet.rs

@@ -1,13 +1,13 @@
 use crate::Balances as OrangeBalances;
-
 use crate::SingleUseReceiveUri as OrangeSingleUseReceiveUri;
 use crate::Wallet as OrangeWallet;
 use crate::WalletConfig as OrangeWalletConfig;
 use crate::ffi::bitcoin_payment_instructions::{
 	Amount, ParseError, PaymentInfo, PaymentInstructions,
 };
 use crate::ffi::ldk_node::ChannelDetails;
-use crate::ffi::orange::config::WalletConfig;
+use crate::ffi::orange::Event;
+use crate::ffi::orange::config::{Tunables, WalletConfig};
 use crate::ffi::orange::error::{InitFailure, WalletError};
 use crate::{impl_from_core_type, impl_into_core_type};
 use std::sync::Arc;
@@ -162,6 +162,17 @@ impl Wallet {
 		Ok(())
 	}
 
+	/// Estimates the fees required to pay using the provided PaymentInfo
+	///
+	/// This will estimate fees for the optimal payment method based on the current wallet state,
+	/// including whether the payment would be routed through the trusted wallet or lightning wallet.
+	pub async fn estimate_fee(
+		&self, payment_info: Arc<PaymentInfo>,
+	) -> Result<Arc<Amount>, WalletError> {
+		let fee = self.inner.estimate_fee(&payment_info.0.instructions).await;
+		Ok(Arc::new(fee.into()))
+	}
+
 	pub async fn stop(&self) {
 		self.inner.stop().await
 	}
@@ -177,4 +188,58 @@ impl Wallet {
 	pub fn list_channels(&self) -> Vec<Arc<ChannelDetails>> {
 		self.inner.channels().into_iter().map(|ch| Arc::new(ch.into())).collect()
 	}
+
+	/// List our current channels
+	pub fn close_channels(&self) -> Result<(), WalletError> {
+		self.inner.close_channels()?;
+		Ok(())
+	}
+
+	/// Returns the wallet's configured tunables.
+	pub fn get_tunables(&self) -> Arc<Tunables> {
+		Arc::new(self.inner.get_tunables().into())
+	}
+
+	/// Returns the next event in the event queue, if currently available.
+	///
+	/// Will return `Some(...)` if an event is available and `None` otherwise.
+	///
+	/// **Note:** this will always return the same event until handling is confirmed via [`crate::Wallet::event_handled`].
+	///
+	/// **Caution:** Users must handle events as quickly as possible to prevent a large event backlog,
+	/// which can increase the memory footprint of [`crate::Wallet`].
+	pub fn next_event(&self) -> Option<Event> {
+		self.inner.next_event().map(|e| e.into())
+	}
+
+	/// Returns the next event in the event queue.
+	///
+	/// Will asynchronously poll the event queue until the next event is ready.
+	///
+	/// **Note:** this will always return the same event until handling is confirmed via [`crate::Wallet::event_handled`].
+	///
+	/// **Caution:** Users must handle events as quickly as possible to prevent a large event backlog,
+	/// which can increase the memory footprint of [`crate::Wallet`].
+	pub async fn next_event_async(&self) -> Event {
+		self.inner.next_event_async().await.into()
+	}
+
+	/// Returns the next event in the event queue.
+	///
+	/// Will block the current thread until the next event is available.
+	///
+	/// **Note:** this will always return the same event until handling is confirmed via [`crate::Wallet::event_handled`].
+	///
+	/// **Caution:** Users must handle events as quickly as possible to prevent a large event backlog,
+	/// which can increase the memory footprint of [`crate::Wallet`].
+	pub fn wait_next_event(&self) -> Event {
+		self.inner.wait_next_event().into()
+	}
+
+	/// Confirm the last retrieved event handled. Returns true if successful.
+	///
+	/// **Note:** This **MUST** be called after each event has been handled.
+	pub fn event_handled(&self) -> bool {
+		self.inner.event_handled().is_ok()
+	}
 }

orange-sdk/src/lib.rs

@@ -1249,7 +1249,7 @@ impl Wallet {
 
 	/// Returns the next event in the event queue, if currently available.
 	///
-	/// Will return `Some(..)` if an event is available and `None` otherwise.
+	/// Will return `Some(...)` if an event is available and `None` otherwise.
 	///
 	/// **Note:** this will always return the same event until handling is confirmed via [`Wallet::event_handled`].
 	///