feat: Add Offer wrapper for FFI bindings

Implement Offer struct in uniffi_types to provide a wrapper around LDK's Offer for cross-language bindings.

Modified payment handling in bolt12.rs to:
- Support both native and FFI-compatible types via type aliasing
- Implement conditional compilation for transparent FFI support
- Update payment functions to handle wrapped types

Added testing to verify that properties are preserved when wrapping/unwrapping between native and FFI types.

Author: alexanderwiederin

bindings/ldk_node.udl

@@ -736,6 +736,22 @@ interface Bolt11Invoice {
 	PublicKey recover_payee_pub_key();
 };
 
+[Enum]
+interface Amount {
+	Bitcoin(u64 amount_msats);
+	Currency(string iso4217_code, u64 amount);
+};
+
+interface Offer {
+    [Throws=NodeError, Name=from_str]
+    constructor([ByRef] string offer_str);
+    OfferId id();
+    boolean is_expired();
+    string? description();
+    string? issuer();
+    Amount? amount();
+};
+
 [Custom]
 typedef string Txid;
 
@@ -754,9 +770,6 @@ typedef string NodeId;
 [Custom]
 typedef string Address;
 
-[Custom]
-typedef string Offer;
-
 [Custom]
 typedef string Refund;
 

src/payment/bolt12.rs

@@ -19,7 +19,7 @@ use crate::types::ChannelManager;
 
 use lightning::ln::channelmanager::{PaymentId, Retry};
 use lightning::offers::invoice::Bolt12Invoice;
-use lightning::offers::offer::{Amount, Offer, Quantity};
+use lightning::offers::offer::{Amount, Offer as LdkOffer, Quantity};
 use lightning::offers::parse::Bolt12SemanticError;
 use lightning::offers::refund::Refund;
 use lightning::util::string::UntrustedString;
@@ -30,6 +30,28 @@ use std::num::NonZeroU64;
 use std::sync::{Arc, RwLock};
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
+#[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())
+}
 /// A payment handler allowing to create and pay [BOLT 12] offers and refunds.
 ///
 /// Should be retrieved by calling [`Node::bolt12_payment`].
@@ -61,6 +83,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 rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
@@ -162,6 +185,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 rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
@@ -256,11 +280,9 @@ impl Bolt12Payment {
 		}
 	}
 
-	/// Returns a payable offer that can be used to request and receive a payment of the amount
-	/// given.
-	pub fn receive(
+	pub(crate) fn receive_inner(
 		&self, amount_msat: u64, description: &str, expiry_secs: Option<u32>, quantity: Option<u64>,
-	) -> Result<Offer, Error> {
+	) -> Result<LdkOffer, Error> {
 		let absolute_expiry = expiry_secs.map(|secs| {
 			(SystemTime::now() + Duration::from_secs(secs as u64))
 				.duration_since(UNIX_EPOCH)
@@ -293,6 +315,15 @@ impl Bolt12Payment {
 		Ok(finalized_offer)
 	}
 
+	/// Returns a payable offer that can be used to request and receive a payment of the amount
+	/// given.
+	pub fn receive(
+		&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))
+	}
+
 	/// Returns a payable offer that can be used to request and receive a payment for which the
 	/// amount is to be determined by the user, also known as a "zero-amount" offer.
 	pub fn receive_variable_amount(
@@ -314,7 +345,7 @@ impl Bolt12Payment {
 			Error::OfferCreationFailed
 		})?;
 
-		Ok(offer)
+		Ok(maybe_wrap_offer(offer))
 	}
 
 	/// Requests a refund payment for the given [`Refund`].

src/payment/unified_qr.rs

@@ -13,7 +13,10 @@
 //! [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, Bolt11Payment, Bolt12Payment, OnchainPayment};
+use crate::payment::{
+	bolt11::maybe_wrap_invoice, bolt12::maybe_wrap_offer, Bolt11Payment, Bolt12Payment,
+	OnchainPayment,
+};
 use crate::Config;
 
 use lightning::ln::channelmanager::PaymentId;
@@ -90,14 +93,14 @@ impl UnifiedQrPayment {
 
 		let amount_msats = amount_sats * 1_000;
 
-		let bolt12_offer = match self.bolt12_payment.receive(amount_msats, description, None, None)
-		{
-			Ok(offer) => Some(offer),
-			Err(e) => {
-				log_error!(self.logger, "Failed to create offer: {}", e);
-				return Err(Error::OfferCreationFailed);
-			},
-		};
+		let bolt12_offer =
+			match self.bolt12_payment.receive_inner(amount_msats, description, None, None) {
+				Ok(offer) => Some(offer),
+				Err(e) => {
+					log_error!(self.logger, "Failed to create offer: {}", e);
+					return Err(Error::OfferCreationFailed);
+				},
+			};
 
 		let invoice_description = Bolt11InvoiceDescription::Direct(
 			Description::new(description.to_string()).map_err(|_| Error::InvoiceCreationFailed)?,
@@ -142,6 +145,7 @@ 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);
 			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),

src/uniffi_types.rs

@@ -26,7 +26,7 @@ pub use lightning::chain::channelmonitor::BalanceSource;
 pub use lightning::events::{ClosureReason, PaymentFailureReason};
 pub use lightning::ln::types::ChannelId;
 pub use lightning::offers::invoice::Bolt12Invoice;
-pub use lightning::offers::offer::{Offer, OfferId};
+pub use lightning::offers::offer::OfferId;
 pub use lightning::offers::refund::Refund;
 pub use lightning::routing::gossip::{NodeAlias, NodeId, RoutingFees};
 pub use lightning::util::string::UntrustedString;
@@ -57,6 +57,7 @@ use bitcoin::hashes::sha256::Hash as Sha256;
 use bitcoin::hashes::Hash;
 use bitcoin::secp256k1::PublicKey;
 use lightning::ln::channelmanager::PaymentId;
+use lightning::offers::offer::{Amount as LdkAmount, Offer as LdkOffer};
 use lightning::util::ser::Writeable;
 use lightning_invoice::{Bolt11Invoice as LdkBolt11Invoice, Bolt11InvoiceDescriptionRef};
 
@@ -113,15 +114,89 @@ impl UniffiCustomTypeConverter for Address {
 	}
 }
 
