feat: Add UniffiType trait for Lightning type conversions

Implement UniffiType trait to standardize conversion between native LDK types and their FFI-compatible wrappers.

Enhanced uniffi_conversions module to:
- Add a generic trait-based approach to type conversions
- Support all wrapped Lightning types (Offer, Refund, Bolt11Invoice, Bolt12Invoice, Bolt11InvoiceDescription)
- Provide consistent maybe_convert and maybe_wrap utilities for conditional compilation
- Ensure correct type handling with compile-time feature flags

Designed for maintainability and consistency when adding new FFI type wrappers in the future.

Author: alexanderwiederin

src/lib.rs

@@ -95,6 +95,7 @@ mod peer_store;
 mod sweep;
 mod tx_broadcaster;
 mod types;
+mod uniffi_conversions;
 #[cfg(feature = "uniffi")]
 mod uniffi_types;
 mod wallet;

src/payment/bolt11.rs

@@ -21,6 +21,7 @@ use crate::payment::store::{
 use crate::payment::SendingParameters;
 use crate::peer_store::{PeerInfo, PeerStore};
 use crate::types::ChannelManager;
+use crate::uniffi_conversions::{maybe_convert, maybe_wrap};
 
 use lightning::ln::bolt11_payment;
 use lightning::ln::channelmanager::{
@@ -43,42 +44,11 @@ type Bolt11Invoice = LdkBolt11Invoice;
 #[cfg(feature = "uniffi")]
 type Bolt11Invoice = Arc<crate::uniffi_types::Bolt11Invoice>;
 
-#[cfg(not(feature = "uniffi"))]
-pub(crate) fn maybe_wrap_invoice(invoice: LdkBolt11Invoice) -> Bolt11Invoice {
-	invoice
-}
-#[cfg(feature = "uniffi")]
-pub(crate) fn maybe_wrap_invoice(invoice: LdkBolt11Invoice) -> Bolt11Invoice {
-	Arc::new(invoice.into())
-}
-
-#[cfg(not(feature = "uniffi"))]
-pub fn maybe_convert_invoice(invoice: &Bolt11Invoice) -> &LdkBolt11Invoice {
-	invoice
-}
-#[cfg(feature = "uniffi")]
-pub fn maybe_convert_invoice(invoice: &Bolt11Invoice) -> &LdkBolt11Invoice {
-	&invoice.inner
-}
-
 #[cfg(not(feature = "uniffi"))]
 type Bolt11InvoiceDescription = LdkBolt11InvoiceDescription;
 #[cfg(feature = "uniffi")]
 type Bolt11InvoiceDescription = crate::uniffi_types::Bolt11InvoiceDescription;
 
-macro_rules! maybe_convert_description {
-	($description: expr) => {{
-		#[cfg(not(feature = "uniffi"))]
-		{
-			$description
-		}
-		#[cfg(feature = "uniffi")]
-		{
-			&LdkBolt11InvoiceDescription::try_from($description)?
-		}
-	}};
-}
-
 /// A payment handler allowing to create and pay [BOLT 11] invoices.
 ///
 /// Should be retrieved by calling [`Node::bolt11_payment`].
@@ -124,7 +94,7 @@ impl Bolt11Payment {
 	pub fn send(
 		&self, invoice: &Bolt11Invoice, sending_parameters: Option<SendingParameters>,
 	) -> Result<PaymentId, Error> {
-		let invoice = maybe_convert_invoice(invoice);
+		let invoice = maybe_convert(invoice);
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
@@ -233,7 +203,7 @@ impl Bolt11Payment {
 		&self, invoice: &Bolt11Invoice, amount_msat: u64,
 		sending_parameters: Option<SendingParameters>,
 	) -> Result<PaymentId, Error> {
-		let invoice = maybe_convert_invoice(invoice);
+		let invoice = maybe_convert(invoice);
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
@@ -465,9 +435,9 @@ impl Bolt11Payment {
 	pub fn receive(
 		&self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32,
 	) -> Result<Bolt11Invoice, Error> {
-		let description = maybe_convert_description!(description);
-		let invoice = self.receive_inner(Some(amount_msat), description, expiry_secs, None)?;
-		Ok(maybe_wrap_invoice(invoice))
+		let description = maybe_convert(description);
+		let invoice = self.receive_inner(Some(amount_msat), &description, expiry_secs, None)?;
+		Ok(maybe_wrap(invoice))
 	}
 
 	/// Returns a payable invoice that can be used to request a payment of the amount
@@ -488,10 +458,10 @@ impl Bolt11Payment {
 		&self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32,
 		payment_hash: PaymentHash,
 	) -> Result<Bolt11Invoice, Error> {
-		let description = maybe_convert_description!(description);
+		let description = maybe_convert(description);
 		let invoice =
-			self.receive_inner(Some(amount_msat), description, expiry_secs, Some(payment_hash))?;
-		Ok(maybe_wrap_invoice(invoice))
+			self.receive_inner(Some(amount_msat), &description, expiry_secs, Some(payment_hash))?;
+		Ok(maybe_wrap(invoice))
 	}
 
 	/// Returns a payable invoice that can be used to request and receive a payment for which the
@@ -501,9 +471,9 @@ impl Bolt11Payment {
 	pub fn receive_variable_amount(
 		&self, description: &Bolt11InvoiceDescription, expiry_secs: u32,
 	) -> Result<Bolt11Invoice, Error> {
-		let description = maybe_convert_description!(description);
-		let invoice = self.receive_inner(None, description, expiry_secs, None)?;
-		Ok(maybe_wrap_invoice(invoice))
+		let description = maybe_convert(description);
+		let invoice = self.receive_inner(None, &description, expiry_secs, None)?;
+		Ok(maybe_wrap(invoice))
 	}
 
 	/// Returns a payable invoice that can be used to request a payment for the given payment hash
@@ -523,9 +493,9 @@ impl Bolt11Payment {
 	pub fn receive_variable_amount_for_hash(
 		&self, description: &Bolt11InvoiceDescription, expiry_secs: u32, payment_hash: PaymentHash,
 	) -> Result<Bolt11Invoice, Error> {
-		let description = maybe_convert_description!(description);
-		let invoice = self.receive_inner(None, description, expiry_secs, Some(payment_hash))?;
-		Ok(maybe_wrap_invoice(invoice))
+		let description = maybe_convert(description);
+		let invoice = self.receive_inner(None, &description, expiry_secs, Some(payment_hash))?;
+		Ok(maybe_wrap(invoice))
 	}
 
 	pub(crate) fn receive_inner(
@@ -600,15 +570,15 @@ impl Bolt11Payment {
 		&self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32,
 		max_total_lsp_fee_limit_msat: Option<u64>,
 	) -> Result<Bolt11Invoice, Error> {
-		let description = maybe_convert_description!(description);
+		let description = maybe_convert(description);
 		let invoice = self.receive_via_jit_channel_inner(
 			Some(amount_msat),
-			description,
+			&description,
 			expiry_secs,
 			max_total_lsp_fee_limit_msat,
 			None,
 		)?;
-		Ok(maybe_wrap_invoice(invoice))
+		Ok(maybe_wrap(invoice))
 	}
 
 	/// Returns a payable invoice that can be used to request a variable amount payment (also known
@@ -626,15 +596,15 @@ impl Bolt11Payment {
 		&self, description: &Bolt11InvoiceDescription, expiry_secs: u32,
 		max_proportional_lsp_fee_limit_ppm_msat: Option<u64>,
 	) -> Result<Bolt11Invoice, Error> {
-		let description = maybe_convert_description!(description);
+		let description = maybe_convert(description);
 		let invoice = self.receive_via_jit_channel_inner(
 			None,
-			description,
+			&description,
 			expiry_secs,
 			None,
 			max_proportional_lsp_fee_limit_ppm_msat,
 		)?;
-		Ok(maybe_wrap_invoice(invoice))
+		Ok(maybe_wrap(invoice))
 	}
 
 	fn receive_via_jit_channel_inner(
@@ -741,7 +711,7 @@ impl Bolt11Payment {
 	/// amount times [`Config::probing_liquidity_limit_multiplier`] won't be used to send
 	/// pre-flight probes.
 	pub fn send_probes(&self, invoice: &Bolt11Invoice) -> Result<(), Error> {
-		let invoice = maybe_convert_invoice(invoice);
+		let invoice = maybe_convert(invoice);
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
@@ -774,7 +744,7 @@ impl Bolt11Payment {
 	pub fn send_probes_using_amount(
 		&self, invoice: &Bolt11Invoice, amount_msat: u64,
 	) -> Result<(), Error> {
-		let invoice = maybe_convert_invoice(invoice);
+		let invoice = maybe_convert(invoice);
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);

src/payment/bolt12.rs

@@ -16,12 +16,11 @@ use crate::payment::store::{
 	PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus, PaymentStore,
 };
 use crate::types::ChannelManager;
+use crate::uniffi_conversions::{maybe_convert, maybe_wrap};
 
 use lightning::ln::channelmanager::{PaymentId, Retry};
-use lightning::offers::invoice::Bolt12Invoice as LdkBolt12Invoice;
 use lightning::offers::offer::{Amount, Offer as LdkOffer, Quantity};
 use lightning::offers::parse::Bolt12SemanticError;
-use lightning::offers::refund::Refund as LdkRefund;
 use lightning::util::string::UntrustedString;
 
 use rand::RngCore;
@@ -31,65 +30,20 @@ use std::sync::{Arc, RwLock};
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 #[cfg(not(feature = "uniffi"))]
-type Bolt12Invoice = LdkBolt12Invoice;
+type Bolt12Invoice = lightning::offers::invoice::Bolt12Invoice;
 #[cfg(feature = "uniffi")]
 type Bolt12Invoice = Arc<crate::uniffi_types::Bolt12Invoice>;
 
-#[cfg(not(feature = "uniffi"))]
-fn maybe_wrap_bolt12_invoice(invoice: LdkBolt12Invoice) -> Bolt12Invoice {
-	invoice
-}
-#[cfg(feature = "uniffi")]
-fn maybe_wrap_bolt12_invoice(invoice: LdkBolt12Invoice) -> Bolt12Invoice {
-	Arc::new(invoice.into())
-}
-
 #[cfg(not(feature = "uniffi"))]
 type Offer = LdkOffer;
 #[cfg(feature = "uniffi")]
 type Offer = Arc<crate::uniffi_types::Offer>;
 
 #[cfg(not(feature = "uniffi"))]
-pub fn maybe_convert_offer(offer: &Offer) -> &LdkOffer {
-	offer
-}
-#[cfg(feature = "uniffi")]
-pub fn maybe_convert_offer(offer: &Offer) -> &LdkOffer {
-	&offer.inner
-}
-
-#[cfg(not(feature = "uniffi"))]
-pub fn maybe_wrap_offer(offer: LdkOffer) -> Offer {
-	offer
-}
-#[cfg(feature = "uniffi")]
-pub fn maybe_wrap_offer(offer: LdkOffer) -> Offer {
-	Arc::new(offer.into())
-}
-
-#[cfg(not(feature = "uniffi"))]
-type Refund = LdkRefund;
+type Refund = lightning::offers::refund::Refund;
 #[cfg(feature = "uniffi")]
 type Refund = Arc<crate::uniffi_types::Refund>;
 
-#[cfg(not(feature = "uniffi"))]
-pub fn maybe_convert_refund(refund: &Refund) -> &LdkRefund {
-	refund
-}
-#[cfg(feature = "uniffi")]
-pub fn maybe_convert_refund(refund: &Refund) -> &LdkRefund {
-	&refund.inner
-}
-
-#[cfg(not(feature = "uniffi"))]
-pub fn maybe_wrap_refund(refund: Refund) -> LdkRefund {
-	refund
-}
-#[cfg(feature = "uniffi")]
-pub fn maybe_wrap_refund(refund: LdkRefund) -> Refund {
-	Arc::new(refund.into())
-}
-
 /// A payment handler allowing to create and pay [BOLT 12] offers and refunds.
 ///
 /// Should be retrieved by calling [`Node::bolt12_payment`].
@@ -121,7 +75,7 @@ impl Bolt12Payment {
 	pub fn send(
 		&self, offer: &Offer, quantity: Option<u64>, payer_note: Option<String>,
 	) -> Result<PaymentId, Error> {
-		let offer = maybe_convert_offer(offer);
+		let offer = maybe_convert(offer);
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
@@ -223,7 +177,7 @@ impl Bolt12Payment {
 	pub fn send_using_amount(
 		&self, offer: &Offer, amount_msat: u64, quantity: Option<u64>, payer_note: Option<String>,
 	) -> Result<PaymentId, Error> {
-		let offer = maybe_convert_offer(offer);
+		let offer = maybe_convert(offer);
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
@@ -359,7 +313,7 @@ impl Bolt12Payment {
 		&self, amount_msat: u64, description: &str, expiry_secs: Option<u32>, quantity: Option<u64>,
 	) -> Result<Offer, Error> {
 		let offer = self.receive_inner(amount_msat, description, expiry_secs, quantity)?;
-		Ok(maybe_wrap_offer(offer))
+		Ok(maybe_wrap(offer))
 	}
 
 	/// Returns a payable offer that can be used to request and receive a payment for which the
@@ -383,7 +337,7 @@ impl Bolt12Payment {
 			Error::OfferCreationFailed
 		})?;
 
-		Ok(maybe_wrap_offer(offer))
+		Ok(maybe_wrap(offer))
 	}
 
 	/// Requests a refund payment for the given [`Refund`].
@@ -394,8 +348,8 @@ impl Bolt12Payment {
 	/// [`Refund`]: lightning::offers::refund::Refund
 	/// [`Bolt12Invoice`]: lightning::offers::invoice::Bolt12Invoice
 	pub fn request_refund_payment(&self, refund: &Refund) -> Result<Bolt12Invoice, Error> {
-		let refund = maybe_convert_refund(refund);
-		let invoice = self.channel_manager.request_refund_payment(refund).map_err(|e| {
+		let refund = maybe_convert(refund);
+		let invoice = self.channel_manager.request_refund_payment(&refund).map_err(|e| {
 			log_error!(self.logger, "Failed to request refund payment: {:?}", e);
 			Error::InvoiceRequestCreationFailed
 		})?;
@@ -422,7 +376,7 @@ impl Bolt12Payment {
 
 		self.payment_store.insert(payment)?;
 
-		Ok(maybe_wrap_bolt12_invoice(invoice))
+		Ok(maybe_wrap(invoice))
 	}
 
 	/// Returns a [`Refund`] object that can be used to offer a refund payment of the amount given.
@@ -489,6 +443,6 @@ impl Bolt12Payment {
 
 		self.payment_store.insert(payment)?;
 
-		Ok(maybe_wrap_refund(refund))
+		Ok(maybe_wrap(refund))
 	}
 }

src/payment/unified_qr.rs

@@ -13,10 +13,8 @@
 //! [BOLT 12]: https://github.com/lightning/bolts/blob/master/12-offer-encoding.md
 use crate::error::Error;
 use crate::logger::{log_error, LdkLogger, Logger};
-use crate::payment::{
-	bolt11::maybe_wrap_invoice, bolt12::maybe_wrap_offer, Bolt11Payment, Bolt12Payment,
-	OnchainPayment,
-};
+use crate::payment::{Bolt11Payment, Bolt12Payment, OnchainPayment};
+use crate::uniffi_conversions::maybe_wrap;
 use crate::Config;
 
 use lightning::ln::channelmanager::PaymentId;
@@ -145,15 +143,15 @@ impl UnifiedQrPayment {
 			uri.clone().require_network(self.config.network).map_err(|_| Error::InvalidNetwork)?;
 
 		if let Some(offer) = uri_network_checked.extras.bolt12_offer {
-			let offer = maybe_wrap_offer(offer);
+			let offer = maybe_wrap(offer);
 			match self.bolt12_payment.send(&offer, None, None) {
 				Ok(payment_id) => return Ok(QrPaymentResult::Bolt12 { payment_id }),
 				Err(e) => log_error!(self.logger, "Failed to send BOLT12 offer: {:?}. This is part of a unified QR code payment. Falling back to the BOLT11 invoice.", e),
 			}
 		}
 
 		if let Some(invoice) = uri_network_checked.extras.bolt11_invoice {
-			let invoice = maybe_wrap_invoice(invoice);
+			let invoice = maybe_wrap(invoice);
 			match self.bolt11_invoice.send(&invoice, None) {
 				Ok(payment_id) => return Ok(QrPaymentResult::Bolt11 { payment_id }),
 				Err(e) => log_error!(self.logger, "Failed to send BOLT11 invoice: {:?}. This is part of a unified QR code payment. Falling back to the on-chain transaction.", e),