Expose payer_note in PaymentKind::Bolt12

bindings/ldk_node.udl

@@ -120,17 +120,17 @@ interface Bolt11Payment {
 
 interface Bolt12Payment {
  [Throws=NodeError]
- PaymentId send([ByRef]Offer offer, string? payer_note);
+ PaymentId send([ByRef]Offer offer, u64? quantity, string? payer_note);
  [Throws=NodeError]
- PaymentId send_using_amount([ByRef]Offer offer, string? payer_note, u64 amount_msat);
+ PaymentId send_using_amount([ByRef]Offer offer, u64 amount_msat, u64? quantity, string? payer_note);
  [Throws=NodeError]
- Offer receive(u64 amount_msat, [ByRef]string description);
+ Offer receive(u64 amount_msat, [ByRef]string description, u64? quantity);
  [Throws=NodeError]
  Offer receive_variable_amount([ByRef]string description);
  [Throws=NodeError]
  Bolt12Invoice request_refund_payment([ByRef]Refund refund);
  [Throws=NodeError]
- Refund initiate_refund(u64 amount_msat, u32 expiry_secs);
+ Refund initiate_refund(u64 amount_msat, u32 expiry_secs, u64? quantity, string? payer_note);
 };
 
 interface SpontaneousPayment {
@@ -201,6 +201,7 @@ enum NodeError {
  "InvalidChannelId",
  "InvalidNetwork",
  "InvalidUri",
+ "InvalidQuantity",
  "DuplicatePayment",
  "UnsupportedCurrency",
  "InsufficientFunds",
@@ -281,8 +282,8 @@ interface PaymentKind {
  Onchain();
  Bolt11(PaymentHash hash, PaymentPreimage? preimage, PaymentSecret? secret);
  Bolt11Jit(PaymentHash hash, PaymentPreimage? preimage, PaymentSecret? secret, LSPFeeLimits lsp_fee_limits);
- Bolt12Offer(PaymentHash? hash, PaymentPreimage? preimage, PaymentSecret? secret, OfferId offer_id);
- Bolt12Refund(PaymentHash? hash, PaymentPreimage? preimage, PaymentSecret? secret);
+ Bolt12Offer(PaymentHash? hash, PaymentPreimage? preimage, PaymentSecret? secret, OfferId offer_id, UntrustedString? payer_note, u64? quantity);
+ Bolt12Refund(PaymentHash? hash, PaymentPreimage? preimage, PaymentSecret? secret, UntrustedString? payer_note, u64? quantity);
  Spontaneous(PaymentHash hash, PaymentPreimage? preimage);
 };
 

src/error.rs

@@ -89,6 +89,8 @@ pub enum Error {
  InvalidNetwork,
  /// The given URI is invalid.
  InvalidUri,
+ /// The given quantity is invalid.
+ InvalidQuantity,
  /// A payment with the given hash has already been initiated.
  DuplicatePayment,
  /// The provided offer was denonminated in an unsupported currency.
@@ -153,6 +155,7 @@ impl fmt::Display for Error {
  Self::InvalidChannelId => write!(f, "The given channel ID is invalid."),
  Self::InvalidNetwork => write!(f, "The given network is invalid."),
  Self::InvalidUri => write!(f, "The given URI is invalid."),
+ Self::InvalidQuantity => write!(f, "The given quantity is invalid."),
  Self::DuplicatePayment => {
  write!(f, "A payment with the given hash has already been initiated.")
  },

src/event.rs

@@ -597,12 +597,16 @@ where
  payment_context,
  ..
  } => {
+ let payer_note = payment_context.invoice_request.payer_note_truncated;
  let offer_id = payment_context.offer_id;
+ let quantity = payment_context.invoice_request.quantity;
  let kind = PaymentKind::Bolt12Offer {
  hash: Some(payment_hash),
  preimage: payment_preimage,
  secret: Some(payment_secret),
  offer_id,
+ payer_note,
+ quantity,
  };
 
  let payment = PaymentDetails::new(

src/payment/bolt12.rs

@@ -12,12 +12,14 @@ use crate::types::ChannelManager;
 
 use lightning::ln::channelmanager::{PaymentId, Retry};
 use lightning::offers::invoice::Bolt12Invoice;
-use lightning::offers::offer::{Amount, Offer};
+use lightning::offers::offer::{Amount, Offer, Quantity};
 use lightning::offers::parse::Bolt12SemanticError;
 use lightning::offers::refund::Refund;
+use lightning::util::string::UntrustedString;
 
 use rand::RngCore;
 
+use std::num::NonZeroU64;
 use std::sync::{Arc, RwLock};
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
@@ -47,13 +49,15 @@ impl Bolt12Payment {
  ///
  /// If `payer_note` is `Some` it will be seen by the recipient and reflected back in the invoice
  /// response.
- pub fn send(&self, offer: &Offer, payer_note: Option<String>) -> Result<PaymentId, Error> {
+ ///
+ /// If `quantity` is `Some` it represents the number of items requested.
+ pub fn send(
+ &self, offer: &Offer, quantity: Option<u64>, payer_note: Option<String>,
+ ) -> Result<PaymentId, Error> {
  let rt_lock = self.runtime.read().unwrap();
  if rt_lock.is_none() {
  return Err(Error::NotRunning);
  }
-
- let quantity = None;
  let mut random_bytes = [0u8; 32];
  rand::thread_rng().fill_bytes(&mut random_bytes);
  let payment_id = PaymentId(random_bytes);
@@ -76,7 +80,7 @@ impl Bolt12Payment {
  &offer,
  quantity,
  None,
- payer_note,
+ payer_note.clone(),
  payment_id,
  retry_strategy,
  max_total_routing_fee_msat,
@@ -95,6 +99,8 @@ impl Bolt12Payment {
  preimage: None,
  secret: None,
  offer_id: offer.id(),
+ payer_note: payer_note.map(UntrustedString),
+ quantity,
  };
  let payment = PaymentDetails::new(
  payment_id,
@@ -117,6 +123,8 @@ impl Bolt12Payment {
  preimage: None,
  secret: None,
  offer_id: offer.id(),
+ payer_note: payer_note.map(UntrustedString),
+ quantity,
  };
  let payment = PaymentDetails::new(
  payment_id,
@@ -143,14 +151,13 @@ impl Bolt12Payment {
  /// If `payer_note` is `Some` it will be seen by the recipient and reflected back in the invoice
  /// response.
  pub fn send_using_amount(
- &self, offer: &Offer, payer_note: Option<String>, amount_msat: u64,
+ &self, offer: &Offer, amount_msat: u64, quantity: Option<u64>, payer_note: Option<String>,
  ) -> Result<PaymentId, Error> {
  let rt_lock = self.runtime.read().unwrap();
  if rt_lock.is_none() {
  return Err(Error::NotRunning);
  }
 
- let quantity = None;
  let mut random_bytes = [0u8; 32];
  rand::thread_rng().fill_bytes(&mut random_bytes);
  let payment_id = PaymentId(random_bytes);
@@ -177,7 +184,7 @@ impl Bolt12Payment {
  &offer,
  quantity,
  Some(amount_msat),
- payer_note,
+ payer_note.clone(),
  payment_id,
  retry_strategy,
  max_total_routing_fee_msat,
@@ -196,6 +203,8 @@ impl Bolt12Payment {
  preimage: None,
  secret: None,
  offer_id: offer.id(),
+ payer_note: payer_note.map(UntrustedString),
+ quantity,
  };
  let payment = PaymentDetails::new(
  payment_id,
@@ -218,6 +227,8 @@ impl Bolt12Payment {
  preimage: None,
  secret: None,
  offer_id: offer.id(),
+ payer_note: payer_note.map(UntrustedString),
+ quantity,
  };
  let payment = PaymentDetails::new(
  payment_id,
@@ -236,21 +247,32 @@ impl Bolt12Payment {
 
  /// 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) -> Result<Offer, Error> {
+ pub fn receive(
+ &self, amount_msat: u64, description: &str, quantity: Option<u64>,
+ ) -> Result<Offer, Error> {
  let offer_builder = self.channel_manager.create_offer_builder().map_err(|e| {
  log_error!(self.logger, "Failed to create offer builder: {:?}", e);
  Error::OfferCreationFailed
  })?;
- let offer = offer_builder
- .amount_msats(amount_msat)
- .description(description.to_string())
- .build()
- .map_err(|e| {
- log_error!(self.logger, "Failed to create offer: {:?}", e);
- Error::OfferCreationFailed
- })?;
 
- Ok(offer)
+ let mut offer =
+ offer_builder.amount_msats(amount_msat).description(description.to_string());
+
+ if let Some(qty) = quantity {
+ if qty == 0 {
+ log_error!(self.logger, "Failed to create offer: quantity can't be zero.");
+ return Err(Error::InvalidQuantity);
+ } else {
+ offer = offer.supported_quantity(Quantity::Bounded(NonZeroU64::new(qty).unwrap()))
+ };
+ };
+
+ let finalized_offer = offer.build().map_err(|e| {
+ log_error!(self.logger, "Failed to create offer: {:?}", e);
+ Error::OfferCreationFailed
+ })?;
+
+ Ok(finalized_offer)
  }
 
  /// Returns a payable offer that can be used to request and receive a payment for which the
@@ -281,8 +303,13 @@ impl Bolt12Payment {
  let payment_hash = invoice.payment_hash();
  let payment_id = PaymentId(payment_hash.0);
 
- let kind =
- PaymentKind::Bolt12Refund { hash: Some(payment_hash), preimage: None, secret: None };
+ let kind = PaymentKind::Bolt12Refund {
+ hash: Some(payment_hash),
+ preimage: None,
+ secret: None,
+ payer_note: refund.payer_note().map(|note| UntrustedString(note.0.to_string())),
+ quantity: refund.quantity(),
+ };
 
  let payment = PaymentDetails::new(
  payment_id,
@@ -298,7 +325,10 @@ impl Bolt12Payment {
  }
 
  /// Returns a [`Refund`] object that can be used to offer a refund payment of the amount given.
- pub fn initiate_refund(&self, amount_msat: u64, expiry_secs: u32) -> Result<Refund, Error> {
+ pub fn initiate_refund(
+ &self, amount_msat: u64, expiry_secs: u32, quantity: Option<u64>,
+ payer_note: Option<String>,
+ ) -> Result<Refund, Error> {
  let mut random_bytes = [0u8; 32];
  rand::thread_rng().fill_bytes(&mut random_bytes);
  let payment_id = PaymentId(random_bytes);
@@ -309,7 +339,7 @@ impl Bolt12Payment {
  let retry_strategy = Retry::Timeout(LDK_PAYMENT_RETRY_TIMEOUT);
  let max_total_routing_fee_msat = None;
 
- let refund = self
+ let mut refund_builder = self
  .channel_manager
  .create_refund_builder(
  amount_msat,
@@ -321,17 +351,30 @@ impl Bolt12Payment {
  .map_err(|e| {
  log_error!(self.logger, "Failed to create refund builder: {:?}", e);
  Error::RefundCreationFailed
- })?
- .build()
- .map_err(|e| {
- log_error!(self.logger, "Failed to create refund: {:?}", e);
- Error::RefundCreationFailed
  })?;
 
- log_info!(self.logger, "Offering refund of {}msat", amount_msat);
+ if let Some(qty) = quantity {
+ refund_builder = refund_builder.quantity(qty);
+ }
+
+ if let Some(note) = payer_note.clone() {
+ refund_builder = refund_builder.payer_note(note);
+ }
+
+ let refund = refund_builder.build().map_err(|e| {
+ log_error!(self.logger, "Failed to create refund: {:?}", e);
+ Error::RefundCreationFailed
+ })?;
 
- let kind = PaymentKind::Bolt12Refund { hash: None, preimage: None, secret: None };
+ log_info!(self.logger, "Offering refund of {}msat", amount_msat);
 
+ let kind = PaymentKind::Bolt12Refund {
+ hash: None,
+ preimage: None,
+ secret: None,
+ payer_note: payer_note.map(|note| UntrustedString(note)),
+ quantity,
+ };
  let payment = PaymentDetails::new(
  payment_id,
  kind,

src/payment/store.rs

@@ -11,6 +11,7 @@ use lightning::ln::msgs::DecodeError;
 use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
 use lightning::offers::offer::OfferId;
 use lightning::util::ser::{Readable, Writeable};
+use lightning::util::string::UntrustedString;
 use lightning::{
  _init_and_read_len_prefixed_tlv_fields, impl_writeable_tlv_based,
  impl_writeable_tlv_based_enum, write_tlv_fields,
@@ -212,6 +213,18 @@ pub enum PaymentKind {
  secret: Option<PaymentSecret>,
  /// The ID of the offer this payment is for.
  offer_id: OfferId,
+ /// The payer note for the payment.
+ ///
+ /// Truncated to [`PAYER_NOTE_LIMIT`] characters.
+ ///
+ /// This will always be `None` for payments serialized with version `v0.3.0`.
+ ///
+ /// [`PAYER_NOTE_LIMIT`]: lightning::offers::invoice_request::PAYER_NOTE_LIMIT
+ payer_note: Option<UntrustedString>,
+ /// The quantity of an item requested in the offer.
+ ///
+ /// This will always be `None` for payments serialized with version `v0.3.0`.
+ quantity: Option<u64>,
  },
  /// A [BOLT 12] 'refund' payment, i.e., a payment for a [`Refund`].
  ///
@@ -224,6 +237,14 @@ pub enum PaymentKind {
  preimage: Option<PaymentPreimage>,
  /// The secret used by the payment.
  secret: Option<PaymentSecret>,
+ /// The payer note for the refund payment.
+ ///
+ /// This will always be `None` for payments serialized with version `v0.3.0`.
+ payer_note: Option<UntrustedString>,
+ /// The quantity of an item that the refund is for.
+ ///
+ /// This will always be `None` for payments serialized with version `v0.3.0`.
+ quantity: Option<u64>,
  },
  /// A spontaneous ("keysend") payment.
  Spontaneous {
@@ -249,7 +270,9 @@ impl_writeable_tlv_based_enum!(PaymentKind,
  },
  (6, Bolt12Offer) => {
  (0, hash, option),
+ (1, payer_note, option),
  (2, preimage, option),
+ (3, quantity, option),
  (4, secret, option),
  (6, offer_id, required),
  },
@@ -259,7 +282,9 @@ impl_writeable_tlv_based_enum!(PaymentKind,
  },
  (10, Bolt12Refund) => {
  (0, hash, option),
+ (1, payer_note, option),
  (2, preimage, option),
+ (3, quantity, option),
  (4, secret, option),
  };
 );

src/payment/unified_qr.rs

@@ -92,7 +92,7 @@ impl UnifiedQrPayment {
 
  let amount_msats = amount_sats * 1_000;
 
- let bolt12_offer = match self.bolt12_payment.receive(amount_msats, description) {
+ let bolt12_offer = match self.bolt12_payment.receive(amount_msats, description, None) {
  Ok(offer) => Some(offer),
  Err(e) => {
  log_error!(self.logger, "Failed to create offer: {}", e);
@@ -136,7 +136,7 @@ impl UnifiedQrPayment {
  uri.clone().require_network(self.config.network).map_err(|_| Error::InvalidNetwork)?;
 
  if let Some(offer) = uri_network_checked.extras.bolt12_offer {
- match self.bolt12_payment.send(&offer, None) {
+ 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),
  }