-impl UniffiCustomTypeConverter for Offer {
-	type Builtin = String;
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Amount {
+	Bitcoin { amount_msats: u64 },
+	Currency { iso4217_code: String, amount: u64 },
+}
+
+impl From<LdkAmount> for Amount {
+	fn from(ldk_amount: LdkAmount) -> Self {
+		match ldk_amount {
+			LdkAmount::Bitcoin { amount_msats } => Amount::Bitcoin { amount_msats },
+			LdkAmount::Currency { iso4217_code, amount } => Amount::Currency {
+				iso4217_code: iso4217_code.iter().map(|&b| b as char).collect(),
+				amount,
+			},
+		}
+	}
+}
 
-	fn into_custom(val: Self::Builtin) -> uniffi::Result<Self> {
-		Offer::from_str(&val).map_err(|_| Error::InvalidOffer.into())
+/// An `Offer` is a potentially long-lived proposal for payment of a good or service.
+///
+/// An offer is a precursor to an [`InvoiceRequest`]. A merchant publishes an offer from which a
+/// customer may request an [`Bolt12Invoice`] for a specific quantity and using an amount sufficient
+/// to cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`].
+///
+/// Offers may be denominated in currency other than bitcoin but are ultimately paid using the
+/// latter.
+///
+/// Through the use of [`BlindedMessagePath`]s, offers provide recipient privacy.
+///
+/// [`InvoiceRequest`]: lightning::offers::invoice_request::InvoiceRequest
+/// [`Bolt12Invoice`]: lightning::offers::invoice::Bolt12Invoice
+/// [`Offer`]: lightning::offers::Offer:amount
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Offer {
+	pub inner: LdkOffer,
+}
+
+impl Offer {
+	pub fn from_str(offer_str: &str) -> Result<Self, Error> {
+		offer_str.parse()
 	}
 
-	fn from_custom(obj: Self) -> Self::Builtin {
-		obj.to_string()
+	/// Returns the id of the offer.
+	pub fn id(&self) -> OfferId {
+		OfferId(self.inner.id().0)
+	}
+
+	/// Whether the offer has expired.
+	pub fn is_expired(&self) -> bool {
+		self.inner.is_expired()
+	}
+
+	/// The minimum amount required for a successful payment of a single item.
+	pub fn description(&self) -> Option<String> {
+		self.inner.description().map(|printable| printable.to_string())
+	}
+
+	/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
+	/// displayed to the user but with the caveat that it has not been verified in any way.
+	pub fn issuer(&self) -> Option<String> {
+		self.inner.issuer().map(|printable| printable.to_string())
+	}
+
+	/// The minimum amount required for a successful payment of a single item.
+	pub fn amount(&self) -> Option<Amount> {
+		self.inner.amount().map(|amount| amount.into())
+	}
+}
+
+impl std::str::FromStr for Offer {
+	type Err = Error;
+
+	fn from_str(offer_str: &str) -> Result<Self, Self::Err> {
+		offer_str
+			.parse::<LdkOffer>()
+			.map(|offer| Offer { inner: offer })
+			.map_err(|_| Error::InvalidOffer)
+	}
+}
+
+impl From<LdkOffer> for Offer {
+	fn from(offer: LdkOffer) -> Self {
+		Offer { inner: offer }
 	}
 }
 
@@ -658,6 +733,10 @@ impl UniffiCustomTypeConverter for DateTime {
 
 #[cfg(test)]
 mod tests {
+	use std::time::{SystemTime, UNIX_EPOCH};
+
+	use lightning::offers::offer::OfferBuilder;
+
 	use super::*;
 
 	fn create_test_invoice() -> (LdkBolt11Invoice, Bolt11Invoice) {
@@ -667,6 +746,27 @@ mod tests {
 		(ldk_invoice, wrapped_invoice)
 	}
 
+	fn create_test_offer() -> (LdkOffer, Offer) {
+		let pubkey = bitcoin::secp256k1::PublicKey::from_str(
+			"02eec7245d6b7d2ccb30380bfbe2a3648cd7a942653f5aa340edcea1f283686619",
+		)
+		.unwrap();
+
+		let expiry =
+			(SystemTime::now() + Duration::from_secs(3600)).duration_since(UNIX_EPOCH).unwrap();
+
+		let builder = OfferBuilder::new(pubkey)
+			.description("Test offer description".to_string())
+			.amount_msats(100_000)
+			.issuer("Offer issuer".to_string())
+			.absolute_expiry(expiry);
+
+		let ldk_offer = builder.build().unwrap();
+		let wrapped_offer = Offer::from(ldk_offer.clone());
+
+		(ldk_offer, wrapped_offer)
+	}
+
 	#[test]
 	fn test_invoice_description_conversion() {
 		let hash = "09d08d4865e8af9266f6cc7c0ae23a1d6bf868207cf8f7c5979b9f6ed850dfb0".to_string();
@@ -776,4 +876,57 @@ mod tests {
 			parsed_invoice.payment_hash().to_byte_array().to_vec()
 		);
 	}
+
+	#[test]
+	fn test_offer() {
+		let (ldk_offer, wrapped_offer) = create_test_offer();
+		match (ldk_offer.description(), wrapped_offer.description()) {
+			(Some(ldk_desc), Some(wrapped_desc)) => {
+				assert_eq!(ldk_desc.to_string(), wrapped_desc);
+			},
+			(None, None) => {
+				panic!("Both offers unexpectedly had no description!");
+			},
+			(Some(_), None) => {
+				panic!("LDK offer had a description but wrapped offer did not!");
+			},
+			(None, Some(_)) => {
+				panic!("Wrapped offer had a description but LDK offer did not!");
+			},
+		}
+
+		match (ldk_offer.amount(), wrapped_offer.amount()) {
+			(Some(ldk_amount), Some(wrapped_amount)) => {
+				let ldk_amount: Amount = ldk_amount.into();
+				assert_eq!(ldk_amount, wrapped_amount);
+			},
+			(None, None) => {
+				panic!("Both offers unexpectedly had no description!");
+			},
+			(Some(_), None) => {
+				panic!("LDK offer had an amount but wrapped offer did not!");
+			},
+			(None, Some(_)) => {
+				panic!("Wrapped offer had an amount but LDK offer did not!");
+			},
+		}
+
+		match (ldk_offer.issuer(), wrapped_offer.issuer()) {
+			(Some(ldk_issuer), Some(wrapped_issuer)) => {
+				assert_eq!(ldk_issuer.to_string(), wrapped_issuer);
+			},
+			(None, None) => {
+				panic!("Both offers unexpectedly had no issuer!");
+			},
+			(Some(_), None) => {
+				panic!("LDK offer had an issuer but wrapped offer did not!");
+			},
+			(None, Some(_)) => {
+				panic!("Wrapped offer had an issuer but LDK offer did not!");
+			},
+		}
+
+		assert_eq!(ldk_offer.is_expired(), wrapped_offer.is_expired());
+		assert_eq!(ldk_offer.id(), wrapped_offer.id());
+	}
 }